palistor 0.0.24 → 0.0.26

package/dist/store/flow/buildFlowStepsProxy.js

@@ -0,0 +1,72 @@
+import { CONFIG_NODE, FLOW_STATE } from "../constants";
+/** Stable steps-proxy cache — one per FlowState (like listProxyCache). */
+const stepsProxyCache = new WeakMap();
+const NUMERIC_KEY = /^\d+$/;
+/**
+ * Proxy over the flow's step collection (flow.steps).
+ *
+ * Access:
+ *   steps[0]        — by index (step array order)
+ *   steps.welcome   — by key
+ *   steps.current   — live reference to the active step's proxy
+ *   steps.length    — number of steps
+ *   [...steps]      — iteration over step proxies
+ *
+ * Step proxies are regular group proxies of the step nodes (cached in
+ * proxyCache), enriched with `status` in the group GET trap (via stepToFlow).
+ */
+export function buildFlowStepsProxy(flowState, kernel) {
+    const cached = stepsProxyCache.get(flowState);
+    if (cached)
+        return cached;
+    const buildStep = (index) => kernel.proxyBuilder.build(flowState.stepNodes[index]);
+    const spreadKeys = () => [...flowState.stepKeys, "current", "length"];
+    const proxy = new Proxy({}, {
+        get(_target, key) {
+            // Tracking brand: navigation bumps the FlowState version.
+            if (key === FLOW_STATE)
+                return flowState;
+            // steps is not a config node; transparent to the tracking proxy.
+            if (key === CONFIG_NODE)
+                return undefined;
+            if (typeof key === "symbol") {
+                if (key === Symbol.iterator) {
+                    return function* () {
+                        for (let i = 0; i < flowState.stepNodes.length; i++)
+                            yield buildStep(i);
+                    };
+                }
+                return undefined;
+            }
+            if (key === "length")
+                return flowState.stepNodes.length;
+            if (key === "current")
+                return buildStep(flowState.currentIndex);
+            if (NUMERIC_KEY.test(key)) {
+                const index = Number(key);
+                return index < flowState.stepNodes.length ? buildStep(index) : undefined;
+            }
+            const index = flowState.stepKeys.indexOf(key);
+            if (index !== -1)
+                return buildStep(index);
+            return undefined;
+        },
+        set() {
+            // The step set is static — writes are forbidden.
+            return false;
+        },
+        ownKeys() {
+            return spreadKeys();
+        },
+        getOwnPropertyDescriptor(_target, key) {
+            if (typeof key === "symbol")
+                return undefined;
+            if (!spreadKeys().includes(key))
+                return undefined;
+            return { configurable: true, enumerable: true, writable: false };
+        },
+    });
+    stepsProxyCache.set(flowState, proxy);
+    return proxy;
+}
+//# sourceMappingURL=buildFlowStepsProxy.js.map

package/dist/store/flow/buildFlowStepsProxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildFlowStepsProxy.js","sourceRoot":"","sources":["../../../store/flow/buildFlowStepsProxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAIvD,0EAA0E;AAC1E,MAAM,eAAe,GAAG,IAAI,OAAO,EAAkB,CAAC;AAEtD,MAAM,WAAW,GAAG,OAAO,CAAC;AAE5B;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAoB,EAAE,MAA0B;IAClF,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,SAA8B,CAAC,CAAC;IACnE,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,SAAS,GAAG,CAAC,KAAa,EAAU,EAAE,CAC1C,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAW,CAAC;IAElE,MAAM,UAAU,GAAG,GAAa,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAEhF,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,EAA6B,EAAE;QACrD,GAAG,CAAC,OAAO,EAAE,GAAoB;YAC/B,0DAA0D;YAC1D,IAAI,GAAG,KAAK,UAAU;gBAAE,OAAO,SAAS,CAAC;YACzC,iEAAiE;YACjE,IAAI,GAAG,KAAK,WAAW;gBAAE,OAAO,SAAS,CAAC;YAE1C,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5B,IAAI,GAAG,KAAK,MAAM,CAAC,QAAQ,EAAE,CAAC;oBAC5B,OAAO,QAAQ,CAAC;wBACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE;4BAAE,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC;oBAC1E,CAAC,CAAC;gBACJ,CAAC;gBACD,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,IAAI,GAAG,KAAK,QAAQ;gBAAE,OAAO,SAAS,CAAC,SAAS,CAAC,MAAM,CAAC;YACxD,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;YAEhE,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC1B,OAAO,KAAK,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC3E,CAAC;YAED,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC9C,IAAI,KAAK,KAAK,CAAC,CAAC;gBAAE,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;YAE1C,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,GAAG;YACD,iDAAiD;YACjD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO;YACL,OAAO,UAAU,EAAE,CAAC;QACtB,CAAC;QAED,wBAAwB,CAAC,OAAO,EAAE,GAAoB;YACpD,IAAI,OAAO,GAAG,KAAK,QAAQ;gBAAE,OAAO,SAAS,CAAC;YAC9C,IAAI,CAAC,UAAU,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,OAAO,SAAS,CAAC;YAClD,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;QACnE,CAAC;KACF,CAAC,CAAC;IAEH,eAAe,CAAC,GAAG,CAAC,SAA8B,EAAE,KAAK,CAAC,CAAC;IAC3D,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/store/flow/defineFlow.d.ts

@@ -0,0 +1,92 @@
+import type { ExtractValues, ProxyStore } from "../store/types";
+/**
+ * Flow step status — a computed step-proxy property derived from navigation
+ * state (currentStepKey + visited set). Not a leaf node: never appears in
+ * values, submit payloads or persisted state.
+ *
+ * - `null`        — the step has not been visited yet
+ * - `"active"`    — the current step
+ * - `"completed"` — was active, then left (forward or back)
+ */
+export type StepStatus = "active" | "completed" | null;
+/** Flow validation error — same shape as in SubmitResult. */
+export interface FlowError {
+    path: string;
+    message: string;
+}
+/**
+ * Result of defineStep: the step's group config + its key within the flow.
+ * defineFlow expands steps into regular child groups of the flow node.
+ */
+export interface FlowStep<K extends string = string, C extends Record<string, any> = Record<string, any>> {
+    readonly key: K;
+    readonly config: C;
+}
+export type AnyFlowStep = FlowStep<string, Record<string, any>>;
+/** Flow values — all steps by key (accumulated state). */
+export type FlowValues<S extends readonly AnyFlowStep[]> = {
+    [Step in S[number] as Step["key"]]: ExtractValues<Step["config"]>;
+};
+declare const __flowBrand: unique symbol;
+/**
+ * A flow node in the config tree: a regular group (steps are child groups by
+ * key), branded with the step tuple for proxy type inference.
+ */
+export type FlowNode<S extends readonly AnyFlowStep[]> = {
+    readonly [__flowBrand]: S;
+} & {
+    [Step in S[number] as Step["key"]]: Step["config"];
+};
+/** Extract the step tuple from a FlowNode (never when the node is not a flow). */
+export type InferFlowSteps<T> = T extends {
+    readonly [__flowBrand]: infer S extends readonly AnyFlowStep[];
+} ? S : never;
+/**
+ * Wrap a group config into a flow step.
+ *
+ * A step config is a regular Palistor group node (fields, isVisible,
+ * validate, resolve, onSubmit, …) plus the flow lifecycle callbacks
+ * `onEnter` / `onReady`.
+ *
+ * @example
+ * defineStep("welcome", {
+ *   name: { value: "", isRequired: true },
+ *   onSubmit: async (values, store, { nextStep }) => { nextStep(); },
+ * })
+ */
+export declare function defineStep<const K extends string, const C extends Record<string, any>>(key: K, config: C & {
+    status?: never;
+}): FlowStep<K, C>;
+export interface DefineFlowOptions<S extends readonly AnyFlowStep[]> {
+    /** Ordered array of steps (defineStep). The order drives nextStep(). */
+    steps: S;
+    /** Flow-level submit: invoked by the standard submit pipeline over all steps. */
+    onSubmit?: (values: FlowValues<S>, store: ProxyStore<any>, parent?: any) => Promise<unknown> | unknown;
+    /** Group-level value transformation before submit. */
+    beforeSubmit?: (values: FlowValues<S>) => FlowValues<S> | Promise<FlowValues<S>>;
+    /** Post-processing after a successful onSubmit. */
+    afterSubmit?: (result: unknown, actions: {
+        reset: () => void;
+    }) => void | Promise<void>;
+}
+/**
+ * Build a flow node from an ordered array of steps.
+ *
+ * The returned node is a regular group in the config tree (steps become child
+ * groups under their keys), stamped with the {@link FLOW_STEPS_PROP} marker
+ * holding the step order. It participates in values / persist / dirty like
+ * any group; NodeRegistry creates a FlowState (navigation, statuses, history)
+ * based on the marker.
+ *
+ * @example
+ * const onboarding = defineFlow({
+ *   steps: [
+ *     defineStep("welcome", { name: { value: "", isRequired: true } }),
+ *     defineStep("summary", {}),
+ *   ],
+ *   onSubmit: async (allValues, store) => api.completeOnboarding(allValues),
+ * });
+ */
+export declare function defineFlow<const S extends readonly AnyFlowStep[]>(options: DefineFlowOptions<S>): FlowNode<S>;
+export {};
+//# sourceMappingURL=defineFlow.d.ts.map

package/dist/store/flow/defineFlow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineFlow.d.ts","sourceRoot":"","sources":["../../../store/flow/defineFlow.ts"],"names":[],"mappings":"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"}

package/dist/store/flow/defineFlow.js

@@ -0,0 +1,99 @@
+import { CONFIG_PROPS, FLOW_SPREAD_KEYS, FLOW_STEPS_PROP, GROUP_SPREAD_KEYS, } from "../constants";
+// ─── defineStep ───────────────────────────────────────────────────────────────
+/**
+ * The name `status` is reserved on the step proxy for the computed step
+ * status — a config field with that name is forbidden (like dirty/loading).
+ */
+const RESERVED_STEP_CONFIG_KEYS = new Set(["status"]);
+/**
+ * Wrap a group config into a flow step.
+ *
+ * A step config is a regular Palistor group node (fields, isVisible,
+ * validate, resolve, onSubmit, …) plus the flow lifecycle callbacks
+ * `onEnter` / `onReady`.
+ *
+ * @example
+ * defineStep("welcome", {
+ *   name: { value: "", isRequired: true },
+ *   onSubmit: async (values, store, { nextStep }) => { nextStep(); },
+ * })
+ */
+export function defineStep(key, config) {
+    if (typeof key !== "string" || key.length === 0) {
+        throw new Error("[palistor] defineStep: key must be a non-empty string.");
+    }
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+        throw new Error(`[palistor] defineStep("${key}"): config must be a plain object (group node).`);
+    }
+    if ("value" in config) {
+        throw new Error(`[palistor] defineStep("${key}"): step config must be a group node — a "value" key makes it a leaf.`);
+    }
+    for (const reserved of RESERVED_STEP_CONFIG_KEYS) {
+        if (reserved in config) {
+            throw new Error(`[palistor] defineStep("${key}"): "${reserved}" is reserved — the flow exposes it as a computed step property.`);
+        }
+    }
+    return { key, config: config };
+}
+// ─── defineFlow ───────────────────────────────────────────────────────────────
+/**
+ * Step keys that conflict with flow-proxy / steps-proxy properties or service
+ * config keys — forbidden as step names.
+ */
+const RESERVED_STEP_KEYS = new Set([
+    ...CONFIG_PROPS,
+    ...GROUP_SPREAD_KEYS,
+    ...FLOW_SPREAD_KEYS,
+    "setValues",
+    "current",
+    "length",
+]);
+/**
+ * Build a flow node from an ordered array of steps.
+ *
+ * The returned node is a regular group in the config tree (steps become child
+ * groups under their keys), stamped with the {@link FLOW_STEPS_PROP} marker
+ * holding the step order. It participates in values / persist / dirty like
+ * any group; NodeRegistry creates a FlowState (navigation, statuses, history)
+ * based on the marker.
+ *
+ * @example
+ * const onboarding = defineFlow({
+ *   steps: [
+ *     defineStep("welcome", { name: { value: "", isRequired: true } }),
+ *     defineStep("summary", {}),
+ *   ],
+ *   onSubmit: async (allValues, store) => api.completeOnboarding(allValues),
+ * });
+ */
+export function defineFlow(options) {
+    const { steps, onSubmit, beforeSubmit, afterSubmit } = options;
+    if (!Array.isArray(steps) || steps.length === 0) {
+        throw new Error("[palistor] defineFlow: `steps` must be a non-empty array of defineStep(...) results.");
+    }
+    const node = {};
+    const stepKeys = [];
+    for (const step of steps) {
+        if (!step || typeof step !== "object" || typeof step.key !== "string" || !step.config) {
+            throw new Error("[palistor] defineFlow: each entry of `steps` must be created via defineStep(key, config).");
+        }
+        if (RESERVED_STEP_KEYS.has(step.key)) {
+            throw new Error(`[palistor] defineFlow: step key "${step.key}" is reserved by the flow/group proxy API.`);
+        }
+        if (stepKeys.includes(step.key)) {
+            throw new Error(`[palistor] defineFlow: duplicate step key "${step.key}".`);
+        }
+        node[step.key] = step.config;
+        stepKeys.push(step.key);
+    }
+    if (onSubmit)
+        node.onSubmit = onSubmit;
+    if (beforeSubmit)
+        node.beforeSubmit = beforeSubmit;
+    if (afterSubmit)
+        node.afterSubmit = afterSubmit;
+    // Flow marker: part of CONFIG_PROPS → all tree walks skip it.
+    node[FLOW_STEPS_PROP] = stepKeys;
+    return node;
+}
+//# sourceMappingURL=defineFlow.js.map

package/dist/store/flow/defineFlow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineFlow.js","sourceRoot":"","sources":["../../../store/flow/defineFlow.ts"],"names":[],"mappings":"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"}

package/dist/store/flow/flowApi.d.ts

@@ -0,0 +1,18 @@
+import type { Palistor } from "../store/palistor";
+import type { SubmitResult } from "../submitPipeline/types";
+import type { FlowError } from "./defineFlow";
+import type { FlowState } from "./flowState";
+/**
+ * Navigation methods of the flow proxy. All are closures bound over
+ * (kernel, flowState), so destructuring in onSubmit works:
+ * `(values, store, { nextStep }) => …`.
+ */
+export interface FlowApi {
+    nextStep: () => void;
+    back: () => void;
+    goTo: (keyOrIndex: string | number) => void;
+    validate: () => FlowError[];
+    submit: () => Promise<SubmitResult>;
+}
+export declare function getFlowApi(kernel: Palistor<any, any>, flowState: FlowState): FlowApi;
+//# sourceMappingURL=flowApi.d.ts.map

package/dist/store/flow/flowApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowApi.d.ts","sourceRoot":"","sources":["../../../store/flow/flowApi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAS7C;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,KAAK,IAAI,CAAC;IAC5C,QAAQ,EAAE,MAAM,SAAS,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;CACrC;AAKD,wBAAgB,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAcpF"}

package/dist/store/flow/flowApi.js

@@ -0,0 +1,18 @@
+import { flowBack, flowGoTo, flowNextStep, flowSubmit, flowValidate, } from "./flowNavigation";
+/** Stable method references — one FlowApi per FlowState (for React). */
+const flowApiCache = new WeakMap();
+export function getFlowApi(kernel, flowState) {
+    const cached = flowApiCache.get(flowState);
+    if (cached)
+        return cached;
+    const api = {
+        nextStep: () => flowNextStep(kernel, flowState),
+        back: () => flowBack(kernel, flowState),
+        goTo: (keyOrIndex) => flowGoTo(kernel, flowState, keyOrIndex),
+        validate: () => flowValidate(kernel, flowState),
+        submit: () => flowSubmit(kernel, flowState),
+    };
+    flowApiCache.set(flowState, api);
+    return api;
+}
+//# sourceMappingURL=flowApi.js.map

package/dist/store/flow/flowApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowApi.js","sourceRoot":"","sources":["../../../store/flow/flowApi.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,YAAY,GACb,MAAM,kBAAkB,CAAC;AAe1B,wEAAwE;AACxE,MAAM,YAAY,GAAG,IAAI,OAAO,EAAmB,CAAC;AAEpD,MAAM,UAAU,UAAU,CAAC,MAA0B,EAAE,SAAoB;IACzE,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,SAA8B,CAAC,CAAC;IAChE,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,GAAG,GAAY;QACnB,QAAQ,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC;QAC/C,IAAI,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;QACvC,IAAI,EAAE,CAAC,UAA2B,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,CAAC;QAC9E,QAAQ,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC;QAC/C,MAAM,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,SAAS,CAAC;KAC5C,CAAC;IAEF,YAAY,CAAC,GAAG,CAAC,SAA8B,EAAE,GAAG,CAAC,CAAC;IACtD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/store/flow/flowNavigation.d.ts

@@ -0,0 +1,137 @@
+import type { AnyConfigNode } from "../store/types";
+import type { Palistor } from "../store/palistor";
+import type { SubmitResult } from "../submitPipeline/types";
+import type { FlowError, StepStatus } from "./defineFlow";
+import type { FlowState } from "./flowState";
+type Kernel = Palistor<any, any>;
+/** Step status — derived from navigation state (not stored). */
+export declare function getStepStatus(flowState: FlowState, stepNode: object): StepStatus;
+/** Step visibility — from the group's computed FieldState (isVisible is reactive). */
+export declare function isStepVisible(kernel: Kernel, stepNode: object): boolean;
+/** Composite flow loading: true when at least one step is resolving. */
+export declare function flowLoading(kernel: Kernel, flowState: FlowState): boolean;
+/**
+ * Collect leaf errors of a step's subtree. Validation is computed "live" via
+ * computeFieldState(revalidate=true) — independent of the group's revalidate
+ * flag (which only the submit pipeline sets). Hidden leaves are skipped.
+ * Lists inside a step are skipped (parity with collectLeafStates).
+ *
+ * `basePath` — prefix for error paths. The flow passes the step KEY: paths
+ * come out relative to the flow node ("welcome.name") — the same base the
+ * submit pipeline uses for errors on flow.submit() (collectLeafStates builds
+ * paths from the submitted node).
+ */
+export declare function collectStepErrors(kernel: Kernel, stepNode: AnyConfigNode, basePath?: string): FlowError[];
+/** Live aggregate of step validity (flow.steps.x.isInvalid). */
+export declare function stepIsInvalid(kernel: Kernel, stepNode: AnyConfigNode): boolean;
+/**
+ * Flow errors over visited visible steps (the scope of flow.validate()).
+ * Hidden steps are always excluded — an untaken branch must not block.
+ * Error paths are relative to the flow node ("stepKey.field") — same as
+ * SubmitResult on flow.submit().
+ */
+export declare function collectFlowErrors(kernel: Kernel, flowState: FlowState): FlowError[];
+/** Aggregate flow.isInvalid: any errors in visited visible steps. */
+export declare function flowIsInvalid(kernel: Kernel, flowState: FlowState): boolean;
+/**
+ * flow.validate(): collect errors of the visited steps, write them into the
+ * reactive flow.errors and return them. Empty array = all valid.
+ */
+export declare function flowValidate(kernel: Kernel, flowState: FlowState): FlowError[];
+/**
+ * Filter out submit-pipeline errors from leaves under HIDDEN steps of any
+ * flow: the base pipeline validates all leaves regardless of visibility, and
+ * without this filter an untaken branch with isRequired fields would block
+ * finalization forever.
+ *
+ * `submittedNode` — the node the submit ran for: pipeline error paths are
+ * RELATIVE to it (collectLeafStates builds paths from the submitted node),
+ * so the absolute paths of hidden steps are rebased to the same base.
+ */
+export declare function filterHiddenFlowStepErrors(kernel: Kernel, errors: Array<{
+    path: string;
+    message: string;
+}>, submittedNode: AnyConfigNode): Array<{
+    path: string;
+    message: string;
+}>;
+/**
+ * flow.submit(): the standard group-submit pipeline over the flow node
+ * (submitting → beforeSubmit → validate → onSubmit → afterSubmit; leaves of
+ * hidden steps are filtered by the pipeline). Validation errors land in the
+ * reactive flow.errors; on success errors are cleared.
+ */
+export declare function flowSubmit(kernel: Kernel, flowState: FlowState): Promise<SubmitResult>;
+/**
+ * Step entry lifecycle: onEnter → resolve (eager) → onReady.
+ *
+ * - `onEnter` / `onReady` receive FLOW-scoped values (all steps by key) —
+ *   the flow's live groupSlot reference; fire-and-forget.
+ * - the step's resolve is a standard group resolve; the flow triggers it ON
+ *   ENTRY (equivalent to first access). Already resolved/error (cached) — not
+ *   re-run, and onReady is NOT invoked again.
+ * - Without resolve — onReady fires right after onEnter.
+ */
+export declare function runEntryLifecycle(kernel: Kernel, flowState: FlowState, stepNode: AnyConfigNode): void;
+/**
+ * nextStep(): the next VISIBLE step in array order; hidden ones are skipped.
+ * When no visible steps remain ahead — finalize via flow.submit() (on
+ * validation errors onSubmit is not called, errors land in flow.errors, the
+ * step does not change).
+ */
+export declare function flowNextStep(kernel: Kernel, flowState: FlowState): void;
+/** back(): go back along the visit stack. No-op when the stack is empty (canGoBack). */
+export declare function flowBack(kernel: Kernel, flowState: FlowState): void;
+/**
+ * goTo(keyOrIndex): arbitrary jump by key or index.
+ * Unknown key/index — throws (catches typos during development).
+ * Jumping to the current step is a no-op.
+ */
+export declare function flowGoTo(kernel: Kernel, flowState: FlowState, keyOrIndex: string | number): void;
+/**
+ * Reset flow navigation: the first step is active, the stack and visited set
+ * are cleared, step resolve states go back to idle. The first step's entry
+ * lifecycle (onEnter → resolve → onReady) runs anew — mirroring initialization.
+ */
+export declare function resetFlowNav(kernel: Kernel, flowState: FlowState): void;
+/**
+ * Reset navigation of all flows that fall into the reset subtree.
+ * Called from ResetPipeline (root reset → all flows; group reset → flows inside it).
+ */
+export declare function resetFlowNavForSubtree(kernel: Kernel, groupNode: AnyConfigNode): void;
+/**
+ * Initialization lifecycle: the first step of every flow is "entered" at
+ * store creation (onEnter → resolve → onReady). Called from the Palistor
+ * constructor.
+ *
+ * Also pre-warms the proxyCache of flow nodes: a step's identity view reads
+ * parent.proxy from the cache on the first step.submit(), and the flow proxy
+ * must already exist by then — otherwise the step's onSubmit would receive
+ * undefined as its third argument.
+ */
+export declare function initFlows(kernel: Kernel): void;
+/** Flow navigation snapshot in the persist payload (field values are stored separately). */
+export interface FlowNavSnapshot {
+    currentStepKey: string;
+    visitStack: string[];
+    visitedKeys: string[];
+}
+/**
+ * Serialize navigation of all flows for persist: key — the flow node's dot-path.
+ * Step statuses are not saved — they are derived from navigation on hydrate.
+ */
+export declare function serializeFlowNav(kernel: Kernel): Record<string, FlowNavSnapshot> | null;
+/**
+ * Restore flow navigation from a persist snapshot. Unknown step keys (the
+ * config changed) are dropped; an incompatible currentStepKey leaves the flow
+ * in its current state. Returns the changed nodes for notify and the flows
+ * whose active step changed (for a repeated entry lifecycle).
+ */
+export declare function restoreFlowNav(kernel: Kernel, snapshots: Record<string, FlowNavSnapshot>): {
+    changed: Set<object>;
+    entered: FlowState[];
+};
+/** Entry lifecycle of the current step (used by persist after hydration). */
+export declare function runFlowEntryLifecycle(kernel: Kernel, flowState: FlowState): void;
+export {};
+//# sourceMappingURL=flowNavigation.d.ts.map

package/dist/store/flow/flowNavigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowNavigation.d.ts","sourceRoot":"","sources":["../../../store/flow/flowNavigation.ts"],"names":[],"mappings":"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"}