coeftable 0.5.0__tar.gz → 0.7.0__tar.gz

{coeftable-0.5.0 → coeftable-0.7.0}/.github/workflows/ci.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches: [main]
   pull_request:
-    branches: [main]
 
 jobs:
   prek:

{coeftable-0.5.0 → coeftable-0.7.0}/.gitignore

@@ -20,3 +20,4 @@ src/coeftable/_version.py
 docs/superpowers/
 # local feature worktrees
 /.worktrees/
+.superpowers/

coeftable-0.7.0/AGENTS.md

@@ -0,0 +1,8 @@
+# Agent guidelines
+
+## Changelog
+
+Never edit `CHANGELOG.md`. It is generated by release automation:
+`.github/workflows/post-release.yml` runs the `changelog-from-release` action
+against it, from release notes built out of merged PR titles and categorized by
+`.github/release.yml`. Describe changes in the PR description instead.

{coeftable-0.5.0 → coeftable-0.7.0}/CHANGELOG.md

@@ -1,3 +1,42 @@
+<a id="v0.6.0"></a>
+# [v0.6.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.6.0) - 2026-08-27
+
+<!-- Release notes generated using configuration in .github/release.yml at v0.6.0 -->
+
+## What's Changed
+### New Features
+* Add coeftable.plots public facade for SVG plot primitives by [@kylejcaron](https://github.com/kylejcaron) in [#35](https://github.com/kylejcaron/coeftable/pull/35)
+* Add typed card adornment vocabulary and HTML rendering by [@kylejcaron](https://github.com/kylejcaron) in [#36](https://github.com/kylejcaron/coeftable/pull/36)
+* Add exact card measurement engine (chrome geometry) by [@kylejcaron](https://github.com/kylejcaron) in [#37](https://github.com/kylejcaron/coeftable/pull/37)
+* Add trend, interval, metric, diagnostics and event card regions by [@kylejcaron](https://github.com/kylejcaron) in [#38](https://github.com/kylejcaron/coeftable/pull/38)
+* Add public Card and CardGrid entry points by [@kylejcaron](https://github.com/kylejcaron) in [#39](https://github.com/kylejcaron/coeftable/pull/39)
+* Add the panel composition layer by [@kylejcaron](https://github.com/kylejcaron) in [#40](https://github.com/kylejcaron/coeftable/pull/40)
+* Add the metric tree / driver-tree graph builder by [@kylejcaron](https://github.com/kylejcaron) in [#41](https://github.com/kylejcaron/coeftable/pull/41)
+### Maintenance
+* Update changelog for v0.5.0 by [@github-actions](https://github.com/github-actions)[bot] in [#34](https://github.com/kylejcaron/coeftable/pull/34)
+
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/compare/v0.5.0...v0.6.0
+
+[Changes][v0.6.0]
+
+
+<a id="v0.5.0"></a>
+# [v0.5.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.5.0) - 2026-08-19
+
+<!-- Release notes generated using configuration in .github/release.yml at v0.5.0 -->
+
+## What's Changed
+### Maintenance
+* Update changelog for v0.4.0 by [@github-actions](https://github.com/github-actions)[bot] in [#32](https://github.com/kylejcaron/coeftable/pull/32)
+* feat: forest plot outlier handling. robust autoscale + margin-fade clipping by [@kylejcaron](https://github.com/kylejcaron) in [#33](https://github.com/kylejcaron/coeftable/pull/33)
+
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/compare/v0.4.0...v0.5.0
+
+[Changes][v0.5.0]
+
+
 <a id="v0.4.0"></a>
 # [v0.4.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.4.0) - 2026-08-14
 
@@ -108,6 +147,8 @@
 [Changes][v0.1.0]
 
 
+[v0.6.0]: https://github.com/kylejcaron/coeftable/compare/v0.5.0...v0.6.0
+[v0.5.0]: https://github.com/kylejcaron/coeftable/compare/v0.4.0...v0.5.0
 [v0.4.0]: https://github.com/kylejcaron/coeftable/compare/v0.3.1...v0.4.0
 [v0.3.1]: https://github.com/kylejcaron/coeftable/compare/v0.3.0...v0.3.1
 [v0.3.0]: https://github.com/kylejcaron/coeftable/compare/v0.2.1...v0.3.0

{coeftable-0.5.0 → coeftable-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coeftable
-Version: 0.5.0
+Version: 0.7.0
 Summary: Publication-quality summary tables for estimates with uncertainty.
 Project-URL: Homepage, https://github.com/kylejcaron/coeftable
 Project-URL: Repository, https://github.com/kylejcaron/coeftable
@@ -470,6 +470,296 @@ absolute = pl.DataFrame(
 )
 ```
 
+## Standalone plots
+
+The inline SVG plots that power `.forest(...)` and `.sparkline(...)` columns
+are available directly from `coeftable.plots` — the same emitters, the same
+themes, no table required. Each function returns a complete `<svg>` string
+for embedding anywhere HTML goes:
+
+```python
+from coeftable.plots import forest_bar, sparkline_bar
+from coeftable.theme import DEFAULT
+import coeftable as ct
+
+bar = forest_bar(
+    1.2, 0.4, 2.0,            # estimate, lower, upper
+    domain=(-1.0, 3.0),
+    ref=0.0,
+    color=DEFAULT.favorable,
+    theme=DEFAULT,
+)
+
+line = sparkline_bar(
+    [0.0, 1.0, 2.0],          # x
+    [1.0, 1.5, 2.0],          # y
+    [0.5, 1.0, 1.6],          # lower
+    [1.5, 2.0, 2.4],          # upper
+    x_domain=(0.0, 2.0),
+    domain=(0.0, 3.0),
+    ref=0.0,
+    color=DEFAULT.favorable,
+    fmt=ct.Number(),
+    theme=DEFAULT,
+)
+```
+
+Also exported: `sparkline_multi` + `Trace` for overlaid series,
+`forest_axis` / `sparkline_axis` for the shared axis footer under a column
+of plots, and `ResolvedRule` / `ResolvedBand` for reference lines and
+shaded intervals via each function's `annotations=` parameter. Because a
+standalone plot and a table column share one `Theme`, a report that mixes
+both stays visually consistent.
+
+## Metric cards (experimental)
+
+`coeftable.cards` composes the standalone plots into measured, foldable
+metric cards — the same formatters, themes, and SVG primitives as the
+tables. The API is experimental and may change; it is deliberately not
+exported from the top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.cards import Card, CardGrid
+from coeftable.cards.regions import Diagnostics, Event, Events, Metric, Trend
+
+events = Events([Event("launch", "#4C72B0", at=2.0)])
+revenue = Card(
+    "Revenue",
+    subtitle="weekly lift vs control",
+    content=[
+        Metric(3.4, ct.Percent(signed=True), ci=(1.2, 5.7), ref=0.0),
+        Trend(
+            x=(0, 1, 2, 3), y=(0.3, 0.8, 1.1, 1.5),
+            lower=(-0.1, 0.3, 0.6, 0.9), upper=(0.7, 1.3, 1.6, 2.1),
+            x_domain=(0, 3), domain=(-0.5, 2.5), ref=0.0,
+            annotations=events.rules(),
+        ),
+        Diagnostics("diagnostics", [("n", 412), ("sigma", 0.8)]),
+        events,
+    ],
+)
+grid = CardGrid([revenue, revenue.with_theme(ct.theme.BLUE)])
+```
+
+A `Card` (or `CardGrid`) left as the last notebook expression renders
+itself; `as_raw_html()` is the string entry point. Cards are fixed-width
+with exact measured heights and fold via a native `<details>` header (the
+headline value stays visible as a chip when it fits beside the header,
+and is omitted otherwise). A standalone card collapses to
+its header; inside a `CardGrid` each card's expanded footprint stays
+reserved, so folding never reflows neighbors.
+
+## Metric panels (experimental)
+
+`coeftable.cards` panels put named side-by-side panes in one bordered shell
+with a shared header and footer: the compositional step above cards. The API
+is experimental and may change; it is deliberately not exported from the
+top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.cards import Metric, Pane, Panel, Row, TextBlock
+
+summary = Pane(
+    "Summary",
+    content=(
+        TextBlock("Weekly revenue", variant="subtitle"),
+        Metric(3.4, ct.Percent(signed=True), ci=(1.2, 5.7), ref=0.0),
+    ),
+    width=220,
+)
+segments = Pane(
+    "Segments",
+    content=(
+        Row(
+            (
+                (TextBlock("Enterprise"), 85),
+                (Metric(8.1, ct.Percent(signed=True)), 105),
+            )
+        ),
+    ),
+    width=200,
+)
+header = Row(
+    (
+        (TextBlock("Revenue", variant="title"), 320),
+        (Metric(3.4, ct.Percent(signed=True)), 120),
+    ),
+    gap=16,
+)
+panel = Panel((summary, segments), header=(header,))
+html = panel.as_raw_html()
+```
+
+Panes declare usable content widths; cell widths are author inputs; the panel
+derives its own footprint with exact measurement, not responsive guessing.
+
+A `Panel` left as the last notebook expression renders itself via
+`_repr_html_`; `with_theme()` returns the same composition under another
+theme.
+
+## Metric trees (experimental)
+
+`coeftable.graph` turns metric cards wired into a driver DAG into a metric
+tree: the graph layer adds slotted layout, vertical wires, and zero-JS
+fold/downstream-hide behavior. The API is experimental and may change; it is
+deliberately not exported from the top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.cards import Card
+from coeftable.graph import MetricTree
+
+tree = MetricTree(
+    nodes=(
+        ("revenue", Card("Revenue")),
+        ("price", Card("Price")),
+        ("volume", Card("Volume")),
+        ("retention", Card("Retention")),
+    ),
+    edges=(
+        ("revenue", "price", 1.2),
+        ("revenue", "volume", 2.1),
+        ("volume", "retention", -0.6),
+    ),
+    fmt=ct.Number(suffix=' pp', decimals=1, signed=True, thousands=False),
+    dom_prefix='drivers',
+)
+html = tree.as_raw_html()
+```
+
+Use a distinct `dom_prefix` for each tree when rendering multiple graphs in one
+document, so their generated control, card, and wire ids remain disjoint.
+
+Each card retains its native `<details>` fold control. The nub under a parent
+hides a node only when every root path to it is blocked: collapsing one parent
+of a shared child leaves that child visible via the other path, all with pure
+CSS and no JavaScript.
+
+A `MetricTree` left as the last notebook expression renders itself via
+`_repr_html_`; `with_theme()` follows the same conventions as cards.
+
+## Driver-tree reports (experimental)
+
+`coeftable.graph.DriverTree` is the composition root over the metric-tree
+layer: give it level series and a decomposition per parent, and it builds the
+cards, wires, and layout itself, plus three opt-in honesty checks a hand-built
+`MetricTree` graph would otherwise have to redo per node. The API is
+experimental and may change; it is deliberately not exported from the
+top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.graph import DriverTree
+from coeftable.graph.breakout import Breakout
+from coeftable.graph.timeline import TimelineEvent
+
+x = (0.0, 1.0, 2.0, 3.0)
+series = {
+    "revenue": (1000.0, 1071.0, 1144.0, 1219.0),
+    "users": (100.0, 105.0, 110.0, 115.0),
+    "aov": (10.0, 10.2, 10.4, 10.6),
+    "us": (600.0, 640.0, 680.0, 720.0),
+    "eu": (400.0, 431.0, 464.0, 499.0),
+}
+titles = {"revenue": "Revenue", "users": "Users", "aov": "AOV", "us": "US", "eu": "EU"}
+breakouts = {
+    "revenue": (
+        Breakout(key="drivers", label="by drivers", op="x", children=("users", "aov")),
+        Breakout(key="region", label="by region", op="+", children=("us", "eu")),
+    )
+}
+events = (TimelineEvent(at=1.0, label="Launch", color="#4C72B0", affects=("revenue", "users")),)
+
+report = DriverTree(
+    series,
+    titles,
+    breakouts,
+    ct.Percent(decimals=1),
+    x,
+    events=events,
+    level_fmt=ct.Number(decimals=1),
+)
+html = report.as_raw_html()
+```
+
+Every node id in `series` and `titles` is derived from `breakouts`: each key
+is a parent, and each `Breakout` names one decomposition of it (an `op="x"`
+product or an `op="+"` sum) plus the child node ids it contributes. A parent
+with two or more breakouts (like `revenue` above) renders a native
+`<select>` that swaps its children's whole subtree in place — no JavaScript,
+because the alternatives share one slotted position and pure CSS shows
+exactly one of them at a time.
+
+Each decomposition is checked against its own arithmetic: a parent that
+should equal the sum or product of its children but falls short gets an
+injected `"Unattributed"` residual card (additive shortfalls) or a reported
+gap badge (multiplicative shortfalls, which have no subtraction fix), and a
+decomposition explaining under 80% of its parent refuses to build rather than
+render a misleading tree. Every wire's label role comes from its own child's
+noise-aware confidence interval, so a wobbly delta renders muted with a
+`· ns` marker instead of a confident color. Anti-correlated siblings (movers
+that trade off against each other week to week) surface a callout hosted on
+one of the participating children, so it stays visible only alongside that
+alternative rather than the parent, which stays visible under every switch.
+The root card renders no text of its own; pass `caption=` to add one. It
+wraps to fit the card using an estimated character width, growing across
+as many lines as that estimate needs. Runs of whitespace collapse to a
+single space and line breaks are not preserved, and unusually wide text
+can still be clipped on a line, since the wrap is an estimate rather than
+a font measurement. A literal `{weeks}` placeholder is substituted for the
+observed period count, and `caption` defaults to `None`, so nothing
+renders unless you ask for it.
+If you want a note that edge labels are accounting, not causal
+claims, that wording is yours to choose — for example
+`caption="Edge labels are an accounting of the realized {weeks}-week
+change, not causal impact."` `events` fan out to every card named in their
+`affects` tuple, both as sparkline markers and as captions, and the
+report's header is a timeline strip indexing them across the whole canvas.
+That strip carries no heading of its own — pass `strip_title=` if you want
+one, since only you know whether your events are deploys, holidays, or
+experiments. With neither events nor a `strip_title` there is nothing to
+index and no heading to show, so the strip is omitted rather than reserving
+space for a bare axis; supplying either one brings it back.
+
+**Switchers can nest.** Every level of the tree may carry its own switcher at
+the same time — revenue by drivers or region, and within drivers, active users
+by funnel or country, and within that, sessions by platform or channel.
+Switching an outer choice takes away the whole branch beneath it, including any
+nested switcher and its alternatives; switching back restores it with the inner
+selection intact, because a native `<select>` keeps its value while hidden.
+
+**Limitations.** All alternatives of one switcher must have the same number of
+children, since they share the same positions.
+
+And every card must keep a visible parent under every combination of choices. A
+card that disappears together with its own alternative is fine — that is the
+point of a switcher. What is refused is a card whose visibility depends on
+several switchers that do not subsume one another, so that some combination of
+selections leaves it on the page with every route to it closed.
+
+Nesting satisfies this on its own: an outer choice that removes a branch is
+decided by the outer rule alone, and everything below goes with it. Being
+reachable through more than one switcher is not by itself a problem either — if
+every option of each switcher reaches the card, or if any route to it is
+unconditional, it always keeps a parent and the tree is accepted.
+
+One shape is refused: a card where *every* route can be independently closed and
+none survives unconditionally. The clearest example is a card reachable through a
+nested branch and also through a different alternative of the switcher above it.
+Keep the outer branch that preserves the nested switcher, then pick an inner
+option that does not reach the card, and both of its routes close at once. Since
+each switcher's rules are emitted independently, no single one can see that. Such
+a tree is rejected at construction with a `SpecError` naming the card and every
+switcher implicated in it.
+
+`DriverTree` returns a `GraphReport`: the underlying `Graph`, and above it a
+measured, exact-width timeline strip whenever events or a `strip_title` call
+for one. `report.measure()`,
+`report.as_raw_html()`, and its `_repr_html_` notebook display all work the
+same way they do for a plain `Graph`.
+
 ## Plot annotations
 
 `ct.Rule` draws a line and `ct.Band` shades an interval in a forest plot or

{coeftable-0.5.0 → coeftable-0.7.0}/README.md

@@ -416,6 +416,296 @@ absolute = pl.DataFrame(
 )
 ```
 
+## Standalone plots
+
+The inline SVG plots that power `.forest(...)` and `.sparkline(...)` columns
+are available directly from `coeftable.plots` — the same emitters, the same
+themes, no table required. Each function returns a complete `<svg>` string
+for embedding anywhere HTML goes:
+
+```python
+from coeftable.plots import forest_bar, sparkline_bar
+from coeftable.theme import DEFAULT
+import coeftable as ct
+
+bar = forest_bar(
+    1.2, 0.4, 2.0,            # estimate, lower, upper
+    domain=(-1.0, 3.0),
+    ref=0.0,
+    color=DEFAULT.favorable,
+    theme=DEFAULT,
+)
+
+line = sparkline_bar(
+    [0.0, 1.0, 2.0],          # x
+    [1.0, 1.5, 2.0],          # y
+    [0.5, 1.0, 1.6],          # lower
+    [1.5, 2.0, 2.4],          # upper
+    x_domain=(0.0, 2.0),
+    domain=(0.0, 3.0),
+    ref=0.0,
+    color=DEFAULT.favorable,
+    fmt=ct.Number(),
+    theme=DEFAULT,
+)
+```
+
+Also exported: `sparkline_multi` + `Trace` for overlaid series,
+`forest_axis` / `sparkline_axis` for the shared axis footer under a column
+of plots, and `ResolvedRule` / `ResolvedBand` for reference lines and
+shaded intervals via each function's `annotations=` parameter. Because a
+standalone plot and a table column share one `Theme`, a report that mixes
+both stays visually consistent.
+
+## Metric cards (experimental)
+
+`coeftable.cards` composes the standalone plots into measured, foldable
+metric cards — the same formatters, themes, and SVG primitives as the
+tables. The API is experimental and may change; it is deliberately not
+exported from the top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.cards import Card, CardGrid
+from coeftable.cards.regions import Diagnostics, Event, Events, Metric, Trend
+
+events = Events([Event("launch", "#4C72B0", at=2.0)])
+revenue = Card(
+    "Revenue",
+    subtitle="weekly lift vs control",
+    content=[
+        Metric(3.4, ct.Percent(signed=True), ci=(1.2, 5.7), ref=0.0),
+        Trend(
+            x=(0, 1, 2, 3), y=(0.3, 0.8, 1.1, 1.5),
+            lower=(-0.1, 0.3, 0.6, 0.9), upper=(0.7, 1.3, 1.6, 2.1),
+            x_domain=(0, 3), domain=(-0.5, 2.5), ref=0.0,
+            annotations=events.rules(),
+        ),
+        Diagnostics("diagnostics", [("n", 412), ("sigma", 0.8)]),
+        events,
+    ],
+)
+grid = CardGrid([revenue, revenue.with_theme(ct.theme.BLUE)])
+```
+
+A `Card` (or `CardGrid`) left as the last notebook expression renders
+itself; `as_raw_html()` is the string entry point. Cards are fixed-width
+with exact measured heights and fold via a native `<details>` header (the
+headline value stays visible as a chip when it fits beside the header,
+and is omitted otherwise). A standalone card collapses to
+its header; inside a `CardGrid` each card's expanded footprint stays
+reserved, so folding never reflows neighbors.
+
+## Metric panels (experimental)
+
+`coeftable.cards` panels put named side-by-side panes in one bordered shell
+with a shared header and footer: the compositional step above cards. The API
+is experimental and may change; it is deliberately not exported from the
+top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.cards import Metric, Pane, Panel, Row, TextBlock
+
+summary = Pane(
+    "Summary",
+    content=(
+        TextBlock("Weekly revenue", variant="subtitle"),
+        Metric(3.4, ct.Percent(signed=True), ci=(1.2, 5.7), ref=0.0),
+    ),
+    width=220,
+)
+segments = Pane(
+    "Segments",
+    content=(
+        Row(
+            (
+                (TextBlock("Enterprise"), 85),
+                (Metric(8.1, ct.Percent(signed=True)), 105),
+            )
+        ),
+    ),
+    width=200,
+)
+header = Row(
+    (
+        (TextBlock("Revenue", variant="title"), 320),
+        (Metric(3.4, ct.Percent(signed=True)), 120),
+    ),
+    gap=16,
+)
+panel = Panel((summary, segments), header=(header,))
+html = panel.as_raw_html()
+```
+
+Panes declare usable content widths; cell widths are author inputs; the panel
+derives its own footprint with exact measurement, not responsive guessing.
+
+A `Panel` left as the last notebook expression renders itself via
+`_repr_html_`; `with_theme()` returns the same composition under another
+theme.
+
+## Metric trees (experimental)
+
+`coeftable.graph` turns metric cards wired into a driver DAG into a metric
+tree: the graph layer adds slotted layout, vertical wires, and zero-JS
+fold/downstream-hide behavior. The API is experimental and may change; it is
+deliberately not exported from the top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.cards import Card
+from coeftable.graph import MetricTree
+
+tree = MetricTree(
+    nodes=(
+        ("revenue", Card("Revenue")),
+        ("price", Card("Price")),
+        ("volume", Card("Volume")),
+        ("retention", Card("Retention")),
+    ),
+    edges=(
+        ("revenue", "price", 1.2),
+        ("revenue", "volume", 2.1),
+        ("volume", "retention", -0.6),
+    ),
+    fmt=ct.Number(suffix=' pp', decimals=1, signed=True, thousands=False),
+    dom_prefix='drivers',
+)
+html = tree.as_raw_html()
+```
+
+Use a distinct `dom_prefix` for each tree when rendering multiple graphs in one
+document, so their generated control, card, and wire ids remain disjoint.
+
+Each card retains its native `<details>` fold control. The nub under a parent
+hides a node only when every root path to it is blocked: collapsing one parent
+of a shared child leaves that child visible via the other path, all with pure
+CSS and no JavaScript.
+
+A `MetricTree` left as the last notebook expression renders itself via
+`_repr_html_`; `with_theme()` follows the same conventions as cards.
+
+## Driver-tree reports (experimental)
+
+`coeftable.graph.DriverTree` is the composition root over the metric-tree
+layer: give it level series and a decomposition per parent, and it builds the
+cards, wires, and layout itself, plus three opt-in honesty checks a hand-built
+`MetricTree` graph would otherwise have to redo per node. The API is
+experimental and may change; it is deliberately not exported from the
+top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.graph import DriverTree
+from coeftable.graph.breakout import Breakout
+from coeftable.graph.timeline import TimelineEvent
+
+x = (0.0, 1.0, 2.0, 3.0)
+series = {
+    "revenue": (1000.0, 1071.0, 1144.0, 1219.0),
+    "users": (100.0, 105.0, 110.0, 115.0),
+    "aov": (10.0, 10.2, 10.4, 10.6),
+    "us": (600.0, 640.0, 680.0, 720.0),
+    "eu": (400.0, 431.0, 464.0, 499.0),
+}
+titles = {"revenue": "Revenue", "users": "Users", "aov": "AOV", "us": "US", "eu": "EU"}
+breakouts = {
+    "revenue": (
+        Breakout(key="drivers", label="by drivers", op="x", children=("users", "aov")),
+        Breakout(key="region", label="by region", op="+", children=("us", "eu")),
+    )
+}
+events = (TimelineEvent(at=1.0, label="Launch", color="#4C72B0", affects=("revenue", "users")),)
+
+report = DriverTree(
+    series,
+    titles,
+    breakouts,
+    ct.Percent(decimals=1),
+    x,
+    events=events,
+    level_fmt=ct.Number(decimals=1),
+)
+html = report.as_raw_html()
+```
+
+Every node id in `series` and `titles` is derived from `breakouts`: each key
+is a parent, and each `Breakout` names one decomposition of it (an `op="x"`
+product or an `op="+"` sum) plus the child node ids it contributes. A parent
+with two or more breakouts (like `revenue` above) renders a native
+`<select>` that swaps its children's whole subtree in place — no JavaScript,
+because the alternatives share one slotted position and pure CSS shows
+exactly one of them at a time.
+
+Each decomposition is checked against its own arithmetic: a parent that
+should equal the sum or product of its children but falls short gets an
+injected `"Unattributed"` residual card (additive shortfalls) or a reported
+gap badge (multiplicative shortfalls, which have no subtraction fix), and a
+decomposition explaining under 80% of its parent refuses to build rather than
+render a misleading tree. Every wire's label role comes from its own child's
+noise-aware confidence interval, so a wobbly delta renders muted with a
+`· ns` marker instead of a confident color. Anti-correlated siblings (movers
+that trade off against each other week to week) surface a callout hosted on
+one of the participating children, so it stays visible only alongside that
+alternative rather than the parent, which stays visible under every switch.
+The root card renders no text of its own; pass `caption=` to add one. It
+wraps to fit the card using an estimated character width, growing across
+as many lines as that estimate needs. Runs of whitespace collapse to a
+single space and line breaks are not preserved, and unusually wide text
+can still be clipped on a line, since the wrap is an estimate rather than
+a font measurement. A literal `{weeks}` placeholder is substituted for the
+observed period count, and `caption` defaults to `None`, so nothing
+renders unless you ask for it.
+If you want a note that edge labels are accounting, not causal
+claims, that wording is yours to choose — for example
+`caption="Edge labels are an accounting of the realized {weeks}-week
+change, not causal impact."` `events` fan out to every card named in their
+`affects` tuple, both as sparkline markers and as captions, and the
+report's header is a timeline strip indexing them across the whole canvas.
+That strip carries no heading of its own — pass `strip_title=` if you want
+one, since only you know whether your events are deploys, holidays, or
+experiments. With neither events nor a `strip_title` there is nothing to
+index and no heading to show, so the strip is omitted rather than reserving
+space for a bare axis; supplying either one brings it back.
+
+**Switchers can nest.** Every level of the tree may carry its own switcher at
+the same time — revenue by drivers or region, and within drivers, active users
+by funnel or country, and within that, sessions by platform or channel.
+Switching an outer choice takes away the whole branch beneath it, including any
+nested switcher and its alternatives; switching back restores it with the inner
+selection intact, because a native `<select>` keeps its value while hidden.
+
+**Limitations.** All alternatives of one switcher must have the same number of
+children, since they share the same positions.
+
+And every card must keep a visible parent under every combination of choices. A
+card that disappears together with its own alternative is fine — that is the
+point of a switcher. What is refused is a card whose visibility depends on
+several switchers that do not subsume one another, so that some combination of
+selections leaves it on the page with every route to it closed.
+
+Nesting satisfies this on its own: an outer choice that removes a branch is
+decided by the outer rule alone, and everything below goes with it. Being
+reachable through more than one switcher is not by itself a problem either — if
+every option of each switcher reaches the card, or if any route to it is
+unconditional, it always keeps a parent and the tree is accepted.
+
+One shape is refused: a card where *every* route can be independently closed and
+none survives unconditionally. The clearest example is a card reachable through a
+nested branch and also through a different alternative of the switcher above it.
+Keep the outer branch that preserves the nested switcher, then pick an inner
+option that does not reach the card, and both of its routes close at once. Since
+each switcher's rules are emitted independently, no single one can see that. Such
+a tree is rejected at construction with a `SpecError` naming the card and every
+switcher implicated in it.
+
+`DriverTree` returns a `GraphReport`: the underlying `Graph`, and above it a
+measured, exact-width timeline strip whenever events or a `strip_title` call
+for one. `report.measure()`,
+`report.as_raw_html()`, and its `_repr_html_` notebook display all work the
+same way they do for a plain `Graph`.
+
 ## Plot annotations
 
 `ct.Rule` draws a line and `ct.Band` shades an interval in a forest plot or