sdr-visualizer 0.6.0__tar.gz

sdr_visualizer-0.6.0/.gitignore

@@ -0,0 +1,73 @@
+# Local PM/planning artifacts (Superpowers brainstorms, plans, spikes)
+.superpowers/
+
+# Reference artifacts (kept in working directory, not tracked).
+# These are the spec inputs and the grader's render artifacts copied here
+# as references. The visualizer has its own templates under
+# src/sdr_visualizer/render/.
+/SPEC.md
+/SPEC-VISUALIZER.md
+/render.py
+/report.css
+/report.html.j2
+/sample-report.html
+/templated-report.html
+
+# macOS
+.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+MANIFEST
+
+# uv / virtualenvs
+.venv/
+venv/
+env/
+
+# Local tool state (Claude Code session state, Hypothesis example cache)
+.claude/
+.hypothesis/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+
+# Linters / type checkers
+.ruff_cache/
+.mypy_cache/
+.pyre/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Local-only generated artifacts
+/visualize-*.html
+/visualize-*.json
+
+# Generated fixtures (materialized on demand by conftest.py)
+/tests/fixtures/cja_snapshot_large.json
+/tests/fixtures/aa_snapshot_large.json
+/tests/fixtures/cja_snapshot_xl.json
+/tests/fixtures/cja_snapshot_small.json
+/tests/fixtures/cja_snapshot_medium.json
+
+# Environment
+.env
+.env.local

sdr_visualizer-0.6.0/CHANGELOG.md

@@ -0,0 +1,301 @@
+# Changelog
+
+All notable changes to `sdr-visualizer` will be documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.6.0] - 2026-07-17
+
+### Added
+
+- Property-based fuzz suite (`tests/test_adapter_fuzz.py`, ported from
+  sdr-grader and extended): random and mutated-fixture inputs must produce
+  a valid report or `InvalidSnapshotError` — never a bare crash — through
+  the adapters AND the render path, including the NaN/Infinity payload
+  class.
+- Browser functional tests now run on webkit as well as Chromium in CI;
+  performance budgets remain Chromium-only by design.
+- `scripts/corpus_check.py`: sweep a private directory tree of real
+  snapshots through the full build, asserting adapter acceptance, payload
+  serializability, embedded-payload parseability, and (optionally) the
+  §6 size budget per tier. A clean corpus sweep becomes the 1.0.0 gate;
+  swept clean ahead of this release over the local real corpus
+  (108 snapshots, budget checks included).
+- Contributor hygiene: `CONTRIBUTING.md`, PR and issue templates, and
+  `SECURITY.md` with private reporting via GitHub security advisories.
+- The example reports can be published via GitHub Pages (`pages.yml`;
+  deploys are manual until Pages is enabled for the repo). The README's
+  catalog screenshot and live-example links are held back until the site
+  is live — the README is also the PyPI page, where they cannot resolve
+  yet; `docs/screenshot-catalog.png` ships in the repo meanwhile.
+- Dependabot keeps the SHA-pinned GitHub Actions and the Python
+  dependencies current (weekly, grouped into one PR per ecosystem).
+
+### Changed
+
+- Releases now publish to PyPI via trusted publishing (OIDC, `pypi`
+  environment) as a hard step — a publish failure fails the release.
+  Release assets no longer include the stray `default.gitignore` file.
+- README install instructions point at PyPI again (0.6.0 is the first
+  published release); installing from the repo remains the development
+  path.
+- CI pins `astral-sh/setup-uv` by commit SHA at v8.3.2 (previously the
+  mutable `v3` tag) and sets `prune-cache: false`, so cached pre-built
+  wheels are no longer stripped and re-downloaded from PyPI on every
+  run. The release build job now uses the cache too.
+
+### Fixed
+
+- The AA and CJA adapters no longer crash with a bare `TypeError`/`ValueError`
+  on a malformed optional field (found by the new fuzz suite). A truthy
+  non-list `tags` or `*_references` value degrades to an empty list; a
+  present-but-unconvertible `nesting_depth` or `complexity_score` now raises
+  `InvalidSnapshotError` (so a single snapshot exits 3 and the trend loader
+  skips such a snapshot) instead of a bare exception. These files are
+  vendored from sdr-grader, which already carried equivalent type guards —
+  the visualizer had drifted behind, and nothing is owed to the sibling repo.
+- The sdist is now built from an explicit file allowlist
+  (`[tool.hatch.build.targets.sdist]`). Hatchling's default includes every
+  non-gitignored file in the project directory — tracked or not — which
+  swept local tool state (a Claude Code lock file, the Hypothesis example
+  cache) and repo-meta content (the example HTML pages, the README
+  screenshot, `uv.lock`, `CLAUDE.md`) into the tarball. The wheel was
+  always restricted to `src/sdr_visualizer` and is unaffected, and no sdist
+  was ever published (PyPI publishing starts with 0.6.0). `.claude/` and
+  `.hypothesis/` are gitignored as a second layer of defense.
+
+## [0.5.0] - 2026-07-12
+
+### Added
+
+- **Trend mode.** `--trend` on a snapshot directory adds a Trend view:
+  server-rendered sparkline charts of descriptive aggregates (total and
+  per-type component counts, orphans, components without a description,
+  reference edge count) across the directory's snapshots, plus a change log
+  with one expandable row per adjacent snapshot pair (added / removed /
+  modified component ids, computed with the 0.4.0 diff engine). The window
+  honors `--at` as its end and is capped at the 60 most recent parseable
+  snapshots with a build warning. Unparseable snapshots and snapshots with an
+  unconvertible scalar field are skipped with warnings. A directory that mixes
+  platforms exits 3 unless `--platform cja|aa` selects one, and a directory
+  that mixes data views / report suites exits 3, so unrelated inventories are
+  never diffed (mirroring `--compare-to`, which refuses both). Fewer than 2
+  usable snapshots exits 3, as does combining `--trend` with `--compare-to`,
+  `--dataview`, `--rsid`, a file path, or stdin. (SPEC §13, trend mode)
+- **`--allow-instance-mismatch`.** Opt-in flag that lets `--compare-to` and
+  `--trend` span different data views / report suites on purpose (for example
+  staging versus prod drift); the run proceeds with a warning instead of
+  exiting 3. Platform mismatches are always rejected.
+
+### Changed
+
+- **`--compare-to` now refuses an instance mismatch.** Comparing snapshots
+  from different data views / report suites exits 3 instead of warning and
+  proceeding (0.4.0 behavior), matching `--trend`; both views require a single
+  implementation so the diff never spans unrelated inventories. Pass
+  `--allow-instance-mismatch` to restore the cross-instance comparison on
+  demand.
+
+### Fixed
+
+- **Cross-command flag consistency.** `--at` now resolves a `--compare-to`
+  baseline directory the same way it resolves the primary directory (it was
+  silently ignored for the baseline, which always used the latest snapshot).
+  A directory mixing timestamped and un-timestamped snapshots now warns about
+  the dropped un-timestamped files in single-snapshot and `--compare-to`
+  selection, matching `--trend`. `--platform` combined with `--dataview` /
+  `--rsid` is ignored with a warning instead of forcing a mismatched adapter.
+
+## [0.4.0] - 2026-07-11
+
+### Added
+
+- **Comparative view.** `--compare-to BASELINE` (a snapshot file, or a
+  directory that resolves to its latest snapshot) adds a Changes view to the
+  report: components added, removed, and modified against the baseline, with
+  field-level before/after detail. The diff is computed at build time and
+  embedded as the payload's `changes` section — the baseline snapshot itself
+  is never embedded, so the report grows only with the size of the diff.
+  A platform mismatch between the two snapshots exits 3; differing instance
+  ids warn but proceed. (SPEC §13, comparative view)
+
+## [0.3.0] - 2026-07-11
+
+### Changed
+
+- **Graph view warm-up no longer freezes on huge graphs.** The synchronous
+  warm-up that pre-settles the force simulation now runs until near-settled
+  or a 150 ms budget elapses, whichever comes first (it ran a fixed 60–120
+  ticks before — ~0.8 s blocked at 2,000 nodes, ~2.2 s at 5,000). Graphs
+  that can't settle in budget finish asynchronously, one tick per frame.
+  The simulation also uses a coarser Barnes-Hut theta and faster alpha
+  decay (~30% cheaper ticks) above 1,000 nodes — §6's interactive ceiling —
+  or above a lower `--max-graph-nodes` opt-in threshold, whichever is
+  smaller.
+- **Graph hover/filter repaints coalesced to one pass per frame.** Filter
+  state is recomputed only when a filter input changes; hover and filter
+  paints apply all node/link classes in a single pass per selection and are
+  batched through `requestAnimationFrame`. Sweeping the pointer across a
+  5,000-node graph previously cost up to ~3.6 ms per mouseover/mouseout
+  event in full selection walks. The graph search box is now debounced
+  (120 ms), matching the catalog search. The hover/filter contract is now
+  explicit: hover fading wins while active, search-match highlights persist
+  through hover (now honored visually too — the fade previously dimmed the
+  highlight ring), and any filter or search change cancels an active hover
+  and repaints on the next frame. (Also fixes a pre-existing bug where a
+  hovered node's edge highlights could linger after mouseout.)
+
+### Added
+
+- `THIRD_PARTY_LICENSES` with the D3 v7.9.0 ISC license notice — D3 is
+  redistributed in the repo, in built packages (wheel `dist-info/licenses/`,
+  sdist), and inlined into every generated report. `pyproject.toml` now uses
+  the SPDX `license` string + `license-files` so both files ship in
+  distributions.
+- **Shareable URL state.** Catalog search, type/description/references/modified
+  filters, sort, the active view, and the open detail panel are reflected in
+  `location.hash` — copy the URL to share a filtered view ("every undocumented
+  metric"). Restored on load. (SPEC §14 Q1)
+- **Radial layout for small graphs.** Implementations with fewer than 20
+  components skip the force simulation and place nodes evenly on a circle —
+  force-directed layouts look chaotic at that size. Drag and reset still work.
+  (SPEC §14 Q2)
+- CI browser gate now also asserts entering the graph view blocks the main
+  thread < 700 ms (`scripts/perf_browser_check.py`) — script time plus a
+  forced style/layout flush of the inserted SVG — timing the worst-case
+  "Render anyway" path on both large fixtures (and failing if that path
+  stops being exercised); plus browser-level functional tests for hover
+  neighbor-highlighting, graph search fade/highlight, and filter-cancels-
+  hover behavior.
+- Perf gate now enforces the SPEC §6 100- and 500-component tiers (build
+  time + HTML size) via generated small fixtures, and the browser gate
+  covers the AA path and asserts per-tier budgets (1,000-component budgets
+  on the large fixtures, 2,000-component on XL).
+
+### Fixed
+
+- Canonical Adobe segment roots (`{"func": "segment", "container": {...}}`)
+  parse into a full anatomy tree instead of collapsing to one empty
+  segment reference.
+- Snapshots containing `NaN`/`Infinity` exit 3 with a clear message instead
+  of emitting a report whose payload the browser cannot parse (exit 0).
+- Usage errors exit 3, not argparse's default 2 (SPEC §7 forbids 2), and
+  unwritable `--output`/`--json` paths exit 1 with a clean message instead
+  of a traceback.
+- AA segment `nesting_depth` counts container nesting; it previously
+  reported raw JSON depth (a single-container segment claimed depth 4).
+- Explicit JSON `null` reference keys in CJA snapshots parse as empty
+  instead of crashing.
+- `--at` accepts full ISO-8601 (offsets, fractional seconds) and warns when
+  passed with non-directory input modes, where it never applied.
+- Date cells display the timestamp's date prefix — Safari showed raw
+  strings and Chrome could drift a day against the modified filter.
+- A shared URL with every type filter unchecked restores as unchecked.
+- AA calc-metric formula summaries render nested formulas readably instead
+  of leaking Python dict syntax; classifications without a name or id no
+  longer add blank tag chips.
+- Duplicate component ids in a snapshot print a build warning (anatomy
+  trees for duplicated ids are last-writer-wins).
+- Shell-out output decodes as UTF-8 regardless of host locale.
+
+### Security
+
+- The embedded JSON payload now escapes `<` as the JSON unicode escape `\u003c` (transparent to `JSON.parse`). Previously a snapshot
+  field containing `</script>` (e.g. a hostile component description) could
+  terminate the data block and inject live markup into the generated HTML.
+- Jinja autoescaping now applies to all templates (`autoescape=True`).
+  `select_autoescape(["html"])` never matched `index.html.j2` (final
+  extension `.j2`, not `.html`), so template-interpolated values — the
+  document title and instance name — rendered unescaped: a hostile Data
+  View name could inject live markup into the page. Same class of stored
+  XSS as the payload escape above; both shipped in the same fix pass.
+
+## [0.2.0] - 2026-06-10
+
+Performance and scaling release. The embedded payload contract changed (see
+Removed) — per the stability policy this bumps the leftmost non-zero version.
+
+### Added
+
+- `modified_ts` (epoch ms) on every catalog entry — the client sorts and
+  date-windows without constructing `Date` objects in hot paths.
+- Browser-side performance gate (`scripts/perf_browser_check.py`, Playwright):
+  initial render + filter latency budgets now enforced in CI alongside the
+  existing build-time/size gate.
+- 2,000-component budget tier gated in CI via a generated XL fixture
+  (`scripts/generate_large_fixture.py --scale 1.67`).
+- Catalog row cap: above 1,000 matching rows the table truncates with a
+  "Showing 1,000 of N · Show all" escape hatch.
+- Graph label culling (graphs over 200 nodes label only the top-60 in-degree nodes by default; all labels
+  past 1.4× zoom or on hover) and warm-started force simulation (near-settled
+  first paint).
+
+### Changed
+
+- Client builds the search index and sort keys in one pass at load; row HTML
+  is cached per entry; the master list stays pre-sorted; search input is
+  debounced (120 ms). Net: filter latency stays flat into the thousands of
+  components.
+- Graph hover/filter passes use precomputed neighbor counts.
+
+### Removed (breaking, embedded payload + `--json` shape)
+
+- `catalog_index` — the client builds its own search blob at load.
+- `graph.nodes`, `graph.in_degree`, `graph.out_degree` — derivable from
+  catalog entries; only `graph.edges` ships.
+- `platform_specific` on component entries — never consumed by the client;
+  consult the original snapshot for platform extras.
+- Null/empty fields on entries (sparse encoding) — consumers must treat a
+  missing key as null/empty.
+
+Net payload reduction: ~40% at the 1,200-component tier.
+
+## [0.1.0] - 2026-05-09
+
+First releasable cut. Feature-complete per [`SPEC-VISUALIZER.md`](SPEC-VISUALIZER.md) §10 phases 0–10. Surface (CLI flags, `--json` payload shape, exit codes, embedded payload schema) is documented but not yet hardened against real-world implementations — expect changes between 0.x releases as feedback comes in.
+
+### Added
+
+- **Catalog view (primary).** Searchable, filterable, sortable table of every component (metric / dimension / derived field / segment / calculated metric). Click a row to slide out a detail panel with description, properties, references, and anatomy.
+- **Reference graph view.** D3 force-directed layout with per-type color coding, in-degree-proportional node sizing, hover-to-highlight neighbors, drag-to-pin, pan + zoom, and graceful degradation above the 1,000-node threshold (configurable via `--max-graph-nodes`).
+- **Segment anatomy.** Reached from a segment's detail panel. Renders the segment definition tree as nested containers with subtle alpha-stacked shading per nesting depth, color-coded AND/OR/NOT operators, and clickable inline references to other segments.
+- **Calculated-metric anatomy.** Reached from a calc metric's detail panel. Renders the formula as a tree of operations and operands; metric refs are clickable.
+- **CJA + AA adapters.** Vendored from `sdr-grader` v1.0 per SPEC §15. Handle missing-description normalization, segment depth + container-context extraction, calc-metric formula parsing across both shapes (CJA `col1`/`col2`, AA `args`), classifications-as-tags for AA.
+- **Four input modes.** File path, snapshot directory (with `--at TIMESTAMP`), shell-out to `cja_auto_sdr` / `aa_auto_sdr`, stdin.
+- **CLI flags.** `--platform`, `--output`, `--json`, `--title`, `--exclude-orphans`, `--max-graph-nodes`, `--at`, `--quiet`, `--version`. Exit codes 0 / 1 / 3 per SPEC §7.
+- **Single-file output.** All CSS, JS (vanilla + D3 v7), and JSON payload inlined. No fetches, no CDNs, no external resources.
+- **Performance gate.** `scripts/perf_check.py` enforces SPEC §6 budgets (build time + HTML size) for both CJA and AA at the 1,000-component class. Wired into CI.
+- **Documentation.** [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), [`docs/PERFORMANCE.md`](docs/PERFORMANCE.md), [`docs/ADAPTER_GUIDE.md`](docs/ADAPTER_GUIDE.md), [`docs/EMBEDDED_DATA_FORMAT.md`](docs/EMBEDDED_DATA_FORMAT.md).
+
+### Stability
+
+The following surfaces are intended to be SemVer-stable from 0.1 onwards (breaking changes will bump the leftmost non-zero version):
+
+- CLI flag names and behavior
+- Exit codes
+- The embedded JSON payload's documented top-level keys (per `docs/EMBEDDED_DATA_FORMAT.md`)
+- The `--json` output shape
+
+The following are explicitly internal and may change without notice:
+
+- Template HTML structure / class names / IDs
+- CSS selectors
+- Module layout under `sdr_visualizer.*` (use the CLI or import from `sdr_visualizer.core.visualizer` only)
+
+### Known limitations
+
+- Not yet validated against real customer `cja_auto_sdr` / `aa_auto_sdr` output beyond the vendored grader fixtures. *(Since resolved: validated against real cja_auto_sdr / aa_auto_sdr output.)*
+- No browser-side performance gate yet (Python build time + HTML size are gated; client-side render and filter latency aren't). *(Resolved in 0.2.0 by scripts/perf_browser_check.py.)*
+- The PyPI publish step in `release.yml` is `continue-on-error: true` until trusted-publisher is configured at pypi.org. *(Resolved in 0.6.0: publishing moved to a hard, gated publish job — a failure fails the release.)*
+
+### Deferred to later releases (per SPEC §13)
+
+- Comparative view, two snapshots side-by-side (v0.2) *(Shipped in 0.4.0.)*
+- Trend mode against a directory of snapshots (v0.3) *(Shipping in 0.5.0.)*
+- Workspace project visualization (v0.4)
+- Schema map view (v0.5)
+
+[0.6.0]: https://github.com/brian-a-au/sdr-visualizer/releases/tag/v0.6.0
+[0.5.0]: https://github.com/brian-a-au/sdr-visualizer/releases/tag/v0.5.0
+[0.4.0]: https://github.com/brian-a-au/sdr-visualizer/releases/tag/v0.4.0
+[0.3.0]: https://github.com/brian-a-au/sdr-visualizer/releases/tag/v0.3.0
+[0.2.0]: https://github.com/brian-a-au/sdr-visualizer/releases/tag/v0.2.0
+[0.1.0]: https://github.com/brian-a-au/sdr-visualizer/releases/tag/v0.1.0

sdr_visualizer-0.6.0/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to sdr-visualizer
+
+Thanks for your interest. This project has a deliberately tight scope and a
+few non-negotiable architectural rules; reading this first will save you a
+review round-trip.
+
+## The rules of the road
+
+These are settled decisions (see the spec history), not open questions:
+
+- **Static output, dynamic interaction.** The tool emits one self-contained
+  HTML file: embedded JSON, embedded CSS, embedded JS. No fetches, no CDNs,
+  no server, no build step for the consumer.
+- **Server-side build, client-side render.** Analysis work happens in
+  Python, where seconds are fine. The client reads, filters, and renders
+  against a millisecond budget.
+- **Vanilla JS.** D3 for the reference graph only. No frameworks, no new
+  JS dependencies.
+- **Descriptive, not evaluative.** The visualizer reports what an
+  implementation contains and how it changed — never whether that is good
+  or bad. Grading belongs in the sibling project,
+  [sdr-grader](https://github.com/brian-a-au/sdr-grader).
+- **Performance budgets are CI-gated.** `docs/PERFORMANCE.md` documents
+  them. A change that blows a budget fails CI regardless of its merits.
+- **Exit codes are 0 / 1 / 3.** 0 success, 1 runtime error, 3 invalid
+  input. Code 2 is never used.
+
+## The vendoring relationship
+
+`src/sdr_visualizer/adapters/*` and `src/sdr_visualizer/input/{loader,detect,shell_out}.py`
+are vendored from sdr-grader, and the `core/models.py` shapes are shared.
+Any behavioral change to those files must be mirrored to the sibling repo in
+the same cycle — a PR that changes them should say how the parity obligation
+is being met. `input/series.py` is visualizer-only and exempt.
+
+## Developing
+
+```bash
+uv sync --dev --group browser    # environment
+uv run playwright install chromium webkit
+uv run pytest                    # tests (includes browser tests)
+uv run ruff check                # lint
+uv run ruff format               # format (the repo is format-clean)
+uv run python scripts/perf_check.py           # build/size budgets
+uv run python scripts/perf_browser_check.py   # browser budgets
+```
+
+Every PR needs: tests for behavior changes, a green suite, clean
+`ruff check` and `ruff format --check`, and green perf gates when the
+change could plausibly affect them.
+
+## Releases (maintainer notes)
+
+The release commit bumps `pyproject.toml`, `src/sdr_visualizer/__init__.py`,
+and `uv.lock` together, dates the CHANGELOG's Unreleased section, and adds
+the version's link definition at the bottom of the file. Tag the release
+commit itself — never a commit whose message contains `[skip ci]` (the
+examples auto-commits), because GitHub skips all workflows for such a tag.
+Do not commit locally generated `examples/*.html`; CI regenerates them.

sdr_visualizer-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Au
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sdr_visualizer-0.6.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: sdr-visualizer
+Version: 0.6.0
+Summary: Static-output visual catalog generator for Adobe Customer Journey Analytics and Adobe Analytics implementations.
+Project-URL: Homepage, https://github.com/brian-a-au/sdr-visualizer
+Project-URL: Issues, https://github.com/brian-a-au/sdr-visualizer/issues
+Author: Brian Au
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_LICENSES
+Requires-Python: >=3.11
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# sdr-visualizer
+
+[![Tests](https://github.com/brian-a-au/sdr-visualizer/actions/workflows/test.yml/badge.svg)](https://github.com/brian-a-au/sdr-visualizer/actions/workflows/test.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Static-output visual catalog generator for Adobe Customer Journey Analytics (CJA) and Adobe Analytics (AA) implementations. Consumes JSON snapshots from [`cja_auto_sdr`](https://github.com/brian-a-au/cja_auto_sdr) and [`aa_auto_sdr`](https://github.com/brian-a-au/aa_auto_sdr) and produces a single self-contained HTML file with:
+
+- A searchable, filterable component catalog (the primary view)
+- An interactive force-directed reference graph
+- Per-segment anatomy diagrams that make deeply-nested segments legible
+- Per-calculated-metric formula trees with click-through to referenced metrics
+
+The output is one HTML file: no server, no build step on the consumer side, no CDN dependencies. Everything is built into that one file. The component data is stored as JSON, the styling as CSS, and the interactive code as JavaScript, all inside it. You open it by double-clicking it in any modern web browser, and it works without an internet connection. There are no network requests, so no data is sent anywhere, and you can open it safely inside a locked-down corporate environment. You can move it, rename it, or copy it anywhere, and it still opens the same way. Drop it on a wiki, email it to a stakeholder, screenshot it into a deck.
+
+## Install
+
+```bash
+uv tool install sdr-visualizer
+```
+
+Or with pip:
+
+```bash
+pip install sdr-visualizer
+```
+
+(Requires 0.6.0 or later on PyPI.) For development, run from a clone:
+
+```bash
+git clone https://github.com/brian-a-au/sdr-visualizer
+cd sdr-visualizer
+uv sync
+uv run sdr-visualizer --help
+```
+
+## Quickstart
+
+```bash
+# Mode 1: from a snapshot file
+sdr-visualizer path/to/snapshot.json
+
+# Mode 2: from a directory of snapshots (uses the most recent)
+sdr-visualizer path/to/snapshots/
+
+# Mode 3: shell out to the upstream tool
+sdr-visualizer --dataview dv_prod_web        # CJA
+sdr-visualizer --rsid prod_us                # AA
+
+# Mode 4: stdin
+cja_auto_sdr dv_prod_web --format json --output - | sdr-visualizer -
+
+# Compare against an earlier snapshot: adds a Changes view to the report
+sdr-visualizer snapshot_new.json --compare-to snapshot_old.json
+
+# Chart evolution across a directory of snapshots: adds a Trend view
+sdr-visualizer ./snapshots/ --trend
+```
+
+The output lands at `./visualize-{instance_id}-{timestamp}.html` by default. Open it in a browser — that's the whole experience.
+
+## Useful flags
+
+| Flag | What it does |
+|---|---|
+| `--output PATH`           | Write HTML somewhere specific. |
+| `--json PATH`             | Also emit the embedded payload as a separate JSON file (useful for downstream tooling). |
+| `--title TEXT`            | Override the document title. |
+| `--exclude-orphans`       | Default the catalog's references filter to "Referenced" — hides components nothing depends on. |
+| `--max-graph-nodes N`     | Override the 1,000-node graph-rendering threshold. |
+| `--platform cja\|aa`      | Override platform auto-detection. |
+| `--at TIMESTAMP`          | When path is a directory, pick the snapshot closest to (and not after) this timestamp. |
+| `--quiet`                 | Suppress informational stderr output. |
+
+## What's in the output
+
+Open the generated HTML and you'll see four views, accessible from the top-level navigation:
+
+1. **Catalog** — a searchable, filterable, sortable table of every component. Click a row to slide out a detail panel with description, properties, references, and anatomy.
+2. **Reference graph** — a force-directed view of every component and the edges between them; small implementations (under 20 components) use a static radial layout instead. Hover dims unrelated nodes; click opens the same detail panel; drag pins; pan/zoom.
+3. **Segment anatomy** (contextual) — opens from a segment's detail panel. Renders the segment's definition tree as nested containers with subtle alpha-stacked shading per nesting level, color-coded AND/OR/NOT chips, and clickable inline references to other segments.
+4. **Calculated metric anatomy** (contextual) — opens from a calc metric's detail panel. Renders the formula as a tree of operations and operands; metric refs are clickable.
+
+With `--compare-to`, a fifth **Changes** view appears, listing components
+added, removed, and modified relative to a baseline snapshot, with
+field-level before/after detail.
+
+With `--trend` on a snapshot directory, a **Trend** view appears: sparkline
+charts of descriptive aggregates (component counts, orphans, undocumented
+components, reference edges) across the directory's snapshots, plus a
+per-interval change log. The window is capped at the 60 most recent
+snapshots.
+
+A trend directory must hold snapshots of a single implementation. If it mixes
+CJA and AA snapshots, pass `--platform cja|aa` to select one (or point at a
+single-platform directory); without it the run stops rather than guess. If it
+mixes data views or report suites, the run stops as well. This mirrors
+`--compare-to`, which refuses both a platform and an instance mismatch, so
+neither view ever diffs unrelated inventories. To compare or chart across
+different data views or report suites on purpose (for example staging versus
+prod drift), pass `--allow-instance-mismatch`; the run then proceeds with a
+warning. Platform mismatches are always rejected. The report shown alongside
+the trend is the newest usable snapshot in the directory.
+
+- **Shareable links** — the catalog's filters, sort, view, and open detail panel are encoded in the URL hash; copy the address bar to share a filtered view.
+
+## Performance budget
+
+The output is CI-gated against the budgets in [`docs/PERFORMANCE.md`](docs/PERFORMANCE.md).
+Build time and HTML size are enforced at every §6 tier (100 / 500 / 1,000 / 2,000
+components). Browser-measured budgets are enforced at the 1,000-component tier
+(initial render < 1s, filter/search < 150ms) and the 2,000-component tier
+(< 2s, < 300ms), plus a 700ms cap on the graph view's main-thread block.
+
+## Develop
+
+Requires Python 3.11+ and [uv](https://github.com/astral-sh/uv).
+
+```bash
+uv sync                # Set up environment
+uv run pytest          # Run tests (auto-generates the large fixture on first run)
+uv run ruff check      # Lint
+uv run ruff format     # Auto-format
+
+uv run python scripts/generate_examples.py   # Regenerate examples/
+uv run python scripts/perf_check.py          # Run the perf gate
+```
+
+## See also
+
+- [`sdr-grader`](https://github.com/brian-a-au/sdr-grader) — deterministic, rule-based linter for the same input format.
+- [`cja_auto_sdr`](https://github.com/brian-a-au/cja_auto_sdr) — generates CJA snapshots.
+- [`aa_auto_sdr`](https://github.com/brian-a-au/aa_auto_sdr) — generates AA snapshots.
+
+## Documentation
+
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — module layout, one-way data flow, design principles.
+- [`docs/ADAPTER_GUIDE.md`](docs/ADAPTER_GUIDE.md) — how the CJA and AA adapters work, and how to add a new platform.
+- [`docs/PERFORMANCE.md`](docs/PERFORMANCE.md) — performance budgets and how they're enforced.
+- [`docs/EMBEDDED_DATA_FORMAT.md`](docs/EMBEDDED_DATA_FORMAT.md) — the JSON payload format embedded in the HTML output.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE). The output bundles [D3](https://d3js.org) v7,
+vendored under the ISC license; see
+[`THIRD_PARTY_LICENSES`](THIRD_PARTY_LICENSES) for the full notice.