wizards 0.5.13 → 0.6.1

package/node_modules/@engenty-wizards/plugin-sdk/dist/index.d.ts

@@ -793,10 +793,13 @@ export interface PluginRunner {
         token: string;
     }): PluginRunnerAddress | null | Promise<PluginRunnerAddress | null>;
 }
-/** How a run answers a review: accept it, with edited texts where the review allows, or ask for one of the shown steps again. */
+/**
+ * How a run answers a review: accept it, with edits where the review allows (a text, or the
+ * data of a json step), or ask for one of the shown steps again.
+ */
 export type PluginReviewAction = {
     type: "accept";
-    edits?: Record<string, string>;
+    edits?: Record<string, string | Record<string, unknown>>;
 } | {
     type: "regenerate";
     target: string;

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { type ObjectShape } from "./shape.js";
 import { type SurfaceComponent } from "./surface.js";
 /** The engenty avatars a wizard can wear. Same cast as engenty's ui-core. */
 export declare const ENGENTY_KINDS: readonly ["round", "drop", "dome", "flame", "oval", "bean", "pebble", "sprout", "tower", "wedge"];
@@ -547,7 +548,40 @@ export declare const agentStepSchema: z.ZodObject<{
             columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
             options: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>>;
-        surface: z.ZodOptional<z.ZodBoolean>;
+        schema: z.ZodOptional<z.ZodType<ObjectShape, unknown, z.core.$ZodTypeInternals<ObjectShape, unknown>>>;
+        surface: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodEnum<{
+                Actions: "Actions";
+                Badge: "Badge";
+                BarChart: "BarChart";
+                Button: "Button";
+                Callout: "Callout";
+                Card: "Card";
+                Checklist: "Checklist";
+                Chips: "Chips";
+                Column: "Column";
+                DetailGrid: "DetailGrid";
+                DonutChart: "DonutChart";
+                Fold: "Fold";
+                Grid: "Grid";
+                Group: "Group";
+                Image: "Image";
+                LineChart: "LineChart";
+                Link: "Link";
+                List: "List";
+                Metric: "Metric";
+                Row: "Row";
+                Steps: "Steps";
+                Table: "Table";
+                Tabs: "Tabs";
+                Text: "Text";
+            }>;
+            children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
+                path: z.ZodString;
+                componentId: z.ZodString;
+            }, z.core.$strip>]>>;
+        }, z.core.$loose>>]>>;
     }, z.core.$strip>>;
     model: z.ZodOptional<z.ZodEnum<{
         classifier: "classifier";
@@ -687,6 +721,10 @@ export declare const widgetStepSchema: z.ZodObject<{
     entry: z.ZodString;
     data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     sample: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodEnum<{
+        fixed: "fixed";
+        page: "page";
+    }>>;
     size: z.ZodOptional<z.ZodObject<{
         width: z.ZodNumber;
         height: z.ZodNumber;
@@ -777,16 +815,25 @@ export declare const surfaceCandidateSchema: z.ZodObject<{
             Badge: "Badge";
             BarChart: "BarChart";
             Button: "Button";
+            Callout: "Callout";
+            Card: "Card";
+            Checklist: "Checklist";
+            Chips: "Chips";
             Column: "Column";
             DetailGrid: "DetailGrid";
             DonutChart: "DonutChart";
+            Fold: "Fold";
             Grid: "Grid";
+            Group: "Group";
             Image: "Image";
             LineChart: "LineChart";
+            Link: "Link";
             List: "List";
             Metric: "Metric";
             Row: "Row";
+            Steps: "Steps";
             Table: "Table";
+            Tabs: "Tabs";
             Text: "Text";
         }>;
         children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
@@ -841,16 +888,25 @@ export declare const surfaceStepSchema: z.ZodObject<{
             Badge: "Badge";
             BarChart: "BarChart";
             Button: "Button";
+            Callout: "Callout";
+            Card: "Card";
+            Checklist: "Checklist";
+            Chips: "Chips";
             Column: "Column";
             DetailGrid: "DetailGrid";
             DonutChart: "DonutChart";
+            Fold: "Fold";
             Grid: "Grid";
+            Group: "Group";
             Image: "Image";
             LineChart: "LineChart";
+            Link: "Link";
             List: "List";
             Metric: "Metric";
             Row: "Row";
+            Steps: "Steps";
             Table: "Table";
+            Tabs: "Tabs";
             Text: "Text";
         }>;
         children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
@@ -868,16 +924,25 @@ export declare const surfaceStepSchema: z.ZodObject<{
                 Badge: "Badge";
                 BarChart: "BarChart";
                 Button: "Button";
+                Callout: "Callout";
+                Card: "Card";
+                Checklist: "Checklist";
+                Chips: "Chips";
                 Column: "Column";
                 DetailGrid: "DetailGrid";
                 DonutChart: "DonutChart";
+                Fold: "Fold";
                 Grid: "Grid";
+                Group: "Group";
                 Image: "Image";
                 LineChart: "LineChart";
+                Link: "Link";
                 List: "List";
                 Metric: "Metric";
                 Row: "Row";
+                Steps: "Steps";
                 Table: "Table";
+                Tabs: "Tabs";
                 Text: "Text";
             }>;
             children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
@@ -1229,7 +1294,40 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
             options: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>>;
-        surface: z.ZodOptional<z.ZodBoolean>;
+        schema: z.ZodOptional<z.ZodType<ObjectShape, unknown, z.core.$ZodTypeInternals<ObjectShape, unknown>>>;
+        surface: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodEnum<{
+                Actions: "Actions";
+                Badge: "Badge";
+                BarChart: "BarChart";
+                Button: "Button";
+                Callout: "Callout";
+                Card: "Card";
+                Checklist: "Checklist";
+                Chips: "Chips";
+                Column: "Column";
+                DetailGrid: "DetailGrid";
+                DonutChart: "DonutChart";
+                Fold: "Fold";
+                Grid: "Grid";
+                Group: "Group";
+                Image: "Image";
+                LineChart: "LineChart";
+                Link: "Link";
+                List: "List";
+                Metric: "Metric";
+                Row: "Row";
+                Steps: "Steps";
+                Table: "Table";
+                Tabs: "Tabs";
+                Text: "Text";
+            }>;
+            children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
+                path: z.ZodString;
+                componentId: z.ZodString;
+            }, z.core.$strip>]>>;
+        }, z.core.$loose>>]>>;
     }, z.core.$strip>>;
     model: z.ZodOptional<z.ZodEnum<{
         classifier: "classifier";
@@ -1367,6 +1465,10 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     entry: z.ZodString;
     data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     sample: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodEnum<{
+        fixed: "fixed";
+        page: "page";
+    }>>;
     size: z.ZodOptional<z.ZodObject<{
         width: z.ZodNumber;
         height: z.ZodNumber;
@@ -1417,16 +1519,25 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             Badge: "Badge";
             BarChart: "BarChart";
             Button: "Button";
+            Callout: "Callout";
+            Card: "Card";
+            Checklist: "Checklist";
+            Chips: "Chips";
             Column: "Column";
             DetailGrid: "DetailGrid";
             DonutChart: "DonutChart";
+            Fold: "Fold";
             Grid: "Grid";
+            Group: "Group";
             Image: "Image";
             LineChart: "LineChart";
+            Link: "Link";
             List: "List";
             Metric: "Metric";
             Row: "Row";
+            Steps: "Steps";
             Table: "Table";
+            Tabs: "Tabs";
             Text: "Text";
         }>;
         children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
@@ -1444,16 +1555,25 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 Badge: "Badge";
                 BarChart: "BarChart";
                 Button: "Button";
+                Callout: "Callout";
+                Card: "Card";
+                Checklist: "Checklist";
+                Chips: "Chips";
                 Column: "Column";
                 DetailGrid: "DetailGrid";
                 DonutChart: "DonutChart";
+                Fold: "Fold";
                 Grid: "Grid";
+                Group: "Group";
                 Image: "Image";
                 LineChart: "LineChart";
+                Link: "Link";
                 List: "List";
                 Metric: "Metric";
                 Row: "Row";
+                Steps: "Steps";
                 Table: "Table";
+                Tabs: "Tabs";
                 Text: "Text";
             }>;
             children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
@@ -1637,6 +1757,15 @@ export type AgentStep = z.infer<typeof agentStepSchema>;
  * (no text) can take.
  */
 export declare function isDecisionStep(step: AgentStep): boolean;
+/**
+ * What an agent step's json output holds: its schema, or its fields as one. Undefined when it
+ * names neither (the model then returns one table).
+ */
+export declare function declaredShape(step: AgentStep): ObjectShape | undefined;
+/** What an agent step's json output holds: its declared shape, or else one table. */
+export declare function stepShape(step: AgentStep): ObjectShape;
+/** The top-level keys of an agent step's output: what `steps.<id>.<key>` may name. */
+export declare function outputKeys(step: AgentStep): string[];
 export type GenerateStep = z.infer<typeof generateStepSchema>;
 export type WidgetStep = z.infer<typeof widgetStepSchema>;
 export type FilmStep = z.infer<typeof filmStepSchema>;
@@ -2167,7 +2296,40 @@ export declare const wizardSchema: z.ZodObject<{
                 columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 options: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>>>;
-            surface: z.ZodOptional<z.ZodBoolean>;
+            schema: z.ZodOptional<z.ZodType<ObjectShape, unknown, z.core.$ZodTypeInternals<ObjectShape, unknown>>>;
+            surface: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                component: z.ZodEnum<{
+                    Actions: "Actions";
+                    Badge: "Badge";
+                    BarChart: "BarChart";
+                    Button: "Button";
+                    Callout: "Callout";
+                    Card: "Card";
+                    Checklist: "Checklist";
+                    Chips: "Chips";
+                    Column: "Column";
+                    DetailGrid: "DetailGrid";
+                    DonutChart: "DonutChart";
+                    Fold: "Fold";
+                    Grid: "Grid";
+                    Group: "Group";
+                    Image: "Image";
+                    LineChart: "LineChart";
+                    Link: "Link";
+                    List: "List";
+                    Metric: "Metric";
+                    Row: "Row";
+                    Steps: "Steps";
+                    Table: "Table";
+                    Tabs: "Tabs";
+                    Text: "Text";
+                }>;
+                children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
+                    path: z.ZodString;
+                    componentId: z.ZodString;
+                }, z.core.$strip>]>>;
+            }, z.core.$loose>>]>>;
         }, z.core.$strip>>;
         model: z.ZodOptional<z.ZodEnum<{
             classifier: "classifier";
@@ -2305,6 +2467,10 @@ export declare const wizardSchema: z.ZodObject<{
         entry: z.ZodString;
         data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
         sample: z.ZodOptional<z.ZodString>;
+        layout: z.ZodOptional<z.ZodEnum<{
+            fixed: "fixed";
+            page: "page";
+        }>>;
         size: z.ZodOptional<z.ZodObject<{
             width: z.ZodNumber;
             height: z.ZodNumber;
@@ -2355,16 +2521,25 @@ export declare const wizardSchema: z.ZodObject<{
                 Badge: "Badge";
                 BarChart: "BarChart";
                 Button: "Button";
+                Callout: "Callout";
+                Card: "Card";
+                Checklist: "Checklist";
+                Chips: "Chips";
                 Column: "Column";
                 DetailGrid: "DetailGrid";
                 DonutChart: "DonutChart";
+                Fold: "Fold";
                 Grid: "Grid";
+                Group: "Group";
                 Image: "Image";
                 LineChart: "LineChart";
+                Link: "Link";
                 List: "List";
                 Metric: "Metric";
                 Row: "Row";
+                Steps: "Steps";
                 Table: "Table";
+                Tabs: "Tabs";
                 Text: "Text";
             }>;
             children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
@@ -2382,16 +2557,25 @@ export declare const wizardSchema: z.ZodObject<{
                     Badge: "Badge";
                     BarChart: "BarChart";
                     Button: "Button";
+                    Callout: "Callout";
+                    Card: "Card";
+                    Checklist: "Checklist";
+                    Chips: "Chips";
                     Column: "Column";
                     DetailGrid: "DetailGrid";
                     DonutChart: "DonutChart";
+                    Fold: "Fold";
                     Grid: "Grid";
+                    Group: "Group";
                     Image: "Image";
                     LineChart: "LineChart";
+                    Link: "Link";
                     List: "List";
                     Metric: "Metric";
                     Row: "Row";
+                    Steps: "Steps";
                     Table: "Table";
+                    Tabs: "Tabs";
                     Text: "Text";
                 }>;
                 children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{

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

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: FSL-1.1-MIT OR MIT
 import { z } from "zod";
 import { tableColumnsSchema } from "./engenty/data-tables/index.js";
+import { outputShapeSchema, shapeOfFields } from "./shape.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. */
@@ -505,12 +506,19 @@ export const agentStepSchema = z.object({
     output: z
         .object({
         format: z.enum(["text", "markdown", "json"]),
+        /** The short form: one level of keys. A step has `fields` or `schema`, not both. */
         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.
+         * json only: nested data (lists of entries with lists of their own), in the kinds of
+         * `shape.ts`. Objects nest at most four deep, a hundred keys in all.
          */
-        surface: z.boolean().optional(),
+        schema: outputShapeSchema.optional(),
+        /**
+         * json only: a view of the result from the surface catalog, bound to the step's own fields;
+         * reviews and the result show it instead of a plain table. Components: written once, the
+         * same every run, nothing to pay. `true`: a model composes one each run.
+         */
+        surface: z.union([z.boolean(), surfaceComponentsSchema]).optional(),
     })
         .default({ format: "markdown" }),
     /** The kind of model the step needs; default `high`. The model itself is bound elsewhere. */
@@ -570,6 +578,12 @@ export const widgetStepSchema = z.object({
     data: z.record(z.string(), z.string()).default({}),
     /** Workspace path of example data (JSON) for previews before any run. */
     sample: z.string().optional(),
+    /**
+     * How the run shows it: `fixed` (default) at `size`, scaled to the page; `page` as a part of
+     * the page, as wide as it and as tall as its content — a result people scroll and use, not a
+     * picture. PNG/PDF/MP4 still render at `size`.
+     */
+    layout: z.enum(["fixed", "page"]).optional(),
     /** The size the widget is designed for; previews scale it, PNG/PDF/MP4 render at it. */
     size: z
         .object({
@@ -703,6 +717,7 @@ export const stepSchema = z.discriminatedUnion("type", [
 export function isDecisionStep(step) {
     const fields = step.output.fields ?? [];
     return (!step.call &&
+        !step.output.schema &&
         step.model === "classifier" &&
         step.output.format === "json" &&
         fields.length > 0 &&
@@ -712,6 +727,27 @@ export function isDecisionStep(step) {
         !step.mcp?.length &&
         !step.connections?.length);
 }
+/**
+ * What an agent step's json output holds: its schema, or its fields as one. Undefined when it
+ * names neither (the model then returns one table).
+ */
+export function declaredShape(step) {
+    if (step.output.schema) {
+        return step.output.schema;
+    }
+    return step.output.fields?.length ? shapeOfFields(step.output.fields) : undefined;
+}
+/** What an agent step's json output holds: its declared shape, or else one table. */
+export function stepShape(step) {
+    return (declaredShape(step) ?? {
+        kind: "object",
+        fields: { data: { kind: "table", description: "The result as a table" } },
+    });
+}
+/** The top-level keys of an agent step's output: what `steps.<id>.<key>` may name. */
+export function outputKeys(step) {
+    return Object.keys(declaredShape(step)?.fields ?? {});
+}
 export const listSchema = z.object({
     id,
     title: z.string().min(1),
@@ -794,7 +830,10 @@ export function formatsFor(step) {
     }
     if (step.type === "agent") {
         if (step.output.format === "json") {
-            return ["json", "csv", "xlsx", "md", "zip"];
+            // Nested data reads as a document too.
+            return step.output.schema
+                ? ["json", "csv", "xlsx", "md", "pdf", "zip"]
+                : ["json", "csv", "xlsx", "md", "zip"];
         }
         return ["md", "txt", "docx", "pdf", "html", "zip"];
     }
@@ -1017,8 +1056,7 @@ export function validateWizard(def, files) {
         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)));
+            (outputKeys(source).includes(key) || (Boolean(source.each) && key === "rows" && !probability)));
     };
     const conditionIssues = (stepId, c) => {
         if ((c.op === "gt" || c.op === "lt") && typeof c.value !== "number") {
@@ -1053,27 +1091,38 @@ export function validateWizard(def, files) {
             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;
+            const out = source?.type === "agent" ? declaredShape(source)?.fields[key] : undefined;
             if (!out) {
                 return `"optionsFrom" names "${from}.${key}", which is not an output of an earlier agent step.`;
             }
+            // The keys of a table's rows, or of a list's entries; undefined: any (free columns).
+            const columns = out.kind === "table"
+                ? out.columns?.length
+                    ? out.columns
+                    : undefined
+                : out.kind === "list" && out.of.kind === "object"
+                    ? Object.keys(out.of.fields)
+                    : null;
+            if (columns === null) {
+                if (column || cards) {
+                    return column
+                        ? `"optionsFrom": "${from}.${key}" is not a table with the column "${column}".`
+                        : `"cards": "${from}.${key}" is not a table.`;
+                }
+                return out.kind === "list"
+                    ? null
+                    : `"optionsFrom": "${from}.${key}" is not a list (a table takes a column, or "cards").`;
+            }
             if (column) {
-                return out.kind === "table" && (!out.columns?.length || out.columns.includes(column))
+                return !columns || columns.includes(column)
                     ? null
                     : `"optionsFrom": "${from}.${key}" is not a table with the column "${column}".`;
             }
             if (cards) {
-                if (out.kind !== "table") {
-                    return `"cards": "${from}.${key}" is not a table.`;
-                }
-                const missing = Object.values(cards).find((c) => out.columns?.length && !out.columns.includes(c));
-                return missing ? `"cards": table "${from}.${key}" has no column "${missing}".` : null;
+                const missing = Object.values(cards).find((c) => columns && !columns.includes(c));
+                return missing ? `"cards": "${from}.${key}" has no column "${missing}".` : null;
             }
-            return out.kind === "list"
-                ? null
-                : `"optionsFrom": "${from}.${key}" is not a list (a table takes a column, or "cards").`;
+            return `"optionsFrom": "${from}.${key}" is not a list (a table takes a column, or "cards").`;
         }
         return `"optionsFrom" is "steps.<id>.<key>", "steps.<id>.<key>.<column>" or "lists.<id>.<column>".`;
     };
@@ -1182,6 +1231,28 @@ export function validateWizard(def, files) {
                         message: 'A step composes a view ("surface") of json output only.',
                     });
                 }
+                if (step.output.schema) {
+                    if (step.output.fields?.length) {
+                        issues.push({
+                            stepId: step.id,
+                            message: 'Output has "fields" or "schema", not both.',
+                        });
+                    }
+                    if (step.output.format !== "json" || step.call) {
+                        issues.push({
+                            stepId: step.id,
+                            message: step.call
+                                ? 'A step with "call" keeps the tool\'s answer as it is: no "schema".'
+                                : 'A "schema" describes json output: output format "json".',
+                        });
+                    }
+                }
+                if (Array.isArray(step.output.surface)) {
+                    // A step with `each` hands over its entries as `rows`.
+                    for (const issue of validateSurface(step.output.surface, step.each ? ["rows"] : declaredShape(step))) {
+                        issues.push({ stepId: step.id, message: `View: ${issue.message}` });
+                    }
+                }
                 if (step.each) {
                     const ref = dataRef(step.each);
                     const list = ref.match(/^lists\.([a-zA-Z][a-zA-Z0-9_]*)$/)?.[1];

package/node_modules/@engenty-wizards/shared/dist/json-schema.js

@@ -2,6 +2,8 @@ import { z } from "zod";
 import { DEFINITION_VERSION, wizardSchema } from "./definition.js";
 import { manifestSchema, PACKAGE_SCHEMA_URL, WIZARD_SCHEMA_URL } from "./wizard-package.js";
 const DIALECT = "https://json-schema.org/draft/2020-12/schema";
+/** `$comment` is the one place a validator ignores; an unknown `$license` keyword would trip Ajv's strict mode. */
+const LICENSE_COMMENT = "MIT License. Copyright (c) 2026 Matthias Platzer.";
 const SCHEMA_PROPERTY = {
     type: "string",
     description: "The JSON Schema an editor checks this file against; the app does not read it.",
@@ -38,6 +40,7 @@ export function wizardJsonSchema() {
     return {
         $schema: DIALECT,
         $id: WIZARD_SCHEMA_URL,
+        $comment: LICENSE_COMMENT,
         title: "engenty.wizards wizard definition",
         description: `A wizard's definition, version ${DEFINITION_VERSION}. Checked by \`wizards validate\`, which also checks what this schema cannot say: ids, references between steps and templates.`,
         ...withSchemaProperty(generate(wizardSchema)),
@@ -50,6 +53,7 @@ export function packageJsonSchema() {
     return {
         $schema: DIALECT,
         $id: PACKAGE_SCHEMA_URL,
+        $comment: LICENSE_COMMENT,
         title: "engenty.wizards package manifest (wizard.json)",
         description: "wizard.json in a .wizard package — a zip with this file and the wizard's workspace under files/.",
         ...manifest,

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

@@ -1,3 +1,4 @@
+import type { RunTheme } from "./run.js";
 export declare const FACT_TYPES: readonly ["text", "longtext", "number", "date", "url", "email", "phone", "boolean"];
 export type FactType = (typeof FACT_TYPES)[number];
 export interface ProjectFact {
@@ -130,6 +131,16 @@ export interface BrandFont {
      */
     uses?: FontUse[];
 }
+/**
+ * How a wizard's pages look, from the brand: the first standard colour is the accent, a standard
+ * colour named as the ground ("Hintergrund") the background, the next colourful one the second
+ * colour; the typeface for headings and the one for text by their roles. What the brand does not
+ * say stays the runner's own.
+ */
+export declare function runTheme(brand: {
+    colors?: BrandColor[];
+    fonts?: Pick<BrandFont, "family" | "role">[];
+}): RunTheme;
 /** The font's licence as a model reads it: ", licence …, may only be used for …". */
 export declare function fontLicenseWords(f: Pick<BrandFont, "license" | "uses">): string;
 /** A text style of the type scale: "Headline XL – Space Grotesk 600, 48 px, line 90 %, −4 %". */

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

@@ -190,6 +190,60 @@ export const FONT_USE_WORDS = {
     images: "images and social graphics",
     video: "video",
 };
+const BACKGROUND_WORDS = /hintergrund|background|untergrund|grund|paper|papier|fläche|surface/i;
+const TEXT_WORDS = /\btext|schrift|ink|typo/i;
+const DISPLAY_ROLES = /head|überschrift|display|titel|title|headline/i;
+const BODY_ROLES = /body|fließ|copy|lauf|text|ui|interface/i;
+/** The channels of a #rrggbb colour, 0–255; null for anything else. */
+function rgbOf(hex) {
+    const m = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hex.trim());
+    return m
+        ? [Number.parseInt(m[1], 16), Number.parseInt(m[2], 16), Number.parseInt(m[3], 16)]
+        : null;
+}
+/** How light a colour looks, 0–1 (relative luminance). */
+function luminance(hex) {
+    const rgb = rgbOf(hex);
+    if (!rgb) {
+        return 1;
+    }
+    const [r, g, b] = rgb.map((c) => {
+        const v = c / 255;
+        return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/** A colour with a hue of its own, not a grey, white or black. */
+function colourful(hex) {
+    const rgb = rgbOf(hex);
+    return rgb ? Math.max(...rgb) - Math.min(...rgb) > 40 : false;
+}
+/**
+ * How a wizard's pages look, from the brand: the first standard colour is the accent, a standard
+ * colour named as the ground ("Hintergrund") the background, the next colourful one the second
+ * colour; the typeface for headings and the one for text by their roles. What the brand does not
+ * say stays the runner's own.
+ */
+export function runTheme(brand) {
+    const standard = (brand.colors ?? []).filter((c) => !c.section && rgbOf(c.value));
+    const accent = standard[0]?.value ?? null;
+    const background = standard.find((c) => BACKGROUND_WORDS.test(c.name))?.value ?? null;
+    const second = standard
+        .slice(1)
+        .find((c) => c.value !== background && !TEXT_WORDS.test(c.name) && colourful(c.value))
+        ?.value ?? null;
+    const fonts = brand.fonts ?? [];
+    const display = fonts.find((f) => DISPLAY_ROLES.test(f.role)) ?? fonts[0];
+    const body = fonts.find((f) => f !== display && BODY_ROLES.test(f.role)) ?? fonts.find((f) => f !== display);
+    return {
+        accent,
+        second,
+        background,
+        display: display?.family ?? null,
+        body: body?.family ?? null,
+        dark: background ? luminance(background) < 0.18 : false,
+    };
+}
 /** The font's licence as a model reads it: ", licence …, may only be used for …". */
 export function fontLicenseWords(f) {
     return [