@assistant-ui/react-generative-ui 0.0.15 → 0.0.17

package/src/convert/boundSpec.ts

@@ -0,0 +1,134 @@
+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

@@ -0,0 +1,131 @@
+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

@@ -0,0 +1,38 @@
+/**
+ * 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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,64 @@
+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

@@ -0,0 +1,19 @@
+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/slack/constants.ts

@@ -11,35 +11,6 @@ import type {
   SlackTextObject,
 } from "./types";
 
-/** 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 the pre-normalization bounding walk will visit
- * across one call, 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;
-
 /** The block limit for a Slack message. */
 export const MESSAGE_BLOCK_CAP = 50;
 

package/src/slack/fromSlackBlocks.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import type { UIElement } from "../ir";
-import { INBOUND_BLOCK_CAP } from "./constants";
+import { INBOUND_BLOCK_CAP, SELECT_OPTION_CAP } from "./constants";
 import { fromSlackBlocks } from "./fromSlackBlocks";
 import { toSlackBlocks } from "./toSlackBlocks";
 import type { ToSlackBlocksOptions } from "./types";
@@ -1118,14 +1118,112 @@ describe("fromSlackBlocks checkbox and radio caps", () => {
   });
 });
 
-it("bounds hostile initial_options arrays when deriving defaultChecked", () => {
-  const hostile = new Proxy([], {
-    get(target, prop) {
-      if (prop === "length") return 2 ** 31;
-      if (prop === "slice") return Array.prototype.slice.bind(target);
-      return Reflect.get(target, prop);
+it("bounds static-select options when an array replaces its slice", () => {
+  const hostile = new Proxy(
+    Array.from({ length: SELECT_OPTION_CAP + 1 }, (_, index) => ({
+      text: { type: "plain_text", text: `Option ${index}` },
+      value: `value-${index}`,
+    })),
+    {
+      get(target, prop, receiver) {
+        if (prop === "slice") {
+          return () =>
+            Array.from({ length: SELECT_OPTION_CAP * 2 }, () => ({
+              text: { type: "plain_text", text: "Injected" },
+              value: "injected",
+            }));
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    },
+  );
+
+  const { nodes } = fromSlackBlocks([
+    {
+      type: "actions",
+      elements: [
+        { type: "static_select", action_id: "pick", options: hostile },
+      ],
     },
+  ]);
+  const select = nodes[0] as unknown as { options: unknown[] };
+
+  expect(select.options).toHaveLength(SELECT_OPTION_CAP);
+  expect(select.options[0]).toEqual({ label: "Option 0", value: "value-0" });
+  expect(select.options.at(-1)).toEqual({
+    label: `Option ${SELECT_OPTION_CAP - 1}`,
+    value: `value-${SELECT_OPTION_CAP - 1}`,
   });
+});
+
+it("skips a hole in a section fields array instead of decoding a blank fact", () => {
+  const fields: unknown[] = [];
+  fields[0] = { type: "mrkdwn", text: "*A*\nyes" };
+  fields[2] = { type: "mrkdwn", text: "*C*\nyes" };
+
+  const { nodes, warnings } = fromSlackBlocks([{ type: "section", fields }]);
+
+  expect(warnings).toEqual([]);
+  expect(nodes.filter(Boolean)).toEqual([
+    { $type: "Fact", label: "A", value: "yes" },
+    { $type: "Fact", label: "C", value: "yes" },
+  ]);
+});
+
+it("bounds static-select options when an array redirects Symbol.species", () => {
+  function HostileCtor() {
+    return {
+      map: () =>
+        Array.from({ length: SELECT_OPTION_CAP * 5 }, () => ({
+          label: "Injected",
+          value: "injected",
+        })),
+      length: 0,
+    };
+  }
+  const constructor = { [Symbol.species]: HostileCtor };
+  const hostile = new Proxy(
+    Array.from({ length: SELECT_OPTION_CAP + 1 }, (_, index) => ({
+      text: { type: "plain_text", text: `Option ${index}` },
+      value: `value-${index}`,
+    })),
+    {
+      get: (target, prop, receiver) =>
+        prop === "constructor"
+          ? constructor
+          : Reflect.get(target, prop, receiver),
+    },
+  );
+
+  const { nodes } = fromSlackBlocks([
+    {
+      type: "actions",
+      elements: [
+        { type: "static_select", action_id: "pick", options: hostile },
+      ],
+    },
+  ]);
+  const select = nodes[0] as unknown as { options: unknown[] };
+
+  expect(select.options).toHaveLength(SELECT_OPTION_CAP);
+  expect(select.options[0]).toEqual({ label: "Option 0", value: "value-0" });
+});
+
+it("bounds hostile initial_options arrays when deriving defaultChecked", () => {
+  const hostile = new Proxy(
+    [{ text: { type: "plain_text", text: "Other" }, value: "other" }],
+    {
+      get(target, prop, receiver) {
+        if (prop === "length") return 2 ** 31;
+        if (prop === "slice") {
+          return () => [
+            { text: { type: "plain_text", text: "First" }, value: "first" },
+          ];
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    },
+  );
   const { nodes } = fromSlackBlocks([
     {
       type: "actions",

package/src/slack/fromSlackBlocks.ts

@@ -1,3 +1,4 @@
+import { copyBounded } from "../convert/copyBounded";
 import type { Action, UIElement } from "../ir";
 import {
   ACTIONS_ELEMENT_CAP,
@@ -34,18 +35,16 @@ const warn = (
 };
 
 /**
- * The shared bounded-iteration primitive: slices `value` to `cap` entries
- * without ever reading past that many indices, so a hostile array (sparse or
- * proxied with a fabricated `length`) cannot stall the event loop. `slice`
- * itself performs the bounded read; only its own reported length is
- * inspected to detect truncation.
+ * The shared bounded-iteration primitive: copies `value` to at most `cap`
+ * entries without ever reading past that many indices, so a hostile array
+ * (sparse or proxied with a fabricated `length`) cannot stall the event loop.
  */
 const clampArray = (
   value: unknown,
   cap: number,
 ): { readonly items: unknown[]; readonly truncated: boolean } => {
   if (!Array.isArray(value)) return { items: [], truncated: false };
-  return { items: value.slice(0, cap), truncated: value.length > cap };
+  return copyBounded(value, cap);
 };
 
 const boundedArray = (
@@ -238,9 +237,10 @@ const checkboxFrom = (element: Record<string, unknown>): UIElement => {
     : [];
   const firstValue =
     isRecord(first) && typeof first["value"] === "string" ? first["value"] : "";
-  const firstChecked = initialOptions
-    .slice(0, SELECT_OPTION_CAP)
-    .some((option) => isRecord(option) && option["value"] === firstValue);
+  const firstChecked = copyBounded(
+    initialOptions,
+    SELECT_OPTION_CAP,
+  ).items.some((option) => isRecord(option) && option["value"] === firstValue);
   return {
     $type: "Checkbox",
     label: isRecord(first) ? textOf(first["text"]) : "",