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

bobframes 0.2.0tar.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 (397) hide show

bobframes-0.2.7/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,167 @@
+# 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.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
+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.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.7/PKG-INFO ADDED Viewed

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: bobframes
+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
+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.7/README.md ADDED Viewed

@@ -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.0 → bobframes-0.2.7}/bobframes/_default_config.toml RENAMED Viewed

@@ -56,6 +56,10 @@ preset = "ue"               # draw_classifier.toml (UE default); "unity"/"godot"
 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 to count as an instancing candidate
-gpu_regression_pct        = 10.0   # latest-vs-previous GPU increase % -> regression 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/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.0__tar.gz → 0.2.7__tar.gz

bobframes 0.2.0tar.gz → 0.2.7tar.gz