@visual-platform/contracts 0.2.0 → 0.4.0

package/dist/events.js

@@ -8,6 +8,17 @@ export const EVENT_KINDS = ["click", "change", "blur", "enter", "submit", "reset
 /** onSubscribe, onBuyNow… — a valid JS identifier starting with "on" + capital letter. */
 export const EventNameSchema = z.string().regex(/^on[A-Z][A-Za-z0-9]{0,47}$/, "event names look like onSubscribe");
 export const EventBindingsSchema = z.partialRecord(z.enum(EVENT_KINDS), EventNameSchema);
+/**
+ * One step after a Server-Action event (ADR-048 actions), chosen in Studio: show a toast, go to a
+ * page, or refresh the page's data. Closed set — never code.
+ */
+const SAFE_HREF = /^(\/(?!\/)|https?:\/\/)[^\s"'<>]*$/;
+export const EventStepSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("toast"), text: z.string().trim().min(1).max(200) }).strict(),
+    z.object({ kind: z.literal("navigate"), href: z.string().max(500).regex(SAFE_HREF, "links start with / or http(s)://") }).strict(),
+    z.object({ kind: z.literal("refresh") }).strict(),
+]);
+export const EventStepsSchema = z.partialRecord(z.enum(EVENT_KINDS), z.object({ success: EventStepSchema.optional(), error: EventStepSchema.optional() }).strict());
 /** Every event binding used in these documents (for Studio lists and `vp types pull`). */
 export function collectEvents(documents) {
     const out = [];
@@ -16,6 +27,12 @@ export function collectEvents(documents) {
             for (const [kind, name] of Object.entries(n.events ?? {}))
                 if (name)
                     out.push({ name, kind: kind, nodeId: n.id, type: n.type });
+            // Block lifecycle (ADR-051): handlers the app may implement (onMount-style names).
+            const l = n.lifecycle;
+            if (l)
+                for (const [kind, name] of [["mount", l.mount], ["unmount", l.unmount], ["visible", l.visible], ["leave", l.leave], ["every", l.every?.run]])
+                    if (name)
+                        out.push({ name, kind, nodeId: n.id, type: n.type });
         }
     return out;
 }

package/dist/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAsB,MAAM,oBAAoB,CAAC;AAEnE;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;AAGtG,0FAA0F;AAC1F,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,4BAA4B,EAAE,mCAAmC,CAAC,CAAC;AACnH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,eAAe,CAAC,CAAC;AAKzF,0FAA0F;AAC1F,MAAM,UAAU,aAAa,CAAC,SAAgD;IAC5E,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,SAAS;QAAE,KAAK,MAAM,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9D,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC;gBAAE,IAAI,IAAI;oBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAiB,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/I,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB,EAAE,IAAY;IAC9D,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,WAAW,CAAC;IAC7D,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,yBAAyB,CAAC;IACxD,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,IAAI,WAAW,KAAK,UAAU,IAAI,WAAW,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC7E,IAAI,WAAW,KAAK,MAAM,IAAI,WAAW,KAAK,QAAQ,IAAI,WAAW,KAAK,YAAY;YAAE,OAAO,QAAQ,CAAC;QACxG,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,OAAO,QAAQ,CAAC;QACnH,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IACzI,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/flow-sim.d.ts

@@ -0,0 +1,36 @@
+import { type Flow, type FlowStepKind } from "./flows.js";
+/**
+ * Dry-run of a flow (ADR-051): the same decisions as the browser runtime, without side effects —
+ * actions return the mocked result (default { ok: true }), modals/links/messages are only recorded,
+ * waits are skipped. Used by "Test run" in Studio and the editor, and by AI tools.
+ */
+export type SimInput = {
+    /** event.* (value, itemIndex…) */
+    event?: Record<string, unknown> | undefined;
+    /** The block's data: item, page inputs… (what the server would read). */
+    data?: Record<string, unknown> | undefined;
+    state?: Record<string, unknown> | undefined;
+    args?: Record<string, unknown> | undefined;
+    /** Mocked app action results by name; missing → { ok: true, data: null }. */
+    actions?: Record<string, {
+        ok: boolean;
+        data?: unknown;
+        error?: string | undefined;
+    }> | undefined;
+};
+export type SimEntry = {
+    path: string;
+    depth: number;
+    kind: FlowStepKind | "error";
+    text: string;
+    detail?: string | undefined;
+    tone?: "ok" | "warn" | "error" | undefined;
+};
+export type SimResult = {
+    trace: SimEntry[];
+    state: Record<string, unknown>;
+    steps: Record<string, unknown>;
+    outcome: "completed" | "stopped" | "failed" | "navigated";
+};
+export declare function simulateFlow(name: string, flows: readonly Flow[], input?: SimInput): SimResult;
+//# sourceMappingURL=flow-sim.d.ts.map

package/dist/flow-sim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-sim.d.ts","sourceRoot":"","sources":["../src/flow-sim.ts"],"names":[],"mappings":"AACA,OAAO,EAAgC,KAAK,IAAI,EAAiB,KAAK,YAAY,EAAiB,MAAM,YAAY,CAAC;AAGtH;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC5C,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC3C,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC,GAAG,SAAS,CAAC;CACnG,CAAC;AACF,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;CAAE,CAAC;AAC5K,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,OAAO,EAAE,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAA;CAAE,CAAC;AA4EzK,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,EAAE,KAAK,GAAE,QAAa,GAAG,SAAS,CASlG"}

package/dist/flow-sim.js

@@ -0,0 +1,128 @@
+import { readPath } from "./data.js";
+import { describeStep, MAX_FLOW_DEPTH } from "./flows.js";
+import { matchFilter, parseFilter } from "./tables.js";
+const STOP = Symbol("stop");
+function ref(r, run) {
+    if (!r)
+        return undefined;
+    if ("value" in r)
+        return r.value;
+    const root = r.path.split(".")[0];
+    if (root === "event" || root === "state" || root === "steps" || root === "args")
+        return readPath({ event: run.event, state: run.state, steps: run.steps, args: run.args }, r.path);
+    return readPath(run.data, r.path);
+}
+const refs = (m, run) => Object.fromEntries(Object.entries(m ?? {}).map(([k, v]) => [k, ref(v, run)]));
+const show = (v) => { const s = JSON.stringify(v); return s === undefined ? "undefined" : s.length > 120 ? `${s.slice(0, 117)}…` : s; };
+function steps(list, run, depth, flowName, path) {
+    for (const [i, s] of list.entries()) {
+        if (run.trace.length > 500) {
+            run.trace.push({ path, depth, kind: "error", text: "Stopped: more than 500 steps (loop?)", tone: "error" });
+            run.outcome = "stopped";
+            return STOP;
+        }
+        const here = `${path}.${i + 1}`;
+        const log = (detail, tone) => run.trace.push({ path: here, depth, kind: s.kind, text: describeStep(s), ...(detail ? { detail } : {}), ...(tone ? { tone } : {}) });
+        switch (s.kind) {
+            case "action": {
+                const input = refs(s.input, run);
+                const result = run.actions[s.action] ?? { ok: true, data: null };
+                if (s.as)
+                    run.steps[s.as] = result;
+                log(`input ${show(input)} → ${result.ok ? `ok${result.data !== undefined ? ` ${show(result.data)}` : ""}` : `failed${result.error ? `: ${result.error}` : ""}`}`, result.ok ? "ok" : "error");
+                if (!result.ok) {
+                    const f = run.flows.get(flowName);
+                    if (f?.onError?.length) {
+                        run.trace.push({ path: `${here}!`, depth, kind: "error", text: "Running “If an action fails”", tone: "warn" });
+                        steps(f.onError, run, depth + 1, flowName, `${here}!`);
+                    }
+                    run.outcome = "failed";
+                    return STOP;
+                }
+                break;
+            }
+            case "flow": {
+                const sub = run.flows.get(s.flow);
+                if (!sub) {
+                    log(`flow "${s.flow}" not found`, "error");
+                    run.outcome = "failed";
+                    return STOP;
+                }
+                if (depth + 1 > MAX_FLOW_DEPTH) {
+                    log(`deeper than ${MAX_FLOW_DEPTH} flows`, "error");
+                    run.outcome = "failed";
+                    return STOP;
+                }
+                const args = refs(s.args, run);
+                const missing = (sub.params ?? []).filter((p) => p.required && (args[p.name] === undefined || args[p.name] === null || args[p.name] === "")).map((p) => p.name);
+                log(`args ${show(args)}${missing.length ? ` — missing required ${missing.join(", ")}` : ""}`, missing.length ? "warn" : undefined);
+                if (steps(sub.steps, { ...run, args }, depth + 1, sub.name, `${here}>${sub.name}`) === STOP)
+                    return STOP;
+                break;
+            }
+            case "navigate": {
+                const href = s.href ?? String(ref(s.hrefFrom, run) ?? "");
+                const safe = /^(\/(?!\/)|https?:\/\/|mailto:|tel:)[^\s"'<>]*$/.test(href);
+                log(safe ? href : `blocked link "${href}"`, safe ? undefined : "error");
+                if (!safe) {
+                    run.outcome = "failed";
+                    return STOP;
+                }
+                if (!s.newTab) {
+                    run.outcome = "navigated";
+                    return STOP;
+                }
+                break;
+            }
+            case "set": {
+                const cur = run.state[s.key];
+                const v = ref(s.value, run);
+                const op = s.op ?? "set";
+                run.state[s.key] = op === "toggle" ? !cur : op === "increment" ? (Number(cur) || 0) + (v === undefined ? 1 : Number(v) || 0) : op === "decrement" ? (Number(cur) || 0) - (v === undefined ? 1 : Number(v) || 0) : v;
+                log(`state.${s.key}: ${show(cur)} → ${show(run.state[s.key])}`);
+                break;
+            }
+            case "if": {
+                let yes = false;
+                let bad = false;
+                try {
+                    const f = parseFilter(s.when);
+                    yes = f ? matchFilter({ ...run.data, event: run.event, state: run.state, steps: run.steps, args: run.args }, f) : false;
+                }
+                catch {
+                    bad = true;
+                }
+                log(bad ? "condition does not parse" : yes ? "→ then" : "→ else", bad ? "error" : undefined);
+                if (steps(yes ? s.then : s.else ?? [], run, depth + 1, flowName, `${here}${yes ? "?" : ":"}`) === STOP)
+                    return STOP;
+                break;
+            }
+            case "copy":
+                log(`copies ${show(ref(s.value, run))}`);
+                break;
+            case "track":
+                log(`props ${show(refs(s.props, run))}`);
+                break;
+            case "wait":
+                log("skipped in a test run");
+                break;
+            case "stop":
+                log();
+                run.outcome = "stopped";
+                return STOP;
+            default: log();
+        }
+    }
+}
+export function simulateFlow(name, flows, input = {}) {
+    const run = {
+        flows: new Map(flows.map((f) => [f.name, f])), trace: [], state: { ...(input.state ?? {}) }, steps: {}, args: { ...(input.args ?? {}) },
+        event: input.event ?? {}, data: input.data ?? {}, actions: input.actions ?? {}, outcome: "completed",
+    };
+    const f = run.flows.get(name);
+    if (!f)
+        return { trace: [{ path: "", depth: 0, kind: "error", text: `flow "${name}" not found`, tone: "error" }], state: run.state, steps: run.steps, outcome: "failed" };
+    steps(f.steps, run, 0, f.name, f.name);
+    return { trace: run.trace, state: run.state, steps: run.steps, outcome: run.outcome };
+}
+//# sourceMappingURL=flow-sim.js.map

package/dist/flow-sim.js.map

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

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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"}