@assistant-ui/react-generative-ui 0.0.23 → 0.1.0

package/src/convert/boundSpec.ts

@@ -1,134 +0,0 @@
-import { copyBounded } from "./copyBounded";
-
-/** The maximum traversal depth, counted in visited values, not tree levels. */
-export const MAX_TRAVERSAL_DEPTH = 64;
-
-/**
- * The element-nesting ceiling a caller observes. `boundNode` visits an element
- * and its `children` array separately, so one level of nesting spends two of
- * {@link MAX_TRAVERSAL_DEPTH}; it runs before the conversion walk and is never
- * the looser of the two. A root array costs one more level than a root object.
- */
-export const MAX_ELEMENT_DEPTH = MAX_TRAVERSAL_DEPTH / 2;
-
-/**
- * The maximum number of entries kept at any single level (root, or a
- * `children` array at any depth) of the raw spec, before it ever reaches
- * `normalizeSpec`. Bounds a hostile array's reported `length` so the pre-pass
- * can never be made to walk further than this regardless of what the array
- * claims about itself.
- */
-export const CHILDREN_CAP = 200;
-
-/**
- * The total number of nodes {@link boundSpec} will visit across one walk,
- * regardless of how many times a shared reference recurs. Bounds the
- * combinatorial work a DAG of shared or self-referential nodes would
- * otherwise force even though each individual array stays within
- * {@link CHILDREN_CAP}.
- */
-export const NODE_BUDGET = 5000;
-
-export type ClampReason = "children" | "budget" | "cycle" | "depth";
-
-/** Renders the warning detail a protocol reports for one {@link ClampReason}. */
-export function clampReasonDetail(reason: ClampReason): string {
-  if (reason === "budget") {
-    return `the tree was truncated after ${NODE_BUDGET} nodes.`;
-  }
-  if (reason === "cycle") return "a self-referencing node was dropped.";
-  if (reason === "depth") {
-    return `nodes deeper than ${MAX_ELEMENT_DEPTH} levels were dropped.`;
-  }
-  return `children were clamped to ${CHILDREN_CAP} entries.`;
-}
-
-interface BoundState {
-  remaining: number;
-  exhausted: boolean;
-}
-
-function boundNode(
-  value: unknown,
-  depth: number,
-  onClamp: (reason: ClampReason) => void,
-  state: BoundState,
-  ancestors: WeakSet<object>,
-): unknown {
-  if (state.remaining <= 0) {
-    if (!state.exhausted) {
-      state.exhausted = true;
-      onClamp("budget");
-    }
-    return null;
-  }
-  state.remaining -= 1;
-  if (depth > MAX_TRAVERSAL_DEPTH) {
-    onClamp("depth");
-    return null;
-  }
-  if (Array.isArray(value)) {
-    if (ancestors.has(value)) {
-      onClamp("cycle");
-      return null;
-    }
-    ancestors.add(value);
-    const { items: bounded, truncated } = copyBounded(value, CHILDREN_CAP);
-    if (truncated) onClamp("children");
-    const result = bounded.map((item) =>
-      boundNode(item, depth + 1, onClamp, state, ancestors),
-    );
-    ancestors.delete(value);
-    return result;
-  }
-  if (value !== null && typeof value === "object") {
-    const record = value as Record<string, unknown>;
-    const children = record["children"];
-    // The spread performs a `children` read of its own, so the copy states the
-    // bounded value even when there is none.
-    if (children === undefined) return { ...record, children: undefined };
-    if (ancestors.has(value)) {
-      onClamp("cycle");
-      return null;
-    }
-    ancestors.add(value);
-    const result = {
-      ...record,
-      children: boundNode(children, depth + 1, onClamp, state, ancestors),
-    };
-    ancestors.delete(value);
-    return result;
-  }
-  return value;
-}
-
-/**
- * Produces a bounded plain copy of a raw generative-ui spec before it
- * reaches `normalizeSpec`, whose own traversal of the root array or any
- * `children` array walks the full reported length of a hostile proxied
- * array before any per-field cap downstream ever applies. Every array
- * (root, or `children` at any depth) is capped to {@link CHILDREN_CAP}
- * entries by index, which bounds a proxy however it fabricates `length` or
- * replaces its array methods; recursion itself is capped at
- * {@link MAX_TRAVERSAL_DEPTH}. Every object is returned as a plain copy whose
- * `children` came from a single read, because a record that answers
- * `[[HasProperty]]` and `[[Get]]`, or two `[[Get]]`s, differently would
- * otherwise hand the bound one value and `normalizeSpec` another, skipping
- * every bound here for that subtree. `onClamp` fires once per level that was
- * truncated, receiving the reason for that truncation: `"children"`,
- * `"depth"`, `"budget"`, or `"cycle"`. The walk also spends a total budget of
- * {@link NODE_BUDGET} nodes, so shared references cannot multiply work
- * exponentially, and a node that is its own ancestor is cut to `null`.
- */
-export function boundSpec(
-  spec: unknown,
-  onClamp: (reason: ClampReason) => void,
-): unknown {
-  return boundNode(
-    spec,
-    0,
-    onClamp,
-    { remaining: NODE_BUDGET, exhausted: false },
-    new WeakSet(),
-  );
-}

package/src/convert/copyBounded.test.ts

@@ -1,131 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { copyBounded } from "./copyBounded";
-
-const hostileSpecies = (real: unknown[], injected: unknown[]) => {
-  function HostileCtor() {
-    return { map: () => injected, some: () => true, length: 0 };
-  }
-  const constructor = { [Symbol.species]: HostileCtor };
-  return new Proxy(real, {
-    get: (target, prop, receiver) =>
-      prop === "constructor"
-        ? constructor
-        : Reflect.get(target, prop, receiver),
-  });
-};
-
-describe("copyBounded", () => {
-  it("copies every entry of a shorter array", () => {
-    expect(copyBounded(["a", "b"], 5).items).toEqual(["a", "b"]);
-  });
-
-  it("stops at the cap", () => {
-    expect(copyBounded(["a", "b", "c"], 2).items).toEqual(["a", "b"]);
-  });
-
-  it("returns a fresh array rather than the input", () => {
-    const input = ["a"];
-    expect(copyBounded(input, 5).items).not.toBe(input);
-  });
-
-  it("leaves an absent index absent, as slice does", () => {
-    const sparse: unknown[] = [];
-    sparse[0] = "a";
-    sparse[2] = "c";
-
-    const { items: result } = copyBounded(sparse, 5);
-
-    expect(result).toHaveLength(3);
-    expect(1 in result).toBe(false);
-    expect(result).toEqual(sparse.slice(0, 5));
-  });
-
-  it("does not read an index the input reports as absent", () => {
-    const reads: string[] = [];
-    const probe = new Proxy(["a", "b"], {
-      has: (target, prop) => prop !== "1" && Reflect.has(target, prop),
-      get: (target, prop, receiver) => {
-        if (typeof prop === "string" && /^\d+$/.test(prop)) reads.push(prop);
-        return Reflect.get(target, prop, receiver);
-      },
-    });
-
-    const { items: result } = copyBounded(probe, 2);
-
-    expect(reads).toEqual(["0"]);
-    expect(1 in result).toBe(false);
-  });
-
-  it("reports truncation from the same length read that bounds the copy", () => {
-    let reads = 0;
-    const shifty = new Proxy(["a", "b", "c"], {
-      get: (target, prop, receiver) => {
-        if (prop === "length") {
-          reads += 1;
-          return reads === 1 ? 3 : 1;
-        }
-        return Reflect.get(target, prop, receiver);
-      },
-    });
-
-    const { items, truncated } = copyBounded(shifty, 2);
-
-    expect(items).toHaveLength(2);
-    expect(truncated).toBe(true);
-  });
-
-  it("matches slice for every shape of reported length", () => {
-    const reportedLengths = [2.5, Infinity, NaN, -1, "3", 2, 0, -0.5, 1e21];
-    const lying = (length: unknown) =>
-      new Proxy(["a", "b", "c"], {
-        get: (target, prop, receiver) =>
-          prop === "length" ? length : Reflect.get(target, prop, receiver),
-      });
-
-    for (const cap of [0, 1, 2, 5]) {
-      for (const length of reportedLengths) {
-        const { items, truncated } = copyBounded(lying(length), cap);
-
-        expect(items).toEqual(
-          Array.prototype.slice.call(lying(length), 0, cap),
-        );
-        expect(truncated).toBe(
-          Array.prototype.slice.call(lying(length), 0, cap + 1).length > cap,
-        );
-      }
-    }
-  });
-
-  it("bounds an array whose reported length is fabricated", () => {
-    const hostile = new Proxy(["a", "b"], {
-      get: (target, prop, receiver) =>
-        prop === "length"
-          ? Number.MAX_SAFE_INTEGER
-          : Reflect.get(target, prop, receiver),
-    });
-
-    expect(copyBounded(hostile, 3).items).toEqual(["a", "b", undefined]);
-  });
-
-  it("bounds an array that replaces its slice", () => {
-    const hostile = new Proxy(["a", "b"], {
-      get: (target, prop, receiver) =>
-        prop === "slice"
-          ? () => Array(500).fill("injected")
-          : Reflect.get(target, prop, receiver),
-    });
-
-    expect(copyBounded(hostile, 5).items).toEqual(["a", "b"]);
-  });
-
-  it("bounds an array that redirects Symbol.species to a foreign object", () => {
-    const injected = Array(500).fill("injected");
-    const { items: result } = copyBounded(
-      hostileSpecies(["a", "b"], injected),
-      5,
-    );
-
-    expect(Array.isArray(result)).toBe(true);
-    expect(result).toEqual(["a", "b"]);
-  });
-});

package/src/convert/copyBounded.ts

@@ -1,38 +0,0 @@
-/**
- * Copies at most `cap` entries out of `value` by index.
- *
- * Every array method dispatches on the input: a replaced `slice` is called
- * directly, and the intrinsic `Array.prototype.slice.call` still reaches a
- * `constructor` with a `@@species` whose `[[Construct]]` returns an arbitrary
- * object, which then supplies the `map` or `some` the caller runs next. Reading
- * indices consults neither, so it is the only form that bounds a hostile array.
- *
- * Absent indices stay absent, matching what `slice` produces for a sparse
- * input, so callers that skip holes still skip them. `truncated` comes from the
- * same `length` read as the bound, so an input cannot report one figure to the
- * cap and another to the caller's warning.
- *
- * A reported `length` is normalized the way `ToLength` does before it reaches
- * `count`, because a fractional one would otherwise reach `items.length` and
- * throw `RangeError` where `slice` returns a bounded result. `truncated` reads
- * that same normalized figure, so a `length` whose `valueOf` answers differently
- * on a second conversion cannot separate the warning from the bound.
- */
-export const copyBounded = <T>(
-  value: readonly T[],
-  cap: number,
-): { readonly items: T[]; readonly truncated: boolean } => {
-  const reported = value.length;
-  const integral = Math.trunc(Number(reported));
-  const usable =
-    Number.isNaN(integral) || integral <= 0
-      ? 0
-      : Math.min(integral, Number.MAX_SAFE_INTEGER);
-  const count = Math.min(cap, usable);
-  const items: T[] = [];
-  for (let index = 0; index < count; index += 1) {
-    if (index in value) items[index] = value[index] as T;
-  }
-  items.length = count;
-  return { items, truncated: usable > cap };
-};

package/src/convert/isElement.ts

@@ -1,6 +0,0 @@
-import type { NormalizedUIElement, NormalizedUINode } from "../ir";
-
-export const isElement = (
-  node: NormalizedUINode,
-): node is NormalizedUIElement =>
-  typeof node === "object" && node !== null && !Array.isArray(node);

package/src/convert/takeRun.test.ts

@@ -1,64 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { NormalizedUIElement, NormalizedUINode } from "../ir";
-import { takeRun } from "./takeRun";
-
-const element = (type: string): NormalizedUIElement => ({ type, props: {} });
-
-const isFact = (candidate: NormalizedUIElement) => candidate.type === "Fact";
-
-describe("takeRun", () => {
-  it("collects the contiguous matching run and reports the resume index", () => {
-    const fact = element("Fact");
-    const nodes = [fact, fact, element("Text"), fact];
-
-    expect(takeRun(nodes, 0, isFact)).toEqual({ run: [fact, fact], next: 2 });
-  });
-
-  it("starts at the given index rather than the head of the list", () => {
-    const fact = element("Fact");
-    const nodes = [element("Text"), fact, fact];
-
-    expect(takeRun(nodes, 1, isFact)).toEqual({ run: [fact, fact], next: 3 });
-  });
-
-  it("stops at the end of the list", () => {
-    const fact = element("Fact");
-
-    expect(takeRun([fact, fact], 0, isFact)).toEqual({
-      run: [fact, fact],
-      next: 2,
-    });
-  });
-
-  it("returns an empty run without advancing when the first node does not match", () => {
-    expect(takeRun([element("Text"), element("Fact")], 0, isFact)).toEqual({
-      run: [],
-      next: 0,
-    });
-  });
-
-  it("stops on every non-element node shape", () => {
-    const fact = element("Fact");
-    const nonElements: (NormalizedUINode | undefined)[] = [
-      undefined,
-      null,
-      "",
-      "text",
-      0,
-      1,
-      [],
-      [fact],
-    ];
-
-    for (const nonElement of nonElements) {
-      expect(takeRun([fact, nonElement, fact], 0, isFact)).toEqual({
-        run: [fact],
-        next: 1,
-      });
-    }
-  });
-
-  it("stops past the end of the list", () => {
-    expect(takeRun([element("Fact")], 1, isFact)).toEqual({ run: [], next: 1 });
-  });
-});

package/src/convert/takeRun.ts

@@ -1,19 +0,0 @@
-import type { NormalizedUIElement, NormalizedUINode } from "../ir";
-import { isElement } from "./isElement";
-
-export function takeRun(
-  nodes: readonly (NormalizedUINode | undefined)[],
-  index: number,
-  matches: (element: NormalizedUIElement) => boolean,
-): { run: NormalizedUIElement[]; next: number } {
-  const run: NormalizedUIElement[] = [];
-  let next = index;
-  while (next < nodes.length) {
-    const candidate = nodes[next];
-    if (candidate === undefined || !isElement(candidate) || !matches(candidate))
-      break;
-    run.push(candidate);
-    next += 1;
-  }
-  return { run, next };
-}

package/src/defineGenerativeComponents.ts

@@ -1,38 +0,0 @@
-import type { GenerativeUILibrary } from "./types";
-
-/**
- * Authoring helper for a `"use generative"` generative-UI library — the set of
- * components the model may render. Each component colocates its `properties`
- * schema (kept on every build, drives the tool parameters) with its `render`
- * (kept only on the client). Pass the result to {@link JSONGenerativeUI}:
- *
- * ```tsx
- * "use generative";
- * const generative = new JSONGenerativeUI({
- *   library: defineGenerativeComponents({
- *     Card: {
- *       description: "A card.",
- *       properties: z.object({ title: z.string() }),
- *       render: (props) => <Card {...props} />,
- *     },
- *   }),
- * });
- * ```
- *
- * Unlike {@link defineToolkit}, it has **no runtime implementation**. A
- * `"use generative"` compiler unwraps the `defineGenerativeComponents(...)` call
- * per build, dropping each `render` (and its client-only imports) from the server
- * build. Reaching it at runtime means the module wasn't compiled (the directive
- * is missing, or it was used outside a `"use generative"` file), so it throws
- * rather than shipping client `render` code to the server.
- */
-export function defineGenerativeComponents(
-  _library: GenerativeUILibrary,
-): GenerativeUILibrary {
-  throw new Error(
-    "[assistant-ui] defineGenerativeComponents() has no runtime implementation " +
-      "— it is stripped at build time by the use-generative compiler. Reaching " +
-      "it means this module was not compiled (e.g. used outside a " +
-      '"use generative" file). Add the directive, or do not use it here.',
-  );
-}

package/src/fieldReferences.test.ts

@@ -1,66 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { hasFieldReference, resolveFieldReferences } from "./fieldReferences";
-
-describe("field references", () => {
-  it("resolve from own fields only and drop what does not resolve", () => {
-    const fields = Object.assign(Object.create({ inherited: "no" }), {
-      note: "hi",
-      empty: undefined,
-    }) as Record<string, unknown>;
-
-    expect(
-      resolveFieldReferences(
-        {
-          note: { $field: "note" },
-          list: [
-            { $field: "note" },
-            { $field: "empty" },
-            { $field: "inherited" },
-          ],
-          literal: { $field: "note", other: 1 },
-        },
-        fields,
-      ),
-    ).toEqual({
-      note: "hi",
-      list: ["hi"],
-      literal: { $field: "note", other: 1 },
-    });
-  });
-
-  it("fall back to the reference's own fallback, and read only $field and fallback as a reference", () => {
-    expect(
-      resolveFieldReferences(
-        {
-          filled: { $field: "note", fallback: "old" },
-          missing: { $field: "gone", fallback: "kept" },
-          empty: { $field: "gone" },
-          list: [{ $field: "gone", fallback: 0 }],
-          data: { $field: "note", fallback: "old", extra: true },
-        },
-        { note: "new" },
-      ),
-    ).toEqual({
-      filled: "new",
-      missing: "kept",
-      list: [0],
-      data: { $field: "note", fallback: "old", extra: true },
-    });
-  });
-
-  it("terminate on a cyclic value and keep the cycle", () => {
-    const cyclic: Record<string, unknown> = { note: { $field: "note" } };
-    cyclic["self"] = cyclic;
-    const acyclic: Record<string, unknown> = { a: 1 };
-    acyclic["self"] = { back: [acyclic] };
-
-    expect(hasFieldReference(cyclic)).toBe(true);
-    expect(hasFieldReference(acyclic)).toBe(false);
-    const resolved = resolveFieldReferences(cyclic, { note: "hi" }) as Record<
-      string,
-      unknown
-    >;
-    expect(resolved["note"]).toBe("hi");
-    expect(resolved["self"]).toBe(cyclic);
-  });
-});

package/src/fieldReferences.ts

@@ -1,83 +0,0 @@
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
-const MAX_DEPTH = 64;
-
-const isFieldReference = (
-  value: unknown,
-): value is { readonly $field: string; readonly fallback?: unknown } =>
-  isRecord(value) &&
-  typeof value["$field"] === "string" &&
-  Object.keys(value).every((key) => key === "$field" || key === "fallback");
-
-/**
- * Whether `value` contains a `{ "$field": name }` or `{ "$field": name, "fallback": value }` reference within 64 levels.
- */
-export const hasFieldReference = (value: unknown): boolean => {
-  const seen = new Set<object>();
-  const visit = (entry: unknown, depth: number): boolean => {
-    if (
-      typeof entry !== "object" ||
-      entry === null ||
-      depth > MAX_DEPTH ||
-      seen.has(entry)
-    ) {
-      return false;
-    }
-    if (isFieldReference(entry)) return true;
-    seen.add(entry);
-    return Object.values(entry).some((item) => visit(item, depth + 1));
-  };
-  return visit(value, 0);
-};
-
-/**
- * Replaces each `{ "$field": name }` reference inside `value` with the own property `name` of `fields`, or with the reference's own `fallback` when that is `undefined`. A reference that still resolves to `undefined` is dropped from its object or array, and a cyclic reference or anything nested deeper than 64 levels is kept as is.
- */
-export const resolveFieldReferences = (
-  value: unknown,
-  fields: Readonly<Record<string, unknown>>,
-): unknown => {
-  const ancestors = new Set<object>();
-  const resolve = (entry: unknown, depth: number): unknown => {
-    if (isFieldReference(entry)) {
-      const current = Object.hasOwn(fields, entry.$field)
-        ? fields[entry.$field]
-        : undefined;
-      if (current !== undefined) return current;
-      return Object.hasOwn(entry, "fallback") ? entry.fallback : undefined;
-    }
-    if (
-      typeof entry !== "object" ||
-      entry === null ||
-      depth > MAX_DEPTH ||
-      ancestors.has(entry)
-    ) {
-      return entry;
-    }
-    ancestors.add(entry);
-    try {
-      if (Array.isArray(entry)) {
-        return entry
-          .map((item) => resolve(item, depth + 1))
-          .filter((item) => item !== undefined);
-      }
-      const result: Record<string, unknown> = {};
-      for (const [key, item] of Object.entries(entry)) {
-        const resolved = resolve(item, depth + 1);
-        if (resolved !== undefined) {
-          Object.defineProperty(result, key, {
-            value: resolved,
-            enumerable: true,
-            configurable: true,
-            writable: true,
-          });
-        }
-      }
-      return result;
-    } finally {
-      ancestors.delete(entry);
-    }
-  };
-  return resolve(value, 0);
-};