fix(viewer): satellite table UX — JS syntax, entity selection, button positioning

- Fix JS syntax error in renderSatTable: \' in Python f-string produced ''
  (empty string) instead of \' (escaped quote), killing the entire <script>
  block — root cause of black page with no globe
- Fix flyToSat entity ID: search correct dataSource, try both satellite-N
  (animated) and snapshot-N (snapshot mode) CZML ID formats
- Fix table row click: use _sat_idx from row data instead of forEach index
  so sorting doesn't break entity lookup
- Move table toggle button from bottom:8px to bottom:36px (clear timeline)
- Hide table button when table is open; add close button in table header
- Set viewer.selectedEntity on row click to show Cesium InfoBox with
  orbital parameters (altitude, inclination, velocity, beta angle, etc.)
- Add _sat_idx field to get_satellite_table API response
- 8 new tests (307 total), 0 regressions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: planet.jeroen

packages/core/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "humeris-core"
-version = "1.27.0"
+version = "1.28.1"
 description = "Astrodynamics library for satellite constellation design — MIT open core"
 requires-python = ">=3.11"
 license = "MIT"

packages/pro/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "humeris-pro"
-version = "1.27.0"
+version = "1.28.1"
 description = "Humeris professional modules — advanced astrodynamics analysis"
 requires-python = ">=3.11"
 license = {text = "Commercial — see COMMERCIAL-LICENSE.md"}

packages/pro/src/humeris/adapters/cesium_viewer.py

@@ -558,7 +558,7 @@ def generate_interactive_html(
         #satTable .sort-asc::after {{ content: " \\25B2"; font-size: 8px; }}
         #satTable .sort-desc::after {{ content: " \\25BC"; font-size: 8px; }}
         #satTableToggle {{
-            position: fixed; bottom: 8px; right: 8px; z-index: 101;
+            position: fixed; bottom: 36px; right: 8px; z-index: 101;
             background: rgba(30,40,60,0.9); color: #fff;
             border: 1px solid rgba(80,160,255,0.3); border-radius: 4px;
             padding: 4px 10px; cursor: pointer; font-size: 11px;
@@ -907,8 +907,11 @@ def generate_interactive_html(
 
         function toggleSatTable() {{
             var tbl = document.getElementById("satTable");
+            var btn = document.getElementById("satTableToggle");
             tbl.classList.toggle("visible");
-            if (tbl.classList.contains("visible") && !satTableData) {{
+            var isVisible = tbl.classList.contains("visible");
+            btn.style.display = isVisible ? "none" : "";
+            if (isVisible && !satTableData) {{
                 // Load table for first constellation layer
                 apiGet("/api/state").then(function(state) {{
                     var constLayer = state.layers.find(function(l) {{ return l.category === "Constellation"; }});
@@ -941,15 +944,19 @@ def generate_interactive_html(
                     return asc ? va - vb : vb - va;
                 }});
             }}
-            var html = '<table><thead><tr>';
+            var html = '<div style="display:flex;justify-content:space-between;align-items:center;padding:4px 8px;background:rgba(30,35,50,0.98);border-bottom:1px solid rgba(255,255,255,0.15)">';
+            html += '<span style="font-weight:bold;font-size:11px;color:rgba(255,255,255,0.7)">Satellite Table (' + rows.length + ')</span>';
+            html += '<button onclick="toggleSatTable()" style="background:none;border:none;color:rgba(255,255,255,0.6);cursor:pointer;font-size:16px;padding:0 4px" title="Close table">&times;</button>';
+            html += '</div>';
+            html += '<table><thead><tr>';
             cols.forEach(function(c) {{
                 var cls = "";
                 if (satTableSort.col === c) cls = satTableSort.asc ? "sort-asc" : "sort-desc";
-                html += '<th class="' + cls + '" onclick="sortSatTable(\'' + escapeHtml(c) + '\')">' + escapeHtml(c.replace(/_/g, " ")) + '</th>';
+                html += '<th class="' + cls + '" onclick="sortSatTable(\\'' + escapeHtml(c) + '\\')">' + escapeHtml(c.replace(/_/g, " ")) + '</th>';
             }});
             html += '</tr></thead><tbody>';
-            rows.forEach(function(row, idx) {{
-                html += '<tr onclick="flyToSat(' + idx + ')">';
+            rows.forEach(function(row) {{
+                html += '<tr onclick="flyToSat(' + row._sat_idx + ')">';
                 cols.forEach(function(c) {{
                     html += '<td>' + escapeHtml(row[c]) + '</td>';
                 }});
@@ -971,14 +978,14 @@ def generate_interactive_html(
 
         function flyToSat(idx) {{
             if (!satTableLayerId) return;
-            var entityId = satTableLayerId + "-" + idx;
-            var ds = viewer.dataSources;
-            for (var i = 0; i < ds.length; i++) {{
-                var entity = ds.get(i).entities.getById(entityId);
-                if (entity) {{
-                    viewer.flyTo(entity, {{duration: 1.5}});
-                    return;
-                }}
+            var ds = layerSources[satTableLayerId];
+            if (!ds) return;
+            // CZML uses satellite-N (animated) or snapshot-N (snapshot mode)
+            var entity = ds.entities.getById("satellite-" + idx)
+                      || ds.entities.getById("snapshot-" + idx);
+            if (entity) {{
+                viewer.selectedEntity = entity;
+                viewer.flyTo(entity, {{duration: 1.5}});
             }}
         }}
 

packages/pro/src/humeris/adapters/viewer_server.py

@@ -1242,6 +1242,7 @@ def get_satellite_table(self, layer_id: str) -> dict[str, Any]:
                 except Exception:
                     eclipse_pct = 0.0
                 rows.append({
+                    "_sat_idx": idx,
                     "name": name,
                     "plane": plane,
                     "altitude_km": round(alt_km, 2),

tests/test_cesium_viewer.py

@@ -979,6 +979,128 @@ def test_remove_data_source_with_destroy(self):
             "dataSources.remove should pass true for destroy"
 
 
+class TestViewerTableUX:
+    """VIEWER-TABLE-UX: table button position and satellite detail selection."""
+
+    def _html(self):
+        from humeris.adapters.cesium_viewer import generate_interactive_html
+        return generate_interactive_html()
+
+    # UXC1: Table toggle button must clear the Cesium timeline
+    def test_table_toggle_button_clears_timeline(self):
+        """#satTableToggle bottom >= 36px to avoid overlapping the timeline."""
+        html = self._html()
+        match = re.search(r'#satTableToggle\s*\{([^}]+)\}', html)
+        assert match is not None, "satTableToggle CSS rule not found"
+        css = match.group(1)
+        bottom_match = re.search(r'bottom:\s*(\d+)px', css)
+        assert bottom_match is not None, "bottom property not found in satTableToggle"
+        bottom_px = int(bottom_match.group(1))
+        assert bottom_px >= 36, (
+            f"satTableToggle bottom is {bottom_px}px, must be >= 36px "
+            "to clear the Cesium timeline widget"
+        )
+
+    # UXC2: flyToSat must set viewer.selectedEntity for InfoBox display
+    def test_fly_to_sat_sets_selected_entity(self):
+        """flyToSat must set viewer.selectedEntity so Cesium InfoBox shows details."""
+        html = self._html()
+        # Find the flyToSat function body
+        match = re.search(
+            r'function flyToSat\([^)]*\)\s*\{(.*?)\n\s{8}\}',
+            html, re.DOTALL,
+        )
+        assert match is not None, "flyToSat function not found"
+        body = match.group(1)
+        assert "viewer.selectedEntity" in body, (
+            "flyToSat must set viewer.selectedEntity to activate "
+            "Cesium's InfoBox with satellite details"
+        )
+
+    # UXC3: flyToSat must use CZML entity ID formats (satellite-N and snapshot-N)
+    def test_fly_to_sat_uses_czml_entity_ids(self):
+        """flyToSat must try both satellite-{idx} and snapshot-{idx} CZML ID formats."""
+        html = self._html()
+        match = re.search(
+            r'function flyToSat\([^)]*\)\s*\{(.*?)\n\s{8}\}',
+            html, re.DOTALL,
+        )
+        assert match is not None, "flyToSat function not found"
+        body = match.group(1)
+        assert '"satellite-"' in body, (
+            "flyToSat must try 'satellite-' prefix for animated mode CZML entities"
+        )
+        assert '"snapshot-"' in body, (
+            "flyToSat must try 'snapshot-' prefix for snapshot mode CZML entities"
+        )
+
+    # UXC4: Table rows pass original sat index, not sorted position
+    def test_table_rows_use_sat_idx_not_position(self):
+        """Table row onclick must use row._sat_idx, not the forEach index."""
+        html = self._html()
+        match = re.search(
+            r'function renderSatTable\(\)\s*\{(.*?)\n\s{8}\}',
+            html, re.DOTALL,
+        )
+        assert match is not None, "renderSatTable function not found"
+        body = match.group(1)
+        assert "_sat_idx" in body, (
+            "renderSatTable must use row._sat_idx for flyToSat, "
+            "not the forEach index which changes with sorting"
+        )
+
+    # UXC5: Table toggle button hides when table is visible
+    def test_table_toggle_hides_when_table_open(self):
+        """toggleSatTable must hide the button when table becomes visible."""
+        html = self._html()
+        match = re.search(
+            r'function toggleSatTable\(\)\s*\{(.*?)\n\s{8}\}',
+            html, re.DOTALL,
+        )
+        assert match is not None, "toggleSatTable function not found"
+        body = match.group(1)
+        assert "satTableToggle" in body, (
+            "toggleSatTable must reference the toggle button to hide/show it"
+        )
+        assert 'display' in body or 'none' in body or 'style' in body, (
+            "toggleSatTable must change button display when table state changes"
+        )
+
+    # UXC6: Table has a close button
+    def test_table_has_close_button(self):
+        """The satellite table must include a close button in its rendered HTML."""
+        html = self._html()
+        match = re.search(
+            r'function renderSatTable\(\)\s*\{(.*?)\n\s{8}\}',
+            html, re.DOTALL,
+        )
+        assert match is not None, "renderSatTable function not found"
+        body = match.group(1)
+        assert "toggleSatTable" in body or "closeSatTable" in body, (
+            "renderSatTable must include a close button that hides the table"
+        )
+
+    # UXC7: Generated JS must have no syntax errors
+    def test_generated_js_syntax_valid(self):
+        """Generated JavaScript must pass syntax validation."""
+        import subprocess
+        html = self._html()
+        match = re.search(r'<script>(.*?)</script>', html, re.DOTALL)
+        assert match is not None, "No script block found"
+        js = match.group(1)
+        result = subprocess.run(
+            ["node", "--check"],
+            input=js,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        assert result.returncode == 0, (
+            f"JavaScript syntax error in generated viewer HTML:\n"
+            f"{result.stderr.strip()}"
+        )
+
+
 class TestCesiumViewerPurity:
     """Adapter purity: only stdlib + internal imports allowed."""
 

tests/test_viewer_server.py

@@ -2964,6 +2964,24 @@ def test_table_plane_assignment(self):
         # First 2 sats in plane 0, next 2 in plane 1
         assert planes == [0, 0, 1, 1]
 
+    def test_table_rows_include_sat_idx(self):
+        """Each row must include _sat_idx for stable entity lookup after sorting."""
+        from humeris.adapters.viewer_server import LayerManager
+        mgr = LayerManager(epoch=EPOCH)
+        states = _make_states(n_planes=2, n_sats=3)
+        lid = mgr.add_layer(
+            name="Constellation:Walker",
+            category="Constellation",
+            layer_type="walker",
+            states=states,
+            params={"altitude_km": 550, "inclination_deg": 53, "num_planes": 2, "sats_per_plane": 3},
+            sat_names=[f"Sat-{i}" for i in range(6)],
+        )
+        table = mgr.get_satellite_table(lid)
+        for i, row in enumerate(table["rows"]):
+            assert "_sat_idx" in row, f"Row {i} missing _sat_idx field"
+            assert row["_sat_idx"] == i, f"Row {i} _sat_idx={row['_sat_idx']}, expected {i}"
+
 
 # ---------------------------------------------------------------------------
 # APP-04: Named scenarios with description