@visual-platform/contracts 0.3.0 → 0.4.0

package/dist/flows.d.ts

@@ -0,0 +1,267 @@
+import { z } from "zod";
+import { type ComponentNode } from "./page-document.js";
+/**
+ * Flows (ADR-049, ADR-050): a named sequence of steps an event runs — call an app action, open or close
+ * a modal, go to a link (same or new tab), remember a value, branch, wait, scroll/focus a block, copy
+ * text, send an analytics event, refresh data, or run another flow with arguments. Steps are a closed
+ * set: never code.
+ *
+ * Where flows live (name lookup in this order): the page (root.props.flows) → components on it (flows)
+ * → the project's flow library (artifact type "flow", versioned, pinned by each release).
+ * A block's event binds a flow by name, like a handler: node.events.click = "onCheckout".
+ */
+export declare const FLOW_NAME: RegExp;
+/** Roots the browser knows while a flow runs; other paths are read on the server at render. */
+export declare const FLOW_CLIENT_ROOTS: readonly ["event", "state", "steps", "args"];
+export declare const MAX_FLOW_DEPTH = 5;
+export declare const MAX_WAIT_MS = 30000;
+export declare const ValueRefSchema: z.ZodUnion<readonly [z.ZodObject<{
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+}, z.core.$strict>, z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strict>]>;
+export type ValueRef = z.infer<typeof ValueRefSchema>;
+export type FlowStep = {
+    kind: "action";
+    action: string;
+    input?: Record<string, ValueRef> | undefined;
+    as?: string | undefined;
+} | {
+    kind: "flow";
+    flow: string;
+    args?: Record<string, ValueRef> | undefined;
+} | {
+    kind: "open";
+    modal: string;
+} | {
+    kind: "close";
+    modal?: string | undefined;
+} | {
+    kind: "navigate";
+    href?: string | undefined;
+    hrefFrom?: ValueRef | undefined;
+    newTab?: boolean | undefined;
+} | {
+    kind: "toast";
+    text: string;
+    tone?: "info" | "success" | "error" | undefined;
+} | {
+    kind: "set";
+    key: string;
+    value?: ValueRef | undefined;
+    op?: "set" | "increment" | "decrement" | "toggle" | undefined;
+} | {
+    kind: "if";
+    when: string;
+    then: FlowStep[];
+    else?: FlowStep[] | undefined;
+} | {
+    kind: "wait";
+    ms: number;
+} | {
+    kind: "scroll";
+    target: string;
+} | {
+    kind: "focus";
+    target: string;
+} | {
+    kind: "copy";
+    value: ValueRef;
+} | {
+    kind: "track";
+    event: string;
+    props?: Record<string, ValueRef> | undefined;
+} | {
+    kind: "animate";
+    target: string;
+    preset: string;
+} | {
+    kind: "refresh";
+} | {
+    kind: "stop";
+};
+export type FlowStepKind = FlowStep["kind"];
+export declare const FlowStepSchema: z.ZodType<FlowStep>;
+export declare const FLOW_PARAM_TYPES: readonly ["text", "number", "boolean"];
+export declare const FlowParamSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    type: z.ZodEnum<{
+        boolean: "boolean";
+        number: "number";
+        text: "text";
+    }>;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type FlowParam = z.infer<typeof FlowParamSchema>;
+export type Flow = {
+    name: string;
+    label?: string | undefined;
+    description?: string | undefined;
+    params?: FlowParam[] | undefined;
+    steps: FlowStep[];
+    onError?: FlowStep[] | undefined;
+};
+export declare const FlowSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        type: z.ZodEnum<{
+            boolean: "boolean";
+            number: "number";
+            text: "text";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    steps: z.ZodArray<z.ZodType<FlowStep, unknown, z.core.$ZodTypeInternals<FlowStep, unknown>>>;
+    onError: z.ZodOptional<z.ZodArray<z.ZodType<FlowStep, unknown, z.core.$ZodTypeInternals<FlowStep, unknown>>>>;
+}, z.core.$strict>;
+/** Every step, nested ones included. */
+export declare function walkSteps(steps: readonly FlowStep[] | undefined, fn: (s: FlowStep, depth: number) => void, depth?: number): void;
+/** Names of the flows a flow calls (sub-flows). */
+export declare function flowCalls(f: Flow): string[];
+/** Sub-flow cycle (a → b → a) as a path, or null. */
+export declare function findFlowCycle(flows: readonly Flow[]): string[] | null;
+/** Sub-flows called but not defined in this set (they must come from the project's flow library). */
+export declare function externalFlowCalls(flows: readonly Flow[]): string[];
+/** Flows of a page/component. Sub-flows not defined here are looked up in the flow library at publish. */
+export declare const FlowsSchema: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        type: z.ZodEnum<{
+            boolean: "boolean";
+            number: "number";
+            text: "text";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    steps: z.ZodArray<z.ZodType<FlowStep, unknown, z.core.$ZodTypeInternals<FlowStep, unknown>>>;
+    onError: z.ZodOptional<z.ZodArray<z.ZodType<FlowStep, unknown, z.core.$ZodTypeInternals<FlowStep, unknown>>>>;
+}, z.core.$strict>>;
+/**
+ * Page triggers (ADR-050/051): run a flow (or handler) when the page loads (optionally later), when the
+ * visitor is about to leave (mouse exits at the top), scrolls past a percentage, stays idle, every N
+ * seconds, when the tab is hidden/shown again, or on leaving the page (send analytics only there).
+ */
+export declare const PAGE_TRIGGERS: readonly ["load", "exitIntent", "scroll", "idle", "interval", "tabHidden", "tabVisible", "leave"];
+export type PageTriggerKind = (typeof PAGE_TRIGGERS)[number];
+export declare const FlowTriggerSchema: z.ZodObject<{
+    on: z.ZodEnum<{
+        exitIntent: "exitIntent";
+        idle: "idle";
+        interval: "interval";
+        leave: "leave";
+        load: "load";
+        scroll: "scroll";
+        tabHidden: "tabHidden";
+        tabVisible: "tabVisible";
+    }>;
+    flow: z.ZodString;
+    delayMs: z.ZodOptional<z.ZodNumber>;
+    percent: z.ZodOptional<z.ZodNumber>;
+    ms: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    once: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type FlowTrigger = z.infer<typeof FlowTriggerSchema>;
+export declare const FlowTriggersSchema: z.ZodArray<z.ZodObject<{
+    on: z.ZodEnum<{
+        exitIntent: "exitIntent";
+        idle: "idle";
+        interval: "interval";
+        leave: "leave";
+        load: "load";
+        scroll: "scroll";
+        tabHidden: "tabHidden";
+        tabVisible: "tabVisible";
+    }>;
+    flow: z.ZodString;
+    delayMs: z.ZodOptional<z.ZodNumber>;
+    percent: z.ZodOptional<z.ZodNumber>;
+    ms: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    once: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>>;
+/**
+ * Block lifecycle (ADR-051): every block can run a flow (or handler) when it appears in the browser
+ * (mount), disappears (unmount — a state gate hides it, the page changes), scrolls into view (visible,
+ * once per view unless visibleOnce = false), scrolls out (leave), or every N seconds while shown (every).
+ */
+export declare const LIFECYCLE_KINDS: readonly ["mount", "unmount", "visible", "leave"];
+export type LifecycleKind = (typeof LIFECYCLE_KINDS)[number] | "every";
+export declare const NodeLifecycleSchema: z.ZodObject<{
+    mount: z.ZodOptional<z.ZodString>;
+    unmount: z.ZodOptional<z.ZodString>;
+    visible: z.ZodOptional<z.ZodString>;
+    leave: z.ZodOptional<z.ZodString>;
+    visibleOnce: z.ZodOptional<z.ZodBoolean>;
+    every: z.ZodOptional<z.ZodObject<{
+        run: z.ZodString;
+        ms: z.ZodNumber;
+        max: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type NodeLifecycle = z.infer<typeof NodeLifecycleSchema>;
+/** Names a block's lifecycle runs. */
+export declare const lifecycleNames: (l: NodeLifecycle | undefined) => string[];
+/** Starting values of the page state (state.*): wizard step, quantity… */
+export declare const FlowStateSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+/** A flow in the project library (artifact type "flow"): one flow + schema version. */
+export declare const FlowDocumentSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        type: z.ZodEnum<{
+            boolean: "boolean";
+            number: "number";
+            text: "text";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    steps: z.ZodArray<z.ZodType<FlowStep, unknown, z.core.$ZodTypeInternals<FlowStep, unknown>>>;
+    onError: z.ZodOptional<z.ZodArray<z.ZodType<FlowStep, unknown, z.core.$ZodTypeInternals<FlowStep, unknown>>>>;
+    schemaVersion: z.ZodLiteral<1>;
+}, z.core.$strict>;
+export type FlowDocument = z.infer<typeof FlowDocumentSchema>;
+export declare const flowFromDocument: ({ schemaVersion: _v, ...f }: FlowDocument) => Flow;
+export declare function filterFields(expr: string): string[];
+/**
+ * Paths a flow (and its sub-flows) reads that the browser does not know — item.*, page data… The server
+ * reads them from the block's data at render and hands them to the event boundary.
+ */
+export declare function flowServerPaths(name: string, flows: readonly Flow[]): string[];
+/** Does a showIf read the page state? Such blocks are shown/hidden in the browser (ADR-050). */
+export declare const showIfUsesState: (expr: string | undefined) => boolean;
+/** Non-state paths of a state showIf (read on the server, passed to the browser gate). */
+export declare const showIfServerPaths: (expr: string) => string[];
+/** Modal names opened/closed by flows (editor checks that a Modal with that name exists). */
+export declare function flowModals(flows: readonly Flow[]): string[];
+/** App action names flows call (publish/editor can check them against the app registry). */
+export declare function flowActions(flows: readonly Flow[]): string[];
+/**
+ * Flow names a document needs: event names of its blocks, triggers, and sub-flows they call, followed
+ * through the given flows (local + library). Used by delivery to ship only the flows a page uses.
+ */
+export declare function neededFlowNames(nodes: readonly ComponentNode[], available: readonly Flow[], extra?: readonly string[]): string[];
+/** A readable sentence for one step (not translated; the editor shows it as the collapsed summary). */
+export declare function describeStep(s: FlowStep): string;
+/** The whole flow as indented lines (then/else nested), used to compare versions. */
+export declare function describeFlow(f: Pick<Flow, "steps" | "onError" | "params" | "label">): string[];
+/** Line diff (LCS) between two describeFlow outputs: unchanged / added / removed lines in order. */
+export declare function diffLines(a: readonly string[], b: readonly string[]): {
+    kind: "same" | "add" | "del";
+    text: string;
+}[];
+/** Animation presets used by "animate" steps (the runtime needs their keyframes in the browser). */
+export declare function flowPresets(flows: readonly Flow[]): string[];
+//# sourceMappingURL=flows.d.ts.map

package/dist/flows.d.ts.map

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

package/dist/flows.js

@@ -0,0 +1,387 @@
+import { z } from "zod";
+import { parseFilter } from "./tables.js";
+import { walkNodes } from "./page-document.js";
+/**
+ * Flows (ADR-049, ADR-050): a named sequence of steps an event runs — call an app action, open or close
+ * a modal, go to a link (same or new tab), remember a value, branch, wait, scroll/focus a block, copy
+ * text, send an analytics event, refresh data, or run another flow with arguments. Steps are a closed
+ * set: never code.
+ *
+ * Where flows live (name lookup in this order): the page (root.props.flows) → components on it (flows)
+ * → the project's flow library (artifact type "flow", versioned, pinned by each release).
+ * A block's event binds a flow by name, like a handler: node.events.click = "onCheckout".
+ */
+export const FLOW_NAME = /^on[A-Z][A-Za-z0-9]{0,47}$/;
+const KEY = /^[A-Za-z_][A-Za-z0-9_]{0,39}$/;
+/** event.value · item.id · steps.order.data.id · state.coupon · args.productId · products.0.name */
+const PATH = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z0-9_]+){0,9}$/;
+const SAFE_HREF = /^(\/(?!\/)|https?:\/\/|mailto:|tel:)[^\s"'<>]*$/;
+const NODE_ID = /^n_[A-Za-z0-9_-]{3,80}$/;
+/** Roots the browser knows while a flow runs; other paths are read on the server at render. */
+export const FLOW_CLIENT_ROOTS = ["event", "state", "steps", "args"];
+export const MAX_FLOW_DEPTH = 5;
+export const MAX_WAIT_MS = 30_000;
+const Literal = z.union([z.string().max(500), z.number(), z.boolean(), z.null()]);
+export const ValueRefSchema = z.union([
+    z.object({ value: Literal }).strict(),
+    z.object({ path: z.string().max(200).regex(PATH, "paths look like item.id or event.value") }).strict(),
+]);
+const checkFilter = (s) => { try {
+    parseFilter(s);
+    return true;
+}
+catch {
+    return false;
+} };
+const refs = z.record(z.string().regex(KEY), ValueRefSchema).refine((r) => Object.keys(r).length <= 20, "at most 20 values");
+export const FlowStepSchema = z.lazy(() => z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("action"), action: z.string().regex(FLOW_NAME, "action names look like onAddToCart"), input: refs.optional(), as: z.string().regex(KEY).optional() }).strict(),
+    z.object({ kind: z.literal("flow"), flow: z.string().regex(FLOW_NAME, "flow names look like onCheckout"), args: refs.optional() }).strict(),
+    z.object({ kind: z.literal("open"), modal: z.string().regex(KEY, "modal names are letters/digits, e.g. checkout") }).strict(),
+    z.object({ kind: z.literal("close"), modal: z.string().regex(KEY).optional() }).strict(),
+    z.object({ kind: z.literal("navigate"), href: z.string().max(500).regex(SAFE_HREF, "links start with /, https://, mailto: or tel:").optional(), hrefFrom: ValueRefSchema.optional(), newTab: z.boolean().optional() }).strict()
+        .refine((s) => !!s.href !== !!s.hrefFrom, "give a link or where to read it from"),
+    z.object({ kind: z.literal("toast"), text: z.string().trim().min(1).max(200), tone: z.enum(["info", "success", "error"]).optional() }).strict(),
+    z.object({ kind: z.literal("set"), key: z.string().regex(KEY), value: ValueRefSchema.optional(), op: z.enum(["set", "increment", "decrement", "toggle"]).optional() }).strict()
+        .refine((s) => (s.op === "toggle" || s.op === "increment" || s.op === "decrement") || s.value !== undefined, "give a value"),
+    z.object({ kind: z.literal("if"), when: z.string().trim().min(1).max(500).refine(checkFilter, "condition syntax: like showIf, e.g. state.qty > 0"), then: z.array(FlowStepSchema).max(20), else: z.array(FlowStepSchema).max(20).optional() }).strict(),
+    z.object({ kind: z.literal("wait"), ms: z.number().int().min(50).max(MAX_WAIT_MS) }).strict(),
+    z.object({ kind: z.literal("scroll"), target: z.string().regex(NODE_ID, "pick a block") }).strict(),
+    z.object({ kind: z.literal("focus"), target: z.string().regex(NODE_ID, "pick a block") }).strict(),
+    z.object({ kind: z.literal("copy"), value: ValueRefSchema }).strict(),
+    z.object({ kind: z.literal("track"), event: z.string().regex(/^[A-Za-z][A-Za-z0-9_.:-]{0,59}$/, "analytics event names: letters, digits, _ . : -"), props: refs.optional() }).strict(),
+    z.object({ kind: z.literal("animate"), target: z.string().regex(NODE_ID, "pick a block"), preset: z.string().regex(/^[a-z][A-Za-z0-9]{0,39}$/, "pick an animation") }).strict(),
+    z.object({ kind: z.literal("refresh") }).strict(),
+    z.object({ kind: z.literal("stop") }).strict(),
+]));
+export const FLOW_PARAM_TYPES = ["text", "number", "boolean"];
+export const FlowParamSchema = z.object({
+    name: z.string().regex(KEY),
+    label: z.string().max(60).optional(),
+    type: z.enum(FLOW_PARAM_TYPES),
+    required: z.boolean().optional(),
+}).strict();
+const flowShape = {
+    name: z.string().regex(FLOW_NAME, "flow names look like onCheckout"),
+    label: z.string().max(60).optional(),
+    description: z.string().max(300).optional(),
+    /** Arguments a caller passes (`flow` step args); read inside as args.<name>. */
+    params: z.array(FlowParamSchema).max(10).optional(),
+    steps: z.array(FlowStepSchema).min(1).max(30),
+    /** Runs when an action step fails (the flow then stops). */
+    onError: z.array(FlowStepSchema).max(10).optional(),
+};
+export const FlowSchema = z.object(flowShape).strict();
+/** Every step, nested ones included. */
+export function walkSteps(steps, fn, depth = 0) {
+    for (const s of steps ?? []) {
+        fn(s, depth);
+        if (s.kind === "if") {
+            walkSteps(s.then, fn, depth + 1);
+            walkSteps(s.else, fn, depth + 1);
+        }
+    }
+}
+const allSteps = (f) => [...f.steps, ...(f.onError ?? [])];
+/** Names of the flows a flow calls (sub-flows). */
+export function flowCalls(f) {
+    const out = new Set();
+    walkSteps(allSteps(f), (s) => { if (s.kind === "flow")
+        out.add(s.flow); });
+    return [...out];
+}
+/** Sub-flow cycle (a → b → a) as a path, or null. */
+export function findFlowCycle(flows) {
+    const calls = new Map(flows.map((f) => [f.name, flowCalls(f)]));
+    const state = new Map();
+    const stack = [];
+    const visit = (n) => {
+        if (state.get(n) === 2)
+            return null;
+        if (state.get(n) === 1)
+            return [...stack.slice(stack.indexOf(n)), n];
+        state.set(n, 1);
+        stack.push(n);
+        for (const c of calls.get(n) ?? [])
+            if (calls.has(c)) {
+                const r = visit(c);
+                if (r)
+                    return r;
+            }
+        stack.pop();
+        state.set(n, 2);
+        return null;
+    };
+    for (const f of flows) {
+        const r = visit(f.name);
+        if (r)
+            return r;
+    }
+    return null;
+}
+/** Sub-flows called but not defined in this set (they must come from the project's flow library). */
+export function externalFlowCalls(flows) {
+    const own = new Set(flows.map((f) => f.name));
+    return [...new Set(flows.flatMap(flowCalls))].filter((n) => !own.has(n)).sort();
+}
+function checkFlowSet(flows, ctx) {
+    const seen = new Set();
+    for (const f of flows) {
+        if (seen.has(f.name))
+            ctx.addIssue({ code: "custom", message: `duplicate flow "${f.name}"` });
+        seen.add(f.name);
+    }
+    for (const f of flows) {
+        let total = 0;
+        let deep = 0;
+        walkSteps(allSteps(f), (_s, d) => { total++; deep = Math.max(deep, d); });
+        if (total > 80)
+            ctx.addIssue({ code: "custom", message: `flow "${f.name}" has more than 80 steps` });
+        if (deep > 3)
+            ctx.addIssue({ code: "custom", message: `flow "${f.name}": conditions nest at most 4 levels` });
+    }
+    const cycle = findFlowCycle(flows);
+    if (cycle)
+        ctx.addIssue({ code: "custom", message: `FLOW_CYCLE: flows call each other (${cycle.join(" → ")})` });
+}
+/** Flows of a page/component. Sub-flows not defined here are looked up in the flow library at publish. */
+export const FlowsSchema = z.array(FlowSchema).max(30).superRefine((flows, ctx) => checkFlowSet(flows, ctx));
+/**
+ * Page triggers (ADR-050/051): run a flow (or handler) when the page loads (optionally later), when the
+ * visitor is about to leave (mouse exits at the top), scrolls past a percentage, stays idle, every N
+ * seconds, when the tab is hidden/shown again, or on leaving the page (send analytics only there).
+ */
+export const PAGE_TRIGGERS = ["load", "exitIntent", "scroll", "idle", "interval", "tabHidden", "tabVisible", "leave"];
+export const FlowTriggerSchema = z.object({
+    on: z.enum(PAGE_TRIGGERS),
+    flow: z.string().regex(FLOW_NAME),
+    /** load: wait before running. */
+    delayMs: z.number().int().min(0).max(120_000).optional(),
+    /** scroll: page depth reached (1–100 %). */
+    percent: z.number().int().min(1).max(100).optional(),
+    /** idle: no input for this long · interval: every this long. */
+    ms: z.number().int().min(1000).max(3_600_000).optional(),
+    /** interval: stop after this many runs. */
+    max: z.number().int().min(1).max(1000).optional(),
+    /** exitIntent / scroll / idle / tabHidden / tabVisible: only the first time per page view (default true). */
+    once: z.boolean().optional(),
+}).strict().superRefine((t, ctx) => {
+    if ((t.on === "idle" || t.on === "interval") && !t.ms)
+        ctx.addIssue({ code: "custom", path: ["ms"], message: `${t.on} needs a duration` });
+    if (t.on === "scroll" && !t.percent)
+        ctx.addIssue({ code: "custom", path: ["percent"], message: "scroll needs a percentage" });
+});
+export const FlowTriggersSchema = z.array(FlowTriggerSchema).max(10);
+/**
+ * Block lifecycle (ADR-051): every block can run a flow (or handler) when it appears in the browser
+ * (mount), disappears (unmount — a state gate hides it, the page changes), scrolls into view (visible,
+ * once per view unless visibleOnce = false), scrolls out (leave), or every N seconds while shown (every).
+ */
+export const LIFECYCLE_KINDS = ["mount", "unmount", "visible", "leave"];
+export const NodeLifecycleSchema = z.object({
+    mount: z.string().regex(FLOW_NAME).optional(),
+    unmount: z.string().regex(FLOW_NAME).optional(),
+    visible: z.string().regex(FLOW_NAME).optional(),
+    leave: z.string().regex(FLOW_NAME).optional(),
+    visibleOnce: z.boolean().optional(),
+    every: z.object({ run: z.string().regex(FLOW_NAME), ms: z.number().int().min(1000).max(3_600_000), max: z.number().int().min(1).max(10_000).optional() }).strict().optional(),
+}).strict().refine((l) => Object.keys(l).some((k) => k !== "visibleOnce"), "choose at least one moment");
+/** Names a block's lifecycle runs. */
+export const lifecycleNames = (l) => (l ? [l.mount, l.unmount, l.visible, l.leave, l.every?.run].filter((x) => !!x) : []);
+/** Starting values of the page state (state.*): wizard step, quantity… */
+export const FlowStateSchema = z.record(z.string().regex(KEY), Literal).refine((r) => Object.keys(r).length <= 30, "at most 30 state values");
+/** A flow in the project library (artifact type "flow"): one flow + schema version. */
+export const FlowDocumentSchema = z.object({ schemaVersion: z.literal(1), ...flowShape }).strict();
+export const flowFromDocument = ({ schemaVersion: _v, ...f }) => f;
+// ---------- analysis ----------
+const refPaths = (r, out) => { if (r && "path" in r)
+    out.add(r.path); };
+export function filterFields(expr) {
+    let f;
+    try {
+        f = parseFilter(expr);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    const walk = (x) => { if (!x)
+        return; if ("and" in x)
+        x.and.forEach(walk);
+    else if ("or" in x)
+        x.or.forEach(walk);
+    else if ("not" in x)
+        walk(x.not);
+    else
+        out.push(x.field); };
+    walk(f);
+    return out;
+}
+const isClientPath = (p) => FLOW_CLIENT_ROOTS.includes(p.split(".")[0]);
+/**
+ * Paths a flow (and its sub-flows) reads that the browser does not know — item.*, page data… The server
+ * reads them from the block's data at render and hands them to the event boundary.
+ */
+export function flowServerPaths(name, flows) {
+    const byName = new Map(flows.map((f) => [f.name, f]));
+    const out = new Set();
+    const seen = new Set();
+    const visit = (n) => {
+        const f = byName.get(n);
+        if (!f || seen.has(n))
+            return;
+        seen.add(n);
+        walkSteps(allSteps(f), (s) => {
+            if (s.kind === "action")
+                for (const r of Object.values(s.input ?? {}))
+                    refPaths(r, out);
+            else if (s.kind === "flow") {
+                for (const r of Object.values(s.args ?? {}))
+                    refPaths(r, out);
+                visit(s.flow);
+            }
+            else if (s.kind === "set")
+                refPaths(s.value, out);
+            else if (s.kind === "navigate")
+                refPaths(s.hrefFrom, out);
+            else if (s.kind === "copy")
+                refPaths(s.value, out);
+            else if (s.kind === "track")
+                for (const r of Object.values(s.props ?? {}))
+                    refPaths(r, out);
+            else if (s.kind === "if")
+                for (const p of filterFields(s.when))
+                    out.add(p);
+        });
+    };
+    visit(name);
+    return [...out].filter((p) => !isClientPath(p)).sort();
+}
+/** Does a showIf read the page state? Such blocks are shown/hidden in the browser (ADR-050). */
+export const showIfUsesState = (expr) => !!expr && filterFields(expr).some((p) => p.split(".")[0] === "state");
+/** Non-state paths of a state showIf (read on the server, passed to the browser gate). */
+export const showIfServerPaths = (expr) => filterFields(expr).filter((p) => !isClientPath(p));
+/** Modal names opened/closed by flows (editor checks that a Modal with that name exists). */
+export function flowModals(flows) {
+    const out = new Set();
+    for (const f of flows)
+        walkSteps(allSteps(f), (s) => { if ((s.kind === "open" || s.kind === "close") && s.modal)
+            out.add(s.modal); });
+    return [...out].sort();
+}
+/** App action names flows call (publish/editor can check them against the app registry). */
+export function flowActions(flows) {
+    const out = new Set();
+    for (const f of flows)
+        walkSteps(allSteps(f), (s) => { if (s.kind === "action")
+            out.add(s.action); });
+    return [...out].sort();
+}
+/**
+ * Flow names a document needs: event names of its blocks, triggers, and sub-flows they call, followed
+ * through the given flows (local + library). Used by delivery to ship only the flows a page uses.
+ */
+export function neededFlowNames(nodes, available, extra = []) {
+    const byName = new Map(available.map((f) => [f.name, f]));
+    const out = new Set();
+    const visit = (n) => { if (out.has(n) || !byName.has(n))
+        return; out.add(n); for (const c of flowCalls(byName.get(n)))
+        visit(c); };
+    for (const n of walkNodes(nodes)) {
+        for (const e of Object.values(n.events ?? {}))
+            if (e)
+                visit(e);
+        for (const e of lifecycleNames(n.lifecycle))
+            visit(e);
+    }
+    for (const e of extra)
+        visit(e);
+    return [...out].sort();
+}
+// ---------- reading flows: one sentence per step (editor summaries, history compare, AI) ----------
+const refText = (r) => (!r ? "—" : "path" in r ? r.path : JSON.stringify(r.value));
+const mapText = (m) => Object.entries(m ?? {}).map(([k, v]) => `${k} = ${refText(v)}`).join(", ");
+/** A readable sentence for one step (not translated; the editor shows it as the collapsed summary). */
+export function describeStep(s) {
+    switch (s.kind) {
+        case "action": return `Run action ${s.action || "?"}${s.input && Object.keys(s.input).length ? ` with ${mapText(s.input)}` : ""}${s.as ? ` → steps.${s.as}` : ""}`;
+        case "flow": return `Run flow ${s.flow || "?"}${s.args && Object.keys(s.args).length ? ` with ${mapText(s.args)}` : ""}`;
+        case "open": return `Open modal ${s.modal || "?"}`;
+        case "close": return s.modal ? `Close modal ${s.modal}` : "Close all modals";
+        case "navigate": return `Go to ${s.href ?? refText(s.hrefFrom)}${s.newTab ? " (new tab)" : ""}`;
+        case "toast": return `Show ${s.tone ?? "info"} message “${s.text}”`;
+        case "set": {
+            const op = s.op ?? "set";
+            return op === "toggle" ? `Toggle state.${s.key}` : op === "set" ? `Set state.${s.key} = ${refText(s.value)}` : `${op === "increment" ? "Increase" : "Decrease"} state.${s.key} by ${s.value ? refText(s.value) : "1"}`;
+        }
+        case "if": return `If ${s.when}`;
+        case "wait": return `Wait ${s.ms >= 1000 ? `${s.ms / 1000} s` : `${s.ms} ms`}`;
+        case "scroll": return `Scroll to block ${s.target || "?"}`;
+        case "focus": return `Focus block ${s.target || "?"}`;
+        case "copy": return `Copy ${refText(s.value)}`;
+        case "track": return `Track “${s.event}”${s.props && Object.keys(s.props).length ? ` with ${mapText(s.props)}` : ""}`;
+        case "animate": return `Animate block ${s.target || "?"} with ${s.preset || "?"}`;
+        case "refresh": return "Refresh data";
+        case "stop": return "Stop";
+    }
+}
+/** The whole flow as indented lines (then/else nested), used to compare versions. */
+export function describeFlow(f) {
+    const out = [];
+    if (f.label)
+        out.push(`Label: ${f.label}`);
+    if (f.params?.length)
+        out.push(`Parameters: ${f.params.map((p) => `${p.name}${p.required ? "*" : ""}: ${p.type}`).join(", ")}`);
+    const walk = (steps, indent, prefix) => steps.forEach((s, i) => {
+        out.push(`${indent}${prefix}${i + 1}. ${describeStep(s)}`);
+        if (s.kind === "if") {
+            out.push(`${indent}   then:`);
+            walk(s.then, `${indent}      `, "");
+            if (s.else?.length) {
+                out.push(`${indent}   else:`);
+                walk(s.else, `${indent}      `, "");
+            }
+        }
+    });
+    walk(f.steps, "", "");
+    if (f.onError?.length) {
+        out.push("If an action fails:");
+        walk(f.onError, "   ", "");
+    }
+    return out;
+}
+/** Line diff (LCS) between two describeFlow outputs: unchanged / added / removed lines in order. */
+export function diffLines(a, b) {
+    const m = a.length, n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = m - 1; i >= 0; i--)
+        for (let j = n - 1; j >= 0; j--)
+            dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    const out = [];
+    let i = 0, j = 0;
+    while (i < m && j < n) {
+        if (a[i] === b[j]) {
+            out.push({ kind: "same", text: a[i] });
+            i++;
+            j++;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1])
+            out.push({ kind: "del", text: a[i++] });
+        else
+            out.push({ kind: "add", text: b[j++] });
+    }
+    while (i < m)
+        out.push({ kind: "del", text: a[i++] });
+    while (j < n)
+        out.push({ kind: "add", text: b[j++] });
+    return out;
+}
+/** Animation presets used by "animate" steps (the runtime needs their keyframes in the browser). */
+export function flowPresets(flows) {
+    const out = new Set();
+    for (const f of flows)
+        walkSteps([...f.steps, ...(f.onError ?? [])], (s) => { if (s.kind === "animate")
+            out.add(s.preset); });
+    return [...out].sort();
+}
+//# sourceMappingURL=flows.js.map