bobframes 0.2.6__tar.gz → 0.2.8__tar.gz

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

@@ -7,6 +7,72 @@ 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
+estimator and rate KPIs read on one per-frame basis, so the same metric agrees across the summary,
+dashboard, and trend. No schema change (still schema 3); parquet digests stay byte-identical on the
+same captures. `_version` 0.2.6 -> 0.2.7.
+
+### Changed
+- One canonical aggregation policy (ADR-46): every rendered KPI label names its estimator precisely --
+  `Pooled mean`, `Mean (per area)`, `Median`, `Total` -- and never a bare "avg". Rate KPIs (GPU, draws)
+  read per-frame on a single basis, so the same area's GPU now reads identically across the summary,
+  dashboard, and trend (previously e.g. `0.0356`/frame on the summary vs a raw `0.178` total on the
+  dashboard with no bridge). A naming gate (`test_no_vague_estimator_labels`) fails the build on any
+  vague estimator word. (D-13..D-16, Q-10..Q-13)
+- Regression detection unified on the per-frame basis with config-driven thresholds: `trend_table`
+  reads every KPI per frame, so a regression flag is capture-count-independent and agrees with the
+  build-health verdict (a 7-vs-5-capture run no longer reports a false +40%); the per-KPI thresholds
+  (`draws`/`vbo`/`ibo`/`program_switches`) move from code literals to the `[report]` config, with
+  defaults that reproduce the prior values. (H-41)
+- `draws_by_class` ratios use `statistics.median` (was the upper-middle `sorted[n//2]`, an off-by-one
+  on even N).
+- `aggregates.frame_counts` is the single owner of every per-(drop, area) frame count; when the
+  GPU/draws denominator and the entity-rate denominator legitimately differ (a capture that replayed
+  but exported partial entity rows), the divergence is logged as a WARNING rather than silently
+  normalized away.
+
+### Fixed
+- Run-selector dropdown did nothing on every report: the component JS runs in `<head>`, so the custom
+  element upgraded before its child `<select>` had parsed; initialization now defers to
+  `DOMContentLoaded`. (R-20)
+- Exported standalone one-pager carried dead tree-relative navigation -- a run dropdown pointing at
+  siblings not in the bundle, a breadcrumb, the dashboard link, and a "viewing an older run" banner.
+  The detached summary now strips them; the in-tree summary keeps its working navigation. (R-21)
+- Older-run report pages showed cross-drop graphs and tables spanning all runs, including ones newer
+  than the page's own run. Cross-drop renderers now scope to run history (up to and including the
+  current run) while the run picker keeps the full list. (R-22)
+
 ## [0.2.6] - 2026-06-06
 
 A build-health one-pager, a shareable `package` bundle, a server-side component system, and a full visual
@@ -123,5 +189,9 @@ 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.1.0...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
 [0.1.0]: https://github.com/altpsyche/bobframes/releases/tag/v0.1.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bobframes
-Version: 0.2.6
+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.6 → 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.6 → bobframes-0.2.8}/bobframes/_default_config.toml

@@ -57,5 +57,9 @@ shader_complexity_high    = 60.0   # fragment shaders at/above this complexity a
 overdraw_reject_warn_pct  = 40.0   # RT sample-rejection % -> warn callout
 overdraw_reject_alarm_pct = 70.0   # RT sample-rejection % -> alarm callout
 instancing_repeat_min     = 4      # min mesh repeat PER FRAME to flag an instancing candidate (c16v: repeat + shader cost are per-frame rates, normalized by the drop's captured-frame count)
-gpu_regression_pct        = 10.0   # latest-vs-previous GPU increase % -> regression callout
+gpu_regression_pct        = 10.0   # latest-vs-previous GPU/frame increase % -> regression (per frame, capture-count-independent)
+draws_regression_pct      = 10.0   # H-41 — per-KPI trend regression thresholds (were baked in trend_table.KPIS literals)
+vbo_regression_pct        = 15.0   #   "   vertex-buffer bytes / frame
+ibo_regression_pct        = 15.0   #   "   index-buffer bytes / frame
+program_switches_regression_pct = 20.0  # "  program switches / frame
 max_prerendered_runs      = 10     # c16f — cap on pre-rendered older-run pages (run selector)

bobframes-0.2.8/bobframes/_version.py

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

{bobframes-0.2.6 → bobframes-0.2.8}/bobframes/aggregates.py

@@ -163,3 +163,69 @@ def shader_aggregates(root: str, drops: list, *, stage: str | None = None) -> Sh
         sa.cplx[k] = max(sa.cplx.get(k, 0.0), c_val)
         sa.stype[k] = stype
     return sa
+
+
+# --- frame counts (D-15: the single owner of every per-(drop, area) frame count) ----------------
+
+def _frame_total_captures(root: str, drops: list) -> dict:
+    """``{(drop_key, area): {captures}}`` from ``frame_totals.parquet`` -- the authoritative
+    captured-frame set (the distinct ``capture`` values present in the per-frame GPU/draws table that
+    ``dashboard._run_totals`` / ``_top_areas_gpu`` divide by). Read live per drop_dir (frame_totals has
+    no per-drop cache, mirroring the dashboard readers). If a frame_totals has no ``capture`` column,
+    each row is treated as one distinct frame (num_rows) so the count never under-reports."""
+    out: dict = defaultdict(set)
+    for d in drops:
+        for r in d.rows:
+            p = os.path.join(r.drop_dir, 'frame_totals.parquet')
+            if not os.path.exists(p):
+                continue
+            try:
+                names = set(papq.read_schema(p).names)
+                if 'capture' in names:
+                    caps = papq.read_table(p, columns=['capture']).column('capture').to_pylist()
+                else:
+                    caps = [f'__row_{i}' for i in range(papq.read_metadata(p).num_rows)]
+            except Exception:
+                continue
+            out[(drop_key(r.drop_date, r.drop_label), r.area)].update(caps)
+    return out
+
+
+def frame_counts(root: str, drops: list) -> dict:
+    """The ONE owner of every per-(drop, area) frame count (D-15 / D-A4). Returns
+    ``{(drop_key, area): {'frames', 'draw_frames', 'shader_frames'}}`` where ``frames`` = distinct
+    captures in frame_totals (the GPU/draws-per-frame denominator) and ``draw_frames``/``shader_frames``
+    = distinct captures in the draws/shaders entity data (the c16v entity-rate denominators).
+
+    The three legitimately DIFFER when a capture replayed "ok" but exported no entity rows (the c16v
+    as-built, ADR-23): per-frame GPU divides by the frames that produced GPU data, while per-frame mesh/
+    shader rates divide by the frames that produced that entity -- both correct for their metric, on
+    different populations. ``frame_count_divergences`` surfaces the difference so the different-N
+    normalization is visible across reports rather than silent. Raw counts (no >=1 guard) so divergence
+    is detectable; the per-frame no-op guard stays in ``DrawAgg.frames`` / ``ShaderAgg.frames``.
+    """
+    da = draw_aggregates(root, drops)
+    sa = shader_aggregates(root, drops)
+    ft = _frame_total_captures(root, drops)
+    keys = set(ft) | set(da.captures) | set(sa.captures)
+    return {
+        k: {
+            'frames': len(ft.get(k, ())),
+            'draw_frames': len(da.captures.get(k, ())),
+            'shader_frames': len(sa.captures.get(k, ())),
+        }
+        for k in keys
+    }
+
+
+def frame_count_divergences(root: str, drops: list) -> list:
+    """``[(drop_key, area, frames, draw_frames, shader_frames), ...]`` for every (drop, area) where an
+    entity count that EXISTS (>0) differs from the frame_totals frame count -- i.e. a capture produced
+    GPU/draw data but not the matching entity rows (or vice versa). Sorted for deterministic logging.
+    Empty when every layer agrees (the uniform-capture case). Drives the render-time warning (D-15)."""
+    out = []
+    for (dk, area), c in sorted(frame_counts(root, drops).items()):
+        ftn, dfr, sfr = c['frames'], c['draw_frames'], c['shader_frames']
+        if (dfr and dfr != ftn) or (sfr and sfr != ftn):
+            out.append((dk, area, ftn, dfr, sfr))
+    return out

{bobframes-0.2.6 → 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.6 → bobframes-0.2.8}/bobframes/config.py

@@ -131,6 +131,12 @@ class ReportCfg:                      # c16 — report-presentation thresholds (
     overdraw_reject_alarm_pct: float = 70.0
     instancing_repeat_min: int = 4    # c16v — min mesh repeat PER FRAME (repeat + shader cost are per-frame rates)
     gpu_regression_pct: float = 10.0
+    # H-41 (v027_1) — per-KPI trend regression thresholds; were baked in `trend_table.KPIS` literals.
+    # Trend-only (health's verdict has only a gpu trajectory rule). Defaults reproduce the old literals.
+    draws_regression_pct: float = 10.0
+    vbo_regression_pct: float = 15.0
+    ibo_regression_pct: float = 15.0
+    program_switches_regression_pct: float = 20.0
     max_prerendered_runs: int = 10    # c16f — cap on pre-rendered older-run pages (per-run UX)
 
 
@@ -327,6 +333,10 @@ def _build_config(root: str | None) -> Config:
             overdraw_reject_alarm_pct=rpt.get('overdraw_reject_alarm_pct', 70.0),
             instancing_repeat_min=rpt.get('instancing_repeat_min', 4),
             gpu_regression_pct=rpt.get('gpu_regression_pct', 10.0),
+            draws_regression_pct=rpt.get('draws_regression_pct', 10.0),
+            vbo_regression_pct=rpt.get('vbo_regression_pct', 15.0),
+            ibo_regression_pct=rpt.get('ibo_regression_pct', 15.0),
+            program_switches_regression_pct=rpt.get('program_switches_regression_pct', 20.0),
             max_prerendered_runs=rpt.get('max_prerendered_runs', 10),
         ),
         theme=ThemeCfg(tokens=tuple(theme_tokens.items())) if theme_tokens else None,

{bobframes-0.2.6 → bobframes-0.2.8}/bobframes/package.py

@@ -217,6 +217,9 @@ def build(root: str, *, out: str | None = None, light: bool = False,
             shutil.rmtree(staging, ignore_errors=True)
 
     if summary_file:
+        # The standalone one-pager is a DETACHED single file -- strip the tree-relative navigation that
+        # cannot resolve beside a lone HTML (R-21), so it no longer carries a dead run dropdown.
+        summary_bytes = _detach_summary(summary_bytes)
         with open(summary_path, 'wb') as f:
             f.write(summary_bytes)
     else:
@@ -503,6 +506,30 @@ def _redact_text_files(entries: list[tuple[str, str]], *, mode: str) -> int:
     return n
 
 
+# Tree-relative navigation that only resolves inside the rendered tree -- dead in a detached one-pager.
+# Each is a cleanly-delimited, non-nesting element generated by the chrome builders.
+_DETACH_RES = (
+    # the run selector: its options point to run/<key>/summary.html siblings not bundled with a lone file
+    re.compile(rb'<rdc-ab-picker><label for="rdc-run-select">.*?</rdc-ab-picker>', re.S),
+    re.compile(rb'<nav class="crumb">.*?</nav>', re.S),          # breadcrumb (root catalog / dashboard)
+    re.compile(rb'<a class="sb-link"[^>]*>.*?</a>', re.S),       # summary-bar "dashboard" link
+    # the "viewing an older run / go to newest" nav banner (older-run one-pagers); its link points to a
+    # sibling page absent beside a lone file. Anchored on its title so the health alarm-banner is kept.
+    re.compile(rb'<rdc-alarm-banner\b[^>]*>(?:(?!</rdc-alarm-banner>).)*?viewing an older run'
+               rb'(?:(?!</rdc-alarm-banner>).)*?</rdc-alarm-banner>', re.S),
+)
+
+
+def _detach_summary(html: bytes) -> bytes:
+    """Make the standalone one-pager genuinely self-contained (R-21): strip the tree-relative navigation
+    that cannot work in a LONE file -- the run selector (a silently-dead dropdown), the breadcrumb, and
+    the summary-bar dashboard link. The page's own content (verdict, KPIs, movement, by-area) is
+    self-contained and untouched; the in-tree `_reports/summary.html` keeps its working nav."""
+    for rx in _DETACH_RES:
+        html = rx.sub(b'', html)
+    return html
+
+
 def _redacted_summary_bytes(staging: str, summary_rel: str, *, newest: bool, target,
                             build_ts: str, shared: bool, redact_paths: str) -> bytes:
     """The standalone one-pager for a redacted bundle: self-contained (INLINE) + redacted.

{bobframes-0.2.6 → bobframes-0.2.8}/bobframes/reports/assets/components.js

@@ -6,7 +6,19 @@
     connectedCallback(){
       if (this._rdcUp) return;
       this._rdcUp = true;
-      try { this.init(); } catch(e) { console.error('rdc init error', this.tagName, e); }
+      const run = () => {
+        try { this.init(); } catch(e) { console.error('rdc init error', this.tagName, e); }
+      };
+      // The component JS rides in <head> (adjacent to the CSS), so a custom element upgrades as its
+      // START tag is parsed -- BEFORE its light-DOM children (e.g. the run <select>) exist. Inits that
+      // querySelector a child would see nothing and bail. Defer to DOMContentLoaded while the document
+      // is still parsing so children are present; run immediately for elements created after load.
+      // (Mirrors the _wireRowDrill deferral below.)
+      if (document.readyState === 'loading'){
+        document.addEventListener('DOMContentLoaded', run, { once: true });
+      } else {
+        run();
+      }
     }
     init(){}
   }

{bobframes-0.2.6 → bobframes-0.2.8}/bobframes/reports/dashboard.py

@@ -301,11 +301,11 @@ def _global_kpis(drops: list) -> list:
     avg_gpu_frame = (total_gpu / n_frames) if n_frames else 0.0
     avg_draws_frame = (total_draws / n_frames) if n_frames else 0.0
     return [
-        {'label': 'total gpu (s)',      'value': base.fmt_float(total_gpu, 3)},
-        {'label': 'avg gpu / frame (s)', 'value': base.fmt_float(avg_gpu_frame, 4)},
-        {'label': 'total draws',        'value': base.fmt_int(total_draws)},
-        {'label': 'avg draws / frame',  'value': base.fmt_int(round(avg_draws_frame))},
-        {'label': 'areas',              'value': base.fmt_int(len(areas))},
+        {'label': 'pooled mean gpu / frame (s)', 'value': base.fmt_float(avg_gpu_frame, 4)},
+        {'label': 'total gpu (s) over captures', 'value': base.fmt_float(total_gpu, 3)},
+        {'label': 'pooled mean draws / frame',   'value': base.fmt_int(round(avg_draws_frame))},
+        {'label': 'total draws over captures',   'value': base.fmt_int(total_draws)},
+        {'label': 'areas',                       'value': base.fmt_int(len(areas))},
     ]
 
 
@@ -351,6 +351,9 @@ def build(root: str, *, drops: list | None = None, ab=None,
     rc = base.run_context(drops, run_label=run_label, run_date=run_date)
     cur = rc.current
     cur_drops = [cur] if cur else []
+    # v027_4: per-area captured-frame counts (the single owner, D-15) so the mini cards can read
+    # per-frame and stay consistent with summary + the trend card (no bare cross-capture totals).
+    area_frames = {a: c['frames'] for (_dk, a), c in _agg.frame_counts(root, cur_drops).items()}
 
     # c16f: a per-run dashboard lives at _reports/run/<key>/index.html; its sibling reports (instancing
     # etc.) are pre-rendered there too, so their links stay bare. trend_table is NOT per-run (it is the
@@ -398,22 +401,23 @@ def build(root: str, *, drops: list | None = None, ab=None,
                          *[base.el('a', {'href': href, 'data-link-kind': 'primary'}, lbl)
                            for href, lbl in _NAV]))
 
-    # Card: trend table - GPU time per area (mini bars matching the trend flagship).
+    # Card: trend table - GPU PER FRAME per area (D-16: leads with the per-frame mean so the same area
+    # reads the SAME number here and on summary; the raw run total rides alongside as the labeled bridge).
     top_a = top_a[:3]
     chart_tt = base.figure(base.bar_chart(
-        [(a, g) for a, g, *_ in top_a], value_fmt=lambda v: f'{v:.3f}', width=280,
-        title='gpu (s) per area', desc='top areas by GPU seconds', chart_id='dash-tt'))
+        [(t[0], t[4]) for t in top_a], value_fmt=lambda v: f'{v:.4f}', width=280,
+        title='gpu / frame per area', desc='top areas by GPU per captured frame', chart_id='dash-tt'))
     body_tt = _card_table(
         top_a,
         [
             ('area', lambda r: r[0], False),
-            ('gpu (s)', lambda r: base.fmt_float(r[1], 3), True),
-            ('draws', lambda r: base.fmt_int(r[2]), True),
-            ('avg draws / frame', lambda r: base.fmt_int(round(r[3])), True),
+            ('mean gpu / frame', lambda r: base.fmt_float(r[4], 4), True),
+            ('total gpu (s)', lambda r: base.fmt_float(r[1], 3), True),
+            ('mean draws / frame', lambda r: base.fmt_int(round(r[3])), True),
         ],
-        caption='per-area GPU + draw load (avg draws per captured frame)')
-    sub_tt = ('GPU time per area in the current run.'
-              + (f' worst: {top_a[0][0]} {base.fmt_float(top_a[0][1], 3)}s' if top_a else ''))
+        caption='per-area GPU per captured frame + the run total (mean = area total / area frames)')
+    sub_tt = ('GPU per frame per area in the current run.'
+              + (f' worst: {top_a[0][0]} {base.fmt_float(top_a[0][4], 4)}s / frame' if top_a else ''))
     cards.append(_card(tt_href, 'trend table', sub_tt, chart_tt, body_tt))
 
     # Card: instancing - repeat per mesh (mini bars).
@@ -426,7 +430,7 @@ def build(root: str, *, drops: list | None = None, ab=None,
         [
             ('mesh', lambda r: r[0], False),
             ('repeat', lambda r: base.fmt_int(r[1]), True),
-            ('indices typ', lambda r: base.fmt_int(r[2]), True),
+            ('median verts', lambda r: base.fmt_int(r[2]), True),
         ],
         caption='most-repeated meshes')
     sub_im = ('Repeated meshes worth instancing or batching.'
@@ -438,7 +442,7 @@ def build(root: str, *, drops: list | None = None, ab=None,
     top_p = _top_passes(cur_drops)
     chart_pg = base.figure(base.bar_chart(
         [(pl, g) for _, pl, g in top_p], value_fmt=lambda v: f'{v:.3f}', width=280,
-        title='gpu (s) per pass', desc='heaviest passes by GPU seconds', chart_id='dash-pg'))
+        title='total gpu (s) per pass', desc='heaviest passes by total GPU seconds', chart_id='dash-pg'))
     body_pg = _card_table(
         top_p,
         [
@@ -447,9 +451,10 @@ def build(root: str, *, drops: list | None = None, ab=None,
             # so hover could never reveal it). The CSS clip now truncates the display + the td title=
             # reveals the full value on hover - consistent with every other mini text column.
             ('marker', lambda r: base.scrub_chrome_text(r[1]), False),
-            ('gpu (s)', lambda r: base.fmt_float(r[2], 3), True),
+            # per-pass GPU is a cross-capture total (the pass report's native basis); labeled as such.
+            ('total gpu (s)', lambda r: base.fmt_float(r[2], 3), True),
         ],
-        caption='heaviest passes by GPU time')
+        caption='heaviest passes by total GPU time')
     sub_pg = ('Heaviest GPU passes.'
               + (f' top: {top_p[0][1]} {base.fmt_float(top_p[0][2], 3)}s in {top_p[0][0]}'
                  if top_p else ''))
@@ -503,10 +508,13 @@ def build(root: str, *, drops: list | None = None, ab=None,
         pa_rows,
         [
             ('area', lambda r: r[0], False),
-            ('draws', lambda r: base.fmt_int(r[1]['n_draws']), True),
+            # per-frame to match summary's By-area + the trend card (D-16 consistency), not a bare total.
+            ('mean draws / frame',
+             lambda r: base.fmt_int(round(base.per_frame(r[1]['n_draws'], area_frames.get(r[0], 0)))),
+             True),
             ('dominant', lambda r: r[1]['dominant_class'], False),
         ],
-        caption='top areas by draw count')
+        caption='top areas by mean draws per captured frame')
     dom = class_totals.most_common(1)[0] if class_totals else None
     sub_dc = ('Draw mix by class.'
               + (f' dominant: {dom[0]} {base.fmt_pct(100.0 * dom[1] / grand)}'

{bobframes-0.2.6 → bobframes-0.2.8}/bobframes/reports/discovery.py

@@ -182,6 +182,15 @@ class RunContext:
     def is_newest(self) -> bool:
         return bool(self.current) and self.index == self.n_runs - 1
 
+    @property
+    def history(self) -> list:
+        """Drops up to AND INCLUDING the current run (chronological) -- the data scope for cross-drop
+        CHARTS/TABLES on a per-run page, so an OLDER run's page never shows data for runs that came
+        AFTER it (ADR-35; R-22). The run picker still lists every run (from `drops`); only the rendered
+        data is scoped. Equals `drops` on the newest page (index == n_runs - 1)."""
+        i = self.index
+        return list(self.drops) if i < 0 else self.drops[:i + 1]
+
     @property
     def run_label(self) -> str:
         """current.key (e.g. '2026-06-01_r110788'); '' when there is no current run."""

{bobframes-0.2.6 → bobframes-0.2.8}/bobframes/reports/draws_by_class.py

@@ -7,12 +7,14 @@ Segments colored by draw_class. Below: raw-count table.
 from __future__ import annotations
 
 import os
+import statistics
 import sys
 from collections import Counter, defaultdict
 
 import pyarrow.parquet as papq
 
 from . import base
+from .. import aggregates as _agg
 
 
 def _gather_from_drops(drops: list) -> tuple[dict, list, list, int]:
@@ -79,8 +81,11 @@ def _build_table(counts: dict, drop_keys: list) -> str:
                            caption='raw draw counts per class, per area and drop')
 
 
-def _compute_kpis(counts: dict, areas: list) -> list:
-    """Hero KPIs: total draws, n areas, median prepass/opaque ratio, dominant class."""
+def _compute_kpis(counts: dict, areas: list, total_frames: int) -> list:
+    """Hero KPIs (current run): mean draws / frame + the labeled raw total, n areas, the MEDIAN
+    prepass/opaque ratio across areas, dominant class. Q-12: lead with the per-frame mean (the
+    capture-count-independent number) and label the total. Q-11: `statistics.median` (not the
+    upper-middle `sorted[n//2]`), and the label names the estimator + population."""
     total = sum(sum(cc.values()) for cc in counts.values())
     ratios = []
     class_totals: Counter = Counter()
@@ -90,14 +95,15 @@ def _compute_kpis(counts: dict, areas: list) -> list:
         op = cc.get('opaque', 0)
         if op:
             ratios.append(cc.get('prepass', 0) / op)
-    median_ratio = (sorted(ratios)[len(ratios) // 2]
-                    if ratios else 0.0)
+    median_ratio = statistics.median(ratios) if ratios else 0.0
     dominant_cls = (class_totals.most_common(1)[0][0]
                     if class_totals else '')
+    mean_draws = base.per_frame(total, total_frames)   # per frame (no-op when frames<=1)
     return [
-        {'label': 'total draws', 'value': base.fmt_int(total)},
+        {'label': 'mean draws / frame', 'value': base.fmt_int(round(mean_draws))},
+        {'label': 'total draws over captures', 'value': base.fmt_int(total)},
         {'label': 'areas',       'value': base.fmt_int(len(areas))},
-        {'label': 'prepass/opaque (med)', 'value': base.fmt_float(median_ratio, 2)},
+        {'label': 'median prepass / opaque (across areas)', 'value': base.fmt_float(median_ratio, 2)},
         {'label': 'dominant class', 'value': dominant_cls or '-'},
     ]
 
@@ -112,9 +118,12 @@ def build(root: str, *, drops: list | None = None, ab=None,
     # table below keeps every run as the breakdown / comparison view.
     rc = base.run_context(drops, run_label=run_label, run_date=run_date)
     cur = rc.current
+    drops = rc.history   # R-22: cross-drop data scoped to <= current (picker still lists all via rc)
     counts, areas, drop_keys, total_captures = _gather_from_drops(drops)
     cur_counts = {k: cc for k, cc in counts.items() if cur and k[1] == cur.key}
     cur_areas = cur.areas if cur else []
+    # Q-12: per-frame mean draws needs the current run's captured-frame count (the single owner, D-15).
+    cur_frames = sum(v['frames'] for v in (_agg.frame_counts(root, [cur]) if cur else {}).values())
 
     parts = []
 
@@ -183,7 +192,7 @@ def build(root: str, *, drops: list | None = None, ab=None,
         drops=len(drops), captures=total_captures, build_ts=build_ts or base.now_iso(),
         crumb_depth=base.crumb_depth(ab, run=rc), ab=ab, root=root, report_key='draws_by_class',
         sink=sink, theme=theme,
-        kpis=_compute_kpis(cur_counts, cur_areas), run=rc,
+        kpis=_compute_kpis(cur_counts, cur_areas, cur_frames), run=rc,
         device=base.provenance_strip(*base.newest_drop_provenance(root, [cur] if cur else []), redact=redact))])
 
 

{bobframes-0.2.6 → bobframes-0.2.8}/bobframes/reports/instancing_opportunities.py

@@ -71,6 +71,7 @@ def build(root: str, *, drops: list | None = None, ab=None,
     # Run model (ADR-35): live candidates are meshes drawn in the CURRENT run; prior runs supply the
     # per-drop comparison columns + the resolved-since section, never inflate the live list.
     rc = base.run_context(drops, run_label=run_label, run_date=run_date)
+    drops = rc.history   # R-22: cross-drop trend scoped to <= current (picker still lists all via rc)
     cur = rc.current
     bl = rc.baseline
     ck = cur.key if cur else None
@@ -220,7 +221,7 @@ def build(root: str, *, drops: list | None = None, ab=None,
         if chart_items:
             mbody.append(base.figure(
                 base.bar_chart(chart_items, title='estimated wasted indices',
-                               desc='(max repeat - 1) x typical indices, per mesh',
+                               desc='(max repeat - 1) x median indices, per mesh',
                                chart_id='inst-wasted'),
                 'estimated wasted indices (top meshes)'))
 
@@ -237,9 +238,9 @@ def build(root: str, *, drops: list | None = None, ab=None,
         cols += [
             base.Column('areas', 'areas', clip='default'),
             base.Column('dompass', 'dominant pass', clip='narrow'),
-            base.Column('ityp', 'indices typical', numeric=True),
+            base.Column('ityp', 'median indices', numeric=True),
             base.Column('wasted', 'wasted indices', numeric=True,
-                        title='(max repeat - 1) x typical indices: index data re-submitted across repeats',
+                        title='(max repeat - 1) x median indices: index data re-submitted across repeats',
                         render=lambda value, row: base.heatmap_cell(value, 0, row['_maxw'],
                                                                     text=base.fmt_int(value))),
         ]

{bobframes-0.2.6 → bobframes-0.2.8}/bobframes/reports/orchestrator.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import time
 
+from .. import aggregates as _agg
 from .. import lint
 from ..config import get_config
 from ..html import template
@@ -43,6 +44,16 @@ def render_all_reports(root: str, log, *,
     cache_out = reports_base.build_per_drop_cache(root)
     log(f'  built per-drop cache: {cache_out} ({time.monotonic()-t0:.1f}s)')
 
+    # D-15 (D-A4): one owner of every per-(drop, area) frame count. Per-frame GPU/draws divide by the
+    # frame_totals frame count; per-frame mesh/shader rates divide by the entity-capture count (c16v).
+    # They legitimately differ when a capture replayed "ok" but exported no entity rows -- surface that
+    # so cross-report per-frame normalization uses different N visibly, not silently (ADR-23, warn not
+    # assert: the divergence is a real data condition, present even in the synthetic fixture).
+    for dk, area, ftn, dfr, sfr in _agg.frame_count_divergences(root, reports_base.discover_drops(root)):
+        log(f'  WARNING: frame-count divergence {area} {dk}: frame_totals={ftn} draws={dfr} '
+            f'shaders={sfr} -- per-frame GPU/draws and per-frame entity rates use different '
+            f'denominators (a capture replayed but exported partial entity data)')
+
     for mod in all_reports():
         try:
             rep = mod.build(root, sink=sink, build_ts=build_ts, redact=redact, theme=theme)