bobframes 0.1.0__tar.gz → 0.2.6__tar.gz

bobframes-0.2.6/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+Changes to this project are documented here, newest first.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.6] - 2026-06-06
+
+A build-health one-pager, a shareable `package` bundle, a server-side component system, and a full visual
+redesign. No schema change (still schema 3); parquet digests stay byte-identical to 0.1.0/0.2.0 on the same
+captures. Per ADR-43 there is no standalone 0.2.5 -- this release carries the c16q-c16x foundation AND the
+redesign, so `_version` jumps `0.2.0 -> 0.2.6`.
+
+### Added
+- Build-health one-pager (`bobframes report summary`): a presentation-independent verdict/trend module
+  (`health.py` -- ordered OK<UNKNOWN<AT_RISK<ALARM so a real alarm is never masked yet missing data is
+  never a false green) feeding a print-first exec summary (verdict bar, averaged KPIs with vs-prior pills +
+  sparklines, a baseline-gated movement card, a worst-first by-area table). (ADR-39)
+- `bobframes package`: a non-mutating transform of a rendered tree into a shareable `<project>-<date>-report.zip`
+  (reproducible bytes) + a standalone self-contained `summary.html`. `--shared-assets` (the default) dedupes
+  chrome into `_assets/` linked per page (built at the render seam, not by scraping HTML); `--inline` opts out;
+  `--redact` scrubs device/host provenance at the data seam (whole-tree drop-sidecars excluded). (ADR-40/41)
+- Server-side component system (`reports/chrome.py`): an escape-by-construction element builder (`el`/`raw`/
+  `el_void`/`classes`), a normalized table-component family (`Column`/`data_table`/`static_table` + a virtual
+  `table_controls`/`virtual_host`/`virtual_table_section` host), a delta-column factory, and a token-validity
+  guard (`undefined_tokens()` -- a typo'd `var(--x)` is a CI failure + a `preview` warning). CSS/JS now live as
+  real `reports/assets/*.{css,js}` files. A `bobframes preview` gallery documents every component. (ADR-42)
+- User theme override for pip installs: a `.bobframes.toml [theme]` section + `render/preview --accent`/
+  `--accent-data` flags re-hue the accent/status/chart colors WITHOUT editing the packaged `design_tokens.toml`
+  (deep-merged through the existing config cascade; color-key allowlist; ASCII/injection-guarded). `export-tokens
+  --theme-template` emits a paste-ready starter; `--watch` polls `.bobframes.toml`. (ADR-45)
+- Dev-only screenshot harness `tools/shoot.py` (headless-Chrome over CDP, light/dark/print; not shipped) + a
+  `-m browser` opt-in matrix + a dependency-free oklch->WCAG contrast test, for the redesign's visual gate.
+
+### Changed
+- Visual redesign anchored on shadcn/ui + Grafana density (ADR-43/44): a neutral grayscale palette (chroma 0),
+  WCAG-AA tertiary text, FLAT border-led surfaces (reverses the ADR-34 depth -- a 1px border + a `--radius`
+  6/8/10 token scale replaces the elevation shadows + the hardcoded 2/3/4px radii), `:focus-visible` rings,
+  reduced-motion-safe `:active`, container-query responsive, and a print pass. Restrained type tune with hero
+  numerals scoped to the summary one-pager; Grafana-dense rows/cards everywhere else; the catalog/drill data
+  browser widened (max data-per-screen).
+- "Everything is a component": the summary, dashboard minis, the 6 detail reports, and the catalog/drill virtual
+  hosts all render through the component family; the remaining hand-written chrome leaves were migrated onto `el`
+  (the bespoke-markup long-tail is closed -- only the fixed page scaffold remains, by necessity). `data_table`
+  normalizes the previously hand-written report tables (the visual-parity gate is intentionally replaced by a
+  structural + data-preservation gate per ADR-43).
+- Per-frame normalization for multi-capture runs (instancing repeat + shader cost read per distinct capture,
+  no-op for 1-capture data so it stays byte-identical) and a single `aggregates.py` data layer feeding the
+  dashboard/reports/verdict so they cannot disagree.
+- Run model + sharing surfaced in the root catalog (build-health + dashboard chips, A/B pair lists).
+
+### Fixed
+- Single-drop trend-table crash (`'str' object has no attribute 'get'`); `--force` rotation-backup
+  double-counting in the catalog + global-entities walkers (canonical-basename reconstruction).
+- WCAG-AA contrast on tertiary text; print no longer hugs the paper edge.
+
+## [0.2.0] - 2026-06-03
+
+De-hardcoding + a full report overhaul. No schema change (still schema 3); extraction output is stable
+where the pipeline is unchanged, so parquet digests are byte-identical to 0.1.0 on the same captures.
+
+### Added
+- Inline-SVG chart toolkit (`reports/charts.py`): a flagship chart per report (pass-GPU treemap,
+  draws-by-class donut, shader complexity-vs-cost scatter, overdraw reject-rate bars, instancing
+  wasted-index bars, per-KPI trend lines), deterministic and dependency-free (no `random`/`Date`).
+- Report design language: hero KPI strip, callouts with config-driven severity, provenance/device
+  strip, section cards, sticky section headers, copy buttons on long IDs, vendored Inter subset font
+  (offline, base64-inlined), and an auto-tint heatmap on ranked numeric columns.
+- Run model: per-run truth (each report names "run N of M"), a run picker, A/B compare, and a trend
+  table across runs; older runs are pre-rendered up to a configurable limit.
+- One unified `rdc-table` engine (progressive enhancement, two modes): server-baked `static` for reports
+  (JS-off / print / Ctrl-F / golden all hold) and windowed `virtual` for the catalog + per-drop drill.
+  Shared natural-numeric sort, type-split, heatmap, column groups, search/filter, controllable cell
+  truncation with hover-reveal, and full sort/filter a11y (aria-sort + keyboard-operable headers + a
+  labelled filter input) across both modes.
+- TOML config (`.bobframes.toml`, `[report]`/`[pipeline]` sections), `design_tokens.toml` token system,
+  and a state-capable draw classifier driven by table columns.
+- Reports cache with a SHA256 sidecar (corrupt/missing/mismatch falls back to a live scan, never
+  silent-empty); manifest schema-version guard (`ingest --force` hint on mismatch).
+
+### Changed
+- Catalog + drill readability: roomier rows, type-split mono/sans, and the heavy per-table row data moved
+  out of the HTML into `_pagedata/*.js` companions (the ~21 MB time-to-interactive fix) loaded via a
+  file://-safe `<script defer src>`.
+- External tool resolution + clearer pipeline error messages and exit codes; environment variables
+  renamed `RDC_*` -> `BOBFRAMES_*` (one-release legacy fallback with a deprecation warning).
+- Project paths, the report registry, and the drill-size budget are configurable rather than hardcoded.
+
+## [0.1.0] - 2026-05-31
+
+First standalone release. v1 is Windows-only (the replay stage drives `qrenderdoc`).
+
+### Added
+- Single `bobframes` binary with subcommands `ingest`, `render`, `ab`, `report`, `catalog`, `lint`,
+  `check`, `serve`, `smoke`, and `version`. Positional `root` (default `.`) across verbs; long-flag
+  only; exit codes `0`/`1`/`2`/`3`/`4`. stdlib `logging` at INFO by default, `--verbose` for DEBUG,
+  `[HH:MM:SS]` line format (G-8).
+- Replay script located via `importlib.resources` (`bobframes.replay.replay_script_path`) so replay
+  works from an installed wheel, not just an in-tree checkout.
+- Reliability hardening: atomic writes for `_manifest.json`, Parquet+CSV pairs, and `done.marker`
+  (`.tmp` + `os.replace`, rollback on failure); process-tree kill (`taskkill /T /F`) when a
+  `qrenderdoc` replay times out; per-capture replay-failure isolation
+  (`capture_status='replay_failed'` instead of aborting the whole drop); subprocess stderr logged on
+  convert-timeout and on every parse; manifest provenance fields `tool_versions` and `host_info`.
+- Test gates: golden-snapshot parity, schema regression, determinism, performance, and a replay
+  column-drift guard against `schemas.py` (H-6); mocked-subprocess tests for the hardening branches
+  the GPU-less runner cannot exercise; a data-driven `smoke` (render-only against a bundled synthetic
+  fixture by default); unit tests for stable keys, schemas, and drop discovery.
+- GitHub Actions CI across a Windows / Python / pyarrow matrix, with a tag-gated PyPI publish job.
+
+### Changed
+- **Stable-key format upgrade:** stable keys now carry a `KEY_VERSION = 1` version byte in the hash
+  input. Keys produced before this release are not comparable with `0.1.0` keys; rebuild affected
+  data with `bobframes ingest --force`. `KEY_VERSION` bumps on any future key-derivation rule change.
+- Timestamps unified to a single UTC `now_iso()` helper (`bobframes.manifest.now_iso`); the
+  local-time variant in `reports/cli` was dropped.
+
+### Removed
+- The project-embedded `_analysis` package. `python -m _analysis.run` and the other
+  `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
+[0.1.0]: https://github.com/altpsyche/bobframes/releases/tag/v0.1.0

bobframes-0.2.6/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: bobframes
+Version: 0.2.6
+Summary: RenderDoc capture pipeline: ingest, analyze, render.
+Project-URL: Homepage, https://github.com/altpsyche/bobframes
+Project-URL: Issues, https://github.com/altpsyche/bobframes/issues
+Project-URL: Changelog, https://github.com/altpsyche/bobframes/blob/main/CHANGELOG.md
+Author-email: Siva Subramanyam <sivasubramanyam@mayhem-studios.com>
+License: MIT
+License-File: LICENSE
+Keywords: gpu,parquet,profiling,renderdoc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: <3.15,>=3.10
+Requires-Dist: pyarrow<22,>=17
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# BobFrames
+
+RenderDoc capture pipeline: ingest, analyze, render. Point it at a folder of `.rdc` captures and it
+produces `_data/` (Parquet tables) plus `_reports/` -- static, offline, `file://`-safe HTML you can
+browse: a one-page **build-health summary**, a reports dashboard, per-aspect reports (overdraw, shader
+hotlist, instancing, draws-by-class, pass-GPU, cross-run trend), and a per-drop drill-down data browser.
+Reports are self-contained, printable, Ctrl-F-able, and work with JavaScript off. Windows-only in v1.
+
+> Built for **Mayhem Studios** -- see [Built for Mayhem Studios](#built-for-mayhem-studios) below.
+
+## Requirements
+
+- Windows 10 or later (the replay stage drives `qrenderdoc`, which is Windows-only in v1).
+- Python 3.10 - 3.13.
+- RenderDoc 1.x, or Arm Performance Studio, providing `renderdoccmd` and `qrenderdoc` on disk.
+
+## Install
+
+```
+pipx install bobframes
+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.
+
+## Quickstart
+
+```
+cd path\to\captures      # a folder of <Area>\<YYYY-MM-DD[_label]>\*.rdc
+bobframes ingest .       # export, parse, replay, parquetize, derive, render
+bobframes serve .        # open a local static preview of the reports
+```
+
+`ingest` writes Parquet under `_data/` and HTML under `_reports/`. Re-run `bobframes render .` any
+time to rebuild the HTML from existing Parquet without re-replaying captures.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `ingest [root] [--area X] [--label Y] [--capture N] [--force] [--pixel-grid 4] [--render-only]` | Full pipeline: export, parse, replay, parquetize, derive, manifest, commit, catalog, render. |
+| `render [root] [--area X] [--label Y] [--accent OKLCH] [--accent-data OKLCH] [--watch]` | Rebuild HTML and catalog from existing Parquet. `--accent`/`--accent-data` re-hue the theme for this render (ADR-45). `--watch` re-renders on `design_tokens.toml`, chrome, or `.bobframes.toml` edits (alpha). |
+| `ab [root] --baseline-label X --compare-label Y` | All reports for one drop pair under `_reports/ab/<pair>/`. |
+| `report [root] <name>` | Build one named report (summary, draws-by-class, trend, instancing, pass-gpu, shader, overdraw, dashboard). `summary` is the exec build-health one-pager. |
+| `catalog [root]` | Rebuild `_data/_catalog.parquet` only. |
+| `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. |
+| `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`. |
+| `smoke [--data DIR]` | End-to-end check; render-only against the bundled fixture when `--data` is omitted. |
+| `version` | Print `bobframes`, schema, and pyarrow versions. |
+
+`<root>` is positional and defaults to `.`. Flags are long-form only. Exit codes: `0` success,
+`1` pipeline or build failure, `2` usage error, `3` external tool missing, `4` interrupted.
+
+## Sharing a report
+
+`bobframes package <root>` turns a rendered tree into two friendly artifacts beside it (it only READS
+`<root>`):
+
+- `<project>-<rundate>-report.zip` -- the full explorable tree. **Extract the whole folder before
+  opening** (`index.html`, then the Build Health Summary): the pages link each other and a shared
+  `_assets/` folder by relative path, so opening one file straight out of the zip breaks those links.
+- `<project>-<rundate>-summary.html` -- a standalone, self-contained one-pager. Email it, double-click
+  it, or `Ctrl-P -> Save as PDF`; no unzip needed. (Its deep links into the reports only resolve when
+  the zip is shipped alongside.)
+
+The zip DEFAULTS to **shared assets**: the ~95 KB of chrome (font + CSS + JS) lives once in `_assets/`
+and every page links it, so a multi-run bundle is markedly smaller. Because the pages share that
+folder, **no single page is portable on its own** -- keep the extracted folder together, or send the
+standalone `summary.html` when you need just one file. `--inline` opts out and makes each page
+self-contained (larger, but any single report file is portable). `--light` bundles only `index.html`
++ the top-level reports (no drill pages or data) for a quick "read, don't drill" share.
+
+### Sharing externally -- `--redact`
+
+`bobframes package <root> --redact` produces a bundle safe to hand to someone outside your team. It
+scrubs the GPU / driver / CPU / OS + capture-tool versions from every page's device strip (replaced with
+`redacted`), drops the raw provenance sidecars (`_manifest.json`, `frame_metadata.jsonl`) from the
+bundle, and replaces absolute Windows paths (`C:\...`) with `<path redacted>` across the pages and the
+downloadable CSVs. Redaction re-renders the tree, so `--inline --redact` is no longer a fast copy.
+
+- `--redact-paths=strip` (default) -- replace the path tokens; the bundle stays usable on a real capture.
+- `--redact-paths=fail` -- a CI completeness check: exit nonzero (don't write the zip) if any absolute
+  path remains in a rendered page, so a leak fails the build.
+
+**Caveat:** the pages and the downloadable CSVs are sanitized, but the **binary `.parquet`** tables still
+contain resource paths (they can't be string-edited safely) -- strip `_data/` if the parquet itself must
+leave your team. UNC (`\\host\share`) and forward-slash (`C:/...`) paths are not auto-stripped.
+
+## Customizing reports
+
+The look is shadcn-clean, neutral, and flat by default. Two ways to re-color it:
+
+### Pip installs -- re-hue without editing source (recommended)
+
+`pip install bobframes` puts the design tokens in site-packages, where edits are lost on upgrade -- so
+re-hue the accent / status / chart colors through the config cascade instead:
+
+- **Persistent:** add a `[theme]` section to `.bobframes.toml` in your capture root (or
+  `%APPDATA%/bobframes/config.toml`). `bobframes export-tokens --theme-template` prints a ready-to-paste
+  starter with just the overridable color knobs.
+- **One-shot:** `bobframes render . --accent '<oklch>'` (and `--accent-data '<oklch>'`) -- the top
+  precedence tier (CLI > env > config > bundled default). `bobframes preview --accent '<oklch>'` previews
+  it with no capture data.
+
+Only color hues (accent, the four status colors, the draw-class + chart palette) are overridable; layout,
+spacing, type, and the table engine stay bundled, so an override can never desync the rendering. A bad or
+non-color value warns and is ignored. `--watch` live-reloads on `.bobframes.toml` edits too.
+
+### Source checkouts -- edit the bundled tokens
+
+The full palette lives in `bobframes/reports/design_tokens.toml` (colors, spacing, type, motion, radius,
+and base layout sizes). The CSS variable name is fixed by its key: `surface_0` becomes `--surface-0`,
+`accent_primary` becomes `--accent-primary`.
+
+```
+bobframes preview                 # writes _reports/_chrome_preview.html (every component, no data)
+# edit a value in design_tokens.toml
+bobframes preview                 # under a second; reload the page in a browser
+bobframes render C:\captures      # apply the change to real reports from existing Parquet
+```
+
+`bobframes render --watch` re-runs render-only whenever `design_tokens.toml`, a chrome module, or
+`.bobframes.toml` changes (alpha; a 500ms poll, no extra dependency). `bobframes export-tokens --format
+css` prints the live `:root` block; `--format json` the nested table; `--format toml` the file itself.
+
+## External tools
+
+The export stage runs `renderdoccmd convert`; the replay stage runs `qrenderdoc --python`. bobframes
+resolves both from (in order) a config file (`.bobframes.toml`), version-globbed Arm Performance Studio
+install paths, and `PATH`. Install RenderDoc / Arm Performance Studio anywhere on those, or point a
+config entry at it. Run `bobframes check` to see what was resolved.
+
+## Output layout
+
+```
+<root>/
+  index.html                          root catalog view
+  <area>/<drop>/                      raw RDC inputs (left untouched)
+  _data/                              pipeline outputs
+    _catalog.parquet (+ .csv, .json)
+    _global_entities.parquet (+ .csv)
+    _query_examples.md
+    <area>/<drop>/                    per-drop data (29 Parquet tables)
+      *.parquet (+ matching .csv)
+      _manifest.json, _resource_labels.json
+      shader_src/*.glsl, jsonl sidecars
+      done.marker
+  _reports/                           rendered HTML
+    *.html (dashboard + reports)
+    ab/<pair>/*.html
+    drill/<area>/<drop>/index.html    per-drop browser
+    _cache/
+```
+
+The catalog stores each drop's path relative to `<root>` for portability.
+
+## Migrating from `_analysis`
+
+v1 is a hard rename of the older project-embedded `_analysis` package, with no compatibility shim:
+`python -m _analysis.*` stops working once `bobframes` is installed. Map old invocations to new ones:
+
+| Old (`_analysis`) | New (`bobframes`) |
+|---|---|
+| `python -m _analysis.run --root . --area X --label Y` | `bobframes ingest . --area X --label Y` |
+| `python -m _analysis.reports.ab --root . --baseline-label X --compare-label Y` | `bobframes ab . --baseline-label X --compare-label Y` |
+| `python -m _analysis.lint <file>` | `bobframes lint <file>` |
+| `python -m _analysis.tests.smoke` | `bobframes smoke` |
+
+## Troubleshooting
+
+| Symptom | Resolution |
+|---|---|
+| `renderdoccmd not found` (exit 3) | Install RenderDoc or Arm Performance Studio, or put the executable on `PATH`; confirm with `bobframes check`. |
+| `qrenderdoc` replay hangs | v1 kills the replay process tree on timeout and records `capture_status='replay_failed'` for that capture; the rest of the drop still completes. Re-run with `--force` to retry. |
+| Lint failure during render | The emitted HTML contains a banned token. Run `bobframes lint <file>` to see the line and label. |
+| `schema mismatch` (exit 1) | A drop's `_manifest.json` schema version differs from the installed schema. Rebuild it with `bobframes ingest --force` (the v1 schema-migration path; see G-3). |
+| Permission denied on `_data` | Close any viewer holding a Parquet open, then re-run; writes are staged and renamed atomically. |
+
+## Advanced
+
+- A/B reports: `bobframes ab . --baseline-label OLD --compare-label NEW` builds a side-by-side set.
+- Programmatic use: import `bobframes.schemas`, `bobframes.discovery`, and `bobframes.paths` to drive
+  table lookups, drop discovery, and path resolution from your own scripts.
+- `bobframes/probes/whatif.py` is a manual qrenderdoc-side probe and is not wired as a CLI command.
+- TOML config (`.bobframes.toml`), an externalized draw classifier, and design-token theming
+  (`[theme]` / `--accent`) shipped in v0.2.6. `bobframes package` produces shareable, optionally
+  redacted bundles (see [Sharing a report](#sharing-a-report)).
+
+## Built for Mayhem Studios
+
+BobFrames is built and maintained for **Mayhem Studios** -- it powers the studio's GPU
+capture-analysis and frame-performance work, and is open-sourced here for the wider RenderDoc and
+graphics community.
+
+If BobFrames helps your work, please **support Mayhem Studios** -- the studio that makes this tool
+possible. Follow the studio, play and wishlist our games, and tell a friend who fights frame times.
+A on the [GitHub repo](https://github.com/altpsyche/bobframes) helps too. Thank you.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

bobframes-0.2.6/README.md

@@ -0,0 +1,206 @@
+# BobFrames
+
+RenderDoc capture pipeline: ingest, analyze, render. Point it at a folder of `.rdc` captures and it
+produces `_data/` (Parquet tables) plus `_reports/` -- static, offline, `file://`-safe HTML you can
+browse: a one-page **build-health summary**, a reports dashboard, per-aspect reports (overdraw, shader
+hotlist, instancing, draws-by-class, pass-GPU, cross-run trend), and a per-drop drill-down data browser.
+Reports are self-contained, printable, Ctrl-F-able, and work with JavaScript off. Windows-only in v1.
+
+> Built for **Mayhem Studios** -- see [Built for Mayhem Studios](#built-for-mayhem-studios) below.
+
+## Requirements
+
+- Windows 10 or later (the replay stage drives `qrenderdoc`, which is Windows-only in v1).
+- Python 3.10 - 3.13.
+- RenderDoc 1.x, or Arm Performance Studio, providing `renderdoccmd` and `qrenderdoc` on disk.
+
+## Install
+
+```
+pipx install bobframes
+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.
+
+## Quickstart
+
+```
+cd path\to\captures      # a folder of <Area>\<YYYY-MM-DD[_label]>\*.rdc
+bobframes ingest .       # export, parse, replay, parquetize, derive, render
+bobframes serve .        # open a local static preview of the reports
+```
+
+`ingest` writes Parquet under `_data/` and HTML under `_reports/`. Re-run `bobframes render .` any
+time to rebuild the HTML from existing Parquet without re-replaying captures.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `ingest [root] [--area X] [--label Y] [--capture N] [--force] [--pixel-grid 4] [--render-only]` | Full pipeline: export, parse, replay, parquetize, derive, manifest, commit, catalog, render. |
+| `render [root] [--area X] [--label Y] [--accent OKLCH] [--accent-data OKLCH] [--watch]` | Rebuild HTML and catalog from existing Parquet. `--accent`/`--accent-data` re-hue the theme for this render (ADR-45). `--watch` re-renders on `design_tokens.toml`, chrome, or `.bobframes.toml` edits (alpha). |
+| `ab [root] --baseline-label X --compare-label Y` | All reports for one drop pair under `_reports/ab/<pair>/`. |
+| `report [root] <name>` | Build one named report (summary, draws-by-class, trend, instancing, pass-gpu, shader, overdraw, dashboard). `summary` is the exec build-health one-pager. |
+| `catalog [root]` | Rebuild `_data/_catalog.parquet` only. |
+| `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. |
+| `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`. |
+| `smoke [--data DIR]` | End-to-end check; render-only against the bundled fixture when `--data` is omitted. |
+| `version` | Print `bobframes`, schema, and pyarrow versions. |
+
+`<root>` is positional and defaults to `.`. Flags are long-form only. Exit codes: `0` success,
+`1` pipeline or build failure, `2` usage error, `3` external tool missing, `4` interrupted.
+
+## Sharing a report
+
+`bobframes package <root>` turns a rendered tree into two friendly artifacts beside it (it only READS
+`<root>`):
+
+- `<project>-<rundate>-report.zip` -- the full explorable tree. **Extract the whole folder before
+  opening** (`index.html`, then the Build Health Summary): the pages link each other and a shared
+  `_assets/` folder by relative path, so opening one file straight out of the zip breaks those links.
+- `<project>-<rundate>-summary.html` -- a standalone, self-contained one-pager. Email it, double-click
+  it, or `Ctrl-P -> Save as PDF`; no unzip needed. (Its deep links into the reports only resolve when
+  the zip is shipped alongside.)
+
+The zip DEFAULTS to **shared assets**: the ~95 KB of chrome (font + CSS + JS) lives once in `_assets/`
+and every page links it, so a multi-run bundle is markedly smaller. Because the pages share that
+folder, **no single page is portable on its own** -- keep the extracted folder together, or send the
+standalone `summary.html` when you need just one file. `--inline` opts out and makes each page
+self-contained (larger, but any single report file is portable). `--light` bundles only `index.html`
++ the top-level reports (no drill pages or data) for a quick "read, don't drill" share.
+
+### Sharing externally -- `--redact`
+
+`bobframes package <root> --redact` produces a bundle safe to hand to someone outside your team. It
+scrubs the GPU / driver / CPU / OS + capture-tool versions from every page's device strip (replaced with
+`redacted`), drops the raw provenance sidecars (`_manifest.json`, `frame_metadata.jsonl`) from the
+bundle, and replaces absolute Windows paths (`C:\...`) with `<path redacted>` across the pages and the
+downloadable CSVs. Redaction re-renders the tree, so `--inline --redact` is no longer a fast copy.
+
+- `--redact-paths=strip` (default) -- replace the path tokens; the bundle stays usable on a real capture.
+- `--redact-paths=fail` -- a CI completeness check: exit nonzero (don't write the zip) if any absolute
+  path remains in a rendered page, so a leak fails the build.
+
+**Caveat:** the pages and the downloadable CSVs are sanitized, but the **binary `.parquet`** tables still
+contain resource paths (they can't be string-edited safely) -- strip `_data/` if the parquet itself must
+leave your team. UNC (`\\host\share`) and forward-slash (`C:/...`) paths are not auto-stripped.
+
+## Customizing reports
+
+The look is shadcn-clean, neutral, and flat by default. Two ways to re-color it:
+
+### Pip installs -- re-hue without editing source (recommended)
+
+`pip install bobframes` puts the design tokens in site-packages, where edits are lost on upgrade -- so
+re-hue the accent / status / chart colors through the config cascade instead:
+
+- **Persistent:** add a `[theme]` section to `.bobframes.toml` in your capture root (or
+  `%APPDATA%/bobframes/config.toml`). `bobframes export-tokens --theme-template` prints a ready-to-paste
+  starter with just the overridable color knobs.
+- **One-shot:** `bobframes render . --accent '<oklch>'` (and `--accent-data '<oklch>'`) -- the top
+  precedence tier (CLI > env > config > bundled default). `bobframes preview --accent '<oklch>'` previews
+  it with no capture data.
+
+Only color hues (accent, the four status colors, the draw-class + chart palette) are overridable; layout,
+spacing, type, and the table engine stay bundled, so an override can never desync the rendering. A bad or
+non-color value warns and is ignored. `--watch` live-reloads on `.bobframes.toml` edits too.
+
+### Source checkouts -- edit the bundled tokens
+
+The full palette lives in `bobframes/reports/design_tokens.toml` (colors, spacing, type, motion, radius,
+and base layout sizes). The CSS variable name is fixed by its key: `surface_0` becomes `--surface-0`,
+`accent_primary` becomes `--accent-primary`.
+
+```
+bobframes preview                 # writes _reports/_chrome_preview.html (every component, no data)
+# edit a value in design_tokens.toml
+bobframes preview                 # under a second; reload the page in a browser
+bobframes render C:\captures      # apply the change to real reports from existing Parquet
+```
+
+`bobframes render --watch` re-runs render-only whenever `design_tokens.toml`, a chrome module, or
+`.bobframes.toml` changes (alpha; a 500ms poll, no extra dependency). `bobframes export-tokens --format
+css` prints the live `:root` block; `--format json` the nested table; `--format toml` the file itself.
+
+## External tools
+
+The export stage runs `renderdoccmd convert`; the replay stage runs `qrenderdoc --python`. bobframes
+resolves both from (in order) a config file (`.bobframes.toml`), version-globbed Arm Performance Studio
+install paths, and `PATH`. Install RenderDoc / Arm Performance Studio anywhere on those, or point a
+config entry at it. Run `bobframes check` to see what was resolved.
+
+## Output layout
+
+```
+<root>/
+  index.html                          root catalog view
+  <area>/<drop>/                      raw RDC inputs (left untouched)
+  _data/                              pipeline outputs
+    _catalog.parquet (+ .csv, .json)
+    _global_entities.parquet (+ .csv)
+    _query_examples.md
+    <area>/<drop>/                    per-drop data (29 Parquet tables)
+      *.parquet (+ matching .csv)
+      _manifest.json, _resource_labels.json
+      shader_src/*.glsl, jsonl sidecars
+      done.marker
+  _reports/                           rendered HTML
+    *.html (dashboard + reports)
+    ab/<pair>/*.html
+    drill/<area>/<drop>/index.html    per-drop browser
+    _cache/
+```
+
+The catalog stores each drop's path relative to `<root>` for portability.
+
+## Migrating from `_analysis`
+
+v1 is a hard rename of the older project-embedded `_analysis` package, with no compatibility shim:
+`python -m _analysis.*` stops working once `bobframes` is installed. Map old invocations to new ones:
+
+| Old (`_analysis`) | New (`bobframes`) |
+|---|---|
+| `python -m _analysis.run --root . --area X --label Y` | `bobframes ingest . --area X --label Y` |
+| `python -m _analysis.reports.ab --root . --baseline-label X --compare-label Y` | `bobframes ab . --baseline-label X --compare-label Y` |
+| `python -m _analysis.lint <file>` | `bobframes lint <file>` |
+| `python -m _analysis.tests.smoke` | `bobframes smoke` |
+
+## Troubleshooting
+
+| Symptom | Resolution |
+|---|---|
+| `renderdoccmd not found` (exit 3) | Install RenderDoc or Arm Performance Studio, or put the executable on `PATH`; confirm with `bobframes check`. |
+| `qrenderdoc` replay hangs | v1 kills the replay process tree on timeout and records `capture_status='replay_failed'` for that capture; the rest of the drop still completes. Re-run with `--force` to retry. |
+| Lint failure during render | The emitted HTML contains a banned token. Run `bobframes lint <file>` to see the line and label. |
+| `schema mismatch` (exit 1) | A drop's `_manifest.json` schema version differs from the installed schema. Rebuild it with `bobframes ingest --force` (the v1 schema-migration path; see G-3). |
+| Permission denied on `_data` | Close any viewer holding a Parquet open, then re-run; writes are staged and renamed atomically. |
+
+## Advanced
+
+- A/B reports: `bobframes ab . --baseline-label OLD --compare-label NEW` builds a side-by-side set.
+- Programmatic use: import `bobframes.schemas`, `bobframes.discovery`, and `bobframes.paths` to drive
+  table lookups, drop discovery, and path resolution from your own scripts.
+- `bobframes/probes/whatif.py` is a manual qrenderdoc-side probe and is not wired as a CLI command.
+- TOML config (`.bobframes.toml`), an externalized draw classifier, and design-token theming
+  (`[theme]` / `--accent`) shipped in v0.2.6. `bobframes package` produces shareable, optionally
+  redacted bundles (see [Sharing a report](#sharing-a-report)).
+
+## Built for Mayhem Studios
+
+BobFrames is built and maintained for **Mayhem Studios** -- it powers the studio's GPU
+capture-analysis and frame-performance work, and is open-sourced here for the wider RenderDoc and
+graphics community.
+
+If BobFrames helps your work, please **support Mayhem Studios** -- the studio that makes this tool
+possible. Follow the studio, play and wishlist our games, and tell a friend who fights frame times.
+A on the [GitHub repo](https://github.com/altpsyche/bobframes) helps too. Thank you.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

bobframes-0.2.6/bobframes/_default_config.toml

@@ -0,0 +1,61 @@
+# bobframes bundled default config (c07). Single source of truth for de-hardcoded literals.
+# Values here reproduce today's output byte-identically (ADR-6). A user .bobframes.toml is
+# deep-merged ON TOP of this (override one key without restating the rest — ADR-25).
+#
+# Regex / format-string values MUST be TOML *literal* (single-quoted) strings: a basic
+# (double-quoted) string interprets backslash escapes and breaks on \d. Do NOT "fix" a decode
+# error by double-escaping — that silently changes the pattern (ADR-23 trap).
+
+schema_version = 1
+
+[tools]
+# renderdoccmd = "..."   # unset by default; resolve_tool falls through to PATH / known paths
+# qrenderdoc   = "..."
+
+[pipeline]
+replay_timeout_s  = 600.0    # H-12 — per-capture qrenderdoc replay budget (seconds)
+convert_timeout_s = 120.0    # H-13 — per-file renderdoccmd convert budget (seconds)
+# workers / pixel_grid / keep_stage are §6 keys but NOT wired in c07 (argparse remains the
+# source; workers default is min(4, os.cpu_count()), so wiring it would change behavior).
+
+[discovery]
+dated_re = '^(\d{4}-\d{2}-\d{2})(?:_(.*))?$'    # H-30 — dated drop-folder pattern
+
+[formatting]
+id_short_n         = 12                          # H-23 — id/hash truncation length
+text_trunc_max     = 60                          # H-23 — mid/left text truncation length
+chrome_scrub_chars = '[—–…“”‘’→←↑↓×·]'           # H-16 — chars scrubbed from rendered chrome
+
+[delta]
+fmt               = '{:+,.0f}'                   # H-22 — default signed delta format
+bar_label_min_pct = 8.0                          # H-21 — min segment % to draw an inline label
+
+[scoring.complexity]                             # H-17 / Q-3 — shader complexity_score weights
+w_texture_samples = 2.0
+w_branches        = 0.5
+w_loops           = 2.0
+w_discards        = 0.3
+w_dfdx_dfdy       = 0.5
+w_mat4            = 0.3
+src_len_divisor   = 100.0
+src_len_cap       = 50.0
+
+[lint]
+# User-appended banned tokens, same shape as lint_banlist.toml [[banned]] entries:
+#   [[lint.extra_banned]]
+#   pattern = 'foo'
+#   label   = 'why'
+#   flags   = ['I']
+extra_banned = []
+
+[classifier]                # c09 — draw-classification preset (H-1..H-5)
+preset = "ue"               # draw_classifier.toml (UE default); "unity"/"godot"/... -> presets/<name>.toml
+# custom_path = "C:/path/to/my_engine.toml"   # absolute path to a custom preset (wins over `preset`)
+
+[report]                    # c16 — thresholds that drive report callout severity. Tune per project.
+shader_complexity_high    = 60.0   # fragment shaders at/above this complexity are flagged
+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
+max_prerendered_runs      = 10     # c16f — cap on pre-rendered older-run pages (run selector)

bobframes-0.2.6/bobframes/_version.py

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