@entifix/core 0.1.0-0

package/dist/wizard/wizard-definition.js

@@ -0,0 +1,125 @@
+import { EntifixBuildError } from '../base-entities/entifix-error/index.js';
+/**
+ * What a step holds, which decides how its value is stored and edited.
+ *
+ * `form` is one `useEntityForm` instance over part of an entity; `selection` is
+ * a table step whose value is a set of ids; `choice` is a branch point offering
+ * a fixed list of options; `summary` is the read-only recap; `custom` is
+ * anything else the host renders and reads itself.
+ */ export const WizardStepKinds = [
+    'form',
+    'selection',
+    'choice',
+    'summary',
+    'custom'
+];
+/** The step a flow starts at: the first declared. */ export const entryStep = (definition)=>{
+    const [first] = definition.steps;
+    if (first === undefined) {
+        throw new EntifixBuildError(`wizard "${definition.key}" declares no steps`);
+    }
+    return first;
+};
+/** The step with this id, or `undefined` when the definition has none. */ export const findStep = (definition, stepId)=>definition.steps.find((step)=>step.id === stepId);
+/**
+ * Checks a definition the moment it is declared, and throws rather than
+ * degrading.
+ *
+ * **Load time, not step time.** A wizard whose last step is missing, or whose
+ * branch names a step that does not exist, must fail on the first render of any
+ * surface rather than on the render of the step nobody reached — otherwise the
+ * failure of the longest flow in the product arrives at the end of it. That is
+ * the posture `assertLinkSourcesAreEditable` and `surfaceFor` already take
+ * ([ADR 0035](../../../../../../docs/adr/0035-entity-actions-selection-and-bulk.md)).
+ *
+ * Six faults, each of which is silent otherwise:
+ *
+ * - **no steps**, which renders an empty frame with a disabled button;
+ * - **a duplicate id**, which makes one step's stored value overwrite another's;
+ * - **an unknown `to` target**, a typo that strands the flow mid-way;
+ * - **several edges and no `next`**, which cannot say where the step goes;
+ * - **a step nothing reaches**, which is either a dead branch or a missing edge;
+ * - **the wrong terminal step** — the flow must end in the summary, and there
+ *   must be exactly one of those. A wizard ending anywhere else commits without
+ *   the operator ever seeing what they answered, which
+ *   [#111](https://github.com/r10c-technologies/r10c/issues/111) records as not
+ *   optional.
+ *
+ * A cycle needs no separate check: every step is reachable from the entry and
+ * exactly one is terminal, so a cycle would leave the steps on it unable to
+ * reach that terminal, which the walk below reports as unreachable-from-here.
+ */ export function assertWizardDefinition(definition) {
+    const first = entryStep(definition);
+    const ids = new Set();
+    for (const step of definition.steps){
+        if (ids.has(step.id)) {
+            throw new EntifixBuildError(`wizard "${definition.key}" declares step "${step.id}" twice`);
+        }
+        ids.add(step.id);
+    }
+    for (const step of definition.steps){
+        assertStepOptions(definition, step);
+        for (const target of step.to){
+            if (!ids.has(target)) {
+                throw new EntifixBuildError(`wizard "${definition.key}" step "${step.id}" leads to unknown step "${target}"`);
+            }
+        }
+        if (step.to.length > 1 && step.next === undefined) {
+            throw new EntifixBuildError(`wizard "${definition.key}" step "${step.id}" has ${step.to.length} edges and no next()`);
+        }
+    }
+    assertOneSummaryAtTheEnd(definition);
+    assertEveryStepIsReachable(definition, first);
+}
+/** `options` belongs to `choice` and to nothing else. */ function assertStepOptions(definition, step) {
+    if (step.kind === 'choice') {
+        if (step.options === undefined || step.options.length === 0) {
+            throw new EntifixBuildError(`wizard "${definition.key}" choice step "${step.id}" offers no options`);
+        }
+        return;
+    }
+    if (step.options !== undefined) {
+        throw new EntifixBuildError(`wizard "${definition.key}" step "${step.id}" is a ${step.kind} step and cannot declare options`);
+    }
+}
+/** Exactly one summary, and it is the only step the flow may end on. */ function assertOneSummaryAtTheEnd(definition) {
+    const summaries = definition.steps.filter((step)=>step.kind === 'summary');
+    if (summaries.length !== 1) {
+        throw new EntifixBuildError(`wizard "${definition.key}" declares ${summaries.length} summary steps, and must declare exactly one`);
+    }
+    for (const step of definition.steps){
+        const terminal = step.to.length === 0;
+        if (terminal && step.kind !== 'summary') {
+            throw new EntifixBuildError(`wizard "${definition.key}" ends on "${step.id}", which is not its summary`);
+        }
+        if (!terminal && step.kind === 'summary') {
+            throw new EntifixBuildError(`wizard "${definition.key}" summary step "${step.id}" leads onward, and must end the flow`);
+        }
+    }
+}
+/** Every declared step is on some path out of the entry step. */ function assertEveryStepIsReachable(definition, first) {
+    const seen = new Set([
+        first.id
+    ]);
+    // A fixpoint over `seen` rather than a queue of resolved steps: every target
+    // has already been checked to name a declared step, so a walk that looked one
+    // up would carry an `undefined` arm nothing can reach — and an unreachable
+    // arm is indistinguishable from an untested one.
+    for(let grew = true; grew;){
+        grew = false;
+        for (const step of definition.steps){
+            if (!seen.has(step.id)) continue;
+            for (const target of step.to){
+                if (seen.has(target)) continue;
+                seen.add(target);
+                grew = true;
+            }
+        }
+    }
+    const stranded = definition.steps.filter((step)=>!seen.has(step.id)).map((step)=>step.id);
+    if (stranded.length > 0) {
+        throw new EntifixBuildError(`wizard "${definition.key}" cannot reach ${stranded.map((id)=>`"${id}"`).join(', ')} from "${first.id}"`);
+    }
+}
+
+//# sourceMappingURL=wizard-definition.js.map

package/dist/wizard/wizard-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/wizard/wizard-definition.ts"],"sourcesContent":["import { EntifixBuildError } from '../base-entities/entifix-error/index.js';\n\n/**\n * What a step holds, which decides how its value is stored and edited.\n *\n * `form` is one `useEntityForm` instance over part of an entity; `selection` is\n * a table step whose value is a set of ids; `choice` is a branch point offering\n * a fixed list of options; `summary` is the read-only recap; `custom` is\n * anything else the host renders and reads itself.\n */\nexport const WizardStepKinds = [\n  'form',\n  'selection',\n  'choice',\n  'summary',\n  'custom',\n] as const;\nexport type WizardStepKind = (typeof WizardStepKinds)[number];\n\n/**\n * One step, and the edges out of it.\n *\n * **The graph is data; `next` only chooses along it.** `to` lists the steps this\n * one may lead to, so reachability, unknown targets, cycles and terminality are\n * decidable by reading the definition — no probing, no enumeration of the state\n * space, and no rule that \"only appears to hold\" because a `next` reading a form\n * value could never be enumerated. It is the move\n * [ADR 0039](../../../../../../docs/adr/0039-multi-step-sagas-are-orchestrated.md)\n * made for saga steps, for the same reason: a walkable definition is checkable\n * at load, and a function is not.\n *\n * A step with an empty `to` is **terminal**, and\n * {@link assertWizardDefinition} requires that to be the summary.\n */\nexport interface WizardStep {\n  readonly id: string;\n  readonly kind: WizardStepKind;\n  /** Catalog key for the stepper's label. Resolved by the renderer, never here. */\n  readonly labelKey: string;\n  /**\n   * The options a `choice` step offers, as stable identifiers.\n   *\n   * Required on `choice` and forbidden elsewhere: the value of a choice step is\n   * one of these strings, so a choice with no options can never be answered and\n   * options on a form step describe nothing.\n   */\n  readonly options?: readonly string[];\n  /** Every step this one may lead to. Empty means the flow ends here. */\n  readonly to: readonly string[];\n  /**\n   * Which of {@link WizardStep.to} comes next, given everything answered so far.\n   *\n   * Optional, and omitting it is the ordinary case: a step with exactly one edge\n   * needs no function to pick it. A step with several **must** declare one, or\n   * the definition cannot say where it goes.\n   *\n   * It returns a step id and never `undefined`: **the end of the flow is an\n   * empty `to`, not a `next` that declines**. Two ways of saying the same thing\n   * would let a step be terminal in one of them and not the other, and it is\n   * `to` that {@link assertWizardDefinition} can read.\n   */\n  next?(state: WizardStateLike): string;\n}\n\n/**\n * The part of the state a `next` may read.\n *\n * Declared structurally rather than importing `WizardState`, so the definition\n * module stays below the state module and neither has to import the other.\n */\nexport interface WizardStateLike {\n  readonly activeStep: string;\n  readonly steps: { readonly [stepId: string]: unknown };\n}\n\n/**\n * A whole wizard: its key — which is also its screen key in a workspace address\n * — and its steps, the first of which is where the flow begins.\n */\nexport interface WizardDefinition {\n  readonly key: string;\n  readonly steps: readonly WizardStep[];\n}\n\n/** The step a flow starts at: the first declared. */\nexport const entryStep = (definition: WizardDefinition): WizardStep => {\n  const [first] = definition.steps;\n  if (first === undefined) {\n    throw new EntifixBuildError(`wizard \"${definition.key}\" declares no steps`);\n  }\n  return first;\n};\n\n/** The step with this id, or `undefined` when the definition has none. */\nexport const findStep = (\n  definition: WizardDefinition,\n  stepId: string,\n): WizardStep | undefined => definition.steps.find(step => step.id === stepId);\n\n/**\n * Checks a definition the moment it is declared, and throws rather than\n * degrading.\n *\n * **Load time, not step time.** A wizard whose last step is missing, or whose\n * branch names a step that does not exist, must fail on the first render of any\n * surface rather than on the render of the step nobody reached — otherwise the\n * failure of the longest flow in the product arrives at the end of it. That is\n * the posture `assertLinkSourcesAreEditable` and `surfaceFor` already take\n * ([ADR 0035](../../../../../../docs/adr/0035-entity-actions-selection-and-bulk.md)).\n *\n * Six faults, each of which is silent otherwise:\n *\n * - **no steps**, which renders an empty frame with a disabled button;\n * - **a duplicate id**, which makes one step's stored value overwrite another's;\n * - **an unknown `to` target**, a typo that strands the flow mid-way;\n * - **several edges and no `next`**, which cannot say where the step goes;\n * - **a step nothing reaches**, which is either a dead branch or a missing edge;\n * - **the wrong terminal step** — the flow must end in the summary, and there\n *   must be exactly one of those. A wizard ending anywhere else commits without\n *   the operator ever seeing what they answered, which\n *   [#111](https://github.com/r10c-technologies/r10c/issues/111) records as not\n *   optional.\n *\n * A cycle needs no separate check: every step is reachable from the entry and\n * exactly one is terminal, so a cycle would leave the steps on it unable to\n * reach that terminal, which the walk below reports as unreachable-from-here.\n */\nexport function assertWizardDefinition(definition: WizardDefinition): void {\n  const first = entryStep(definition);\n  const ids = new Set<string>();\n\n  for (const step of definition.steps) {\n    if (ids.has(step.id)) {\n      throw new EntifixBuildError(\n        `wizard \"${definition.key}\" declares step \"${step.id}\" twice`,\n      );\n    }\n    ids.add(step.id);\n  }\n\n  for (const step of definition.steps) {\n    assertStepOptions(definition, step);\n\n    for (const target of step.to) {\n      if (!ids.has(target)) {\n        throw new EntifixBuildError(\n          `wizard \"${definition.key}\" step \"${step.id}\" leads to unknown step \"${target}\"`,\n        );\n      }\n    }\n\n    if (step.to.length > 1 && step.next === undefined) {\n      throw new EntifixBuildError(\n        `wizard \"${definition.key}\" step \"${step.id}\" has ${step.to.length} edges and no next()`,\n      );\n    }\n  }\n\n  assertOneSummaryAtTheEnd(definition);\n  assertEveryStepIsReachable(definition, first);\n}\n\n/** `options` belongs to `choice` and to nothing else. */\nfunction assertStepOptions(\n  definition: WizardDefinition,\n  step: WizardStep,\n): void {\n  if (step.kind === 'choice') {\n    if (step.options === undefined || step.options.length === 0) {\n      throw new EntifixBuildError(\n        `wizard \"${definition.key}\" choice step \"${step.id}\" offers no options`,\n      );\n    }\n    return;\n  }\n  if (step.options !== undefined) {\n    throw new EntifixBuildError(\n      `wizard \"${definition.key}\" step \"${step.id}\" is a ${step.kind} step and cannot declare options`,\n    );\n  }\n}\n\n/** Exactly one summary, and it is the only step the flow may end on. */\nfunction assertOneSummaryAtTheEnd(definition: WizardDefinition): void {\n  const summaries = definition.steps.filter(step => step.kind === 'summary');\n  if (summaries.length !== 1) {\n    throw new EntifixBuildError(\n      `wizard \"${definition.key}\" declares ${summaries.length} summary steps, and must declare exactly one`,\n    );\n  }\n\n  for (const step of definition.steps) {\n    const terminal = step.to.length === 0;\n    if (terminal && step.kind !== 'summary') {\n      throw new EntifixBuildError(\n        `wizard \"${definition.key}\" ends on \"${step.id}\", which is not its summary`,\n      );\n    }\n    if (!terminal && step.kind === 'summary') {\n      throw new EntifixBuildError(\n        `wizard \"${definition.key}\" summary step \"${step.id}\" leads onward, and must end the flow`,\n      );\n    }\n  }\n}\n\n/** Every declared step is on some path out of the entry step. */\nfunction assertEveryStepIsReachable(\n  definition: WizardDefinition,\n  first: WizardStep,\n): void {\n  const seen = new Set<string>([first.id]);\n\n  // A fixpoint over `seen` rather than a queue of resolved steps: every target\n  // has already been checked to name a declared step, so a walk that looked one\n  // up would carry an `undefined` arm nothing can reach — and an unreachable\n  // arm is indistinguishable from an untested one.\n  for (let grew = true; grew;) {\n    grew = false;\n    for (const step of definition.steps) {\n      if (!seen.has(step.id)) continue;\n      for (const target of step.to) {\n        if (seen.has(target)) continue;\n        seen.add(target);\n        grew = true;\n      }\n    }\n  }\n\n  const stranded = definition.steps\n    .filter(step => !seen.has(step.id))\n    .map(step => step.id);\n\n  if (stranded.length > 0) {\n    throw new EntifixBuildError(\n      `wizard \"${definition.key}\" cannot reach ${stranded.map(id => `\"${id}\"`).join(', ')} from \"${first.id}\"`,\n    );\n  }\n}\n"],"names":["EntifixBuildError","WizardStepKinds","entryStep","definition","first","steps","undefined","key","findStep","stepId","find","step","id","assertWizardDefinition","ids","Set","has","add","assertStepOptions","target","to","length","next","assertOneSummaryAtTheEnd","assertEveryStepIsReachable","kind","options","summaries","filter","terminal","seen","grew","stranded","map","join"],"mappings":"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"}

package/dist/wizard/wizard-navigation.d.ts

@@ -0,0 +1,81 @@
+import { type WizardDefinition } from './wizard-definition.js';
+import type { WizardState } from './wizard-state.js';
+/** How a step reads in the stepper. */
+export declare const WizardStepStatuses: readonly ["pending", "active", "complete", "error"];
+export type WizardStepStatus = (typeof WizardStepStatuses)[number];
+/**
+ * Where the active step leads, or `undefined` when it ends the flow.
+ *
+ * A step with one edge needs no `next`; a step with several declares one, and
+ * what it returns **must** be an edge the step declared. That check is an
+ * {@link EntifixLogicError} rather than a silent fallback because the two ways
+ * of being wrong are both invisible otherwise: returning an id from another
+ * branch strands the operator on a step whose earlier answers were never given,
+ * and returning a typo would read as "this wizard has ended" one step early.
+ */
+export declare function nextStepId(definition: WizardDefinition, state: WizardState): string | undefined;
+/**
+ * The state one step further on, or the same state when there is nowhere to go.
+ *
+ * Unchanged rather than throwing on a terminal step: the button that calls this
+ * is the one {@link canFinish} turns into Finalizar, so reaching here means the
+ * caller asked twice, not that the definition is wrong.
+ */
+export declare function advanceWizard(definition: WizardDefinition, state: WizardState): WizardState;
+/**
+ * The state one step back, or the same state at the entry step.
+ *
+ * It pops {@link WizardState.history} rather than inverting `next`, which is the
+ * whole reason that history is stored: a branch's inverse is ambiguous the
+ * moment an earlier answer changes, so a computed one walks the operator back
+ * through a path they were never on.
+ */
+export declare function goBackWizard(state: WizardState): WizardState;
+/**
+ * Jump to a step already visited.
+ *
+ * Backwards only, and to a step **on the current path** — a stepper may make a
+ * completed step clickable, and nothing else. Jumping forward would skip the
+ * per-step submit that validates the steps in between, which is the one thing
+ * gating advancement at all; jumping to a step on an abandoned branch would put
+ * the operator somewhere their current answers do not lead.
+ *
+ * The history truncates to before the target, exactly as arriving there by
+ * pressing Back repeatedly would leave it.
+ */
+export declare function goToWizardStep(state: WizardState, stepId: string): WizardState;
+/** Whether the active step ends the flow, so its button reads Finalizar. */
+export declare const canFinish: (definition: WizardDefinition, state: WizardState) => boolean;
+/**
+ * The steps this flow runs through, given what has been answered — the ones
+ * already visited, the active one, and the ones ahead.
+ *
+ * **Projected, not the declared list.** A graph's step list contains branches
+ * not taken, so rendering `definition.steps` would show a stepper promising a
+ * "duplicate" step to an operator who chose to start blank. Walking forward from
+ * the active step with the current answers is what makes the stepper honest:
+ * it re-shapes as a branch point is answered, which is the visible half of the
+ * step graph being a graph.
+ *
+ * The walk stops on a step it has already placed, which is what makes it
+ * terminate: every pass either adds a step to a finite set or stops. A
+ * definition that cycles therefore produces a finite path rather than hanging
+ * the render — `assertWizardDefinition` has already refused such a definition at
+ * load, and this exists because a render loop is a worse way to find out.
+ */
+export declare function wizardPath(definition: WizardDefinition, state: WizardState): readonly string[];
+/**
+ * Each step on the projected path, with how it reads.
+ *
+ * `errored` is supplied by the caller rather than derived, because validity is
+ * the step's own knowledge: a form step's errors live in its `useEntityForm`
+ * instance, and this module is framework-free and holds none of them.
+ *
+ * An error wins over `complete` — a step the operator has been through and left
+ * invalid is exactly the one the stepper has to point at.
+ */
+export declare function stepStatuses(definition: WizardDefinition, state: WizardState, errored?: readonly string[]): ReadonlyArray<{
+    readonly id: string;
+    readonly status: WizardStepStatus;
+}>;
+//# sourceMappingURL=wizard-navigation.d.ts.map

package/dist/wizard/wizard-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wizard-navigation.d.ts","sourceRoot":"","sources":["../../src/wizard/wizard-navigation.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,uCAAuC;AACvC,eAAO,MAAM,kBAAkB,qDAKrB,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,WAAW,GACjB,MAAM,GAAG,SAAS,CAcpB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,WAAW,GACjB,WAAW,CASb;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAS5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,GACb,WAAW,CASb;AAED,4EAA4E;AAC5E,eAAO,MAAM,SAAS,GACpB,YAAY,gBAAgB,EAC5B,OAAO,WAAW,KACjB,OAAsD,CAAC;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,WAAW,GACjB,SAAS,MAAM,EAAE,CAcnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,SAAS,MAAM,EAAO,GAC9B,aAAa,CAAC;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAO3E"}

package/dist/wizard/wizard-navigation.js

@@ -0,0 +1,139 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { EntifixLogicError } from '../base-entities/entifix-error/index.js';
+import { findStep } from './wizard-definition.js';
+/** How a step reads in the stepper. */ export const WizardStepStatuses = [
+    'pending',
+    'active',
+    'complete',
+    'error'
+];
+/**
+ * Where the active step leads, or `undefined` when it ends the flow.
+ *
+ * A step with one edge needs no `next`; a step with several declares one, and
+ * what it returns **must** be an edge the step declared. That check is an
+ * {@link EntifixLogicError} rather than a silent fallback because the two ways
+ * of being wrong are both invisible otherwise: returning an id from another
+ * branch strands the operator on a step whose earlier answers were never given,
+ * and returning a typo would read as "this wizard has ended" one step early.
+ */ export function nextStepId(definition, state) {
+    var _ref;
+    const step = findStep(definition, state.activeStep);
+    if (step === undefined || step.to.length === 0) return undefined;
+    // `to` is non-empty here, so the fallback always resolves — which is why a
+    // step ends a flow by declaring no edges rather than by returning nothing.
+    const chosen = (_ref = step.next == null ? void 0 : step.next.call(step, state)) != null ? _ref : step.to[0];
+    if (!step.to.includes(chosen)) {
+        throw new EntifixLogicError(`wizard "${definition.key}" step "${step.id}" chose "${chosen}", which is not one of its edges`);
+    }
+    return chosen;
+}
+/**
+ * The state one step further on, or the same state when there is nowhere to go.
+ *
+ * Unchanged rather than throwing on a terminal step: the button that calls this
+ * is the one {@link canFinish} turns into Finalizar, so reaching here means the
+ * caller asked twice, not that the definition is wrong.
+ */ export function advanceWizard(definition, state) {
+    const next = nextStepId(definition, state);
+    if (next === undefined) return state;
+    return _extends({}, state, {
+        activeStep: next,
+        history: [
+            ...state.history,
+            state.activeStep
+        ]
+    });
+}
+/**
+ * The state one step back, or the same state at the entry step.
+ *
+ * It pops {@link WizardState.history} rather than inverting `next`, which is the
+ * whole reason that history is stored: a branch's inverse is ambiguous the
+ * moment an earlier answer changes, so a computed one walks the operator back
+ * through a path they were never on.
+ */ export function goBackWizard(state) {
+    const previous = state.history.at(-1);
+    if (previous === undefined) return state;
+    return _extends({}, state, {
+        activeStep: previous,
+        history: state.history.slice(0, -1)
+    });
+}
+/**
+ * Jump to a step already visited.
+ *
+ * Backwards only, and to a step **on the current path** — a stepper may make a
+ * completed step clickable, and nothing else. Jumping forward would skip the
+ * per-step submit that validates the steps in between, which is the one thing
+ * gating advancement at all; jumping to a step on an abandoned branch would put
+ * the operator somewhere their current answers do not lead.
+ *
+ * The history truncates to before the target, exactly as arriving there by
+ * pressing Back repeatedly would leave it.
+ */ export function goToWizardStep(state, stepId) {
+    const index = state.history.indexOf(stepId);
+    if (index === -1) return state;
+    return _extends({}, state, {
+        activeStep: stepId,
+        history: state.history.slice(0, index)
+    });
+}
+/** Whether the active step ends the flow, so its button reads Finalizar. */ export const canFinish = (definition, state)=>nextStepId(definition, state) === undefined;
+/**
+ * The steps this flow runs through, given what has been answered — the ones
+ * already visited, the active one, and the ones ahead.
+ *
+ * **Projected, not the declared list.** A graph's step list contains branches
+ * not taken, so rendering `definition.steps` would show a stepper promising a
+ * "duplicate" step to an operator who chose to start blank. Walking forward from
+ * the active step with the current answers is what makes the stepper honest:
+ * it re-shapes as a branch point is answered, which is the visible half of the
+ * step graph being a graph.
+ *
+ * The walk stops on a step it has already placed, which is what makes it
+ * terminate: every pass either adds a step to a finite set or stops. A
+ * definition that cycles therefore produces a finite path rather than hanging
+ * the render — `assertWizardDefinition` has already refused such a definition at
+ * load, and this exists because a render loop is a worse way to find out.
+ */ export function wizardPath(definition, state) {
+    const path = [
+        ...state.history,
+        state.activeStep
+    ];
+    const seen = new Set(path);
+    let cursor = state.activeStep;
+    for(;;){
+        const next = nextStepId(definition, _extends({}, state, {
+            activeStep: cursor
+        }));
+        if (next === undefined || seen.has(next)) break;
+        path.push(next);
+        seen.add(next);
+        cursor = next;
+    }
+    return path;
+}
+/**
+ * Each step on the projected path, with how it reads.
+ *
+ * `errored` is supplied by the caller rather than derived, because validity is
+ * the step's own knowledge: a form step's errors live in its `useEntityForm`
+ * instance, and this module is framework-free and holds none of them.
+ *
+ * An error wins over `complete` — a step the operator has been through and left
+ * invalid is exactly the one the stepper has to point at.
+ */ export function stepStatuses(definition, state, errored = []) {
+    const visited = new Set(state.history);
+    return wizardPath(definition, state).map((id)=>({
+            id,
+            status: statusOf(id, state.activeStep, visited, errored)
+        }));
+}
+function statusOf(id, activeStep, visited, errored) {
+    if (errored.includes(id)) return 'error';
+    if (id === activeStep) return 'active';
+    return visited.has(id) ? 'complete' : 'pending';
+}
+
+//# sourceMappingURL=wizard-navigation.js.map

package/dist/wizard/wizard-navigation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/wizard/wizard-navigation.ts"],"sourcesContent":["import { EntifixLogicError } from '../base-entities/entifix-error/index.js';\nimport { findStep, type WizardDefinition } from './wizard-definition.js';\nimport type { WizardState } from './wizard-state.js';\n\n/** How a step reads in the stepper. */\nexport const WizardStepStatuses = [\n  'pending',\n  'active',\n  'complete',\n  'error',\n] as const;\nexport type WizardStepStatus = (typeof WizardStepStatuses)[number];\n\n/**\n * Where the active step leads, or `undefined` when it ends the flow.\n *\n * A step with one edge needs no `next`; a step with several declares one, and\n * what it returns **must** be an edge the step declared. That check is an\n * {@link EntifixLogicError} rather than a silent fallback because the two ways\n * of being wrong are both invisible otherwise: returning an id from another\n * branch strands the operator on a step whose earlier answers were never given,\n * and returning a typo would read as \"this wizard has ended\" one step early.\n */\nexport function nextStepId(\n  definition: WizardDefinition,\n  state: WizardState,\n): string | undefined {\n  const step = findStep(definition, state.activeStep);\n  if (step === undefined || step.to.length === 0) return undefined;\n\n  // `to` is non-empty here, so the fallback always resolves — which is why a\n  // step ends a flow by declaring no edges rather than by returning nothing.\n  const chosen = step.next?.(state) ?? step.to[0];\n\n  if (!step.to.includes(chosen)) {\n    throw new EntifixLogicError(\n      `wizard \"${definition.key}\" step \"${step.id}\" chose \"${chosen}\", which is not one of its edges`,\n    );\n  }\n  return chosen;\n}\n\n/**\n * The state one step further on, or the same state when there is nowhere to go.\n *\n * Unchanged rather than throwing on a terminal step: the button that calls this\n * is the one {@link canFinish} turns into Finalizar, so reaching here means the\n * caller asked twice, not that the definition is wrong.\n */\nexport function advanceWizard(\n  definition: WizardDefinition,\n  state: WizardState,\n): WizardState {\n  const next = nextStepId(definition, state);\n  if (next === undefined) return state;\n\n  return {\n    ...state,\n    activeStep: next,\n    history: [...state.history, state.activeStep],\n  };\n}\n\n/**\n * The state one step back, or the same state at the entry step.\n *\n * It pops {@link WizardState.history} rather than inverting `next`, which is the\n * whole reason that history is stored: a branch's inverse is ambiguous the\n * moment an earlier answer changes, so a computed one walks the operator back\n * through a path they were never on.\n */\nexport function goBackWizard(state: WizardState): WizardState {\n  const previous = state.history.at(-1);\n  if (previous === undefined) return state;\n\n  return {\n    ...state,\n    activeStep: previous,\n    history: state.history.slice(0, -1),\n  };\n}\n\n/**\n * Jump to a step already visited.\n *\n * Backwards only, and to a step **on the current path** — a stepper may make a\n * completed step clickable, and nothing else. Jumping forward would skip the\n * per-step submit that validates the steps in between, which is the one thing\n * gating advancement at all; jumping to a step on an abandoned branch would put\n * the operator somewhere their current answers do not lead.\n *\n * The history truncates to before the target, exactly as arriving there by\n * pressing Back repeatedly would leave it.\n */\nexport function goToWizardStep(\n  state: WizardState,\n  stepId: string,\n): WizardState {\n  const index = state.history.indexOf(stepId);\n  if (index === -1) return state;\n\n  return {\n    ...state,\n    activeStep: stepId,\n    history: state.history.slice(0, index),\n  };\n}\n\n/** Whether the active step ends the flow, so its button reads Finalizar. */\nexport const canFinish = (\n  definition: WizardDefinition,\n  state: WizardState,\n): boolean => nextStepId(definition, state) === undefined;\n\n/**\n * The steps this flow runs through, given what has been answered — the ones\n * already visited, the active one, and the ones ahead.\n *\n * **Projected, not the declared list.** A graph's step list contains branches\n * not taken, so rendering `definition.steps` would show a stepper promising a\n * \"duplicate\" step to an operator who chose to start blank. Walking forward from\n * the active step with the current answers is what makes the stepper honest:\n * it re-shapes as a branch point is answered, which is the visible half of the\n * step graph being a graph.\n *\n * The walk stops on a step it has already placed, which is what makes it\n * terminate: every pass either adds a step to a finite set or stops. A\n * definition that cycles therefore produces a finite path rather than hanging\n * the render — `assertWizardDefinition` has already refused such a definition at\n * load, and this exists because a render loop is a worse way to find out.\n */\nexport function wizardPath(\n  definition: WizardDefinition,\n  state: WizardState,\n): readonly string[] {\n  const path = [...state.history, state.activeStep];\n  const seen = new Set(path);\n\n  let cursor = state.activeStep;\n  for (;;) {\n    const next = nextStepId(definition, { ...state, activeStep: cursor });\n    if (next === undefined || seen.has(next)) break;\n    path.push(next);\n    seen.add(next);\n    cursor = next;\n  }\n\n  return path;\n}\n\n/**\n * Each step on the projected path, with how it reads.\n *\n * `errored` is supplied by the caller rather than derived, because validity is\n * the step's own knowledge: a form step's errors live in its `useEntityForm`\n * instance, and this module is framework-free and holds none of them.\n *\n * An error wins over `complete` — a step the operator has been through and left\n * invalid is exactly the one the stepper has to point at.\n */\nexport function stepStatuses(\n  definition: WizardDefinition,\n  state: WizardState,\n  errored: readonly string[] = [],\n): ReadonlyArray<{ readonly id: string; readonly status: WizardStepStatus }> {\n  const visited = new Set(state.history);\n\n  return wizardPath(definition, state).map(id => ({\n    id,\n    status: statusOf(id, state.activeStep, visited, errored),\n  }));\n}\n\nfunction statusOf(\n  id: string,\n  activeStep: string,\n  visited: ReadonlySet<string>,\n  errored: readonly string[],\n): WizardStepStatus {\n  if (errored.includes(id)) return 'error';\n  if (id === activeStep) return 'active';\n  return visited.has(id) ? 'complete' : 'pending';\n}\n"],"names":["EntifixLogicError","findStep","WizardStepStatuses","nextStepId","definition","state","step","activeStep","undefined","to","length","chosen","next","includes","key","id","advanceWizard","history","goBackWizard","previous","at","slice","goToWizardStep","stepId","index","indexOf","canFinish","wizardPath","path","seen","Set","cursor","has","push","add","stepStatuses","errored","visited","map","status","statusOf"],"mappings":"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"}

package/dist/wizard/wizard-state.d.ts

@@ -0,0 +1,89 @@
+import type { EntityDraft } from '../types/EntityDraft.js';
+/**
+ * What one step holds.
+ *
+ * A wizard's state is **heterogeneous by construction** — a form step drafts
+ * strings, a table step holds a set of ids, a branch point holds the option
+ * taken — so this is a discriminated union rather than one shape with optional
+ * members, which would let a form step carry ids nothing would ever read.
+ *
+ * ⚠️ A selection holds `readonly string[]`, **never a `ReadonlySet`**. A `Set`
+ * serializes to `{}` and does it silently, which is the fault
+ * [ADR 0035](../../../../../../docs/adr/0035-entity-actions-selection-and-bulk.md)
+ * named for the wire — and a wizard's state goes through `createJSONStorage` on
+ * every keystroke, so it would be met far more often here than there.
+ */
+export type WizardStepValue = {
+    readonly kind: 'form';
+    readonly values: EntityDraft;
+} | {
+    readonly kind: 'selection';
+    readonly ids: readonly string[];
+} | {
+    readonly kind: 'choice';
+    readonly option: string;
+} | {
+    readonly kind: 'none';
+};
+/**
+ * A wizard in progress: where the operator is, how they got there, and what
+ * they have answered.
+ *
+ * **A `type`, never an `interface`.** This is persisted through
+ * `createJSONStorage` and therefore has to satisfy `JsonValue`, and TypeScript
+ * gives an interface no implicit index signature — the resulting "Index
+ * signature for type 'string' is missing" explains nothing about the real cause
+ * ([ADR 0032](../../../../../../docs/adr/0032-what-may-live-in-an-autosaved-draft.md)).
+ *
+ * `history` is **the path actually taken**, and it is what Back pops. A branch's
+ * inverse is ambiguous once an earlier answer changes, so a computed `previous`
+ * would walk the operator back through a path they were never on
+ * ([ADR 0045](../../../../../../docs/adr/0045-the-wizard-a-step-graph-and-a-submit-that-hands-off.md)).
+ *
+ * `steps` is deliberately **not** pruned when a branch is abandoned. It is the
+ * record of what was typed, and {@link wizardPath} decides what counts — so
+ * flipping back to an earlier answer restores the work instead of discarding it,
+ * while the summary and the submit still read only the steps on the live path.
+ */
+export type WizardState = {
+    readonly activeStep: string;
+    readonly history: readonly string[];
+    readonly steps: {
+        readonly [stepId: string]: WizardStepValue;
+    };
+};
+/** A wizard that has been opened and not yet answered. */
+export declare const emptyWizardState: (entryStepId: string) => WizardState;
+/** The value stored for a step, or `undefined` when it has none. */
+export declare const readStepValue: (state: WizardState, stepId: string) => WizardStepValue | undefined;
+/**
+ * The draft a form step holds, or an empty one.
+ *
+ * The fallback is `{}` rather than `undefined` for the reason every draft read
+ * in this repo has one: a form handed `undefined` flips its inputs from
+ * controlled to uncontrolled mid-render.
+ */
+export declare const readStepDraft: (state: WizardState, stepId: string) => EntityDraft;
+/** The ids a selection step holds, or none. */
+export declare const readStepIds: (state: WizardState, stepId: string) => readonly string[];
+/** The option a choice step holds, or `undefined` while it is unanswered. */
+export declare const readStepChoice: (state: WizardState, stepId: string) => string | undefined;
+/** The state with one step's value replaced. */
+export declare const withStepValue: (state: WizardState, stepId: string, value: WizardStepValue) => WizardState;
+/**
+ * Narrows a restored value to a usable state.
+ *
+ * A persisted wizard comes back as `JsonValue`, so it can be anything — written
+ * by a build before a step existed, `null`, or the right shape with the wrong
+ * contents. Every caller must ask before reading, and the answer for a value
+ * that fails is a **fresh** wizard rather than a crash: an unreadable draft is
+ * an unfinished edit, and `restoreEntityDraft` already discards those per entry
+ * rather than losing the whole form.
+ *
+ * A step value of an unknown `kind` fails the whole state rather than being
+ * dropped, deliberately. Dropping it would resume the operator on a step whose
+ * answer had silently vanished, which reads as the wizard having forgotten one
+ * page of a flow it otherwise restored perfectly.
+ */
+export declare function readWizardState(value: unknown): WizardState | undefined;
+//# sourceMappingURL=wizard-state.d.ts.map

package/dist/wizard/wizard-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wizard-state.d.ts","sourceRoot":"","sources":["../../src/wizard/wizard-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,CAAA;KAAE,CAAC;CAChE,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,GAAI,aAAa,MAAM,KAAG,WAIrD,CAAC;AAEH,oEAAoE;AACpE,eAAO,MAAM,aAAa,GACxB,OAAO,WAAW,EAClB,QAAQ,MAAM,KACb,eAAe,GAAG,SAAgC,CAAC;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,WAAW,EAClB,QAAQ,MAAM,KACb,WAGF,CAAC;AAEF,+CAA+C;AAC/C,eAAO,MAAM,WAAW,GACtB,OAAO,WAAW,EAClB,QAAQ,MAAM,KACb,SAAS,MAAM,EAGjB,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,cAAc,GACzB,OAAO,WAAW,EAClB,QAAQ,MAAM,KACb,MAAM,GAAG,SAGX,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,aAAa,GACxB,OAAO,WAAW,EAClB,QAAQ,MAAM,EACd,OAAO,eAAe,KACrB,WAGD,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAiBvE"}

package/dist/wizard/wizard-state.js

@@ -0,0 +1,103 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/** A wizard that has been opened and not yet answered. */ export const emptyWizardState = (entryStepId)=>({
+        activeStep: entryStepId,
+        history: [],
+        steps: {}
+    });
+/** The value stored for a step, or `undefined` when it has none. */ export const readStepValue = (state, stepId)=>state.steps[stepId];
+/**
+ * The draft a form step holds, or an empty one.
+ *
+ * The fallback is `{}` rather than `undefined` for the reason every draft read
+ * in this repo has one: a form handed `undefined` flips its inputs from
+ * controlled to uncontrolled mid-render.
+ */ export const readStepDraft = (state, stepId)=>{
+    const value = state.steps[stepId];
+    return (value == null ? void 0 : value.kind) === 'form' ? value.values : {};
+};
+/** The ids a selection step holds, or none. */ export const readStepIds = (state, stepId)=>{
+    const value = state.steps[stepId];
+    return (value == null ? void 0 : value.kind) === 'selection' ? value.ids : [];
+};
+/** The option a choice step holds, or `undefined` while it is unanswered. */ export const readStepChoice = (state, stepId)=>{
+    const value = state.steps[stepId];
+    return (value == null ? void 0 : value.kind) === 'choice' ? value.option : undefined;
+};
+/** The state with one step's value replaced. */ export const withStepValue = (state, stepId, value)=>_extends({}, state, {
+        steps: _extends({}, state.steps, {
+            [stepId]: value
+        })
+    });
+/**
+ * Narrows a restored value to a usable state.
+ *
+ * A persisted wizard comes back as `JsonValue`, so it can be anything — written
+ * by a build before a step existed, `null`, or the right shape with the wrong
+ * contents. Every caller must ask before reading, and the answer for a value
+ * that fails is a **fresh** wizard rather than a crash: an unreadable draft is
+ * an unfinished edit, and `restoreEntityDraft` already discards those per entry
+ * rather than losing the whole form.
+ *
+ * A step value of an unknown `kind` fails the whole state rather than being
+ * dropped, deliberately. Dropping it would resume the operator on a step whose
+ * answer had silently vanished, which reads as the wizard having forgotten one
+ * page of a flow it otherwise restored perfectly.
+ */ export function readWizardState(value) {
+    if (!isRecord(value)) return undefined;
+    const { activeStep, history, steps } = value;
+    if (typeof activeStep !== 'string' || activeStep === '') return undefined;
+    if (!Array.isArray(history)) return undefined;
+    if (!history.every((entry)=>typeof entry === 'string')) return undefined;
+    if (!isRecord(steps)) return undefined;
+    const readSteps = {};
+    for (const [stepId, stepValue] of Object.entries(steps)){
+        const read = readStepValueOf(stepValue);
+        if (read === undefined) return undefined;
+        readSteps[stepId] = read;
+    }
+    return {
+        activeStep,
+        history,
+        steps: readSteps
+    };
+}
+function readStepValueOf(value) {
+    if (!isRecord(value)) return undefined;
+    switch(value.kind){
+        case 'none':
+            return {
+                kind: 'none'
+            };
+        case 'choice':
+            return typeof value.option === 'string' ? {
+                kind: 'choice',
+                option: value.option
+            } : undefined;
+        case 'selection':
+            return Array.isArray(value.ids) && value.ids.every((id)=>typeof id === 'string') ? {
+                kind: 'selection',
+                ids: value.ids
+            } : undefined;
+        case 'form':
+            return isDraft(value.values) ? {
+                kind: 'form',
+                values: value.values
+            } : undefined;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Whether a restored value is a usable {@link EntityDraft}.
+ *
+ * The same two shapes `EntityDraft` allows, checked the way `isRowDraftArray`
+ * checks its half — a scalar is a string and a composition is a list of row
+ * drafts, and anything else means the entry was written by something that does
+ * not know the contract.
+ */ function isDraft(value) {
+    return isRecord(value) && Object.values(value).every((member)=>typeof member === 'string' || Array.isArray(member) && member.every(isRowOfStrings));
+}
+const isRowOfStrings = (row)=>isRecord(row) && Object.values(row).every((cell)=>typeof cell === 'string');
+const isRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+
+//# sourceMappingURL=wizard-state.js.map

package/dist/wizard/wizard-state.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/wizard/wizard-state.ts"],"sourcesContent":["import type { EntityDraft } from '../types/EntityDraft.js';\n\n/**\n * What one step holds.\n *\n * A wizard's state is **heterogeneous by construction** — a form step drafts\n * strings, a table step holds a set of ids, a branch point holds the option\n * taken — so this is a discriminated union rather than one shape with optional\n * members, which would let a form step carry ids nothing would ever read.\n *\n * ⚠️ A selection holds `readonly string[]`, **never a `ReadonlySet`**. A `Set`\n * serializes to `{}` and does it silently, which is the fault\n * [ADR 0035](../../../../../../docs/adr/0035-entity-actions-selection-and-bulk.md)\n * named for the wire — and a wizard's state goes through `createJSONStorage` on\n * every keystroke, so it would be met far more often here than there.\n */\nexport type WizardStepValue =\n  | { readonly kind: 'form'; readonly values: EntityDraft }\n  | { readonly kind: 'selection'; readonly ids: readonly string[] }\n  | { readonly kind: 'choice'; readonly option: string }\n  | { readonly kind: 'none' };\n\n/**\n * A wizard in progress: where the operator is, how they got there, and what\n * they have answered.\n *\n * **A `type`, never an `interface`.** This is persisted through\n * `createJSONStorage` and therefore has to satisfy `JsonValue`, and TypeScript\n * gives an interface no implicit index signature — the resulting \"Index\n * signature for type 'string' is missing\" explains nothing about the real cause\n * ([ADR 0032](../../../../../../docs/adr/0032-what-may-live-in-an-autosaved-draft.md)).\n *\n * `history` is **the path actually taken**, and it is what Back pops. A branch's\n * inverse is ambiguous once an earlier answer changes, so a computed `previous`\n * would walk the operator back through a path they were never on\n * ([ADR 0045](../../../../../../docs/adr/0045-the-wizard-a-step-graph-and-a-submit-that-hands-off.md)).\n *\n * `steps` is deliberately **not** pruned when a branch is abandoned. It is the\n * record of what was typed, and {@link wizardPath} decides what counts — so\n * flipping back to an earlier answer restores the work instead of discarding it,\n * while the summary and the submit still read only the steps on the live path.\n */\nexport type WizardState = {\n  readonly activeStep: string;\n  readonly history: readonly string[];\n  readonly steps: { readonly [stepId: string]: WizardStepValue };\n};\n\n/** A wizard that has been opened and not yet answered. */\nexport const emptyWizardState = (entryStepId: string): WizardState => ({\n  activeStep: entryStepId,\n  history: [],\n  steps: {},\n});\n\n/** The value stored for a step, or `undefined` when it has none. */\nexport const readStepValue = (\n  state: WizardState,\n  stepId: string,\n): WizardStepValue | undefined => state.steps[stepId];\n\n/**\n * The draft a form step holds, or an empty one.\n *\n * The fallback is `{}` rather than `undefined` for the reason every draft read\n * in this repo has one: a form handed `undefined` flips its inputs from\n * controlled to uncontrolled mid-render.\n */\nexport const readStepDraft = (\n  state: WizardState,\n  stepId: string,\n): EntityDraft => {\n  const value = state.steps[stepId];\n  return value?.kind === 'form' ? value.values : {};\n};\n\n/** The ids a selection step holds, or none. */\nexport const readStepIds = (\n  state: WizardState,\n  stepId: string,\n): readonly string[] => {\n  const value = state.steps[stepId];\n  return value?.kind === 'selection' ? value.ids : [];\n};\n\n/** The option a choice step holds, or `undefined` while it is unanswered. */\nexport const readStepChoice = (\n  state: WizardState,\n  stepId: string,\n): string | undefined => {\n  const value = state.steps[stepId];\n  return value?.kind === 'choice' ? value.option : undefined;\n};\n\n/** The state with one step's value replaced. */\nexport const withStepValue = (\n  state: WizardState,\n  stepId: string,\n  value: WizardStepValue,\n): WizardState => ({\n  ...state,\n  steps: { ...state.steps, [stepId]: value },\n});\n\n/**\n * Narrows a restored value to a usable state.\n *\n * A persisted wizard comes back as `JsonValue`, so it can be anything — written\n * by a build before a step existed, `null`, or the right shape with the wrong\n * contents. Every caller must ask before reading, and the answer for a value\n * that fails is a **fresh** wizard rather than a crash: an unreadable draft is\n * an unfinished edit, and `restoreEntityDraft` already discards those per entry\n * rather than losing the whole form.\n *\n * A step value of an unknown `kind` fails the whole state rather than being\n * dropped, deliberately. Dropping it would resume the operator on a step whose\n * answer had silently vanished, which reads as the wizard having forgotten one\n * page of a flow it otherwise restored perfectly.\n */\nexport function readWizardState(value: unknown): WizardState | undefined {\n  if (!isRecord(value)) return undefined;\n\n  const { activeStep, history, steps } = value;\n  if (typeof activeStep !== 'string' || activeStep === '') return undefined;\n  if (!Array.isArray(history)) return undefined;\n  if (!history.every(entry => typeof entry === 'string')) return undefined;\n  if (!isRecord(steps)) return undefined;\n\n  const readSteps: Record<string, WizardStepValue> = {};\n  for (const [stepId, stepValue] of Object.entries(steps)) {\n    const read = readStepValueOf(stepValue);\n    if (read === undefined) return undefined;\n    readSteps[stepId] = read;\n  }\n\n  return { activeStep, history, steps: readSteps };\n}\n\nfunction readStepValueOf(value: unknown): WizardStepValue | undefined {\n  if (!isRecord(value)) return undefined;\n\n  switch (value.kind) {\n    case 'none':\n      return { kind: 'none' };\n    case 'choice':\n      return typeof value.option === 'string'\n        ? { kind: 'choice', option: value.option }\n        : undefined;\n    case 'selection':\n      return Array.isArray(value.ids) &&\n        value.ids.every(id => typeof id === 'string')\n        ? { kind: 'selection', ids: value.ids }\n        : undefined;\n    case 'form':\n      return isDraft(value.values)\n        ? { kind: 'form', values: value.values }\n        : undefined;\n    default:\n      return undefined;\n  }\n}\n\n/**\n * Whether a restored value is a usable {@link EntityDraft}.\n *\n * The same two shapes `EntityDraft` allows, checked the way `isRowDraftArray`\n * checks its half — a scalar is a string and a composition is a list of row\n * drafts, and anything else means the entry was written by something that does\n * not know the contract.\n */\nfunction isDraft(value: unknown): value is EntityDraft {\n  return (\n    isRecord(value) &&\n    Object.values(value).every(\n      member =>\n        typeof member === 'string' ||\n        (Array.isArray(member) && member.every(isRowOfStrings)),\n    )\n  );\n}\n\nconst isRowOfStrings = (row: unknown): boolean =>\n  isRecord(row) && Object.values(row).every(cell => typeof cell === 'string');\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n"],"names":["emptyWizardState","entryStepId","activeStep","history","steps","readStepValue","state","stepId","readStepDraft","value","kind","values","readStepIds","ids","readStepChoice","option","undefined","withStepValue","readWizardState","isRecord","Array","isArray","every","entry","readSteps","stepValue","Object","entries","read","readStepValueOf","id","isDraft","member","isRowOfStrings","row","cell"],"mappings":"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"}