Semiotic Files

Added

• StreamPhysicsFrame and physics process runtime. A deterministic, streaming physics frame for data stories where motion is the mechanism: sampling, lateness, queues, routing, collision, threshold crossing, and accumulation. It includes resident worker execution; running/paused/settled lifecycle; chart-derived colliders, regions, portals, absorption, forces, annotations, selection, observations, semantic interaction, and an imperative control surface; optional Matter and Rapier adapters; capacity queues, finite service-resource pools, service-level and dependency-gate controllers, journey ledgers, reference envelopes, and trace comparison; accessible settled projections and tables; deterministic SVG/evidence output and server-stepped animated GIF frames; plus EventDrop, Galton board, gauntlet, pile, collision, physical-flow, process-flow, and custom physics HOCs.

• ChartContainer notifications. New notifications prop surfaces chart-level notices that have no single mark to anchor to (a data-pitfalls or accessibility-audit finding about the whole chart, an unplaceable data-quality result) and custom user-authored notes. They collapse into a single severity-colored toolbar bell with a count badge — the bell adopts the icon and color of the most severe visible notice — and clicking it opens a popover with the dismissible cards, so a notice arriving or being dismissed never reflows the chart body. Each ChartNotification is { id?, level?, title?, message, source?, dismissible? }; levels (info | success | warning | error | neutral) resolve through the theme's semantic role CSS variables, a screen-reader-only aria-live="polite" region announces the current count + most-severe level so notices arriving while streaming are still voiced with the popover collapsed, and dismissal is tracked internally by id with an onNotificationDismiss callback for host stores/telemetry. Semantic class hooks: semiotic-chart-notifications (wrapper), -toggle (bell), -badge, -popover, and semiotic-chart-notification + --{level} / -source/-title/-message/-dismiss (cards). Types exported from semiotic and semiotic/ai; demonstrated on the Chart Container feature page and the Chart Clinic example.

• Worker-based force layout. ForceDirectedGraph gains layoutExecution ("auto" default | "worker" | "sync"), layoutLoadingContent, and onLayoutStateChange; in auto mode, layouts whose estimated cost (iterations × (nodes + edges)) exceeds a threshold settle in a short-lived module Web Worker and fall back to the synchronous path when workers are unavailable. New forceLayoutAsync() (Promise sibling of the forceLayout recipe, identical deterministic output) and useForceLayout() (React wrapper; SSR and first hydration stay synchronous for markup parity, and settled positions are memoized by graph identity + options so remounts don't re-enter a loading state). Ships a packaged forceLayoutWorker.js asset — CSP deployments need worker-src 'self'.

• x-band annotation. Full-height vertical shaded region (x0, x1, fill, fillOpacity, label) for marking eras/phases, rendered by both the canvas annotation rules and static SSR output; annotations with a missing bound are skipped in both.
• intervalLanesLayout minBarWidth (default 2): zero- and short-duration intervals stay visible and hoverable on long domains.
• Custom-layout readback: ref.current.getCustomLayout(). All four custom chart HOCs (XY/Ordinal/Network/Geo) expose the most recent layout(ctx) result on their ref, beside getData()/getScales() — hosts that need the computed placement (stats readouts, inspectors, validation) no longer re-run the layout function themselves. null before the first layout or on built-in chart types.
• unwrapDatum also unwraps .datum nesting (some interaction payloads nest the raw object there rather than under .data), and is now documented as the single unwrap path for both onObservation and frameProps.tooltipContent values.

Changed

• Force layout model overhauled (degree-aware charge, degree-normalized link strength, radius-aware collision, weaker centering; the forceLayout recipe is now backed by d3-force). Layouts settle to better-spread positions, but the same seed produces different geometry than earlier 3.x betas — regenerate position-pinned snapshots. forceStrength documentation was corrected to its actual link-attraction semantics, and its response curve changed with the new model, so hand-tuned values may need revisiting.
• intervalLanesLayout packs in rendered-pixel space, so the minBarWidth floor and inclusive end + unit extension can no longer overlap a same-track neighbor (previously visible as darker doubled fills when one interval ended the same unit the next began).
• DataPitfalls and GoFish adapters remain experimental. The DataPitfalls bridge is exposed from semiotic/experimental as unstable_toDataPitfallsChain / unstable_buildDataPitfallsBridge, with return-path helpers for DataPitfalls PR [#35] reports: unstable_toDataPitfallsNotifications for chart-level findings and unstable_toDataPitfallsAnnotations for host-anchored Semiotic v3 annotations. The GoFish DisplayList adapter remains unstable_fromGofishIR on the same endpoint. Neither adapter is part of the stable API surface yet.
• Force layout worker session. runForceLayoutWorker reuses a long-lived ForceLayoutWorkerSession (request IDs, no spawn/terminate per layout), matching the physics worker lifecycle. Abort cancels the pending request without killing the shared worker.
• Growing-window default cap. windowMode: "growing" now defaults maxCapacity to 100_000 (was 1_000_000). Dev builds log a one-time warning when the buffer first crosses 50_000 points.
• world-atlas is an optional peer. Built-in reference geographies still work when the package is installed; consumers who never call resolveReferenceGeography no longer take it as a hard dependency. (Still a devDependency for tests/docs.)
• Library build target raised from es2015 to es2020.
• CI: full gate suite runs once on Node 22; other engines run a smoke matrix (install, dist, vitest, typecheck).
• size-limit budgets added for physics, server, ai, recipes, utils, and value entry points.
• Stream frames memoized: StreamXYFrame, StreamOrdinalFrame, StreamNetworkFrame, StreamGeoFrame, and StreamPhysicsFrame are React.memo-wrapped so parent re-renders with stable props skip the frame body.
• Interaction canvas idle skip on XY and Geo (one clear when hover ends).
• Shared frameThemeColors module for version-cached theme/background resolution (StreamXYFrame uses it; other frames can adopt the same helper).
• RingBuffer.resize uses slice for shrink (avoids O(n²) shift loops when a growing window hits its cap).
• pipelineIdentityOps shared helpers for id-keyed remove/update paths.
• Shared paintCanvasBackground helper used by XY / Ordinal / Network / Geo frames (CSS-var-safe fill, transparent + backgroundGraphics opt-outs).
• Network dirty-canvas path: full clear/redraw only when data, transition, particles, encodings, or continuous animation need it — annotation-only rAF retries no longer thrash the data canvas.
• Root entry diet: physics HOCs (GaltonBoardChart, GauntletChart, PhysicsPileChart, etc.) are no longer exported from semiotic. Import from semiotic/physics (or semiotic/ai for tooling). Measured full package entry ~233 KB gz (was ~296 KB gz).
• XY decay/pulse share a version-cached datum→index map (buildDatumIndexMap) so continuous frames do not rebuild the map twice.
• Geo dirty-canvas path: hover-only repaints skip the data canvas and only update the interaction layer.
• Shared paintNeeds helpers (needsDataCanvasPaint / needsInteractionCanvasPaint) used by Network/Geo/XY paint gates.
• Test typecheck is clean: baseline emptied (~228 → 0 known errors). Cleared keyboardNav (82), ordinalSceneBuilders (45), recipes, heatmap, hydration suites, networkColoring, and the remaining debt files.

Deprecated

• GuantletChart typo alias of GauntletChart — use GauntletChart. Removal planned for the next major.

Docs

• CONTRIBUTING.md / DEVELOPMENT.md updated for the tsup + Vite toolchain (removed stale Rollup/Parcel/src/processing guidance).