@uicast/core 0.0.1-beta.2 → 0.0.1

package/dist/expr/evaluate.js

@@ -1,62 +1,52 @@
 import { EntryError } from "../entry-error.js";
-import { ALLOWED_GLOBALS } from "./globals.js";
-import { SaferEval, SaferEvalError } from "./safer-eval.js";
-const saferEval = new SaferEval({
-    allowGlobals: ALLOWED_GLOBALS,
-    enforceAllowlist: true,
-});
-// Every scopes.X.Y path an expression reads, via the shared SaferEval singleton
-// (so extractDeps doesn't reach into the evaluator). Same parse cache as eval().
-export const getScopeReads = (expr) => saferEval.scopeReads(expr);
-// Classify an evaluation failure by provenance: SaferEval's own rejections
-// carry their reason (syntax / policy / unknown identifier); an EntryError
-// passes through (a host function already tagged it); anything else threw
-// while the compiled expression ran.
-const wrapEvalError = (err) => {
+import { CONTEXT_NAMES } from "../constants.js";
+import { unwrapRows } from "../scope/create-proxy-scope.js";
+// Identifier validity is the evaluator's own check; this screens only uicast's names.
+const screened = new WeakSet();
+const screen = (evaluator) => {
+    if (screened.has(evaluator))
+        return;
+    for (const { name } of evaluator.functions) {
+        if (CONTEXT_NAMES.has(name)) {
+            throw new EntryError(`Host function name "${name}" is reserved — it would shadow the expression context of the same name`, { reason: "host-function" });
+        }
+    }
+    screened.add(evaluator);
+};
+// Brand check: core has no runtime import of @uicast/expr.
+const isExpressionError = (err) => typeof err === "object" &&
+    err !== null &&
+    err.uicastExpressionError === true;
+export const wrapEvalError = (err) => {
     if (EntryError.is(err))
         return err;
-    if (err instanceof SaferEvalError)
+    if (isExpressionError(err)) {
+        // A host that classified its own failure keeps that verdict.
+        if (EntryError.is(err.cause))
+            return err.cause;
         return EntryError.wrap(err, err.reason);
+    }
     return EntryError.wrap(err, "expression-runtime");
 };
-// Evaluate a ValueSource: a `literal` is returned as-is, an `expr` runs through
-// SaferEval against context + host functions. Returns unknown — an async expr
-// resolves to a Promise (callers check `value instanceof Promise`). `functions`
-// (a StandardToolV0[]) are spread after context, so a host fn wins a name clash.
-// Every failure surfaces as a classified EntryError.
-export const evaluate = (expr, context, options) => {
-    var _a;
+export const evaluate = (expr, context, evaluator) => {
     if ("literal" in expr)
         return expr.literal;
-    if (!expr.expr)
+    // An empty string falls through to the evaluator, which rejects it.
+    if (expr.expr == null)
         return null;
-    const functions = Object.fromEntries(((_a = options === null || options === void 0 ? void 0 : options.functions) !== null && _a !== void 0 ? _a : []).map((tool) => [
-        tool.name,
-        // This closure is the engine/host boundary: anything escaping
-        // `tool.execute` is host code failing — unless the host already threw a
-        // classified EntryError itself (e.g. "invalid-arguments"), which wrap()
-        // passes through.
-        (input) => {
-            try {
-                const result = tool.execute(input);
-                return result instanceof Promise
-                    ? result.catch((err) => {
-                        throw EntryError.wrap(err, "host-function");
-                    })
-                    : result;
-            }
-            catch (err) {
-                throw EntryError.wrap(err, "host-function");
-            }
-        },
-    ]));
     try {
-        const result = saferEval.eval(expr.expr, Object.assign(Object.assign({}, context), functions), options === null || options === void 0 ? void 0 : options.allowedGlobals);
+        screen(evaluator);
+        const source = expr.expr;
+        const result = evaluator.eval(source, context);
+        // Only a read of a whole scope (`scopes.row`) can put a row window in the result.
+        const data = (value) => evaluator.memberReads(source, "scopes").some((read) => read.indexOf(".", "scopes.".length) === -1)
+            ? unwrapRows(value)
+            : value;
         return result instanceof Promise
-            ? result.catch((err) => {
+            ? result.then(data, (err) => {
                 throw wrapEvalError(err);
             })
-            : result;
+            : data(result);
     }
     catch (err) {
         throw wrapEvalError(err);

package/dist/expr/extract-deps.d.ts

@@ -1,2 +1,4 @@
+import type { ExpressionEvaluator } from "@uicast/expr";
 import { type ComponentEntry } from "../types.js";
-export declare function extractDeps(entry: ComponentEntry): string[];
+export type DepsPart = "all" | "render" | "each";
+export declare function extractDeps(entry: ComponentEntry, evaluator: ExpressionEvaluator, part: DepsPart): string[];

package/dist/expr/extract-deps.js

@@ -1,30 +1,30 @@
 import { isComponentListEntry } from "../types.js";
-import { getScopeReads } from "./evaluate.js";
-// Entries are immutable, so cached reads never go stale; WeakMap so a dropped
-// entry can be collected.
+import { depKey } from "../scope/parse-scope.js";
+// Entries are immutable, so cached reads never go stale.
 const cache = new WeakMap();
-// The reactive scopes.X.Y paths an entry reads, across its props, hidden, and each
-// expressions — the renderer subscribes to these. (seed run once and
-// callbacks read at fire time, so neither is scanned.)
-export function extractDeps(entry) {
-    const cached = cache.get(entry);
+// seed runs once and callbacks read at fire time, so neither is scanned.
+export function extractDeps(entry, evaluator, part) {
+    const slots = cache.get(entry);
+    const cached = slots?.[part];
     if (cached)
         return cached;
     const out = new Set();
-    if (entry.props && "expr" in entry.props && entry.props.expr) {
-        for (const r of getScopeReads(entry.props.expr))
-            out.add(r);
-    }
-    if (entry.hidden) {
-        for (const r of getScopeReads(entry.hidden))
-            out.add(r);
+    const add = (expr) => {
+        for (const r of evaluator.memberReads(expr, "scopes"))
+            out.add(depKey(r));
+    };
+    if (part !== "each") {
+        if (entry.props && "expr" in entry.props && entry.props.expr)
+            add(entry.props.expr);
+        if (entry.hidden)
+            add(entry.hidden);
+        if (entry.loading)
+            add(entry.loading);
     }
     // `each` reads both the list and anything its filter touches (e.g. a search term).
-    if (isComponentListEntry(entry)) {
-        for (const r of getScopeReads(entry.each))
-            out.add(r);
-    }
+    if (part !== "render" && isComponentListEntry(entry))
+        add(entry.each);
     const result = [...out];
-    cache.set(entry, result);
+    cache.set(entry, { ...slots, [part]: result });
     return result;
 }

package/dist/expr/plan-step-waves.d.ts

@@ -0,0 +1,8 @@
+import type { ExpressionEvaluator } from "@uicast/expr";
+type PlannableStep = {
+    set?: string;
+    expr?: string;
+    confirm?: string;
+};
+export declare function planStepWaves<T extends PlannableStep>(steps: readonly T[], evaluator: ExpressionEvaluator, isBarrier?: (step: T) => boolean, declaredWrites?: (step: T) => string[]): T[][];
+export {};

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

@@ -1,9 +1,8 @@
-export { createComponentDefinition } from "./def/create-component-definition.js";
-export { evaluate } from "./expr/evaluate.js";
-export { extractDeps } from "./expr/extract-deps.js";
-export { EntryError, type EntryErrorReason, type EntryFault, } from "./entry-error.js";
+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 { parseScope } from "./scope/parse-scope.js";
-export { buildElementsById } from "./utils/utils.js";
-export { streamJsonLines } from "./stream/stream-json-lines.js";
-export { type ComponentEntry, type ComponentListEntry, type ComponentDefinition, type CombinedSpec, isComponentEntry, isComponentListEntry, } from "./types.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

@@ -1,10 +1,6 @@
-// uicast public API. Prompt-partial builders live in uicast/prompt.
-export { createComponentDefinition } from "./def/create-component-definition.js";
-export { evaluate } from "./expr/evaluate.js";
-export { extractDeps } from "./expr/extract-deps.js";
-export { EntryError, } from "./entry-error.js";
+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 { parseScope } from "./scope/parse-scope.js";
-export { buildElementsById } from "./utils/utils.js";
-export { streamJsonLines } from "./stream/stream-json-lines.js";
-export { isComponentEntry, isComponentListEntry, } from "./types.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

@@ -1,13 +1,23 @@
-/** 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).
+ * Options for `getCommonInstructionsPartialPrompt`.
  *
- * 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.
+ * @example
+ * const options: CommonInstructionsPromptOptions = { maxListItems: 50 };
  */
-export declare function getCommonInstructionsPartialPrompt(_options?: CommonInstructionsPromptOptions): string;
+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

@@ -1,14 +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 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).
+ * 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.
  *
- * 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.
+ * @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(_options = {}) {
-    return INSTRUCTIONS;
+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

@@ -1,35 +1,27 @@
-import type { CombinedSpec, ComponentDefinition } from "../types.js";
+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 = {
-    /** The component defs to advertise — the catalog's `allDefinitions` (plus any app-local defs). */
+    /** Your definitions: the same components the renderer has. One with `hidden: true` is left out. */
     definitions: ComponentDefinition[];
-    /** Shared event schemas (each with a JSON Schema `$id`), rendered once under `# Common Events`. */
-    commonEvents?: CombinedSpec[];
+    /** 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;
 };
 /**
- * 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.
+ * 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`.
  *
- * Mirrors `getFunctionsPartialPrompt` — same `# Available X` / `# X Details`
- * two-section shape.
+ * @example
+ * getComponentsPartialPrompt({ definitions: defs });
  *
- * 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 declare function getComponentsPartialPrompt({ definitions: defs, commonEvents, }: ComponentsPromptOptions): string;
+export declare function getComponentsPartialPrompt({ definitions: defs, urlPolicy, note }: ComponentsPromptOptions): string;