@uicast/core 0.0.1-beta.1 → 0.0.1-beta.2

package/dist/scope/create-proxy-scope.js

@@ -0,0 +1,101 @@
+function createEmitter() {
+    const events = new Map();
+    return {
+        on(type, handler) {
+            const handlers = events.get(type);
+            if (handlers)
+                handlers.add(handler);
+            else
+                events.set(type, new Set([handler]));
+            return () => { var _a; return (_a = events.get(type)) === null || _a === void 0 ? void 0 : _a.delete(handler); };
+        },
+        off(type, handler) {
+            var _a;
+            (_a = events.get(type)) === null || _a === void 0 ? void 0 : _a.delete(handler);
+        },
+        emit(type, payload) {
+            var _a;
+            (_a = events.get(type)) === null || _a === void 0 ? void 0 : _a.forEach((fn) => {
+                fn(payload);
+            });
+            // Writing a path replaces everything beneath it, so subscribers of
+            // deeper paths must wake too: a write to `products` wakes a reader of
+            // `products.length`. The reverse direction stays exact — a write to
+            // `rows.0.name` does not wake a reader of `rows`.
+            const prefix = `${type}.`;
+            for (const [key, handlers] of events) {
+                if (key.startsWith(prefix)) {
+                    handlers.forEach((fn) => {
+                        fn(payload);
+                    });
+                }
+            }
+        },
+    };
+}
+function createProxyScope(target = {}) {
+    const emitter = createEmitter();
+    const proxyCache = new WeakMap();
+    function set(path, value, options) {
+        const keys = path.split(".");
+        let current = proxy;
+        for (let i = 0; i < keys.length - 1; i++) {
+            const key = keys[i];
+            if (current[key] === undefined || current[key] === null) {
+                current[key] = {};
+            }
+            current = current[key];
+        }
+        const lastKey = keys[keys.length - 1];
+        // `default: true` → init-if-absent (first-writer-wins); never clobber an
+        // existing value. Used by `seed` so two components seeding the same
+        // path don't overwrite each other, and user edits survive remounts.
+        if ((options === null || options === void 0 ? void 0 : options.default) && current[lastKey] !== undefined)
+            return;
+        current[lastKey] = value;
+    }
+    function wrap(obj, path = []) {
+        if (obj === null || typeof obj !== "object")
+            return obj;
+        if (proxyCache.has(obj))
+            return proxyCache.get(obj);
+        const proxy = new Proxy(obj, {
+            get(target, prop, receiver) {
+                if (path.length === 0) {
+                    if (prop === "$emitter")
+                        return emitter;
+                    if (prop === "$set")
+                        return set;
+                }
+                const value = Reflect.get(target, prop, receiver);
+                // Proxy invariant: for non-configurable, non-writable properties
+                // the trap MUST return the exact target value.
+                if (value !== null && typeof value === "object") {
+                    const desc = Object.getOwnPropertyDescriptor(target, prop);
+                    if (desc && !desc.configurable && !desc.writable) {
+                        return value;
+                    }
+                }
+                return wrap(value, path.concat(prop));
+            },
+            set(target, prop, value, receiver) {
+                const oldValue = target[prop];
+                const result = Reflect.set(target, prop, value, receiver);
+                if (oldValue !== value) {
+                    const fullPath = path.concat(prop).join(".");
+                    emitter.emit(fullPath, {
+                        path: fullPath,
+                        value,
+                        oldValue,
+                    });
+                }
+                return result;
+            },
+        });
+        proxyCache.set(obj, proxy);
+        return proxy;
+    }
+    const proxy = wrap(target);
+    return proxy;
+}
+export { createProxyScope, createEmitter, };

package/{src/scope/parse-scope.ts → dist/scope/parse-scope.d.ts}

@@ -17,20 +17,4 @@
  * produces `scopes.X.Y` read strings, and the renderer hands each to
  * `parseScope(...)` to route an `$emitter.on(targetPath, …)` subscription.
  */
-export const parseScope = (key: string, prefix = "scopes") => {
-  // Strip the "<prefix>." namespace token if present.
-  const scopesPrefix = `${prefix}.`;
-  const normalizedKey = key.startsWith(scopesPrefix)
-    ? key.slice(scopesPrefix.length)
-    : key;
-
-  const dotIndex = normalizedKey.indexOf(".");
-  if (dotIndex === -1) {
-    throw new Error(`Invalid scope key: ${key}`);
-  } else {
-    return [
-      normalizedKey.slice(0, dotIndex),
-      normalizedKey.slice(dotIndex + 1),
-    ] as [string, string];
-  }
-};
+export declare const parseScope: (key: string, prefix?: string) => [string, string];

package/dist/scope/parse-scope.js

@@ -0,0 +1,36 @@
+/**
+ * Split a scope key into `[scopeName, leafPath]`.
+ *
+ * Strips the leading namespace token (default `"scopes"`) if present, then
+ * splits on the first dot: the head is the named scope, the tail is the path
+ * *within* that scope.
+ *
+ *   parseScope("scopes.root.user.name")  → ["root", "user.name"]
+ *   parseScope("root.count")             → ["root", "count"]   (prefix optional)
+ *
+ * `prefix` (default `"scopes"`) is the leading namespace identifier the dotted
+ * key is written against; it builds the `scopesPrefix` (`prefix + "."`) that
+ * gets stripped. Pass a different value when keys are written against another
+ * root identifier.
+ *
+ * This is the scope-layer counterpart to `createProxyScope`: `extractDeps`
+ * produces `scopes.X.Y` read strings, and the renderer hands each to
+ * `parseScope(...)` to route an `$emitter.on(targetPath, …)` subscription.
+ */
+export const parseScope = (key, prefix = "scopes") => {
+    // Strip the "<prefix>." namespace token if present.
+    const scopesPrefix = `${prefix}.`;
+    const normalizedKey = key.startsWith(scopesPrefix)
+        ? key.slice(scopesPrefix.length)
+        : key;
+    const dotIndex = normalizedKey.indexOf(".");
+    if (dotIndex === -1) {
+        throw new Error(`Invalid scope key: ${key}`);
+    }
+    else {
+        return [
+            normalizedKey.slice(0, dotIndex),
+            normalizedKey.slice(dotIndex + 1),
+        ];
+    }
+};

package/dist/stream/stream-json-lines.d.ts

@@ -0,0 +1 @@
+export declare function streamJsonLines<T = unknown>(source: ReadableStream<Uint8Array | string> | AsyncIterable<string | Uint8Array>): AsyncGenerator<T>;

package/dist/stream/stream-json-lines.js

@@ -0,0 +1,94 @@
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncDelegator = (this && this.__asyncDelegator) || function (o) {
+    var i, p;
+    return i = {}, verb("next"), verb("throw", function (e) { throw e; }), verb("return"), i[Symbol.iterator] = function () { return this; }, i;
+    function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: false } : f ? f(v) : v; } : f; }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+// Yields every parseable JSON value from a byte or string stream, skipping
+// blank/non-JSON lines (code fences, model prose, partial lines). Narrow the
+// element type via <T>; shape-checking is the caller's concern.
+export function streamJsonLines(source) {
+    return __asyncGenerator(this, arguments, function* streamJsonLines_1() {
+        var _a, e_1, _b, _c;
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            for (var _d = true, _e = __asyncValues(toAsyncIterable(source)), _f; _f = yield __await(_e.next()), _a = _f.done, !_a; _d = true) {
+                _c = _f.value;
+                _d = false;
+                const chunk = _c;
+                buffer += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+                let nl = buffer.indexOf("\n");
+                while (nl !== -1) {
+                    yield __await(yield* __asyncDelegator(__asyncValues(parseLine(buffer.slice(0, nl)))));
+                    buffer = buffer.slice(nl + 1);
+                    nl = buffer.indexOf("\n");
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (!_d && !_a && (_b = _e.return)) yield __await(_b.call(_e));
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        yield __await(yield* __asyncDelegator(__asyncValues(parseLine(buffer + decoder.decode()))));
+    });
+}
+function* parseLine(raw) {
+    const line = raw.trim();
+    if (!line)
+        return;
+    try {
+        yield JSON.parse(line);
+    }
+    catch (_a) {
+        // non-JSON noise (fences, prose, partial) — drop it
+    }
+}
+function toAsyncIterable(source) {
+    if (Symbol.asyncIterator in source) {
+        return source;
+    }
+    // Browser ReadableStream isn't async-iterable — pull it through a reader.
+    const stream = source;
+    return {
+        [Symbol.asyncIterator]() {
+            return __asyncGenerator(this, arguments, function* _a() {
+                const reader = stream.getReader();
+                try {
+                    for (;;) {
+                        const { done, value } = yield __await(reader.read());
+                        if (done)
+                            return yield __await(void 0);
+                        if (value !== undefined)
+                            yield yield __await(value);
+                    }
+                }
+                finally {
+                    reader.releaseLock();
+                }
+            });
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,89 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
+export type Expression = string;
+export type ScopePath = string;
+export type ValueSource = {
+    expr: Expression;
+} | {
+    literal: unknown;
+};
+export type ValueSourceAssignment = {
+    set: ScopePath;
+} & ValueSource;
+export type ConfirmableValueSourceAssignment = {
+    confirm?: string;
+} & ValueSourceAssignment;
+/**
+ * The uicast entry model. One line of a uicast document is a
+ * `ComponentEntry`. A `ComponentListEntry` is an entry that repeats: it carries
+ * `each` (the array to iterate) plus `as` and an optional `keyBy`.
+ *
+ * There is no separate "plain entry" type and no
+ * `ComponentEntry | ComponentListEntry` union: the list fields (`each`, `as`,
+ * `keyBy`) live on `ComponentEntry` as optional, so one type describes every
+ * line and a heterogeneous `ComponentEntry[]` can hold list lines directly.
+ * `ComponentListEntry` is the same shape with `each`/`as` required — narrow
+ * `ComponentEntry` → `ComponentListEntry` with `isComponentListEntry` (presence
+ * of `each`).
+ */
+export interface ComponentEntry {
+    key: string;
+    component: string;
+    props?: ValueSource;
+    seed?: ValueSourceAssignment[];
+    hidden?: Expression;
+    callbacks?: Record<string, ConfirmableValueSourceAssignment[]>;
+    children?: string[];
+    each?: Expression;
+    as?: string;
+    keyBy?: (string & {}) | "_index" | "_item";
+}
+/**
+ * A list entry repeats — the same shape as `ComponentEntry` with the iteration
+ * fields required. `each` is the structural marker (its presence is what makes
+ * an entry a list); `as` names the per-item scope.
+ */
+export interface ComponentListEntry extends ComponentEntry {
+    each: Expression;
+    as: string;
+}
+/**
+ * Narrow a `ComponentEntry` to a `ComponentListEntry`. List-ness is the
+ * presence of `each` — there is no `kind` discriminator, exactly like root-ness
+ * (derived from an entry being referenced by no other entry's `children`).
+ */
+export declare function isComponentListEntry(entry: ComponentEntry): entry is ComponentListEntry;
+/**
+ * Narrow an untrusted parsed value to a `ComponentEntry` — the shape guard for
+ * model-emitted lines (`streamJsonLines` output, fence bodies, stored JSONL).
+ */
+export declare function isComponentEntry(value: unknown): value is ComponentEntry;
+/**
+ * An interface that combines StandardJSONSchema and StandardSchema.
+ * */
+export type CombinedSpec<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output> & StandardJSONSchemaV1<Input, Output>;
+/**
+ * The partner module the LLM reads for a component: a props spec plus optional
+ * callback specs (its `description` + `props` schema are serialized into the
+ * prompt). Parameterized over the concrete `props` / `callbacks` specs so an
+ * implementation can recover their exact types — `createComponentImplementation`
+ * infers `TProps` / `TCallbacks` straight off the `def` it's handed to type its
+ * `render` callback. Both params default to the widened base, so a bare
+ * `ComponentDefinition` is the heterogeneous form used in collections
+ * (`ComponentDefinition[]`, the `allDefinitions` registry, the prompt
+ * serializer). The `createComponentDefinition` factory (in
+ * `def/create-component-definition.ts`) is the value-side constructor for this.
+ */
+export type ComponentDefinition<TProps extends CombinedSpec = CombinedSpec, TCallbacks extends Record<string, CombinedSpec> = Record<string, CombinedSpec>> = {
+    name: string;
+    description: string;
+    props: TProps;
+    callbacks?: TCallbacks;
+    /**
+     * Host-only component. Registered in the renderer registry so entries
+     * referencing it mount correctly, but filtered out of the LLM-facing
+     * prompt list in `getComponentsPartialPrompt`. Use for internal infrastructure
+     * (e.g. RootFragment — the synthetic wrapper used by `Renderer`'s `init`
+     * prop machinery) that the LLM should never emit.
+     */
+    hidden?: boolean;
+};

package/dist/types.js

@@ -0,0 +1,22 @@
+/**
+ * Narrow a `ComponentEntry` to a `ComponentListEntry`. List-ness is the
+ * presence of `each` — there is no `kind` discriminator, exactly like root-ness
+ * (derived from an entry being referenced by no other entry's `children`).
+ */
+export function isComponentListEntry(entry) {
+    return entry.each !== undefined;
+}
+/**
+ * Narrow an untrusted parsed value to a `ComponentEntry` — the shape guard for
+ * model-emitted lines (`streamJsonLines` output, fence bodies, stored JSONL).
+ */
+export function isComponentEntry(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const entry = value;
+    return (typeof entry.key === "string" &&
+        typeof entry.component === "string" &&
+        // The least-trusted input path: `children` as a string (a plausible LLM
+        // slip) would be iterated char-by-char downstream into phantom child slots.
+        (entry.children === undefined || Array.isArray(entry.children)));
+}

package/dist/utils/utils.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentEntry } from "../types.js";
+/**
+ * Build an elements-by-key map from the NDJSON lines array.
+ *
+ * When an entry with a duplicate key is encountered (i.e. the LLM re-emits a
+ * entry to correct a mistake), the old subtree is removed before inserting
+ * the replacement — except old nodes the new `children` array still
+ * references (directly or through a kept child), which survive with their
+ * own subtrees. This lets the LLM restructure a parent by re-emitting just
+ * that entry, keeping existing children by reference, without regenerating
+ * the entire tree.
+ */
+export declare function buildElementsById(lines: ComponentEntry[]): Record<string, ComponentEntry>;

package/dist/utils/utils.js

@@ -0,0 +1,58 @@
+/**
+ * Collect all descendant IDs of a given entry (not including the entry itself)
+ * by walking its children array recursively.
+ */
+function collectDescendantIds(id, map) {
+    const result = new Set();
+    const stack = [id];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        const entry = map[current];
+        if (entry === null || entry === void 0 ? void 0 : entry.children) {
+            for (const childId of entry.children) {
+                if (!result.has(childId)) {
+                    result.add(childId);
+                    stack.push(childId);
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Build an elements-by-key map from the NDJSON lines array.
+ *
+ * When an entry with a duplicate key is encountered (i.e. the LLM re-emits a
+ * entry to correct a mistake), the old subtree is removed before inserting
+ * the replacement — except old nodes the new `children` array still
+ * references (directly or through a kept child), which survive with their
+ * own subtrees. This lets the LLM restructure a parent by re-emitting just
+ * that entry, keeping existing children by reference, without regenerating
+ * the entire tree.
+ */
+export function buildElementsById(lines) {
+    var _a;
+    const map = {};
+    for (const line of lines) {
+        if (map[line.key]) {
+            const oldDescendants = collectDescendantIds(line.key, map);
+            const kept = new Set();
+            const stack = [...((_a = line.children) !== null && _a !== void 0 ? _a : [])];
+            while (stack.length > 0) {
+                const id = stack.pop();
+                if (kept.has(id) || !oldDescendants.has(id))
+                    continue;
+                kept.add(id);
+                const entry = map[id];
+                if (entry === null || entry === void 0 ? void 0 : entry.children)
+                    stack.push(...entry.children);
+            }
+            for (const descId of oldDescendants) {
+                if (!kept.has(descId))
+                    delete map[descId];
+            }
+        }
+        map[line.key] = line;
+    }
+    return map;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uicast/core",
-  "version": "0.0.1-beta.1",
+  "version": "0.0.1-beta.2",
   "description": "LLM-generated UIs from a stream of JSONLines — the framework-agnostic uicast engine: entry format, sandboxed expressions, reactive scopes, and prompt builders.",
   "license": "MIT",
   "repository": {
@@ -20,16 +20,23 @@
   ],
   "type": "module",
   "exports": {
-    ".": "./src/index.ts",
-    "./prompt": "./src/prompt/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./prompt": {
+      "types": "./dist/prompt/index.d.ts",
+      "default": "./dist/prompt/index.js"
+    }
   },
   "files": [
-    "src",
-    "!src/**/test/**",
+    "dist",
     "LICENSE",
     "CHANGELOG.md"
   ],
   "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -39,7 +46,7 @@
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
     "acorn": "^8.16.0",
-    "standard-tool": "^0.0.6"
+    "standard-tool": "^0.1.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.0",

package/src/entry-error.ts

@@ -1,104 +0,0 @@
-// 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.
-
-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";
-
-export type EntryFault = "document" | "environment" | "unknown";
-
-// 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: Record<EntryErrorReason, EntryFault> = {
-  "expression-syntax": "document",
-  "sandbox-violation": "document",
-  "unknown-reference": "document",
-  "unknown-component": "document",
-  "invalid-list": "document",
-  "invalid-props": "document",
-  "invalid-arguments": "document",
-  "host-function": "environment",
-  "host-init": "environment",
-  implementation: "environment",
-  "expression-runtime": "unknown",
-  unknown: "unknown",
-};
-
-export class EntryError extends Error {
-  readonly reason: EntryErrorReason;
-  /** The element the failure belongs to; the error boundary fills it in when the throw site couldn't. */
-  elementKey?: string;
-  // Brand marker: with git-dep consumption two copies of core can coexist in
-  // one bundle, where `instanceof` silently fails — `EntryError.is()` checks
-  // this instead.
-  readonly uicastEntryError = true;
-
-  constructor(
-    message: string,
-    options: { reason: EntryErrorReason; elementKey?: string; cause?: unknown },
-  ) {
-    super(
-      message,
-      options.cause !== undefined ? { cause: options.cause } : undefined,
-    );
-    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. */
-  get fault(): EntryFault {
-    return FAULT_BY_REASON[this.reason];
-  }
-
-  /** Cross-copy-safe `instanceof`. */
-  static is(err: unknown): err is EntryError {
-    return (
-      typeof err === "object" &&
-      err !== null &&
-      (err as { uicastEntryError?: unknown }).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.
-   */
-  static wrap(
-    err: unknown,
-    reason: EntryErrorReason,
-    elementKey?: string,
-  ): EntryError {
-    if (EntryError.is(err)) {
-      if (elementKey && !err.elementKey) err.elementKey = elementKey;
-      return err;
-    }
-    const message = err instanceof Error ? err.message : String(err);
-    return new EntryError(message, { reason, elementKey, cause: err });
-  }
-}