wizards 0.5.13 → 0.6.1

package/node_modules/@engenty-wizards/shared/dist/run.d.ts

@@ -23,6 +23,11 @@ export interface StepOutput {
     /** A view from the surface catalog and the data it is bound to. */
     surface?: Surface;
     assets?: AssetRef[];
+    /**
+     * What the person did in the step's view, kept with the run: a checklist's ticks by component
+     * id, a widget's own state (`wizard.save`).
+     */
+    view?: Record<string, unknown>;
     /** Widgets: what loading it with this run's data showed. */
     widget?: {
         /** Seconds of animation the widget registered for video export; null = a still widget. */
@@ -177,6 +182,7 @@ declare const NOTES_EN: {
     };
     readonly videoRendering: "Rendering the video – this usually takes 1–3 minutes.";
     readonly photo: "Looking at photo {n} of {total}";
+    readonly found: "{label}: {name}";
     readonly listen: "Listening to “{label}”…";
     readonly listenFailed: "“{label}” couldn’t be transcribed.";
     readonly filmCutting: "Cutting the film – this takes about a minute.";
@@ -584,6 +590,22 @@ export interface BrandView {
     name: string;
     accent: string | null;
     logoUrl: string | null;
+    /** How the pages look: the run page sets its tokens from it. */
+    theme: RunTheme;
+}
+/** How a wizard's pages look, taken from its space's brand (`runTheme`). Null: the runner's own. */
+export interface RunTheme {
+    /** Buttons and marks. */
+    accent: string | null;
+    /** What is there, done or good to know: ticks, tips, group headings. */
+    second: string | null;
+    /** The ground the pages stand on; its hue tints paper and ink. */
+    background: string | null;
+    /** Typefaces as CSS names them. */
+    display: string | null;
+    body: string | null;
+    /** The brand stands on a dark ground. */
+    dark: boolean;
 }
 export interface PublicWizard {
     token: string;

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

@@ -20,6 +20,8 @@ const NOTES_EN = {
     },
     videoRendering: "Rendering the video – this usually takes 1–3 minutes.",
     photo: "Looking at photo {n} of {total}",
+    // An entry a step has just written, while it writes the rest: "Rezepte: Shakshuka mit Feta".
+    found: "{label}: {name}",
     listen: "Listening to “{label}”…",
     listenFailed: "“{label}” couldn’t be transcribed.",
     filmCutting: "Cutting the film – this takes about a minute.",
@@ -308,6 +310,7 @@ const NOTES_DE = {
     },
     videoRendering: "Das Video wird gerendert – das dauert meist 1–3 Minuten.",
     photo: "Sieht sich Foto {n} von {total} an",
+    found: "{label}: {name}",
     listen: "Hört „{label}“ an …",
     listenFailed: "„{label}“ konnte nicht verschriftlicht werden.",
     filmCutting: "Der Film wird geschnitten – das dauert etwa eine Minute.",

package/node_modules/@engenty-wizards/shared/dist/runner-texts.d.ts

@@ -8,6 +8,26 @@ declare const en: {
     "translation.showTranslated": string;
     "translation.failed": string;
     "share.copied": string;
+    "surface.done": string;
+    "surface.allDone": string;
+    "surface.close": string;
+    "data.view": string;
+    "data.edit": string;
+    "data.json": string;
+    "data.modes": string;
+    "data.add": string;
+    "data.remove": string;
+    "data.missing": string;
+    "data.yes": string;
+    "data.no": string;
+    "data.menu": string;
+    "data.open": string;
+    "data.close": string;
+    "data.save": string;
+    "data.saved": string;
+    "data.schema": string;
+    "data.copy": string;
+    "data.download": string;
     "run.closed": string;
     "slot.later": string;
     "slot.none": string;
@@ -261,6 +281,26 @@ export declare const RUNNER_TEXTS: {
         "translation.showTranslated": string;
         "translation.failed": string;
         "share.copied": string;
+        "surface.done": string;
+        "surface.allDone": string;
+        "surface.close": string;
+        "data.view": string;
+        "data.edit": string;
+        "data.json": string;
+        "data.modes": string;
+        "data.add": string;
+        "data.remove": string;
+        "data.missing": string;
+        "data.yes": string;
+        "data.no": string;
+        "data.menu": string;
+        "data.open": string;
+        "data.close": string;
+        "data.save": string;
+        "data.saved": string;
+        "data.schema": string;
+        "data.copy": string;
+        "data.download": string;
         "run.closed": string;
         "slot.later": string;
         "slot.none": string;
@@ -501,6 +541,6 @@ export declare const RUNNER_TEXTS: {
         "video.you": string;
         "nav.language": string;
     };
-    de: Record<"ai.generated" | "ai.modified" | "ai.publish" | "ask.allow" | "ask.allowRest" | "ask.deny" | "ask.done" | "ask.down" | "ask.hide" | "ask.pictureHint" | "ask.private" | "ask.remember" | "ask.signIn" | "ask.skip" | "ask.typeInto" | "ask.up" | "ask.wants" | "browser.driving" | "browser.handBack" | "browser.takeOver" | "camera.asking" | "camera.clipHint" | "camera.denied" | "camera.done" | "camera.flip" | "camera.hint" | "camera.hintMany" | "camera.native" | "camera.photo" | "camera.pick" | "camera.record" | "camera.recording" | "camera.shoot" | "camera.stop" | "camera.taken" | "camera.title" | "camera.torch" | "camera.video" | "cards.open" | "cards.pick" | "cards.picked" | "chat.above" | "chat.badEmail" | "chat.badNumber" | "chat.badUrl" | "chat.change" | "chat.checked" | "chat.connected" | "chat.dictate" | "chat.dictateStop" | "chat.file" | "chat.files" | "chat.listening" | "chat.micDenied" | "chat.placeholder" | "chat.readAloud" | "chat.readAloudOff" | "chat.required" | "chat.rows" | "chat.send" | "chat.skip" | "chat.skipped" | "chat.transcribing" | "chat.voice" | "check.noFile" | "check.noPreview" | "check.onlyOpen" | "check.progress" | "check.reopen" | "common.cancel" | "common.close" | "common.offline" | "common.retry" | "connect.connected" | "connect.disconnect" | "connect.go" | "connect.none" | "connect.openLink" | "install.add" | "install.app" | "install.bookmark" | "install.bookmark.mac" | "install.bookmark.pc" | "install.ios" | "list.delete" | "list.empty" | "location.accuracy" | "location.denied" | "location.label" | "location.locating" | "location.manual" | "location.map" | "location.refining" | "location.remove" | "location.use" | "location.why" | "nav.language" | "notify.ask" | "notify.blocked" | "notify.done" | "notify.needsYou" | "notify.next" | "notify.on" | "notify.onHint" | "notify.quiet" | "notify.why" | "output.preview" | "package.badJson" | "package.newer" | "package.noManifest" | "package.unreadable" | "result.translate" | "run.accept" | "run.addRow" | "run.again" | "run.awake" | "run.back" | "run.camera" | "run.cancelled" | "run.closed" | "run.cls.account" | "run.cls.audio" | "run.cls.image" | "run.cls.speech" | "run.cls.text" | "run.cls.video" | "run.copy" | "run.edit" | "run.elapsed" | "run.failed" | "run.feedbackPick" | "run.feedbackPlaceholder" | "run.feedbackTarget" | "run.filesMin" | "run.filesOf" | "run.madeWith" | "run.maxFiles" | "run.moveFile" | "run.moveFileHint" | "run.net" | "run.next" | "run.no" | "run.notFound" | "run.openFull" | "run.orAs" | "run.pickItem" | "run.pickedItem" | "run.print" | "run.regenerateAll" | "run.regenerateGo" | "run.regeneratePicked" | "run.removeFile" | "run.resume" | "run.retry" | "run.share" | "run.shareFile" | "run.shareNow" | "run.start" | "run.total" | "run.unavailable" | "run.upload" | "run.uploadMore" | "run.uploadTouch" | "run.uploading" | "run.vat" | "run.working" | "run.yes" | "scan.asking" | "scan.button" | "scan.fromPhoto" | "scan.hint" | "scan.hintQr" | "scan.miss" | "scan.title" | "scan.typeInstead" | "share.copied" | "sign.accept" | "sign.again" | "sign.clear" | "sign.hint" | "sign.open" | "sign.pad" | "sign.remove" | "slot.later" | "slot.none" | "store.confirmDelete" | "store.delete" | "store.empty" | "store.explain" | "store.files" | "store.open" | "store.rows" | "store.signIns" | "store.title" | "talk.camera" | "talk.cameraDenied" | "talk.cameraOff" | "talk.connecting" | "talk.failed" | "talk.hint" | "talk.joinHint" | "talk.listening" | "talk.live" | "talk.speaking" | "talk.start" | "talk.stop" | "translation.failed" | "translation.machine" | "translation.showOriginal" | "translation.showTranslated" | "translation.working" | "video.cameraOff" | "video.ended" | "video.flip" | "video.hint" | "video.join" | "video.leave" | "video.mute" | "video.rejoin" | "video.unmute" | "video.you" | "voice.again" | "voice.denied" | "voice.left" | "voice.noRecorder" | "voice.pick" | "voice.recording" | "voice.remove" | "voice.start" | "voice.stop" | "voice.why", Line>;
+    de: Record<"ai.generated" | "ai.modified" | "ai.publish" | "ask.allow" | "ask.allowRest" | "ask.deny" | "ask.done" | "ask.down" | "ask.hide" | "ask.pictureHint" | "ask.private" | "ask.remember" | "ask.signIn" | "ask.skip" | "ask.typeInto" | "ask.up" | "ask.wants" | "browser.driving" | "browser.handBack" | "browser.takeOver" | "camera.asking" | "camera.clipHint" | "camera.denied" | "camera.done" | "camera.flip" | "camera.hint" | "camera.hintMany" | "camera.native" | "camera.photo" | "camera.pick" | "camera.record" | "camera.recording" | "camera.shoot" | "camera.stop" | "camera.taken" | "camera.title" | "camera.torch" | "camera.video" | "cards.open" | "cards.pick" | "cards.picked" | "chat.above" | "chat.badEmail" | "chat.badNumber" | "chat.badUrl" | "chat.change" | "chat.checked" | "chat.connected" | "chat.dictate" | "chat.dictateStop" | "chat.file" | "chat.files" | "chat.listening" | "chat.micDenied" | "chat.placeholder" | "chat.readAloud" | "chat.readAloudOff" | "chat.required" | "chat.rows" | "chat.send" | "chat.skip" | "chat.skipped" | "chat.transcribing" | "chat.voice" | "check.noFile" | "check.noPreview" | "check.onlyOpen" | "check.progress" | "check.reopen" | "common.cancel" | "common.close" | "common.offline" | "common.retry" | "connect.connected" | "connect.disconnect" | "connect.go" | "connect.none" | "connect.openLink" | "data.add" | "data.close" | "data.copy" | "data.download" | "data.edit" | "data.json" | "data.menu" | "data.missing" | "data.modes" | "data.no" | "data.open" | "data.remove" | "data.save" | "data.saved" | "data.schema" | "data.view" | "data.yes" | "install.add" | "install.app" | "install.bookmark" | "install.bookmark.mac" | "install.bookmark.pc" | "install.ios" | "list.delete" | "list.empty" | "location.accuracy" | "location.denied" | "location.label" | "location.locating" | "location.manual" | "location.map" | "location.refining" | "location.remove" | "location.use" | "location.why" | "nav.language" | "notify.ask" | "notify.blocked" | "notify.done" | "notify.needsYou" | "notify.next" | "notify.on" | "notify.onHint" | "notify.quiet" | "notify.why" | "output.preview" | "package.badJson" | "package.newer" | "package.noManifest" | "package.unreadable" | "result.translate" | "run.accept" | "run.addRow" | "run.again" | "run.awake" | "run.back" | "run.camera" | "run.cancelled" | "run.closed" | "run.cls.account" | "run.cls.audio" | "run.cls.image" | "run.cls.speech" | "run.cls.text" | "run.cls.video" | "run.copy" | "run.edit" | "run.elapsed" | "run.failed" | "run.feedbackPick" | "run.feedbackPlaceholder" | "run.feedbackTarget" | "run.filesMin" | "run.filesOf" | "run.madeWith" | "run.maxFiles" | "run.moveFile" | "run.moveFileHint" | "run.net" | "run.next" | "run.no" | "run.notFound" | "run.openFull" | "run.orAs" | "run.pickItem" | "run.pickedItem" | "run.print" | "run.regenerateAll" | "run.regenerateGo" | "run.regeneratePicked" | "run.removeFile" | "run.resume" | "run.retry" | "run.share" | "run.shareFile" | "run.shareNow" | "run.start" | "run.total" | "run.unavailable" | "run.upload" | "run.uploadMore" | "run.uploadTouch" | "run.uploading" | "run.vat" | "run.working" | "run.yes" | "scan.asking" | "scan.button" | "scan.fromPhoto" | "scan.hint" | "scan.hintQr" | "scan.miss" | "scan.title" | "scan.typeInstead" | "share.copied" | "sign.accept" | "sign.again" | "sign.clear" | "sign.hint" | "sign.open" | "sign.pad" | "sign.remove" | "slot.later" | "slot.none" | "store.confirmDelete" | "store.delete" | "store.empty" | "store.explain" | "store.files" | "store.open" | "store.rows" | "store.signIns" | "store.title" | "surface.allDone" | "surface.close" | "surface.done" | "talk.camera" | "talk.cameraDenied" | "talk.cameraOff" | "talk.connecting" | "talk.failed" | "talk.hint" | "talk.joinHint" | "talk.listening" | "talk.live" | "talk.speaking" | "talk.start" | "talk.stop" | "translation.failed" | "translation.machine" | "translation.showOriginal" | "translation.showTranslated" | "translation.working" | "video.cameraOff" | "video.ended" | "video.flip" | "video.hint" | "video.join" | "video.leave" | "video.mute" | "video.rejoin" | "video.unmute" | "video.you" | "voice.again" | "voice.denied" | "voice.left" | "voice.noRecorder" | "voice.pick" | "voice.recording" | "voice.remove" | "voice.start" | "voice.stop" | "voice.why", Line>;
 };
 export {};

package/node_modules/@engenty-wizards/shared/dist/runner-texts.js

@@ -12,6 +12,26 @@ const de = {
     "translation.showTranslated": "Übersetzung zeigen",
     "translation.failed": "Dieser Wizard lässt sich gerade nicht übersetzen.",
     "share.copied": "Kopiert",
+    "surface.done": "{done} von {total}",
+    "surface.allDone": "Alles erledigt",
+    "surface.close": "Schließen",
+    "data.view": "Ansicht",
+    "data.edit": "Bearbeiten",
+    "data.json": "JSON",
+    "data.modes": "Daten zeigen als",
+    "data.add": "{what} hinzufügen",
+    "data.remove": "Entfernen",
+    "data.missing": "{id} fehlt",
+    "data.yes": "Ja",
+    "data.no": "Nein",
+    "data.menu": "Mehr",
+    "data.open": "Daten ansehen und bearbeiten",
+    "data.close": "Daten schließen",
+    "data.save": "Speichern",
+    "data.saved": "Gespeichert",
+    "data.schema": "JSON Schema",
+    "data.copy": "Kopieren",
+    "data.download": "Herunterladen",
     "run.closed": "Hier gerade nicht verfügbar, dafür fehlt: {list}",
     "slot.later": "Spätere Termine zeigen",
     "slot.none": "Gerade sind keine Termine frei.",
@@ -248,6 +268,26 @@ const en = {
     "translation.showTranslated": "Show translation",
     "translation.failed": "This wizard can’t be translated right now.",
     "share.copied": "Copied",
+    "surface.done": "{done} of {total}",
+    "surface.allDone": "All done",
+    "surface.close": "Close",
+    "data.view": "View",
+    "data.edit": "Edit",
+    "data.json": "JSON",
+    "data.modes": "Show the data as",
+    "data.add": "Add {what}",
+    "data.remove": "Remove",
+    "data.missing": "{id} is missing",
+    "data.yes": "Yes",
+    "data.no": "No",
+    "data.menu": "More",
+    "data.open": "View and edit the data",
+    "data.close": "Close the data",
+    "data.save": "Save",
+    "data.saved": "Saved",
+    "data.schema": "JSON Schema",
+    "data.copy": "Copy",
+    "data.download": "Download",
     "run.closed": "Not available here right now. It needs {list}.",
     "slot.later": "Show later times",
     "slot.none": "No times are free right now.",

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

@@ -68,7 +68,7 @@ export const DEFAULT_RUNNER_SETTINGS = {
 export function outputKindOf(step) {
     switch (step.type) {
         case "agent":
-            return step.output?.fields?.length ? "data" : "text";
+            return step.output?.fields?.length || step.output?.schema ? "data" : "text";
         case "generate":
             return step.asset;
         case "widget":

package/node_modules/@engenty-wizards/shared/dist/shape.d.ts

@@ -0,0 +1,102 @@
+import { z } from "zod";
+/**
+ * What an agent step's json output holds, in the kinds wizards already use: `output.schema`.
+ * Text, numbers, yes/no, a choice, an entry of another list by its id (`ref`), and lists — of
+ * these or of objects (entries) with lists of their own — every one with a label. The runtime builds the model's JSON Schema from
+ * it, the admin shows and edits the data by it, downloads and views read it.
+ *
+ * `output.fields`, the short form, compiles to the same shape (`shapeOfFields`); two kinds exist
+ * only there: `score` (a decision's levels) and `table` (rows of text or numbers, columns named
+ * or picked by the model).
+ */
+/** Objects nest at most this deep, the step's own object counted. */
+export declare const MAX_SHAPE_DEPTH = 4;
+/** At most this many keys in all objects together. */
+export declare const MAX_SHAPE_KEYS = 100;
+interface Named {
+    /** What people read: a column's head, a part's title, "add …". Without one, the key. */
+    label?: string;
+    /** What the model is to put there. */
+    description?: string;
+}
+export type TextShape = Named & {
+    kind: "text";
+    long?: boolean;
+};
+export type NumberShape = Named & {
+    kind: "number";
+    unit?: string;
+};
+export type YesNoShape = Named & {
+    kind: "yesno";
+    yes?: string;
+    no?: string;
+};
+export type ChoiceShape = Named & {
+    kind: "choice";
+    options: string[];
+};
+/** An entry of a top-level list of the same output, by its `id`. */
+export type RefShape = Named & {
+    kind: "ref";
+    to: string;
+};
+export type LeafShape = TextShape | NumberShape | YesNoShape | ChoiceShape | RefShape;
+export type ListShape = Named & {
+    kind: "list";
+    of: LeafShape | ObjectShape;
+};
+export interface ObjectShape extends Named {
+    kind: "object";
+    fields: Record<string, FieldShape>;
+}
+/** `fields` only: a decision's levels, lowest first. */
+export type ScoreShape = Named & {
+    kind: "score";
+    options: string[];
+};
+/** `fields` only: rows of text or numbers; without columns the model picks them. */
+export type TableShape = Named & {
+    kind: "table";
+    columns?: string[];
+};
+export type FieldShape = LeafShape | ListShape | ScoreShape | TableShape;
+/** `output.schema`: what the step returns. */
+export declare const outputShapeSchema: z.ZodType<ObjectShape, unknown, z.core.$ZodTypeInternals<ObjectShape, unknown>>;
+/** An output field as `output.fields` writes it. */
+interface ShortField {
+    id: string;
+    kind: string;
+    description?: string;
+    columns?: string[];
+    options?: string[];
+}
+/** The short form as a shape: a field per key, a list of text, a table as it is. */
+export declare function shapeOfFields(fields: ShortField[]): ObjectShape;
+/** The key of an entry's title: its first short text other than its `id`. */
+export declare function titleKey(shape: ObjectShape): string | undefined;
+/** What people read for a key. */
+export declare function labelOf(key: string, shape: FieldShape | ListShape["of"]): string;
+/** The data a shape describes, as Zod: what a model's answer is checked against. */
+export declare function shapeZod(shape: FieldShape | ListShape["of"], k?: string): z.ZodType;
+/**
+ * The data as JSON Schema (draft 2020-12): every key required, no other keys — what a model's
+ * structured output takes, and what developers read.
+ */
+export declare function shapeJsonSchema(shape: ObjectShape, title?: string): Record<string, unknown>;
+/**
+ * Data a model wrote itself, fitted to the shape before it is checked: a number where text
+ * belongs as text, a number written as text as a number; in a table a cell's list joined and a
+ * missing column empty. Lists stay lists everywhere else.
+ */
+export declare function fitData(shape: FieldShape | ListShape["of"], value: unknown): unknown;
+/** Tables with free columns come back as columns + rows and are stored as records. */
+export declare function recordsOf(shape: FieldShape | ListShape["of"], value: unknown): unknown;
+/** The shape as lines of paths a model binds to: "/recipes[]/title (text): Titel". */
+export declare function shapeLines(shape: ObjectShape, at?: string): string[];
+/**
+ * The shape at a path: keys of objects, an index (digits) into a list. `any` where the data can
+ * hold anything (a table's row), undefined where the shape has nothing.
+ */
+export declare function shapeAt(shape: FieldShape | ListShape["of"], path: string[]): FieldShape | ListShape["of"] | "any" | undefined;
+export {};

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

@@ -0,0 +1,318 @@
+// SPDX-License-Identifier: FSL-1.1-MIT OR MIT
+import { z } from "zod";
+/**
+ * What an agent step's json output holds, in the kinds wizards already use: `output.schema`.
+ * Text, numbers, yes/no, a choice, an entry of another list by its id (`ref`), and lists — of
+ * these or of objects (entries) with lists of their own — every one with a label. The runtime builds the model's JSON Schema from
+ * it, the admin shows and edits the data by it, downloads and views read it.
+ *
+ * `output.fields`, the short form, compiles to the same shape (`shapeOfFields`); two kinds exist
+ * only there: `score` (a decision's levels) and `table` (rows of text or numbers, columns named
+ * or picked by the model).
+ */
+/** Objects nest at most this deep, the step's own object counted. */
+export const MAX_SHAPE_DEPTH = 4;
+/** At most this many keys in all objects together. */
+export const MAX_SHAPE_KEYS = 100;
+const key = z
+    .string()
+    .regex(/^[a-zA-Z][a-zA-Z0-9_]{0,40}$/, "keys are letters, digits and _ and start with a letter");
+const named = {
+    label: z.string().min(1).optional(),
+    description: z.string().optional(),
+};
+const leaves = [
+    z.object({ kind: z.literal("text"), ...named, long: z.boolean().optional() }),
+    z.object({ kind: z.literal("number"), ...named, unit: z.string().optional() }),
+    z.object({
+        kind: z.literal("yesno"),
+        ...named,
+        yes: z.string().optional(),
+        no: z.string().optional(),
+    }),
+    z.object({
+        kind: z.literal("choice"),
+        ...named,
+        options: z.array(z.string().min(1)).min(2).max(40),
+    }),
+    z.object({ kind: z.literal("ref"), ...named, to: key }),
+];
+const LEAF_KINDS = "text, number, yesno, choice, ref";
+/**
+ * The shape of an object `depth` deep, built level by level instead of recursively: JSON Schema
+ * of the definition takes no $ref, and the depth is part of the schema. Objects are the entries
+ * of lists (and the step's own); a field holding one object would only add a level.
+ */
+function objectAt(depth) {
+    const deeper = depth < MAX_SHAPE_DEPTH ? objectAt(depth + 1) : undefined;
+    const of = deeper
+        ? z.discriminatedUnion("kind", [...leaves, deeper], {
+            error: `A list holds ${LEAF_KINDS} or object.`,
+        })
+        : z.discriminatedUnion("kind", [...leaves], {
+            error: `A list this deep holds ${LEAF_KINDS}: objects nest at most ${MAX_SHAPE_DEPTH} deep.`,
+        });
+    const list = z.object({ kind: z.literal("list"), ...named, of });
+    const field = z.discriminatedUnion("kind", [...leaves, list], {
+        error: `"kind" is one of ${LEAF_KINDS}, list.`,
+    });
+    return z.object({
+        kind: z.literal("object"),
+        ...named,
+        fields: z
+            .record(key, field)
+            .refine((f) => Object.keys(f).length > 0, { message: "An object has fields." }),
+    });
+}
+/** Every object of a shape with where it sits, the shape's own first. */
+function objectsOf(shape, at = []) {
+    const out = [{ shape, at }];
+    for (const [k, f] of Object.entries(shape.fields)) {
+        if (f.kind === "list" && f.of.kind === "object") {
+            out.push(...objectsOf(f.of, [...at, "fields", k, "of"]));
+        }
+    }
+    return out;
+}
+/** The list a `ref` points into: a top-level list of objects with an `id`. Null when it is fine. */
+function refProblem(root, to) {
+    const target = root.fields[to];
+    if (target?.kind !== "list" || target.of.kind !== "object") {
+        return `"ref" to "${to}": that is no list of objects at the top of the schema.`;
+    }
+    return target.of.fields.id?.kind === "text"
+        ? null
+        : `"ref" to "${to}": its entries need an "id" text field to be pointed at.`;
+}
+/** `output.schema`: what the step returns. */
+export const outputShapeSchema = objectAt(1).superRefine((shape, ctx) => {
+    const objects = objectsOf(shape);
+    const keys = objects.reduce((n, o) => n + Object.keys(o.shape.fields).length, 0);
+    if (keys > MAX_SHAPE_KEYS) {
+        ctx.addIssue({
+            code: "custom",
+            message: `A schema has at most ${MAX_SHAPE_KEYS} keys in all; this one has ${keys}.`,
+        });
+    }
+    for (const o of objects) {
+        for (const [k, f] of Object.entries(o.shape.fields)) {
+            const ref = f.kind === "ref" ? f : f.kind === "list" && f.of.kind === "ref" ? f.of : null;
+            const problem = ref ? refProblem(shape, ref.to) : null;
+            if (problem) {
+                ctx.addIssue({ code: "custom", message: problem, path: [...o.at, "fields", k] });
+            }
+        }
+    }
+});
+/** The short form as a shape: a field per key, a list of text, a table as it is. */
+export function shapeOfFields(fields) {
+    const one = (f) => {
+        const d = f.description ? { description: f.description } : {};
+        switch (f.kind) {
+            case "number":
+                return { kind: "number", ...d };
+            case "list":
+                return { kind: "list", ...d, of: { kind: "text" } };
+            case "yesno":
+                return { kind: "yesno", ...d };
+            case "choice":
+                return { kind: "choice", ...d, options: f.options ?? [] };
+            case "score":
+                return { kind: "score", ...d, options: f.options ?? [] };
+            case "table":
+                return { kind: "table", ...d, ...(f.columns?.length ? { columns: f.columns } : {}) };
+            default:
+                return { kind: "text", ...d };
+        }
+    };
+    return { kind: "object", fields: Object.fromEntries(fields.map((f) => [f.id, one(f)])) };
+}
+/** The key of an entry's title: its first short text other than its `id`. */
+export function titleKey(shape) {
+    return Object.entries(shape.fields).find(([k, f]) => k !== "id" && f.kind === "text" && !f.long)?.[0];
+}
+/** What people read for a key. */
+export function labelOf(key, shape) {
+    return shape.label ?? key;
+}
+/**
+ * What the model reads about a value beside its title: its description (without label: its key),
+ * its unit, a score's order, where a ref points. Undefined where the title says it all.
+ */
+function about(k, s) {
+    const base = s.description ?? (s.label ? "" : k);
+    const more = s.kind === "number" && s.unit
+        ? `in ${s.unit}`
+        : s.kind === "score"
+            ? "lowest to highest"
+            : s.kind === "ref"
+                ? `the id of an entry of "${s.to}"`
+                : "";
+    return (base && more ? `${base} (${more})` : base || more) || undefined;
+}
+const CELL = z.union([z.string(), z.number(), z.null()]);
+/** The data a shape describes, as Zod: what a model's answer is checked against. */
+export function shapeZod(shape, k = "data") {
+    const description = about(k, shape);
+    const meta = {
+        ...(shape.label ? { title: shape.label } : {}),
+        ...(description ? { description } : {}),
+    };
+    switch (shape.kind) {
+        case "text":
+        case "ref":
+            return z.string().meta(meta);
+        case "number":
+            return z.number().meta(meta);
+        case "yesno":
+            return z.boolean().meta(meta);
+        case "choice":
+        case "score":
+            return z.enum(shape.options).meta(meta);
+        case "list":
+            return z.array(shapeZod(shape.of, k)).meta(meta);
+        case "object":
+            return z
+                .object(Object.fromEntries(Object.entries(shape.fields).map(([n, f]) => [n, shapeZod(f, n)])))
+                .meta(meta);
+        case "table":
+            return (shape.columns?.length
+                ? z.array(z.object(Object.fromEntries(shape.columns.map((c) => [c, CELL]))))
+                : // Free columns come as columns + rows, which a strict schema takes; stored as records.
+                    z.object({ columns: z.array(z.string()), rows: z.array(z.array(CELL)) })).meta(meta);
+    }
+}
+/**
+ * The data as JSON Schema (draft 2020-12): every key required, no other keys — what a model's
+ * structured output takes, and what developers read.
+ */
+export function shapeJsonSchema(shape, title) {
+    const schema = z.toJSONSchema(shapeZod(shape), { target: "draft-2020-12" });
+    return title && !shape.label ? { ...schema, title } : schema;
+}
+/** A table cell as a table takes it: a list joined by spaces, anything else as text. */
+function fitCell(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        return value;
+    }
+    if (Array.isArray(value) && value.every((v) => typeof v === "string" || typeof v === "number")) {
+        return value.join(" ");
+    }
+    return typeof value === "boolean" ? String(value) : JSON.stringify(value);
+}
+const isRecord = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+/**
+ * Data a model wrote itself, fitted to the shape before it is checked: a number where text
+ * belongs as text, a number written as text as a number; in a table a cell's list joined and a
+ * missing column empty. Lists stay lists everywhere else.
+ */
+export function fitData(shape, value) {
+    switch (shape.kind) {
+        case "text":
+        case "ref":
+            return typeof value === "number" ? String(value) : value;
+        case "number":
+            return typeof value === "string" && value.trim() && Number.isFinite(Number(value))
+                ? Number(value)
+                : value;
+        case "list":
+            return Array.isArray(value) ? value.map((v) => fitData(shape.of, v)) : value;
+        case "object":
+            if (!isRecord(value)) {
+                return value;
+            }
+            return {
+                ...value,
+                ...Object.fromEntries(Object.entries(shape.fields)
+                    .filter(([k]) => k in value)
+                    .map(([k, f]) => [k, fitData(f, value[k])])),
+            };
+        case "table": {
+            const columns = shape.columns;
+            return columns?.length && Array.isArray(value)
+                ? value.map((row) => isRecord(row) ? Object.fromEntries(columns.map((c) => [c, fitCell(row[c])])) : row)
+                : value;
+        }
+        default:
+            return value;
+    }
+}
+/** Tables with free columns come back as columns + rows and are stored as records. */
+export function recordsOf(shape, value) {
+    if (shape.kind === "table" && !shape.columns?.length && isRecord(value)) {
+        const t = value;
+        if (t.columns && t.rows) {
+            const columns = t.columns;
+            return t.rows.map((row) => Object.fromEntries(columns.map((c, i) => [c, row[i] ?? null])));
+        }
+    }
+    if (shape.kind === "object" && isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => {
+            const f = shape.fields[k];
+            return [k, f ? recordsOf(f, v) : v];
+        }));
+    }
+    if (shape.kind === "list" && Array.isArray(value)) {
+        return value.map((v) => recordsOf(shape.of, v));
+    }
+    return value;
+}
+/** What a value of a shape is, in a word or two: "list of Rezept", "choice: a | b". */
+function kindLine(s) {
+    switch (s.kind) {
+        case "choice":
+        case "score":
+            return `${s.kind}: ${s.options.join(" | ")}`;
+        case "ref":
+            return `ref → /${s.to}[].id`;
+        case "table":
+            return s.columns?.length ? `table: ${s.columns.join(", ")}` : "table";
+        case "list":
+            return s.of.kind === "object" ? "list of entries" : `list of ${s.of.kind}`;
+        default:
+            return s.kind;
+    }
+}
+/** The shape as lines of paths a model binds to: "/recipes[]/title (text): Titel". */
+export function shapeLines(shape, at = "") {
+    const out = [];
+    for (const [k, f] of Object.entries(shape.fields)) {
+        const path = `${at}/${k}`;
+        const words = [f.label, f.description].filter(Boolean).join(" — ");
+        out.push(`- ${path} (${kindLine(f)})${words ? `: ${words}` : ""}`);
+        if (f.kind === "list" && f.of.kind === "object") {
+            out.push(...shapeLines(f.of, `${path}[]`));
+        }
+    }
+    return out;
+}
+/**
+ * The shape at a path: keys of objects, an index (digits) into a list. `any` where the data can
+ * hold anything (a table's row), undefined where the shape has nothing.
+ */
+export function shapeAt(shape, path) {
+    let at = shape;
+    for (const part of path) {
+        if (at.kind === "object") {
+            const next = at.fields[part];
+            if (!next) {
+                return undefined;
+            }
+            at = next;
+        }
+        else if (at.kind === "list" && /^\d+$/.test(part)) {
+            at = at.of;
+        }
+        else if (at.kind === "table") {
+            // A row, and in it whatever columns the model wrote.
+            return /^\d+$/.test(part) ? "any" : undefined;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return at;
+}