PyPI - bobframes - Versions diffs - 0.2.6__tar.gz → 0.2.7__tar.gz - Mend

bobframes 0.2.6tar.gz → 0.2.7tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (392) hide show

{bobframes-0.2.6 → bobframes-0.2.7}/CHANGELOG.md RENAMED Viewed

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [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 +160,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.1.0...HEAD
+[Unreleased]: https://github.com/altpsyche/bobframes/compare/v0.2.7...HEAD
+[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.7}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bobframes
-Version: 0.2.6
+Version: 0.2.7
 Summary: RenderDoc capture pipeline: ingest, analyze, render.
 Project-URL: Homepage, https://github.com/altpsyche/bobframes
 Project-URL: Issues, https://github.com/altpsyche/bobframes/issues

{bobframes-0.2.6 → bobframes-0.2.7}/bobframes/_default_config.toml RENAMED Viewed

@@ -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.7/bobframes/_version.py ADDED Viewed

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

{bobframes-0.2.6 → bobframes-0.2.7}/bobframes/aggregates.py RENAMED Viewed

@@ -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.7}/bobframes/config.py RENAMED Viewed

@@ -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.7}/bobframes/package.py RENAMED Viewed

@@ -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.7}/bobframes/reports/assets/components.js RENAMED Viewed

@@ -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.7}/bobframes/reports/dashboard.py RENAMED Viewed

@@ -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.7}/bobframes/reports/discovery.py RENAMED Viewed

@@ -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.7}/bobframes/reports/draws_by_class.py RENAMED Viewed

@@ -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.7}/bobframes/reports/instancing_opportunities.py RENAMED Viewed

@@ -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.7}/bobframes/reports/orchestrator.py RENAMED Viewed

@@ -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)

{bobframes-0.2.6 → bobframes-0.2.7}/bobframes/reports/overdraw.py RENAMED Viewed

@@ -133,8 +133,10 @@ def build(root: str, *, drops: list | None = None, ab=None,
     if drops is None:
         drops = base.discover_drops(root)
     # Run model (ADR-35): live render targets = those sampled in the CURRENT run; per-drop sample
-    # columns below keep every run. A representative bucket is the current run's, not the oldest.
+    # columns below span the runs UP TO the current one (R-22: never runs that came after it; the run
+    # picker still lists every run). A representative bucket is the current run's, not the oldest.
     rc = base.run_context(drops, run_label=run_label, run_date=run_date)
+    drops = rc.history   # R-22: scope cross-drop data to <= current
     cur = rc.current
     ck = cur.key if cur else None
     out_path = base.output_path(root, 'overdraw', ab, run=rc)

{bobframes-0.2.6 → bobframes-0.2.7}/bobframes/reports/pass_gpu.py RENAMED Viewed

@@ -13,6 +13,7 @@ from collections import defaultdict
 import pyarrow.parquet as papq
 from . import base
+from .. import aggregates as _agg
 def _aggregate(drops: list, ok_caps: set) -> dict:
@@ -68,9 +69,11 @@ def build(root: str, *, drops: list | None = None, ab=None,
     if drops is None:
         drops = base.discover_drops(root)
     # Run model (ADR-35): GPU headline + treemap + per-area ranking reflect the CURRENT run; the
-    # per-drop GPU comparison rows below keep every run.
+    # per-drop GPU comparison rows below span the runs UP TO the current one (R-22: an older run's page
+    # must not show runs that came after it; the run picker still lists every run).
     rc = base.run_context(drops, run_label=run_label, run_date=run_date)
     cur = rc.current
+    drops = rc.history   # R-22: scope cross-drop data to <= current
     ck = cur.key if cur else None
     out_path = base.output_path(root, 'pass_gpu', ab, run=rc)
     out_dir = os.path.dirname(out_path)
@@ -96,10 +99,17 @@ def build(root: str, *, drops: list | None = None, ab=None,
             total_gpu += g
             n_passes += 1
             cur_areas_set.add(area)
+    # Q-10: lead with GPU PER FRAME (pooled over the run's captured frames, the summary/dashboard
+    # basis) so this hero shares a magnitude with the rest of the reports; the raw cross-capture total
+    # rides alongside as the labeled "total ... over captures".
+    fc = _agg.frame_counts(root, [cur]) if cur else {}
+    total_frames = sum(v['frames'] for v in fc.values())
+    gpu_per_frame = (total_gpu / total_frames) if total_frames else 0.0
     kpis = [
-        {'label': 'total gpu (s)', 'value': base.fmt_float(total_gpu, 3)},
-        {'label': 'areas',         'value': base.fmt_int(len(cur_areas_set))},
-        {'label': 'passes',        'value': base.fmt_int(n_passes)},
+        {'label': 'gpu / frame (s)',             'value': base.fmt_float(gpu_per_frame, 4)},
+        {'label': 'total gpu (s) over captures', 'value': base.fmt_float(total_gpu, 3)},
+        {'label': 'areas',                       'value': base.fmt_int(len(cur_areas_set))},
+        {'label': 'passes',                      'value': base.fmt_int(n_passes)},
     ]
     # Summary bar: top pass in the current run + area count
@@ -126,7 +136,7 @@ def build(root: str, *, drops: list | None = None, ab=None,
             parts.append(base.callout(
                 'info',
                 f'heaviest pass: {area} / {marker_short}',
-                f'{base.fmt_float(global_top_gpu, 3)}s GPU on the costliest capture - '
+                f'{base.fmt_float(global_top_gpu, 3)}s GPU summed over the run\'s captures - '
                 f'profile this pass first.',
                 href=f'#{base.h(area)}', link_text='jump to area'))
@@ -183,7 +193,7 @@ def build(root: str, *, drops: list | None = None, ab=None,
                 if len(drop_keys) >= 2:
                     cells = ['<div class="bar-row">',
-                             '<span class="key" style="color: var(--text-2)">drops</span>',
+                             '<span class="key" style="color: var(--text-2)">drops (total / drop)</span>',
                              '<div style="display:flex;gap:var(--sp-3);font:var(--fs-small) ui-monospace,monospace;align-items:center;color:var(--text-2)">']
                     prev_gpu = None
                     for i, k in enumerate(drop_keys):

{bobframes-0.2.6 → bobframes-0.2.7}/bobframes/reports/preview.py RENAMED Viewed

@@ -119,14 +119,14 @@ def _links_block() -> str:
 def _kpi_cards_block() -> str:
     cards = [
-        base.kpi_card('avg draws / frame', base.fmt_int(28410),
+        base.kpi_card('pooled mean draws / frame', base.fmt_int(28410),
                       delta_html='<span class="delta-pill neg">+4%</span>',
                       trend=base.trendline([3, 5, 4, 8, 6, 9, 7], tone='neg'),
-                      note='5 areas - 142,050 total', tone='neg'),
-        base.kpi_card('avg gpu / frame', base.fmt_float(12.8, 4),
+                      note='pooled across 5 frames, 5 areas - 142,050 total', tone='neg'),
+        base.kpi_card('pooled mean gpu / frame', base.fmt_float(12.8, 4),
                       delta_html='<span class="delta-pill pos">-1%</span>',
                       trend=base.trendline([9, 7, 8, 6, 6, 5, 5], tone='pos'),
-                      note='0.064 s total', tone='pos'),
+                      note='pooled across 5 frames - 0.064 s total', tone='pos'),
     ]
     return ('<div data-page-kind="summary"><div class="kpi-strip">'
             + ''.join(cards) + '</div></div>')

{bobframes-0.2.6 → bobframes-0.2.7}/bobframes/reports/shader_hotlist.py RENAMED Viewed

@@ -71,6 +71,7 @@ def build(root: str, *, drops: list | None = None, ab=None,
     # Run model (ADR-35): the hotlist ranks the CURRENT run's shaders; prior runs feed the per-drop
     # comparison columns + the resolved-since section, never the cost ranking.
     rc = base.run_context(drops, run_label=run_label, run_date=run_date)
+    drops = rc.history   # R-22: cross-drop comparison scoped to <= current (picker still lists all via rc)
     cur = rc.current
     bl = rc.baseline
     ck = cur.key if cur else None

bobframes 0.2.6__tar.gz → 0.2.7__tar.gz

bobframes 0.2.6tar.gz → 0.2.7tar.gz