bobframes 0.2.7__tar.gz → 0.2.8__tar.gz

{bobframes-0.2.7 → bobframes-0.2.8}/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.8] - 2026-06-24
+
+A guided local-web control panel (`bobframes ui`) for QA and product teammates who are not comfortable
+in a terminal. Zero new runtime dependency (stdlib `http.server` only) and no report-output change --
+the panel drives the existing verbs and emits no report HTML, so the rendered HTML and parquet digests
+stay byte-identical on the same captures. No schema change (still schema 3). `_version` 0.2.7 -> 0.2.8.
+
+### Added
+- `bobframes ui`: a zero-dependency local-web control panel that drives the whole pipeline from a
+  browser (ADR-47). It detects the RenderDoc tools and discovers capture drops, runs ingest /
+  re-generate / package / A-B as subprocesses with live per-capture progress streamed over Server-Sent
+  Events, opens or serves the rendered report, applies accent theming to a re-render, and can scaffold a
+  convention-correct capture folder. Server-rendered HTML + vanilla JS -- no framework, no build step,
+  no client router (the hard governance line in ADR-47). Binds `127.0.0.1` only and gates every
+  `/api/*` call with a per-session token. Install with `pipx install bobframes`, then run `bobframes ui`.
+
+### Changed
+- The static preview server body moved from `cli._cmd_serve` into a reusable `serve.make_server` /
+  `serve.serve_forever` so the panel's background serve and the `bobframes serve` verb share it; the
+  `serve` verb's behavior is unchanged.
+- The control panel's JS and CSS are now served as static files (`bobframes/ui/assets/panel.{js,css}`,
+  at `GET /panel.js` / `GET /panel.css`) instead of being embedded in a Python string -- so the client
+  is a real file that `node --check`/lint can validate (no build step; still no framework or router).
+
+### Tests / CI
+- Added an automated guard that the panel JS parses and runs: a `node --check` gate (a pytest test +
+  an unconditional CI step) and an opt-in `browser`-marked headless smoke that drives the live panel in
+  Chrome and asserts it populates -- closing the gap that let a broken `<script>` ship undetected.
+
 ## [0.2.7] - 2026-06-24
 
 An aggregation-consistency pass plus four report/sharing correctness fixes. Every KPI now names its
@@ -160,7 +189,8 @@ First standalone release. v1 is Windows-only (the replay stage drives `qrenderdo
   `python -m _analysis.*` entry points no longer work; switch to the `bobframes` commands (see the
   migration table in the README). This is a hard rename with no compatibility shim.
 
-[Unreleased]: https://github.com/altpsyche/bobframes/compare/v0.2.7...HEAD
+[Unreleased]: https://github.com/altpsyche/bobframes/compare/v0.2.8...HEAD
+[0.2.8]: https://github.com/altpsyche/bobframes/compare/v0.2.7...v0.2.8
 [0.2.7]: https://github.com/altpsyche/bobframes/compare/v0.2.6...v0.2.7
 [0.2.6]: https://github.com/altpsyche/bobframes/compare/v0.2.0...v0.2.6
 [0.2.0]: https://github.com/altpsyche/bobframes/compare/v0.1.0...v0.2.0

{bobframes-0.2.7 → bobframes-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bobframes
-Version: 0.2.7
+Version: 0.2.8
 Summary: RenderDoc capture pipeline: ingest, analyze, render.
 Project-URL: Homepage, https://github.com/altpsyche/bobframes
 Project-URL: Issues, https://github.com/altpsyche/bobframes/issues
@@ -55,6 +55,21 @@ bobframes check
 `bobframes check` prints the resolved paths for `renderdoccmd` and `qrenderdoc` and exits non-zero if
 either is missing, so you can confirm the toolchain before a long ingest.
 
+## Guided mode (recommended for QA / product)
+
+Not comfortable in a terminal? `bobframes ui` opens a local-web control panel in your browser that
+drives the whole pipeline point-and-click: detect the RenderDoc tools, pick a capture folder, ingest
+with live per-capture progress, then open / serve / package the report or compare two runs.
+
+```
+pipx install bobframes
+bobframes ui             # opens http://127.0.0.1:8765 in your browser
+```
+
+The panel binds `127.0.0.1` only and carries a one-time session token in the opened URL, so only your
+own browser can drive it. It is stdlib-only -- one `pipx install` gives every feature, no extra setup --
+and it emits no report files of its own; it just runs the same verbs as the CLI.
+
 ## Quickstart
 
 ```
@@ -78,6 +93,7 @@ time to rebuild the HTML from existing Parquet without re-replaying captures.
 | `lint <file>...` | Check HTML or markdown against the banlist. |
 | `check` | Print resolved tool paths; non-zero when a tool is missing. |
 | `serve [root] [--port 8000] [--bind 127.0.0.1]` | Static preview via the stdlib HTTP server. |
+| `ui [root] [--port 8765] [--bind 127.0.0.1] [--no-open]` | Guided local-web control panel (ADR-47): ingest / render / package / A-B / open / serve / scaffold from a browser, with live progress. Localhost-bound + per-session token; emits no report output of its own. |
 | `package [root] [--inline] [--light] [--redact] [--redact-paths {strip,fail}] [--out PATH] [--run KEY] [--no-summary-file] [--stage]` | Bundle a rendered tree into a shareable `<project>-<rundate>-report.zip` + a standalone `<project>-<rundate>-summary.html`, both written OUTSIDE `<root>` (non-mutating). `--redact` scrubs device/host provenance + absolute paths for external sharing. |
 | `preview [root] [--accent OKLCH] [--accent-data OKLCH]` | Render the chrome gallery to `_reports/_chrome_preview.html`; no capture data needed. `--accent` previews a theme override before you commit it. |
 | `export-tokens [--format toml\|json\|css] [--theme-template]` | Print the design tokens to stdout in the chosen format. `--theme-template` emits a paste-ready `[theme]` block for `.bobframes.toml`. |

{bobframes-0.2.7 → bobframes-0.2.8}/README.md

@@ -24,6 +24,21 @@ bobframes check
 `bobframes check` prints the resolved paths for `renderdoccmd` and `qrenderdoc` and exits non-zero if
 either is missing, so you can confirm the toolchain before a long ingest.
 
+## Guided mode (recommended for QA / product)
+
+Not comfortable in a terminal? `bobframes ui` opens a local-web control panel in your browser that
+drives the whole pipeline point-and-click: detect the RenderDoc tools, pick a capture folder, ingest
+with live per-capture progress, then open / serve / package the report or compare two runs.
+
+```
+pipx install bobframes
+bobframes ui             # opens http://127.0.0.1:8765 in your browser
+```
+
+The panel binds `127.0.0.1` only and carries a one-time session token in the opened URL, so only your
+own browser can drive it. It is stdlib-only -- one `pipx install` gives every feature, no extra setup --
+and it emits no report files of its own; it just runs the same verbs as the CLI.
+
 ## Quickstart
 
 ```
@@ -47,6 +62,7 @@ time to rebuild the HTML from existing Parquet without re-replaying captures.
 | `lint <file>...` | Check HTML or markdown against the banlist. |
 | `check` | Print resolved tool paths; non-zero when a tool is missing. |
 | `serve [root] [--port 8000] [--bind 127.0.0.1]` | Static preview via the stdlib HTTP server. |
+| `ui [root] [--port 8765] [--bind 127.0.0.1] [--no-open]` | Guided local-web control panel (ADR-47): ingest / render / package / A-B / open / serve / scaffold from a browser, with live progress. Localhost-bound + per-session token; emits no report output of its own. |
 | `package [root] [--inline] [--light] [--redact] [--redact-paths {strip,fail}] [--out PATH] [--run KEY] [--no-summary-file] [--stage]` | Bundle a rendered tree into a shareable `<project>-<rundate>-report.zip` + a standalone `<project>-<rundate>-summary.html`, both written OUTSIDE `<root>` (non-mutating). `--redact` scrubs device/host provenance + absolute paths for external sharing. |
 | `preview [root] [--accent OKLCH] [--accent-data OKLCH]` | Render the chrome gallery to `_reports/_chrome_preview.html`; no capture data needed. `--accent` previews a theme override before you commit it. |
 | `export-tokens [--format toml\|json\|css] [--theme-template]` | Print the design tokens to stdout in the chosen format. `--theme-template` emits a paste-ready `[theme]` block for `.bobframes.toml`. |

bobframes-0.2.8/bobframes/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.8"

{bobframes-0.2.7 → bobframes-0.2.8}/bobframes/cli.py

@@ -251,20 +251,19 @@ def _cmd_check(args: argparse.Namespace) -> int:
 
 
 def _cmd_serve(args: argparse.Namespace) -> int:
-    import functools
-    import http.server
-    import socketserver
+    # The static preview server body lives in serve.serve_forever so the `ui` panel can reuse the
+    # same builder (serve.make_server) for its background click-to-serve (v028_3).
+    from . import serve
+    return serve.serve_forever(os.path.abspath(args.root), bind=args.bind, port=args.port)
 
-    root = os.path.abspath(args.root)
-    handler = functools.partial(http.server.SimpleHTTPRequestHandler, directory=root)
-    log = logging.getLogger('bobframes')
-    try:
-        with socketserver.TCPServer((args.bind, args.port), handler) as httpd:
-            log.info(f'serving {root} at http://{args.bind}:{args.port} (Ctrl+C to stop)')
-            httpd.serve_forever()
-    except KeyboardInterrupt:
-        return 4
-    return 0
+
+def _cmd_ui(args: argparse.Namespace) -> int:
+    # ADR-47: a zero-dependency local-web control panel that DRIVES the verbs for non-terminal users.
+    # A frontend SURFACE above the verb taxonomy -- it emits no report HTML (golden gate untouched) and
+    # pulls no dep into core. Lazy-imported so a core install never loads the ui package.
+    from .ui import server
+    return server.serve(os.path.abspath(args.root), bind=args.bind, port=args.port,
+                        open_browser=not args.no_open)
 
 
 def _cmd_package(args: argparse.Namespace) -> int:
@@ -380,6 +379,16 @@ def _build_parser() -> argparse.ArgumentParser:
     sp.add_argument('--bind', default='127.0.0.1')
     sp.set_defaults(func=_cmd_serve)
 
+    sp = sub.add_parser('ui', parents=[common],
+                        help='guided local-web control panel (ingest/generate/package in a browser)')
+    sp.add_argument('root', nargs='?', default='.')
+    sp.add_argument('--port', type=int, default=8765)
+    sp.add_argument('--bind', default='127.0.0.1',
+                    help='bind address; localhost only by design (ADR-47)')
+    sp.add_argument('--no-open', action='store_true',
+                    help="don't auto-open the browser")
+    sp.set_defaults(func=_cmd_ui)
+
     sp = sub.add_parser('package', parents=[common],
                         help='bundle a rendered tree into a shareable zip + standalone summary')
     sp.add_argument('root', nargs='?', default='.')

bobframes-0.2.8/bobframes/serve.py

@@ -0,0 +1,36 @@
+"""Static preview file server (extracted from ``cli._cmd_serve`` for reuse by ``bobframes ui``).
+
+A stdlib ``http.server`` serving ``<root>`` read-only over localhost. ``make_server`` builds (does not
+start) the server; ``serve_forever`` builds it and blocks until Ctrl+C -- the body of the ``serve`` verb.
+The ``ui`` panel reuses ``make_server`` to run the static server in a background daemon thread alongside
+the control panel (so a click-to-serve returns a URL instead of blocking the request handler).
+
+No new dependency; behavior is identical to the prior inlined ``_cmd_serve`` (same ``socketserver``
+TCPServer + ``SimpleHTTPRequestHandler(directory=root)`` + ``[HH:MM:SS]`` log line + exit codes).
+"""
+from __future__ import annotations
+
+import functools
+import http.server
+import logging
+import socketserver
+
+log = logging.getLogger('bobframes')
+
+
+def make_server(root: str, *, bind: str = '127.0.0.1', port: int = 8000) -> socketserver.TCPServer:
+    """Build (do not start) a static file server over ``<root>``. ``port=0`` binds an ephemeral port
+    (read it back from ``server.server_address[1]``); used by the panel's background serve."""
+    handler = functools.partial(http.server.SimpleHTTPRequestHandler, directory=root)
+    return socketserver.TCPServer((bind, port), handler)
+
+
+def serve_forever(root: str, *, bind: str = '127.0.0.1', port: int = 8000) -> int:
+    """Serve ``<root>`` and block until Ctrl+C. Returns a CLI exit code (0 clean, 4 interrupted)."""
+    try:
+        with make_server(root, bind=bind, port=port) as httpd:
+            log.info(f'serving {root} at http://{bind}:{port} (Ctrl+C to stop)')
+            httpd.serve_forever()
+    except KeyboardInterrupt:
+        return 4
+    return 0

bobframes-0.2.8/bobframes/tests/_ui_util.py

@@ -0,0 +1,57 @@
+"""Shared helpers for the `bobframes ui` panel tests (v028_1).
+
+Starts the stdlib panel server on an ephemeral port in a daemon thread and hits it with `urllib`,
+so the tests exercise the real HTTP surface (token gating, JSON shape) without a browser or GPU.
+"""
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import threading
+import urllib.request
+
+from ..ui import server as _server
+
+
+def make_capture_root(tmp_path) -> str:
+    """A tmp project root with the `<Area>/<YYYY-MM-DD[_label]>/*.rdc` convention (mirrors
+    test_discovery): Town has the newest dated drop with 3 captures; Bay a single undated-label drop."""
+    root = str(tmp_path / 'proj')
+    layout = (('Town', '2026-05-27_old', ('1',)),
+              ('Town', '2026-05-28_new', ('1', '2', '10')),
+              ('Bay', '2026-01-01', ('cap',)))
+    for area, key, caps in layout:
+        for cap in caps:
+            p = os.path.join(root, area, key, f'{cap}.rdc')
+            os.makedirs(os.path.dirname(p), exist_ok=True)
+            open(p, 'w', encoding='utf-8').close()
+    return root
+
+
+@contextlib.contextmanager
+def running(root: str):
+    """Run the panel server on an ephemeral port; yield (httpd, port)."""
+    httpd = _server.build_server(root, port=0)
+    t = threading.Thread(target=httpd.serve_forever, daemon=True)
+    t.start()
+    try:
+        yield httpd, httpd.server_address[1]
+    finally:
+        _server._shutdown_aux(httpd)          # stop the background static serve if /api/serve started one
+        httpd.shutdown()
+        t.join(timeout=5)
+
+
+def get(port: int, path: str, headers: dict | None = None):
+    """GET http://127.0.0.1:<port><path>; returns the response (raises HTTPError on >=400)."""
+    req = urllib.request.Request(f'http://127.0.0.1:{port}{path}', headers=headers or {})
+    return urllib.request.urlopen(req, timeout=5)
+
+
+def post(port: int, path: str, token: str, body: dict):
+    """POST JSON with the session token; returns the response (raises HTTPError on >=400)."""
+    req = urllib.request.Request(
+        f'http://127.0.0.1:{port}{path}', data=json.dumps(body).encode('utf-8'), method='POST',
+        headers={'Content-Type': 'application/json', 'X-Bobframes-Token': token})
+    return urllib.request.urlopen(req, timeout=5)

bobframes-0.2.8/bobframes/tests/test_ui_ab_theme.py

@@ -0,0 +1,162 @@
+"""v028_4: A/B comparison + accent theming + the opt-in capture-folder scaffold.
+
+A/B and the accent re-render are streamed subprocess jobs mocked at the spawn seam (no GPU/RenderDoc --
+ADR-6): `jobs.spawn` (render reuses `python -m bobframes.run`) and `jobs.spawn_cli` (`bobframes ab`)
+are monkeypatched with a fake process. The run list backing the picker is asserted via `/api/state`
+(`discovery.discover_drops` monkeypatched). Scaffold creates a real folder under a tmp root.
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+
+import pytest
+
+from ..ui import jobs as _jobs
+from ._ui_util import get, post, running
+
+
+class _FakeProc:
+    def __init__(self, lines, rc=0):
+        self.stdout = iter(lines)
+        self.returncode = None
+        self._rc = rc
+
+    def wait(self):
+        self.returncode = self._rc
+        return self._rc
+
+    def poll(self):
+        return self.returncode
+
+    def terminate(self):
+        self.returncode = -15
+
+
+class _FakeRun:
+    def __init__(self, key, label, date, n):
+        self.key, self.label, self.date, self.n_captures = key, label, date, n
+
+
+# --- argv builders ------------------------------------------------------------------------------
+
+def test_build_render_argv_threads_accent():
+    argv = _jobs.build_render_argv('/proj', accent='oklch(0.5 0.2 250)', accent_data='red')
+    assert '--render-only' in argv
+    assert argv[argv.index('--accent') + 1] == 'oklch(0.5 0.2 250)'
+    assert argv[argv.index('--accent-data') + 1] == 'red'
+    plain = _jobs.build_render_argv('/proj')
+    assert '--accent' not in plain and '--accent-data' not in plain and '--render-only' in plain
+
+
+def test_build_ab_argv_mirrors_ab_verb():
+    argv = _jobs.build_ab_argv('/proj', baseline_label='r1', compare_label='r2',
+                               baseline_date='2026-05-27', compare_date='2026-05-28')
+    assert argv[0] == 'ab'
+    assert argv[argv.index('--baseline-label') + 1] == 'r1'
+    assert argv[argv.index('--compare-label') + 1] == 'r2'
+    assert argv[argv.index('--baseline-date') + 1] == '2026-05-27'
+    assert argv[argv.index('--compare-date') + 1] == '2026-05-28'
+    bare = _jobs.build_ab_argv('/proj', baseline_label='r1', compare_label='r2')
+    assert '--baseline-date' not in bare and '--compare-date' not in bare
+
+
+# --- /api/render accent -------------------------------------------------------------------------
+
+def test_render_threads_accent_into_spawn(tmp_path, monkeypatch):
+    seen = {}
+
+    def fake_spawn(argv):
+        seen['argv'] = argv
+        return _FakeProc(["[10:00:00] render-only done"])
+    monkeypatch.setattr(_jobs, 'spawn', fake_spawn)
+    with running(str(tmp_path)) as (httpd, port):
+        jid = json.loads(post(port, '/api/render', httpd.bobframes_token,
+                              {'accent': 'oklch(0.6 0.2 30)', 'accent_data': ''}).read())['job']
+        stream = get(port, f'/api/stream/{jid}?t={httpd.bobframes_token}').read().decode('utf-8')
+    assert '--render-only' in seen['argv']
+    assert seen['argv'][seen['argv'].index('--accent') + 1] == 'oklch(0.6 0.2 30)'
+    assert '--accent-data' not in seen['argv']            # blank field -> flag omitted
+    assert '"rc": 0' in stream
+
+
+# --- /api/ab ------------------------------------------------------------------------------------
+
+def test_ab_spawns_cli_and_streams(tmp_path, monkeypatch):
+    seen = {}
+
+    def fake_spawn_cli(argv):
+        seen['argv'] = argv
+        return _FakeProc(["[10:00:00] a/b: 2026-05-27_r1 (2 captures) vs 2026-05-28_r2 (3 captures)"])
+    monkeypatch.setattr(_jobs, 'spawn_cli', fake_spawn_cli)
+    with running(str(tmp_path)) as (httpd, port):
+        body = {'baseline_label': 'r1', 'baseline_date': '2026-05-27',
+                'compare_label': 'r2', 'compare_date': '2026-05-28'}
+        jid = json.loads(post(port, '/api/ab', httpd.bobframes_token, body).read())['job']
+        stream = get(port, f'/api/stream/{jid}?t={httpd.bobframes_token}').read().decode('utf-8')
+    assert seen['argv'][0] == 'ab'
+    assert seen['argv'][seen['argv'].index('--baseline-label') + 1] == 'r1'
+    assert seen['argv'][seen['argv'].index('--compare-label') + 1] == 'r2'
+    assert 'a/b:' in stream and '"rc": 0' in stream
+
+
+def test_ab_requires_both_runs(tmp_path):
+    with running(str(tmp_path)) as (httpd, port):
+        with pytest.raises(urllib.error.HTTPError) as e:
+            post(port, '/api/ab', httpd.bobframes_token, {'baseline_label': 'r1'})   # no compare
+        assert e.value.code == 400
+
+
+# --- /api/state runs (the picker source) --------------------------------------------------------
+
+def test_state_lists_rendered_runs(tmp_path, monkeypatch):
+    from ..reports import discovery as rdisc
+    runs = [_FakeRun('2026-05-27_r1', 'r1', '2026-05-27', 2),
+            _FakeRun('2026-05-28_r2', 'r2', '2026-05-28', 3)]
+    monkeypatch.setattr(rdisc, 'discover_drops', lambda root: runs)
+    with running(str(tmp_path)) as (httpd, port):
+        s = json.load(get(port, '/api/state?t=' + httpd.bobframes_token))
+    assert [r['key'] for r in s['runs']] == ['2026-05-27_r1', '2026-05-28_r2']
+    assert s['runs'][1]['n_captures'] == 3
+
+
+def test_state_runs_empty_without_catalog(tmp_path):
+    with running(str(tmp_path)) as (httpd, port):
+        s = json.load(get(port, '/api/state?t=' + httpd.bobframes_token))
+    assert s['runs'] == []                                 # no catalog yet -> no runs
+
+
+# --- /api/scaffold ------------------------------------------------------------------------------
+
+def test_scaffold_creates_convention_folder(tmp_path):
+    root = str(tmp_path / 'proj')
+    os.makedirs(root)
+    with running(root) as (httpd, port):
+        r = json.loads(post(port, '/api/scaffold', httpd.bobframes_token,
+                            {'area': 'Town', 'date': '2026-06-24', 'label': 'r110600'}).read())
+        assert r['created'] is True
+        assert os.path.basename(r['path']) == '2026-06-24_r110600'
+        assert os.path.isdir(os.path.join(root, 'Town', '2026-06-24_r110600'))
+        # idempotent: a second call reports already-exists.
+        again = json.loads(post(port, '/api/scaffold', httpd.bobframes_token,
+                                {'area': 'Town', 'date': '2026-06-24', 'label': 'r110600'}).read())
+        assert again['created'] is False
+
+
+def test_scaffold_rejects_bad_date_and_traversal(tmp_path):
+    with running(str(tmp_path)) as (httpd, port):
+        with pytest.raises(urllib.error.HTTPError) as bad_date:
+            post(port, '/api/scaffold', httpd.bobframes_token, {'area': 'Town', 'date': 'June 24'})
+        assert bad_date.value.code == 400
+        with pytest.raises(urllib.error.HTTPError) as traversal:
+            post(port, '/api/scaffold', httpd.bobframes_token, {'area': '../escape', 'date': '2026-06-24'})
+        assert traversal.value.code == 400
+
+
+def test_ab_and_scaffold_require_token(tmp_path):
+    with running(str(tmp_path)) as (httpd, port):
+        for path in ('/api/ab', '/api/scaffold'):
+            with pytest.raises(urllib.error.HTTPError) as e:
+                post(port, path, 'wrong-token', {})
+            assert e.value.code == 403, path

bobframes-0.2.8/bobframes/tests/test_ui_browser.py

@@ -0,0 +1,78 @@
+"""v028_7: opt-in headless-browser smoke that the panel JS actually RUNS and populates state.
+
+Marked ``browser`` -- DESELECTED by the default suite (``-m "not browser"``) and only run on demand
+(``pytest -m browser``) where a local Chrome exists, mirroring ``test_browser_shots.py`` (ADR-43 gate-d).
+This is the gate the v028_6 bug needed and node --check cannot give: ``node --check`` proves the script
+PARSES; this proves it RUNS. Chrome loads the LIVE panel over http (token in the URL), the page's
+``loadState()`` fetches ``/api/state``, and we assert the DOM populated (root path + tool rows + drops
+table) -- i.e. the script parsed AND executed AND wired the fetch->render path.
+"""
+from __future__ import annotations
+
+import pathlib
+import sys
+
+import pytest
+
+from ._ui_util import make_capture_root, running
+
+_TOOLS = pathlib.Path(__file__).resolve().parents[2] / 'tools'
+sys.path.insert(0, str(_TOOLS))
+import shoot  # noqa: E402  (path injected above; dev-only CDP harness, never shipped)
+
+pytestmark = pytest.mark.browser
+
+
+def _eval(chrome, expr, *, await_promise=False):
+    """Runtime.evaluate in the attached page; returns the by-value result. Raises on a JS exception
+    (a thrown panel script is a failure, not a None)."""
+    r = chrome.cdp.call('Runtime.evaluate',
+                        {'expression': expr, 'returnByValue': True, 'awaitPromise': await_promise},
+                        session=chrome.session)
+    if 'exceptionDetails' in r:
+        raise AssertionError(f'panel JS threw: {r["exceptionDetails"]}')
+    return r['result'].get('value')
+
+
+# An awaited promise that resolves once render() has replaced the "Loading..." placeholder (loadState's
+# fetch is async, so it completes AFTER Page.loadEventFired). Times out to a {timeout:true} marker so a
+# dead script fails the assert instead of hanging.
+_WAIT_POPULATED = """
+new Promise(function(resolve){
+  var waited = 0, step = 50, deadline = 5000;
+  var timer = setInterval(function(){
+    var root = document.getElementById('root');
+    var ready = root && root.textContent.indexOf('Loading') === -1;
+    if (ready) {
+      clearInterval(timer);
+      resolve({
+        root: root.textContent,
+        tools: document.getElementById('tools').innerHTML,
+        drops: document.getElementById('drops').innerHTML
+      });
+    } else if ((waited += step) >= deadline) {
+      clearInterval(timer);
+      resolve({timeout: true, root: root ? root.textContent : null});
+    }
+  }, step);
+})
+"""
+
+
+def test_panel_js_runs_and_populates_state(tmp_path):
+    if not shoot.find_chrome():
+        pytest.skip('Chrome not found')
+    root = make_capture_root(tmp_path)            # Town + Bay drops with .rdc files
+    with running(root) as (httpd, port):
+        url = f'http://127.0.0.1:{port}/?t={httpd.bobframes_token}'
+        with shoot.Chrome() as chrome:
+            s = chrome.session
+            chrome.cdp.call('Page.navigate', {'url': url}, session=s)
+            chrome.cdp.wait_event('Page.loadEventFired', session=s)
+            state = _eval(chrome, _WAIT_POPULATED, await_promise=True)
+
+    assert not state.get('timeout'), f'panel never populated -- the JS did not run: {state!r}'
+    # The script parsed, ran, fetched /api/state, and render() filled the DOM:
+    assert 'Loading' not in state['root'] and 'proj' in state['root'], state['root']
+    assert 'renderdoccmd' in state['tools'], 'tool rows did not render'
+    assert 'Town' in state['drops'] or 'Bay' in state['drops'], 'drops table did not render'

bobframes-0.2.8/bobframes/tests/test_ui_jobs.py

@@ -0,0 +1,82 @@
+"""v028_2: the subprocess job runner + SSE (mocked spawn -- no GPU/RenderDoc, the ADR-6 discipline).
+
+`jobs.spawn` is monkeypatched with a fake process that emits a scripted stdout transcript; the test
+asserts POST /api/ingest starts a job and GET /api/stream/<job> relays the classified lines + a final
+`done` event carrying the return code.
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+
+import pytest
+
+from ..ui import jobs as _jobs
+from ._ui_util import get, post, running
+
+_SCRIPT = [
+    "[10:00:00] pipeline: 1 drop(s); root=.",
+    "[10:00:00]   replay: 2 captures (sequential)",
+    "[10:00:10]     1: rc=0 10.0s",
+    "[10:00:20]     2: rc=0 10.0s",
+    "[10:00:21]   merge + parquetize",
+    "[10:00:22] pipeline done: 1 drops processed",
+]
+
+
+class _FakeProc:
+    def __init__(self, lines, rc=0):
+        self.stdout = iter(lines)
+        self.returncode = None
+        self._rc = rc
+
+    def wait(self):
+        self.returncode = self._rc
+        return self._rc
+
+    def poll(self):
+        return self.returncode
+
+    def terminate(self):
+        self.returncode = -15
+
+
+def test_build_run_argv_mirrors_ingest():
+    argv = _jobs.build_run_argv('/proj', force=True, render_only=False, workers=8, pixel_grid=2)
+    assert '--root' in argv and '--force' in argv
+    assert argv[argv.index('--workers') + 1] == '8'
+    assert argv[argv.index('--pixel-grid') + 1] == '2'
+    assert '--render-only' not in argv
+
+
+def test_ingest_streams_stdout_and_return_code(tmp_path, monkeypatch):
+    monkeypatch.setattr(_jobs, 'spawn', lambda argv: _FakeProc(list(_SCRIPT), rc=0))
+    with running(str(tmp_path)) as (httpd, port):
+        started = json.loads(post(port, '/api/ingest', httpd.bobframes_token, {'render_only': True}).read())
+        assert 'job' in started
+        stream = get(port, f"/api/stream/{started['job']}?t={httpd.bobframes_token}").read().decode('utf-8')
+    assert 'replay: 2 captures' in stream                 # raw line relayed verbatim
+    assert '"replay_total": 2' in stream and '"replay_done": 2' in stream
+    assert 'event: done' in stream and '"rc": 0' in stream
+
+
+def test_ingest_reports_nonzero_rc(tmp_path, monkeypatch):
+    monkeypatch.setattr(_jobs, 'spawn', lambda argv: _FakeProc(['[10:00:00] boom'], rc=1))
+    with running(str(tmp_path)) as (httpd, port):
+        jid = json.loads(post(port, '/api/ingest', httpd.bobframes_token, {}).read())['job']
+        stream = get(port, f'/api/stream/{jid}?t={httpd.bobframes_token}').read().decode('utf-8')
+    assert 'event: done' in stream and '"rc": 1' in stream
+
+
+def test_ingest_requires_token(tmp_path):
+    with running(str(tmp_path)) as (httpd, port):
+        with pytest.raises(urllib.error.HTTPError) as e:
+            post(port, '/api/ingest', 'wrong-token', {})
+        assert e.value.code == 403
+
+
+def test_stream_unknown_job_404(tmp_path):
+    with running(str(tmp_path)) as (httpd, port):
+        with pytest.raises(urllib.error.HTTPError) as e:
+            get(port, f'/api/stream/nope?t={httpd.bobframes_token}')
+        assert e.value.code == 404

bobframes-0.2.8/bobframes/tests/test_ui_js_parses.py

@@ -0,0 +1,34 @@
+"""v028_7/8: the panel JS must PARSE -- an automated gate that runs the parser (the v028_6 lesson).
+
+pytest exercises the panel's HTTP surface in Python but never parses or executes the panel JS; the
+v028_2 bug (a normal triple-quoted page literal turned the embedded JS ``"\\n"`` into a REAL newline
+mid-string-literal -> the WHOLE script was a syntax error -> nothing populated) shipped undetected
+through five commits for exactly that reason. v028_8 externalized the JS to
+``bobframes/ui/assets/panel.js`` (a real file -- the embedding bug class is now impossible), and this
+runs ``node --check`` on it (syntax-only, so browser globals like ``document`` / ``fetch`` /
+``EventSource`` are fine -- it parses, it does not resolve).
+
+Skips when node is absent locally; CI (`windows-latest` ships node) also runs an UNCONDITIONAL
+``node --check bobframes/ui/assets/panel.js`` step + ``node --version``, so the gate can never silently
+skip everywhere (ADR-23).
+"""
+from __future__ import annotations
+
+import pathlib
+import shutil
+import subprocess
+
+import pytest
+
+from ..ui import server as _server
+
+_PANEL_JS = pathlib.Path(_server.__file__).parent / 'assets' / 'panel.js'
+
+
+def test_panel_js_parses_with_node():
+    node = shutil.which('node')
+    if node is None:
+        pytest.skip('node not installed (CI runs an unconditional node --check step)')
+    assert _PANEL_JS.exists(), f'missing {_PANEL_JS}'
+    proc = subprocess.run([node, '--check', str(_PANEL_JS)], capture_output=True, text=True)
+    assert proc.returncode == 0, f'node --check rejected panel.js:\n{proc.stdout}\n{proc.stderr}'