wizards 0.2.25 → 0.2.26

package/node_modules/@engenty-wizards/shared/dist/definition.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { tableColumnsSchema } from "./engenty/data-tables/index.js";
 import { CONNECTION_KINDS } from "./store.js";
+import { surfaceComponentsSchema, validateSurface } from "./surface.js";
 /** The engenty avatars a wizard can wear. Same cast as engenty's ui-core. */
 export const ENGENTY_KINDS = [
     "round",
@@ -117,6 +118,27 @@ export const itemColumnSchema = z.object({
     label: z.string().min(1),
     kind: z.enum(["text", "number", "money"]),
 });
+export const CONDITION_OPS = [
+    "equals",
+    "notEquals",
+    "in",
+    "notEmpty",
+    "empty",
+    "gt",
+    "lt",
+    "contains",
+];
+/**
+ * One test on what the run knows: an answer by field id, an output of an agent step as
+ * "steps.<step>.<field>", or how many rows a stored list has as "lists.<list>.count".
+ */
+export const conditionSchema = z.object({
+    field: z.string(),
+    op: z.enum(CONDITION_OPS),
+    value: z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]).optional(),
+});
+/** One condition, or several that must all hold. */
+export const whenSchema = z.union([conditionSchema, z.array(conditionSchema).min(1)]);
 export const fieldSchema = z.object({
     id,
     label: z.string().min(1),
@@ -157,15 +179,54 @@ export const fieldSchema = z.object({
      * `items` field takes a table whose columns are its column ids; the person corrects it.
      */
     prefill: z.string().optional(),
+    /**
+     * The field is shown only while this holds. It reads an answer of this page (decided as the
+     * person types) or anything known before the page. A hidden field is not asked and not kept.
+     */
+    when: whenSchema.optional(),
+    /**
+     * select / multiselect: the choices come from earlier data — a list output
+     * ("steps.<id>.<key>"), a column of a table output ("steps.<id>.<key>.<column>") or a column
+     * of a stored list ("lists.<id>.<column>"). `options` stand in while that data is empty.
+     */
+    optionsFrom: z.string().optional(),
+    /**
+     * The field is shown when a decision, made as the run reaches the page, finds this statement
+     * true of the run ("The complaint is about a damaged article").
+     */
+    ask: z.string().min(1).optional(),
+    /** The id of one of the page's `groups`: of a group's fields a decision shows one (or none). */
+    group: z.string().optional(),
 });
-export const nextRuleSchema = z.object({
-    when: z.object({
-        field: z.string(),
-        op: z.enum(["equals", "notEquals", "in", "notEmpty", "empty"]),
-        value: z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]).optional(),
-    }),
-    /** A step id, or "end". */
+export const fieldGroupSchema = z.object({
+    id,
+    /** What the decision picks: "How should we reach the person?" */
+    instructions: z.string().min(1),
+    /** True when showing none of the group's fields is a valid answer. */
+    optional: z.boolean().optional(),
+});
+export const nextRuleSchema = z
+    .object({
+    /** The rule holds when this holds … */
+    when: whenSchema.optional(),
+    /**
+     * … or, instead, when a decision finds this statement true of the run ("The person wants a
+     * refund"). All `ask` rules of a step are decided together, after no `when` rule matched.
+     */
+    ask: z.string().min(1).optional(),
+    /**
+     * A step id, or "end". A rule with neither `when` nor `ask` is the step's "otherwise": where
+     * the run goes when no other rule holds, in place of the next step in the list.
+     */
     goto: z.string(),
+    /**
+     * How often this rule may send the run on in one run; afterwards it is skipped. Meant for a
+     * branch back to an earlier step (a loop), which without it is taken at most ten times.
+     */
+    max: z.number().int().min(1).max(50).optional(),
+})
+    .refine((rule) => rule.when === undefined || rule.ask === undefined, {
+    message: 'A branch has "when" or "ask", not both.',
 });
 const stepBase = {
     id,
@@ -176,22 +237,25 @@ const stepBase = {
 export const outputFieldSchema = z
     .object({
     id,
-    kind: z.enum(["text", "number", "list", "table", "yesno", "choice"]),
-    /** What the field holds; for `yesno` and `choice` the question it answers. */
+    kind: z.enum(["text", "number", "list", "table", "yesno", "choice", "score"]),
+    /** What the field holds; for `yesno`, `choice` and `score` the question it answers. */
     description: z.string().optional(),
     /** Table only: the exact column keys every row has — what a widget reads. */
     columns: z.array(z.string().min(1)).optional(),
-    /** Choice only: the options, one of which is the answer. */
+    /** Choice: the options, one of which is the answer. Score: the levels, lowest first. */
     options: z.array(z.string().min(1)).min(2).max(40).optional(),
 })
-    .refine((field) => field.kind !== "choice" || Boolean(field.options?.length), {
-    message: "A choice field lists its options.",
+    .refine((field) => (field.kind !== "choice" && field.kind !== "score") || Boolean(field.options?.length), { message: "A choice or score field lists its options.", path: ["options"] })
+    .refine((field) => field.kind !== "score" || (field.options?.length ?? 0) <= 10, {
+    message: "A score has at most ten levels.",
     path: ["options"],
 });
 export const pageStepSchema = z.object({
     ...stepBase,
     type: z.literal("page"),
     fields: z.array(fieldSchema).min(1),
+    /** Fields of which a decision shows one: see `group` on a field. */
+    groups: z.array(fieldGroupSchema).max(6).optional(),
     cta: z.string().optional(),
 });
 export const agentStepSchema = z.object({
@@ -213,12 +277,24 @@ export const agentStepSchema = z.object({
         .object({
         format: z.enum(["text", "markdown", "json"]),
         fields: z.array(outputFieldSchema).optional(),
+        /**
+         * json only: the step also composes a view of its result from the surface catalog, bound
+         * to its own fields; reviews and the result show that view instead of a plain table.
+         */
+        surface: z.boolean().optional(),
     })
         .default({ format: "markdown" }),
     /** The kind of model the step needs; default `high`. The model itself is bound elsewhere. */
     model: z.enum(TEXT_CLASSES).optional(),
     effort: z.enum(EFFORTS).optional(),
     /** Shown to the person while it works. */
+    /**
+     * One run of the step per entry, at most twenty: the rows of a table output
+     * ("steps.<id>.<key>"), the entries of a list output, or the rows of a stored list
+     * ("lists.<id>"). The instructions read the entry as {{item.<column>}}, {{index}}, {{count}}.
+     * The output is a table: the entry's columns and the step's output fields, one row per entry.
+     */
+    each: z.string().optional(),
     working: z.string().optional(),
 });
 export const generateStepSchema = z.object({
@@ -319,6 +395,48 @@ export const filmStepSchema = z.object({
     effort: z.enum(EFFORTS).optional(),
     working: z.string().optional(),
 });
+/** A piece a decided surface may show: its components (the first has the piece's id) and what it shows. */
+export const surfaceCandidateSchema = z.object({
+    id,
+    /** What this piece shows, for the decision: "A chart of prices per supplier". */
+    description: z.string().min(1),
+    components: surfaceComponentsSchema,
+    /** Pieces of a group exclude each other: the decision shows one (or none, if optional). */
+    group: z.string().optional(),
+    /** Always shown: a title, the main list. */
+    required: z.boolean().optional(),
+});
+export const surfaceStepSchema = z
+    .object({
+    ...stepBase,
+    type: z.literal("surface"),
+    /** A view from the surface catalog, written once like a widget; every run brings new data. */
+    components: surfaceComponentsSchema.optional(),
+    /**
+     * Instead of `components`: pieces a decision picks from per run (no chart when there is
+     * nothing to chart), drawn in this order under one column.
+     */
+    candidates: z.array(surfaceCandidateSchema).max(16).optional(),
+    groups: z.array(fieldGroupSchema).max(6).optional(),
+    /** What the surface reads as data: key → a field id, steps.id, steps.id.key, lists.id, brand.name or today. */
+    data: z.record(z.string(), z.string()).default({}),
+    working: z.string().optional(),
+})
+    .refine((step) => Boolean(step.components) !== Boolean(step.candidates), {
+    message: 'A surface step has either "components" or "candidates".',
+});
+/**
+ * The components of a decided surface for the pieces kept: one root column holding them in
+ * their order. Every piece kept is the same as all of them for the validator.
+ */
+export function assembleSurface(candidates, kept) {
+    const keep = new Set(kept);
+    const chosen = candidates.filter((c) => keep.has(c.id));
+    return [
+        { id: "root", component: "Column", children: chosen.map((c) => c.components[0]?.id ?? c.id) },
+        ...chosen.flatMap((c) => c.components),
+    ];
+}
 export const reviewStepSchema = z.object({
     ...stepBase,
     type: z.literal("review"),
@@ -343,6 +461,7 @@ export const stepSchema = z.discriminatedUnion("type", [
     agentStepSchema,
     generateStepSchema,
     widgetStepSchema,
+    surfaceStepSchema,
     filmStepSchema,
     reviewStepSchema,
     resultStepSchema,
@@ -357,7 +476,8 @@ export function isDecisionStep(step) {
     return (step.model === "classifier" &&
         step.output.format === "json" &&
         fields.length > 0 &&
-        fields.every((f) => f.kind === "yesno" || f.kind === "choice") &&
+        fields.every((f) => f.kind === "yesno" || f.kind === "choice" || f.kind === "score") &&
+        !step.each &&
         step.tools.length === 0 &&
         !step.mcp?.length &&
         !step.connections?.length);
@@ -444,6 +564,9 @@ export function formatsFor(step) {
     if (step.type === "widget") {
         return step.video ? ["mp4", "png"] : ["html", "png", "pdf", "mp4", "json"];
     }
+    if (step.type === "surface") {
+        return ["json"];
+    }
     if (step.type === "agent") {
         if (step.output.format === "json") {
             return ["json", "csv", "xlsx", "md", "zip"];
@@ -536,7 +659,9 @@ export function validateWizard(def, files) {
                     issues.push({ stepId: step.id, message: `Duplicate field id "${field.id}".` });
                 }
                 fieldIds.add(field.id);
-                if ((field.kind === "select" || field.kind === "multiselect") && !field.options?.length) {
+                if ((field.kind === "select" || field.kind === "multiselect") &&
+                    !field.options?.length &&
+                    !field.optionsFrom) {
                     issues.push({ stepId: step.id, message: `Field "${field.id}" needs options.` });
                 }
                 if (field.kind === "items" && !field.columns?.length) {
@@ -614,10 +739,10 @@ export function validateWizard(def, files) {
                 // provided by the runner
             }
             else if (head === "item" || head === "index" || head === "count") {
-                if (step.type !== "generate" || !step.each) {
+                if ((step.type !== "generate" && step.type !== "agent") || !step.each) {
                     issues.push({
                         stepId: step.id,
-                        message: `"{{${ref}}}" only exists in a generate step with "each".`,
+                        message: `"{{${ref}}}" only exists in a generate or agent step with "each".`,
                     });
                 }
             }
@@ -634,10 +759,134 @@ export function validateWizard(def, files) {
             }
         }
     };
+    /**
+     * What a condition may read before `step`: an answer asked earlier, an output field of an
+     * earlier agent step ("steps.<step>.<field>", the step itself for a branch), or how many rows
+     * a stored list has ("lists.<list>.count").
+     */
+    const knownBefore = (step, ref, self = false) => {
+        if (seenFields.has(ref)) {
+            return true;
+        }
+        const [head, from, key, ...more] = ref.split(".");
+        if (head === "lists") {
+            return key === "count" && more.length === 0 && listIds.has(from ?? "");
+        }
+        // `steps.<step>.<field>.p`: how probable the decision's answer is.
+        const probability = more.length === 1 && more[0] === "p";
+        if (head !== "steps" || !key || (more.length > 0 && !probability)) {
+            return false;
+        }
+        if (!(seenSteps.has(from) || (self && from === step.id))) {
+            return false;
+        }
+        const source = def.steps.find((s) => s.id === from);
+        return (source?.type === "agent" &&
+            (!probability || isDecisionStep(source)) &&
+            ((source.output.fields ?? []).some((f) => f.id === key) ||
+                (Boolean(source.each) && key === "rows" && !probability)));
+    };
+    const conditionIssues = (stepId, c) => {
+        if ((c.op === "gt" || c.op === "lt") && typeof c.value !== "number") {
+            return [{ stepId, message: `"${c.op}" on "${c.field}" compares with a number value.` }];
+        }
+        if (c.op === "in" && !Array.isArray(c.value)) {
+            return [{ stepId, message: `"in" on "${c.field}" needs a list of values.` }];
+        }
+        if (c.op !== "empty" && c.op !== "notEmpty" && c.value === undefined) {
+            return [{ stepId, message: `"${c.op}" on "${c.field}" needs a value.` }];
+        }
+        return [];
+    };
+    /** Why an `optionsFrom` reference finds nothing, or null when it is fine. */
+    const optionsFromProblem = (raw) => {
+        const [head, from, key, column, ...more] = dataRef(raw).split(".");
+        if (head === "lists" && from && key && !column) {
+            const list = def.lists?.find((l) => l.id === from);
+            if (!list) {
+                return `"optionsFrom" names an unknown list "${from}".`;
+            }
+            if (sharedLists.has(from)) {
+                return notShown(from);
+            }
+            return list.columns.some((c) => c.id === key)
+                ? null
+                : `"optionsFrom": list "${from}" has no column "${key}".`;
+        }
+        if (head === "steps" && from && key && more.length === 0) {
+            const source = seenSteps.has(from) ? def.steps.find((s) => s.id === from) : undefined;
+            // An agent step with `each` hands on one table, `rows`: the entry's columns and its fields.
+            if (source?.type === "agent" && source.each && key === "rows") {
+                return column ? null : `"optionsFrom": "${from}.rows" is a table; name one of its columns.`;
+            }
+            const out = source?.type === "agent"
+                ? (source.output.fields ?? []).find((f) => f.id === key)
+                : undefined;
+            if (!out) {
+                return `"optionsFrom" names "${from}.${key}", which is not an output of an earlier agent step.`;
+            }
+            if (column) {
+                return out.kind === "table" && (!out.columns?.length || out.columns.includes(column))
+                    ? null
+                    : `"optionsFrom": "${from}.${key}" is not a table with the column "${column}".`;
+            }
+            return out.kind === "list" ? null : `"optionsFrom": "${from}.${key}" is not a list.`;
+        }
+        return `"optionsFrom" is "steps.<id>.<key>", "steps.<id>.<key>.<column>" or "lists.<id>.<column>".`;
+    };
     for (const step of def.steps) {
         switch (step.type) {
-            case "page":
+            case "page": {
+                const groups = new Set();
+                for (const g of step.groups ?? []) {
+                    if (groups.has(g.id)) {
+                        issues.push({ stepId: step.id, message: `Duplicate field group "${g.id}".` });
+                    }
+                    groups.add(g.id);
+                    if (!step.fields.some((f) => f.group === g.id)) {
+                        issues.push({ stepId: step.id, message: `Field group "${g.id}" has no fields.` });
+                    }
+                }
+                const decided = step.fields.some((f) => f.ask || f.group);
+                if (decided && step.fields.length > MAX_DECIDED_FIELDS) {
+                    issues.push({
+                        stepId: step.id,
+                        message: `A page whose fields are decided has at most ${MAX_DECIDED_FIELDS} fields.`,
+                    });
+                }
                 for (const field of step.fields) {
+                    if (field.ask && field.group) {
+                        issues.push({
+                            stepId: step.id,
+                            message: `Field "${field.id}" has "ask" or "group", not both.`,
+                        });
+                    }
+                    if (field.group && !groups.has(field.group)) {
+                        issues.push({
+                            stepId: step.id,
+                            message: `Field "${field.id}" names an unknown group "${field.group}".`,
+                        });
+                    }
+                }
+                for (const field of step.fields) {
+                    for (const c of conditionsOf(field.when)) {
+                        const own = step.fields.some((f) => f.id === c.field && f.id !== field.id);
+                        if (!own && !knownBefore(step, c.field)) {
+                            issues.push({
+                                stepId: step.id,
+                                message: `Field "${field.id}": "when" reads "${c.field}", which is neither on this page nor known before it.`,
+                            });
+                        }
+                        issues.push(...conditionIssues(step.id, c));
+                    }
+                    if (field.optionsFrom) {
+                        const problem = field.kind !== "select" && field.kind !== "multiselect"
+                            ? `"optionsFrom" fills the choices of a select or multiselect; kind is "${field.kind}".`
+                            : optionsFromProblem(field.optionsFrom);
+                        if (problem) {
+                            issues.push({ stepId: step.id, message: `Field "${field.id}": ${problem}` });
+                        }
+                    }
                     if (field.prefill) {
                         const ref = dataRef(field.prefill);
                         if (ref.split(".")[0] !== "steps") {
@@ -653,6 +902,7 @@ export function validateWizard(def, files) {
                     seenFields.add(field.id);
                 }
                 break;
+            }
             case "agent":
                 checkTemplate(step, step.instructions);
                 for (const c of step.connections ?? []) {
@@ -660,6 +910,30 @@ export function validateWizard(def, files) {
                         issues.push({ stepId: step.id, message: `Step uses unknown connection "${c}".` });
                     }
                 }
+                if (step.output.surface && step.output.format !== "json") {
+                    issues.push({
+                        stepId: step.id,
+                        message: 'A step composes a view ("surface") of json output only.',
+                    });
+                }
+                if (step.each) {
+                    const ref = dataRef(step.each);
+                    const list = ref.match(/^lists\.([a-zA-Z][a-zA-Z0-9_]*)$/)?.[1];
+                    if (list) {
+                        if (!listIds.has(list)) {
+                            issues.push({ stepId: step.id, message: `each names an unknown list "${list}".` });
+                        }
+                    }
+                    else if (ref.startsWith("steps.") && ref.split(".").length === 3) {
+                        checkTemplate(step, `{{${ref}}}`);
+                    }
+                    else {
+                        issues.push({
+                            stepId: step.id,
+                            message: `each "${step.each}" is "steps.<id>.<key>" (a table or list output) or "lists.<id>".`,
+                        });
+                    }
+                }
                 break;
             case "generate":
                 checkTemplate(step, step.prompt);
@@ -711,6 +985,49 @@ export function validateWizard(def, files) {
                     });
                 }
                 break;
+            case "surface": {
+                for (const [key, ref] of Object.entries(step.data)) {
+                    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+                        issues.push({
+                            stepId: step.id,
+                            message: `Surface data key "${key}" is not an identifier.`,
+                        });
+                    }
+                    const list = listRef(dataRef(ref));
+                    if (list) {
+                        if (!listIds.has(list)) {
+                            issues.push({
+                                stepId: step.id,
+                                message: `Surface data reads an unknown list "${list}".`,
+                            });
+                        }
+                    }
+                    else {
+                        checkTemplate(step, `{{${dataRef(ref)}}}`);
+                    }
+                }
+                const groups = new Set((step.groups ?? []).map((g) => g.id));
+                for (const c of step.candidates ?? []) {
+                    if (c.components[0]?.id !== c.id) {
+                        issues.push({
+                            stepId: step.id,
+                            message: `Surface piece "${c.id}": its first component carries the piece's id.`,
+                        });
+                    }
+                    if (c.group && !groups.has(c.group)) {
+                        issues.push({
+                            stepId: step.id,
+                            message: `Surface piece "${c.id}" names an unknown group "${c.group}".`,
+                        });
+                    }
+                }
+                const components = step.components ??
+                    assembleSurface(step.candidates ?? [], (step.candidates ?? []).map((c) => c.id));
+                for (const issue of validateSurface(components, Object.keys(step.data))) {
+                    issues.push({ stepId: step.id, message: `Surface: ${issue.message}` });
+                }
+                break;
+            }
             case "film":
                 checkTemplate(step, step.brief);
                 for (const [name, ref] of Object.entries(step.inputs)) {
@@ -778,23 +1095,23 @@ export function validateWizard(def, files) {
                 }
                 break;
         }
+        if ((step.next ?? []).filter(isOtherwise).length > 1) {
+            issues.push({
+                stepId: step.id,
+                message: 'A step has at most one "otherwise" branch (one without "when" and "ask").',
+            });
+        }
         for (const rule of step.next ?? []) {
             if (rule.goto !== "end" && !stepIds.has(rule.goto)) {
                 issues.push({ stepId: step.id, message: `Branch goes to unknown step "${rule.goto}".` });
             }
-            // A branch reads what the person answered, or an output field of this or an earlier
-            // agent step as `steps.<step>.<field>`.
-            const [head, from, key, ...more] = rule.when.field.split(".");
-            const source = head === "steps" && key && more.length === 0 && (from === step.id || seenSteps.has(from))
-                ? def.steps.find((s) => s.id === from)
-                : undefined;
-            const known = fieldIds.has(rule.when.field) ||
-                (source?.type === "agent" && (source.output.fields ?? []).some((f) => f.id === key));
-            if (!known) {
-                issues.push({
-                    stepId: step.id,
-                    message: `Branch reads unknown field "${rule.when.field}".`,
-                });
+            // A branch reads what the person answered (on any page), an output field of this or an
+            // earlier agent step, or the row count of a stored list.
+            for (const c of conditionsOf(rule.when)) {
+                if (!fieldIds.has(c.field) && !knownBefore(step, c.field, true)) {
+                    issues.push({ stepId: step.id, message: `Branch reads unknown field "${c.field}".` });
+                }
+                issues.push(...conditionIssues(step.id, c));
             }
         }
         seenSteps.add(step.id);
@@ -817,48 +1134,204 @@ export function parseWizard(input, files) {
  * What branch rules can read in a run: the person's answers by field id, and the structured
  * output of the steps run so far as `steps.<step>.<field>`.
  */
-export function branchValues(values, outputs) {
+export function branchValues(values, outputs, 
+/** Rows per stored list, read as `lists.<list>.count`. */
+listCounts = {}) {
     const out = { ...values };
+    for (const [list, count] of Object.entries(listCounts)) {
+        out[`lists.${list}.count`] = count;
+    }
     for (const [stepId, output] of Object.entries(outputs)) {
         if (output.json && typeof output.json === "object" && !Array.isArray(output.json)) {
             for (const [key, value] of Object.entries(output.json)) {
                 out[`steps.${stepId}.${key}`] = value;
             }
         }
+        for (const [key, p] of Object.entries(output.decided ?? {})) {
+            out[`steps.${stepId}.${key}.p`] = p;
+        }
     }
     return out;
 }
-/** The step after `step`, honouring its branch rules. `null` = the end. */
-export function nextStepId(def, stepId, values) {
+/** A branch back to an earlier step without `max` is taken at most this often in one run. */
+export const DEFAULT_LOOP_MAX = 10;
+/** How a run counts the times it took a branch: "<step>→<goto>". */
+export function loopKey(stepId, goto) {
+    return `${stepId}→${goto}`;
+}
+/** Whether a rule may still send the run on: one with `max`, or one back, stops after so many. */
+export function ruleOpen(def, stepId, rule, loops = {}) {
+    const from = def.steps.findIndex((s) => s.id === stepId);
+    const to = rule.goto === "end" ? def.steps.length : def.steps.findIndex((s) => s.id === rule.goto);
+    const max = rule.max ?? (to >= 0 && to <= from ? DEFAULT_LOOP_MAX : Number.POSITIVE_INFINITY);
+    return (loops[loopKey(stepId, rule.goto)] ?? 0) < max;
+}
+export function followRules(def, stepId, values, loops = {}) {
     const index = def.steps.findIndex((s) => s.id === stepId);
     const step = def.steps[index];
     if (!step) {
-        return null;
+        return { kind: "go", cursor: null, rule: null };
     }
-    for (const rule of step.next ?? []) {
-        if (ruleMatches(rule, values)) {
-            return rule.goto === "end" ? null : rule.goto;
+    const rules = step.next ?? [];
+    for (const [i, rule] of rules.entries()) {
+        if (ruleOpen(def, stepId, rule, loops) && ruleMatches(rule, values)) {
+            return { kind: "go", cursor: rule.goto === "end" ? null : rule.goto, rule: i };
         }
     }
+    const asks = rules.flatMap((rule, i) => rule.ask && ruleOpen(def, stepId, rule, loops) ? [i] : []);
+    if (asks.length) {
+        return { kind: "decide", rules: asks };
+    }
+    return { kind: "go", ...otherwiseOf(def, stepId, loops) };
+}
+/** A rule with neither a condition nor a statement: where the run goes when no other rule holds. */
+export function isOtherwise(rule) {
+    return rule.when === undefined && rule.ask === undefined;
+}
+/**
+ * Where a step goes when none of its rules holds: its "otherwise" rule (`rule` is its index in
+ * `next`), else the next step in the list. `cursor` null = the end.
+ */
+export function otherwiseOf(def, stepId, loops = {}) {
+    const index = def.steps.findIndex((s) => s.id === stepId);
+    const rules = def.steps[index]?.next ?? [];
+    const i = rules.findIndex((r) => isOtherwise(r) && ruleOpen(def, stepId, r, loops));
+    if (i >= 0) {
+        return { cursor: rules[i].goto === "end" ? null : rules[i].goto, rule: i };
+    }
+    return { cursor: def.steps[index + 1]?.id ?? null, rule: null };
+}
+/** The step after `step` by its `when` rules alone. `null` = the end. */
+export function nextStepId(def, stepId, values) {
+    const outcome = followRules(def, stepId, values);
+    if (outcome.kind === "go") {
+        return outcome.cursor;
+    }
+    const index = def.steps.findIndex((s) => s.id === stepId);
     return def.steps[index + 1]?.id ?? null;
 }
 function isEmptyValue(v) {
     return v === undefined || v === null || v === "" || (Array.isArray(v) && v.length === 0);
 }
-export function ruleMatches(rule, values) {
-    const v = values[rule.when.field];
-    switch (rule.when.op) {
+/** The conditions of a rule or a field, as a list: one, several, or none. */
+export function conditionsOf(when) {
+    return when === undefined ? [] : Array.isArray(when) ? when : [when];
+}
+/** A typed number as a number: "89,90" from a German number pad counts as 89.9. */
+function numberOf(v) {
+    if (typeof v === "number") {
+        return Number.isFinite(v) ? v : null;
+    }
+    if (typeof v !== "string" || !v.trim()) {
+        return null;
+    }
+    const n = Number(v.replace(/\s/g, "").replace(",", "."));
+    return Number.isFinite(n) ? n : null;
+}
+export function conditionMatches(c, values) {
+    const v = values[c.field];
+    switch (c.op) {
         case "empty":
             return isEmptyValue(v);
         case "notEmpty":
             return !isEmptyValue(v);
         case "equals":
-            return String(v) === String(rule.when.value);
+            return String(v) === String(c.value);
         case "notEquals":
-            return String(v) !== String(rule.when.value);
+            return String(v) !== String(c.value);
         case "in":
-            return Array.isArray(rule.when.value) && rule.when.value.map(String).includes(String(v));
+            return Array.isArray(c.value) && c.value.map(String).includes(String(v));
+        case "gt":
+        case "lt": {
+            const a = numberOf(v);
+            const b = numberOf(c.value);
+            return a !== null && b !== null && (c.op === "gt" ? a > b : a < b);
+        }
+        case "contains":
+            if (Array.isArray(v)) {
+                return v.map(String).includes(String(c.value));
+            }
+            return (typeof v === "string" &&
+                c.value !== undefined &&
+                v.toLowerCase().includes(String(c.value).toLowerCase()));
+    }
+}
+/** Whether every condition holds; no conditions hold trivially. */
+export function whenHolds(when, values) {
+    return conditionsOf(when).every((c) => conditionMatches(c, values));
+}
+/** Whether a `when` rule holds. An `ask` rule never holds here: a decision takes it (see decide). */
+export function ruleMatches(rule, values) {
+    return rule.when !== undefined && whenHolds(rule.when, values);
+}
+/** A page with decided fields has at most this many; it shows at most MAX_SHOWN_FIELDS of them. */
+export const MAX_DECIDED_FIELDS = 12;
+export const MAX_SHOWN_FIELDS = 5;
+/** Whether a field is shown only when a decision keeps it. */
+export function isDecidedField(field) {
+    return Boolean(field.ask || field.group);
+}
+/**
+ * The fields of a page that are shown: those whose `when` holds on what was known before the
+ * page (`known`) and what the page holds so far (`page`). A hidden field's value does not count
+ * for the fields after it.
+ */
+export function shownFields(fields, known, page) {
+    const values = { ...known, ...page };
+    const out = [];
+    for (const field of fields) {
+        if (whenHolds(field.when, values)) {
+            out.push(field);
+        }
+        else {
+            delete values[field.id];
+        }
+    }
+    return out;
+}
+/** The references the `when` of a page's fields read outside the page: what the page must know. */
+export function pageNeeds(fields) {
+    const own = new Set(fields.map((f) => f.id));
+    return [
+        ...new Set(fields.flatMap((f) => conditionsOf(f.when).map((c) => c.field)).filter((r) => !own.has(r))),
+    ];
+}
+/** At most this many choices come from data. */
+export const MAX_DATA_OPTIONS = 100;
+/**
+ * The choices an `optionsFrom` reference finds in a run: the entries of a list output, one
+ * column of a table output, or one column of a stored list — as text, without duplicates and
+ * empties. Empty when the data is not there (yet).
+ */
+export function optionsFromData(ref, outputs, lists = {}) {
+    const [head, id, key, column, ...more] = dataRef(ref).split(".");
+    let raw = [];
+    if (head === "lists" && id && key && !column) {
+        raw = (lists[id]?.rows ?? []).map((r) => r.cells[key]);
+    }
+    else if (head === "steps" && id && key && more.length === 0) {
+        const json = outputs[id]?.json;
+        const value = json && typeof json === "object" ? json[key] : undefined;
+        if (Array.isArray(value)) {
+            raw = column
+                ? value.map((row) => row && typeof row === "object" ? row[column] : undefined)
+                : value;
+        }
+    }
+    const seen = new Set();
+    for (const v of raw) {
+        if (v === null || v === undefined || typeof v === "object") {
+            continue;
+        }
+        const text = String(v).trim().slice(0, 200);
+        if (text) {
+            seen.add(text);
+        }
+        if (seen.size >= MAX_DATA_OPTIONS) {
+            break;
+        }
     }
+    return [...seen];
 }
 export function itemsTotals(field, value, values) {
     const rows = Array.isArray(value) ? value : [];