@uicast/core 0.0.1-beta.2 → 0.0.1

package/CHANGELOG.md

@@ -2,18 +2,8 @@
 
 All notable changes to this package will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.0.1] - 2026-09-30
 
-### Added
-
-- Initial public beta of the framework-agnostic uicast engine: entry format, sandboxed JavaScript expressions, reactive scopes, and prompt partial builders.
-- Prompt signatures carry schema descriptions: any described field (Zod `.describe()` / `.meta({ description })`) renders inline as `type /* description */`, at every nesting level — objects, arrays, enums, tuples, unions, `$ref`s.
-- Function signatures in the prompt render multiline, one field per line, via `JSONSchemaToTs`'s new `multiline` option.
-
-### Changed
-
-- Reactive writes wake descendant-path subscribers: replacing `products` re-renders a reader of `products.length`. The reverse stays exact.
-- The contract no longer mentions a `deps` array — the runtime extracts the read set from expression text.
+The first release. Earlier changes are in the [pre-release changelog](https://github.com/finom/uicast/blob/a2eaa7703496f7679efd56f5309ee08a1dd4209b/packages/core/CHANGELOG.md).

package/README.md

@@ -1 +1,120 @@
-Coming soon.
+<h1 align="center">@uicast/core</h1>
+<p align="center">Part of <a href="https://github.com/finom/uicast"><strong>uicast</strong></a>, the expression-driven generative UI framework.</p>
+<p align="center"><a href="https://uicast.dev">uicast.dev</a></p>
+<p align="center"><a href="https://www.npmjs.com/package/@uicast/core"><img src="https://img.shields.io/npm/v/@uicast/core.svg?color=brightgreen" alt="npm version"></a> <a href="https://scorecard.dev/viewer/?uri=github.com/finom/uicast"><img src="https://api.scorecard.dev/projects/github.com/finom/uicast/badge" alt="OpenSSF Scorecard"></a> <a href="https://www.bestpractices.dev/projects/15106"><img src="https://www.bestpractices.dev/projects/15106/badge" alt="OpenSSF Best Practices"></a> <a href="https://github.com/finom/uicast/actions/workflows/ci.yml"><img src="https://github.com/finom/uicast/actions/workflows/ci.yml/badge.svg" alt="CI"></a></p>
+
+The engine of **uicast**, without React: component definitions, the entry format, reactive scopes, error classification and the prompt builders. [`@uicast/react`](https://www.npmjs.com/package/@uicast/react) renders on top of it.
+
+```sh
+npm install @uicast/core @uicast/expr
+```
+
+## Define a component
+
+A definition is what the model reads about a component. It imports no React, so the prompt can be built on the server.
+
+```ts
+import { createComponentDefinition } from "@uicast/core";
+import z from "zod";
+
+export const StatDef = createComponentDefinition({
+  name: "Stat",
+  description: "One number with a label. Use it for a KPI, not for a table cell.",
+  props: z.strictObject({
+    label: z.string().meta({ description: "What the number means" }),
+    value: z.number().meta({ description: "The number itself" }),
+  }),
+});
+```
+
+`props` and each payload in `callbacks` are schemas that implement [Standard Schema](https://standardschema.dev/schema) and [Standard JSON Schema](https://standardschema.dev/json-schema): Zod 4.2+, Valibot or ArkType. Every `description` reaches the model word for word.
+
+## Build the prompt
+
+```ts
+import {
+  getCommonInstructionsPartialPrompt,
+  getComponentsPartialPrompt,
+  getExpressionsPartialPrompt,
+  getFunctionsPartialPrompt,
+  getScopePartialPrompt,
+} from "@uicast/core/prompt";
+
+const system = [
+  getCommonInstructionsPartialPrompt(),
+  getScopePartialPrompt({ kind: "page" }),
+  getComponentsPartialPrompt({ definitions: [StatDef] }),
+  getFunctionsPartialPrompt({ functions: tools }),
+  getExpressionsPartialPrompt(),
+].join("\n\n");
+```
+
+Keep this order: each block refers to earlier ones.
+
+| Builder | Emits |
+| --- | --- |
+| `getCommonInstructionsPartialPrompt()` | The entry format and its rules. |
+| `getScopePartialPrompt({ kind })` | What one response should be: `"page"`, `"widget"` or `"answer"`. |
+| `getComponentsPartialPrompt({ definitions })` | The components, from your definitions. |
+| `getFunctionsPartialPrompt({ functions })` | The signatures of your [host functions](https://uicast.dev/expr/functions). |
+| `getExpressionsPartialPrompt()` | The expression language. |
+
+Each takes `note`: your text, added at the end of its block. Two more builders make a user message for one turn:
+
+- `getEditRequestPrompt({ request, missingKeys })` asks for a change to a stored page. The model sends only the entries that change; a line with an existing key replaces that entry. `buildElementsByKey(entries)` applies the same rule to stored lines.
+- `getErrorRecoveryPrompt({ failures })` names the elements that failed, so the model sends them fixed.
+
+## Read the stream
+
+`streamJsonLines` yields each line of a stream that parses as JSON, and skips the rest: code fences, prose, a cut-off last line. On the server, store each entry as it arrives:
+
+```ts
+import { isComponentEntry, streamJsonLines } from "@uicast/core";
+
+for await (const value of streamJsonLines(result.textStream)) {
+  if (isComponentEntry(value)) await saveEntry(value);
+}
+```
+
+In the browser, `streamJsonLines<ComponentEntry>(res.body)` feeds the renderer. See [Streaming](https://uicast.dev/streaming).
+
+## Errors
+
+Every element failure is an `EntryError`. Its `fault` says whose code failed: `"document"` means the model wrote the bug, so sending it back can fix it; `"environment"` means your code failed.
+
+```ts
+import type { EntryError } from "@uicast/core";
+import { getErrorRecoveryPrompt } from "@uicast/core/prompt";
+
+function onError(error: EntryError) {
+  if (error.fault !== "document" || !error.elementKey) return report(error);
+  sendUserMessage(
+    getErrorRecoveryPrompt({
+      failures: [{ key: error.elementKey, message: error.message, reason: error.reason }],
+    }),
+  );
+}
+```
+
+The renderer calls `onError` once per failure. See [Error recovery](https://uicast.dev/error-recovery).
+
+## Exports
+
+| Export | What it does |
+| --- | --- |
+| `createComponentDefinition(def)` | Builds a component definition. |
+| `streamJsonLines(source)` | Yields each JSON line of a byte or text stream. |
+| `isComponentEntry(value)` | Checks that a parsed value is an entry. |
+| `buildElementsByKey(entries)` | Folds entries into a `key → entry` map, applying replacements. |
+| `createProxyScope(initial?)` | A reactive scope, for a [scope your app adds](https://uicast.dev/react/renderer#extra-named-scopes). |
+| `EntryError` | The error every element failure arrives as. |
+
+The prompt builders come from `@uicast/core/prompt`.
+
+## Documentation
+
+[Concepts](https://uicast.dev/concepts) · [Component definition](https://uicast.dev/def) · [Assembling the prompt](https://uicast.dev/prompt) · [Entry fields](https://uicast.dev/entry) · [Streaming](https://uicast.dev/streaming) · [Error recovery](https://uicast.dev/error-recovery) · [API reference](https://uicast.dev/api-ref#uicastcore)
+
+## License
+
+[MIT](https://github.com/finom/uicast/blob/main/LICENSE) © [Andrey Gubanov](https://github.com/finom)

package/dist/build-elements-by-key.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentEntry } from "./types.js";
+/**
+ * Folds entries into a `key → entry` map, as they render: a re-emitted key replaces its subtree but keeps the old
+ * children its new `children` still names.
+ *
+ * @example
+ * const byKey = buildElementsByKey(storedEntries);
+ * const current = Object.values(byKey); // without the entries a re-emit dropped
+ *
+ * @example
+ * const missingKeys = Object.values(byKey).flatMap((entry) => entry.children ?? []).filter((key) => !byKey[key]);
+ */
+export declare function buildElementsByKey(lines: ComponentEntry[]): Record<string, ComponentEntry>;

package/dist/build-elements-by-key.js

@@ -0,0 +1,39 @@
+// The keys reachable from `start` through `children`, optionally only those `within` a set.
+const reachable = (map, start, within) => {
+    const out = new Set();
+    const stack = [...start];
+    for (let key = stack.pop(); key !== undefined; key = stack.pop()) {
+        if (out.has(key) || (within && !within.has(key)))
+            continue;
+        out.add(key);
+        stack.push(...(map[key]?.children ?? []));
+    }
+    return out;
+};
+/**
+ * Folds entries into a `key → entry` map, as they render: a re-emitted key replaces its subtree but keeps the old
+ * children its new `children` still names.
+ *
+ * @example
+ * const byKey = buildElementsByKey(storedEntries);
+ * const current = Object.values(byKey); // without the entries a re-emit dropped
+ *
+ * @example
+ * const missingKeys = Object.values(byKey).flatMap((entry) => entry.children ?? []).filter((key) => !byKey[key]);
+ */
+export function buildElementsByKey(lines) {
+    // No prototype: keys are model-written, and `__proto__` or `toString` must be plain keys.
+    const map = Object.create(null);
+    for (const line of lines) {
+        const old = map[line.key];
+        if (old) {
+            const descendants = reachable(map, old.children ?? []);
+            const kept = reachable(map, line.children ?? [], descendants);
+            for (const key of descendants)
+                if (!kept.has(key))
+                    delete map[key];
+        }
+        map[line.key] = line;
+    }
+    return map;
+}

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const CALLBACK_DEBOUNCE_MS = 300;
+export declare const CONTEXT_NAMES: ReadonlySet<string>;

package/dist/constants.js

@@ -0,0 +1,4 @@
+// The prompt tells the model this number too.
+export const CALLBACK_DEBOUNCE_MS = 300;
+// A host function may not take one of these: it would shadow the context.
+export const CONTEXT_NAMES = new Set(["scopes", "evt", "currentValue"]);

package/dist/create-component-definition.d.ts

@@ -0,0 +1,26 @@
+import type { CombinedSpec, ComponentDefinition } from "./types.js";
+type EmptyProps = Record<string, never>;
+declare const NO_PROPS: CombinedSpec<EmptyProps, EmptyProps>;
+/**
+ * Builds a component definition, what the model reads about a component. Throws when `props` or a callback payload
+ * declares a `children` field: that name is reserved for child entries.
+ *
+ * @example
+ * export const BadgeDef = createComponentDefinition({
+ *   name: "Badge",
+ *   description: "A short status label.",
+ *   props: z.strictObject({ text: z.string().meta({ description: "The label" }) }),
+ * });
+ *
+ * @example
+ * createComponentDefinition({
+ *   name: "Button", description: "A clickable button.",
+ *   props: z.strictObject({ text: z.string() }),
+ *   callbacks: { onClick: z.null() }, // printed as onClick()
+ * });
+ */
+export declare const createComponentDefinition: <TProps extends CombinedSpec = typeof NO_PROPS, TCallbacks extends Record<string, CombinedSpec> = Record<string, never>>({ name, description, props, callbacks, hidden, }: Omit<ComponentDefinition<TProps, TCallbacks>, "props"> & {
+    /** The props schema. Omit it for a component that takes none. */
+    props?: TProps;
+}) => ComponentDefinition<TProps, TCallbacks>;
+export {};

package/dist/create-component-definition.js

@@ -0,0 +1,74 @@
+import { isSchemaObject, resolvePointer, specToJSONSchema } from "./json-schema.js";
+const EMPTY_OBJECT_SCHEMA = {
+    type: "object",
+    properties: {},
+    additionalProperties: false,
+};
+// Hand-written, so core needs no schema library.
+const NO_PROPS = {
+    "~standard": {
+        version: 1,
+        vendor: "uicast",
+        validate: (value) => ({ value: value }),
+        jsonSchema: {
+            input: () => ({ ...EMPTY_OBJECT_SCHEMA }),
+            output: () => ({ ...EMPTY_OBJECT_SCHEMA }),
+        },
+    },
+};
+const RESERVED_PROP = "children";
+// The top-level field names: the root object's, each union or intersection branch's, and a root `$ref`'s.
+const propertyNames = (spec) => {
+    let schema;
+    try {
+        schema = specToJSONSchema(spec);
+    }
+    catch {
+        // A spec that cannot convert fails loudly in the prompt builder instead.
+        return [];
+    }
+    const names = new Set();
+    const seen = new Set();
+    const stack = [schema];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (!isSchemaObject(node) || seen.has(node))
+            continue;
+        seen.add(node);
+        for (const name of Object.keys(node.properties ?? {}))
+            names.add(name);
+        if (typeof node.$ref === "string")
+            stack.push(resolvePointer(node.$ref, schema));
+        stack.push(...(node.anyOf ?? []), ...(node.oneOf ?? []), ...(node.allOf ?? []));
+    }
+    return [...names];
+};
+/**
+ * Builds a component definition, what the model reads about a component. Throws when `props` or a callback payload
+ * declares a `children` field: that name is reserved for child entries.
+ *
+ * @example
+ * export const BadgeDef = createComponentDefinition({
+ *   name: "Badge",
+ *   description: "A short status label.",
+ *   props: z.strictObject({ text: z.string().meta({ description: "The label" }) }),
+ * });
+ *
+ * @example
+ * createComponentDefinition({
+ *   name: "Button", description: "A clickable button.",
+ *   props: z.strictObject({ text: z.string() }),
+ *   callbacks: { onClick: z.null() }, // printed as onClick()
+ * });
+ */
+export const createComponentDefinition = ({ name, description, props = NO_PROPS, callbacks, hidden, }) => {
+    if (propertyNames(props).includes(RESERVED_PROP)) {
+        throw new Error(`Component "${name}": "children" is a reserved name and cannot be a prop. Name the prop for what it holds (e.g. "text"); nested elements come from the entry's \`children\` array.`);
+    }
+    for (const [event, payload] of Object.entries(callbacks ?? {})) {
+        if (propertyNames(payload).includes(RESERVED_PROP)) {
+            throw new Error(`Component "${name}": callback "${event}" declares a "children" field, which is a reserved name. Rename it.`);
+        }
+    }
+    return { name, description, props, callbacks, hidden };
+};

package/dist/entry-error.d.ts

@@ -1,47 +1,57 @@
-export type EntryErrorReason = 
-/** The expression doesn't parse. */
-"expression-syntax"
-/** The expression uses syntax or reaches an API the sandbox blocks. */
- | "sandbox-violation"
-/** The expression references an identifier that doesn't exist — an unregistered function, a blocked-by-omission global, or an unknown scope path target. */
- | "unknown-reference"
-/** The element's `component` name has no implementation in the registry. */
- | "unknown-component"
-/** A list's `each` did not evaluate to an array, or a non-list element was rendered as a list. */
- | "invalid-list"
-/** The implementation's render threw, and the evaluated props FAIL the def's schema — the document sent a shape the contract forbids. */
- | "invalid-props"
-/** A host function rejected the arguments the document called it with (host functions throw this deliberately). */
- | "invalid-arguments"
-/** A host function threw or rejected while executing — server/host failure. */
- | "host-function"
-/** The host `init` callback threw or rejected. */
- | "host-init"
-/** The implementation's render threw on props its own def schema accepts — an implementation bug. */
- | "implementation"
-/** A valid expression threw at runtime (e.g. a property read through null) — the document wrote the path, but the host may have written the value. */
- | "expression-runtime"
-/** Escaped from an uninstrumented path — the defensive default. */
- | "unknown";
+import type { ExpressionErrorReason } from "@uicast/expr";
+/**
+ * What failed: an expression's refusal or failure (an `ExpressionErrorReason`), or an element-level one.
+ *
+ * @example
+ * if (error.reason === "unknown-component") return <p>No implementation for {error.elementKey}</p>;
+ */
+export type EntryErrorReason = ExpressionErrorReason | "invalid-entry" | "unknown-component" | "invalid-list" | "invalid-props" | "host-init" | "implementation" | "unknown";
+/**
+ * Whose code must fix a failure: `"document"` the model's (re-emit the entry), `"environment"` the host's, `"unknown"`
+ * either.
+ *
+ * @example
+ * const fault: EntryFault = error.fault; // "document" for reason "invalid-props"
+ */
 export type EntryFault = "document" | "environment" | "unknown";
+export declare const FAULT_BY_REASON: Record<EntryErrorReason, EntryFault>;
+export declare const REASON_DESCRIPTIONS: Record<EntryErrorReason, string>;
+/**
+ * The classified error every element failure arrives as, in the error slot and in `onError`. `reason` says what
+ * failed; `fault` says whose code must fix it.
+ *
+ * @example
+ * const onError = (error: EntryError) =>
+ *   error.fault === "document" ? askModelToFix(error.elementKey, error.message) : report(error);
+ */
 export declare class EntryError extends Error {
+    /** What failed, e.g. `"invalid-props"`. */
     readonly reason: EntryErrorReason;
-    /** The element the failure belongs to; the error boundary fills it in when the throw site couldn't. */
+    /** The key of the element that failed. The error boundary fills it in when the throw site could not. */
     elementKey?: string;
+    /** Brand for `EntryError.is`: `instanceof` fails when two copies of this package share a bundle. */
     readonly uicastEntryError = true;
     constructor(message: string, options: {
         reason: EntryErrorReason;
         elementKey?: string;
         cause?: unknown;
     });
-    /** Coarse verdict for recovery flows: `document` → ask the model to re-emit; `environment` → the host's problem; `unknown` → undecidable. */
+    /** Whose code must fix it: `"document"` (the model, by re-emitting), `"environment"` (host code) or `"unknown"`. */
     get fault(): EntryFault;
-    /** Cross-copy-safe `instanceof`. */
+    /**
+     * Whether `err` is an `EntryError`, from any copy of this package. Use it over `instanceof`.
+     *
+     * @example
+     * if (EntryError.is(err)) console.warn(err.reason, err.elementKey);
+     */
     static is(err: unknown): err is EntryError;
     /**
-     * Classify `err` as `reason`, keeping the original in `cause`. An error that
-     * is already an EntryError passes through untouched (the deepest — most
-     * precise — classification wins); a missing `elementKey` is filled in.
+     * Turns any thrown value into an `EntryError` with this `reason`. An `EntryError` passes through as is, and gets
+     * `elementKey` if it had none.
+     *
+     * @example
+     * const error = EntryError.wrap(err, "implementation", "orders-table");
+     * error.fault; // "environment"
      */
     static wrap(err: unknown, reason: EntryErrorReason, elementKey?: string): EntryError;
 }

package/dist/entry-error.js

@@ -1,13 +1,9 @@
-// The engine's classified error: every failure surfaced to the host — through
-// the error slot or the Renderer's `onError` — is an EntryError. Classification
-// happens at the throw site (by provenance: whose code raised it), never by
-// inspecting messages. Reason names state the verdict, not the location.
-// The single source of truth `fault` derives from — every reason maps to
-// exactly one fault; hosts pick a side by picking the reason.
-const FAULT_BY_REASON = {
+export const FAULT_BY_REASON = {
     "expression-syntax": "document",
-    "sandbox-violation": "document",
+    "guardrail-violation": "document",
+    "budget-exceeded": "document",
     "unknown-reference": "document",
+    "invalid-entry": "document",
     "unknown-component": "document",
     "invalid-list": "document",
     "invalid-props": "document",
@@ -18,31 +14,64 @@ const FAULT_BY_REASON = {
     "expression-runtime": "unknown",
     unknown: "unknown",
 };
+// Appended to the recovery prompt's failure lines.
+export const REASON_DESCRIPTIONS = {
+    "expression-syntax": "expression doesn't parse",
+    "guardrail-violation": "breaks guardrail rule: blocked syntax or API, or `set` not `scopes.<scope>.<field>`",
+    "budget-exceeded": "expression passed its step, time or allocation budget",
+    "unknown-reference": "name doesn't exist: unregistered function, blocked global, or unset scope path",
+    "invalid-entry": "line field has wrong type, like `seed` not array of steps",
+    "unknown-component": "no component with this name",
+    "invalid-list": "`each` not array, or `as` names existing scope",
+    "invalid-props": "evaluated props don't match component's props schema",
+    "invalid-arguments": "host function rejected call's arguments",
+    "host-function": "host function failed",
+    "host-init": "host init callback failed",
+    implementation: "component implementation threw",
+    "expression-runtime": "valid expression threw at runtime",
+    unknown: "unclassified failure",
+};
+/**
+ * The classified error every element failure arrives as, in the error slot and in `onError`. `reason` says what
+ * failed; `fault` says whose code must fix it.
+ *
+ * @example
+ * const onError = (error: EntryError) =>
+ *   error.fault === "document" ? askModelToFix(error.elementKey, error.message) : report(error);
+ */
 export class EntryError extends Error {
+    /** What failed, e.g. `"invalid-props"`. */
+    reason;
+    /** The key of the element that failed. The error boundary fills it in when the throw site could not. */
+    elementKey;
+    /** Brand for `EntryError.is`: `instanceof` fails when two copies of this package share a bundle. */
+    uicastEntryError = true;
     constructor(message, options) {
         super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
-        // Brand marker: with git-dep consumption two copies of core can coexist in
-        // one bundle, where `instanceof` silently fails — `EntryError.is()` checks
-        // this instead.
-        this.uicastEntryError = true;
         this.name = "EntryError";
         this.reason = options.reason;
         this.elementKey = options.elementKey;
     }
-    /** Coarse verdict for recovery flows: `document` → ask the model to re-emit; `environment` → the host's problem; `unknown` → undecidable. */
+    /** Whose code must fix it: `"document"` (the model, by re-emitting), `"environment"` (host code) or `"unknown"`. */
     get fault() {
         return FAULT_BY_REASON[this.reason];
     }
-    /** Cross-copy-safe `instanceof`. */
+    /**
+     * Whether `err` is an `EntryError`, from any copy of this package. Use it over `instanceof`.
+     *
+     * @example
+     * if (EntryError.is(err)) console.warn(err.reason, err.elementKey);
+     */
     static is(err) {
-        return (typeof err === "object" &&
-            err !== null &&
-            err.uicastEntryError === true);
+        return typeof err === "object" && err !== null && err.uicastEntryError === true;
     }
     /**
-     * Classify `err` as `reason`, keeping the original in `cause`. An error that
-     * is already an EntryError passes through untouched (the deepest — most
-     * precise — classification wins); a missing `elementKey` is filled in.
+     * Turns any thrown value into an `EntryError` with this `reason`. An `EntryError` passes through as is, and gets
+     * `elementKey` if it had none.
+     *
+     * @example
+     * const error = EntryError.wrap(err, "implementation", "orders-table");
+     * error.fault; // "environment"
      */
     static wrap(err, reason, elementKey) {
         if (EntryError.is(err)) {

package/dist/entry-shape.d.ts

@@ -0,0 +1,7 @@
+import { EntryError } from "./entry-error.js";
+import type { ComponentEntry } from "./types.js";
+type RawEntry = {
+    [K in keyof ComponentEntry]?: unknown;
+};
+export declare const entryShapeError: (entry: RawEntry) => EntryError | null;
+export {};

package/dist/entry-shape.js

@@ -0,0 +1,88 @@
+import { EntryError } from "./entry-error.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const jsonType = (value) => {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    if (typeof value === "object")
+        return "an object";
+    return `a ${typeof value}`;
+};
+const expected = (at, what, value) => `"${at}" must be ${what}, got ${jsonType(value)}.`;
+// No `expr` (or `null`) is no value, as `evaluate` reads it.
+const exprFault = (source, at) => source.expr == null || typeof source.expr === "string"
+    ? null
+    : expected(`${at}.expr`, "an expression string", source.expr);
+const stepsFault = (steps, at, setRequired) => {
+    if (!Array.isArray(steps))
+        return expected(at, "an array of steps", steps);
+    for (const [i, step] of steps.entries()) {
+        const here = `${at}[${i}]`;
+        if (!isRecord(step))
+            return expected(here, 'a step ({ "set": "…", "expr": "…" })', step);
+        if (setRequired && step.set === undefined)
+            return `"${here}" has no "set": a seed step writes one field.`;
+        if (step.set !== undefined && typeof step.set !== "string")
+            return expected(`${here}.set`, "an address string", step.set);
+        if (step.confirm !== undefined && typeof step.confirm !== "string") {
+            return expected(`${here}.confirm`, "a message string", step.confirm);
+        }
+        if (step.debounce !== undefined && typeof step.debounce !== "boolean") {
+            return expected(`${here}.debounce`, "true or false", step.debounce);
+        }
+        const fault = exprFault(step, here);
+        if (fault)
+            return fault;
+    }
+    return null;
+};
+const STRING_FIELDS = ["hidden", "loading", "each", "as", "keyBy"];
+const shapeFault = (entry) => {
+    if (entry.props !== undefined) {
+        if (!isRecord(entry.props))
+            return expected("props", '{ "expr": "…" } or { "literal": … }', entry.props);
+        const fault = exprFault(entry.props, "props");
+        if (fault)
+            return fault;
+    }
+    for (const field of STRING_FIELDS) {
+        const value = entry[field];
+        if (value !== undefined && typeof value !== "string")
+            return expected(field, "a string", value);
+    }
+    if (entry.each !== undefined && entry.as === undefined)
+        return 'A list needs "as": the name its rows are read under.';
+    if (typeof entry.as === "string" && entry.as.startsWith("$"))
+        return `"as": "${entry.as}" starts with "$", which marks a row's own scope, "scopes.$<as>".`;
+    if (entry.children !== undefined) {
+        if (!Array.isArray(entry.children))
+            return expected("children", "an array of element keys", entry.children);
+        const i = entry.children.findIndex((child) => typeof child !== "string");
+        if (i !== -1)
+            return expected(`children[${i}]`, "an element key string", entry.children[i]);
+    }
+    if (entry.seed !== undefined) {
+        const fault = stepsFault(entry.seed, "seed", true);
+        if (fault)
+            return fault;
+    }
+    if (entry.callbacks !== undefined) {
+        if (!isRecord(entry.callbacks))
+            return expected("callbacks", "an object of step arrays", entry.callbacks);
+        for (const [name, steps] of Object.entries(entry.callbacks)) {
+            const fault = stepsFault(steps, `callbacks.${name}`, false);
+            if (fault)
+                return fault;
+        }
+    }
+    return null;
+};
+// Every field but `key` and `component`. The message names the field, so a re-emit can fix it.
+export const entryShapeError = (entry) => {
+    const fault = shapeFault(entry);
+    if (!fault)
+        return null;
+    const elementKey = typeof entry.key === "string" ? entry.key : undefined;
+    return new EntryError(fault, { reason: "invalid-entry", elementKey });
+};

package/dist/expr/evaluate.d.ts

@@ -1,7 +1,5 @@
-import type { StandardToolV0 } from "standard-tool";
 import type { ValueSource } from "../types.js";
-export declare const getScopeReads: (expr: string) => string[];
-export declare const evaluate: (expr: ValueSource, context: Record<string, unknown>, options?: {
-    functions?: StandardToolV0[];
-    allowedGlobals?: string[];
-}) => unknown;
+import { EntryError } from "../entry-error.js";
+import type { ExpressionEvaluator } from "@uicast/expr";
+export declare const wrapEvalError: (err: unknown) => EntryError;
+export declare const evaluate: (expr: ValueSource, context: Record<string, unknown>, evaluator: ExpressionEvaluator) => unknown;