semiotic 3.8.4 → 3.8.6

package/CLAUDE.md

@@ -4,7 +4,7 @@
 - Install: `npm install semiotic`
 <!-- semiotic-bundle-sizes:start -->
 <!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
-- **Use sub-path imports** — `semiotic/xy` (138KB gz), `semiotic/ordinal` (117KB gz), `semiotic/network` (123KB gz), `semiotic/geo` (97KB gz), `semiotic/realtime` (150KB gz), `semiotic/realtime/core` (145KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (190KB gz), `semiotic/server/node` (190KB gz), `semiotic/server/edge` (208KB gz), `semiotic/utils` (76KB gz), `semiotic/utils/core` (74KB gz), `semiotic/utils/react` (6KB gz), `semiotic/recipes` (77KB gz), `semiotic/recipes/core` (77KB gz), `semiotic/recipes/react` (2KB gz), `semiotic/themes` (7KB gz), `semiotic/themes/core` (7KB gz), `semiotic/themes/react` (6KB gz), `semiotic/data` (4KB gz), `semiotic/value` (8KB gz), `semiotic/physics` (133KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (432KB gz), `semiotic/ai/core` (70KB gz), `semiotic/controls` (12KB gz), `semiotic/rough` (4KB gz). Full `semiotic` is 349KB gz.
+- **Use sub-path imports** — `semiotic/xy` (143KB gz), `semiotic/ordinal` (119KB gz), `semiotic/network` (125KB gz), `semiotic/geo` (98KB gz), `semiotic/realtime` (152KB gz), `semiotic/realtime/core` (146KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (207KB gz), `semiotic/server/node` (207KB gz), `semiotic/server/edge` (226KB gz), `semiotic/utils` (83KB gz), `semiotic/utils/core` (81KB gz), `semiotic/utils/react` (6KB gz), `semiotic/recipes` (84KB gz), `semiotic/recipes/core` (83KB gz), `semiotic/recipes/react` (2KB gz), `semiotic/themes` (7KB gz), `semiotic/themes/core` (7KB gz), `semiotic/themes/react` (6KB gz), `semiotic/data` (4KB gz), `semiotic/value` (8KB gz), `semiotic/physics` (154KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (468KB gz), `semiotic/ai/core` (78KB gz), `semiotic/controls` (12KB gz), `semiotic/rough` (4KB gz). Full `semiotic` is 382KB gz.
 <!-- semiotic-bundle-sizes:end -->
 - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor|--audit-a11y]` · MCP: `npx semiotic-mcp`
 
@@ -21,8 +21,9 @@ HOC Charts (simple, default) → Stream Frames (full control). Use HOCs unless y
 ## XY Charts (`semiotic/xy`)
 
 **LineChart** — `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor`, `colorBy`, `colorScheme`, `curve`, `lineWidth` (2), `showPoints`, `pointRadius` (3), `fillArea` (boolean|string[]), `areaOpacity` (0.3), `lineGradient`, `anomaly`, `forecast`, `band` ({y0Accessor, y1Accessor, style?, perSeries?, interactive?} or array for fan charts; participates in yExtent; non-interactive by default), `directLabel`, `gapStrategy`, `xScaleType`/`yScaleType` ("linear"|"log"|"time"), `styleRules` (per-series), `tooltip="multi"` for hover-anywhere
-**AreaChart** — LineChart props + `areaBy`, `y0Accessor`, `gradientFill`, `areaOpacity` (0.7), `showLine` (true), `band`, `tooltip="multi"`
+**AreaChart** — LineChart props + `areaBy`, `y0Accessor`, `gradientFill`, `semanticGradient` (`{stops: [{offset: 0–1, color?, opacity?}]}`; offset follows the resolved y-domain), `semanticLine` (true with semanticGradient; false keeps the normal stroke/lineGradient), `areaOpacity` (0.7), `showLine` (true), `band`, `tooltip="multi"`
 **DifferenceChart** — Two-series A/B. Fills between with `seriesAColor` where A>B, `seriesBColor` where B>A; crossovers interpolated. `data`, `xAccessor`, `seriesAAccessor` ("a"), `seriesBAccessor` ("b"), `seriesALabel`/`seriesBLabel`, `seriesAColor` (var(--semiotic-danger))/`seriesBColor` (var(--semiotic-info)), `showLines` (true), `lineWidth` (1.5), `showPoints` (false), `pointRadius` (3), `curve` ("linear"), `areaOpacity` (0.6), `gradientFill`, `xExtent`/`yExtent`, `pointIdAccessor`, `windowSize`. Push via `ref.push({x,a,b})`. Accessor outputs coerce through `toNumber`.
+**BumpChart** — Ranking-over-x. Each x-column ranks series by `yAccessor`; rank is vertical position. `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy` ("series"), `rankDirection` ("descending"|"ascending"), `ribbon` (false — encode magnitude as true perpendicular-offset ribbon width instead of fixed-width lines; line↔ribbon share centerline geometry so `animate` tweens width only), `curve` ("smooth"|"linear"), `ribbonSizeRange` ([4,28]), `samplesPerSegment` (12), `lineWidth` (3), `highlightTop` (color only the N best series by mean rank; the rest share `neutralColor`), `neutralColor`, `styleRules` (per-series; resolve against each series' first observation), `showPoints`, `showLabels` (true|"start"|"end"|"both"), `hoverHighlight`, `annotations` (x may use original x values incl. `Date`). Wraps XYCustomChart.
 **StackedAreaChart** — flat array + `areaBy` (required), `colorBy`, `normalize`, `baseline` ("zero"|"wiggle" streamgraph|"silhouette" centered), `stackOrder` ("key"|"insideOut"|"asc"|"desc"). Streamgraph: `baseline="wiggle"` + `stackOrder="insideOut"`. `baseline` ⊥ `normalize`. No `lineBy`. `tooltip="multi"` interpolates between samples.
 **Scatterplot** — `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`, `sizeRange`, `symbolBy` (categorical field → glyph **shape**: each mark becomes a d3-shape glyph; size still tracks `sizeBy`/`pointRadius`), `symbolMap` ({category → shape}; unmapped auto-assign — pass it for legend-matchable shapes), `pointRadius` (5), `pointOpacity` (0.8), `marginalGraphics`, `styleRules` (per-point; `axis:"x"`/`"y"` thresholds), `regression` (boolean | "linear"|"polynomial"|"loess" | RegressionConfig — sugar for trend overlay)
 **BubbleChart** — Scatterplot + `sizeBy` (required), `sizeRange` ([5,40]), `regression`
@@ -36,7 +37,7 @@ HOC Charts (simple, default) → Stream Frames (full control). Use HOCs unless y
 
 ## Ordinal Charts (`semiotic/ordinal`)
 
-**BarChart** — `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40), `roundedTop`, `gradientFill` (true | {topOpacity, bottomOpacity} | {colorStops}; tip→base), `styleRules`, `regression`
+**BarChart** — `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40), `roundedTop`, `gradientFill` (`{stops: [{offset: 0–1, color?, opacity?}]}`; tip→base), `styleRules`, `regression`
 **StackedBarChart** — + `stackBy` (required), `normalize`, `sort` (false default — insertion order), `styleRules`
 **GroupedBarChart** — + `groupBy` (required), `barPadding` (60), `sort` (false default), `styleRules`
 **SwarmPlot** — `colorBy`, `sizeBy`, `symbolBy` (categorical field → glyph shape, like Scatterplot), `symbolMap`, `pointRadius`, `pointOpacity`
@@ -58,7 +59,7 @@ All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `sho
 
 ## Network Charts (`semiotic/network`)
 
-**ForceDirectedGraph** — `nodes`, `edges`, `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize`, `nodeSizeRange`, `edgeWidth`, `iterations` (300), `forceStrength` (0.1 — link-attraction multiplier), `layoutExecution` ("auto" default | "worker" | "sync" — auto runs big layouts in a Web Worker by estimated cost, sync fallback everywhere), `layoutLoadingContent` (ReactNode while worker layout pends; `false` suppresses), `onLayoutStateChange` (`"pending"|"ready"|"error"`), `showLabels`, `nodeLabel`, `styleRules` (style groups of nodes — rules see the raw node; `ctx.category` = colorBy group)
+**ForceDirectedGraph** — `nodes`, `edges`, `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize`, `nodeSizeRange`, `nodeStroke`/`nodeStrokeWidth` (node-only outline), `edgeWidth`, `edgeColor`/`edgeOpacity` (edge-only stroke), `iterations` (300), `forceStrength` (0.1 — link-attraction multiplier), `layoutExecution` ("auto" default | "worker" | "sync" — auto runs big layouts in a Web Worker by estimated cost, sync fallback everywhere), `layoutLoadingContent` (ReactNode while worker layout pends; `false` suppresses), `onLayoutStateChange` (`"pending"|"ready"|"error"`), `showLabels`, `nodeLabel`, `styleRules` (style groups of nodes — rules see the raw node; `ctx.category` = colorBy group). **Node vs edge stroking**: the generic `stroke`/`strokeWidth`/`opacity` style *all* marks uniformly; to stroke nodes and edges separately use node-only `nodeStroke`/`nodeStrokeWidth` (e.g. `nodeStroke="none"` drops the node ring) and edge-only `edgeColor`/`edgeWidth`/`edgeOpacity`. Precedence per property: specific > generic > built-in default.
 **SankeyDiagram** — `edges`, `nodes`, `valueAccessor`, `nodeIdAccessor`, `colorBy`, `edgeColorBy`, `orientation`, `nodeAlign`, `nodeWidth`, `nodePaddingRatio`, `showLabels`
 **ProcessSankey** — temporal sankey with real time x-axis. `nodes`, `edges` (each with `startTime`/`endTime`), `domain` (req `[t0, t1]`), `axisTicks?`, `xExtentAccessor` (optional `[start, end]` lifetime per node), `colorBy`/`colorScheme`/`showLegend`/`legendPosition`, `pairing` ("value"|"temporal"), `packing` ("off"|"reuse"), `laneOrder` ("crossing-min"|"inside-out"|"crossing-min+inside-out"|"insertion"), `lifetimeMode` ("full"|"half"), `ribbonLane` ("source"|"target"|"both"), `showLaneRails`, `showLabels` (true), `showQualityReadout`, `showParticles` + `particleStyle`, `timeFormat`/`valueFormat`, push API via ref. Static-graph cycles OK as long as edges move forward in time. Use ProcessSankey for time-stamped events; SankeyDiagram for static snapshots.
 **ChordDiagram** — `edges`, `nodes`, `valueAccessor`, `edgeColorBy`, `padAngle`, `showLabels`
@@ -92,6 +93,7 @@ Process/arrival/distribution charts backed by `StreamPhysicsFrame`. The settled
 **ProcessFlowChart** — multi-body workflow lane. `data`, `stages` (required: `[{id, label?, force?, damping?, capacity?, pressure?, portal?, absorb?, share?}]`), `stageAccessor` ("stage"), `idAccessor`, `groupBy` (optional feature key; completion when all members hit an absorb stage), `groupLabelAccessor`, `workAccessor`, `radiusAccessor`, `ballRadius` (6), `colorBy`, `groupCompletion` ("allAbsorbed"|"none"), `groupAnchorAlong` (0.55), `showProjection` (true), `showChrome` (true — processChrome kit), `liveCapacity` (true — FIFO queues at `unitsPerSecond`), `onCapacityChange` (queue depth / processed), `bodyLimit` (soft stream budget + oldest eviction), `bodyMark` ("circle"|"halo"|"faceted"|"pill"|"diamond"|"square" or per-row `datum.__physicsMark`), `selection`, `settle`, `seed`, `size`, `paused`, `frameProps`. Settled projection is stage occupancy + capacity badges; use for review queues / triage / merge pipelines. Prefer **GauntletChart** for one compound plan with timed gate effects.
 **Physics controllers** (`createCapacityQueueController`, `createPortalController`, `composePhysicsControllers`) — process plugins via `controllers`. Capacity `getSnapshot()` → queueDepth/processedCount; emit `physics-capacity-processed`. **processChrome** (`semiotic/physics` / `semiotic/recipes`) — stage bays, capacity badges, feature sockets (theme: `--semiotic-process-*`). `PhysicsCustomChart`: `layout()` may return `regionEffects`, `controllers`, `bodyForces`; `layoutConfig` hot path without re-enqueue. Guide: `/features/physics-process-guide`. Contracts: `PhysicsContracts.test.tsx`.
 **GauntletChart** — compound project core + tethered positive/negative property bodies + timed gate events. `positiveProperties`/`negativeProperties` (req), `gates`, `events`, `showChrome` (true), `showProjection` (true — viability/outcome strip), `showTethers` (true), `onStateChange`, `frameProps`. Bodies clamp inside walls (`clampGauntletPoint`). Not for multi-item factory floors (use ProcessFlowChart).
+**CrucibleChart** — bounded peer components undergo authored `phases` and `events`, form declared `products`, and settle into reason-labelled `outlets` with source lineage. The ledger/projection is authoritative; motion never infers classification, timing, membership, loss, or routing. `buildCrucibleProductEvents({productId, form, contributions?, complete})` is pure authoring sugar for `combine → contribute* → complete-product`; every source/relation id, event position, reason, and outlet remains caller-supplied. The ref handle's `replay()` atomically restarts the deterministic tape even mid-run (`reset()` restores-and-pauses; `rerunMS` repeats after settlement). `playbackRate` changes presentation only. No push/live-event API.
 **Pop (body-removal burst)** — every physics HOC ref is a `PhysicsFrameHandle` (extends the shared push handle) exposing **`popBodies(ids, options?)`** (`StreamPhysicsPopOptions` = `{ color?, durationMs?, radius? }`): removes the bodies and plays a burst — expanding ring + inner glow + radial sparks fading over `durationMs` (`drawPopAnimations`) — returning the removed ids. It reads as a *departure*, the physics/exit-emphasis counterpart to realtime **`pulse`**'s data-*arrival* glow (the same transient-emphasis metaphor on opposite ends of a datum's life). GauntletChart also fires it internally on gate-driven property removal; `/examples/nimby` (civic-value balloons) and `/examples/merge-pressure` (merge-risk traits) drive it that way.
 
 ## Value Charts (`semiotic/value`)
@@ -169,7 +171,9 @@ Layout signature differs by family:
 - **Decoration**: `linearAxis` (tick axis + gridlines from *any* scale — the bespoke-scale escape hatch `showAxes` can't cover), `legendSwatches` (portable SVG legend for `overlays` — fill/line/shape/hatch swatches; sibling to `legendGroupsFrom` which feeds `frameProps.legend`), `hatchFill` (`{def, fill}` SVG `<pattern>` for percentile/uncertainty bands — the SVG analogue of `createHatchPattern`).
 - **`unwrapDatum`** (`semiotic/recipes` + `semiotic/utils`): collapse the wrapped-vs-raw datum split — always the raw user object (handles both `.data` wrappers and `.datum` nesting). **The** unwrap path for `onObservation` handlers AND `frameProps.tooltipContent` renderers: call it once on the incoming value; never pre-unwrap the argument (`unwrapDatum(x?.data ?? x)` double-unwraps).
 
-`semiotic/recipes` ships pure layout functions (`waffleLayout`, `calendarLayout`, `marimekkoLayout`, `bulletLayout`, `parallelCoordinatesLayout`, `intervalLanesLayout`, `flextreeLayout`, `dagreLayout`, `lineageDagLayout`, `axisFixedForceLayout`, `packedClusterMatrix`, `isometricLandmarkLayout`, `forceLayout`, `arcLayout`, `adjacencyMatrix`, `circularLayout`). **Network-analysis kit** (`semiotic/recipes`, pure graph algorithms): `buildAdjacency`, `bfsDistances`, `shortestPath`, `egoNetwork`, `degree`/`betweenness`(Brandes)/`closeness`/`clustering` (+ `normalizeScores`), and `proximityProblem` — the "spatial problem" layout diagnostic that flags nodes drawn closer than their graph distance warrants. Pair with network charts to size by centrality, highlight an ego network on hover, trace a shortest path, or diagnose a misleading layout. `forceLayout(nodes, edges, {seed})` is a **seeded, deterministic** positioner returning normalized `{id:{x,y}}` for `NetworkCustomChart` (same seed ⇒ same layout; re-seed for a "re-run the layout" interaction); `forceLayoutAsync(nodes, edges, {execution?, workerThreshold?, signal?})` is its Promise sibling that runs large layouts in a short-lived module Web Worker (identical deterministic output; graceful sync fallback), and `useForceLayout(nodes, edges, options)` → `{positions, status, error}` is the React wrapper — SSR and first hydration stay synchronous for markup parity, client graph changes go async while previous positions stay visible, and settled positions are memoized by node/edge array identity + options so remounting the same module-constant graph is "ready" immediately (no loading flash). `arcLayout`/`adjacencyMatrix`/`circularLayout` (+ `orderByGroupDegree`, `arcPath`) are the classic physics-free network forms. `allocateCells` is the largest-remainder grid allocator behind `waffleLayout` (turn `{key, weight}[]` + a cell count into integer cells with no rounding drift; `minPerCategory` keeps small categories visible) — reusable for any feature-mix / proportional waffle. **`unitize(value, {unit, maxUnits?, minFraction?})` / `unitizeRange(value, rangeValue, opts)`** is the counting sibling: the pictogram/tally allocator (value → repeated unit signs with a fractional final sign — ISOTYPE: symbols repeat, they never grow). Returns `{units: [{index, fraction, start, end, value}], total, shown, overflow}` — `maxUnits` caps with an `overflow` flag, `minFraction` drops trailing slivers while `total` vs `shown` keeps the ledger honest; `unitizeRange` extends the tally to a projected/scenario endpoint (`rangeUnits` drawn hatched), sharing a mid-sign boundary exactly via `startFraction`. Feeds `glyph`-node `fraction`s directly (unit charts, sign stacks, arrow bundles; `allocateCells` divides fixed cells, `unitize` counts). **Tokenized reasoning helpers**: `generateTokens(input, tokenEncoding)` wraps `unitize` plus `actual`, `fixed-denominator`, `quantile`, `posterior-sample`/`sample`, and seeded `random-sample` strategies with explicit `tokenType` (`dot`/`icon`/`glyph`), `tokenSemantics` (`observed-unit`, `unitized-measure`, `risk-case`, `possible-outcome`, etc.), and `countStrategy`; `{ value, rangeValue }` yields `rangeTokens` for scenario/projection tallies. `layoutTokenGrid` places the resulting tokens for icon/glyph arrays; `normalizeTokenEncoding` keeps legacy `token`/`unit` aliases working while canonical configs use `icon`/`unitValue`; `diagnoseTokenEncoding`, `suggestTokenEncoding`, and `tokenTaskIntentToCapabilityIntents` expose IDID-style warnings, task-aware defaults, and a bridge to `suggestCharts` intents. Built-in token glyph names include `person`, `server`, `chip`, `bolt`, and `bus`. `intervalLanesLayout` (ordinal) packs concurrent `{start,end,lane}` records into stacked Gantt sub-tracks per lane with period bands + lane labels + a time axis — packing runs in rendered-pixel space and honors `minBarWidth` (2) so zero/short-duration events stay visible without overlapping same-track neighbors; `axisFixedForceLayout` (network) pins one axis from a field and settles the other (rect-aware collision). BYO heavy deps (`d3-flextree`, `dagre`) in user code. `packedClusterMatrix` (network) bins records into a column×row matrix of **densely-packed beeswarm clusters** (deterministic self-contained packing, geometry cached) and emits **multi-channel glyphs** — hue (`colorAccessor`/`colorMap`), size (`sizeAccessor`, area), shade (`shadeAccessor`, CIELAB lightness), plus EITHER shape-encoding (`symbolAccessor`/`symbolMap` — the base mark becomes that shape) OR the **composite-glyph** model (`iconAccessor`/`iconMap` — base is a filled circle, only mapped values get a stroked inner icon). `rowMode:"banded"` (default) gives aligned global orbit-bands (row labels align, one enclosure spans the columns per band, columns vary in height) vs `"stacked"` (per-column cell heights ∝ count). `callouts:[{field,value,label}]` draws leader lines to named marks. `cellSizing:"proportional"` makes area ∝ count. **Recipe decoration kit** (exported from `semiotic/recipes`, for any custom-layout's `overlays`): `roundedEnclosure`/`boundsOf` (group/band borders), `bandLabel` (overflow-aware axis/band labels), `markCallout` (leader-line callout to a mark), `readField` (`node.data`-wrapper reader), `groupBy`, `dimFor` (the highlight/dim opacity rule — `{predicate?, highlight?, baseOpacity?, dimOpacity?, brighten?}`; `matchesHighlight` is its `{field,value}[]` matcher), `signatureKey`/`LayoutCache` (content-signature geometry cache so re-styling never re-runs an expensive layout — key by *content*, never by `ctx.nodes` identity), `legendGroupsFrom` (`{colorMap|keys, symbolMap?, sizeStops?}` → `LegendGroup[]` for `frameProps.legend`), `shade`/`makeShade`, `symbolPathString`/`symbolRadius`/`symbolExtent`/`SYMBOL_SEQUENCE`, and the small numeric/color one-liners every layout re-declares — `clamp`, `mean`, `withAlpha`, `nonNegativeFinite` (hex→`rgba()` so a hover-dim can ride a recipe's `resolveColor` callback). (`bandLabel`/`dimFor` are adopted by marimekko/bullet/parallelCoordinates/packedClusterMatrix.) `lineageDagLayout` renders a pre-positioned **layered lineage/DAG** (reads logical layer/row coords, no re-layout) with composite node glyphs (one hit-rect per node + icon/label/store-chip decoration in `overlays`), level-of-detail collapse (full→compact→icon→dot), distinct dashed back-edges, and host-driven reach-dimming (`layoutConfig.reachableIds`) + selection (`layoutConfig.selectedId` / shared `ctx.selection`).
+**Word Trails** (`wordTrailsLayout`) is the quantitatively anchored word-cloud recipe: column = category, segment = ordered vertical position, weight = font size, with overlap-free stable placement. `wordColor`/`wordOpacity` receive `WordTrailsWordInfo`: canonical `word`/`column`/`weight`/`segment` plus the exact source `datum`, `dataIndex`, `columnIndex`, and `resolvedColumnColor`, so derived encodings do not need brittle compound-key lookup maps. Spread `wordTrailsProgressiveReveal({currentSegment, segmentDomain, oldestOpacity?, currentOpacity?, futureOpacity?, combineWeightOpacity?})` into `layoutConfig` for future hiding + linearly faded history without reflow; zero-opacity rows reserve geometry but emit no glyph or hit target. Analysis-derived color/distinctiveness remains a source-data field, not something the layout infers.
+
+`semiotic/recipes` ships pure layout functions (`waffleLayout`, `calendarLayout`, `marimekkoLayout`, `bulletLayout`, `parallelCoordinatesLayout`, `intervalLanesLayout`, `flextreeLayout`, `dagreLayout`, `lineageDagLayout`, `netEnsembleLayout`, `axisFixedForceLayout`, `packedClusterMatrix`, `isometricLandmarkLayout`, `forceLayout`, `arcLayout`, `adjacencyMatrix`, `circularLayout`). **Network-analysis kit** (`semiotic/recipes`, pure graph algorithms): `buildAdjacency`, `bfsDistances`, `shortestPath`, `egoNetwork`, `degree`/`betweenness`(Brandes)/`closeness`/`clustering` (+ `normalizeScores`), `analyzeNetEnsemble` (the headless net census — see `netEnsembleLayout` below), and `proximityProblem` — the "spatial problem" layout diagnostic that flags nodes drawn closer than their graph distance warrants. Pair with network charts to size by centrality, highlight an ego network on hover, trace a shortest path, or diagnose a misleading layout. `forceLayout(nodes, edges, {seed})` is a **seeded, deterministic** positioner returning normalized `{id:{x,y}}` for `NetworkCustomChart` (same seed ⇒ same layout; re-seed for a "re-run the layout" interaction); `forceLayoutAsync(nodes, edges, {execution?, workerThreshold?, signal?})` is its Promise sibling that runs large layouts in a short-lived module Web Worker (identical deterministic output; graceful sync fallback), and `useForceLayout(nodes, edges, options)` → `{positions, status, error}` is the React wrapper — SSR and first hydration stay synchronous for markup parity, client graph changes go async while previous positions stay visible, and settled positions are memoized by node/edge array identity + options so remounting the same module-constant graph is "ready" immediately (no loading flash). `arcLayout`/`adjacencyMatrix`/`circularLayout` (+ `orderByGroupDegree`, `arcPath`) are the classic physics-free network forms. `allocateCells` is the largest-remainder grid allocator behind `waffleLayout` (turn `{key, weight}[]` + a cell count into integer cells with no rounding drift; `minPerCategory` keeps small categories visible) — reusable for any feature-mix / proportional waffle. **`unitize(value, {unit, maxUnits?, minFraction?})` / `unitizeRange(value, rangeValue, opts)`** is the counting sibling: the pictogram/tally allocator (value → repeated unit signs with a fractional final sign — ISOTYPE: symbols repeat, they never grow). Returns `{units: [{index, fraction, start, end, value}], total, shown, overflow}` — `maxUnits` caps with an `overflow` flag, `minFraction` drops trailing slivers while `total` vs `shown` keeps the ledger honest; `unitizeRange` extends the tally to a projected/scenario endpoint (`rangeUnits` drawn hatched), sharing a mid-sign boundary exactly via `startFraction`. Feeds `glyph`-node `fraction`s directly (unit charts, sign stacks, arrow bundles; `allocateCells` divides fixed cells, `unitize` counts). **Tokenized reasoning helpers**: `generateTokens(input, tokenEncoding)` wraps `unitize` plus `actual`, `fixed-denominator`, `quantile`, `posterior-sample`/`sample`, and seeded `random-sample` strategies with explicit `tokenType` (`dot`/`icon`/`glyph`), `tokenSemantics` (`observed-unit`, `unitized-measure`, `risk-case`, `possible-outcome`, etc.), and `countStrategy`; `{ value, rangeValue }` yields `rangeTokens` for scenario/projection tallies. `layoutTokenGrid` places the resulting tokens for icon/glyph arrays; `normalizeTokenEncoding` keeps legacy `token`/`unit` aliases working while canonical configs use `icon`/`unitValue`; `diagnoseTokenEncoding`, `suggestTokenEncoding`, and `tokenTaskIntentToCapabilityIntents` expose IDID-style warnings, task-aware defaults, and a bridge to `suggestCharts` intents. Built-in token glyph names include `person`, `server`, `chip`, `bolt`, and `bus`. `intervalLanesLayout` (ordinal) packs concurrent `{start,end,lane}` records into stacked Gantt sub-tracks per lane with period bands + lane labels + a time axis — packing runs in rendered-pixel space and honors `minBarWidth` (2) so zero/short-duration events stay visible without overlapping same-track neighbors; `axisFixedForceLayout` (network) pins one axis from a field and settles the other (rect-aware collision). BYO heavy deps (`d3-flextree`, `dagre`) in user code. `packedClusterMatrix` (network) bins records into a column×row matrix of **densely-packed beeswarm clusters** (deterministic self-contained packing, geometry cached) and emits **multi-channel glyphs** — hue (`colorAccessor`/`colorMap`), size (`sizeAccessor`, area), shade (`shadeAccessor`, CIELAB lightness), plus EITHER shape-encoding (`symbolAccessor`/`symbolMap` — the base mark becomes that shape) OR the **composite-glyph** model (`iconAccessor`/`iconMap` — base is a filled circle, only mapped values get a stroked inner icon). `rowMode:"banded"` (default) gives aligned global orbit-bands (row labels align, one enclosure spans the columns per band, columns vary in height) vs `"stacked"` (per-column cell heights ∝ count). `callouts:[{field,value,label}]` draws leader lines to named marks. `cellSizing:"proportional"` makes area ∝ count. **Recipe decoration kit** (exported from `semiotic/recipes`, for any custom-layout's `overlays`): `roundedEnclosure`/`boundsOf` (group/band borders), `bandLabel` (overflow-aware axis/band labels), `markCallout` (leader-line callout to a mark), `readField` (`node.data`-wrapper reader), `groupBy`, `dimFor` (the highlight/dim opacity rule — `{predicate?, highlight?, baseOpacity?, dimOpacity?, brighten?}`; `matchesHighlight` is its `{field,value}[]` matcher), `signatureKey`/`LayoutCache` (content-signature geometry cache so re-styling never re-runs an expensive layout — key by *content*, never by `ctx.nodes` identity), `legendGroupsFrom` (`{colorMap|keys, symbolMap?, sizeStops?}` → `LegendGroup[]` for `frameProps.legend`), `shade`/`makeShade`, `symbolPathString`/`symbolRadius`/`symbolExtent`/`SYMBOL_SEQUENCE`, and the small numeric/color one-liners every layout re-declares — `clamp`, `mean`, `withAlpha`, `nonNegativeFinite` (hex→`rgba()` so a hover-dim can ride a recipe's `resolveColor` callback). (`bandLabel`/`dimFor` are adopted by marimekko/bullet/parallelCoordinates/packedClusterMatrix.) `lineageDagLayout` renders a pre-positioned **layered lineage/DAG** (reads logical layer/row coords, no re-layout) with composite node glyphs (one hit-rect per node + icon/label/store-chip decoration in `overlays`), level-of-detail collapse (full→compact→icon→dot), distinct dashed back-edges, and host-driven reach-dimming (`layoutConfig.reachableIds`) + selection (`layoutConfig.selectedId` / shared `ctx.selection`). `netEnsembleLayout` (network) is the complement — for **ensembles of disconnected/trivially-connected DAGs** (a "bag of little graphs" force layout scatters and dagre/flextree can't place). It splits into weakly-connected components, tests each for **directedness** (borrowing the mathematical *net*/directed-set idea: for a weakly-connected DAG, a single sink ⟹ everything converges to one limit; ≥2 sinks ⟹ it branches), fingerprints components with Weisfeiler–Leman refinement so **order-isomorphic motifs** group together, lays each out converging toward its sink(s) at the bottom, and arranges the ensemble as small multiples in motif bands (collapsing to one census glyph per component when cells get tiny). Config: `colorMode` (`"directedness"|"motif"|"category"`), `groupByMotif`, `sort`, `fingerprintRounds`, `minCellForFull`. `analyzeNetEnsemble(nodes, edges)` is the pure headless census (per-component `directed`/sink/source counts + motif classes) with no rendering. Demo + lay explanation at `/recipes/net-ensemble`.
 
 `tokenLayer({input, encoding, options})` is the high-level tokenized-rendering helper for custom layouts: it runs `generateTokens`, applies row/column/grid/waffle/dotplot/bar-segment/quantile-strip placement (or `positionToken` for scale/map-driven placement), and returns ordinary dot/symbol/glyph scene nodes with `pointId`/transition identity. Use it for ISOTYPE, icon arrays, risk grids, quantile dotplots, strips, and hybrid token overlays; pass `includeRange` to render `rangeTokens`; drop down to `generateTokens` when a bespoke layout only needs records.
 

package/README.md

@@ -16,17 +16,21 @@ AI coding assistants generate correct chart code on the first try.
 <img src="./docs/public/assets/img/semiotic-release-dashboard.svg" alt="Semiotic release dashboard showing chart count, bundle sizes, capability coverage, chart families, and documentation growth" width="100%">
 <!-- semiotic-readme-dashboard:end -->
 
-## What's New in 3.8.4
-
-3.8.4 closes the remaining server/browser render gaps and hardens the physics and network runtimes:
-
-- Static SVG and `renderChart` now match the browser for line+area fills, semantic gradients, line
-  bands, pie/donut start angles, swimlane extents, treemap `colorBy`, range candlesticks,
-  streamgraph baselines, and the LineChart series features—each guarded by parity tests.
-- Physics simulations settle and rerun reliably via quiescence-based `atRest` detection, and network
-  frames rebuild scenes without the duplicate builds that could flash during hydration.
-- New `layoutSequence` and `gridObservatory` recipes, a report-style Semiotic Standard example, and
-  lazy-loaded brush overlays that trim the entry graph.
+## What's New in 3.8.6
+
+3.8.6 adds a ranking chart and semantic-line area bands, then refines legend layout across the
+client and server renderers:
+
+- New `BumpChart` (`semiotic/xy`): ranks every series within each x-column and connects each
+  series' rank across columns. Set `ribbon` to encode the original magnitude as true
+  perpendicular-offset ribbon width instead of a fixed-width line — both modes share one
+  centerline, so the toggle animates as a pure width change.
+- `AreaChart` gains `semanticLine` (default on) for hard, value-banded color segments along the
+  area's top stroke, and `gradientFill`/`lineGradient`/`semanticGradient` now share one
+  `{ stops }` config (with `GradientConfig` and friends exported).
+- Legend layout gains `legendLayout.sideGutter` (space between a side legend and axis chrome) and
+  a `legendDistance` control, with content-measured side-legend widths and tightened defaults,
+  aligned across the client and SSR renderers.
 
 ```jsx
 import { LineChart } from "semiotic/xy"
@@ -56,6 +60,7 @@ correct visualizations without trial and error:
 - **`npx semiotic-mcp`** — an MCP server for tool-based chart rendering in any MCP client
 - **`npx semiotic-ai --doctor`** — validate component + props JSON from the command line with typo suggestions and anti-pattern detection
 - **`diagnoseConfig(component, props)`** — programmatic anti-pattern detector with actionable fixes, spanning validation, encoding, accessibility, and misleading-design (deception) checks
+- **`auditData(component, props, data?)`** — chart-aware numeric preflight for inputs that pass schema validation but break the math: non-finite values, zero-span domains, invalid log inputs, negative size geometry, unsafe normalized totals, and scale-dominating outliers. Returns bounded row evidence and flows into `diagnoseConfig`, Chart Clinic, CLI doctor, and opt-in `ChartContainer` notifications
 - **`CLAUDE.md`** — instruction files auto-synced for Claude, Cursor, Copilot, Windsurf, and Cline
 - **`llms.txt`** — machine-readable documentation following the emerging standard
 
@@ -72,8 +77,9 @@ diagrams, tree layouts, treemaps, circle packing, and orbit diagrams — all
 as React components with the same prop API as LineChart.
 
 **Streaming data.** Realtime charts render on canvas at 60fps with a
-ref-based push API. Built-in decay, pulse, and staleness encoding for
-monitoring dashboards.
+ref-based push API. Rapid network edge pushes coalesce into one layout per
+animation frame, while read/mutation methods preserve synchronous read-after-write
+semantics. Built-in decay, pulse, and staleness encoding for monitoring dashboards.
 
 **Coordinated views.** `LinkedCharts` provides hover cross-highlighting,
 brush cross-filtering, coordinate-based linked crosshairs, and selection
@@ -373,35 +379,35 @@ The numbers below are **first-party artifact cost**: the gzip size of Semiotic's
 
 | Entry Point | gzip | What's inside |
 |---|---|---|
-| `semiotic/xy` | **138 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
-| `semiotic/ordinal` | **117 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
-| `semiotic/network` | **123 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
-| `semiotic/geo` | **97 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
-| `semiotic/realtime` | **150 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
-| `semiotic/realtime/core` | **145 KB** | Streaming chart types, HOCs, and buffer helpers |
+| `semiotic/xy` | **143 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
+| `semiotic/ordinal` | **119 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
+| `semiotic/network` | **125 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
+| `semiotic/geo` | **98 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
+| `semiotic/realtime` | **152 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
+| `semiotic/realtime/core` | **146 KB** | Streaming chart types, HOCs, and buffer helpers |
 | `semiotic/realtime/react` | **1 KB** | Stream status and synced push hooks |
-| `semiotic/server` | **190 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
-| `semiotic/server/node` | **190 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
-| `semiotic/server/edge` | **208 KB** | renderChart, renderChartWithEvidence, renderToStaticSVG, renderDashboard |
-| `semiotic/utils` | **76 KB** | ThemeProvider, validators, serialization — no chart components |
-| `semiotic/utils/core` | **74 KB** | Theme helpers and serialization utilities |
+| `semiotic/server` | **207 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/server/node` | **207 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/server/edge` | **226 KB** | renderChart, renderChartWithEvidence, renderToStaticSVG, renderDashboard |
+| `semiotic/utils` | **83 KB** | ThemeProvider, numeric/accessibility audits, serialization — no chart components |
+| `semiotic/utils/core` | **81 KB** | Pure theme helpers, numeric/accessibility audits, and serialization |
 | `semiotic/utils/react` | **6 KB** | ThemeProvider, useTheme, useReducedMotion, useHighContrast, useStreamStatus |
-| `semiotic/recipes` | **77 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
-| `semiotic/recipes/core` | **77 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
+| `semiotic/recipes` | **84 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
+| `semiotic/recipes/core` | **83 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
 | `semiotic/recipes/react` | **2 KB** | Glyph and React layout-selection helpers |
 | `semiotic/themes` | **7 KB** | Theme presets only (tufte, carbon, etc.) |
 | `semiotic/themes/core` | **7 KB** | Theme presets and token helpers |
 | `semiotic/themes/react` | **6 KB** | ThemeProvider/useTheme and hooks |
 | `semiotic/data` | **4 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
 | `semiotic/value` | **8 KB** | BigNumber — focal-value KPI / scorecard (SingleValueFrame POC) |
-| `semiotic/physics` | **133 KB** | GaltonBoardChart, EventDropChart, PhysicsPileChart, CollisionSwarmChart, PhysicalFlowChart, PhysicsCustomChart |
+| `semiotic/physics` | **154 KB** | GaltonBoardChart, EventDropChart, PhysicsPileChart, CollisionSwarmChart, PhysicalFlowChart, PhysicsCustomChart |
 | `semiotic/physics/matter` | **1 KB** | Matter.js migration helpers + optional peer guard (no chart components) |
 | `semiotic/physics/rapier` | **1 KB** | Rapier peer guard + adapter decision metadata (no chart components) |
-| `semiotic/ai` | **432 KB** | All schema-backed charts + validation — optimized for LLM code generation |
-| `semiotic/ai/core` | **70 KB** | suggestCharts, validateProps, describeChart, repairChartConfig, tool adapters — no chart components |
+| `semiotic/ai` | **468 KB** | All schema-backed charts + validation — optimized for LLM code generation |
+| `semiotic/ai/core` | **78 KB** | suggestCharts, auditData, describeChart, repairChartConfig, tool adapters — no chart components |
 | `semiotic/controls` | **12 KB** | DirectManipulationControl, CircularBrush, MobileStandardControls, auditVisualizationControls — no frame renderer |
 | `semiotic/rough` | **4 KB** | Optional deterministic Rough.js paint backend — exact Semiotic geometry remains authoritative |
-| `semiotic` | **349 KB** | Everything below (full bundle) |
+| `semiotic` | **382 KB** | Everything below (full bundle) |
 
 <!-- semiotic-bundle-sizes:end -->
 
@@ -422,28 +428,28 @@ Method: fresh `npm pack --ignore-scripts` tarball → temporary consumer → min
 
 | Public named import | Runtime | gzip cold-consumer bundle |
 |---|---:|---:|
-| `import { LineChart } from "semiotic"` | browser | **147.9 KiB** |
-| `import { LineChart } from "semiotic/xy"` | browser | **148.0 KiB** |
-| `import { BarChart } from "semiotic/ordinal"` | browser | **122.1 KiB** |
-| `import { SankeyDiagram } from "semiotic/network"` | browser | **127.1 KiB** |
-| `import { RealtimeLineChart } from "semiotic/realtime"` | browser | **121.3 KiB** |
-| `import { RingBuffer } from "semiotic/realtime/core"` | browser | **169.6 KiB** |
+| `import { LineChart } from "semiotic"` | browser | **152.8 KiB** |
+| `import { LineChart } from "semiotic/xy"` | browser | **152.8 KiB** |
+| `import { BarChart } from "semiotic/ordinal"` | browser | **122.9 KiB** |
+| `import { SankeyDiagram } from "semiotic/network"` | browser | **127.8 KiB** |
+| `import { RealtimeLineChart } from "semiotic/realtime"` | browser | **122.5 KiB** |
+| `import { RingBuffer } from "semiotic/realtime/core"` | browser | **170.9 KiB** |
 | `import { useStreamStatus } from "semiotic/realtime/react"` | browser | **0.6 KiB** |
-| `import { GaltonBoardChart } from "semiotic/physics"` | browser | **118.7 KiB** |
+| `import { GaltonBoardChart } from "semiotic/physics"` | browser | **138.0 KiB** |
 | `import { MATTER_PHYSICS_CAPABILITIES } from "semiotic/physics/matter"` | browser | **0.2 KiB** |
 | `import { RAPIER_PHYSICS_CAPABILITIES } from "semiotic/physics/rapier"` | browser | **0.2 KiB** |
-| `import { renderChart } from "semiotic/server"` | node | **249.5 KiB** |
-| `import { generateFrameSVGs } from "semiotic/server/edge"` | node | **165.3 KiB** |
-| `import { renderToImage } from "semiotic/server/node"` | node | **249.9 KiB** |
-| `import { suggestCharts } from "semiotic/ai"` | browser | **207.3 KiB** |
-| `import { suggestCharts } from "semiotic/ai/core"` | browser | **32.2 KiB** |
+| `import { renderChart } from "semiotic/server"` | node | **266.6 KiB** |
+| `import { generateFrameSVGs } from "semiotic/server/edge"` | node | **165.0 KiB** |
+| `import { renderToImage } from "semiotic/server/node"` | node | **267.0 KiB** |
+| `import { suggestCharts } from "semiotic/ai"` | browser | **219.7 KiB** |
+| `import { suggestCharts } from "semiotic/ai/core"` | browser | **34.7 KiB** |
 | `import { bin } from "semiotic/data"` | browser | **0.4 KiB** |
-| `import { ChoroplethMap } from "semiotic/geo"` | browser | **106.6 KiB** |
+| `import { ChoroplethMap } from "semiotic/geo"` | browser | **108.2 KiB** |
 | `import { createRoughRenderMode } from "semiotic/rough"` | browser | **3.4 KiB** |
 | `import { resolveThemePreset } from "semiotic/themes"` | browser | **3.4 KiB** |
 | `import { resolveThemePreset } from "semiotic/themes/core"` | browser | **3.4 KiB** |
 | `import { ThemeProvider } from "semiotic/themes/react"` | browser | **4.4 KiB** |
-| `import { validateProps } from "semiotic/utils"` | browser | **6.9 KiB** |
+| `import { validateProps } from "semiotic/utils"` | browser | **7.4 KiB** |
 | `import { smartTickFormat } from "semiotic/utils/core"` | browser | **0.2 KiB** |
 | `import { useReducedMotion } from "semiotic/utils/react"` | browser | **0.3 KiB** |
 | `import { waffleLayout } from "semiotic/recipes"` | browser | **2.5 KiB** |
@@ -464,7 +470,7 @@ import { ChoroplethMap } from "semiotic/geo"
 
 **Tree-shaking & multi-subpath imports**: Family entries (`semiotic/xy`, `semiotic/network`, `semiotic/ai`, …) are built as one ESM graph with **shared chunks**. Stream frames, renderers, and other common code ship once and are imported by every entry that needs them — so combining `semiotic/ai` + `semiotic/xy` + `semiotic/network` does **not** mean paying for three full copies of the runtime. The package is marked `"sideEffects": false`, so modern bundlers keep only the named exports you retain (e.g. `LineChart` + `suggestCharts`). Prefer family subpaths for clarity; import AI helpers from `semiotic/ai` or the lighter `semiotic/ai/core` when you do not need the chart catalog.
 
-**When to use `"semiotic"`**: Fine when you want one import for mixed families. With shared chunks it is no longer “sum every subpath” — the cold-consumer table above is the better guide for a single named import, and multi-family apps should not see the old double-pay tax.
+**When to use `"semiotic"`**: Fine when you want one import for mixed families. Shared chunks prevent duplicated runtime code across family subpaths; the cold-consumer table above is the better guide for a single named import.
 
 ## TypeScript
 
@@ -551,7 +557,7 @@ host-header allowlisting. For ChatGPT Apps domain verification, set
 | **`renderChart`** | Render a Semiotic chart to static SVG. Supports the components returned by `getSchema` that are marked `[renderable]`. Pass `{ component: "LineChart", props: { data: [...], xAccessor: "x", yAccessor: "y" } }`. Returns SVG string plus a "Render evidence" JSON block (mark counts by scene type, resolved axis domains, empty flag, annotation count, accessible name) so agents can verify the chart drew data marks, or validation errors with fix suggestions. |
 | **`renderInteractiveChart`** | Render a static-data chart as a ChatGPT Apps widget. Uses the same Semiotic server render path as `renderChart`, then hydrates an iframe UI with fit, zoom, data, hover, and render-evidence controls. |
 | **`getSchema`** | Return the prop schema for a specific component. Pass `{ component: "LineChart" }` to get its props, or omit `component` to list the complete schema-backed catalog. Components marked `[renderable]` are available through `renderChart`; realtime charts require a browser/live environment. |
-| **`suggestChart`** | Legacy sample-row recommender. Pass `{ data: [{...}, ...] }` with 1–5 sample objects plus optional broad intent/capability filters. |
+| **`suggestChart`** | Sample-row recommender. Pass `{ data: [{...}, ...] }` with 1–5 sample objects plus optional broad intent/capability filters. |
 | **`suggestCharts`** | Capability-based recommender for bounded row data. Returns ranked chart suggestions with scores, reasons, caveats, import paths, and ready-to-use props. |
 | **`suggestStreamCharts`** | Recommend realtime charts from a stream schema, throughput, and retention hints. |
 | **`suggestDashboard`** | Build a multi-panel dashboard suggestion that covers distinct analytical intents. |

package/ai/behaviorContracts.cjs

@@ -27,8 +27,8 @@ const DOC_MARKER_END = "<!-- semiotic-behavior-contracts:end -->"
 // diagnoseConfig as "OK" in static mode. Keying off the presence of a `data`
 // property catches them (and still includes the charts that DO list `data`).
 //
-// `STATIC_DATA_COMPONENTS` stays exported as a Set for test/legacy callers
-// that probe the surface, and is rebuilt from disk at module load time.
+// `STATIC_DATA_COMPONENTS` is exported as a Set and rebuilt from disk at
+// module load time.
 function loadStaticDataComponentsFromSchema() {
   // Source layout has this file at `<repo>/ai/behaviorContracts.cjs` and the
   // schema at `<repo>/ai/schema.json` — `__dirname` works directly.

package/ai/componentMetadata.cjs

@@ -4,7 +4,7 @@ const CATEGORY_ORDER = ["xy", "ordinal", "network", "geo", "realtime", "physics"
 
 const COMPONENTS_BY_CATEGORY = {
   xy: [
-    "LineChart", "AreaChart", "DifferenceChart", "StackedAreaChart", "Scatterplot", "QuadrantChart",
+    "LineChart", "BumpChart", "AreaChart", "DifferenceChart", "StackedAreaChart", "Scatterplot", "QuadrantChart",
     "MultiAxisLineChart", "CandlestickChart", "BubbleChart", "Heatmap",
     "ConnectedScatterplot", "ScatterplotMatrix", "MinimapChart",
   ],
@@ -26,7 +26,7 @@ const COMPONENTS_BY_CATEGORY = {
   ],
   physics: [
     "GaltonBoardChart", "EventDropChart", "PhysicsPileChart", "CollisionSwarmChart",
-    "PhysicalFlowChart", "ProcessFlowChart", "GauntletChart",
+    "PhysicalFlowChart", "ProcessFlowChart", "GauntletChart", "CrucibleChart",
   ],
   value: [
     "BigNumber",

package/ai/dist/mcp-server.js

@@ -6898,6 +6898,7 @@ var require_componentMetadata = __commonJS({
     var COMPONENTS_BY_CATEGORY = {
       xy: [
         "LineChart",
+        "BumpChart",
         "AreaChart",
         "DifferenceChart",
         "StackedAreaChart",
@@ -6959,7 +6960,8 @@ var require_componentMetadata = __commonJS({
         "CollisionSwarmChart",
         "PhysicalFlowChart",
         "ProcessFlowChart",
-        "GauntletChart"
+        "GauntletChart",
+        "CrucibleChart"
       ],
       value: [
         "BigNumber"
@@ -33015,6 +33017,7 @@ var import_geo = require("semiotic/geo");
 var COMPONENT_REGISTRY = {
   LineChart: { component: import_ai.LineChart, category: "xy" },
   AreaChart: { component: import_ai.AreaChart, category: "xy" },
+  BumpChart: { component: import_ai.BumpChart, category: "xy" },
   DifferenceChart: { component: import_ai.DifferenceChart, category: "xy" },
   StackedAreaChart: { component: import_ai.StackedAreaChart, category: "xy" },
   Scatterplot: { component: import_ai.Scatterplot, category: "xy" },
@@ -33060,7 +33063,8 @@ var COMPONENT_REGISTRY = {
   CollisionSwarmChart: { component: import_ai.CollisionSwarmChart, category: "physics" },
   PhysicalFlowChart: { component: import_ai.PhysicalFlowChart, category: "physics" },
   ProcessFlowChart: { component: import_ai.ProcessFlowChart, category: "physics" },
-  GauntletChart: { component: import_ai.GauntletChart, category: "physics" }
+  GauntletChart: { component: import_ai.GauntletChart, category: "physics" },
+  CrucibleChart: { component: import_ai.CrucibleChart, category: "physics" }
 };
 
 // ai/renderHOCToSVG.tsx

package/ai/examples.md

@@ -147,7 +147,12 @@ const data = [
   data={data}
   xAccessor="month"
   yAccessor="revenue"
-  gradientFill
+  gradientFill={{
+    stops: [
+      { offset: 0, opacity: 0.8 },
+      { offset: 1, opacity: 0.05 }
+    ]
+  }}
   xLabel="Month"
   yLabel="Revenue ($)"
 />
@@ -180,7 +185,12 @@ const data = [
     y0Accessor="p5"
     showLine={false}
     areaOpacity={0.3}
-    gradientFill
+    gradientFill={{
+      stops: [
+        { offset: 0, opacity: 0.8 },
+        { offset: 1, opacity: 0.05 }
+      ]
+    }}
     width={600}
     height={400}
   />
@@ -235,6 +245,38 @@ Fills the region between two series with a color that switches based on which se
 
 Key props: `seriesALabel` / `seriesBLabel` (legend + tooltip), `seriesAColor` / `seriesBColor` (defaults to `var(--semiotic-danger)` / `var(--semiotic-info)`), `showLines` (default `true` — draws both series on top of the fill), `areaOpacity` (0.6), `gradientFill` (same shape as AreaChart), `windowSize` (max raw rows in push buffer; FIFO eviction). Push API: `ref.current.push({ x, a, b })` — accessor outputs coerce through a `toNumber` helper so `Date` (time series) and numeric strings (CSV/JSON) work transparently.
 
+### BumpChart
+
+```jsx
+import { BumpChart } from "semiotic/ai"
+
+const data = [
+  { quarter: "Q1", team: "North", sales: 420 },
+  { quarter: "Q1", team: "South", sales: 380 },
+  { quarter: "Q1", team: "East",  sales: 510 },
+  { quarter: "Q1", team: "West",  sales: 290 },
+  { quarter: "Q2", team: "North", sales: 460 },
+  { quarter: "Q2", team: "South", sales: 500 },
+  { quarter: "Q2", team: "East",  sales: 480 },
+  { quarter: "Q2", team: "West",  sales: 350 },
+  { quarter: "Q3", team: "North", sales: 610 },
+  { quarter: "Q3", team: "South", sales: 470 },
+  { quarter: "Q3", team: "East",  sales: 520 },
+  { quarter: "Q3", team: "West",  sales: 540 }
+]
+
+<BumpChart
+  data={data}
+  xAccessor="quarter"
+  yAccessor="sales"
+  lineBy="team"
+  highlightTop={2}
+  xLabel="Quarter"
+/>
+```
+
+Ranks every series within each x-column and connects each series' rank across columns — the classic "who's leading over time" chart. `yAccessor` is the magnitude used to rank (highest value = rank 1 by default; use `rankDirection="ascending"` when lower is better). `highlightTop` colors only the N best series by mean rank and greys the rest via `neutralColor`. Set `ribbon={true}` to encode the raw magnitude as true perpendicular-offset ribbon width instead of fixed-width lines — line and ribbon share the same centerline geometry, so `animate` tweens only the width. Endpoint labels show by default (`showLabels`).
+
 ### StackedAreaChart
 
 ```jsx
@@ -1184,6 +1226,86 @@ Key props: `y-threshold` works on vertical ordinal charts. `category-highlight`
 
 ---
 
+## Recipe Layouts — Explicit Semantics Without Bespoke Geometry
+
+### Word Trails (source-aware color + progressive reveal)
+
+```jsx
+import { useState } from "react"
+import { OrdinalCustomChart } from "semiotic/ordinal"
+import { wordTrailsLayout, wordTrailsProgressiveReveal } from "semiotic/recipes"
+
+// One source row per topic / word / recorded model iteration.
+const topicWordRuns = [
+  { topic: "Topic A", word: "archive", iteration: 0, probability: 0.08, distinctiveness: 0.28 },
+  { topic: "Topic A", word: "archive", iteration: 1, probability: 0.14, distinctiveness: 0.56 },
+  { topic: "Topic A", word: "archive", iteration: 2, probability: 0.19, distinctiveness: 0.84 },
+  { topic: "Topic A", word: "document", iteration: 2, probability: 0.13, distinctiveness: 0.62 },
+  { topic: "Topic B", word: "labor", iteration: 0, probability: 0.09, distinctiveness: 0.35 },
+  { topic: "Topic B", word: "labor", iteration: 1, probability: 0.16, distinctiveness: 0.72 },
+  { topic: "Topic B", word: "factory", iteration: 2, probability: 0.18, distinctiveness: 0.91 },
+]
+
+const topicColors = { "Topic A": "#2563eb", "Topic B": "#db2777" }
+
+function distinctivenessColor({ datum, resolvedColumnColor }) {
+  // The callback receives the exact source row, plus canonical layout fields.
+  const strength =
+    datum.distinctiveness >= 0.75 ? 100 :
+    datum.distinctiveness >= 0.5 ? 50 :
+    datum.distinctiveness >= 0.25 ? 25 : 0
+  return `color-mix(in srgb, ${resolvedColumnColor} ${strength}%, var(--surface-0, white))`
+}
+
+export default function ProgressiveTopicTrails() {
+  const [iteration, setIteration] = useState(2)
+
+  return (
+    <>
+      <label>
+        Model iteration {iteration}
+        <input
+          type="range"
+          min={0}
+          max={2}
+          value={iteration}
+          onChange={(event) => setIteration(Number(event.target.value))}
+        />
+      </label>
+      <OrdinalCustomChart
+        data={topicWordRuns}
+        layout={wordTrailsLayout}
+        layoutConfig={{
+          textAccessor: "word",
+          weightAccessor: "probability",
+          columnAccessor: "topic",
+          segmentAccessor: "iteration",
+          segmentDomain: [0, 2],
+          columnOrder: ["Topic A", "Topic B"],
+          repeatWords: true,
+          wordColor: distinctivenessColor,
+          columnColor: (topic) => topicColors[topic],
+          ...wordTrailsProgressiveReveal({
+            currentSegment: iteration,
+            segmentDomain: [0, 2],
+            oldestOpacity: 0.25,
+          }),
+        }}
+        categoryAccessor="topic"
+        valueAccessor="probability"
+        width={760}
+        height={460}
+        tooltip
+      />
+    </>
+  )
+}
+```
+
+Key APIs: `WordTrailsWordInfo` gives `word`, `column`, `weight`, and `segment` plus the exact `datum`, `dataIndex`, `columnIndex`, and `resolvedColumnColor`. `wordTrailsProgressiveReveal` hides future segments, fades reached history, and reserves every row's layout slot so playback never reflows. Set `combineWeightOpacity: true` only when opacity should also encode word weight.
+
+---
+
 ## Physics Charts — Motion With A Settled Projection
 
 ### GaltonBoardChart (distribution drop)
@@ -1356,6 +1478,93 @@ import { GauntletChart } from "semiotic/physics"
 
 Key props: `positiveProperties` / `negativeProperties` define satellite marks on each project core, `gates` place timed obstacles along the route, and the settled projection strip summarizes viability. Prefer GauntletChart for one plan with many attached attributes; use ProcessFlowChart for many independent work items.
 
+### CrucibleChart (explicit product lifecycle + immediate replay)
+
+```jsx
+import { useRef } from "react"
+import { CrucibleChart, buildCrucibleProductEvents } from "semiotic/physics"
+
+const evidence = [
+  { id: "deploy-log", label: "Deploy log", kind: "record" },
+  { id: "trace", label: "Request trace", kind: "telemetry" },
+  { id: "rollback", label: "Rollback result", kind: "experiment" },
+  { id: "traffic", label: "Traffic spike", kind: "counterclaim" },
+]
+
+const phases = [
+  { id: "charge", label: "Charge", duration: 1, motion: "charge" },
+  { id: "test", label: "Test mechanism", duration: 2.4, motion: "mix" },
+  { id: "publish", label: "Publish", duration: 1.6, motion: "pour" },
+]
+
+const products = [
+  { id: "finding", label: "Deploy caused regression", outletId: "findings" },
+]
+
+const events = [
+  ...buildCrucibleProductEvents({
+    productId: "finding",
+    form: {
+      at: { phaseId: "test", progress: 0.25 },
+      sourceIds: ["deploy-log", "trace"],
+      label: "Chronology and mechanism agree",
+    },
+    contributions: [{
+      at: { phaseId: "test", progress: 0.7 },
+      sourceIds: ["rollback"],
+      label: "Rollback supplies the counterfactual",
+    }],
+    complete: {
+      at: { phaseId: "publish", progress: 0.55 },
+      outletId: "findings",
+      reason: "Three authored observations support the finding",
+    },
+  }),
+  {
+    id: "reject-traffic",
+    at: { phaseId: "test", progress: 0.82 },
+    effects: [{
+      type: "eject",
+      select: { ids: ["traffic"] },
+      outletId: "contradicted",
+      reason: "The regression also occurs at ordinary traffic levels",
+    }],
+  },
+]
+
+export default function IncidentEvidenceCrucible() {
+  const chartRef = useRef(null)
+
+  return (
+    <>
+      <button type="button" onClick={() => chartRef.current?.replay()}>
+        Replay evidence
+      </button>
+      <CrucibleChart
+        ref={chartRef}
+        data={evidence}
+        phases={phases}
+        products={products}
+        events={events}
+        outlets={[
+          { id: "findings", label: "Supported finding", side: "bottom" },
+          { id: "contradicted", label: "Contradicted", side: "right" },
+        ]}
+        idAccessor="id"
+        labelAccessor="label"
+        categoryAccessor="kind"
+        projection={{ groupBy: "outlet", measure: "count" }}
+        playbackRate={0.8}
+        controls={{ playPause: true, reset: true, stepPhase: true, speed: true }}
+        size={[820, 400]}
+      />
+    </>
+  )
+}
+```
+
+Key APIs: `buildCrucibleProductEvents` emits the explicit `combine → contribute* → complete-product` grammar and deterministic fallback event ids. It never infers analysis, timing, product membership, reasons, or routing. The handle's `replay()` atomically restarts the same bounded tape even during a run; `reset()` restores the origin and pauses, while `rerunMS` schedules repetition after settlement.
+
 ---
 
 ## Value Charts — One Number Is The Visualization