wizards 0.5.13 → 0.6.0

package/apps/runtime/dist/authoring/guide.js

@@ -136,8 +136,9 @@ type AgentStep = {
   tools: ("web_search"|"web_fetch"|"browser"|"sandbox"|"image"|"http"|"pages")[]
   mcp?: string[]                // ids of the project's MCP servers this step may use
   connections?: string[]        // ids of wizard connections this step may read (mail → mail_search, mail_read, mail_save)
-  output: { format: "text"|"markdown"|"json", fields?: { id, kind: "text"|"number"|"list"|"table"|"yesno"|"choice"|"score", description, columns?: string[], options?: string[] }[], surface?: boolean }
+  output: { format: "text"|"markdown"|"json", fields?: { id, kind: "text"|"number"|"list"|"table"|"yesno"|"choice"|"score", description, columns?: string[], options?: string[] }[], schema?: Schema, surface?: SurfaceComponent[] | true }
                                 // "score" answers its description on the scale in options, lowest first ("low", "medium", "high")
+                                // fields: one level of keys (the short form). schema: nested data, below. One of the two, not both.
   each?: "steps.<id>.<key>" | "lists.<id>"
                                 // ONE RUN PER ENTRY (at most 20): the rows of a table output, the entries of a list output, or the
                                 //   rows of a stored list; the instructions read {{item.<column>}}, {{index}}, {{count}}. The output is
@@ -172,9 +173,45 @@ type SurfaceStep = {
   candidates?: { id, description, components: SurfaceComponent[] (the first has the piece's id), group?, required? }[]
   groups?: { id, instructions, optional? }[]
 }
+// SCHEMA (json only): nested data — lists of entries that hold lists of their own (days with meals, recipes with
+//   ingredients and steps). Its root is { kind: "object", label, fields: { <key>: Field } }; a Field is
+//     { kind: "text", label, description?, long?: true }           long: paragraphs, not a line
+//     { kind: "number", label, description?, unit?: "Min" }
+//     { kind: "yesno", label, description?, yes?: "da", no?: "einkaufen" }   (yes/no: the words people read)
+//     { kind: "choice", label, description?, options: string[] }
+//     { kind: "ref", label, description?, to: "<top-level list key>" }   the id of an entry of that list; its entries
+//                                                                          need { id: { kind: "text" } }
+//     { kind: "list", label, description?, of: Field-without-list | { kind: "object", label, fields: { … } } }
+//   Labels are in the wizard's language: column heads, part titles, "add <label>" in the admin's editor. Description:
+//   what the model is to put there. Objects nest at most 4 deep (the root counted), at most 100 keys in all.
+//   The model gets it as a strict JSON Schema: every key is always filled.
+//   DESIGN THE VIEW FIRST, then the schema it needs: write output.surface (Tabs, Card, Fold, Group, Chips, Checklist,
+//   Steps, Link, Callout …) for what the person should see, then give the schema exactly the lists and keys that
+//   view binds — nothing it does not show or a later step does not read. One step returns the whole tree.
+//   Paths: {"path": "/recipes"} from the data; inside a repeated entry "title" or "meals" reads the entry; a Link's
+//   view reads the entry it opens. The view is checked against the schema.
+//   Later steps read top-level keys ({{steps.id.key}}, optionsFrom, each, conditions); a list of entries is a table
+//   there ("steps.id.recipes.title"). Downloads: xlsx one sheet per top-level list, csv the first list of flat
+//   entries, md and pdf the whole tree.
+//   Example (Kühlschrank-Koch): { kind: "object", label: "Menüplan", fields: {
+//     summary: { kind: "text", label: "Zusammenfassung", long: true },
+//     days: { kind: "list", label: "Tage", of: { kind: "object", label: "Tag", fields: {
+//       label: { kind: "text", label: "Tag" }, theme: { kind: "text", label: "Motto" },
+//       meals: { kind: "list", label: "Mahlzeiten", of: { kind: "object", label: "Mahlzeit", fields: {
+//         slot: { kind: "choice", label: "Mahlzeit", options: ["Frühstück", "Mittag", "Abend"] },
+//         recipe_id: { kind: "ref", label: "Rezept", to: "recipes" } } } } } } },
+//     recipes: { kind: "list", label: "Rezepte", of: { kind: "object", label: "Rezept", fields: {
+//       id: { kind: "text", label: "Kennung" }, title: { kind: "text", label: "Titel" },
+//       time_minutes: { kind: "number", label: "Zeit", unit: "Min" },
+//       steps: { kind: "list", label: "Zubereitung", of: { kind: "object", label: "Schritt", fields: {
+//         text: { kind: "text", label: "Schritt", long: true }, minutes: { kind: "number", label: "Dauer", unit: "Min" } } } } } } } } }
+//   with a view: Tabs over a Grid of day Cards (each meal a Link to its recipe) and a Grid of recipe Links whose
+//   view is a Card, a Fold of ingredients and the Steps.
 // A SURFACE is a native view in the runner — facts, a list of results, key figures, a chart — themed, on phones, free per run.
 //   Prefer it to a widget for such views; a widget is for what the catalog cannot show (a map, an animation).
-//   An agent step with output.format "json" can also set output.surface: true: it composes such a view of its own result.
+//   An agent step with output.format "json" can also carry such a view of its own result: output.surface: [components],
+//   written once and bound to its fields or schema by path ({"path": "/<key>"}; a step with "each": "/rows"). Prefer it to
+//   output.surface: true, which has a model compose a new view on every run.
 //   Reviews and the result show a step's view instead of its plain table.
 type GenerateStep = {
   type: "generate"
@@ -200,7 +237,10 @@ type WidgetStep = {
   entry: string                 // workspace path of the widget's HTML, e.g. "weather/index.html"
   data: { [key]: string }       // what the widget gets as wizard.data: key → fieldId | steps.stepId | steps.stepId.key | brand.name | facts.key | today
   sample?: string               // workspace path of example data (same shape as data) for previews
-  size?: { width, height }      // design size in px, default 1280×720 (9:16 → 1080×1920)
+  layout?: "fixed"|"page"       // fixed (default): drawn at size and scaled to the page — maps, charts, films.
+                                //   page: part of the run page, as wide as it and as tall as its content, never scaled —
+                                //   a result people scroll and use (a cook mode, a configurator, a planner)
+  size?: { width, height }      // design size in px, default 1280×720 (9:16 → 1080×1920); exports render at it
   video?: boolean               // a FILM: the timeline is rendered to an MP4 WITH SOUND when the step runs; the person sees and
                                 //   downloads that video. data may then name generate steps: "steps.<id>" of an image / video / voice
                                 //   step arrives as a URL (a list of URLs for a step with "each").
@@ -238,6 +278,7 @@ type ResultStep = { type: "result", message?: string, deliverables: { from: step
 //                     film widget (video: true)→mp4 png · film→mp4
 //                     widget→html png pdf mp4 json (mp4 only when the widget registers a timeline)
 //                     agent text/markdown→md txt docx pdf html · agent json→json csv xlsx md (xlsx: one sheet per table)
+//                     agent json with schema→json csv xlsx md pdf
 //                     agent, any format→zip: the FILES the step kept with mail_save / browser_download
 //                     lists.<id>→xlsx csv json md · zip (a list with check.file: the kept files its rows name, plus the list)
 
@@ -252,9 +293,18 @@ A template may only use fields asked and steps run EARLIER.`;
 export const PRINCIPLES = `
 How good wizards look:
 - For non-technical end users. Plain words, friendly titles phrased as questions ("What is the post for?").
+- The wizard speaks for itself: the first page invites in its own voice ("Show me your fridge."), every field's help says in
+  one line why it is asked ("For the amounts in the recipes"), every step that takes a while has a "working" line that
+  names what happens ("Looking into your fridge…"). Choices with up to five options are buttons, not a dropdown.
+- The result is what people come for: design how it looks first, then the data it needs. A json step's result gets a view
+  (output.surface, written once) or a widget; give its data the fields only the view uses — a yes/no that picks a colour
+  ("in_fridge"), a key that groups ("category"), one human line (a summary, a tip, a theme per day) — and links instead of
+  copies (a meal names its recipe's id). Things are cards, ordered work is Steps, things to get or do are a Checklist;
+  never a table of things for a person — a table only for figures compared across columns (prices, dates).
 - A page whose fields depend on an earlier answer uses "when" on its fields, never one copy of the page per answer and a branch to each copy. Choices that depend on what an earlier step found use "optionsFrom", never one page per possible result.
 - Few pages, 1–5 fields each, one theme per page. Only ask what the result really needs; prefer selects with sensible defaults.
-- Put a review step before anything expensive (video) and before the final result, so people can correct or regenerate.
+- Put a review step before anything expensive (video) and before anything written elsewhere (mail, CRM), so people can
+  correct or regenerate. A result people can simply make again needs no review before it.
 - Money/totals: use an "items" field with vat — the runner computes totals; documents must use {{items}} verbatim. Never let a model compute totals.
 - Facts from the web need an agent step with web_search + web_fetch BEFORE writing; documents then cite those notes.
 - Live data with a free public JSON API (weather and wind: api.open-meteo.com; sunrise/sunset is in it too) → an agent step with the http tool and model "standard" that calls the API and returns json. Far cheaper and more exact than web research; use web research only when no API exists.
@@ -295,8 +345,12 @@ one-off pages stay "generate" steps. A widget is code in the wizard's WORKSPACE
   <script src="lib/name.min.js">. Fetch reference data ONCE now (e.g. lake outlines
   from nominatim.openstreetmap.org/search?q=…&format=json&polygon_geojson=1&polygon_threshold=0.0005)
   and save it as a workspace file.
-- Runtime, window.wizard: data · brand {name, accent, logo, colors [{name, value}], facts {key: value}} · ai "generated"|"edited"|null · mode "view"|"export" · file(path) ·
-  json(path) · url(path) (data URL for images/fonts) · ready() · timeline({ duration, seek, poster }).
+- Runtime, window.wizard: data · brand {name, accent, logo, colors [{name, value}], facts {key: value}, theme} · ai "generated"|"edited"|null · mode "view"|"export" · file(path) ·
+  json(path) · url(path) (data URL for images/fonts) · ready() · timeline({ duration, seek, poster }) ·
+  state (what the person did last time, kept with the run) · save(state) (keep ticks, an open tab, a step reached: small JSON) ·
+  share(text) (the device's share sheet).
+- layout "page": let the document grow with its content (no height: 100vh, no fixed body height) and lay out for phones
+  first; the page sets the frame's height from it. Keep what the person does with wizard.save and start from wizard.state.
 - Animation: call wizard.timeline({ duration: seconds, seek: t => draw(t) }) and drive your own
   play/pause and <input type=range> scrubber from it. seek(t) must draw time t synchronously — the MP4
   export steps through it frame by frame. In mode "export" hide all controls and do not autoplay.
@@ -308,7 +362,9 @@ one-off pages stay "generate" steps. A widget is code in the wizard's WORKSPACE
   arrive as URLs, not inlined.
 - Call wizard.ready() once the first frame is drawn. Lay out for the step's size and scale to fit
   the window on every "resize" event — the window can be 0×0 when your script first runs.
-- Plain HTML/CSS/JS, SVG or canvas. Calm design, one accent colour (brand.accent), legible labels.
+- Plain HTML/CSS/JS, SVG or canvas. Take the look from wizard.brand.theme: accent for actions, second for meaning (done,
+  there, a tip), background for the ground, display for headings, body for text (system fonts behind them); dark: a dark
+  ground. Cards for things, generous spacing, legible labels; no table of things.
 - After writing, ALWAYS run check_widget, read its errors and look at the screenshot; fix until clean.`;
 export function connectorsLine(connectors) {
     const lines = connectors.map((c) => {

package/apps/runtime/dist/credits/estimate.js

@@ -61,7 +61,7 @@ function stepFormula(step, catalog) {
         if (step.output.format === "json") {
             credits += textCredits(cls("classifier"), TOKENS.structure);
         }
-        if (step.output.surface) {
+        if (step.output.surface === true) {
             credits += textCredits(cls("standard"), TOKENS.structure);
         }
         return credits;

package/apps/runtime/dist/engine/requirements.js

@@ -36,7 +36,7 @@ function ownClasses(step) {
             if (step.output.format === "json") {
                 classes.push("classifier");
             }
-            if (step.output.surface && !classes.includes("standard")) {
+            if (step.output.surface === true && !classes.includes("standard")) {
                 classes.push("standard");
             }
             return classes;

package/apps/runtime/dist/engine/runner.js

@@ -2,6 +2,7 @@ import { marginOf, } from "@engenty-wizards/shared/decision";
 import { branchValues, cardsFromData, conditionsOf, dataRef, followRules, formatsFor, isDecidedField, LIST_FORMATS, listRef, loopKey, MAX_SHOWN_FIELDS, optionsFromData, otherwiseOf, pageNeeds, whenHolds, wizardLang, } from "@engenty-wizards/shared/definition";
 import { note, saidText, } from "@engenty-wizards/shared/run";
 import { CONVERSATION_RUNNERS, DEFAULT_RUNNER_SETTINGS } from "@engenty-wizards/shared/runners";
+import { fitData } from "@engenty-wizards/shared/shape";
 import { machineTranslated, translateDefinition } from "@engenty-wizards/shared/translation";
 import { eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
@@ -30,7 +31,7 @@ import { readPageInput } from "./input.js";
 import { pushRun } from "./push.js";
 import { blockingMessage, closedChoices, missingModelsSaid, openValue, stepsWithoutModel, } from "./requirements.js";
 import { releaseResources, resourcesFor } from "./resources.js";
-import { runAutomaticStep } from "./steps.js";
+import { outputSchema, runAutomaticStep } from "./steps.js";
 import { answersAsText, resolveRef } from "./template.js";
 import { StepError } from "./types.js";
 /** A command the run cannot take in its current state; a note where the person may read it. */
@@ -695,6 +696,47 @@ export async function submitPage(runId, stepId, input) {
     await updateRun(runId, { state, cursor, status: "running", error: null });
     kick(runId);
 }
+/** Edited data of a json step is kept up to this size. */
+const MAX_EDITED_JSON = 500_000;
+/**
+ * A json step's output with data someone edited: checked against the step's schema, and what
+ * its view shows too. Refused when it does not fit.
+ */
+export function editedJson(def, stepId, output, data) {
+    const step = stepOf(def, stepId);
+    if (step?.type !== "agent" || step.output.format !== "json" || step.each || step.call) {
+        throw new RunConflict("Not a json step");
+    }
+    if (JSON.stringify(data).length > MAX_EDITED_JSON) {
+        throw new RunConflict("Too large");
+    }
+    const { schema, shape } = outputSchema(step);
+    const parsed = schema.safeParse(fitData(shape, data));
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw new RunConflict(`Does not fit the schema: ${issue?.path.join(".")} ${issue?.message}`);
+    }
+    const json = parsed.data;
+    return {
+        ...output,
+        json,
+        ...(output.surface ? { surface: { ...output.surface, data: json } } : {}),
+    };
+}
+/** Data of a finished or waiting run's json step, edited in the studio. */
+export async function editOutput(runId, stepId, data) {
+    const run = await loadRun(runId);
+    const output = run?.state.outputs[stepId];
+    if (!run || !output) {
+        throw new RunConflict("Unknown step");
+    }
+    if (run.status !== "waiting_input" && run.status !== "done") {
+        throw new RunConflict({ code: "runBusy" });
+    }
+    const state = structuredClone(run.state);
+    state.outputs[stepId] = editedJson(run.definition, stepId, output, data);
+    await updateRun(runId, { state });
+}
 export async function reviewStep(runId, stepId, action) {
     const run = await requireWaiting(runId, stepId);
     const step = stepOf(run.definition, stepId);
@@ -703,9 +745,16 @@ export async function reviewStep(runId, stepId, action) {
     }
     const state = structuredClone(run.state);
     if (action.type === "accept") {
-        for (const [target, text] of Object.entries(action.edits ?? {})) {
-            if (step.edit && step.show.includes(target) && state.outputs[target]) {
-                state.outputs[target] = { ...state.outputs[target], text: String(text).slice(0, 50_000) };
+        for (const [target, edit] of Object.entries(action.edits ?? {})) {
+            const output = state.outputs[target];
+            if (!step.edit || !step.show.includes(target) || !output) {
+                continue;
+            }
+            if (typeof edit === "string") {
+                state.outputs[target] = { ...output, text: edit.slice(0, 50_000) };
+            }
+            else {
+                state.outputs[target] = editedJson(run.definition, target, output, edit);
             }
         }
         state.history.push(stepId);

package/apps/runtime/dist/engine/steps.js

@@ -1,11 +1,11 @@
 import { pOf } from "@engenty-wizards/shared/decision";
-import { allFields, dataRef, isDecisionStep, LOCALES, langNameEn, templateRefs, wizardLang, } from "@engenty-wizards/shared/definition";
-import { mainLogo, ruleLines } from "@engenty-wizards/shared/projects";
+import { allFields, dataRef, isDecisionStep, LOCALES, langNameEn, stepShape, templateRefs, wizardLang, } from "@engenty-wizards/shared/definition";
+import { mainLogo, ruleLines, runTheme } from "@engenty-wizards/shared/projects";
 import { note as runNote } from "@engenty-wizards/shared/run";
+import { fitData, labelOf, recordsOf, shapeJsonSchema, shapeLines, shapeZod, titleKey, } from "@engenty-wizards/shared/shape";
 import { SURFACE_GUIDE, validateSurface, } from "@engenty-wizards/shared/surface";
 import { Agent } from "@mastra/core/agent";
-import { generateText, Output } from "ai";
-import { z } from "zod";
+import { generateText, jsonSchema, Output, parsePartialJson } from "ai";
 import { extFor, loadAsset, loadAssetText } from "../files/storage.js";
 import { snapshotHtmlImages } from "../files/web-images.js";
 import { runFilmStep } from "../film/step.js";
@@ -109,80 +109,21 @@ const BROWSER_RULES = [
     "The person can take the browser over while you work; your next browser action then waits and gets the page as they left it.",
 ].join("\n");
 // --- agent -------------------------------------------------------------------
+/**
+ * What the step returns: its schema, its fields as one, or else one table. The model's
+ * structured output takes it as JSON Schema; its own JSON is checked against it.
+ */
 export function outputSchema(step) {
-    const fields = step.output.fields?.length
-        ? step.output.fields
-        : [{ id: "data", kind: "table", description: "The result as a table" }];
-    const shape = {};
-    for (const f of fields) {
-        const d = f.description ?? f.id;
-        switch (f.kind) {
-            case "text":
-                shape[f.id] = z.string().describe(d);
-                break;
-            case "number":
-                shape[f.id] = z.number().describe(d);
-                break;
-            case "list":
-                shape[f.id] = z.array(z.string()).describe(d);
-                break;
-            case "yesno":
-                shape[f.id] = z.boolean().describe(d);
-                break;
-            case "choice":
-                shape[f.id] = z.enum(f.options).describe(d);
-                break;
-            case "score":
-                shape[f.id] = z
-                    .enum(f.options)
-                    .describe(`${d} (lowest to highest)`);
-                break;
-            case "table":
-                shape[f.id] = f.columns?.length
-                    ? z
-                        .array(z.object(Object.fromEntries(f.columns.map((c) => [c, z.union([z.string(), z.number(), z.null()])]))))
-                        .describe(d)
-                    : z
-                        .object({
-                        columns: z.array(z.string()),
-                        rows: z.array(z.array(z.union([z.string(), z.number(), z.null()]))),
-                    })
-                        .describe(d);
-                break;
-        }
-    }
-    return { schema: z.object(shape), fields };
-}
-/** Tables come back as columns + rows (strict-schema friendly) and are stored as records. */
-function tablesToRecords(value, fields) {
-    const out = { ...value };
-    for (const f of fields) {
-        const t = value[f.id];
-        if (f.kind === "table" && t?.columns && t.rows) {
-            out[f.id] = t.rows.map((row) => Object.fromEntries(t.columns.map((c, i) => [c, row[i] ?? null])));
-        }
-    }
-    return out;
-}
-/** A table cell as the step's schema 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 shape = stepShape(step);
+    return { schema: shapeZod(shape), shape };
 }
 /**
  * What the agent wrote as JSON itself — its last fenced block, else its answer or the object in
- * it — fitted to the step's fields (a list in a table cell joined, a missing column empty) and
- * checked against the schema. Null where none fits; then a model structures the text.
+ * it — fitted to the step's shape (a number where text belongs as text; in a short-form table a
+ * list in a cell joined, a missing column empty) and checked against the schema. Null where none
+ * fits; then a model structures the text.
  */
-export function ownJson(text, schema, fields) {
+export function ownJson(text, schema, shape) {
     const blocks = [...text.matchAll(/```(?:json)?[ \t]*\n([\s\S]*?)```/g)].map((m) => m[1]);
     const open = text.indexOf("{");
     const close = text.lastIndexOf("}");
@@ -202,30 +143,88 @@ export function ownJson(text, schema, fields) {
         if (!value || typeof value !== "object" || Array.isArray(value)) {
             continue;
         }
-        const fitted = { ...value };
-        for (const f of fields) {
-            const v = fitted[f.id];
-            if (f.kind === "table" && f.columns?.length && Array.isArray(v)) {
-                fitted[f.id] = v.map((row) => row && typeof row === "object" && !Array.isArray(row)
-                    ? Object.fromEntries(f.columns.map((c) => [c, fitCell(row[c])]))
-                    : row);
+        const parsed = schema.safeParse(fitData(shape, value));
+        if (parsed.success) {
+            return parsed.data;
+        }
+    }
+    return null;
+}
+/** At most this many entries a step reports while it writes; the rest come with the result. */
+const MAX_FOUND = 40;
+/**
+ * Runs a json step's agent as a stream and reports each entry of a top-level list once it is
+ * complete in the JSON the agent is writing: "Rezepte: Shakshuka mit Feta". Returns what
+ * `generate` would: the text, the steps and the usage.
+ */
+async function streamWithProgress(agent, message, options, step, ctx) {
+    const shape = outputSchema(step).shape;
+    const reported = new Map();
+    let told = 0;
+    let written = "";
+    let checked = 0;
+    const report = async () => {
+        const start = written.lastIndexOf("```json");
+        if (start < 0 || told >= MAX_FOUND) {
+            return;
+        }
+        const body = written.slice(start + 7).replace(/```\s*$/, "");
+        const { value } = await parsePartialJson(body);
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return;
+        }
+        const keys = Object.keys(shape.fields);
+        for (const [index, [key, field]] of Object.entries(shape.fields).entries()) {
+            const list = value[key];
+            if (field.kind !== "list" || !Array.isArray(list)) {
+                continue;
             }
-            else if (f.kind === "text" && typeof v === "number") {
-                fitted[f.id] = String(v);
+            // The last entry may still be half written – until a later part has begun.
+            const later = keys.slice(index + 1).some((k) => k in value);
+            const done = later ? list.length : list.length - 1;
+            for (let i = reported.get(key) ?? 0; i < done && told < MAX_FOUND; i++) {
+                const entry = list[i];
+                const name = field.of.kind === "object"
+                    ? String(entry?.[titleKey(field.of) ?? ""] ?? "")
+                    : String(entry ?? "");
+                if (name.trim()) {
+                    told += 1;
+                    await ctx.emit("info", {
+                        code: "found",
+                        params: { label: labelOf(key, field), name: name.trim().slice(0, 80) },
+                    });
+                }
+                reported.set(key, i + 1);
             }
-            else if (f.kind === "number" &&
-                typeof v === "string" &&
-                v.trim() &&
-                Number.isFinite(Number(v))) {
-                fitted[f.id] = Number(v);
+        }
+    };
+    const stream = await agent.stream(message, options);
+    // A model that answers in one piece (a local client) has nothing to report while it writes:
+    // its entries come with the result.
+    let whole = false;
+    for await (const chunk of stream.fullStream) {
+        const payload = chunk.payload ?? chunk;
+        if (chunk.type === "text-delta") {
+            const delta = payload.text ?? payload.delta ?? "";
+            whole ||= delta.length > 2_000;
+            written += delta;
+            // Parsing the growing answer every few hundred characters is enough to keep up.
+            if (!whole && written.length - checked > 300) {
+                checked = written.length;
+                await report();
             }
         }
-        const parsed = schema.safeParse(fitted);
-        if (parsed.success) {
-            return parsed.data;
+        else if (chunk.type === "error") {
+            throw payload.error ?? new Error("step stream error");
         }
     }
-    return null;
+    const s = stream;
+    return {
+        text: (await s.text) ?? written,
+        steps: await s.steps,
+        usage: await s.usage,
+        totalUsage: await s.totalUsage,
+    };
 }
 /** An agent step looks at this many photos itself; more are read one by one with read_document. */
 const MAX_SEEN = 8;
@@ -331,10 +330,8 @@ function jsonArrayIn(text) {
  * for its view.
  */
 async function composeSurface(step, json, ctx) {
-    const keys = Object.keys(json);
-    const fields = (step.output.fields ?? [])
-        .map((f) => `- /${f.id} (${f.kind}${f.columns ? `: ${f.columns.join(", ")}` : ""}): ${f.description ?? ""}`)
-        .join("\n");
+    const shape = outputSchema(step).shape;
+    const fields = shapeLines(shape).join("\n");
     const sample = JSON.stringify(json).slice(0, 4000);
     try {
         const writer = await textModel("standard", ctx.call);
@@ -356,7 +353,7 @@ async function composeSurface(step, json, ctx) {
             });
             await ctx.chargeUsd(costOf(writer, result.usage));
             const components = jsonArrayIn(result.text);
-            issues = validateSurface(components, keys).map((i) => i.message);
+            issues = validateSurface(components, shape).map((i) => i.message);
             if (!issues.length) {
                 return { components: components, data: json };
             }
@@ -413,21 +410,24 @@ async function runAgentEach(step, ctx) {
         assets.push(...(out.assets ?? []));
     }
     const json = { rows };
-    const surface = step.output.surface
-        ? await composeSurface({
-            ...step,
-            output: {
-                ...step.output,
-                fields: [
-                    {
-                        id: "rows",
-                        kind: "table",
-                        description: "One row per entry: its columns and the step's fields",
-                    },
-                ],
-            },
-        }, json, ctx)
-        : undefined;
+    const surface = Array.isArray(step.output.surface)
+        ? { components: step.output.surface, data: json }
+        : step.output.surface
+            ? await composeSurface({
+                ...step,
+                output: {
+                    ...step.output,
+                    schema: undefined,
+                    fields: [
+                        {
+                            id: "rows",
+                            kind: "table",
+                            description: "One row per entry: its columns and the step's fields",
+                        },
+                    ],
+                },
+            }, json, ctx)
+            : undefined;
     return {
         text: texts.join("\n\n"),
         json,
@@ -493,7 +493,11 @@ export async function runAgentStep(step, ctx) {
             ? "Answer with the finished result in clean Markdown — no preamble, no closing remarks."
             : step.output.format === "text"
                 ? "Answer with the finished result as plain text — no Markdown, no preamble."
-                : "Finish with everything the result needs in your final answer; it is turned into structured data afterwards.";
+                : [
+                    "Finish with everything the result needs in your final answer, ending with one ```json block in exactly this shape (keys as named, lists as lists):",
+                    shapeLines(outputSchema(step).shape).join("\n"),
+                    'Write the parts in this order, each entry complete before the next. Its values are read on a phone: short names without hedges (doubt goes into its own field, "ca. 1 Becher"), only the values a field allows, no filler entries ("if needed").',
+                ].join("\n");
         const system = [
             groundRules(ctx),
             step.tools.includes("browser") ? BROWSER_RULES : "",
@@ -556,7 +560,10 @@ export async function runAgentStep(step, ctx) {
                 },
             ]
             : prompt;
-        const result = await agent.generate(message, { maxSteps, abortSignal: ctx.signal });
+        // A json step streams, so the person sees its entries as they are written (`found`).
+        const result = step.output.format === "json"
+            ? await streamWithProgress(agent, message, { maxSteps, abortSignal: ctx.signal }, step, ctx)
+            : await agent.generate(message, { maxSteps, abortSignal: ctx.signal });
         await ctx.chargeUsd(costOf(resolved, result.totalUsage ?? result.usage));
         // `result.text` strings together what the model said between tool calls ("I open the page …").
         // A written result is its last message; structuring keeps everything, numbers may sit anywhere.
@@ -569,23 +576,38 @@ export async function runAgentStep(step, ctx) {
             }
             return { text, assets: assets.length ? assets : undefined, at: new Date().toISOString() };
         }
-        const { schema, fields } = outputSchema(step);
+        const { schema, shape } = outputSchema(step);
         // The agent mostly writes the JSON itself; a second model only structures what does not fit.
         // Having it copy kilobytes of JSON again is slow and can fail on its own.
-        let output = ownJson(text, schema, fields);
+        let output = ownJson(text, schema, shape);
         if (!output) {
             const structurer = await textModel("classifier", ctx.call);
             const structured = await generateText({
                 model: structurer.model,
                 abortSignal: ctx.signal,
-                output: Output.object({ schema }),
+                // The JSON Schema built from the shape, strict: every key required, no other keys.
+                output: Output.object({
+                    schema: jsonSchema(shapeJsonSchema(shape), {
+                        validate: (value) => {
+                            const parsed = schema.safeParse(value);
+                            return parsed.success
+                                ? { success: true, value: parsed.data }
+                                : { success: false, error: parsed.error };
+                        },
+                    }),
+                }),
                 prompt: `Turn this result into the requested structure. Keep every number and source exactly.\n\n${text}`,
             });
             await ctx.chargeUsd(costOf(structurer, structured.usage));
             output = structured.output;
         }
-        const json = tablesToRecords(output, fields);
-        const surface = step.output.surface ? await composeSurface(step, json, ctx) : undefined;
+        const json = recordsOf(shape, output);
+        // A view written once is bound to this run's data; `true` asks a model for one.
+        const surface = Array.isArray(step.output.surface)
+            ? { components: step.output.surface, data: json }
+            : step.output.surface
+                ? await composeSurface(step, json, ctx)
+                : undefined;
         return {
             text,
             json,
@@ -647,7 +669,7 @@ const DOCUMENT_GUIDES = {
     offer: "A commercial offer: sender and recipient, offer number and date, a short personal intro, the scope of work, a positions table, net / VAT / total, validity and next steps. Use the totals EXACTLY as given.",
     briefing: "A research briefing: title, a three-sentence executive summary, key findings with numbers, sections with headings, implications, and a numbered source list with links.",
     letter: "A business letter with sender, recipient, date, subject line, body and signature.",
-    report: "A structured report with title, summary, sections with headings, tables where useful.",
+    report: "A structured report with title, summary and sections with headings; findings and items as short headed blocks, a table only for figures compared across columns.",
     free: "A well-structured document fitting the brief.",
 };
 /** Images a document may place: earlier generated images, uploads, the project's logos and images. */
@@ -717,19 +739,29 @@ function placeableImages(step, ctx) {
 async function writeHtml(step, ctx, kind) {
     const brief = renderTemplate(step.prompt, ctx.scope);
     const images = placeableImages(step, ctx);
-    const accent = ctx.scope.brand.colors?.[0]?.value ?? "#c4582c";
+    // The look comes from the space's brand, as on the run page; what it does not say, the runner's own.
+    const theme = runTheme(ctx.scope.brand);
+    const accent = theme.accent ?? "#e0531b";
+    const look = [
+        `headings in ${theme.display ? `"${theme.display}"` : "a characterful sans"}, text in ${theme.body ? `"${theme.body}"` : "a clean sans"} (each with a system font behind it)`,
+        `the accent ${accent} for marks and figures`,
+        theme.second ? `${theme.second} for what carries meaning (done, there, good)` : "",
+        theme.background ? `a ground in the tone of ${theme.background}` : "",
+    ]
+        .filter(Boolean)
+        .join(", ");
     const guide = kind === "dashboard"
         ? [
             "Build a single self-contained HTML dashboard (one file).",
             "Charts are INLINE SVG you draw yourself — no external scripts, no CDN, no network requests. Bar, line and donut charts with axis labels and values.",
             "Interactivity (tabs, tooltips, a slider over time, filters) may use a small inline <script>. Everything must also read well without interacting.",
-            "Layout: a title row, 3–6 KPI tiles, then charts and a compact data table, and a 'Sources' list at the bottom.",
-            `Calm design: white background, generous whitespace, system font stack, one accent colour ${accent}, muted greys. Width-responsive with CSS grid.`,
+            "Layout: a title row with one plain sentence of what it shows, 3–6 key figures as tiles, then the charts; things (offers, products, places, people) as cards; a table only for figures compared across columns; a 'Sources' list at the bottom.",
+            `Design: ${look}; generous whitespace, cards for things, width-responsive with CSS grid.`,
         ].join("\n")
         : [
             "Write a single self-contained, print-ready HTML document (A4).",
             DOCUMENT_GUIDES[step.options?.template ?? "free"],
-            `Design: @page A4 margins 18mm, system/Inter font stack, 10.5pt body, clear hierarchy, thin rules, one accent colour ${accent}. No external assets, no scripts.`,
+            `Design: @page A4 margins 18mm, 10.5pt body, ${look}; a clear type scale, thin rules. No external assets, no scripts.`,
         ].join("\n");
     const system = [
         groundRules(ctx),