wizards 0.5.12 → 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/db/control-schema.js

@@ -80,6 +80,16 @@ export const setting = sqliteTable("setting", {
     key: text("key").primaryKey(),
     value: text("value", { mode: "json" }).$type().notNull(),
 });
+/**
+ * The runner's own words in a language outside `LANGS`, translated once for the runtime:
+ * `source` is the hash of the English tables they were made from.
+ */
+export const uiTranslation = sqliteTable("ui_translation", {
+    lang: text("lang").primaryKey(),
+    source: text("source").notNull(),
+    texts: text("texts", { mode: "json" }).$type().notNull(),
+    createdAt: createdAt(),
+});
 // --- marketplace -----------------------------------------------------------------
 // The marketplace is an app of its own (docs/marketplace-contract.md). What this runtime keeps
 // of it for offline use: its starters and what people starred, as the marketplace exports them.

package/apps/runtime/dist/db/migrations/control/0010_tan_snowbird.sql

@@ -0,0 +1,6 @@
+CREATE TABLE `ui_translation` (
+	`lang` text PRIMARY KEY NOT NULL,
+	`source` text NOT NULL,
+	`texts` text NOT NULL,
+	`created_at` integer DEFAULT (unixepoch() * 1000) NOT NULL
+);