@demlik/tea 0.7.0 → 0.8.0

package/dist/machine-viz/index.d.ts

@@ -1,5 +1,22 @@
 import { C as Cmd, S as Sub, M as Machine } from '../core-Bjc0bS8j.js';
 
+/**
+ * Sanitize a discriminant string into a Mermaid-safe node identifier.
+ *
+ * Any run of non-identifier characters becomes `_`; a leading digit is
+ * prefixed so the id is always a valid Mermaid token; the empty string gets a
+ * stable placeholder. Deterministic and idempotent — `safeId(safeId(x))` is
+ * `safeId(x)`, so a diagram may sanitize the same name at several sites.
+ */
+declare function safeId(raw: string): string;
+/**
+ * Sanitize text used as a Mermaid edge/transition label (the part after `:`).
+ *
+ * Strips the characters that terminate or confuse a label: newlines, the `:`
+ * that separates label from target, and Mermaid's `"`/`;` delimiters.
+ */
+declare function safeLabel(raw: string): string;
+
 /**
  * @demlik/tea/machine-viz — turn a `Machine` into a Mermaid diagram string.
  *
@@ -75,4 +92,4 @@ declare function toMermaid<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts?: MachineVizOptions<NoInfer<S>, NoInfer<M>>): string;
 
-export { type MachineVizOptions, toMermaid };
+export { type MachineVizOptions, safeId, safeLabel, toMermaid };

package/dist/machine-viz/index.js

@@ -1,15 +1,9 @@
+import { safeId, safeLabel } from '../chunk-UOC2PL46.js';
+export { safeId, safeLabel } from '../chunk-UOC2PL46.js';
 import '../chunk-5EHLEUTL.js';
 import { formOf } from '../chunk-B5VXOFMZ.js';
 
 // src/machine-viz/index.ts
-function safeId(raw) {
-  const cleaned = raw.replace(/[^A-Za-z0-9_]/g, "_");
-  if (cleaned === "") return "_empty";
-  return /^[0-9]/.test(cleaned) ? `s_${cleaned}` : cleaned;
-}
-function safeLabel(raw) {
-  return raw.replace(/["\n\r;:]/g, " ").trim();
-}
 function toMermaid(machine, opts = {}) {
   const direction = opts.direction ?? "TB";
   const stateSamples = opts.samples?.states ?? {};

package/dist/machine-viz/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/machine-viz/index.ts"],"names":[],"mappings":";;;;AAoEA,SAAS,OAAO,GAAA,EAAqB;AAGnC,EAAA,MAAM,OAAA,GAAU,GAAA,CAAI,OAAA,CAAQ,gBAAA,EAAkB,GAAG,CAAA;AACjD,EAAA,IAAI,OAAA,KAAY,IAAI,OAAO,QAAA;AAC3B,EAAA,OAAO,SAAS,IAAA,CAAK,OAAO,CAAA,GAAI,CAAA,EAAA,EAAK,OAAO,CAAA,CAAA,GAAK,OAAA;AACnD;AAGA,SAAS,UAAU,GAAA,EAAqB;AAGtC,EAAA,OAAO,GAAA,CAAI,OAAA,CAAQ,YAAA,EAAc,GAAG,EAAE,IAAA,EAAK;AAC7C;AA8BO,SAAS,SAAA,CAOd,OAAA,EAKA,IAAA,GAAkD,EAAC,EAC3C;AACR,EAAA,MAAM,SAAA,GAAY,KAAK,SAAA,IAAa,IAAA;AACpC,EAAA,MAAM,YAAA,GAAe,IAAA,CAAK,OAAA,EAAS,MAAA,IAAU,EAAC;AAC9C,EAAA,MAAM,UAAA,GAAa,IAAA,CAAK,OAAA,EAAS,IAAA,IAAQ,EAAC;AAC1C,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,OAAA,KAAY,MAAA,IAAa,SAAS,IAAA,CAAK,OAAA;AAE3D,EAAA,MAAM,IAAA,GAAO,OAAO,OAAO,CAAA;AAC3B,EAAA,MAAM,QAAkB,EAAC;AAGzB,EAAA,IAAI,IAAA,CAAK,UAAU,MAAA,EAAW;AAC5B,IAAA,KAAA,CAAM,KAAK,KAAA,EAAO,CAAA,OAAA,EAAU,IAAA,CAAK,KAAK,IAAI,KAAK,CAAA;AAAA,EACjD;AACA,EAAA,KAAA,CAAM,KAAK,iBAAiB,CAAA;AAC5B,EAAA,KAAA,CAAM,IAAA,CAAK,CAAA,YAAA,EAAe,SAAS,CAAA,CAAE,CAAA;AAErC,EAAA,IAAI,SAAS,SAAA,EAAW;AACtB,IAAA,WAAA,CAAY,SAAS,KAAK,CAAA;AAAA,EAC5B,CAAA,MAAO;AACL,IAAA,eAAA,CAAgB,SAAS,KAAA,EAAO;AAAA,MAC9B,YAAA;AAAA,MACA,UAAA;AAAA,MACA,MAAA;AAAA,MACA,GAAA,EAAK,KAAK,OAAA,EAAS;AAAA,KACpB,CAAA;AAAA,EACH;AAKA,EAAA,iBAAA,CAAkB,OAAA,EAAS,OAAO,YAAY,CAAA;AAE9C,EAAA,OAAO,KAAA,CAAM,KAAK,IAAI,CAAA;AACxB;AASA,SAAS,WAAA,CAAY,SAA8B,KAAA,EAAuB;AACxE,EAAA,MAAM,QAAA,GAAW,MAAA,CAAO,IAAA,CAAK,OAAA,CAAQ,MAAgB,CAAA;AACrD,EAAA,KAAA,CAAM,KAAK,0BAA0B,CAAA;AACrC,EAAA,IAAI,QAAA,CAAS,WAAW,CAAA,EAAG;AACzB,IAAA,KAAA,CAAM,KAAK,oBAAoB,CAAA;AAC/B,IAAA,KAAA,CAAM,KAAK,oDAA+C,CAAA;AAAA,EAC5D,CAAA,MAAO;AACL,IAAA,KAAA,MAAW,KAAK,QAAA,EAAU;AACxB,MAAA,KAAA,CAAM,IAAA,CAAK,OAAO,MAAA,CAAO,CAAC,CAAC,CAAA,GAAA,EAAM,SAAA,CAAU,CAAC,CAAC,CAAA,CAAE,CAAA;AAAA,IACjD;AAAA,EACF;AACA,EAAA,KAAA,CAAM,KAAK,KAAK,CAAA;AAGhB,EAAA,KAAA,CAAM,KAAK,gCAAgC,CAAA;AAC3C,EAAA,KAAA,CAAM,KAAK,4DAA4D,CAAA;AACvE,EAAA,KAAA,CAAM,IAAA;AAAA,IACJ;AAAA,GACF;AACA,EAAA,KAAA,CAAM,IAAA,CAAK,CAAA,uBAAA,EAA0B,QAAA,CAAS,MAAM,CAAA,CAAE,CAAA;AACtD,EAAA,KAAA,CAAM,KAAK,YAAY,CAAA;AACzB;AAgBA,SAAS,eAAA,CAOP,OAAA,EACA,KAAA,EACA,GAAA,EACM;AAGN,EAAA,MAAM,QAAQ,OAAA,CAAQ,MAAA;AACtB,EAAA,MAAM,UAAA,GAAa,MAAA,CAAO,IAAA,CAAK,KAAK,CAAA;AAGpC,EAAA,KAAA,MAAW,MAAM,UAAA,EAAY;AAC3B,IAAA,KAAA,CAAM,IAAA,CAAK,CAAA,EAAA,EAAK,MAAA,CAAO,EAAE,CAAC,CAAA,CAAE,CAAA;AAAA,EAC9B;AAIA,EAAA,IAAI,IAAI,MAAA,EAAQ;AACd,IAAA,MAAM,CAAC,SAAS,CAAA,GAAI,QAAQ,IAAA,CAAK,IAAA,EAAM,IAAI,GAAU,CAAA;AACrD,IAAA,MAAM,WAAY,SAAA,CAA0C,IAAA;AAC5D,IAAA,KAAA,CAAM,IAAA,CAAK,CAAA,UAAA,EAAa,MAAA,CAAO,QAAQ,CAAC,CAAA,CAAE,CAAA;AAAA,EAC5C,CAAA,MAAO;AACL,IAAA,KAAA,CAAM,IAAA;AAAA,MACJ;AAAA,KACF;AAAA,EACF;AAEA,EAAA,IAAI,aAAA,GAAgB,KAAA;AACpB,EAAA,KAAA,MAAW,MAAM,UAAA,EAAY;AAC3B,IAAA,MAAM,GAAA,GAAM,MAAM,EAAE,CAAA;AACpB,IAAA,IAAI,QAAQ,MAAA,EAAW;AACvB,IAAA,MAAM,QAAA,GAAW,MAAA,CAAO,IAAA,CAAK,GAAG,CAAA;AAChC,IAAA,KAAA,MAAW,MAAM,QAAA,EAAU;AACzB,MAAA,MAAM,IAAA,GAAO,WAAA,CAAY,GAAA,EAAK,EAAA,EAAI,IAAI,GAAG,CAAA;AACzC,MAAA,IAAI,IAAA,CAAK,SAAS,UAAA,EAAY;AAC5B,QAAA,KAAA,CAAM,IAAA;AAAA,UACJ,CAAA,EAAA,EAAK,MAAA,CAAO,IAAA,CAAK,IAAI,CAAC,CAAA,KAAA,EAAQ,MAAA,CAAO,IAAA,CAAK,EAAE,CAAC,CAAA,GAAA,EAAM,SAAA,CAAU,IAAA,CAAK,GAAG,CAAC,CAAA;AAAA,SACxE;AAAA,MACF,CAAA,MAAO;AACL,QAAA,aAAA,GAAgB,IAAA;AAGhB,QAAA,KAAA,CAAM,IAAA;AAAA,UACJ,CAAA,EAAA,EAAK,MAAA,CAAO,IAAA,CAAK,IAAI,CAAC,CAAA,KAAA,EAAQ,MAAA,CAAO,IAAA,CAAK,IAAI,CAAC,CAAA,GAAA,EAAM,SAAA,CAAU,IAAA,CAAK,GAAG,CAAC,CAAA,CAAA;AAAA,SAC1E;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAGA,EAAA,KAAA,CAAM,IAAA,CAAK,mBAAmB,MAAA,CAAO,UAAA,CAAW,CAAC,CAAA,IAAK,QAAQ,CAAC,CAAA,CAAE,CAAA;AACjE,EAAA,KAAA,CAAM,KAAK,+BAA+B,CAAA;AAC1C,EAAA,KAAA,CAAM,KAAK,iEAAiE,CAAA;AAC5E,EAAA,IAAI,aAAA,EAAe;AACjB,IAAA,KAAA,CAAM,IAAA;AAAA,MACJ;AAAA,KACF;AAAA,EACF;AACA,EAAA,KAAA,CAAM,KAAK,YAAY,CAAA;AACzB;AASA,SAAS,WAAA,CACP,GAAA,EACA,SAAA,EACA,OAAA,EACA,GAAA,EAIM;AACN,EAAA,MAAM,WAAA,GAAc,GAAA,CAAI,YAAA,CAAa,SAAS,CAAA;AAC9C,EAAA,MAAM,SAAA,GAAY,GAAA,CAAI,UAAA,CAAW,OAAO,CAAA;AACxC,EAAA,MAAM,IAAA,GAAO,IAAI,OAAO,CAAA;AACxB,EAAA,IACE,WAAA,KAAgB,MAAA,IAChB,SAAA,KAAc,MAAA,IACd,SAAS,MAAA,EACT;AACA,IAAA,OAAO,EAAE,IAAA,EAAM,YAAA,EAAc,IAAA,EAAM,SAAA,EAAW,KAAK,OAAA,EAAQ;AAAA,EAC7D;AACA,EAAA,IAAI;AACF,IAAA,MAAM,CAAC,IAAI,CAAA,GAAI,IAAA,CAAK,aAAa,SAAS,CAAA;AAC1C,IAAA,MAAM,KAAM,IAAA,CAAqC,IAAA;AACjD,IAAA,OAAO,EAAE,IAAA,EAAM,UAAA,EAAY,MAAM,SAAA,EAAW,EAAA,EAAI,KAAK,OAAA,EAAQ;AAAA,EAC/D,CAAA,CAAA,MAAQ;AAEN,IAAA,OAAO,EAAE,IAAA,EAAM,YAAA,EAAc,IAAA,EAAM,SAAA,EAAW,KAAK,OAAA,EAAQ;AAAA,EAC7D;AACF;AAWA,SAAS,iBAAA,CAOP,OAAA,EACA,KAAA,EACA,YAAA,EACM;AACN,EAAA,IAAI,OAAA,CAAQ,kBAAkB,MAAA,EAAW;AACzC,EAAA,MAAM,UAAA,GAAa,MAAA,CAAO,IAAA,CAAK,YAAY,CAAA;AAC3C,EAAA,IAAI,UAAA,CAAW,WAAW,CAAA,EAAG;AAE7B,EAAA,KAAA,MAAW,MAAM,UAAA,EAAY;AAC3B,IAAA,MAAM,MAAA,GAAS,aAAa,EAAE,CAAA;AAC9B,IAAA,IAAI,WAAW,MAAA,EAAW;AAC1B,IAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,aAAA,CAAc,MAAM,CAAA;AACzC,IAAA,MAAM,WAAW,IAAA,CAAK,GAAA,CAAI,CAAC,CAAA,KAAM,EAAE,IAAI,CAAA;AACvC,IAAA,MAAM,IAAA,GACJ,QAAA,CAAS,MAAA,KAAW,CAAA,GAChB,kBAAA,GACA,CAAA,MAAA,EAAS,QAAA,CAAS,GAAA,CAAI,SAAS,CAAA,CAAE,IAAA,CAAK,IAAI,CAAC,CAAA,CAAA;AACjD,IAAA,KAAA,CAAM,IAAA,CAAK,CAAA,eAAA,EAAkB,MAAA,CAAO,EAAE,CAAC,CAAA,CAAE,CAAA;AACzC,IAAA,KAAA,CAAM,IAAA,CAAK,CAAA,IAAA,EAAO,IAAI,CAAA,CAAE,CAAA;AACxB,IAAA,KAAA,CAAM,KAAK,YAAY,CAAA;AAAA,EACzB;AACF","file":"index.js","sourcesContent":["/**\n * @demlik/tea/machine-viz — turn a `Machine` into a Mermaid diagram string.\n *\n * PURE. No deps, no AST parsing, no file I/O. The function reads only the\n * `Machine` value it is handed plus optional sample states/msgs/ctx.\n *\n * The trick: TEA update cells are PURE (invariant 2 — they return\n * `[nextState, cmds]` as data, no effects). So we can SAFELY EXECUTE a cell to\n * discover its target state — exactly what `replay` does. That gives us REAL\n * edges (`red --> green : go`) without parsing source. When no sample is\n * provided for a `(state, msg)` pair we cannot resolve the target, so we fall\n * back to a STRUCTURAL self-edge annotated with `?` — visually distinct from a\n * resolved edge and documented in the diagram's legend.\n *\n * Form detection is `formOf(machine)` — the same reader `run`/`replay` use,\n * honoring the authoritative `__form` tag `defineMachine` stamps (falling back\n * to the structural heuristic for machines built without it; #275).\n *\n * What we MUST NOT do (these are the effectful paths, off-limits here):\n *   - call `interpret[*]` handlers (perform I/O)\n *   - call `subscribe[*]` handlers (install listeners)\n *   - call `run` / the runtime\n * We MAY call `init`, `update[*]` cells, and `subscriptions(state)` — all pure\n * by the invariants (same set `replay` is allowed to touch).\n */\n\nimport type { Cmd, Machine, Sub } from \"../index\";\nimport { formOf } from \"../index\";\n\n// === Public options ===\n\n/**\n * Options controlling diagram emission.\n *\n * `samples` is the lever that turns STRUCTURAL edges into RESOLVED edges. For a\n * Transitions machine, providing a sample state for `stateType` AND a sample\n * msg for `msgType` lets us execute `update[stateType][msgType](state, msg)` and\n * read the real target `next.type`. Sample maps are keyed by the discriminant\n * string (`state.type` / `msg.type`).\n *\n * `samples.ctx` is the argument to `init(null, ctx)` — provide it to draw the\n * `[*] -->` initial-state edge. Omitted ⇒ no init edge (annotated as such),\n * because `init`'s signature requires a ctx and we will not invent one.\n */\nexport interface MachineVizOptions<S, M> {\n  samples?: {\n    /** Sample state per `state.type` — unlocks RESOLVED edges + sub annotations. */\n    states?: Partial<Record<string, S>>;\n    /** Sample msg per `msg.type` — unlocks RESOLVED edges. */\n    msgs?: Partial<Record<string, M>>;\n    /** Ctx for `init(null, ctx)` — unlocks the `[*] -->` initial-state edge. */\n    ctx?: unknown;\n  };\n  /** Mermaid layout direction. Default `\"TB\"` (top-to-bottom). */\n  direction?: \"TB\" | \"LR\";\n  /** Optional diagram title, emitted as a Mermaid front-matter `title:` block. */\n  title?: string;\n}\n\n// === Mermaid label escaping ===\n//\n// Mermaid state ids must be identifier-safe; arbitrary `type` strings (which\n// CAN contain `:`, spaces, `-`, etc.) are not. We sanitize the id used as the\n// node identifier and carry the human-readable original as a quoted label via\n// `stateId : \"Original\"` when they differ. Edge transition labels (after the\n// `:`) are sanitized to avoid breaking the arrow syntax.\n\n/** Sanitize a discriminant string into a Mermaid-safe node identifier. */\nfunction safeId(raw: string): string {\n  // Replace any run of non-identifier chars with `_`; prefix a leading digit so\n  // the id is always a valid Mermaid token. Empty ⇒ a stable placeholder.\n  const cleaned = raw.replace(/[^A-Za-z0-9_]/g, \"_\");\n  if (cleaned === \"\") return \"_empty\";\n  return /^[0-9]/.test(cleaned) ? `s_${cleaned}` : cleaned;\n}\n\n/** Sanitize text used as a Mermaid edge/transition label (after the `:`). */\nfunction safeLabel(raw: string): string {\n  // Strip the chars that terminate or confuse a transition label: newlines,\n  // the `:` that separates label from target, and Mermaid's `\"`/`;` delimiters.\n  return raw.replace(/[\"\\n\\r;:]/g, \" \").trim();\n}\n\n// === Edge model ===\n\ntype Edge =\n  // Resolved: we executed the cell with samples and read the real target.\n  | { kind: \"resolved\"; from: string; to: string; msg: string }\n  // Structural: no samples for the pair → target unknown, drawn as a self-loop.\n  | { kind: \"structural\"; from: string; msg: string };\n\n// === toMermaid ===\n\n/**\n * Render a `Machine` as a Mermaid `stateDiagram-v2` string.\n *\n * - **Transitions form** (`update` is a record-of-records): nodes are the\n *   `state.type` keys; each `(stateType × msgType)` cell becomes an edge. With\n *   samples for both, the edge is RESOLVED by executing the (pure) cell. Without\n *   samples it is STRUCTURAL — a `from --> from : msg?` self-loop (the `?`\n *   suffix marks \"target unresolved\"). A legend note documents the distinction.\n *   The `[*] -->` init edge is drawn only when `samples.ctx` is provided.\n *\n * - **Reducer form** (`update` values are functions): there is no static phase\n *   graph (state is not a discriminated union over phases). We emit a single\n *   node listing the handled `msg.type`s and an honest note saying so. No edges\n *   are invented.\n *\n * Output is deterministic for the same input (keys iterated in insertion order,\n * no clocks, no randomness).\n */\nexport function toMermaid<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  // `NoInfer` pins S/M to the `machine` argument so sample object literals in\n  // `opts` are CHECKED against the machine's State/Msg unions rather than\n  // driving inference (which would widen `{ type: \"open\" }` to `{ type: string }`\n  // and collide with the machine's discriminated union).\n  opts: MachineVizOptions<NoInfer<S>, NoInfer<M>> = {},\n): string {\n  const direction = opts.direction ?? \"TB\";\n  const stateSamples = opts.samples?.states ?? {};\n  const msgSamples = opts.samples?.msgs ?? {};\n  const hasCtx = opts.samples !== undefined && \"ctx\" in opts.samples;\n\n  const mode = formOf(machine);\n  const lines: string[] = [];\n\n  // Front matter — Mermaid reads a YAML `title:` block before the diagram.\n  if (opts.title !== undefined) {\n    lines.push(\"---\", `title: ${opts.title}`, \"---\");\n  }\n  lines.push(\"stateDiagram-v2\");\n  lines.push(`  direction ${direction}`);\n\n  if (mode === \"reducer\") {\n    emitReducer(machine, lines);\n  } else {\n    emitTransitions(machine, lines, {\n      stateSamples,\n      msgSamples,\n      hasCtx,\n      ctx: opts.samples?.ctx,\n    });\n  }\n\n  // Subscriptions annotation — pure call to `subscriptions(sampleState)` per\n  // sampled state. Skipped entirely when no state samples are provided (we\n  // refuse to invent a state to feed it).\n  emitSubscriptions(machine, lines, stateSamples);\n\n  return lines.join(\"\\n\");\n}\n\n// === Reducer-form emission ===\n\n/**\n * Reducer form has no phase graph. Emit one node listing the handled msg types\n * plus an honest note. The msg set is the `update` record's keys (the Reducer\n * mapped type guarantees one cell per Msg variant).\n */\nfunction emitReducer(machine: { update: unknown }, lines: string[]): void {\n  const msgTypes = Object.keys(machine.update as object);\n  lines.push(\"  state ReducerMachine {\");\n  if (msgTypes.length === 0) {\n    lines.push(\"    [*] --> NoMsgs\");\n    lines.push('    NoMsgs : \"(no msg variants — M is never)\"');\n  } else {\n    for (const m of msgTypes) {\n      lines.push(`    ${safeId(m)} : ${safeLabel(m)}`);\n    }\n  }\n  lines.push(\"  }\");\n  // The note IS the design honesty: no edges, because reducer-form state is not\n  // a discriminated union over phases — there is no static target to draw.\n  lines.push(\"  note right of ReducerMachine\");\n  lines.push(\"    Reducer-form machine: flat dispatch keyed by msg.type.\");\n  lines.push(\n    \"    No phase graph — state is not a discriminated union over phases.\",\n  );\n  lines.push(`    Handled msg types: ${msgTypes.length}`);\n  lines.push(\"  end note\");\n}\n\n// === Transitions-form emission ===\n\ninterface TransitionsCtx<S, M> {\n  stateSamples: Partial<Record<string, S>>;\n  msgSamples: Partial<Record<string, M>>;\n  hasCtx: boolean;\n  ctx: unknown;\n}\n\n/**\n * Transitions form: walk the `update[stateType][msgType]` table. Execute the\n * (pure) cell when both samples exist → RESOLVED edge; otherwise → STRUCTURAL\n * self-loop. Draw the `[*] -->` init edge only when a ctx sample is given.\n */\nfunction emitTransitions<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  lines: string[],\n  ctx: TransitionsCtx<S, M>,\n): void {\n  type CellFn = (state: S, msg: M) => readonly [S, readonly C[]];\n  type Table = Record<string, Record<string, CellFn>>;\n  const table = machine.update as unknown as Table;\n  const stateTypes = Object.keys(table);\n\n  // Declare every node up front so even unreachable phases render.\n  for (const st of stateTypes) {\n    lines.push(`  ${safeId(st)}`);\n  }\n\n  // Init edge — only resolvable with a ctx sample. `init(null, ctx)` is pure\n  // (invariant 2: fresh-boot branch returns a starting state). Read `next.type`.\n  if (ctx.hasCtx) {\n    const [initState] = machine.init(null, ctx.ctx as Ctx);\n    const initType = (initState as unknown as { type: string }).type;\n    lines.push(`  [*] --> ${safeId(initType)}`);\n  } else {\n    lines.push(\n      \"  %% init edge omitted: no samples.ctx provided to run init(null, ctx)\",\n    );\n  }\n\n  let anyStructural = false;\n  for (const st of stateTypes) {\n    const row = table[st];\n    if (row === undefined) continue;\n    const msgTypes = Object.keys(row);\n    for (const mt of msgTypes) {\n      const edge = resolveEdge(row, st, mt, ctx);\n      if (edge.kind === \"resolved\") {\n        lines.push(\n          `  ${safeId(edge.from)} --> ${safeId(edge.to)} : ${safeLabel(edge.msg)}`,\n        );\n      } else {\n        anyStructural = true;\n        // Structural self-loop with a `?` suffix — target unresolved. Visually\n        // distinct from a resolved edge (self-loop + trailing `?`).\n        lines.push(\n          `  ${safeId(edge.from)} --> ${safeId(edge.from)} : ${safeLabel(edge.msg)}?`,\n        );\n      }\n    }\n  }\n\n  // Legend — document the resolved-vs-structural distinction in the output.\n  lines.push(`  note right of ${safeId(stateTypes[0] ?? \"_empty\")}`);\n  lines.push(\"    Transitions-form machine.\");\n  lines.push(\"    Edge a --> b : msg = RESOLVED (cell executed with samples).\");\n  if (anyStructural) {\n    lines.push(\n      \"    Self-loop a --> a : msg? = STRUCTURAL (no sample; target unresolved).\",\n    );\n  }\n  lines.push(\"  end note\");\n}\n\n/**\n * Resolve a single `(stateType, msgType)` cell into an Edge. With both a sample\n * state and a sample msg, EXECUTE the pure cell to read the real target. Any\n * missing sample → structural. A thrown cell (e.g. a sample shaped wrong for\n * the cell) degrades to structural rather than crashing the whole diagram —\n * the diagram is a best-effort visualization, not a correctness gate.\n */\nfunction resolveEdge<S, M extends { type: string }, C extends Cmd>(\n  row: Record<string, (state: S, msg: M) => readonly [S, readonly C[]]>,\n  stateType: string,\n  msgType: string,\n  ctx: {\n    stateSamples: Partial<Record<string, S>>;\n    msgSamples: Partial<Record<string, M>>;\n  },\n): Edge {\n  const sampleState = ctx.stateSamples[stateType];\n  const sampleMsg = ctx.msgSamples[msgType];\n  const cell = row[msgType];\n  if (\n    sampleState === undefined ||\n    sampleMsg === undefined ||\n    cell === undefined\n  ) {\n    return { kind: \"structural\", from: stateType, msg: msgType };\n  }\n  try {\n    const [next] = cell(sampleState, sampleMsg);\n    const to = (next as unknown as { type: string }).type;\n    return { kind: \"resolved\", from: stateType, to, msg: msgType };\n  } catch {\n    // Mismatched sample → cannot resolve. Fall back to structural.\n    return { kind: \"structural\", from: stateType, msg: msgType };\n  }\n}\n\n// === Subscriptions annotation ===\n\n/**\n * For each sampled state, call the (pure) `subscriptions(state)` description\n * function and annotate which Sub types are active in that state as a Mermaid\n * note. We call `subscriptions` (the description) but NEVER `subscribe[*]` (the\n * effectful installer) — same boundary `replay` honors. Skipped when no state\n * samples are provided or the machine declares no `subscriptions`.\n */\nfunction emitSubscriptions<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  lines: string[],\n  stateSamples: Partial<Record<string, S>>,\n): void {\n  if (machine.subscriptions === undefined) return;\n  const stateTypes = Object.keys(stateSamples);\n  if (stateTypes.length === 0) return;\n\n  for (const st of stateTypes) {\n    const sample = stateSamples[st];\n    if (sample === undefined) continue;\n    const subs = machine.subscriptions(sample);\n    const subTypes = subs.map((s) => s.type);\n    const body =\n      subTypes.length === 0\n        ? \"(no active subs)\"\n        : `subs: ${subTypes.map(safeLabel).join(\", \")}`;\n    lines.push(`  note left of ${safeId(st)}`);\n    lines.push(`    ${body}`);\n    lines.push(\"  end note\");\n  }\n}\n"]}
+{"version":3,"sources":["../../src/machine-viz/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/machine-viz — turn a `Machine` into a Mermaid diagram string.\n *\n * PURE. No deps, no AST parsing, no file I/O. The function reads only the\n * `Machine` value it is handed plus optional sample states/msgs/ctx.\n *\n * The trick: TEA update cells are PURE (invariant 2 — they return\n * `[nextState, cmds]` as data, no effects). So we can SAFELY EXECUTE a cell to\n * discover its target state — exactly what `replay` does. That gives us REAL\n * edges (`red --> green : go`) without parsing source. When no sample is\n * provided for a `(state, msg)` pair we cannot resolve the target, so we fall\n * back to a STRUCTURAL self-edge annotated with `?` — visually distinct from a\n * resolved edge and documented in the diagram's legend.\n *\n * Form detection is `formOf(machine)` — the same reader `run`/`replay` use,\n * honoring the authoritative `__form` tag `defineMachine` stamps (falling back\n * to the structural heuristic for machines built without it; #275).\n *\n * What we MUST NOT do (these are the effectful paths, off-limits here):\n *   - call `interpret[*]` handlers (perform I/O)\n *   - call `subscribe[*]` handlers (install listeners)\n *   - call `run` / the runtime\n * We MAY call `init`, `update[*]` cells, and `subscriptions(state)` — all pure\n * by the invariants (same set `replay` is allowed to touch).\n */\n\nimport type { Cmd, Machine, Sub } from \"../index\";\nimport { formOf } from \"../index\";\nimport { safeId, safeLabel } from \"./mermaid-id\";\n\n// The sanitizers are SHARED with `chart`'s `chartMermaid` — one copy, in a\n// dependency-free module, re-exported here because both drawings are public\n// and a consumer post-processing either one needs the same escaping.\nexport { safeId, safeLabel } from \"./mermaid-id\";\n\n// === Public options ===\n\n/**\n * Options controlling diagram emission.\n *\n * `samples` is the lever that turns STRUCTURAL edges into RESOLVED edges. For a\n * Transitions machine, providing a sample state for `stateType` AND a sample\n * msg for `msgType` lets us execute `update[stateType][msgType](state, msg)` and\n * read the real target `next.type`. Sample maps are keyed by the discriminant\n * string (`state.type` / `msg.type`).\n *\n * `samples.ctx` is the argument to `init(null, ctx)` — provide it to draw the\n * `[*] -->` initial-state edge. Omitted ⇒ no init edge (annotated as such),\n * because `init`'s signature requires a ctx and we will not invent one.\n */\nexport interface MachineVizOptions<S, M> {\n  samples?: {\n    /** Sample state per `state.type` — unlocks RESOLVED edges + sub annotations. */\n    states?: Partial<Record<string, S>>;\n    /** Sample msg per `msg.type` — unlocks RESOLVED edges. */\n    msgs?: Partial<Record<string, M>>;\n    /** Ctx for `init(null, ctx)` — unlocks the `[*] -->` initial-state edge. */\n    ctx?: unknown;\n  };\n  /** Mermaid layout direction. Default `\"TB\"` (top-to-bottom). */\n  direction?: \"TB\" | \"LR\";\n  /** Optional diagram title, emitted as a Mermaid front-matter `title:` block. */\n  title?: string;\n}\n\n// === Edge model ===\n\ntype Edge =\n  // Resolved: we executed the cell with samples and read the real target.\n  | { kind: \"resolved\"; from: string; to: string; msg: string }\n  // Structural: no samples for the pair → target unknown, drawn as a self-loop.\n  | { kind: \"structural\"; from: string; msg: string };\n\n// === toMermaid ===\n\n/**\n * Render a `Machine` as a Mermaid `stateDiagram-v2` string.\n *\n * - **Transitions form** (`update` is a record-of-records): nodes are the\n *   `state.type` keys; each `(stateType × msgType)` cell becomes an edge. With\n *   samples for both, the edge is RESOLVED by executing the (pure) cell. Without\n *   samples it is STRUCTURAL — a `from --> from : msg?` self-loop (the `?`\n *   suffix marks \"target unresolved\"). A legend note documents the distinction.\n *   The `[*] -->` init edge is drawn only when `samples.ctx` is provided.\n *\n * - **Reducer form** (`update` values are functions): there is no static phase\n *   graph (state is not a discriminated union over phases). We emit a single\n *   node listing the handled `msg.type`s and an honest note saying so. No edges\n *   are invented.\n *\n * Output is deterministic for the same input (keys iterated in insertion order,\n * no clocks, no randomness).\n */\nexport function toMermaid<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  // `NoInfer` pins S/M to the `machine` argument so sample object literals in\n  // `opts` are CHECKED against the machine's State/Msg unions rather than\n  // driving inference (which would widen `{ type: \"open\" }` to `{ type: string }`\n  // and collide with the machine's discriminated union).\n  opts: MachineVizOptions<NoInfer<S>, NoInfer<M>> = {},\n): string {\n  const direction = opts.direction ?? \"TB\";\n  const stateSamples = opts.samples?.states ?? {};\n  const msgSamples = opts.samples?.msgs ?? {};\n  const hasCtx = opts.samples !== undefined && \"ctx\" in opts.samples;\n\n  const mode = formOf(machine);\n  const lines: string[] = [];\n\n  // Front matter — Mermaid reads a YAML `title:` block before the diagram.\n  if (opts.title !== undefined) {\n    lines.push(\"---\", `title: ${opts.title}`, \"---\");\n  }\n  lines.push(\"stateDiagram-v2\");\n  lines.push(`  direction ${direction}`);\n\n  if (mode === \"reducer\") {\n    emitReducer(machine, lines);\n  } else {\n    emitTransitions(machine, lines, {\n      stateSamples,\n      msgSamples,\n      hasCtx,\n      ctx: opts.samples?.ctx,\n    });\n  }\n\n  // Subscriptions annotation — pure call to `subscriptions(sampleState)` per\n  // sampled state. Skipped entirely when no state samples are provided (we\n  // refuse to invent a state to feed it).\n  emitSubscriptions(machine, lines, stateSamples);\n\n  return lines.join(\"\\n\");\n}\n\n// === Reducer-form emission ===\n\n/**\n * Reducer form has no phase graph. Emit one node listing the handled msg types\n * plus an honest note. The msg set is the `update` record's keys (the Reducer\n * mapped type guarantees one cell per Msg variant).\n */\nfunction emitReducer(machine: { update: unknown }, lines: string[]): void {\n  const msgTypes = Object.keys(machine.update as object);\n  lines.push(\"  state ReducerMachine {\");\n  if (msgTypes.length === 0) {\n    lines.push(\"    [*] --> NoMsgs\");\n    lines.push('    NoMsgs : \"(no msg variants — M is never)\"');\n  } else {\n    for (const m of msgTypes) {\n      lines.push(`    ${safeId(m)} : ${safeLabel(m)}`);\n    }\n  }\n  lines.push(\"  }\");\n  // The note IS the design honesty: no edges, because reducer-form state is not\n  // a discriminated union over phases — there is no static target to draw.\n  lines.push(\"  note right of ReducerMachine\");\n  lines.push(\"    Reducer-form machine: flat dispatch keyed by msg.type.\");\n  lines.push(\n    \"    No phase graph — state is not a discriminated union over phases.\",\n  );\n  lines.push(`    Handled msg types: ${msgTypes.length}`);\n  lines.push(\"  end note\");\n}\n\n// === Transitions-form emission ===\n\ninterface TransitionsCtx<S, M> {\n  stateSamples: Partial<Record<string, S>>;\n  msgSamples: Partial<Record<string, M>>;\n  hasCtx: boolean;\n  ctx: unknown;\n}\n\n/**\n * Transitions form: walk the `update[stateType][msgType]` table. Execute the\n * (pure) cell when both samples exist → RESOLVED edge; otherwise → STRUCTURAL\n * self-loop. Draw the `[*] -->` init edge only when a ctx sample is given.\n */\nfunction emitTransitions<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  lines: string[],\n  ctx: TransitionsCtx<S, M>,\n): void {\n  type CellFn = (state: S, msg: M) => readonly [S, readonly C[]];\n  type Table = Record<string, Record<string, CellFn>>;\n  const table = machine.update as unknown as Table;\n  const stateTypes = Object.keys(table);\n\n  // Declare every node up front so even unreachable phases render.\n  for (const st of stateTypes) {\n    lines.push(`  ${safeId(st)}`);\n  }\n\n  // Init edge — only resolvable with a ctx sample. `init(null, ctx)` is pure\n  // (invariant 2: fresh-boot branch returns a starting state). Read `next.type`.\n  if (ctx.hasCtx) {\n    const [initState] = machine.init(null, ctx.ctx as Ctx);\n    const initType = (initState as unknown as { type: string }).type;\n    lines.push(`  [*] --> ${safeId(initType)}`);\n  } else {\n    lines.push(\n      \"  %% init edge omitted: no samples.ctx provided to run init(null, ctx)\",\n    );\n  }\n\n  let anyStructural = false;\n  for (const st of stateTypes) {\n    const row = table[st];\n    if (row === undefined) continue;\n    const msgTypes = Object.keys(row);\n    for (const mt of msgTypes) {\n      const edge = resolveEdge(row, st, mt, ctx);\n      if (edge.kind === \"resolved\") {\n        lines.push(\n          `  ${safeId(edge.from)} --> ${safeId(edge.to)} : ${safeLabel(edge.msg)}`,\n        );\n      } else {\n        anyStructural = true;\n        // Structural self-loop with a `?` suffix — target unresolved. Visually\n        // distinct from a resolved edge (self-loop + trailing `?`).\n        lines.push(\n          `  ${safeId(edge.from)} --> ${safeId(edge.from)} : ${safeLabel(edge.msg)}?`,\n        );\n      }\n    }\n  }\n\n  // Legend — document the resolved-vs-structural distinction in the output.\n  lines.push(`  note right of ${safeId(stateTypes[0] ?? \"_empty\")}`);\n  lines.push(\"    Transitions-form machine.\");\n  lines.push(\"    Edge a --> b : msg = RESOLVED (cell executed with samples).\");\n  if (anyStructural) {\n    lines.push(\n      \"    Self-loop a --> a : msg? = STRUCTURAL (no sample; target unresolved).\",\n    );\n  }\n  lines.push(\"  end note\");\n}\n\n/**\n * Resolve a single `(stateType, msgType)` cell into an Edge. With both a sample\n * state and a sample msg, EXECUTE the pure cell to read the real target. Any\n * missing sample → structural. A thrown cell (e.g. a sample shaped wrong for\n * the cell) degrades to structural rather than crashing the whole diagram —\n * the diagram is a best-effort visualization, not a correctness gate.\n */\nfunction resolveEdge<S, M extends { type: string }, C extends Cmd>(\n  row: Record<string, (state: S, msg: M) => readonly [S, readonly C[]]>,\n  stateType: string,\n  msgType: string,\n  ctx: {\n    stateSamples: Partial<Record<string, S>>;\n    msgSamples: Partial<Record<string, M>>;\n  },\n): Edge {\n  const sampleState = ctx.stateSamples[stateType];\n  const sampleMsg = ctx.msgSamples[msgType];\n  const cell = row[msgType];\n  if (\n    sampleState === undefined ||\n    sampleMsg === undefined ||\n    cell === undefined\n  ) {\n    return { kind: \"structural\", from: stateType, msg: msgType };\n  }\n  try {\n    const [next] = cell(sampleState, sampleMsg);\n    const to = (next as unknown as { type: string }).type;\n    return { kind: \"resolved\", from: stateType, to, msg: msgType };\n  } catch {\n    // Mismatched sample → cannot resolve. Fall back to structural.\n    return { kind: \"structural\", from: stateType, msg: msgType };\n  }\n}\n\n// === Subscriptions annotation ===\n\n/**\n * For each sampled state, call the (pure) `subscriptions(state)` description\n * function and annotate which Sub types are active in that state as a Mermaid\n * note. We call `subscriptions` (the description) but NEVER `subscribe[*]` (the\n * effectful installer) — same boundary `replay` honors. Skipped when no state\n * samples are provided or the machine declares no `subscriptions`.\n */\nfunction emitSubscriptions<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  lines: string[],\n  stateSamples: Partial<Record<string, S>>,\n): void {\n  if (machine.subscriptions === undefined) return;\n  const stateTypes = Object.keys(stateSamples);\n  if (stateTypes.length === 0) return;\n\n  for (const st of stateTypes) {\n    const sample = stateSamples[st];\n    if (sample === undefined) continue;\n    const subs = machine.subscriptions(sample);\n    const subTypes = subs.map((s) => s.type);\n    const body =\n      subTypes.length === 0\n        ? \"(no active subs)\"\n        : `subs: ${subTypes.map(safeLabel).join(\", \")}`;\n    lines.push(`  note left of ${safeId(st)}`);\n    lines.push(`    ${body}`);\n    lines.push(\"  end note\");\n  }\n}\n"]}

package/dist/reducer-BqyoVyBG.d.ts

@@ -0,0 +1,447 @@
+import { k as EventOrigin, C as Chart, R as ReducerChart } from './graph-CcjWZVrd.js';
+import { R as RtSamples } from './samples-DCt6nF8H.js';
+
+/**
+ * WHY a (state, event) pair is refused. The chart's three refusal mechanisms,
+ * each carrying the evidence that produced it, so a UI can say *"`WIP` is not
+ * addressed to `blocked` — its scope is `edges`"* rather than "disabled".
+ *
+ * `undeclared` is the fourth case the type layer forbids: a pair that is live,
+ * unhandled and unrefused. It cannot occur on a chart that compiled through
+ * `defineChart`, and it is reported rather than swallowed because reaching it
+ * means the types were bypassed with a cast — which is precisely when a
+ * debugger should say so instead of drawing a well-behaved button.
+ */
+type RefusalReason = {
+    readonly kind: "end";
+    /** Terminal state: it accepts nothing, by declaration. */
+    readonly state: string;
+} | {
+    readonly kind: "out-of-scope";
+    /** The event's declared `scope`, flattened to its members. */
+    readonly scope: readonly string[];
+    /** The phase this state lives in — the one that is not in `scope`. */
+    readonly phase: string;
+} | {
+    /**
+     * `scope: "edges"` — the event is live exactly where an edge declares it,
+     * and this state declares none.
+     *
+     * SPLIT OUT OF `out-of-scope` because the phase has nothing to do with it.
+     * `"edges"` is not a phase name, so the phase test could never pass and
+     * the refusal came back naming a phase the reader then went looking for:
+     * *"`DONE` is not addressed to phase `working` (scope: edges)"* — three
+     * pieces of vocabulary for one fact, and the fact is not in there. The
+     * default scope is `edges`, so this was most refusals on most charts.
+     */
+    readonly kind: "no-edge";
+    readonly state: string;
+} | {
+    readonly kind: "ignored";
+    /** The event is live here and this state refuses it BY NAME. */
+    readonly state: string;
+} | {
+    readonly kind: "undeclared";
+};
+/** A one-line, human-readable rendering of a {@link RefusalReason}. */
+declare function explainRefusal(event: string, reason: RefusalReason): string;
+/** What kind of transition an edge declares. */
+type EdgeKind = "plain" | "guarded" | "cell" | "resume";
+/** One declared edge — a `(state, event)` pair the chart routes. */
+interface ChartEdge {
+    readonly from: string;
+    readonly event: string;
+    /** `"${from}.${event}"` — the site key guards/cmds/cells are indexed by. */
+    readonly at: string;
+    readonly kind: EdgeKind;
+    /**
+     * Every state this edge can land on, in declaration order. A guarded edge
+     * contributes both arms; a cell edge contributes its whole declared `to`.
+     * For a resume edge this is the fallback alone — the real target is
+     * `state.was`, which is a property of the LIVE state, not of the chart.
+     */
+    readonly targets: readonly string[];
+    /** The guard's name, on a guarded edge. */
+    readonly guard?: string;
+    /** The target taken when the guard HOLDS. */
+    readonly then?: string;
+    /** The target taken when the guard FAILS. */
+    readonly otherwise?: string;
+    /** The cell's name, on a `{ to, cell }` edge. */
+    readonly cell?: string;
+    /** The declared fallback, on a `resume` edge. */
+    readonly fallback?: string;
+    /** Cmds fired when the edge fires (the guard's `then` arm, if guarded). */
+    readonly cmds: readonly string[];
+    /** Cmds fired when the guard FAILS. Empty unless the edge is guarded. */
+    readonly otherwiseCmds: readonly string[];
+}
+/** A (state, event) pair the chart explicitly refuses, and why. */
+interface ChartRefusal {
+    readonly from: string;
+    readonly event: string;
+    readonly reason: RefusalReason;
+}
+/** One state, with the facts the chart declares about it. */
+interface ChartStateInfo {
+    readonly name: string;
+    /** The phase it was declared under. */
+    readonly phase: string;
+    /** `initial: true` — the entry state. Exactly one per machine-bearing chart. */
+    readonly initial: boolean;
+    /**
+     * Terminal by DECLARATION, not by "has no outgoing edges" — `true` for both
+     * polarities, because both accept nothing and both owe nothing.
+     */
+    readonly end: boolean;
+    /**
+     * WHICH ending. `true` a success final, `"error"` the failure terminal,
+     * `false` not a final at all.
+     *
+     * `end` answers "does this accept anything"; this answers "did the machine
+     * win or lose". A lane needs both and they are not the same question —
+     * `shipped` and `frozen` are equally terminal and are not the same outcome.
+     */
+    readonly endPolarity: false | true | "error";
+    /** Carries a `resume` edge out of it, so the compiler injects `was` here. */
+    readonly parking: boolean;
+}
+/** One event of the alphabet. */
+interface ChartEventInfo {
+    readonly name: string;
+    /** The declared `scope`, flattened: `"edges"`, `"all"`, or phase names. */
+    readonly scope: readonly string[];
+    /** `foreign: true` — the name belongs to someone else and stays bare. */
+    readonly foreign: boolean;
+    /**
+     * WHERE THIS EVENT COMES FROM — `from`, read back off the chart.
+     *
+     * `undefined` means the chart does not say, which is a fact of its own and
+     * never a default: a UI that groups its button row by sender must render the
+     * undeclared ones as undeclared rather than filing them under a guess.
+     */
+    readonly from?: EventOrigin;
+    /**
+     * Whether the event DECLARED a payload (`data: ty<…>()`).
+     *
+     * `ty<T>()` is `{}` at runtime, so `T` is unreadable — but the `data` KEY is
+     * right there in the literal, so "does this event carry a payload at all" IS
+     * a runtime fact. It is what decides whether a sample is required.
+     */
+    readonly hasPayload: boolean;
+}
+/**
+ * A whole chart, as data a UI can build itself from. Nothing here is supplied
+ * by the caller; every field is read off the one chart value.
+ */
+interface ChartDescription {
+    /** The phases, in declaration order, each with its member states. */
+    readonly phases: readonly {
+        readonly name: string;
+        readonly states: readonly string[];
+    }[];
+    readonly states: readonly ChartStateInfo[];
+    /** The state marked `initial: true`, or `undefined` on a chart with none. */
+    readonly initial: string | undefined;
+    readonly events: readonly ChartEventInfo[];
+    /** Every cmd DECLARED in the `cmds` section — the effect alphabet. */
+    readonly cmds: readonly string[];
+    /** Every guard name any edge references. */
+    readonly guards: readonly string[];
+    /** Every cell name any `{ to, cell }` edge references. */
+    readonly cells: readonly string[];
+    readonly edges: readonly ChartEdge[];
+    readonly refusals: readonly ChartRefusal[];
+}
+/**
+ * A read edge MINUS the state it leaves — everything about an edge that is a
+ * fact of the edge itself rather than of the grid it sits in.
+ *
+ * The reducer form has no state dimension (`src/chart/inspect/reducer.ts`), so
+ * its edges are exactly this: same kinds, same targets, same guard/cell/cmd
+ * fields, with `from` unrepresentable rather than blank.
+ */
+type EdgeCore = Omit<ChartEdge, "from">;
+/**
+ * Read a chart into its {@link ChartDescription}.
+ *
+ * Pure, total, and allocation-only — it never executes a guard, a cell or a
+ * payload builder, so it is safe on a chart whose parts do not exist yet.
+ */
+declare function describeChart<const C extends Chart<C>>(chart: C): ChartDescription;
+/** The declared edge out of `state` on `event`, or `undefined`. */
+declare function edgeAt(desc: ChartDescription, state: string, event: string): ChartEdge | undefined;
+/** Why `state` refuses `event`, or `undefined` when it does not. */
+declare function refusalAtState(desc: ChartDescription, state: string, event: string): RefusalReason | undefined;
+/** The record for `state`, or `undefined` when the chart has no such state. */
+declare function stateInfo(desc: ChartDescription, state: string): ChartStateInfo | undefined;
+
+/** Any guard, however narrowly its use sites typed it. */
+type AnyGuard = (...args: never[]) => boolean;
+/** Any cell, in either the single-body or the per-site form. */
+type AnyCell = ((...args: never[]) => readonly [{
+    readonly type: string;
+}, unknown]) | Readonly<Record<string, unknown>>;
+/**
+ * The code parts a preview may consult — the SAME bag `compile` receives, so
+ * an author passes the one they already built rather than a second copy.
+ * Every field is optional: the preview degrades where a part is absent.
+ */
+interface InspectParts {
+    readonly guards?: Readonly<Record<string, AnyGuard | undefined>>;
+    readonly cells?: Readonly<Record<string, AnyCell | undefined>>;
+}
+/** Everything a live preview may consult, beyond the state itself. */
+interface InspectOptions {
+    /** The parts bag `compile` was given. Guards/cells are read from it. */
+    readonly parts?: InspectParts;
+    /** Sample payload per event — see `./samples`. */
+    readonly samples?: RtSamples;
+}
+/** Why a guard could not be evaluated. Each is a fact, not a guess. */
+type GuardUnknown = "no-guard-bag" | "no-implementation" | "no-sample" | "threw";
+/**
+ * Which branch a guarded edge would take right now.
+ *
+ * `then` / `else` are ANSWERS — the guard ran, on this state, with this msg.
+ * `unknown` is the honest non-answer, carrying the reason and (for a throwing
+ * guard) the message, so a UI shows "cannot evaluate: no sample for FAIL"
+ * rather than a confidently wrong arrow.
+ */
+type GuardPreview = {
+    readonly guard: string;
+    readonly branch: "then" | "else";
+    /** The state that branch lands on. */
+    readonly target: string;
+    /** The cmds that branch fires. */
+    readonly cmds: readonly string[];
+} | {
+    readonly guard: string;
+    readonly branch: "unknown";
+    readonly why: GuardUnknown;
+    /** The thrown error's message, when `why` is `"threw"`. */
+    readonly error?: string;
+};
+/** How a single target was determined, when one could be. */
+type ResolvedBy = "declared" | "guard" | "resume" | "cell";
+/**
+ * What would happen if `event` were dispatched at the current state.
+ *
+ * A refusal is FIRST-CLASS: it carries the reason and a rendered explanation,
+ * so a UI draws it as visibly refused rather than omitting the control. That
+ * is the totality property paying rent — the chart knows the difference
+ * between "not routed here", "deliberately dropped here" and "this state is
+ * over", and a debugger that hides all three behind a missing button throws
+ * away the one thing this substrate knows and others do not.
+ */
+interface EventPreview {
+    readonly event: string;
+    readonly status: "legal" | "refused";
+    /**
+     * Who would send this — the event's declared `from`, carried through rather
+     * than recomputed, so a button row can be grouped by sender with the same
+     * answer the report's "waiting on" line gives. `undefined` when the chart
+     * does not say.
+     */
+    readonly from?: EventOrigin;
+    /** Present iff `status` is `"refused"`. */
+    readonly reason?: RefusalReason;
+    /** A one-line rendering of `reason`. Present iff refused. */
+    readonly why?: string;
+    /** The declared edge. Present iff legal. */
+    readonly edge?: ChartEdge;
+    /** Present iff the edge is guarded. */
+    readonly guard?: GuardPreview;
+    /**
+     * The cmds that WOULD fire — read off the edge's declaration. For a guarded
+     * edge whose branch resolved, the cmds of THAT arm; for one that did not, the
+     * `then` arm's (the declared happy path) — `guard.branch === "unknown"` is
+     * what says so.
+     *
+     * This is the BEFORE question, and a `{ to, cell }` edge answers it with an
+     * empty list BY DECLARATION: the cell builds its cmds inside its body, so the
+     * chart has none to declare. For what actually fired, ask the after question
+     * — `captureCmds` in `./captured`, which reads the emitted cmds off the
+     * machine's own output.
+     */
+    readonly cmds: readonly string[];
+    /** Every state the edge declares it can reach. */
+    readonly targets: readonly string[];
+    /** The single target, when one is determined. */
+    readonly resolved?: string;
+    /** How {@link EventPreview.resolved} was determined. */
+    readonly resolvedBy?: ResolvedBy;
+    /**
+     * The msg this preview used — the sample plus the chart's `type`. `undefined`
+     * when the event declares a payload and no sample was supplied, which is
+     * also why a guard or cell may have come back `unknown`.
+     */
+    readonly msg?: {
+        readonly type: string;
+    };
+}
+/**
+ * Preview one event against a live state.
+ *
+ * @param desc  the chart's {@link ChartDescription}.
+ * @param state the live state — anything with a `type` (and `was`, on a
+ *              parking state, which is what makes a resume target resolvable).
+ */
+declare function previewEvent<S extends {
+    readonly type: string;
+}>(desc: ChartDescription, state: S, event: string, opts?: InspectOptions): EventPreview;
+/**
+ * Preview EVERY event of the alphabet against a live state, in the chart's
+ * declaration order.
+ *
+ * This is the button row: one entry per declared event, each either legal
+ * (with its branch, targets and cmds) or refused (with its reason). Nothing is
+ * filtered out — a refused event is a control the UI draws, not one it lacks.
+ */
+declare function inspectState<S extends {
+    readonly type: string;
+}>(desc: ChartDescription, state: S, opts?: InspectOptions): readonly EventPreview[];
+/**
+ * {@link inspectState}, plus the two roll-ups a caller almost always wants
+ * next: the legal event names and the refused ones.
+ *
+ * The whole verdict list is still there — the split is a convenience, not a
+ * filter, and `events` remains the surface a UI renders so a refusal keeps its
+ * reason.
+ */
+declare function inspectStateSummary<S extends {
+    readonly type: string;
+}>(desc: ChartDescription, state: S, opts?: InspectOptions): {
+    readonly state: S;
+    readonly events: readonly EventPreview[];
+    readonly legal: readonly string[];
+    readonly refused: readonly string[];
+};
+
+/**
+ * A QUESTION THIS FORM CANNOT ANSWER, carried in the slot where the grid form
+ * carries the answer.
+ *
+ * `answerable: false` is the whole type: there is no `true` member, because a
+ * question this form CAN answer is answered with the answer. So `desc.refusals`
+ * on a reducer description is not an empty list a UI silently renders — it is a
+ * value whose only shape says why the list is not there, and code written
+ * against the grid form's array fails to compile against it.
+ */
+interface Unanswerable<Q extends string> {
+    readonly answerable: false;
+    /** Which question — the grid-form field this stands in for. */
+    readonly question: Q;
+    /** One line, ready to render. */
+    readonly why: string;
+}
+/** One edge of a reducer chart — an edge with no state to leave from. */
+type ReducerEdge = EdgeCore;
+/** One event of a reducer chart's alphabet. `scope` has no counterpart here. */
+interface ReducerEventInfo {
+    readonly name: string;
+    /** `foreign: true` — the name belongs to someone else and stays bare. */
+    readonly foreign: boolean;
+    /** WHO SENDS THIS. `undefined` means the chart does not say — never a guess. */
+    readonly from?: EventOrigin;
+    /** Whether the event declared a payload (`data: ty<…>()`). */
+    readonly hasPayload: boolean;
+    /** `false` iff the chart declares this event and routes it nowhere. */
+    readonly routed: boolean;
+}
+/**
+ * A reducer-form chart, as data a UI can build itself from — the same contract
+ * as {@link import("./describe").ChartDescription}, over the facts this form
+ * actually has.
+ */
+interface ReducerChartDescription {
+    /** The declared state names, in declaration order. Flat: there are no groups. */
+    readonly states: readonly string[];
+    /** The entry state — the chart's `initial` field, not a marked node. */
+    readonly initial: string;
+    readonly events: readonly ReducerEventInfo[];
+    /** Every cmd DECLARED in the `cmds` section — the effect alphabet. */
+    readonly cmds: readonly string[];
+    readonly guards: readonly string[];
+    readonly cells: readonly string[];
+    /** One edge per routed event, in the alphabet's declaration order. */
+    readonly edges: readonly ReducerEdge[];
+    /**
+     * TOTALITY, read back off the value: `true` iff every declared event owes and
+     * has an edge. Through the typed door this is always `true` — `on` is a
+     * required mapped type — so a `false` here means the types were bypassed with
+     * a cast, exactly as `refusals`' `undeclared` kind does in the grid form.
+     */
+    readonly total: boolean;
+    /** The declared events with no edge. Empty through the typed door. */
+    readonly missing: readonly string[];
+    /** NOT AVAILABLE — see {@link Unanswerable}. */
+    readonly phases: Unanswerable<"phases">;
+    /** NOT AVAILABLE — see {@link Unanswerable}. */
+    readonly refusals: Unanswerable<"refusals">;
+    /** NOT AVAILABLE — see {@link Unanswerable}. */
+    readonly scope: Unanswerable<"scope">;
+}
+/**
+ * Read a reducer-form chart into its {@link ReducerChartDescription}.
+ *
+ * Pure, total and allocation-only, exactly as `describeChart` is: it never runs
+ * a guard, a cell or a payload builder, so it is safe on a chart whose parts do
+ * not exist yet.
+ */
+declare function describeReducerChart<const C extends ReducerChart<C>>(chart: C): ReducerChartDescription;
+/** The edge that routes `event`, or `undefined` when the chart routes it nowhere. */
+declare function reducerEdgeAt(desc: ReducerChartDescription, event: string): ReducerEdge | undefined;
+/**
+ * What would happen if `event` were dispatched at the current state.
+ *
+ * There is NO `status` field, and its absence is the honest part: this form
+ * cannot refuse an event — `on` is total over the alphabet and there is no
+ * state dimension to refuse from — so a "legal" tag would be a distinction
+ * without a second case. Everything a grid preview can still say here it says:
+ * the edge, the guard's branch, the declared fan-out, the target a cell picks.
+ *
+ * The cmds are the DECLARED ones — the before question. For what actually
+ * fired, see `captureCmds` in `./captured`.
+ */
+interface ReducerEventPreview {
+    readonly event: string;
+    /** The event's declared `from`, carried through rather than recomputed. */
+    readonly from?: EventOrigin;
+    /** The declared edge. `undefined` only when the chart routes the event nowhere. */
+    readonly edge?: ReducerEdge;
+    /** Present iff the edge is guarded. */
+    readonly guard?: GuardPreview;
+    /** The cmds the edge DECLARES for the arm that resolved. */
+    readonly cmds: readonly string[];
+    /** Every state the edge declares it can reach. */
+    readonly targets: readonly string[];
+    /** The single target, when one is determined. */
+    readonly resolved?: string;
+    /** How {@link ReducerEventPreview.resolved} was determined. */
+    readonly resolvedBy?: ResolvedBy;
+    /** The msg this preview used, or `undefined` when no sample was supplied. */
+    readonly msg?: {
+        readonly type: string;
+    };
+}
+/**
+ * Preview one event of a reducer chart against a live state.
+ *
+ * The guard and cell previews are the SAME functions the grid form uses — a
+ * guard is pure and a cell is pure in both forms, and the only difference is
+ * that `at` is the bare event name.
+ */
+declare function previewReducerEvent<S extends {
+    readonly type: string;
+}>(desc: ReducerChartDescription, state: S, event: string, opts?: InspectOptions): ReducerEventPreview;
+/**
+ * Preview EVERY event of a reducer chart's alphabet against a live state, in
+ * declaration order. The button row — and here every control is live, because
+ * this form has nothing with which to refuse one.
+ */
+declare function inspectReducerState<S extends {
+    readonly type: string;
+}>(desc: ReducerChartDescription, state: S, opts?: InspectOptions): readonly ReducerEventPreview[];
+
+export { type AnyCell as A, type ChartDescription as C, type EdgeCore as E, type GuardPreview as G, type InspectOptions as I, type ReducerChartDescription as R, type Unanswerable as U, type AnyGuard as a, type ChartEdge as b, type ChartEventInfo as c, type ChartRefusal as d, type ChartStateInfo as e, type EdgeKind as f, type EventPreview as g, type GuardUnknown as h, type InspectParts as i, type ReducerEdge as j, type ReducerEventInfo as k, type ReducerEventPreview as l, type RefusalReason as m, type ResolvedBy as n, describeChart as o, describeReducerChart as p, edgeAt as q, explainRefusal as r, inspectReducerState as s, inspectState as t, inspectStateSummary as u, previewEvent as v, previewReducerEvent as w, reducerEdgeAt as x, refusalAtState as y, stateInfo as z };