@uicast/core 0.0.1-beta.1 → 0.0.1

package/dist/expr/plan-step-waves.js

@@ -0,0 +1,45 @@
+import { depKey } from "../scope/parse-scope.js";
+import { wrapEvalError } from "./evaluate.js";
+// Reads wait for earlier writes, independent steps share a wave, `confirm` and `isBarrier` steps are barriers.
+export function planStepWaves(steps, evaluator, isBarrier, declaredWrites) {
+    const waves = [];
+    let wave = [];
+    let waveWrites = new Set();
+    const close = () => {
+        if (wave.length)
+            waves.push(wave);
+        wave = [];
+        waveWrites = new Set();
+    };
+    for (const step of steps) {
+        const reads = [];
+        if (step.expr) {
+            // Planning parses before `evaluate` runs, so a bad expression must be classified here.
+            try {
+                for (const r of evaluator.memberReads(step.expr, "scopes"))
+                    reads.push(depKey(r));
+                // `currentValue` is the value at the step's own `set`.
+                if (step.set && evaluator.validate(step.expr).freeIds.includes("currentValue"))
+                    reads.push(step.set);
+            }
+            catch (err) {
+                throw wrapEvalError(err);
+            }
+        }
+        // A whole-scope read (`scopes.root.*`) waits for any write into that scope.
+        const dependsOnWave = reads.some((r) => r.endsWith(".*") ? [...waveWrites].some((w) => w.startsWith(r.slice(0, -1))) : waveWrites.has(r));
+        const barrier = !!step.confirm || !!isBarrier?.(step);
+        if (dependsOnWave || barrier)
+            close();
+        wave.push(step);
+        if (step.set)
+            waveWrites.add(step.set);
+        if (declaredWrites)
+            for (const w of declaredWrites(step))
+                waveWrites.add(w);
+        if (barrier)
+            close();
+    }
+    close();
+    return waves;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { ExpressionEvaluator } from "@uicast/expr";
+export { buildElementsByKey } from "./build-elements-by-key.js";
+export { createComponentDefinition } from "./create-component-definition.js";
+export { EntryError, type EntryErrorReason, type EntryFault } from "./entry-error.js";
+export { createProxyScope, type ReactiveProxy } from "./scope/create-proxy-scope.js";
+export { streamJsonLines } from "./stream-json-lines.js";
+export { type CallbackValueSourceAssignment, type CombinedSpec, type ComponentDefinition, type ComponentEntry, type ComponentListEntry, isComponentEntry, type ValueSource, type ValueSourceAssignment, } from "./types.js";
+export type { UrlPolicy } from "./url-policy.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { buildElementsByKey } from "./build-elements-by-key.js";
+export { createComponentDefinition } from "./create-component-definition.js";
+export { EntryError } from "./entry-error.js";
+export { createProxyScope } from "./scope/create-proxy-scope.js";
+export { streamJsonLines } from "./stream-json-lines.js";
+export { isComponentEntry, } from "./types.js";

package/dist/internal.d.ts

@@ -0,0 +1,12 @@
+export { CALLBACK_DEBOUNCE_MS } from "./constants.js";
+export { entryShapeError } from "./entry-shape.js";
+export { evaluate } from "./expr/evaluate.js";
+export { type DepsPart, extractDeps } from "./expr/extract-deps.js";
+export { planStepWaves } from "./expr/plan-step-waves.js";
+export { type JSONSchema, specToJSONSchema } from "./json-schema.js";
+export { noteSection } from "./prompt/format.js";
+export { countEmits, createRowScope, createRowState, getForwardTargets, type RowScope, type RowState, } from "./scope/create-proxy-scope.js";
+export { parseScope } from "./scope/parse-scope.js";
+export { entrySetAddressError, parseSetAddress } from "./scope/parse-set-address.js";
+export { isComponentListEntry } from "./types.js";
+export { findUrlViolations, schemaHasUrlFormat } from "./url-policy.js";

package/dist/internal.js

@@ -0,0 +1,13 @@
+// No semver guarantee.
+export { CALLBACK_DEBOUNCE_MS } from "./constants.js";
+export { entryShapeError } from "./entry-shape.js";
+export { evaluate } from "./expr/evaluate.js";
+export { extractDeps } from "./expr/extract-deps.js";
+export { planStepWaves } from "./expr/plan-step-waves.js";
+export { specToJSONSchema } from "./json-schema.js";
+export { noteSection } from "./prompt/format.js";
+export { countEmits, createRowScope, createRowState, getForwardTargets, } from "./scope/create-proxy-scope.js";
+export { parseScope } from "./scope/parse-scope.js";
+export { entrySetAddressError, parseSetAddress } from "./scope/parse-set-address.js";
+export { isComponentListEntry } from "./types.js";
+export { findUrlViolations, schemaHasUrlFormat } from "./url-policy.js";

package/dist/json-schema.d.ts

@@ -0,0 +1,58 @@
+import type { CombinedSpec } from "./types.js";
+type JSONSchemaType = "object" | "array" | "string" | "number" | "boolean" | "null" | "integer";
+export interface JSONSchema {
+    type?: JSONSchemaType | JSONSchemaType[];
+    format?: string;
+    pattern?: string;
+    $ref?: string;
+    items?: boolean | JSONSchema;
+    prefixItems?: JSONSchema[];
+    enum?: unknown[];
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    default?: unknown;
+    $id?: string;
+    description?: string;
+    properties?: {
+        [key: string]: JSONSchema;
+    };
+    patternProperties?: {
+        [pattern: string]: JSONSchema;
+    };
+    propertyNames?: JSONSchema;
+    required?: string[];
+    not?: JSONSchema;
+    $defs?: {
+        [key: string]: JSONSchema;
+    };
+    definitions?: {
+        [key: string]: JSONSchema;
+    };
+    additionalProperties?: boolean | JSONSchema;
+    unevaluatedProperties?: boolean | JSONSchema;
+    unevaluatedItems?: boolean | JSONSchema;
+    contains?: JSONSchema;
+    dependentSchemas?: {
+        [key: string]: JSONSchema;
+    };
+    if?: JSONSchema;
+    then?: JSONSchema;
+    else?: JSONSchema;
+    anyOf?: JSONSchema[];
+    oneOf?: JSONSchema[];
+    allOf?: JSONSchema[];
+    const?: unknown;
+    minLength?: number;
+    maxLength?: number;
+}
+export declare const isSchemaObject: (node: unknown) => node is JSONSchema;
+export declare const resolvePointer: (ref: string, root: unknown) => unknown;
+export declare const collectRefs: (node: unknown, out?: Set<string>) => Set<string>;
+export declare const specToJSONSchema: (spec: CombinedSpec) => JSONSchema;
+export {};

package/dist/json-schema.js

@@ -0,0 +1,73 @@
+export const isSchemaObject = (node) => typeof node === "object" && node !== null && !Array.isArray(node);
+// `#` is the document itself. Own keys only, so a pointer never lands on a prototype member.
+export const resolvePointer = (ref, root) => {
+    if (ref === "#")
+        return root;
+    if (!ref.startsWith("#/"))
+        return undefined;
+    let node = root;
+    for (const segment of ref.slice(2).split("/")) {
+        const key = segment.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (typeof node !== "object" || node === null || !Object.hasOwn(node, key))
+            return undefined;
+        node = Reflect.get(node, key);
+    }
+    return node;
+};
+// Every `$ref` string at or under `node`.
+export const collectRefs = (node, out = new Set()) => {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectRefs(item, out);
+    }
+    else if (node !== null && typeof node === "object") {
+        for (const [key, value] of Object.entries(node)) {
+            if (key === "$ref" && typeof value === "string")
+                out.add(value);
+            else
+                collectRefs(value, out);
+        }
+    }
+    return out;
+};
+const DEFS = "#/$defs/";
+const renameRefs = (node, renamed) => {
+    if (Array.isArray(node))
+        return node.map((item) => renameRefs(item, renamed));
+    if (node === null || typeof node !== "object")
+        return node;
+    return Object.fromEntries(Object.entries(node).map(([key, value]) => [
+        key,
+        key === "$ref" && typeof value === "string" ? (renamed.get(value) ?? value) : renameRefs(value, renamed),
+    ]));
+};
+// A def that is only a `$ref` is an alias. When nothing else uses its target, both are one type under the alias's name.
+// zod emits such a pair for a recursive schema given a new description.
+const foldAliasDefs = (schema) => {
+    const defs = schema.$defs;
+    if (!defs)
+        return schema;
+    const targetOf = (node) => {
+        const ref = node?.$ref;
+        return typeof ref === "string" && ref.startsWith(DEFS) && ref.slice(DEFS.length) in defs ? ref : undefined;
+    };
+    const used = collectRefs({ ...schema, $defs: undefined });
+    for (const node of Object.values(defs))
+        if (!targetOf(node))
+            collectRefs(node, used);
+    const renamed = new Map();
+    const merged = { ...defs };
+    for (const [key, node] of Object.entries(defs)) {
+        const target = targetOf(node);
+        if (!target || used.has(target) || renamed.has(target))
+            continue;
+        const { $ref, ...annotations } = node;
+        merged[key] = { ...defs[target.slice(DEFS.length)], ...annotations };
+        renamed.set(target, DEFS + key);
+    }
+    if (renamed.size === 0)
+        return schema;
+    const kept = Object.fromEntries(Object.entries(merged).filter(([key]) => !renamed.has(DEFS + key)));
+    return renameRefs({ ...schema, $defs: kept }, renamed);
+};
+export const specToJSONSchema = (spec) => foldAliasDefs(spec["~standard"].jsonSchema.input({ target: "draft-2020-12" }));

package/dist/prompt/format.d.ts

@@ -0,0 +1,5 @@
+export declare const dashTail: (description: string | undefined) => string;
+export declare const unwrapParens: (ts: string) => string;
+export declare const stripRootAnnotations: (jsonSchema: unknown) => unknown;
+export declare const noteSection: (note: string | undefined) => string;
+export declare const joinSections: (...sections: (string | false | null | undefined)[]) => string;

package/dist/prompt/format.js

@@ -0,0 +1,22 @@
+// The prompt's convention: a type, then ` — description`.
+export const dashTail = (description) => (description ? ` — ${description}` : "");
+// Drops one pair of parentheses around the whole type: `(A & B)` → `A & B`, but `(A) | (B)` stays.
+export const unwrapParens = (ts) => {
+    if (!ts.startsWith("(") || !ts.endsWith(")"))
+        return ts;
+    let depth = 0;
+    for (let i = 0; i < ts.length - 1; i++) {
+        if (ts[i] === "(")
+            depth++;
+        else if (ts[i] === ")" && --depth === 0)
+            return ts;
+    }
+    return ts.slice(1, -1);
+};
+// The builder prints the root description and default itself.
+export const stripRootAnnotations = (jsonSchema) => jsonSchema !== null && typeof jsonSchema === "object"
+    ? { ...jsonSchema, description: undefined, default: undefined }
+    : jsonSchema;
+export const noteSection = (note) => (note?.trim() ? `## Note\n\n${note.trim()}` : "");
+// A partial's sections, blank-line separated; empty ones drop out.
+export const joinSections = (...sections) => sections.filter(Boolean).join("\n\n");

package/dist/prompt/get-common-instructions-partial-prompt.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Options for `getCommonInstructionsPartialPrompt`.
+ *
+ * @example
+ * const options: CommonInstructionsPromptOptions = { maxListItems: 50 };
+ */
+export type CommonInstructionsPromptOptions = {
+    /** Most items one list may render; the model pages or filters past it. Default 100. */
+    maxListItems?: number;
+    /** Your text, appended verbatim as a trailing `## Note` section. */
+    note?: string;
+};
+/**
+ * The rules every surface needs: the output format, partial replacement, and the names an expression can read
+ * (`scopes`, `evt`, `currentValue`, host functions). The language itself is `getExpressionsPartialPrompt`; use both.
+ *
+ * @example
+ * const system = [getCommonInstructionsPartialPrompt(), getExpressionsPartialPrompt()].join("\n\n");
+ *
+ * @example
+ * getCommonInstructionsPartialPrompt({ note: "scopes.userCtx holds the signed-in user: name, plan; read-only." });
+ */
+export declare function getCommonInstructionsPartialPrompt({ maxListItems, note, }?: CommonInstructionsPromptOptions): string;

package/dist/prompt/get-common-instructions-partial-prompt.js

@@ -0,0 +1,16 @@
+import { joinSections, noteSection } from "./format.js";
+// Generated from `md/INSTRUCTIONS.md`: run `npm run md-to-json` after editing it.
+import INSTRUCTIONS from "./md/INSTRUCTIONS.json" with { type: "json" };
+/**
+ * The rules every surface needs: the output format, partial replacement, and the names an expression can read
+ * (`scopes`, `evt`, `currentValue`, host functions). The language itself is `getExpressionsPartialPrompt`; use both.
+ *
+ * @example
+ * const system = [getCommonInstructionsPartialPrompt(), getExpressionsPartialPrompt()].join("\n\n");
+ *
+ * @example
+ * getCommonInstructionsPartialPrompt({ note: "scopes.userCtx holds the signed-in user: name, plan; read-only." });
+ */
+export function getCommonInstructionsPartialPrompt({ maxListItems = 100, note, } = {}) {
+    return joinSections(INSTRUCTIONS.replaceAll("🔴MAX_LIST_ITEMS🔴", String(maxListItems)).trim(), noteSection(note));
+}

package/dist/prompt/get-components-partial-prompt.d.ts

@@ -0,0 +1,27 @@
+import type { ComponentDefinition } from "../types.js";
+import { type UrlPolicy } from "../url-policy.js";
+/**
+ * Options for `getComponentsPartialPrompt`.
+ *
+ * @example
+ * const options: ComponentsPromptOptions = { definitions: defs, urlPolicy };
+ */
+export type ComponentsPromptOptions = {
+    /** Your definitions: the same components the renderer has. One with `hidden: true` is left out. */
+    definitions: ComponentDefinition[];
+    /** The renderer's `urlPolicy`, so the model writes URLs the renderer loads. Omitted: the renderer's defaults. */
+    urlPolicy?: UrlPolicy;
+    /** Your text, appended verbatim as this section's trailing `## Note`. */
+    note?: string;
+};
+/**
+ * The component menu, from your definitions. A payload with an `id` prints once, under `## Common Events`; a URL
+ * prop adds `## URL Props`. Throws on a duplicate name, or on two different payloads with one `id`.
+ *
+ * @example
+ * getComponentsPartialPrompt({ definitions: defs });
+ *
+ * @example
+ * getComponentsPartialPrompt({ definitions: [...defs, BadgeDef], urlPolicy: { hosts: ["cdn.example.com"] } });
+ */
+export declare function getComponentsPartialPrompt({ definitions: defs, urlPolicy, note }: ComponentsPromptOptions): string;

package/dist/prompt/get-components-partial-prompt.js

@@ -0,0 +1,133 @@
+import { isSchemaObject, resolvePointer, specToJSONSchema } from "../json-schema.js";
+import { resolveUrlPolicy, schemaHasUrlFormat } from "../url-policy.js";
+import { dashTail, joinSections, noteSection, stripRootAnnotations, unwrapParens } from "./format.js";
+import { jsonSchemaToTs } from "./json-schema-to-ts.js";
+import { collectSharedTypes } from "./shared-types.js";
+const typeOf = (schema, namedRefs) => jsonSchemaToTs(stripRootAnnotations(schema), { namedRefs });
+const describeFields = (schema, indent, namedRefs) => {
+    const required = schema.required ?? [];
+    return Object.entries(schema.properties ?? {}).map(([name, field]) => {
+        const optional = required.includes(name) ? "" : "?";
+        // The engine applies defaults before render, so the default is what omitting the field means.
+        const fallback = "default" in field ? ` = ${JSON.stringify(field.default)}` : "";
+        return `${indent}- ${name}${optional}: ${typeOf(field, namedRefs)}${fallback}${dashTail(field.description)}`;
+    });
+};
+// The props object whose fields list one per line: the schema itself, or what a root `$ref` names.
+const propsObject = (schema) => {
+    if (schema.properties)
+        return schema;
+    if (typeof schema.$ref !== "string")
+        return null;
+    const target = resolvePointer(schema.$ref, schema);
+    return isSchemaObject(target) && target.properties ? target : null;
+};
+// Any other shape (a union, an intersection, a record) prints as one type, so the model still sees it.
+const describeProps = (schema, namedRefs) => {
+    const object = propsObject(schema);
+    if (!object)
+        return [`  Props: ${unwrapParens(typeOf(schema, namedRefs))}`];
+    const fields = describeFields(object, "    ", namedRefs);
+    return fields.length ? ["  Props:", ...fields] : [];
+};
+// What a URL prop may hold. A predicate cannot be described, so it prints nothing: say it in `note`.
+const describeUrlProps = (policy) => {
+    if (typeof policy === "function")
+        return "";
+    const { allowRelative, allowSameOrigin, hosts, allowDataImages, origin } = resolveUrlPolicy(policy);
+    const allowed = [
+        allowRelative && "- relative URL: `/a`, `a/b`, `?q=1`, `#x`",
+        allowSameOrigin && `- absolute URL on ${origin ? `\`${origin}\`` : "this site"}`,
+        hosts.length > 0 && `- http or https URL on ${hosts.map((host) => `\`${host}\``).join(", ")}`,
+        "- `mailto:`, `tel:` or `sms:` link",
+        allowDataImages && "- `data:` image, not SVG",
+    ].filter(Boolean);
+    return `## URL Props\n\nURL-format props (\`format uri\`, \`format uri-reference\`) take only:\n${allowed.join("\n")}\n\nOther URLs fail element.`;
+};
+// A payload with an `id` converts to a root `$ref` into `$defs`; the def's key is the event's name.
+const eventName = (schema) => {
+    const name = schema.$ref?.startsWith("#/$defs/") ? schema.$ref.slice("#/$defs/".length) : undefined;
+    return name && schema.$defs?.[name] ? name : undefined;
+};
+// A callback payload with an `id` is a common event; two different payloads under one `id` throw.
+const commonEvents = (defs) => {
+    const events = new Map();
+    for (const def of defs) {
+        for (const spec of Object.values(def.callbacks ?? {})) {
+            const schema = specToJSONSchema(spec);
+            const name = eventName(schema);
+            if (!name)
+                continue;
+            const fingerprint = JSON.stringify(schema);
+            const known = events.get(name);
+            if (known && known.fingerprint !== fingerprint) {
+                throw new Error(`Two callbacks declare the event "${name}" with different payloads — a shared \`id\` must name one shape.`);
+            }
+            if (!known)
+                events.set(name, { schema, fingerprint });
+        }
+    }
+    return new Map([...events].map(([id, { schema }]) => [id, schema]));
+};
+/**
+ * The component menu, from your definitions. A payload with an `id` prints once, under `## Common Events`; a URL
+ * prop adds `## URL Props`. Throws on a duplicate name, or on two different payloads with one `id`.
+ *
+ * @example
+ * getComponentsPartialPrompt({ definitions: defs });
+ *
+ * @example
+ * getComponentsPartialPrompt({ definitions: [...defs, BadgeDef], urlPolicy: { hosts: ["cdn.example.com"] } });
+ */
+export function getComponentsPartialPrompt({ definitions: defs, urlPolicy, note }) {
+    const names = new Set();
+    for (const { name } of defs) {
+        if (names.has(name))
+            throw new Error(`Duplicate component name: "${name}"`);
+        names.add(name);
+    }
+    const visible = defs.filter((def) => !def.hidden);
+    // A heading with nothing under it is dropped.
+    if (visible.length === 0)
+        return noteSection(note);
+    // One registry for the block: a `$def` shared by an event payload and a prop prints once.
+    const shared = collectSharedTypes();
+    const events = commonEvents(visible);
+    const eventLines = [...events].flatMap(([name, schema]) => {
+        const refs = shared.add(schema);
+        const payload = schema.$defs?.[name];
+        const tail = dashTail(payload.description);
+        const fields = describeFields(payload, "  ", refs);
+        return fields.length ? [`- ${name}${tail}`, ...fields] : [`- ${name}: ${typeOf(payload, refs)}${tail}`];
+    });
+    let hasUrlProps = false;
+    const details = visible.map(({ name, description, props, callbacks }) => {
+        const propsSchema = specToJSONSchema(props);
+        hasUrlProps ||= schemaHasUrlFormat(propsSchema);
+        const propLines = describeProps(propsSchema, shared.add(propsSchema));
+        const handlers = Object.entries(callbacks ?? {}).flatMap(([callback, spec]) => {
+            const schema = specToJSONSchema(spec);
+            const refs = shared.add(schema);
+            const event = eventName(schema);
+            if (event && events.has(event))
+                return [`    - ${callback}(evt: ${event})`];
+            // The description documents the handler, not its `evt`.
+            const tail = dashTail(schema.description);
+            if (schema.type === "null")
+                return [`    - ${callback}()${tail}`];
+            const fields = describeFields(schema, "      ", refs);
+            if (fields.length)
+                return [`    - ${callback}(evt)${tail}`, ...fields];
+            return [`    - ${callback}(evt: ${typeOf(schema, refs)})${tail}`];
+        });
+        return [
+            `- ${name} — ${description}`,
+            ...propLines,
+            ...(handlers.length ? ["  Event handlers:", ...handlers] : []),
+        ].join("\n");
+    });
+    // After the details, so every hoisted definition is in.
+    const sharedLines = shared.lines();
+    const block = joinSections(`# Available Components\n\n${visible.map((def) => def.name).join(", ")}`, eventLines.length > 0 && `## Common Events\n\n${eventLines.join("\n")}`, `## Component Details\n\n${details.join("\n\n")}`, sharedLines.length > 0 && `## Shared Types\n\n${sharedLines.join("\n")}`, hasUrlProps && describeUrlProps(urlPolicy));
+    return joinSections(block.trim(), noteSection(note));
+}

package/dist/prompt/get-edit-request-prompt.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Options for `getEditRequestPrompt`.
+ *
+ * @example
+ * const options: EditRequestPromptOptions = { request: "Add a total row.", missingKeys: ["totals"] };
+ */
+export type EditRequestPromptOptions = {
+    /** The change the user asked for, in their words. */
+    request: string;
+    /** Keys named in `children` but never emitted, as after a cut-off response. The model is told to emit them. */
+    missingKeys?: string[];
+};
+/**
+ * A user message asking the model to change a page it made, by emitting only the entries that change. One turn's
+ * content, not part of the system prompt.
+ *
+ * @example
+ * const messages = [
+ *   { role: "assistant", content: stored.map((entry) => JSON.stringify(entry)).join("\n") },
+ *   { role: "user", content: getEditRequestPrompt({ request: "Make the total large." }) },
+ * ];
+ */
+export declare function getEditRequestPrompt({ request, missingKeys }: EditRequestPromptOptions): string;

package/dist/prompt/get-edit-request-prompt.js

@@ -0,0 +1,15 @@
+import { joinSections } from "./format.js";
+/**
+ * A user message asking the model to change a page it made, by emitting only the entries that change. One turn's
+ * content, not part of the system prompt.
+ *
+ * @example
+ * const messages = [
+ *   { role: "assistant", content: stored.map((entry) => JSON.stringify(entry)).join("\n") },
+ *   { role: "user", content: getEditRequestPrompt({ request: "Make the total large." }) },
+ * ];
+ */
+export function getEditRequestPrompt({ request, missingKeys = [] }) {
+    return joinSections(request, "Change page above. Emit ONLY entries that change: re-emit key to replace its entry (new `children` define its subtree; listed old children stay, don't re-emit them); new keys for new entries. Never re-emit whole page. Re-emitted `seed` doesn't run again: new state goes in new key's `seed`.", missingKeys.length > 0 &&
+        `Warning: page lists keys never emitted (earlier response cut off): ${missingKeys.join(", ")}. They do NOT exist: emit them, or re-emit their parents with fixed \`children\`.`);
+}

package/dist/prompt/get-error-recovery-prompt.d.ts

@@ -0,0 +1,35 @@
+import { type EntryErrorReason } from "../entry-error.js";
+/**
+ * One failed element, for `getErrorRecoveryPrompt`.
+ *
+ * @example
+ * const failure: RenderFailure = { key: "chart", message: error.message, reason: error.reason };
+ */
+export type RenderFailure = {
+    /** The failed element's key. */
+    key: string;
+    /** What went wrong, e.g. the error's `message`. */
+    message: string;
+    /** Adds what this kind of failure means to the line; a reason whose fault is `"environment"` adds nothing. */
+    reason?: EntryErrorReason;
+};
+/**
+ * Options for `getErrorRecoveryPrompt`.
+ *
+ * @example
+ * const options: ErrorRecoveryPromptOptions = { failures: [{ key: "chart", message: error.message }] };
+ */
+export type ErrorRecoveryPromptOptions = {
+    /** One per failed element. */
+    failures: RenderFailure[];
+};
+/**
+ * A user message naming the elements that failed, so the model sends fixed ones under the same keys. One turn's
+ * content, not part of the system prompt.
+ *
+ * @example
+ * getErrorRecoveryPrompt({
+ *   failures: [{ key: "chart", message: "chartData.map is not a function", reason: "expression-runtime" }],
+ * });
+ */
+export declare function getErrorRecoveryPrompt({ failures }: ErrorRecoveryPromptOptions): string;

package/dist/prompt/get-error-recovery-prompt.js

@@ -0,0 +1,26 @@
+import { FAULT_BY_REASON, REASON_DESCRIPTIONS } from "../entry-error.js";
+/**
+ * A user message naming the elements that failed, so the model sends fixed ones under the same keys. One turn's
+ * content, not part of the system prompt.
+ *
+ * @example
+ * getErrorRecoveryPrompt({
+ *   failures: [{ key: "chart", message: "chartData.map is not a function", reason: "expression-runtime" }],
+ * });
+ */
+export function getErrorRecoveryPrompt({ failures }) {
+    const list = failures
+        .map(({ key, message, reason }) => {
+        const line = `- Entry \`${key}\`: ${message}`;
+        // Environment faults are not the model's to fix.
+        if (!reason || FAULT_BY_REASON[reason] === "environment")
+            return line;
+        return `${line} (${reason} — ${REASON_DESCRIPTIONS[reason]})`;
+    })
+        .join("\n");
+    return [
+        "Rendered UI has errors:",
+        list,
+        "Re-emit each failed entry fixed, same `key`. Fix cause: when it comes from another entry (like `seed` elsewhere), fix that entry too.",
+    ].join("\n\n");
+}

package/dist/prompt/get-expressions-partial-prompt.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Options for `getExpressionsPartialPrompt`.
+ *
+ * @example
+ * const options: ExpressionsPromptOptions = { maxLength: 500 };
+ */
+export type ExpressionsPromptOptions = {
+    /** The evaluator's `maxSourceLength`: the longest expression, in characters. Default 1000. */
+    maxLength?: number;
+    /** Your text, appended verbatim as a trailing `## Note`. */
+    note?: string;
+};
+/**
+ * The `# JavaScript Expressions` block: the language's rules, its globals and a few idioms. The globals and the
+ * default length come from `@uicast/expr` itself.
+ *
+ * @example
+ * getExpressionsPartialPrompt();
+ *
+ * @example
+ * getExpressionsPartialPrompt({ maxLength: 500 }); // with new Evaluator({ maxSourceLength: 500 })
+ */
+export declare function getExpressionsPartialPrompt({ maxLength, note, }?: ExpressionsPromptOptions): string;

package/dist/prompt/get-expressions-partial-prompt.js

@@ -0,0 +1,17 @@
+import { ALLOWED_GLOBALS, DEFAULT_MAX_SOURCE_LENGTH } from "@uicast/expr/internal";
+import { joinSections, noteSection } from "./format.js";
+import EXPRESSIONS from "./md/EXPRESSIONS.json" with { type: "json" };
+/**
+ * The `# JavaScript Expressions` block: the language's rules, its globals and a few idioms. The globals and the
+ * default length come from `@uicast/expr` itself.
+ *
+ * @example
+ * getExpressionsPartialPrompt();
+ *
+ * @example
+ * getExpressionsPartialPrompt({ maxLength: 500 }); // with new Evaluator({ maxSourceLength: 500 })
+ */
+export function getExpressionsPartialPrompt({ maxLength = DEFAULT_MAX_SOURCE_LENGTH, note, } = {}) {
+    const language = EXPRESSIONS.replace("🔴ALLOWED_GLOBALS🔴", ALLOWED_GLOBALS.join(", ")).replace("🔴MAX_LENGTH🔴", String(maxLength));
+    return joinSections(language.trim(), noteSection(note));
+}

package/dist/prompt/get-functions-partial-prompt.d.ts

@@ -0,0 +1,22 @@
+import type { StandardToolV0 } from "@uicast/expr";
+/**
+ * Options for `getFunctionsPartialPrompt`.
+ *
+ * @example
+ * const options: FunctionsPromptOptions = { functions: tools, note: "Amounts are in cents." };
+ */
+export type FunctionsPromptOptions = {
+    /** Your host functions: the array the evaluator binds. An empty one adds nothing. */
+    functions: StandardToolV0[];
+    /** Your text, appended verbatim as this section's trailing `## Note`. */
+    note?: string;
+};
+/**
+ * The `# Available Functions` block: a call signature per host function, from its schemas. A tool with no
+ * `outputSchema` prints `=> unknown`: undeclared, not empty. Throws on a duplicate name, a name that is not an
+ * identifier, or a reserved one: `scopes`, `evt`, `currentValue` or a global such as `Math`.
+ *
+ * @example
+ * getFunctionsPartialPrompt({ functions: tools }); // the same array as new Evaluator({ functions: tools })
+ */
+export declare function getFunctionsPartialPrompt({ functions, note }: FunctionsPromptOptions): string;