@uicast/core 0.0.1-beta.2 → 0.0.2

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

@@ -1,134 +1,133 @@
-import { JSONSchemaToTs } from "../prompt-utils/json-schema-to-ts.js";
-const toJSONSchema = (spec) => spec["~standard"].jsonSchema.input({ target: "draft-2020-12" });
-const readId = (jsonSchema) => jsonSchema === null || jsonSchema === void 0 ? void 0 : jsonSchema.$id;
-// This builder prints a node's own description after an em-dash, so drop it
-// from the schema before type rendering — otherwise `JSONSchemaToTs` (which
-// annotates described nodes inline) would say it twice. Only the ROOT is
-// stripped: descriptions nested inside the type still render as inline
-// comments, which is the only place they can appear.
-const stripRootDescription = (jsonSchema) => jsonSchema !== null && typeof jsonSchema === "object"
-    ? Object.assign(Object.assign({}, jsonSchema), { description: undefined }) : jsonSchema;
-/**
- * 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, indent) => {
-    var _a;
-    const schema = jsonSchema;
-    if (!(schema === null || schema === void 0 ? void 0 : schema.properties))
-        return [];
-    const required = (_a = schema.required) !== null && _a !== void 0 ? _a : [];
-    return Object.entries(schema.properties).map(([name, field]) => {
+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) ? "" : "?";
-        const description = field.description;
-        return `${indent}- ${name}${optional}: ${JSONSchemaToTs(stripRootDescription(field))}${description ? ` — ${description}` : ""}`;
+        // 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]));
+};
 /**
- * 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.
+ * 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`.
  *
- * `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.
+ * @example
+ * getComponentsPartialPrompt({ definitions: defs });
  *
- * 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`.
+ * @example
+ * getComponentsPartialPrompt({ definitions: [...defs, BadgeDef], urlPolicy: { hosts: ["cdn.example.com"] } });
  */
-export function getComponentsPartialPrompt({ definitions: defs, commonEvents = [], }) {
-    const seen = new Set();
-    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();
-    const commonLines = [];
-    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(stripRootDescription(jsonSchema));
-        const description = jsonSchema.description;
-        commonLines.push(`- ${id}: ${ts}${description ? ` — ${description}` : ""}`);
+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);
-    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 === null || cbJSONSchema === void 0 ? void 0 : cbJSONSchema.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 === null || cbJSONSchema === void 0 ? void 0 : cbJSONSchema.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(stripRootDescription(cbJSONSchema))})${tail}`,
-            ];
+    // 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}`];
         });
-        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);
+        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

@@ -1,23 +1,23 @@
+/**
+ * Options for `getEditRequestPrompt`.
+ *
+ * @example
+ * const options: EditRequestPromptOptions = { request: "Add a total row.", missingKeys: ["totals"] };
+ */
 export type EditRequestPromptOptions = {
-    /** The user's change request, e.g. "Add pagination to the orders table". */
+    /** The change the user asked for, in their words. */
     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.
-     */
+    /** Keys named in `children` but never emitted, as after a cut-off response. The model is told to emit them. */
     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.
+ * 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.
  *
- * Not a system-prompt partial: this is per-turn message content, composed by
- * the host into `messages`, not into `system`.
+ * @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;
+export declare function getEditRequestPrompt({ request, missingKeys }: EditRequestPromptOptions): string;

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

@@ -1,22 +1,15 @@
+import { joinSections } from "./format.js";
 /**
- * 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.
+ * 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.
  *
- * Not a system-prompt partial: this is per-turn message content, composed by
- * the host into `messages`, not into `system`.
+ * @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 [
-        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");
+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

@@ -1,24 +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 `key` of the element whose render failed. */
+    /** The failed element's key. */
     key: string;
-    /** The runtime error message, verbatim. */
+    /** 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 = {
-    /** The failures to report, one per failed element. */
+    /** 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.
+ * 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.
  *
- * Not a system-prompt partial: this is per-turn message content, composed by
- * the host into `messages`, not into `system`.
+ * @example
+ * getErrorRecoveryPrompt({
+ *   failures: [{ key: "chart", message: "chartData.map is not a function", reason: "expression-runtime" }],
+ * });
  */
-export declare function getErrorRecoveryPrompt({ failures, }: ErrorRecoveryPromptOptions): string;
+export declare function getErrorRecoveryPrompt({ failures }: ErrorRecoveryPromptOptions): string;

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

@@ -1,23 +1,26 @@
+import { FAULT_BY_REASON, REASON_DESCRIPTIONS } from "../entry-error.js";
 /**
- * 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.
+ * 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.
  *
- * Not a system-prompt partial: this is per-turn message content, composed by
- * the host into `messages`, not into `system`.
+ * @example
+ * getErrorRecoveryPrompt({
+ *   failures: [{ key: "chart", message: "chartData.map is not a function", reason: "expression-runtime" }],
+ * });
  */
-export function getErrorRecoveryPrompt({ failures, }) {
+export function getErrorRecoveryPrompt({ failures }) {
     const list = failures
-        .map((failure) => `- Element \`${failure.key}\`: ${failure.message}`)
+        .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 [
-        "The generated UI hit runtime errors:",
+        "Rendered UI has 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.",
+        "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

@@ -1,24 +1,23 @@
-/** No options yet — the type is reserved so the signature can grow without breaking callers. */
-export type ExpressionsPromptOptions = Record<string, never>;
 /**
- * The `# JavaScript Expressions` block — the micro-expression syntax contract
- * the generation LLM follows when authoring `expr` values (props, hidden,
- * seed, callbacks). Catalog-/app-agnostic: it documents only the evaluator
- * surface (allowed syntax, the `scopes` / `evt` context variables), not any
- * specific host functions.
+ * Options for `getExpressionsPartialPrompt`.
  *
- * Authored in `md/EXPRESSIONS.md` and imported as a JSON string via the
- * md-to-json pipeline (`npm run md-to-json` regenerates the `.json` sibling
- * after edits). The doc carries a visible `🔴ALLOWED_GLOBALS🔴` slot that this
- * builder fills from `globals.ts` (the single source of truth for the sandbox
- * allow-list) so the prompt can never drift from what the evaluator actually
- * permits.
+ * @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();
  *
- * A partial-prompt primitive: the consuming app's prompt assembler composes
- * this — alongside the other `get*PartialPrompt` builders — into the full
- * system prompt. The closing line refers to host functions "listed below",
- * so the app should join its function-list partial (e.g.
- * `getFunctionsPartialPrompt({ functions })`) as a later section. core
- * ships the pieces; the app owns the assembly.
+ * @example
+ * getExpressionsPartialPrompt({ maxLength: 500 }); // with new Evaluator({ maxSourceLength: 500 })
  */
-export declare function getExpressionsPartialPrompt(_options?: ExpressionsPromptOptions): string;
+export declare function getExpressionsPartialPrompt({ maxLength, note, }?: ExpressionsPromptOptions): string;

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

@@ -1,27 +1,17 @@
-import { ALLOWED_GLOBALS } from "../expr/globals.js";
+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 micro-expression syntax contract
- * the generation LLM follows when authoring `expr` values (props, hidden,
- * seed, callbacks). Catalog-/app-agnostic: it documents only the evaluator
- * surface (allowed syntax, the `scopes` / `evt` context variables), not any
- * specific host functions.
+ * 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.
  *
- * Authored in `md/EXPRESSIONS.md` and imported as a JSON string via the
- * md-to-json pipeline (`npm run md-to-json` regenerates the `.json` sibling
- * after edits). The doc carries a visible `🔴ALLOWED_GLOBALS🔴` slot that this
- * builder fills from `globals.ts` (the single source of truth for the sandbox
- * allow-list) so the prompt can never drift from what the evaluator actually
- * permits.
+ * @example
+ * getExpressionsPartialPrompt();
  *
- * A partial-prompt primitive: the consuming app's prompt assembler composes
- * this — alongside the other `get*PartialPrompt` builders — into the full
- * system prompt. The closing line refers to host functions "listed below",
- * so the app should join its function-list partial (e.g.
- * `getFunctionsPartialPrompt({ functions })`) as a later section. core
- * ships the pieces; the app owns the assembly.
+ * @example
+ * getExpressionsPartialPrompt({ maxLength: 500 }); // with new Evaluator({ maxSourceLength: 500 })
  */
-export function getExpressionsPartialPrompt(_options = {}) {
-    const globals = ALLOWED_GLOBALS.join(", ");
-    return EXPRESSIONS.replace("🔴ALLOWED_GLOBALS🔴", globals);
+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

@@ -1,22 +1,22 @@
-import type { StandardToolV0 } from "standard-tool";
+import type { StandardToolV0 } from "@uicast/expr";
+/**
+ * Options for `getFunctionsPartialPrompt`.
+ *
+ * @example
+ * const options: FunctionsPromptOptions = { functions: tools, note: "Amounts are in cents." };
+ */
 export type FunctionsPromptOptions = {
-    /** The host functions to advertise — the same set handed to the renderer's `functions` prop. */
+    /** 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;
 };
 /**
- * Render an array of `StandardToolV0`s into the prompt's function section — a
- * `# Available Functions` names list followed by `# Function Details`, one
- * Markdown bullet per tool as a TypeScript-style call signature derived from
- * the tool's Zod schemas:
- *
- *     - updateRows({ sheet: string, ... }) => void: <description>
- *
- * A tool with no `inputSchema` renders `name()`; one with no `outputSchema`
- * renders `=> void`.
+ * 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`.
  *
- * Catalog-agnostic: a caller passes whatever tool set it exposes to the LLM
- * (whatever host functions it exposes) and composes the returned block into the
- * surrounding prompt it needs (extra calling conventions, examples, …).
- * Mirrors `getComponentsPartialPrompt` — same two-section shape.
+ * @example
+ * getFunctionsPartialPrompt({ functions: tools }); // the same array as new Evaluator({ functions: tools })
  */
-export declare function getFunctionsPartialPrompt({ functions: tools, }: FunctionsPromptOptions): string;
+export declare function getFunctionsPartialPrompt({ functions, note }: FunctionsPromptOptions): string;