semiotic 3.10.0 → 3.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (191) hide show
  1. package/README.md +55 -59
  2. package/ai/artifact-surface-inventory.json +1 -1
  3. package/ai/componentMetadata.cjs +3 -1
  4. package/ai/dist/mcp-server.js +45 -45
  5. package/ai/examples.md +67 -0
  6. package/ai/reference.md +75 -1
  7. package/ai/schema.json +5199 -1
  8. package/ai/surface-manifest.json +24 -3
  9. package/ai/task-packets/compare-category-totals.json +6 -6
  10. package/ai/task-packets/compare-category-totals.md +3 -3
  11. package/ai/task-packets/correct-published-chart.json +6 -6
  12. package/ai/task-packets/correct-published-chart.md +3 -3
  13. package/ai/task-packets/index.json +6 -6
  14. package/ai/task-packets/update-live-chart.json +6 -6
  15. package/ai/task-packets/update-live-chart.md +3 -3
  16. package/dist/c-2RL2QPZJ.min.js +1 -0
  17. package/dist/c-45CQWZZ6.min.js +1 -0
  18. package/dist/{c-PP6VY3QU.min.js → c-4BRHKVKV.min.js} +1 -1
  19. package/dist/c-7DVPSB5C.min.js +1 -0
  20. package/dist/{c-XDQKXPX4.min.js → c-A7OGOFSL.min.js} +1 -1
  21. package/dist/{c-AZKPVBOC.min.js → c-AH5HWZWS.min.js} +1 -1
  22. package/dist/c-B7GW7IHJ.min.js +1 -0
  23. package/dist/{c-ROEHCIGV.min.js → c-C3TZLTZK.min.js} +1 -1
  24. package/dist/c-CGQAQWBV.min.js +1 -0
  25. package/dist/c-DIPEYUOW.min.js +1 -0
  26. package/dist/{c-WNGH47HF.min.js → c-E72OTUZU.min.js} +1 -1
  27. package/dist/{c-DY2676CR.min.js → c-EUMPMDCS.min.js} +1 -1
  28. package/dist/c-EZZT2WAE.min.js +1 -0
  29. package/dist/c-FHBVFCQB.min.js +1 -0
  30. package/dist/{c-E32M6XW5.min.js → c-G4HCO2IQ.min.js} +1 -1
  31. package/dist/{c-ZYPXQF7B.min.js → c-G5VIJEOK.min.js} +1 -1
  32. package/dist/c-GHVOXAYH.min.js +1 -0
  33. package/dist/{c-EBOQ7ER7.min.js → c-HP4ZFM47.min.js} +1 -1
  34. package/dist/{c-IDJV3CZK.min.js → c-HYDTS5OP.min.js} +1 -1
  35. package/dist/c-IK33LNZ6.min.js +1 -0
  36. package/dist/c-IK3PZHRY.min.js +1 -0
  37. package/dist/{c-JO2UGTCP.min.js → c-J6DVC236.min.js} +1 -1
  38. package/dist/{c-MXCP7GNZ.min.js → c-JIMJF6F6.min.js} +1 -1
  39. package/dist/{c-4FN7Q6VQ.min.js → c-KKPMHAZC.min.js} +1 -1
  40. package/dist/c-L6WNDBHV.min.js +1 -0
  41. package/dist/c-LDEX5OFW.min.js +1 -0
  42. package/dist/{c-CPSPZH6A.min.js → c-LESEUVC5.min.js} +1 -1
  43. package/dist/c-MB6CV5NC.min.js +1 -0
  44. package/dist/{c-OO5QLMJC.min.js → c-MOKJOIPE.min.js} +1 -1
  45. package/dist/{c-BNG5ECK5.min.js → c-N3FXLRNT.min.js} +1 -1
  46. package/dist/c-N5NPTJVJ.min.js +1 -0
  47. package/dist/{c-DE5Q3U2X.min.js → c-NHBL4J67.min.js} +1 -1
  48. package/dist/{c-LMGSSD2E.min.js → c-ODG6TFSY.min.js} +1 -1
  49. package/dist/{c-HXDKPIKR.min.js → c-PSKKFZNP.min.js} +1 -1
  50. package/dist/{c-NYZ2QNAM.min.js → c-R2P4RR7Q.min.js} +1 -1
  51. package/dist/{c-KCRJGUHP.min.js → c-RFC7UAG7.min.js} +1 -1
  52. package/dist/c-SGAURYHG.min.js +1 -0
  53. package/dist/{c-DK662R77.min.js → c-SJMWU6UX.min.js} +1 -1
  54. package/dist/c-STIIGQOD.min.js +1 -0
  55. package/dist/c-T2ASIJVZ.min.js +1 -0
  56. package/dist/c-TX3THUTO.min.js +1 -0
  57. package/dist/{c-55BAJ333.min.js → c-TX7XJM3Z.min.js} +1 -1
  58. package/dist/c-UMXSJIOV.min.js +1 -0
  59. package/dist/{c-JLGRHXGZ.min.js → c-VRSXMLYF.min.js} +1 -1
  60. package/dist/c-VSLWSAN2.min.js +1 -0
  61. package/dist/{c-33QOXEUG.min.js → c-WCBRPILW.min.js} +1 -1
  62. package/dist/{c-WH2O53VI.min.js → c-WGHT7OCY.min.js} +1 -1
  63. package/dist/c-WWCW3APR.min.js +1 -0
  64. package/dist/c-Y6PYUMFU.min.js +1 -0
  65. package/dist/c-ZIVPFTOC.min.js +1 -0
  66. package/dist/components/charts/shared/chartDataProps.d.ts +3 -0
  67. package/dist/components/charts/shared/chartSpecAtlasSchemas.d.ts +5 -0
  68. package/dist/components/charts/shared/chartSpecCore.d.ts +4 -0
  69. package/dist/components/charts/shared/chartSpecsAtlas.d.ts +2 -0
  70. package/dist/components/charts/shared/hooks.d.ts +3 -1
  71. package/dist/components/charts/shared/knownChartComponents.d.ts +1 -1
  72. package/dist/components/recipes/atlas/DependencyForestChart.d.ts +20 -0
  73. package/dist/components/recipes/atlas/DependencyMatrix.d.ts +7 -0
  74. package/dist/components/recipes/atlas/FlowCircuitChart.d.ts +20 -0
  75. package/dist/components/recipes/atlas/MotifBraidChart.d.ts +17 -0
  76. package/dist/components/recipes/atlas/atlasChartOptions.d.ts +11 -0
  77. package/dist/components/recipes/atlas/braid.d.ts +62 -0
  78. package/dist/components/recipes/atlas/capsules.d.ts +18 -0
  79. package/dist/components/recipes/atlas/compare.d.ts +4 -0
  80. package/dist/components/recipes/atlas/completeness.d.ts +2 -0
  81. package/dist/components/recipes/atlas/dependencyForest.d.ts +32 -0
  82. package/dist/components/recipes/atlas/dependencyForestChartProps.d.ts +58 -0
  83. package/dist/components/recipes/atlas/dependencyForestLayout.d.ts +17 -0
  84. package/dist/components/recipes/atlas/dependencyQueries.d.ts +20 -0
  85. package/dist/components/recipes/atlas/dependencyTypes.d.ts +21 -0
  86. package/dist/components/recipes/atlas/directedGraph.d.ts +9 -0
  87. package/dist/components/recipes/atlas/entityCounts.d.ts +3 -0
  88. package/dist/components/recipes/atlas/flowCircuit.d.ts +32 -0
  89. package/dist/components/recipes/atlas/flowCircuitChartProps.d.ts +72 -0
  90. package/dist/components/recipes/atlas/flowCircuitChrome.d.ts +18 -0
  91. package/dist/components/recipes/atlas/flowCircuitGeometry.d.ts +11 -0
  92. package/dist/components/recipes/atlas/flowCircuitLayout.d.ts +20 -0
  93. package/dist/components/recipes/atlas/flowCircuitSemantics.d.ts +26 -0
  94. package/dist/components/recipes/atlas/flowCircuitTape.d.ts +22 -0
  95. package/dist/components/recipes/atlas/flowCircuitTypes.d.ts +144 -0
  96. package/dist/components/recipes/atlas/forests.d.ts +11 -0
  97. package/dist/components/recipes/atlas/ids.d.ts +6 -0
  98. package/dist/components/recipes/atlas/index.d.ts +26 -0
  99. package/dist/components/recipes/atlas/ledger.d.ts +7 -0
  100. package/dist/components/recipes/atlas/motifBraidChartProps.d.ts +51 -0
  101. package/dist/components/recipes/atlas/motifBraidGeometry.d.ts +5 -0
  102. package/dist/components/recipes/atlas/motifBraidLayout.d.ts +11 -0
  103. package/dist/components/recipes/atlas/motifs.d.ts +3 -0
  104. package/dist/components/recipes/atlas/prefixForest.d.ts +9 -0
  105. package/dist/components/recipes/atlas/prepare.d.ts +14 -0
  106. package/dist/components/recipes/atlas/prepareAsync.d.ts +7 -0
  107. package/dist/components/recipes/atlas/profile.d.ts +19 -0
  108. package/dist/components/recipes/atlas/publish.d.ts +10 -0
  109. package/dist/components/recipes/atlas/queries.d.ts +34 -0
  110. package/dist/components/recipes/atlas/requiredPaths.d.ts +9 -0
  111. package/dist/components/recipes/atlas/rootedForest.d.ts +4 -0
  112. package/dist/components/recipes/atlas/sections.d.ts +3 -0
  113. package/dist/components/recipes/atlas/support.d.ts +7 -0
  114. package/dist/components/recipes/atlas/types.d.ts +278 -0
  115. package/dist/components/recipes/atlas/validate.d.ts +12 -0
  116. package/dist/components/semiotic-atlas-core.d.ts +20 -0
  117. package/dist/components/semiotic-atlas.d.ts +8 -0
  118. package/dist/components/semiotic-recipes-core.d.ts +9 -0
  119. package/dist/components/server/serverChartConfigs.d.ts +3 -0
  120. package/dist/components/server/serverChartConfigsAtlas.d.ts +4 -0
  121. package/dist/components/stream/NetworkPipelineStore.d.ts +1 -0
  122. package/dist/components/stream/canvasSetup.d.ts +1 -2
  123. package/dist/components/stream/fontLoading.d.ts +4 -0
  124. package/dist/components/stream/networkCustomLayout.d.ts +8 -0
  125. package/dist/components/stream/networkCustomLayoutCache.d.ts +12 -0
  126. package/dist/components/stream/networkPipelineConfig.d.ts +0 -7
  127. package/dist/components/stream/physics/physicsSemanticUI.d.ts +2 -0
  128. package/dist/components/stream/physics/usePhysicsCanvasPointer.d.ts +3 -1
  129. package/dist/components/stream/physics/usePhysicsSemanticNavigation.d.ts +2 -0
  130. package/dist/components/stream/shallowEqual.d.ts +2 -0
  131. package/dist/components/stream/useEnsureCustomXYRenderers.d.ts +4 -2
  132. package/dist/geo.min.js +1 -1
  133. package/dist/geo.module.min.js +1 -1
  134. package/dist/network.module.min.js +1 -1
  135. package/dist/ordinal.module.min.js +1 -1
  136. package/dist/physics.module.min.js +1 -1
  137. package/dist/rough.module.min.js +1 -1
  138. package/dist/semiotic-access.module.min.js +1 -1
  139. package/dist/semiotic-ai-core.min.js +1 -1
  140. package/dist/semiotic-ai-core.module.min.js +1 -1
  141. package/dist/semiotic-ai.module.min.js +1 -1
  142. package/dist/semiotic-artifact.min.js +1 -1
  143. package/dist/semiotic-artifact.module.min.js +1 -1
  144. package/dist/semiotic-atlas-core.d.ts +20 -0
  145. package/dist/semiotic-atlas-core.min.js +1 -0
  146. package/dist/semiotic-atlas-core.module.min.js +1 -0
  147. package/dist/semiotic-atlas-selection.module.min.js +2 -0
  148. package/dist/semiotic-atlas.d.ts +8 -0
  149. package/dist/semiotic-atlas.min.js +2 -0
  150. package/dist/semiotic-atlas.module.min.js +2 -0
  151. package/dist/semiotic-client-cjs-shared.min.js +1 -1
  152. package/dist/semiotic-evidence.min.js +1 -1
  153. package/dist/semiotic-evidence.module.min.js +1 -1
  154. package/dist/semiotic-experimental-auxiliary.module.min.js +1 -1
  155. package/dist/semiotic-experimental-node-auxiliary.module.min.js +1 -1
  156. package/dist/semiotic-experimental-react-shared.module.min.js +1 -1
  157. package/dist/semiotic-experimental-vacp.min.js +1 -1
  158. package/dist/semiotic-experimental-vacp.module.min.js +1 -1
  159. package/dist/semiotic-line.module.min.js +1 -1
  160. package/dist/semiotic-realtime-core.module.min.js +1 -1
  161. package/dist/semiotic-recipes-core-cjs-base.min.js +1 -1
  162. package/dist/semiotic-recipes-core.d.ts +9 -0
  163. package/dist/semiotic-recipes-core.module.min.js +1 -1
  164. package/dist/semiotic-server-edge-node.module.min.js +1 -1
  165. package/dist/semiotic-server-edge.min.js +1 -1
  166. package/dist/semiotic-server-edge.module.min.js +1 -1
  167. package/dist/semiotic-server-node.min.js +1 -1
  168. package/dist/semiotic-server-node.module.min.js +1 -1
  169. package/dist/semiotic-text.min.js +1 -1
  170. package/dist/semiotic-text.module.min.js +1 -1
  171. package/dist/semiotic-utils-core.min.js +1 -1
  172. package/dist/semiotic-utils-core.module.min.js +1 -1
  173. package/dist/semiotic.module.min.js +1 -1
  174. package/dist/server.min.js +1 -1
  175. package/dist/server.module.min.js +1 -1
  176. package/dist/xy.module.min.js +1 -1
  177. package/package.json +16 -1
  178. package/dist/c-447VIMRO.min.js +0 -1
  179. package/dist/c-553QUDKA.min.js +0 -1
  180. package/dist/c-7HP7MB2I.min.js +0 -1
  181. package/dist/c-7NBU5ZKS.min.js +0 -1
  182. package/dist/c-CCTGN5CK.min.js +0 -1
  183. package/dist/c-GSZRZRD6.min.js +0 -1
  184. package/dist/c-GWX7JGMF.min.js +0 -1
  185. package/dist/c-ITKX3RC5.min.js +0 -1
  186. package/dist/c-JG2JCQLP.min.js +0 -1
  187. package/dist/c-LYVKDBQJ.min.js +0 -1
  188. package/dist/c-NG7BLZTR.min.js +0 -1
  189. package/dist/c-PYNW54D2.min.js +0 -1
  190. package/dist/c-TIXX5CAU.min.js +0 -1
  191. /package/dist/{c-OOVX2JPQ.min.js → c-UC7SIU2W.min.js} +0 -0
package/ai/examples.md CHANGED
@@ -1918,3 +1918,70 @@ import { BigNumber } from "semiotic/value"
1918
1918
  ```
1919
1919
 
1920
1920
  Key props: `direction: "lower-is-better"` flips sentiment colouring — a value that went UP now reads as negative (danger). Same pattern for error rate, churn, complaint count, etc.
1921
+
1922
+
1923
+ ## Network Atlas readers
1924
+
1925
+ These examples consume admitted inputs supplied by the application. Prepare once upstream, check admission issues, and pass the same artifact to React and static rendering. The interactive reference pages provide complete synthetic inputs and downloadable JSON readings.
1926
+
1927
+ ### MotifBraidChart
1928
+
1929
+ ```tsx
1930
+ import { MotifBraidChart } from "semiotic/atlas"
1931
+ import { prepareNetworkAtlas, type NetworkAtlasSpec, type NetworkAtlasSource } from "semiotic/atlas/core"
1932
+
1933
+ export function prepareJourneys(spec: NetworkAtlasSpec, source: NetworkAtlasSource) {
1934
+ const result = prepareNetworkAtlas(spec, source)
1935
+ if (!result.ok) throw new Error(JSON.stringify(result.issues))
1936
+ return result.atlas
1937
+ }
1938
+ // Run preparation upstream. Optional occurrence.stepEntityCounts aligns with
1939
+ // nodePath; omitted counts retain a constant entityCount at every step.
1940
+ export function Journeys({ atlas }: { atlas: ReturnType<typeof prepareJourneys> }) {
1941
+ return <MotifBraidChart atlas={atlas} title="Supported journeys" accessibleTable />
1942
+ }
1943
+ ```
1944
+
1945
+ ### DependencyForestChart
1946
+
1947
+ ```tsx
1948
+ import { DependencyForestChart, DependencyMatrix } from "semiotic/atlas"
1949
+ import { prepareDependencyForest, type PreparedNetworkAtlas } from "semiotic/atlas/core"
1950
+
1951
+ export function prepareDependencies(atlas: PreparedNetworkAtlas) {
1952
+ return prepareDependencyForest(atlas)
1953
+ }
1954
+ export function Dependencies({ forest }: { forest: ReturnType<typeof prepareDependencies> }) {
1955
+ return <>
1956
+ <DependencyForestChart forest={forest} reading="required-paths"
1957
+ title="Required supplier paths" summary="Required paths describe topology; capacity remains a separate measurement." />
1958
+ <DependencyMatrix forest={forest} nodeIds={forest.order.slice(0, 6)} />
1959
+ </>
1960
+ }
1961
+ ```
1962
+
1963
+ ### FlowCircuitChart
1964
+
1965
+ ```tsx
1966
+ import { FlowCircuitChart } from "semiotic/atlas"
1967
+ import { readCircuitEdition, type FlowCircuitProjection, type CircuitEdition } from "semiotic/atlas/core"
1968
+ import { renderChartWithEvidence } from "semiotic/server"
1969
+
1970
+ // circuit comes from prepareFlowCircuit(atlas, authoredSemantics).
1971
+ // edition has passed admitCircuitEdition(circuit, authoredTape).
1972
+ export function ProcessReading({ circuit, edition, time }: {
1973
+ circuit: FlowCircuitProjection; edition: CircuitEdition; time: number
1974
+ }) {
1975
+ const mode = edition.kind === "modeled" ? "modeled-scenario" : "observed-replay"
1976
+ const reading = readCircuitEdition(edition, mode, time)
1977
+ return <FlowCircuitChart circuit={circuit} edition={edition} reading={reading}
1978
+ title={edition.label} reducedMotion accessibleTable />
1979
+ }
1980
+ export function staticProcess(circuit: FlowCircuitProjection, edition: CircuitEdition, time: number) {
1981
+ const mode = edition.kind === "modeled" ? "modeled-scenario" : "observed-replay"
1982
+ return renderChartWithEvidence("FlowCircuitChart", {
1983
+ circuit, edition, reading: readCircuitEdition(edition, mode, time),
1984
+ title: edition.label, reducedMotion: true
1985
+ })
1986
+ }
1987
+ ```
package/ai/reference.md CHANGED
@@ -10,7 +10,7 @@ diagnostic tools; when possible, confirm a non-empty render with evidence.
10
10
  - Install: `npm install semiotic`
11
11
  <!-- semiotic-bundle-sizes:start -->
12
12
  <!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
13
- - **Use sub-path imports** — `semiotic/access` (36KB gz), `semiotic/evidence` (50KB gz), `semiotic/artifact` (121KB gz), `semiotic/artifact/react` (4KB gz), `semiotic/line` (131KB gz), `semiotic/xy` (161KB gz), `semiotic/ordinal` (130KB gz), `semiotic/network` (150KB gz), `semiotic/geo` (107KB gz), `semiotic/realtime` (159KB gz), `semiotic/realtime/core` (158KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (228KB gz), `semiotic/server/node` (228KB gz), `semiotic/server/edge` (230KB gz), `semiotic/utils` (98KB gz), `semiotic/utils/core` (91KB gz), `semiotic/utils/react` (7KB gz), `semiotic/recipes` (100KB gz), `semiotic/recipes/core` (92KB gz), `semiotic/recipes/react` (8KB gz), `semiotic/themes` (12KB gz), `semiotic/themes/core` (12KB gz), `semiotic/themes/react` (7KB gz), `semiotic/data` (3KB gz), `semiotic/value` (6KB gz), `semiotic/physics` (165KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (591KB gz), `semiotic/ai/core` (138KB gz), `semiotic/controls` (10KB gz), `semiotic/rough` (3KB gz), `semiotic/text` (1KB gz). Full `semiotic` is 371KB gz.
13
+ - **Use sub-path imports** — `semiotic/atlas` (273KB gz), `semiotic/atlas/core` (14KB gz), `semiotic/access` (36KB gz), `semiotic/evidence` (50KB gz), `semiotic/artifact` (121KB gz), `semiotic/artifact/react` (4KB gz), `semiotic/line` (132KB gz), `semiotic/xy` (163KB gz), `semiotic/ordinal` (131KB gz), `semiotic/network` (151KB gz), `semiotic/geo` (108KB gz), `semiotic/realtime` (161KB gz), `semiotic/realtime/core` (160KB gz), `semiotic/realtime/react` (1KB gz), `semiotic/server` (241KB gz), `semiotic/server/node` (241KB gz), `semiotic/server/edge` (248KB gz), `semiotic/utils` (99KB gz), `semiotic/utils/core` (91KB gz), `semiotic/utils/react` (7KB gz), `semiotic/recipes` (111KB gz), `semiotic/recipes/core` (103KB gz), `semiotic/recipes/react` (8KB gz), `semiotic/themes` (12KB gz), `semiotic/themes/core` (12KB gz), `semiotic/themes/react` (7KB gz), `semiotic/data` (3KB gz), `semiotic/value` (6KB gz), `semiotic/physics` (167KB gz), `semiotic/physics/matter` (1KB gz), `semiotic/physics/rapier` (1KB gz), `semiotic/ai` (595KB gz), `semiotic/ai/core` (139KB gz), `semiotic/controls` (10KB gz), `semiotic/rough` (3KB gz), `semiotic/text` (1KB gz). Full `semiotic` is 374KB gz.
14
14
  <!-- semiotic-bundle-sizes:end -->
15
15
  - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor|--audit-a11y|--evaluate]` · MCP: `npx semiotic-mcp`
16
16
 
@@ -242,6 +242,80 @@ For fitted lineage regions, set `lineageDagLayout`'s `hullGroupAccessor` (for ex
242
242
 
243
243
  `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.
244
244
 
245
+ ### Network Atlas readers (semiotic/atlas)
246
+
247
+ **MotifBraidChart**, **DependencyForestChart** and **FlowCircuitChart** are public React readers and serialized chart names. Import them from `semiotic/atlas`; use `semiotic/atlas/core` for synchronous, React-free preparation and queries. All three render with `renderChartWithEvidence(name, props)` from `semiotic/server` (including Node and edge server entries).
248
+
249
+ - `MotifBraidChart`: required `atlas: PreparedNetworkAtlas`. `prepareNetworkAtlas(spec, source)` returns an admission result; inspect `ok` and issues before rendering. Rounded square steps share recognizable depths; divergent prefixes split strands. `stepEntityCounts` must align with `nodePath`; omitted counts retain constant `entityCount`. Overlapping motif counts do not partition the population.
250
+ - `DependencyForestChart`: required `forest: prepareDependencyForest(atlas)`. `reading` is `organize` or `required-paths`. `collapsedNodeIds`, `highlightedEdgeIds` and `{ nodeId, analysisRevision, relationScopeId: "directed-admitted" }` selection affect the reading without rewriting evidence. `DependencyMatrix`, `dependencyMatrix`, `getRequiredPaths`, `getBypassWitness` and `getBranchResidualConnections` expose local evidence. A structural bypass does not imply usable capacity.
251
+ - `FlowCircuitChart`: required `circuit: prepareFlowCircuit(atlas, semantics)`, `edition: admitCircuitEdition(circuit, tape)` and `reading: readCircuitEdition(edition, mode, time)`. Modes are `observed-snapshot`, `observed-replay`, `modeled-scenario`. The circuit, edition and reading must share their identities and revisions. Observed tapes and modeled scenarios remain separate; measurements use explicit units and null for unmeasured values. `particleBudget`, `placementSeed` and `reducedMotion` affect visual cues only. `exportCircuitEvidence` preserves provenance and assumptions.
252
+
253
+ These readers accept `title`, `description`, `summary`, `accessibleTable` (default true), `chartId`, `onObservation`, `linkedHover` and annotations. Dependency and Circuit expose `onSelectNode` for both pointer and keyboard activation, `linkedSelection: { name }`, and semantic `colors` overrides. Publish canonical vertex hover with `linkedHover: { name, fields: ["nodeId"] }`; consume that named selection with `selection: { name }` on Braid or `linkedSelection: { name }` on Dependency/Circuit. Use `ThemeProvider` from `semiotic/themes/react`; selections and observations share `LinkedCharts` from `semiotic/ai`. Preserve task tables and inspectors in phone layouts instead of shrinking a dense graph to unreadability.
254
+
255
+ Prepare analysis upstream or in an application-owned worker, then serialize the complete prepared artifact into chart props. `prepareNetworkAtlasAsync` loads preparation lazily but does not spawn a worker. Machine schemas describe prepared artifacts; flat-data chart suggestions cannot invent roots, route evidence, module semantics or editions. Interactive references: `/charts/motif-braid-chart`, `/charts/dependency-forest-chart`, `/charts/flow-circuit-chart`. The five synthetic stories are tested by an independent packed-package consumer.
256
+
257
+ **Motif Braid preparation** (`semiotic/recipes/core` or `semiotic/recipes`): the compatible lower-level recipe API remains available.
258
+
259
+ `await prepareNetworkAtlasAsync(spec: NetworkAtlasSpec, source: NetworkAtlasSource)` returns
260
+ `{ ok: true, atlas, issues }` or `{ ok: false, issues }`. Both preparation functions load their analysis code on demand. After checking `ok`, call
261
+ `await prepareMotifBraid(atlas)` to obtain a `MotifBraidProjection`. Use
262
+ `NetworkCustomChart` with `nodes={braid.sceneSeeds.nodes}`,
263
+ `edges={braid.sceneSeeds.edges}`, `layout={motifBraidLayout}`, and
264
+ `layoutConfig={{ braid }}`; the same props support `renderChart` from
265
+ `semiotic/server`. The layout labels every prefix step with a rounded square
266
+ at its depth, shares reference prefix ordering across selected comparison
267
+ partitions, and keeps separate parallel strands until their prefixes diverge.
268
+ Supply optional `stepEntityCounts` on each source occurrence: one finite,
269
+ nonnegative traffic count per `nodePath` entry. Width tapers between adjacent
270
+ counts using one scale across visible partitions (maximum 10 px, minimum 1 px
271
+ for positive traffic; zero traffic has zero width). Omit the array to use
272
+ `entityCount` at every step. Cohort weights and profile counts still use
273
+ `entityCount`; step traffic does not change motif prevalence. Repeated vertices
274
+ remain separate visits and short journeys end at their actual depth.
275
+ Episodes end at the second visit to a repeated state; profile
276
+ cells count each entity once and use the declared assigned denominator. Capsule
277
+ expansion is not supported. `MotifBraidChart` is public from `semiotic/atlas` and accepts `{ atlas }` directly. The existing asynchronous recipe APIs remain compatible.
278
+
279
+ Atlas layouts retain canonical `nodeId`, source and analysis revisions on
280
+ interaction data. For public Motif Braid consumers, give `NetworkCustomChart`
281
+ a `chartId` and read its events with `useChartObserver`, `ObservationReadout`
282
+ or `DetailsPanel` inside `LinkedCharts`. Link vertices with
283
+ `linkedHover={{ name: "vertices", fields: ["nodeId"] }}` and
284
+ `selection={{ name: "vertices" }}`. Selection dims marks without changing
285
+ the prepared analysis. Use `ThemeProvider` from `semiotic/themes/react`;
286
+ `colorScheme` maps can assign colors by complete journey signature.
287
+ Network keyboard navigation uses Space to activate a vertex; Enter follows
288
+ a connected edge. Accessible tables retain readable step and traffic fields.
289
+
290
+ For Dependency X-Ray preparation, optionally set
291
+ `forest.requiredPaths: { roots: ["world"], relationScopeId: "directed-admitted" }`.
292
+ The existing public `prepareNetworkAtlasAsync` facades then return
293
+ `atlas.requiredPaths`: original-graph immediate dominators, reachable and
294
+ unreachable node IDs, and an exact/incomplete status. Null parents refer to the
295
+ analytical synthetic root, not source edges. The scope currently admits only
296
+ the full directed graph. `rooted-traversal:id-asc` and
297
+ `rooted-traversal:id-desc` select an acyclic display backbone while retaining
298
+ every other original edge as residual. Neither dominance nor a structural
299
+ bypass proves usable capacity or AND-prerequisite completion. The X-Ray chart is public as `DependencyForestChart` from `semiotic/atlas`; projection and query helpers ship from `semiotic/atlas/core`. `/examples/dependency-xray` demonstrates the synthetic supplier study.
300
+
301
+ The public Flow Circuit reader exposes exact current module and original-pipe
302
+ readings to keyboard/table users and observers, including unmeasured fields.
303
+ Replay updates semantic data while retaining the physical bodies. Both public
304
+ readers accept standard chart text, `chartId`, `onObservation`, annotations,
305
+ `frameProps`, and `linkedHover`; use `linkedSelection={{ name: "vertices" }}`
306
+ alongside their local graph selection. Their `colors` layout option overrides
307
+ semantic theme roles. `/examples/flow-circuit` and `/examples/dependency-xray`
308
+ demonstrate shared observation readouts, documentation theme changes and
309
+ matching SVG exports through public package imports.
310
+
311
+ `diagnoseConfig` accepts JavaScript configurations of the five custom-chart
312
+ HOCs and checks their layout callback, input array shapes, dimensions and
313
+ interactive annotation IDs. It does not execute or prove a custom layout;
314
+ also use `renderChartWithEvidence` and `auditAccessibility`. Executable custom
315
+ layouts are still outside the serialized component schema. To export a linked
316
+ selection, supply its predicate through `frameProps.layoutSelection` on network
317
+ or geo custom charts; a server renderer cannot read a browser's selection store.
318
+
245
319
  **Decoration (labels/axes/legends): the recipe owns it.** Recipes emit own decoration via `overlays` return field (ReactNode painted on top). Built-in axes via `showAxes` on the HOC work for layouts respecting the standard scale. Recipe convention: `showXxx` boolean toggles, `xxxFormat` callbacks. Shipped recipes' toggles: marimekko `showCategoryLabels`, bullet `showLabels`+`showTicks`, parallelCoordinates `showAxes`, flextree/dagre `showLabels`, waffle/calendar none.
246
320
 
247
321
  **Interaction (hover/brush/selection): the parent owns it.** Recipes are pure — they take predicate props (e.g. `parallelCoordinatesLayout`'s `highlightFn?`) and the parent manages state via `onObservation` (`{type: "hover" | "hover-end" | ...}`), feeding a derived predicate back into `layoutConfig`. Matching rows render at full opacity; non-matching dim; highlighted z-order on top.