@superxd-studio/adptr 0.5.0

package/source/reusable/generative/schema.ts

@@ -0,0 +1,327 @@
+import { z } from "zod";
+import { parseDate } from "@internationalized/date";
+
+const text = z.string().max(8000);
+const short = z.string().min(1).max(160);
+const optionalText = text.optional();
+const options = z
+  .array(z.strictObject({ label: short, value: short }))
+  .min(1)
+  .max(50)
+  .refine((v) => new Set(v.map((x) => x.value)).size === v.length);
+const name = z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/);
+export const actionSchema = z.record(z.string(), z.json()).and(z.object({ type: name }));
+export type StructuredAction = z.infer<typeof actionSchema>;
+const footer = z.strictObject({ label: short, $action: actionSchema.optional() });
+const layout = {
+  gap: z.number().int().min(0).max(8).optional(),
+  align: z.enum(["start", "center", "end"]).optional(),
+};
+const field = { name, label: short, defaultValue: optionalText, required: z.boolean().optional() };
+const point = z.strictObject({ label: short, value: z.number().finite().min(-1e12).max(1e12) });
+export const chartSchema = z
+  .strictObject({
+    label: short,
+    variant: z.enum(["bar", "line", "area", "sparkline"]),
+    data: z.array(point).max(100).optional(),
+    series: z
+      .array(z.strictObject({ label: short, data: z.array(point).max(100) }))
+      .max(5)
+      .optional(),
+    stacked: z.boolean().optional(),
+    showAxis: z.boolean().optional(),
+    showLegend: z.boolean().optional(),
+  })
+  .superRefine((v, ctx) => {
+    const series = v.series;
+    if (series?.length) {
+      const labels = series[0]?.data.map((p) => p.label).join("\u0000");
+      if (series.some((s) => s.data.map((p) => p.label).join("\u0000") !== labels))
+        ctx.addIssue({ code: "custom", message: "Series labels must align" });
+    }
+  });
+export type GenerativeChartProps = z.infer<typeof chartSchema>;
+export const tableSchema = z
+  .strictObject({
+    label: short,
+    columns: z
+      .array(z.strictObject({ label: short, align: z.enum(["start", "end"]).optional() }))
+      .min(1)
+      .max(12),
+    rows: z.array(z.array(z.union([text, z.number().finite(), z.boolean()])).max(12)).max(200),
+    sortable: z.boolean().optional(),
+  })
+  .refine((v) => v.rows.every((row) => row.length === v.columns.length));
+export type GenerativeTableProps = z.infer<typeof tableSchema>;
+export const nodeSchemas = {
+  Card: z.strictObject({
+    title: optionalText,
+    asForm: z.boolean().optional(),
+    confirm: footer.optional(),
+    cancel: footer.optional(),
+  }),
+  Form: z.strictObject({}),
+  Row: z.strictObject({
+    ...layout,
+    justify: z.enum(["start", "center", "end", "between"]).optional(),
+  }),
+  Col: z.strictObject(layout),
+  Text: z.strictObject({
+    value: text,
+    size: z.enum(["sm", "md", "lg", "xl", "2xl", "3xl"]).optional(),
+    weight: z.enum(["normal", "medium", "semibold", "bold"]).optional(),
+    color: z.enum(["emphasis", "secondary"]).optional(),
+  }),
+  Header: z.strictObject({ text, size: z.enum(["sm", "md", "lg", "xl", "2xl", "3xl"]).optional() }),
+  Caption: z.strictObject({ value: text }),
+  Markdown: z.strictObject({ value: text }),
+  Badge: z.strictObject({
+    value: short,
+    variant: z.enum(["success", "info", "warning", "neutral"]).optional(),
+  }),
+  Fact: z.strictObject({ label: short, value: text, binding: name.optional() }),
+  Divider: z.strictObject({}),
+  Spacer: z.strictObject({}),
+  Accent: z.strictObject({}),
+  Icon: z.strictObject({
+    name: z.enum([
+      "sun",
+      "moon",
+      "cloud",
+      "rain",
+      "snow",
+      "wind",
+      "play",
+      "pause",
+      "check",
+      "x",
+      "star",
+      "heart",
+      "arrow-right",
+      "arrow-up-right",
+      "chevron-right",
+      "calendar",
+      "clock",
+      "map-pin",
+      "plane",
+      "truck",
+      "credit-card",
+      "user",
+      "search",
+      "bell",
+    ]),
+    size: z.enum(["sm", "md", "lg"]).optional(),
+  }),
+  Image: z.strictObject({
+    src: text,
+    alt: text,
+    size: z.enum(["sm", "md", "lg"]).optional(),
+    round: z.boolean().optional(),
+  }),
+  Avatar: z.strictObject({ name: short }),
+  Alert: z.strictObject({
+    tone: z.enum(["info", "success", "warning", "danger"]),
+    title: short,
+    description: optionalText,
+  }),
+  ListView: z.strictObject({}),
+  ListViewItem: z.strictObject({}),
+  Input: z.strictObject({
+    ...field,
+    placeholder: optionalText,
+    multiline: z.boolean().optional(),
+    inputType: z.enum(["text", "email"]).optional(),
+  }),
+  Select: z
+    .strictObject({ ...field, options, placeholder: optionalText })
+    .refine((v) => !v.defaultValue || v.options.some((o) => o.value === v.defaultValue)),
+  DatePicker: z.strictObject(field).refine((v) => {
+    try {
+      if (v.defaultValue) parseDate(v.defaultValue);
+      return true;
+    } catch {
+      return false;
+    }
+  }),
+  RadioGroup: z
+    .strictObject({ ...field, options })
+    .refine((v) => !v.defaultValue || v.options.some((o) => o.value === v.defaultValue)),
+  Checkbox: z.strictObject({ name, label: short, defaultChecked: z.boolean().optional() }),
+  Button: z.strictObject({
+    label: short,
+    buttonStyle: z.enum(["primary", "secondary", "outline", "ghost", "danger"]).optional(),
+    block: z.boolean().optional(),
+    submit: z.boolean().optional(),
+  }),
+  Progress: z
+    .strictObject({
+      label: short,
+      value: z.number().min(0).max(100),
+      max: z.number().positive().max(100),
+    })
+    .refine((v) => v.value <= v.max),
+  Chart: chartSchema,
+  Table: tableSchema,
+};
+export type StructuredSpec = {
+  readonly $type: string;
+  readonly $key?: string | number;
+  readonly $action?: StructuredAction;
+  readonly children?: StructuredSpec | readonly StructuredSpec[];
+  readonly [property: string]: unknown;
+};
+
+/** Bound the whole JSON tree before recursive schemas, including action payloads. */
+export function assertBoundedJson(input: unknown, maxBytes = 120000) {
+  let nodes = 0,
+    bytes = 0;
+  const ancestors = new Set<object>();
+  function walk(value: unknown, depth: number) {
+    if (depth > 24 || ++nodes > 6000) throw new Error("Response too large");
+    if (value === null || typeof value === "boolean") return;
+    if (typeof value === "string") {
+      bytes += value.length;
+      if (bytes > maxBytes) throw new Error("Response too large");
+      return;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) return;
+    if (typeof value !== "object" || ancestors.has(value)) throw new Error("Expected JSON");
+    if (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+      throw new Error("Expected plain JSON");
+    ancestors.add(value);
+    for (const [key, entry] of Object.entries(value)) {
+      if (["__proto__", "constructor", "prototype"].includes(key)) throw new Error("Unsafe key");
+      bytes += key.length;
+      walk(entry, depth + 1);
+    }
+    ancestors.delete(value);
+  }
+  walk(input, 0);
+}
+
+/** Validate BEFORE the upstream renderer; its property schemas describe tools, not input validation. */
+export function parseStructuredSpec(input: unknown): StructuredSpec {
+  assertBoundedJson(input);
+  let count = 0;
+  const seen = new Set<object>();
+  let stringBudget = 0;
+  function visit(
+    v: unknown,
+    depth: number,
+    inForm: boolean,
+    names: Set<string>,
+    inline = false,
+  ): StructuredSpec {
+    if (
+      depth > 16 ||
+      ++count > 300 ||
+      !v ||
+      typeof v !== "object" ||
+      Array.isArray(v) ||
+      seen.has(v)
+    )
+      throw new Error("Invalid response tree");
+    seen.add(v);
+    const { $type, $key, $action, children, ...props } = v as Record<string, unknown>;
+    if (typeof $type !== "string" || !Object.hasOwn(nodeSchemas, $type))
+      throw new Error("Unsupported component");
+    if (inline && !["Text", "Badge", "Icon"].includes($type))
+      throw new Error("Inline content cannot contain a layout or control");
+    const schema = nodeSchemas[$type as keyof typeof nodeSchemas];
+    const parsed = schema.parse(props);
+    const leaf = [
+      "Input",
+      "Select",
+      "DatePicker",
+      "RadioGroup",
+      "Checkbox",
+      "Image",
+      "Avatar",
+      "Fact",
+      "Chart",
+      "Table",
+      "Progress",
+      "Divider",
+      "Spacer",
+      "Accent",
+      "Caption",
+      "Markdown",
+      "Header",
+      "Alert",
+      "Icon",
+    ];
+    if (children !== undefined && leaf.includes($type))
+      throw new Error("A leaf cannot have children");
+    if ($type === "Button" && (parsed as { submit?: boolean }).submit && !inForm)
+      throw new Error("A submit button needs a form");
+    if (
+      $type === "ListView" &&
+      children !== undefined &&
+      (Array.isArray(children) ? children : [children]).some(
+        (c) => !c || typeof c !== "object" || (c as { $type?: string }).$type !== "ListViewItem",
+      )
+    )
+      throw new Error("A list needs list items");
+    if (
+      $key !== undefined &&
+      !(typeof $key === "string" && $key.length <= 160) &&
+      !(typeof $key === "number" && Number.isFinite($key))
+    )
+      throw new Error("Invalid key");
+    const action = $action === undefined ? undefined : actionSchema.parse($action);
+    if (action && !["Button", "Form"].includes($type))
+      throw new Error("Action on a passive component");
+    const form = $type === "Form" || ($type === "Card" && (parsed as { asForm?: boolean }).asForm);
+    if (form && inForm) throw new Error("Nested forms");
+    const scope = form ? new Set<string>() : names;
+    if (
+      ["Input", "Select", "DatePicker", "RadioGroup", "Checkbox"].includes($type) &&
+      "name" in parsed &&
+      typeof parsed.name === "string"
+    ) {
+      if (!inForm || scope.has(parsed.name)) throw new Error("A field needs a unique form name");
+      scope.add(parsed.name);
+    }
+    for (const value of Object.values(parsed))
+      if (typeof value === "string") stringBudget += value.length;
+    if (stringBudget > 48000) throw new Error("Response too large");
+    if (action && JSON.stringify(action).length > 4000) throw new Error("Action too large");
+    let nested: StructuredSpec | StructuredSpec[] | undefined;
+    if (children !== undefined) {
+      if (Array.isArray(children)) {
+        if (children.length > 100) throw new Error("Too many children");
+        const keys = children
+          .map((c) =>
+            c && typeof c === "object" ? (c as Record<string, unknown>).$key : undefined,
+          )
+          .filter((k) => k !== undefined);
+        if (new Set(keys).size !== keys.length) throw new Error("Duplicate child keys");
+        nested = children.map((c) =>
+          visit(
+            c,
+            depth + 1,
+            Boolean(form || inForm),
+            scope,
+            inline || ["Text", "Badge", "Button"].includes($type),
+          ),
+        );
+      } else
+        nested = visit(
+          children,
+          depth + 1,
+          Boolean(form || inForm),
+          scope,
+          inline || ["Text", "Badge", "Button"].includes($type),
+        );
+    }
+    seen.delete(v);
+    return {
+      ...parsed,
+      $type,
+      ...($key === undefined ? {} : { $key: $key as string | number }),
+      ...(action ? { $action: action } : {}),
+      ...(nested ? { children: nested } : {}),
+    };
+  }
+  return visit(input, 0, false, new Set());
+}

package/source/reusable/generative/timeline.tsx

@@ -0,0 +1,214 @@
+import {
+  CanvasPastContext,
+  CanvasStageBridge,
+  historicalNode,
+  type CanvasFrame,
+} from "../../components/canvas/index.js";
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import { CanvasConnector } from "../../components/canvas/connector.js";
+import type {
+  GenerativeActionController,
+  GenerativeActionSnapshot,
+  GenerativeActions,
+} from "./actions.js";
+import { actionSchema } from "./schema.js";
+import type { GenerativeCopy } from "./copy.js";
+
+type ResponseStatus = "loading" | "streaming" | "done" | "error";
+interface Step {
+  snapshot: GenerativeActionSnapshot;
+  spec: unknown;
+  status: ResponseStatus;
+  input?: Readonly<Record<string, string | boolean>>;
+  result?: ReactNode;
+  label?: string;
+}
+
+export function ResponseTimeline({
+  controller,
+  spec,
+  status,
+  actions,
+  copy,
+  children,
+}: {
+  controller: GenerativeActionController;
+  spec: unknown;
+  status: ResponseStatus;
+  actions: GenerativeActions;
+  copy: GenerativeCopy;
+  children: (step: Step, onRequest: (input: unknown) => void) => ReactNode;
+}) {
+  const [steps, setSteps] = useState<Step[]>(() => [
+    { snapshot: controller.getSnapshot(), spec, status },
+  ]);
+  const continuation = useRef<CanvasFrame | null>(null);
+  const [publishResult] = useState(() => (frame: CanvasFrame) => {
+    const previous = continuation.current;
+    if (previous?.terminal) return;
+    continuation.current = frame;
+    if (!previous || previous.phase === frame.phase) return;
+    setSteps((prior) => {
+      const last = prior[prior.length - 1];
+      if (!last) return prior;
+      return [
+        ...prior.slice(0, -1),
+        {
+          ...last,
+          result: (
+            <div
+              data-generative-result
+              className="rounded-surface border border-line-subtle bg-surface p-5 sm:p-6"
+            >
+              {historicalNode(previous.node)}
+            </div>
+          ),
+        },
+        {
+          ...last,
+          result: (
+            <div
+              data-generative-result
+              className="rounded-surface border border-line-subtle bg-surface p-5 sm:p-6"
+            >
+              {frame.node}
+            </div>
+          ),
+          label: frame.label,
+        },
+      ];
+    });
+  });
+  const source = useRef({ spec, status });
+  const lastInput = useRef<Readonly<Record<string, string | boolean>>>(undefined);
+  const origin = useRef<number>(-1);
+  const userStarted = useRef(false);
+  const canvas = useRef<HTMLDivElement>(null);
+  const seen = useRef(controller.getSnapshot());
+  useEffect(() => {
+    source.current = { spec, status };
+  }, [spec, status]);
+  useEffect(() => {
+    // Observe every controller notification, including loading followed immediately by a receipt.
+    const record = () => {
+      const snapshot = controller.getSnapshot();
+      if (seen.current === snapshot) return;
+      // A canvas run ends at its first receipt or dismissal. Reset remounts the preview.
+      if (seen.current.stage === "complete" || seen.current.stage === "dismissed") return;
+      seen.current = snapshot;
+      // Inspection creates a request just before entering submitting; this isn't a displayed step.
+      if (snapshot.stage === "ready" && snapshot.request) return;
+      const next = {
+        snapshot,
+        ...source.current,
+        input: lastInput.current,
+      };
+      setSteps((prior) => [...prior, next]);
+    };
+    record();
+    return controller.subscribe(record);
+  }, [controller]);
+  useEffect(() => {
+    if (!userStarted.current) return;
+    const current = canvas.current?.querySelector<HTMLElement>('[data-current="true"]');
+    if (!current) return;
+    const latest = steps[steps.length - 1];
+    if (latest?.snapshot.stage === "ready") {
+      const buttons = current.querySelectorAll<HTMLElement>("[data-generative-content] button");
+      const target = buttons[origin.current] ?? current;
+      target.focus({ preventScroll: true });
+    } else {
+      (current.querySelector<HTMLElement>("[data-generative-action]") ?? current).focus({
+        preventScroll: true,
+      });
+    }
+    // Keep the new step in view, without animating or dragging the whole page past it.
+    current.scrollIntoView({ block: "nearest", behavior: "instant" });
+  }, [steps]);
+  const onRequest = (input: unknown) => {
+    const parsed = actionSchema.safeParse(input);
+    const inputValues = parsed.success ? parsed.data.$input : undefined;
+    if (inputValues && typeof inputValues === "object" && !Array.isArray(inputValues))
+      lastInput.current = Object.fromEntries(
+        Object.entries(inputValues).filter(
+          (entry): entry is [string, string | boolean] =>
+            typeof entry[1] === "string" || typeof entry[1] === "boolean",
+        ),
+      );
+    const current = canvas.current?.querySelector('[data-current="true"]');
+    origin.current = Array.from(
+      current?.querySelectorAll("[data-generative-content] button") ?? [],
+    ).indexOf(document.activeElement as Element);
+    userStarted.current = true;
+  };
+  function label(step: Step) {
+    if (step.label) return step.label;
+    const stage = step.snapshot.stage;
+    if (stage === "ready") return step.status === "done" ? copy.stepReady : copy.stepLoading;
+    if (stage === "submitting")
+      return step.snapshot.request && actions[step.snapshot.request.action.type]?.kind === "inspect"
+        ? copy.stepLoading
+        : copy.working;
+    return {
+      confirm: copy.stepReview,
+      checking: copy.checking,
+      failed: copy.stepFailed,
+      uncertain: copy.stepUncertain,
+      complete: copy.stepResult,
+      dismissed: copy.dismissed,
+    }[stage];
+  }
+  return (
+    <div
+      ref={canvas}
+      data-generative-timeline
+      className="mx-auto flex w-full max-w-2xl min-w-0 flex-col gap-20"
+    >
+      {steps.map((step, index) => {
+        const current = index === steps.length - 1;
+        // Live source updates can finish a stream or retry invalid data before an action begins.
+        const displayed =
+          current && step.snapshot.stage === "ready"
+            ? { ...step, spec: index === 0 ? spec : step.spec, status }
+            : step;
+        return (
+          <div
+            key={index}
+            data-generative-step={step.snapshot.stage}
+            data-current={current}
+            tabIndex={-1}
+            className="relative min-w-0 scroll-mt-6 outline-none"
+          >
+            {index > 0 ? <CanvasConnector /> : null}
+            <p className="mb-3 flex items-center gap-3 font-mono type-caption text-system-blue">
+              <span>{String(index + 1).padStart(2, "0")}</span>
+              <span>{label(displayed)}</span>
+              {!current ? <span className="ml-auto">{copy.stepPast}</span> : null}
+            </p>
+            <div inert={!current} aria-hidden={!current}>
+              <CanvasPastContext.Provider value={!current}>
+                <CanvasStageBridge publish={publishResult}>
+                  {step.result ?? (
+                    <TimelineStep step={displayed} render={children} onRequest={onRequest} />
+                  )}
+                </CanvasStageBridge>
+              </CanvasPastContext.Provider>
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function TimelineStep({
+  step,
+  render,
+  onRequest,
+}: {
+  step: Step;
+  render: (step: Step, onRequest: (input: unknown) => void) => ReactNode;
+  onRequest: (input: unknown) => void;
+}) {
+  return render(step, onRequest);
+}