@uicast/core 0.0.1-beta.1

package/src/prompt-utils/json-schema-to-ts.ts

@@ -0,0 +1,225 @@
+type JSONSchemaType =
+	| "object"
+	| "array"
+	| "string"
+	| "number"
+	| "boolean"
+	| "null"
+	| "integer";
+
+/**
+ * JSON Schema shape this module reads — a recursive structural type covering
+ * the draft-07 / 2020-12 keywords a Standard-Schema `toJSONSchema()` can emit
+ * (primitives, composition, objects, arrays/tuples, `$ref` + `$defs`, and the
+ * refinement keywords that constrain a value without changing its TypeScript
+ * type). Every sub-schema slot is another `JSONSchema`.
+ *
+ * `JSONSchemaToTs` still takes `unknown` and narrows at runtime, because a
+ * schema value can also be a boolean (`true`/`false`) — and, in legacy
+ * draft-07, an `items` array — which this object type intentionally doesn't
+ * model. The function reads back through itself, so the recursion stays loose.
+ */
+export interface JSONSchema {
+	$schema?:
+		| "https://json-schema.org/draft/2020-12/schema"
+		| "http://json-schema.org/draft-07/schema#";
+	type?: JSONSchemaType | JSONSchemaType[];
+	format?: string;
+	pattern?: string;
+	$ref?: string;
+	items?: boolean | JSONSchema;
+	prefixItems?: JSONSchema[];
+	additionalItems?: boolean | JSONSchema;
+	enum?: unknown[];
+	minimum?: number;
+	maximum?: number;
+	exclusiveMinimum?: number;
+	exclusiveMaximum?: number;
+	minItems?: number;
+	maxItems?: number;
+	title?: string;
+	description?: string;
+	properties?: { [key: string]: JSONSchema };
+	required?: string[];
+	examples?: unknown[];
+	not?: JSONSchema;
+	// support both $defs and definitions
+	$defs?: { [key: string]: JSONSchema };
+	definitions?: { [key: string]: JSONSchema };
+	additionalProperties?: boolean | JSONSchema;
+	anyOf?: JSONSchema[];
+	oneOf?: JSONSchema[];
+	allOf?: JSONSchema[];
+	// older schema
+	const?: unknown;
+	example?: unknown;
+	// binary
+	contentEncoding?: string;
+	contentMediaType?: string;
+	minLength?: number;
+	maxLength?: number;
+	// explicit TypeScript-type override for code generation
+	"x-tsType"?: string;
+}
+
+/**
+ * Convert a JSON Schema to a compact TypeScript type string for the prompt.
+ *
+ * Pass the whole schema document (with any `$defs` / `definitions`): local
+ * `$ref`s resolve against it, and a recursive schema terminates — the cycle's
+ * back-edge renders as `unknown` while everything above it stays fully typed.
+ */
+export function JSONSchemaToTs(jsonSchema: unknown): string {
+	return toTs(jsonSchema, jsonSchema, new Set());
+}
+
+/**
+ * Recursive worker. `root` is the document the first call was handed (the
+ * resolution base for `$ref`); `seen` is the set of refs currently being
+ * expanded on this path, so a cycle short-circuits to `unknown` instead of
+ * recursing forever.
+ */
+function toTs(jsonSchema: unknown, root: unknown, seen: Set<string>): string {
+	if (jsonSchema === true) return "unknown";
+	if (jsonSchema === false) return "never";
+	if (jsonSchema === null || jsonSchema === undefined) return "unknown";
+	if (typeof jsonSchema !== "object") return "unknown";
+	const schema = jsonSchema as JSONSchema;
+
+	if (typeof schema.$ref === "string") {
+		if (seen.has(schema.$ref)) return "unknown"; // cycle back-edge
+		const target = resolveRef(schema.$ref, root);
+		if (target === undefined) return "unknown";
+		seen.add(schema.$ref);
+		const resolved = toTs(target, root, seen);
+		seen.delete(schema.$ref);
+		return resolved;
+	}
+
+	if ("const" in schema) return JSON.stringify(schema.const);
+
+	if (schema.enum) {
+		return schema.enum.map((v) => JSON.stringify(v)).join(" | ") || "never";
+	}
+
+	if (schema.allOf) {
+		const parts = schema.allOf.map((s) => toTs(s, root, seen));
+		return parts.length ? `(${parts.join(" & ")})` : "unknown";
+	}
+	if (schema.anyOf) {
+		const parts = schema.anyOf.map((s) => toTs(s, root, seen));
+		return parts.length ? `(${parts.join(" | ")})` : "never";
+	}
+	if (schema.oneOf) {
+		const parts = schema.oneOf.map((s) => toTs(s, root, seen));
+		return parts.length ? `(${parts.join(" | ")})` : "never";
+	}
+	if (schema.not) return "unknown";
+
+	if (Array.isArray(schema.type)) {
+		const types = schema.type.map((t) =>
+			toTs({ ...schema, type: t }, root, seen),
+		);
+		return types.length ? `(${types.join(" | ")})` : "unknown";
+	}
+
+	const type = schema.type;
+
+	if (type === "string") return "string";
+	if (type === "number" || type === "integer") return "number";
+	if (type === "boolean") return "boolean";
+	if (type === "null") return "null";
+
+	if (
+		type === "object" ||
+		schema.properties ||
+		schema.additionalProperties !== undefined
+	) {
+		const props = schema.properties || {};
+		const required = schema.required || [];
+
+		const propStrings = Object.entries(props).map(([key, value]) => {
+			const isRequired = required.includes(key);
+			const safeName = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)
+				? key
+				: JSON.stringify(key);
+			return `${safeName}${isRequired ? "" : "?"}: ${toTs(value, root, seen)}`;
+		});
+
+		let additionalType: string | null = null;
+		if (schema.additionalProperties === true) {
+			additionalType = "unknown";
+		} else if (
+			schema.additionalProperties &&
+			typeof schema.additionalProperties === "object"
+		) {
+			additionalType = toTs(schema.additionalProperties, root, seen);
+		}
+
+		if (propStrings.length === 0 && additionalType) {
+			return `{ [key: string]: ${additionalType} }`;
+		}
+		if (propStrings.length === 0 && !additionalType) {
+			return schema.additionalProperties === false
+				? "{}"
+				: "{ [key: string]: unknown }";
+		}
+
+		let result = `{ ${propStrings.join("; ")} }`;
+		if (additionalType) {
+			result = `(${result} & { [key: string]: ${additionalType} })`;
+		}
+		return result;
+	}
+
+	if (type === "array" || schema.items || schema.prefixItems) {
+		if (schema.prefixItems) {
+			const tupleTypes = schema.prefixItems.map((s) => toTs(s, root, seen));
+			if (schema.items === false) return `[${tupleTypes.join(", ")}]`;
+			const restType = schema.items ? toTs(schema.items, root, seen) : "unknown";
+			return `[${tupleTypes.join(", ")}, ...${restType}[]]`;
+		}
+
+		if (schema.items !== undefined && schema.items !== null) {
+			if (Array.isArray(schema.items)) {
+				const tupleTypes = schema.items.map((s) => toTs(s, root, seen));
+				if (schema.additionalItems === false) {
+					return `[${tupleTypes.join(", ")}]`;
+				}
+				const restType = schema.additionalItems
+					? toTs(schema.additionalItems, root, seen)
+					: "unknown";
+				return `[${tupleTypes.join(", ")}, ...${restType}[]]`;
+			}
+			return `${toTs(schema.items, root, seen)}[]`;
+		}
+
+		return "unknown[]";
+	}
+
+	if (schema.properties) {
+		return toTs({ ...schema, type: "object" }, root, seen);
+	}
+
+	return "unknown";
+}
+
+/**
+ * Resolve a local JSON Pointer ref (`#/$defs/Foo`, `#/definitions/Bar`)
+ * against the document root. Returns the target sub-schema, or `undefined`
+ * for a non-local ref (`https://…`, bare `#`) or a path that doesn't exist —
+ * the caller renders those as `unknown`.
+ */
+function resolveRef(ref: string, root: unknown): unknown {
+	if (!ref.startsWith("#/")) return undefined;
+	const segments = ref
+		.slice(2)
+		.split("/")
+		.map((seg) => seg.replace(/~1/g, "/").replace(/~0/g, "~"));
+	let node: unknown = root;
+	for (const seg of segments) {
+		if (node === null || typeof node !== "object") return undefined;
+		node = (node as Record<string, unknown>)[seg];
+	}
+	return node;
+}

package/src/scope/create-proxy-scope.ts

@@ -0,0 +1,131 @@
+type EventHandler<T = unknown> = (payload: T) => void;
+
+interface ChangePayload<T = unknown> {
+  path: string;
+  value: T;
+  oldValue: T;
+}
+
+interface Emitter {
+  on<T = unknown>(type: string, handler: EventHandler<T>): () => void;
+  off<T = unknown>(type: string, handler: EventHandler<T>): void;
+  emit<T = unknown>(type: string, payload: T): void;
+}
+
+function createEmitter(): Emitter {
+  const events = new Map<string, Set<EventHandler<any>>>();
+
+  return {
+    on(type, handler) {
+      const handlers = events.get(type);
+      if (handlers) handlers.add(handler);
+      else events.set(type, new Set([handler]));
+      return () => events.get(type)?.delete(handler);
+    },
+
+    off(type, handler) {
+      events.get(type)?.delete(handler);
+    },
+
+    emit(type, payload) {
+      events.get(type)?.forEach((fn) => {
+        fn(payload);
+      });
+    },
+  };
+}
+
+type ReactiveProxy<T extends object = object> = T & {
+  $emitter: Emitter;
+  $set: (path: string, value: unknown, options?: { default?: boolean }) => void;
+};
+
+function createProxyScope<T extends object>(
+  target: T = {} as T,
+): ReactiveProxy<T> {
+  const emitter = createEmitter();
+  const proxyCache = new WeakMap<object, object>();
+
+  function set(
+    path: string,
+    value: unknown,
+    options?: { default?: boolean },
+  ): void {
+    const keys = path.split(".");
+    let current: any = 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?.default && current[lastKey] !== undefined) return;
+    current[lastKey] = value;
+  }
+
+  function wrap<U>(obj: U, path: PropertyKey[] = []): U {
+    if (obj === null || typeof obj !== "object") return obj;
+    if (proxyCache.has(obj as object))
+      return proxyCache.get(obj as object) as U;
+
+    const proxy = new Proxy(obj as object, {
+      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 as Record<PropertyKey, unknown>)[prop];
+        const result = Reflect.set(target, prop, value, receiver);
+
+        if (oldValue !== value) {
+          const fullPath = path.concat(prop).join(".");
+          emitter.emit<ChangePayload>(fullPath, {
+            path: fullPath,
+            value,
+            oldValue,
+          });
+        }
+
+        return result;
+      },
+    }) as U;
+
+    proxyCache.set(obj as object, proxy as object);
+    return proxy;
+  }
+
+  const proxy = wrap(target) as ReactiveProxy<T>;
+
+  return proxy;
+}
+
+export {
+  createProxyScope,
+  createEmitter,
+  type Emitter,
+  type ChangePayload,
+  type EventHandler,
+  type ReactiveProxy,
+};

package/src/scope/parse-scope.ts

@@ -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: 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];
+  }
+};

package/src/stream/stream-json-lines.ts

@@ -0,0 +1,56 @@
+// 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 async function* streamJsonLines<T = unknown>(
+  source: ReadableStream<Uint8Array | string> | AsyncIterable<string | Uint8Array>,
+): AsyncGenerator<T> {
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  for await (const chunk of toAsyncIterable(source)) {
+    buffer += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+
+    let nl = buffer.indexOf("\n");
+    while (nl !== -1) {
+      yield* parseLine<T>(buffer.slice(0, nl));
+      buffer = buffer.slice(nl + 1);
+      nl = buffer.indexOf("\n");
+    }
+  }
+
+  yield* parseLine<T>(buffer + decoder.decode());
+}
+
+function* parseLine<T>(raw: string): Generator<T> {
+  const line = raw.trim();
+  if (!line) return;
+  try {
+    yield JSON.parse(line) as T;
+  } catch {
+    // non-JSON noise (fences, prose, partial) — drop it
+  }
+}
+
+function toAsyncIterable(
+  source: ReadableStream<Uint8Array | string> | AsyncIterable<string | Uint8Array>,
+): AsyncIterable<string | Uint8Array> {
+  if (Symbol.asyncIterator in source) {
+    return source as AsyncIterable<string | Uint8Array>;
+  }
+  // Browser ReadableStream isn't async-iterable — pull it through a reader.
+  const stream = source as ReadableStream<Uint8Array | string>;
+  return {
+    async *[Symbol.asyncIterator]() {
+      const reader = stream.getReader();
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) return;
+          if (value !== undefined) yield value;
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,124 @@
+import type {
+  StandardJSONSchemaV1,
+  StandardSchemaV1,
+} from "@standard-schema/spec";
+
+// A bare JavaScript expression string, always evaluated as code (no literal
+// form). Used by `hidden` and `each`.
+export type Expression = string;
+
+// A dotted path into the reactive `scopes` store — the write target of an
+// assignment, e.g. `"scopes.root.users"`. Logically just a string; the alias
+// documents intent (mirrors `Expression`). Used by the `set` field below.
+export type ScopePath = string;
+
+// A value: `literal` is any JSON value used as-is (no evaluation); `expr` is
+// evaluated as code.
+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[];
+  // List fields — present only when the entry repeats (`each` is the marker).
+  // Optional here so a heterogeneous `ComponentEntry[]` can hold list lines
+  // directly; `ComponentListEntry` below is the same shape with `each`/`as`
+  // required.
+  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 function isComponentListEntry(
+  entry: ComponentEntry,
+): entry is ComponentListEntry {
+  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: unknown): value is ComponentEntry {
+  if (!value || typeof value !== "object") return false;
+  const entry = value as ComponentEntry;
+  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))
+  );
+}
+
+/**
+ * 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/src/utils/utils.ts

@@ -0,0 +1,64 @@
+import type { ComponentEntry } from "../types";
+
+/**
+ * Collect all descendant IDs of a given entry (not including the entry itself)
+ * by walking its children array recursively.
+ */
+function collectDescendantIds(
+  id: string,
+  map: Record<string, ComponentEntry>,
+): Set<string> {
+  const result = new Set<string>();
+  const stack = [id];
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    const entry = map[current];
+    if (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: ComponentEntry[],
+): Record<string, ComponentEntry> {
+  const map: Record<string, ComponentEntry> = {};
+
+  for (const line of lines) {
+    if (map[line.key]) {
+      const oldDescendants = collectDescendantIds(line.key, map);
+      const kept = new Set<string>();
+      const stack = [...(line.children ?? [])];
+      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?.children) stack.push(...entry.children);
+      }
+      for (const descId of oldDescendants) {
+        if (!kept.has(descId)) delete map[descId];
+      }
+    }
+    map[line.key] = line;
+  }
+
+  return map;
+}