@uicast/core 0.0.1-beta.1

package/src/expr/safer-eval.ts

@@ -0,0 +1,233 @@
+import * as acorn from "acorn";
+import {
+  containsAwait,
+  extractFreeIdentifiers,
+  extractScopeReads,
+} from "./analyze";
+import { GLOBALS_TO_SHADOW } from "./globals";
+import { SaferEvalError, validateNode } from "./validate";
+
+// Compiles and runs the expressions validate.ts approves: parse + analyse once
+// (cached), compile to a Function (AsyncFunction when the expr uses `await`),
+// shadow ambient globals as undefined params, run in-realm so Proxy state works.
+// Guardrail, not a sandbox — see the Expressions docs page, § Safety.
+
+// Re-exported from validate.ts for callers of this module.
+export { SaferEvalError };
+
+// The AsyncFunction constructor, for expressions that use `await`.
+const AsyncFunction = Object.getPrototypeOf(async () => {})
+  .constructor as typeof Function;
+
+type CacheEntry = {
+  isAsync: boolean;
+  scopeReads: string[];
+  freeIds: string[];
+  // Built lazily on first compile(); validate()/scopeReads() leave it unset.
+  fn?: (context: Record<string, unknown>) => unknown;
+};
+
+export class SaferEval {
+  #cache = new Map<string, CacheEntry>();
+  #maxCacheSize: number;
+  #shadowParams: string[];
+  #allowGlobals: Set<string>;
+  #enforceAllowlist: boolean;
+
+  constructor(
+    options: {
+      maxCacheSize?: number;
+      extraGlobalsToShadow?: string[];
+      allowGlobals?: string[];
+      enforceAllowlist?: boolean;
+    } = {},
+  ) {
+    const {
+      maxCacheSize = 500,
+      extraGlobalsToShadow = [],
+      allowGlobals = [],
+      enforceAllowlist = false,
+    } = options;
+
+    this.#maxCacheSize = maxCacheSize;
+    this.#enforceAllowlist = enforceAllowlist;
+
+    const allowSet = new Set(allowGlobals);
+    this.#allowGlobals = allowSet;
+    this.#shadowParams = [...GLOBALS_TO_SHADOW, ...extraGlobalsToShadow].filter(
+      (g) => !allowSet.has(g),
+    );
+  }
+
+  // Parse + validate without running. Throws SaferEvalError if invalid; returns
+  // isAsync + scopeReads and caches the analysis (compile() builds the fn later).
+  validate(expression: string): {
+    isAsync: boolean;
+    scopeReads: string[];
+    freeIds: string[];
+  } {
+    if (typeof expression !== "string") {
+      throw new SaferEvalError("Expression must be a string", "expression-syntax");
+    }
+
+    const trimmed = expression.trim();
+    if (!trimmed) {
+      throw new SaferEvalError("Expression cannot be empty", "expression-syntax");
+    }
+
+    const cached = this.#cache.get(expression);
+    if (cached) {
+      return {
+        isAsync: cached.isAsync,
+        scopeReads: cached.scopeReads,
+        freeIds: cached.freeIds,
+      };
+    }
+
+    // Parse as `"use strict"; void (expr)`: void(...) forces expression context
+    // (so `{...}` is an object literal, not a block), and strict mode rejects
+    // sloppy-only constructs (octal, `with`, dup params) here, not at compile.
+    const wrapper = `"use strict"; void (${trimmed})`;
+    let ast: acorn.Program;
+    try {
+      ast = acorn.parse(wrapper, {
+        ecmaVersion: 2022,
+        sourceType: "script",
+        allowAwaitOutsideFunction: true,
+      });
+    } catch (e: unknown) {
+      throw new SaferEvalError(
+        `Syntax error: ${e instanceof Error ? e.message : String(e)}. Expression: ${expression}`,
+        "expression-syntax",
+      );
+    }
+
+    validateNode(ast);
+
+    const analysis = {
+      isAsync: containsAwait(ast),
+      scopeReads: extractScopeReads(ast),
+      freeIds: extractFreeIdentifiers(ast),
+    };
+
+    // Cache the analysis (no fn yet); evict oldest when full.
+    if (this.#cache.size >= this.#maxCacheSize) {
+      const firstKey = this.#cache.keys().next().value;
+      if (firstKey !== undefined) this.#cache.delete(firstKey);
+    }
+    this.#cache.set(expression, { ...analysis });
+
+    return analysis;
+  }
+
+  // Compile to a reusable fn (returns a Promise if the expr uses `await`).
+  compile(expression: string): (context: Record<string, unknown>) => unknown {
+    const { isAsync } = this.validate(expression);
+    const entry = this.#cache.get(expression);
+    if (!entry) {
+      // Unreachable — validate() just inserted this entry.
+      throw new SaferEvalError(
+        `Cache entry missing for expression: ${expression}`,
+      );
+    }
+    if (entry.fn) return entry.fn;
+
+    const expr = expression.trim();
+    const Ctor = isAsync ? AsyncFunction : Function;
+
+    // Single-slot cache: new Ctor bakes in the param names (context keys ∪ shadow
+    // params), so it recompiles only if the context shape changes — which it
+    // doesn't in practice (a given expr always sees the same keys).
+    let cachedSig: string | undefined;
+    let cachedFn: ((...args: unknown[]) => unknown) | undefined;
+
+    const evaluator = (context: Record<string, unknown>) => {
+      const contextKeys = Object.keys(context);
+      const sig = contextKeys.join("\u0000");
+      if (sig !== cachedSig) {
+        // Context keys become params; shadow params follow, bound to undefined.
+        const allParams = [...contextKeys, ...this.#shadowParams];
+        try {
+          cachedFn = new Ctor(
+            ...allParams,
+            `"use strict"; return (${expr})`,
+          ) as (...args: unknown[]) => unknown;
+        } catch (e: unknown) {
+          // Parsed but won't compile — surface as SaferEvalError, not a raw one.
+          throw new SaferEvalError(
+            `Failed to compile expression: ${
+              e instanceof Error ? e.message : String(e)
+            }. Expression: ${expression}`,
+            "expression-syntax",
+          );
+        }
+        cachedSig = sig;
+      }
+
+      // Args match allParams: context values (Object.keys order) then shadow fills.
+      const allArgs = [
+        ...Object.values(context),
+        ...new Array(this.#shadowParams.length).fill(undefined),
+      ];
+      return (cachedFn as (...args: unknown[]) => unknown)(...allArgs);
+    };
+
+    entry.fn = evaluator;
+    return evaluator;
+  }
+
+  isAsync(expression: string): boolean {
+    const cached = this.#cache.get(expression);
+    if (cached) return cached.isAsync;
+    return this.validate(expression).isAsync;
+  }
+
+  // Every `scopes.X.Y` path the expression reads — the renderer auto-subscribes
+  // to these instead of the LLM writing a deps array.
+  scopeReads(expression: string): string[] {
+    const cached = this.#cache.get(expression);
+    if (cached) return cached.scopeReads;
+    return this.validate(expression).scopeReads;
+  }
+
+  // Allowlist gate: every free identifier must be an injected context name, a
+  // base allowed global, or one the host opted into via allowedGlobals.
+  #checkAllowlist(
+    freeIds: string[],
+    contextKeys: string[],
+    allowedGlobals: string[],
+  ): void {
+    const allowed = new Set([
+      ...contextKeys,
+      ...this.#allowGlobals,
+      ...allowedGlobals,
+    ]);
+    for (const id of freeIds) {
+      if (!allowed.has(id)) {
+        // The expression named something that doesn't exist here — an
+        // unregistered function or a global outside the allowlist.
+        throw new SaferEvalError(
+          `"${id}" is not available in expressions`,
+          "unknown-reference",
+        );
+      }
+    }
+  }
+
+  eval(
+    expression: string,
+    context: Record<string, unknown> = {},
+    allowedGlobals: string[] = [],
+  ): unknown {
+    if (this.#enforceAllowlist) {
+      const { freeIds } = this.validate(expression);
+      this.#checkAllowlist(freeIds, Object.keys(context), allowedGlobals);
+    }
+    const evaluator = this.compile(expression);
+    return evaluator(context);
+  }
+
+  clearCache(): void {
+    this.#cache.clear();
+  }
+}

package/src/expr/validate.ts

@@ -0,0 +1,149 @@
+import type * as acorn from "acorn";
+import { isNode } from "./ast-utils";
+
+// Expression validation — the guardrail. Walks a parsed expression and throws on
+// anything that shouldn't run; safer-eval.ts compiles only what this approves.
+// Guardrail, NOT a sandbox: a computed key (`obj["con"+"structor"]`) escapes it.
+// Full threat model: the Expressions docs page, § Safety.
+
+// Which EntryError reason an evaluation failure maps to. Defaults to
+// "sandbox-violation" (every policy rejection in this file); the parse and
+// allowlist sites in safer-eval.ts override it.
+export type SaferEvalErrorReason =
+  | "expression-syntax"
+  | "sandbox-violation"
+  | "unknown-reference";
+
+export class SaferEvalError extends Error {
+  readonly reason: SaferEvalErrorReason;
+
+  constructor(
+    message: string,
+    reason: SaferEvalErrorReason = "sandbox-violation",
+  ) {
+    super(message);
+    this.name = "SaferEvalError";
+    this.reason = reason;
+  }
+}
+
+// `eval` / `arguments` can't be shadowed as strict-mode params, so reject them as
+// references here instead (the rest are shadowed — see GLOBALS_TO_SHADOW).
+const FORBIDDEN_IDENTIFIERS = new Set(["eval", "arguments"]);
+
+// Most dangerous syntax never reaches this walk: every expression is parsed as
+// `"use strict"; void (EXPR)`, so a top-level statement / declaration / `with` /
+// octal / import is a syntax error. What survives, to reject by hand, is below.
+
+// Forbidden everywhere, even in a function body: dynamic `import()` loads code,
+// and `import.meta` / `new.target` (MetaProperty) reach host / constructor
+// internals. Keywords, so shadowing can't touch them — block structurally.
+const FORBIDDEN_EXPRESSIONS = new Set(["ImportExpression", "MetaProperty"]);
+
+// Forbidden as the whole expression (which must be one pure value); fine inside a
+// callback body where imperative code is allowed.
+const BODY_ONLY_EXPRESSIONS = new Set([
+  "AssignmentExpression", // x = 1, x += 1
+  "UpdateExpression", // x++, --x
+  "SequenceExpression", // a, b — comma operator
+]);
+
+// Escape-hatch property names: `.constructor` reaches the Function constructor,
+// `.__proto__` the prototype chain. Only static keys are caught; a computed key
+// escapes (the guardrail gap — banning it would ban all `arr[i]` access).
+const FORBIDDEN_PROPERTIES = new Set([
+  "constructor",
+  "__proto__",
+  "prototype",
+  "__defineGetter__",
+  "__defineSetter__",
+  "__lookupGetter__",
+  "__lookupSetter__",
+]);
+
+// Recursively walk the parsed expression, throwing on anything disallowed.
+// insideFunctionBody flips once inside an arrow / function body, where the
+// BODY_ONLY_EXPRESSIONS become legal. Entry point is acorn's Program node.
+export function validateNode(
+  node: acorn.AnyNode | null | undefined,
+  insideFunctionBody = false,
+): void {
+  if (!node || typeof node !== "object") return;
+
+  // The wrapped program must hold exactly one expression (the filter drops the
+  // "use strict" directive). More than one means the expr smuggled a `)` to break
+  // out of `void (...)` — e.g. `1); evil(); (2`.
+  if (node.type === "Program") {
+    const statements = node.body.filter(
+      (s) => !(s.type === "ExpressionStatement" && s.directive),
+    );
+    if (statements.length !== 1) {
+      throw new SaferEvalError(
+        `Expression must be a single expression, got ${statements.length} statements`,
+      );
+    }
+    validateNode(statements[0]);
+    return;
+  }
+
+  // Dynamic import / meta-properties: never allowed, not even in a body.
+  if (FORBIDDEN_EXPRESSIONS.has(node.type)) {
+    throw new SaferEvalError(`"${node.type}" is not allowed in expressions`);
+  }
+
+  // Assignment / update / comma: allowed in a callback body, not as the whole expr.
+  if (BODY_ONLY_EXPRESSIONS.has(node.type) && !insideFunctionBody) {
+    throw new SaferEvalError(
+      `"${node.type}" is only allowed inside a function body, not as the whole expression`,
+    );
+  }
+
+  // Tagged templates invoke an arbitrary tag function.
+  if (node.type === "TaggedTemplateExpression") {
+    throw new SaferEvalError("Tagged template literals are not allowed");
+  }
+
+  // Static access to escape-hatch properties; dynamic keys slip past.
+  if (node.type === "MemberExpression") {
+    const { property, computed } = node;
+    const staticKey =
+      !computed && property.type === "Identifier"
+        ? property.name
+        : computed &&
+            property.type === "Literal" &&
+            typeof property.value === "string"
+          ? property.value
+          : null;
+    if (staticKey !== null && FORBIDDEN_PROPERTIES.has(staticKey)) {
+      throw new SaferEvalError(`Access to "${staticKey}" is not allowed`);
+    }
+  }
+
+  // `eval` / `arguments` in reference position (the recursion below skips a
+  // non-computed member's `.property`, so a harmless `row.arguments` isn't hit).
+  if (node.type === "Identifier" && FORBIDDEN_IDENTIFIERS.has(node.name)) {
+    throw new SaferEvalError(`Access to "${node.name}" is not allowed`);
+  }
+
+  // Recurse. Two carries: descending into a function `body` sets
+  // insideFunctionBody for the subtree; a non-computed member's `.property` is a
+  // name already checked, so skip it (a computed `obj[eval]` is not skipped).
+  const fields = node as unknown as Record<string, unknown>;
+  const isFunction =
+    node.type === "ArrowFunctionExpression" ||
+    node.type === "FunctionExpression";
+  for (const key of Object.keys(node)) {
+    if (key === "type" || key === "start" || key === "end") continue;
+    if (node.type === "MemberExpression" && !node.computed && key === "property")
+      continue;
+    const child = fields[key];
+    const childInside = insideFunctionBody || (isFunction && key === "body");
+    if (Array.isArray(child)) {
+      for (const c of child) {
+        if (isNode(c)) validateNode(c, childInside);
+      }
+    } else if (isNode(child)) {
+      validateNode(child, childInside);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+// uicast public API. Prompt-partial builders live in uicast/prompt.
+
+export { createComponentDefinition } from "./def/create-component-definition";
+
+export { evaluate } from "./expr/evaluate";
+export { extractDeps } from "./expr/extract-deps";
+
+export {
+  EntryError,
+  type EntryErrorReason,
+  type EntryFault,
+} from "./entry-error";
+
+export { createProxyScope, type ReactiveProxy } from "./scope/create-proxy-scope";
+export { parseScope } from "./scope/parse-scope";
+
+export { buildElementsById } from "./utils/utils";
+
+export { streamJsonLines } from "./stream/stream-json-lines";
+
+export {
+  type ComponentEntry,
+  type ComponentListEntry,
+  type ComponentDefinition,
+  type CombinedSpec,
+  isComponentEntry,
+  isComponentListEntry,
+} from "./types";

package/src/prompt/get-common-instructions-partial-prompt.ts

@@ -0,0 +1,20 @@
+import INSTRUCTIONS from "./md/INSTRUCTIONS.json" with { type: "json" };
+
+/** No options yet — the type is reserved so the signature can grow without breaking callers. */
+export type CommonInstructionsPromptOptions = Record<string, never>;
+
+/**
+ * The LLM-facing instruction block — the contract authored in
+ * `md/INSTRUCTIONS.md` and imported here as a JSON string via the md-to-json
+ * pipeline (`npm run md-to-json` regenerates the `.json` sibling after edits).
+ *
+ * A partial-prompt primitive: the consuming app's prompt assembler composes
+ * this — alongside the other `get*PartialPrompt` builders — into the full
+ * system prompt it sends to the generation LLM. core ships the pieces; the app
+ * owns the assembly.
+ */
+export function getCommonInstructionsPartialPrompt(
+	_options: CommonInstructionsPromptOptions = {},
+): string {
+	return INSTRUCTIONS;
+}

package/src/prompt/get-components-partial-prompt.ts

@@ -0,0 +1,153 @@
+import { type JSONSchema, JSONSchemaToTs } from "../prompt-utils/json-schema-to-ts";
+import type { CombinedSpec, ComponentDefinition } from "../types";
+
+const toJSONSchema = (spec: CombinedSpec): unknown =>
+  spec["~standard"].jsonSchema.input({ target: "draft-2020-12" });
+
+const readId = (jsonSchema: unknown): string | undefined =>
+  (jsonSchema as { $id?: string } | null)?.$id;
+
+export type ComponentsPromptOptions = {
+  /** The component defs to advertise — the catalog's `allDefinitions` (plus any app-local defs). */
+  definitions: ComponentDefinition[];
+  /** Shared event schemas (each with a JSON Schema `$id`), rendered once under `# Common Events`. */
+  commonEvents?: CombinedSpec[];
+};
+
+/**
+ * Render an object schema's properties as an indented, described bullet list:
+ *
+ *     - count?: number — The number to display
+ *
+ * Each field's type comes from `JSONSchemaToTs`; its `description` (when set)
+ * follows after an em-dash. A non-object schema, or one without properties,
+ * yields `[]`. Shared by a component's props and a typed event's options — both
+ * are "object schema → described fields".
+ */
+const describeFields = (jsonSchema: unknown, indent: string): string[] => {
+  const schema = jsonSchema as JSONSchema | null;
+  if (!schema?.properties) return [];
+  const required = schema.required ?? [];
+  return Object.entries(schema.properties).map(([name, field]) => {
+    const optional = required.includes(name) ? "" : "?";
+    const description = field.description;
+    return `${indent}- ${name}${optional}: ${JSONSchemaToTs(field)}${
+      description ? ` — ${description}` : ""
+    }`;
+  });
+};
+
+/**
+ * Render an array of component defs into the prompt's component section — a
+ * `# Available Components` names list, an optional `# Common Events` block, then
+ * `# Component Details`, one entry per visible def: its name + description, a
+ * `Props:` list (each prop's type + description) and an `Event handlers:` list
+ * (each handler's signature + description, a typed event's options described one
+ * level deeper). Types come from `JSONSchemaToTs`; every description rides after
+ * an em-dash, so nothing the author wrote on a prop, option, or handler is lost.
+ *
+ * `commonEvents` hoists handlers shared across many components (e.g. `onClick`)
+ * out of every entry. Each passed schema must carry a JSON Schema `$id`; its
+ * payload is rendered once as a named type under `# Common Events`, and a
+ * component whose callback is one of them references it as `evt: <$id>` instead
+ * of re-inlining the payload — killing the per-component duplication. A callback
+ * is matched by its `$id`, so it stays library-agnostic (anything that emits
+ * `$id` participates); non-common callbacks render inline as before.
+ *
+ * Host-only defs (`hidden: true`, e.g. RootFragment) are filtered out so the LLM
+ * never sees host infrastructure in its component menu. Catalog-agnostic: the
+ * caller passes whatever def set + common events it exposes.
+ *
+ * Mirrors `getFunctionsPartialPrompt` — same `# Available X` / `# X Details`
+ * two-section shape.
+ *
+ * Throws on a duplicate component `name`, a common event whose schema has no
+ * `$id`, or a duplicate common event `$id`.
+ */
+export function getComponentsPartialPrompt({
+  definitions: defs,
+  commonEvents = [],
+}: ComponentsPromptOptions): string {
+  const seen = new Set<string>();
+  for (const def of defs) {
+    if (seen.has(def.name)) {
+      throw new Error(`Duplicate component name: "${def.name}"`);
+    }
+    seen.add(def.name);
+  }
+
+  // Index the common events by `$id`, rendering each once. A missing `$id`
+  // would leave the handler unmatchable (it would silently inline on every
+  // component), so it's a hard error — as is a duplicate id, which would make
+  // the per-component reference ambiguous.
+  const commonIds = new Set<string>();
+  const commonLines: string[] = [];
+  for (const schema of commonEvents) {
+    const jsonSchema = toJSONSchema(schema);
+    const id = readId(jsonSchema);
+    if (!id) {
+      throw new Error(
+        'Common event schema is missing a JSON Schema `$id` (add e.g. .meta({ $id: "onClick" }))',
+      );
+    }
+    if (commonIds.has(id)) {
+      throw new Error(`Duplicate common event id: "${id}"`);
+    }
+    commonIds.add(id);
+    const ts = JSONSchemaToTs(jsonSchema);
+    const description = (jsonSchema as { description?: string }).description;
+    commonLines.push(`- ${id}: ${ts}${description ? ` — ${description}` : ""}`);
+  }
+
+  const visible = defs.filter((def) => !def.hidden);
+
+  const detail = visible
+    .map(({ name, description, props, callbacks }) => {
+      const lines = [`- ${name} — ${description}`];
+
+      const propLines = describeFields(toJSONSchema(props), "    ");
+      if (propLines.length) lines.push("  Props:", ...propLines);
+
+      const callbackLines = Object.entries(callbacks || {}).flatMap(
+        ([cbName, cbDef]) => {
+          const cbJSONSchema = toJSONSchema(cbDef);
+          const id = readId(cbJSONSchema);
+          if (id && commonIds.has(id)) {
+            // Common event — its payload is named + described once under
+            // `# Common Events`; reference it instead of re-inlining here.
+            return [`    - ${cbName}(evt: ${id})`];
+          }
+          // The description documents the handler itself, not its `evt`
+          // argument — append it after the signature, as common events do.
+          const cbDescription = (cbJSONSchema as JSONSchema | null)?.description;
+          const tail = cbDescription ? ` — ${cbDescription}` : "";
+          // A `null` payload means the handler carries no event data — render it
+          // as a no-arg call rather than `(evt: null)`.
+          if ((cbJSONSchema as JSONSchema | null)?.type === "null") {
+            return [`    - ${cbName}()${tail}`];
+          }
+          // An object payload's fields are the event's options — list them like
+          // props, one level deeper. Anything else keeps the inline `evt` type.
+          const optionLines = describeFields(cbJSONSchema, "      ");
+          if (optionLines.length) {
+            return [`    - ${cbName}(evt)${tail}`, ...optionLines];
+          }
+          return [`    - ${cbName}(evt: ${JSONSchemaToTs(cbJSONSchema)})${tail}`];
+        },
+      );
+      if (callbackLines.length) lines.push("  Event handlers:", ...callbackLines);
+
+      return lines.join("\n");
+    })
+    .join("\n\n");
+
+  return (
+    "# Available Components\n\n" +
+    visible.map((def) => def.name).join(", ") +
+    (commonLines.length
+      ? `\n\n# Common Events\n\n${commonLines.join("\n")}`
+      : "") +
+    "\n\n# Component Details\n\n" +
+    detail
+  );
+}

package/src/prompt/get-edit-request-prompt.ts

@@ -0,0 +1,37 @@
+export type EditRequestPromptOptions = {
+	/** The user's change request, e.g. "Add pagination to the orders table". */
+	request: string;
+	/**
+	 * Keys referenced as children in the replayed tree but never emitted —
+	 * typically the tail of an earlier response that was cut off. Listing them
+	 * tells the model those elements do NOT exist, so it re-emits them instead
+	 * of keeping them by reference.
+	 */
+	missingKeys?: string[];
+};
+
+/**
+ * The user-turn message for an incremental edit. The host replays the page's
+ * current JSONL as an assistant turn, then sends this as the next user turn:
+ * the change request plus the delta convention (re-emit a key to replace its
+ * subtree — the Partial Replacement rule the system prompt already teaches).
+ * The model then emits only the elements that change instead of the whole
+ * page — cheaper and faster, since output tokens dominate both.
+ *
+ * Not a system-prompt partial: this is per-turn message content, composed by
+ * the host into `messages`, not into `system`.
+ */
+export function getEditRequestPrompt({
+	request,
+	missingKeys = [],
+}: EditRequestPromptOptions): string {
+	return [
+		request,
+		"Update the previously generated page above. Emit ONLY the elements that change: re-emit an existing key to replace that element (its new `children` array defines the new subtree — children you still reference are kept as-is, so do not re-emit them), use fresh keys for new elements, and do not re-emit unchanged elements. Never re-emit the whole page. `seed` on re-emitted keys does NOT re-run — initialize any NEW state via the `seed` of a newly-keyed element instead.",
+		missingKeys.length > 0
+			? `Warning: the page above references child keys that were never emitted (the earlier response was cut off): ${missingKeys.join(", ")}. These elements do NOT exist — emit them now, or re-emit their parents with corrected children.`
+			: "",
+	]
+		.filter(Boolean)
+		.join("\n\n");
+}

package/src/prompt/get-error-recovery-prompt.ts

@@ -0,0 +1,37 @@
+export type RenderFailure = {
+	/** The `key` of the element whose render failed. */
+	key: string;
+	/** The runtime error message, verbatim. */
+	message: string;
+};
+
+export type ErrorRecoveryPromptOptions = {
+	/** The failures to report, one per failed element. */
+	failures: RenderFailure[];
+};
+
+/**
+ * The user-turn message for user-triggered error recovery: an element failed
+ * at runtime (its error slot rendered), and the host asks the model to re-emit
+ * it corrected. Deliberately surface-neutral — it states the failures and the
+ * fix request, while the output conventions come from the surface's own
+ * prompt: on a page surface the host passes this through its edit pipeline
+ * (replayed document + `getEditRequestPrompt`, which carries the delta
+ * convention), on a chat surface it goes out as a plain user message and the
+ * model replies with a corrected fence.
+ *
+ * Not a system-prompt partial: this is per-turn message content, composed by
+ * the host into `messages`, not into `system`.
+ */
+export function getErrorRecoveryPrompt({
+	failures,
+}: ErrorRecoveryPromptOptions): string {
+	const list = failures
+		.map((failure) => `- Element \`${failure.key}\`: ${failure.message}`)
+		.join("\n");
+	return [
+		"The generated UI hit runtime errors:",
+		list,
+		"Diagnose each failure and emit a corrected version of the failed element, keeping its `key`. Fix the cause, not just the reported line — if the error comes from state or an expression that another element sets up (e.g. a `seed` elsewhere), correct that element as well.",
+	].join("\n\n");
+}