@ulearning/ai-generative-frame 0.0.0-stage → 1.0.0-next.0

package/src/spec/catalog.ts

@@ -0,0 +1,196 @@
+import {
+  describeSchema,
+  toJsonSchema,
+  validateSchema,
+  type JsonSchema,
+  type SchemaIssue,
+  type StandardSchemaLike,
+} from "../json-schema";
+import { isExpression } from "./expressions";
+import { buildSpecPrompt, type SpecPromptOptions } from "./prompt";
+
+export type PropsSchema = JsonSchema | StandardSchemaLike;
+
+/** A component the model may use. Implementations are supplied per framework. */
+export type ComponentDefinition = {
+  description: string;
+  /** JSON Schema for the props, or a Standard Schema (e.g. Zod 4) that can export one. */
+  props?: PropsSchema;
+  /**
+   * Child slots. `"default"` maps to `children`; other names map to
+   * `slots.<name>`. Components without slots take no children.
+   */
+  slots?: readonly string[];
+  /** Events the component emits, which elements bind with `on`. */
+  events?: readonly string[];
+};
+
+export type ActionDefinition = {
+  description: string;
+  params?: PropsSchema;
+};
+
+export type CatalogDefinition<
+  TComponents extends Record<string, ComponentDefinition> = Record<
+    string,
+    ComponentDefinition
+  >,
+  TActions extends Record<string, ActionDefinition> = Record<
+    string,
+    ActionDefinition
+  >,
+> = {
+  components: TComponents;
+  actions?: TActions;
+};
+
+export type Catalog<
+  TComponents extends Record<string, ComponentDefinition> = Record<
+    string,
+    ComponentDefinition
+  >,
+  TActions extends Record<string, ActionDefinition> = Record<
+    string,
+    ActionDefinition
+  >,
+> = {
+  readonly components: TComponents;
+  readonly actions: TActions;
+  /** Component definition by name, or undefined. */
+  component(type: string): ComponentDefinition | undefined;
+  /** Action definition by name, including the built-in `setState`. */
+  action(name: string): ActionDefinition | undefined;
+  /** JSON Schema of a component's props, if it has one. */
+  propsSchema(type: string): JsonSchema | undefined;
+  /** Validates props, treating expression values as valid placeholders. */
+  /** JSON Schema of an action's params, if it has one. */
+  paramsSchema(action: string): JsonSchema | undefined;
+  validateProps(type: string, props: unknown): SchemaIssue[];
+  validateParams(action: string, params: unknown): SchemaIssue[];
+  /** Model guidance for this catalog: components, actions, protocol, expressions, rules. */
+  prompt(options?: SpecPromptOptions): string;
+};
+
+/** The built-in action every catalog accepts. */
+export const SET_STATE_ACTION: ActionDefinition = {
+  description: "Writes `value` at the JSON Pointer `path` in state.",
+  params: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "JSON Pointer into state" },
+      value: { description: "The value to write" },
+    },
+    required: ["path"],
+  },
+};
+
+const SEND_MESSAGE_ACTION: ActionDefinition = {
+  description: "Sends `text` as the user's next message.",
+  params: {
+    type: "object",
+    properties: { text: { type: "string", description: "The message" } },
+    required: ["text"],
+  },
+};
+
+const UPDATE_MODEL_CONTEXT_ACTION: ActionDefinition = {
+  description:
+    "Replaces what this UI tells the model about the user's choices with `text` and `data`.",
+  params: {
+    type: "object",
+    properties: {
+      text: { type: "string", description: "The choices in words" },
+      data: { description: "The choices as data" },
+    },
+  },
+};
+
+const COPY_TEXT_ACTION: ActionDefinition = {
+  description: "Copies `text` to the user's clipboard.",
+  params: {
+    type: "object",
+    properties: { text: { type: "string", description: "The text to copy" } },
+    required: ["text"],
+  },
+};
+
+/** Built-in actions every catalog accepts; a host handles `sendMessage`, `updateModelContext`, and `copyText` the way it handles its own actions. */
+const BUILT_IN_ACTIONS: Readonly<Record<string, ActionDefinition>> = {
+  setState: SET_STATE_ACTION,
+  sendMessage: SEND_MESSAGE_ACTION,
+  updateModelContext: UPDATE_MODEL_CONTEXT_ACTION,
+  copyText: COPY_TEXT_ACTION,
+};
+
+const skipExpressions = { skip: isExpression };
+
+/**
+ * Declares the components and actions a model may use in a spec. Props are
+ * JSON Schema (or a Standard Schema exposing JSON Schema), so the catalog
+ * stays dependency-free and works as model guidance and runtime validation.
+ */
+export function defineCatalog<
+  const TComponents extends Record<string, ComponentDefinition>,
+  const TActions extends Record<string, ActionDefinition> = Record<
+    never,
+    ActionDefinition
+  >,
+>(
+  definition: CatalogDefinition<TComponents, TActions>,
+): Catalog<TComponents, TActions> {
+  const components = definition.components;
+  const actions = (definition.actions ?? {}) as TActions;
+  const schemaCache = new Map<string, JsonSchema | undefined>();
+
+  const component = (type: string) =>
+    Object.hasOwn(components, type) ? components[type] : undefined;
+  for (const name of Object.keys(BUILT_IN_ACTIONS)) {
+    if (Object.hasOwn(actions, name)) {
+      throw new Error(
+        `The action name "${name}" is reserved for the built-in action.`,
+      );
+    }
+  }
+  const action = (name: string) =>
+    Object.hasOwn(BUILT_IN_ACTIONS, name)
+      ? BUILT_IN_ACTIONS[name]
+      : Object.hasOwn(actions, name)
+        ? actions[name]
+        : undefined;
+
+  const catalog: Catalog<TComponents, TActions> = {
+    components,
+    actions,
+    component,
+    action,
+    propsSchema(type) {
+      if (!schemaCache.has(type)) {
+        schemaCache.set(type, toJsonSchema(component(type)?.props));
+      }
+      return schemaCache.get(type);
+    },
+    paramsSchema(name) {
+      const key = `action:${name}`;
+      if (!schemaCache.has(key)) {
+        schemaCache.set(key, toJsonSchema(action(name)?.params));
+      }
+      return schemaCache.get(key);
+    },
+    validateProps(type, props) {
+      const schema = component(type)?.props;
+      if (!schema) return [];
+      return validateSchema(schema, props ?? {}, skipExpressions);
+    },
+    validateParams(name, params) {
+      const schema = action(name)?.params;
+      if (!schema) return [];
+      return validateSchema(schema, params ?? {}, skipExpressions);
+    },
+    prompt: (options) => buildSpecPrompt(catalog, options),
+  };
+  return catalog;
+}
+
+/** One line describing a component's props for prompts and errors. */
+export const describeProps = (catalog: Catalog, type: string) =>
+  describeSchema(catalog.propsSchema(type));

package/src/spec/expressions.ts

@@ -0,0 +1,301 @@
+import { deepEqual } from "../json-schema";
+import { evaluateFormula } from "./calc";
+import { getAtPointer, joinPointer, parsePointer } from "./pointer";
+import type { Condition } from "./types";
+
+/** What expressions can read while an element renders or an action runs. */
+export type ExpressionContext = {
+  state: unknown;
+  /** The current item and index inside a `repeat`. */
+  item?: unknown;
+  index?: number;
+  /** The state path of the current item, so `$bindItem` can write back. */
+  itemPath?: string;
+  /** The payload an event was emitted with, for action params. */
+  event?: unknown;
+};
+
+const SOURCE_KEYS = [
+  "$state",
+  "$bindState",
+  "$item",
+  "$bindItem",
+  "$index",
+  "$event",
+] as const;
+const EXPRESSION_KEYS = new Set<string>([
+  ...SOURCE_KEYS,
+  "$cond",
+  "$calc",
+  "$template",
+]);
+const COMPARATORS = ["eq", "neq", "gt", "gte", "lt", "lte"] as const;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** True for `{ $state }`, `{ $bindState }`, `{ $item }`, `{ $bindItem }`, `{ $index }`, `{ $event }`, `{ $cond }`, `{ $calc }`, and `{ $template }`. */
+export const isExpression = (
+  value: unknown,
+): value is Record<string, unknown> =>
+  isRecord(value) && Object.keys(value).some((key) => EXPRESSION_KEYS.has(key));
+
+/** True for a string that is only an expression key, such as `"$calc"`. */
+export const isExpressionKey = (value: string) =>
+  EXPRESSION_KEYS.has(value.trim());
+
+const readPath = (base: unknown, path: unknown) =>
+  typeof path === "string" && path !== ""
+    ? getAtPointer(base, safeTokens(path))
+    : base;
+
+const safeTokens = (path: string) => {
+  try {
+    return parsePointer(path.startsWith("/") ? path : `/${path}`);
+  } catch {
+    return [];
+  }
+};
+
+const readSource = (
+  expression: Record<string, unknown>,
+  ctx: ExpressionContext,
+) => {
+  if ("$state" in expression) return readPath(ctx.state, expression["$state"]);
+  if ("$bindState" in expression)
+    return readPath(ctx.state, expression["$bindState"]);
+  if ("$item" in expression) return readPath(ctx.item, expression["$item"]);
+  if ("$bindItem" in expression)
+    return readPath(ctx.item, expression["$bindItem"]);
+  if ("$index" in expression) return ctx.index;
+  if ("$event" in expression) return readPath(ctx.event, expression["$event"]);
+  return undefined;
+};
+
+const formatTemplateValue = (value: unknown) =>
+  value === undefined || value === null
+    ? ""
+    : typeof value === "object"
+      ? JSON.stringify(value)
+      : String(value);
+
+/**
+ * Fills `${/path}` (state), `${$item/path}`, `${$item}`, and `${$index}`
+ * placeholders in a `$template` string.
+ */
+export function renderTemplate(
+  template: string,
+  ctx: ExpressionContext,
+): string {
+  const fill = (ref: string) => {
+    if (ref === "$index") return formatTemplateValue(ctx.index);
+    if (ref === "$item") return formatTemplateValue(ctx.item);
+    if (ref.startsWith("$item/")) {
+      return formatTemplateValue(readPath(ctx.item, ref.slice(5)));
+    }
+    return formatTemplateValue(readPath(ctx.state, ref));
+  };
+  let out = "";
+  let from = 0;
+  for (const { start, end, ref } of placeholders(template)) {
+    out += template.slice(from, start) + fill(ref);
+    from = end + 1;
+  }
+  return out + template.slice(from);
+}
+
+function* placeholders(template: string) {
+  let from = 0;
+  for (;;) {
+    const start = template.indexOf("${", from);
+    if (start === -1) return;
+    const end = template.indexOf("}", start + 2);
+    if (end === -1) return;
+    yield { start, end, ref: template.slice(start + 2, end).trim() };
+    from = end + 1;
+  }
+}
+
+/** The state paths a `$template` string's placeholders read. */
+export const templateStatePaths = (template: string): string[] =>
+  [...placeholders(template)]
+    .map(({ ref }) => ref)
+    .filter((ref) => !ref.startsWith("$"));
+
+/** Resolves expressions anywhere inside a value; plain values pass through. */
+export function resolveValue(value: unknown, ctx: ExpressionContext): unknown {
+  if (Array.isArray(value)) return value.map((item) => resolveValue(item, ctx));
+  if (!isRecord(value)) return value;
+  if ("$cond" in value) {
+    return evaluateCondition(value["$cond"] as Condition, ctx)
+      ? resolveValue(value["$then"], ctx)
+      : resolveValue(value["$else"], ctx);
+  }
+  if ("$calc" in value) {
+    return typeof value["$calc"] === "string"
+      ? evaluateFormula(value["$calc"], ctx)
+      : null;
+  }
+  if ("$template" in value) {
+    return typeof value["$template"] === "string"
+      ? renderTemplate(value["$template"], ctx)
+      : "";
+  }
+  if (SOURCE_KEYS.some((key) => key in value)) return readSource(value, ctx);
+  const result: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value)) {
+    result[key] = resolveValue(child, ctx);
+  }
+  return result;
+}
+
+const compare = (
+  left: unknown,
+  operator: (typeof COMPARATORS)[number],
+  right: unknown,
+) => {
+  switch (operator) {
+    case "eq":
+      return deepEqual(left, right);
+    case "neq":
+      return !deepEqual(left, right);
+    default: {
+      if (
+        !(typeof left === "number" && typeof right === "number") &&
+        !(typeof left === "string" && typeof right === "string")
+      ) {
+        return false;
+      }
+      if (operator === "gt") return left > right;
+      if (operator === "gte") return left >= right;
+      if (operator === "lt") return left < right;
+      return left <= right;
+    }
+  }
+};
+
+/** The state paths a condition only holds true while they have a value: a `$state` it tests for truthiness or with any comparator but `neq` alone, in every part of `$and` or a list. */
+export function conditionGuards(condition: unknown): string[] {
+  if (Array.isArray(condition)) return condition.flatMap(conditionGuards);
+  if (!isRecord(condition)) return [];
+  if (Array.isArray(condition["$and"]))
+    return conditionGuards(condition["$and"]);
+  if (typeof condition["$state"] !== "string" || condition["not"] === true)
+    return [];
+  const comparators = COMPARATORS.filter((operator) => operator in condition);
+  return comparators.length === 0 ||
+    comparators.some((operator) => operator !== "neq")
+    ? [condition["$state"]]
+    : [];
+}
+
+/**
+ * Evaluates a visibility condition. Unknown shapes are false, so a
+ * half-streamed condition hides its element rather than throwing.
+ */
+export function evaluateCondition(
+  condition: Condition | undefined,
+  ctx: ExpressionContext,
+): boolean {
+  return evaluateConditionValue(condition, ctx) ?? false;
+}
+
+function evaluateConditionValue(
+  condition: Condition | undefined,
+  ctx: ExpressionContext,
+): boolean | undefined {
+  if (condition === undefined) return true;
+  if (typeof condition === "boolean") return condition;
+  if (Array.isArray(condition)) {
+    let result: boolean | undefined = true;
+    for (const part of condition) {
+      const value = evaluateConditionValue(part as Condition, ctx);
+      if (value === false) return false;
+      if (value === undefined) result = undefined;
+    }
+    return result;
+  }
+  if (!isRecord(condition)) return Boolean(condition);
+  if (Array.isArray(condition["$and"])) {
+    return evaluateConditionValue(condition["$and"] as Condition[], ctx);
+  }
+  if (Array.isArray(condition["$or"])) {
+    let result: boolean | undefined = false;
+    for (const part of condition["$or"] as Condition[]) {
+      const value = evaluateConditionValue(part, ctx);
+      if (value === true) return true;
+      if (value === undefined) result = undefined;
+    }
+    return result;
+  }
+  const hasSource = SOURCE_KEYS.some((key) => key in condition);
+  if (!hasSource && "not" in condition) {
+    const value = evaluateConditionValue(condition["not"] as Condition, ctx);
+    return value === undefined ? undefined : !value;
+  }
+  if (!hasSource) {
+    if (!isExpression(condition)) return undefined;
+    let expression: unknown = condition;
+    while (isRecord(expression) && "$cond" in expression) {
+      const matches = evaluateConditionValue(
+        expression["$cond"] as Condition,
+        ctx,
+      );
+      if (matches === undefined) return undefined;
+      expression = expression[matches ? "$then" : "$else"];
+    }
+    return Boolean(resolveValue(expression, ctx));
+  }
+
+  const value = readSource(condition, ctx);
+  let result = true;
+  let compared = false;
+  for (const operator of COMPARATORS) {
+    if (!(operator in condition)) continue;
+    compared = true;
+    result &&= compare(value, operator, resolveValue(condition[operator], ctx));
+  }
+  if (!compared) result = Boolean(value);
+  return condition["not"] === true ? !result : result;
+}
+
+/** Resolved props plus the state path behind each two-way bound prop. */
+export type ResolvedProps = {
+  props: Record<string, unknown>;
+  bindings: Record<string, string>;
+};
+
+const normalizePath = (path: string) =>
+  path === "" || path.startsWith("/") ? path : `/${path}`;
+
+/**
+ * Resolves an element's props. Top-level `$bindState` and `$bindItem` props
+ * are also reported in `bindings`, so the component can write the value back.
+ */
+export function resolveProps(
+  props: Record<string, unknown> | undefined,
+  ctx: ExpressionContext,
+): ResolvedProps {
+  const resolved: Record<string, unknown> = {};
+  const bindings: Record<string, string> = {};
+  for (const [key, value] of Object.entries(props ?? {})) {
+    if (isRecord(value) && typeof value["$bindState"] === "string") {
+      bindings[key] = normalizePath(value["$bindState"]);
+    } else if (
+      isRecord(value) &&
+      typeof value["$bindItem"] === "string" &&
+      ctx.itemPath !== undefined
+    ) {
+      const field = value["$bindItem"];
+      bindings[key] = field
+        ? `${ctx.itemPath}${normalizePath(field)}`
+        : ctx.itemPath;
+    }
+    resolved[key] = resolveValue(value, ctx);
+  }
+  return { props: resolved, bindings };
+}
+
+/** The state path of item `index` in the array at `path`. */
+export const itemPointer = (path: string, index: number) =>
+  `${path === "" ? "" : normalizePath(path)}${joinPointer([index])}`;

package/src/spec/patch.ts

@@ -0,0 +1,112 @@
+import { deepEqual } from "../json-schema";
+import {
+  getAtPointer,
+  parsePointer,
+  writeAtPointer,
+  type WriteOptions,
+} from "./pointer";
+import type { PatchOperation } from "./types";
+
+const OPS = new Set(["add", "replace", "remove", "move", "copy", "test"]);
+
+/** Narrows an unknown value to a patch operation, or explains why it is not one. */
+export function checkPatchOperation(
+  value: unknown,
+): { ok: true; op: PatchOperation } | { ok: false; error: string } {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { ok: false, error: "a patch operation must be a JSON object" };
+  }
+  const op = value as Record<string, unknown>;
+  if (typeof op["op"] !== "string" || !OPS.has(op["op"])) {
+    return {
+      ok: false,
+      error: `"op" must be one of ${[...OPS].join(", ")}`,
+    };
+  }
+  if (typeof op["path"] !== "string") {
+    return { ok: false, error: '"path" must be a string' };
+  }
+  if (
+    (op["op"] === "move" || op["op"] === "copy") &&
+    typeof op["from"] !== "string"
+  ) {
+    return { ok: false, error: `"${op["op"]}" needs a string "from"` };
+  }
+  if (
+    (op["op"] === "add" || op["op"] === "replace" || op["op"] === "test") &&
+    !("value" in op)
+  ) {
+    return { ok: false, error: `"${op["op"]}" needs a "value"` };
+  }
+  return { ok: true, op: op as PatchOperation };
+}
+
+const clone = <T>(value: T): T =>
+  value === undefined ? value : (JSON.parse(JSON.stringify(value)) as T);
+
+/**
+ * Applies one RFC 6902 operation and returns the new document; the input is
+ * not mutated and unchanged branches are shared. Throws when the operation
+ * cannot apply. With `createMissing`, `add` and `replace` create missing
+ * parent objects, which streaming relies on for paths like `/state/a/b`.
+ */
+export function applyPatchOperation<T>(
+  doc: T,
+  operation: PatchOperation,
+  options: WriteOptions = {},
+): T {
+  const path = parsePointer(operation.path);
+  switch (operation.op) {
+    case "add":
+      return writeAtPointer(doc, path, "add", operation.value, options) as T;
+    case "replace":
+      return writeAtPointer(
+        doc,
+        path,
+        "replace",
+        operation.value,
+        options,
+      ) as T;
+    case "remove":
+      return writeAtPointer(doc, path, "remove") as T;
+    case "move": {
+      const from = parsePointer(operation.from);
+      if (
+        from.length < path.length &&
+        from.every((token, index) => path[index] === token)
+      ) {
+        throw new Error("Cannot move a value into one of its own children");
+      }
+      const value = getAtPointer(doc, from);
+      if (value === undefined) {
+        throw new Error(`Nothing to move at "${operation.from}"`);
+      }
+      const removed = writeAtPointer(doc, from, "remove");
+      return writeAtPointer(removed, path, "add", value, options) as T;
+    }
+    case "copy": {
+      const value = getAtPointer(doc, operation.from);
+      if (value === undefined) {
+        throw new Error(`Nothing to copy at "${operation.from}"`);
+      }
+      return writeAtPointer(doc, path, "add", clone(value), options) as T;
+    }
+    case "test":
+      if (!deepEqual(getAtPointer(doc, path), operation.value)) {
+        throw new Error(`Test failed at "${operation.path}"`);
+      }
+      return doc;
+  }
+}
+
+/** Applies operations in order; throws on the first one that fails. */
+export function applyPatch<T>(
+  doc: T,
+  operations: readonly PatchOperation[],
+  options: WriteOptions = {},
+): T {
+  return operations.reduce(
+    (current, operation) => applyPatchOperation(current, operation, options),
+    doc,
+  );
+}

package/src/spec/pending.ts

@@ -0,0 +1,36 @@
+const DOT_FRAMES = [{ opacity: 0.2 }, { opacity: 0.8 }, { opacity: 0.2 }];
+
+export const PENDING_STYLE = {
+  display: "inline-flex",
+  gap: "4px",
+  padding: "6px 2px",
+} as const;
+
+export const PENDING_DOT_STYLE = {
+  width: "5px",
+  height: "5px",
+  borderRadius: "50%",
+  background: "currentColor",
+  opacity: 0.2,
+} as const;
+
+/** Pulses the pending indicator's dots in turn, and leaves them still under reduced motion; returns the cleanup. */
+export function animatePendingDots(host: Element): () => void {
+  if (globalThis.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches) {
+    return () => {};
+  }
+  const animations = Array.from(host.children).flatMap((dot, index) =>
+    typeof dot.animate === "function"
+      ? [
+          dot.animate(DOT_FRAMES, {
+            duration: 1200,
+            delay: index * 150,
+            iterations: Infinity,
+          }),
+        ]
+      : [],
+  );
+  return () => {
+    for (const animation of animations) animation.cancel();
+  };
+}