@uicast/core 0.0.1-beta.1

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+### Added
+
+- Initial public beta of the framework-agnostic uicast engine: entry format, sandboxed JavaScript expressions, reactive scopes, and prompt partial builders.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Gubanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+Coming soon.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@uicast/core",
+  "version": "0.0.1-beta.1",
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/finom/uicast.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/finom/uicast#readme",
+  "keywords": [
+    "generative-ui",
+    "llm",
+    "jsonlines",
+    "streaming",
+    "ui",
+    "agent",
+    "component-catalog"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./prompt": "./src/prompt/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/test/**",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "npm-publish": "if [ -z \"$NPM_TAG\" ]; then echo 'Error: NPM_TAG is not set'; exit 1; fi; npm publish --tag=$NPM_TAG"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "acorn": "^8.16.0",
+    "standard-tool": "^0.0.6"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.0",
+    "vitest": "^4.1.0",
+    "zod": "~4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/def/create-component-definition.ts

@@ -0,0 +1,21 @@
+import type { CombinedSpec, ComponentDefinition } from "../types";
+
+/**
+ * Value-side constructor for a {@link ComponentDefinition} (the type lives in
+ * `types.ts`). Infers the concrete `props` / `callbacks` specs at the call site
+ * and returns the def unchanged — its purpose is the inference + a single typed
+ * authoring shape; `createComponentImplementation` later reads those inferred
+ * types off the returned def.
+ */
+export const createComponentDefinition = <
+  TProps extends CombinedSpec,
+  TCallbacks extends Record<string, CombinedSpec> = Record<string, never>,
+>({
+  name,
+  description,
+  props,
+  callbacks,
+  hidden,
+}: ComponentDefinition<TProps, TCallbacks>): ComponentDefinition<TProps, TCallbacks> => {
+  return { name, description, props, callbacks, hidden };
+};

package/src/entry-error.ts

@@ -0,0 +1,104 @@
+// 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 });
+  }
+}

package/src/expr/analyze.ts

@@ -0,0 +1,190 @@
+import type * as acorn from "acorn";
+import { childNodes } from "./ast-utils";
+
+// Static analysis of a parsed expression (not the security check — that's
+// validate.ts). Two things the renderer needs: whether the expr is async
+// (containsAwait), and which scopes.X.Y paths it reads (extractScopeReads), so it
+// can subscribe without the LLM writing a deps array.
+
+/** Does the expression `await` anything? */
+export function containsAwait(node: acorn.AnyNode | null | undefined): boolean {
+  if (!node || typeof node !== "object") return false;
+  if (node.type === "AwaitExpression") return true;
+  for (const child of childNodes(node)) {
+    if (containsAwait(child)) return true;
+  }
+  return false;
+}
+
+// Collect every static scopes.X.Y chain the expression reads, stopping at the
+// first dynamic segment (computed key, call, non-identifier property). A method
+// call drops its last segment (rows.filter(...) depends on rows, not .filter).
+// The test file pins the trickier cases.
+
+// Read a member chain into its identifier segments (`a.b.c` -> ["a","b","c"]), or
+// null if it hits a computed / non-identifier segment.
+function collectChain(node: acorn.AnyNode | null | undefined): string[] | null {
+  const parts: string[] = [];
+  let cur: acorn.AnyNode | null | undefined = node;
+  while (cur) {
+    if (cur.type === "MemberExpression") {
+      if (cur.computed) return null;
+      const prop = cur.property;
+      if (prop.type !== "Identifier") return null;
+      parts.unshift(prop.name);
+      cur = cur.object;
+    } else if (cur.type === "Identifier") {
+      parts.unshift(cur.name);
+      return parts;
+    } else {
+      return null;
+    }
+  }
+  return null;
+}
+
+// A computed key can read scopes itself (`scopes.x[scopes.y]`), so walk the
+// computed parts of a chain too.
+function walkComputedKeysWithin(memberExpr: acorn.AnyNode, out: Set<string>): void {
+  let cur: acorn.AnyNode = memberExpr;
+  while (cur.type === "MemberExpression") {
+    if (cur.computed) {
+      walkScopeReads(cur.property, out);
+    }
+    cur = cur.object;
+  }
+}
+
+// The recursive walker behind extractScopeReads().
+function walkScopeReads(
+  node: acorn.AnyNode | null | undefined,
+  out: Set<string>,
+): void {
+  if (!node || typeof node !== "object") return;
+
+  // A method call depends on the chain, not the method name — record the chain
+  // without the method, then recurse args.
+  if (node.type === "CallExpression") {
+    const callee = node.callee;
+    if (callee.type === "MemberExpression" && !callee.computed) {
+      const chain = collectChain(callee.object);
+      if (chain && chain[0] === "scopes" && chain.length > 1) {
+        out.add(chain.join("."));
+        walkComputedKeysWithin(callee.object, out);
+      } else {
+        walkScopeReads(callee.object, out);
+      }
+    } else {
+      walkScopeReads(callee, out);
+    }
+    for (const arg of node.arguments) {
+      walkScopeReads(arg, out);
+    }
+    return;
+  }
+
+  // A plain member read: take the chain if it's rooted at `scopes`.
+  if (node.type === "MemberExpression") {
+    const chain = collectChain(node);
+    if (chain && chain[0] === "scopes" && chain.length > 1) {
+      out.add(chain.join("."));
+      walkComputedKeysWithin(node, out);
+      return;
+    }
+    // Not a scopes chain (or it hit a computed segment) — recurse for nested reads.
+    walkScopeReads(node.object, out);
+    if (node.computed) {
+      walkScopeReads(node.property, out);
+    }
+    return;
+  }
+
+  for (const child of childNodes(node)) {
+    walkScopeReads(child, out);
+  }
+}
+
+export function extractScopeReads(ast: acorn.AnyNode): string[] {
+  const out = new Set<string>();
+  walkScopeReads(ast, out);
+  return [...out];
+}
+
+// Free identifiers — names read from the outer scope (globals + injected
+// context). Anything bound by a param, destructuring, or a local declaration
+// stays internal and is not reported.
+function bindPattern(
+  node: acorn.AnyNode | null | undefined,
+  scope: Set<string>,
+): void {
+  if (!node) return;
+  if (node.type === "Identifier") {
+    scope.add(node.name);
+  } else if (node.type === "ObjectPattern") {
+    for (const p of node.properties)
+      bindPattern(p.type === "RestElement" ? p.argument : p.value, scope);
+  } else if (node.type === "ArrayPattern") {
+    for (const el of node.elements) if (el) bindPattern(el, scope);
+  } else if (node.type === "AssignmentPattern") {
+    bindPattern(node.left, scope);
+  } else if (node.type === "RestElement") {
+    bindPattern(node.argument, scope);
+  }
+}
+
+function isBound(name: string, stack: Set<string>[]): boolean {
+  for (let i = stack.length - 1; i >= 0; i--)
+    if (stack[i].has(name)) return true;
+  return false;
+}
+
+function walkFree(
+  node: acorn.AnyNode | null | undefined,
+  stack: Set<string>[],
+  out: Set<string>,
+): void {
+  if (!node || typeof node !== "object") return;
+
+  switch (node.type) {
+    case "Identifier":
+      if (!isBound(node.name, stack)) out.add(node.name);
+      return;
+    case "MemberExpression":
+      walkFree(node.object, stack, out);
+      if (node.computed) walkFree(node.property, stack, out);
+      return;
+    case "Property":
+      if (node.computed) walkFree(node.key, stack, out);
+      walkFree(node.value, stack, out);
+      return;
+    case "VariableDeclarator":
+      bindPattern(node.id, stack[stack.length - 1]);
+      walkFree(node.init, stack, out);
+      return;
+    case "ArrowFunctionExpression":
+    case "FunctionExpression": {
+      const scope = new Set<string>();
+      if (node.type === "FunctionExpression" && node.id)
+        scope.add(node.id.name);
+      for (const p of node.params) bindPattern(p, scope);
+      const inner = [...stack, scope];
+      for (const p of node.params) walkFree(p, inner, out);
+      walkFree(node.body, inner, out);
+      return;
+    }
+    case "CatchClause": {
+      const scope = new Set<string>();
+      if (node.param) bindPattern(node.param, scope);
+      walkFree(node.body, [...stack, scope], out);
+      return;
+    }
+  }
+
+  for (const child of childNodes(node)) walkFree(child, stack, out);
+}
+
+export function extractFreeIdentifiers(ast: acorn.AnyNode): string[] {
+  const out = new Set<string>();
+  walkFree(ast, [new Set()], out);
+  return [...out];
+}

package/src/expr/ast-utils.ts

@@ -0,0 +1,28 @@
+import type * as acorn from "acorn";
+
+// Low-level acorn-AST helpers shared by validate.ts and analyze.ts. NOT a parser
+// — acorn parses; these are a node type-guard and a child-traversal helper.
+
+/** Runtime guard: does `x` look like an AST node (object with a string `type`)? */
+export function isNode(x: unknown): x is acorn.AnyNode {
+  return (
+    typeof x === "object" &&
+    x !== null &&
+    typeof (x as { type?: unknown }).type === "string"
+  );
+}
+
+// Direct child nodes, flattening array-valued fields — for key-agnostic walks.
+export function childNodes(node: acorn.AnyNode): acorn.AnyNode[] {
+  const out: acorn.AnyNode[] = [];
+  for (const value of Object.values(
+    node as unknown as Record<string, unknown>,
+  )) {
+    if (Array.isArray(value)) {
+      for (const child of value) if (isNode(child)) out.push(child);
+    } else if (isNode(value)) {
+      out.push(value);
+    }
+  }
+  return out;
+}

package/src/expr/evaluate.ts

@@ -0,0 +1,74 @@
+import type { StandardToolV0 } from "standard-tool";
+import type { ValueSource } from "../types";
+import { EntryError } from "../entry-error";
+import { ALLOWED_GLOBALS } from "./globals";
+import { SaferEval, SaferEvalError } from "./safer-eval";
+
+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: string): string[] =>
+  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: unknown): EntryError => {
+  if (EntryError.is(err)) return err;
+  if (err instanceof SaferEvalError) 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: ValueSource,
+  context: Record<string, unknown>,
+  options?: { functions?: StandardToolV0[]; allowedGlobals?: string[] },
+): unknown => {
+  if ("literal" in expr) return expr.literal;
+  if (!expr.expr) return null;
+  const functions = Object.fromEntries(
+    (options?.functions ?? []).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: unknown) => {
+        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,
+      { ...context, ...functions },
+      options?.allowedGlobals,
+    );
+    return result instanceof Promise
+      ? result.catch((err) => {
+          throw wrapEvalError(err);
+        })
+      : result;
+  } catch (err) {
+    throw wrapEvalError(err);
+  }
+};

package/src/expr/extract-deps.ts

@@ -0,0 +1,32 @@
+import { type ComponentEntry, isComponentListEntry } from "../types";
+import { getScopeReads } from "./evaluate";
+
+// Entries are immutable, so cached reads never go stale; WeakMap so a dropped
+// entry can be collected.
+const cache = new WeakMap<ComponentEntry, string[]>();
+
+// 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: ComponentEntry): string[] {
+  const cached = cache.get(entry);
+  if (cached) return cached;
+
+  const out = new Set<string>();
+
+  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);
+  }
+
+  // `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);
+  }
+
+  const result = [...out];
+  cache.set(entry, result);
+  return result;
+}

package/src/expr/globals.ts

@@ -0,0 +1,118 @@
+// Which JavaScript globals an expression can see. The engine enforces an
+// allowlist (safer-eval.ts): a free identifier that is neither an allowed global
+// nor an injected context name is rejected before the expression runs.
+// ALLOWED_GLOBALS is that list — also handed to SaferEval as allowGlobals and
+// shown to the LLM in the prompt. GLOBALS_TO_SHADOW are bound to undefined as a
+// second line of defence, so an allowed-by-mistake reference still stays inert.
+
+/** Globals an expression may reference. Every entry is also usable with `new`. */
+export const ALLOWED_GLOBALS: string[] = [
+  // Namespaces / utilities
+  "Math",
+  "JSON",
+  "Intl",
+  "Object",
+  "Array",
+  // Coercion (use as calls — `new Number(x)` etc. boxes the value)
+  "Number",
+  "String",
+  "Boolean",
+  "parseInt",
+  "parseFloat",
+  // Predicates / constants
+  "isNaN",
+  "isFinite",
+  "undefined",
+  "NaN",
+  "Infinity",
+  // URI helpers
+  "encodeURIComponent",
+  "decodeURIComponent",
+  "encodeURI",
+  "decodeURI",
+  // Constructors & async
+  "Date",
+  "Map",
+  "Set",
+  "RegExp",
+  "URL",
+  "URLSearchParams",
+  "Promise",
+  "BigInt",
+  // Error constructors
+  "Error",
+  "TypeError",
+  "RangeError",
+  "SyntaxError",
+  "ReferenceError",
+  "EvalError",
+  "URIError",
+  "AggregateError",
+];
+
+// Capability globals shadowed to undefined. (`eval` / `arguments` can't be param
+// names in strict mode — blocked in validate.ts instead.)
+export const GLOBALS_TO_SHADOW: string[] = [
+  // Global objects
+  "globalThis",
+  "self",
+  "window",
+  "global",
+  "document",
+  "navigator",
+  "location",
+  "history",
+  "localStorage",
+  "sessionStorage",
+  "indexedDB",
+
+  // Network / IO
+  "fetch",
+  "XMLHttpRequest",
+  "WebSocket",
+  "EventSource",
+  "Worker",
+  "SharedWorker",
+  "ServiceWorker",
+  "importScripts",
+  // Fire a network request via `.src` — an exfiltration channel even with fetch
+  // shadowed.
+  "Image",
+  "Audio",
+
+  // Code execution
+  "Function",
+  "WebAssembly", // runs arbitrary code
+  "setTimeout",
+  "setInterval",
+  "setImmediate",
+  "requestAnimationFrame",
+  "requestIdleCallback",
+  "queueMicrotask",
+
+  // Process / non-browser runtimes
+  "process",
+  "require",
+  "module",
+  "exports",
+  "__dirname",
+  "__filename",
+  "Buffer",
+  "Deno", // runtime god-object (fs/net/env) outside a browser
+  "Bun",
+
+  // DOM
+  "alert",
+  "confirm",
+  "prompt",
+  "close",
+  "open",
+  "print",
+  "postMessage",
+
+  // Constructors that can escape
+  "Proxy",
+  "Reflect",
+  "SharedArrayBuffer",
+  "Atomics",
+];