@superxd-studio/adptr 0.5.0

package/examples/review-backend/copy.mjs

@@ -0,0 +1,27 @@
+export const reviewFixture = {
+  title: "Make the welcome email clearer",
+  destination: "Welcome email",
+  changes: [
+    {
+      id: "subject",
+      title: "A clearer subject",
+      before: "Your journey begins here",
+      after: "Your workspace is ready",
+      reason: "Tell people what they can do next.",
+    },
+    {
+      id: "opening",
+      title: "A more useful opening",
+      before: "We’re delighted to welcome you to the platform.",
+      after: "Your workspace is ready. Add your first project when you’re ready.",
+      reason: "Keep the welcome warm and make the next step clear.",
+    },
+    {
+      id: "action",
+      title: "A specific action",
+      before: "Get started",
+      after: "Create your first project",
+      reason: "Describe where the action takes people.",
+    },
+  ],
+};

package/examples/review-backend/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "superxd-local-review-backend",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node server.mjs"
+  },
+  "dependencies": {
+    "@langchain/langgraph": "1.4.18"
+  }
+}

package/examples/review-backend/server.mjs

@@ -0,0 +1,276 @@
+import { createServer } from "node:http";
+import { randomUUID, randomBytes, timingSafeEqual } from "node:crypto";
+import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
+import { setTimeout as delay } from "node:timers/promises";
+import { parseReviewDecision } from "../../review/index.js";
+import { createLangGraphReviewDriver } from "../../langgraph-review/index.js";
+import { reviewFixture } from "./copy.mjs";
+
+const scenarios = new Set([
+  "normal",
+  "load-fails",
+  "send-fails",
+  "lost-response",
+  "conflict",
+  "partial",
+  "blocked",
+  "empty",
+  "slow",
+]);
+const origins = new Set([
+  "http://127.0.0.1:5190",
+  "http://127.0.0.1:5300",
+  "http://127.0.0.1:5301",
+]);
+const clone = (value) => structuredClone(value);
+const fault = (code) => Object.assign(new Error("Review rejected"), { code });
+/** Loopback fixture only. No models, emails, real documents, accounts or durable storage. */
+export function createReviewServer({ wait = 120, now = Date.now } = {}) {
+  const sessions = new Map();
+  async function body(request) {
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of request) {
+      size += chunk.length;
+      if (size > 8000) throw fault(413);
+      chunks.push(chunk);
+    }
+    try {
+      return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    } catch {
+      throw fault(400);
+    }
+  }
+  function authorize(request, session) {
+    const value = request.headers.authorization;
+    if (!session || session.expires <= now() || typeof value !== "string") throw fault(401);
+    const supplied = Buffer.from(value),
+      expected = Buffer.from(`Bearer ${session.token}`);
+    if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected))
+      throw fault(401);
+  }
+  function validate(session, decision) {
+    const r = session.record;
+    if (session.expires <= now()) throw fault(401);
+    if (!r.proposal.canDecide) throw fault(403);
+    if (
+      r.proposal.id !== decision.proposalId ||
+      r.proposal.revision !== decision.revision ||
+      !["pending", "partial"].includes(r.outcome)
+    )
+      throw fault(409);
+    if (decision.changeIds.some((id) => !r.remainingIds.includes(id))) throw fault(400);
+    // Preconditions come from the server's stored proposal, never client text or arbitrary tool args.
+    if (
+      decision.changeIds.some(
+        (id) => session.document[id] !== r.proposal.changes.find((c) => c.id === id)?.before,
+      )
+    )
+      throw fault(409);
+  }
+  function commit(session, decision) {
+    validate(session, decision);
+    const r = clone(session.record);
+    const appliedIds = [];
+    if (decision.choice === "approve") {
+      for (const id of decision.changeIds) {
+        if (session.scenario === "partial" && !session.partial && appliedIds.length === 1) break;
+        const change = r.proposal.changes.find((c) => c.id === id);
+        session.document[id] = change.after;
+        appliedIds.push(id);
+        session.applyCount++;
+      }
+      session.partial = true;
+    }
+    r.appliedIds.push(...appliedIds);
+    r.remainingIds =
+      decision.choice === "approve"
+        ? decision.changeIds.filter((id) => !appliedIds.includes(id))
+        : [];
+    r.outcome =
+      decision.choice === "deny"
+        ? r.appliedIds.length
+          ? "complete"
+          : "denied"
+        : r.remainingIds.length
+          ? "partial"
+          : "complete";
+    r.proposal.revision++;
+    const receipt = {
+      requestId: decision.requestId,
+      choice: decision.choice,
+      appliedIds,
+      record: r,
+    };
+    // One synchronous commit includes the result and its idempotency receipt. Never evict active receipts.
+    session.record = r;
+    session.receipts.set(decision.requestId, {
+      fingerprint: JSON.stringify(decision),
+      receipt: clone(receipt),
+    });
+    return Promise.resolve(receipt);
+  }
+  async function pause(session) {
+    session.thread = `${session.id}-${session.record.proposal.revision}`;
+    await session.driver.start(clone(session.record.proposal), session.thread);
+  }
+  const server = createServer(async (request, response) => {
+    function json(code, value) {
+      if (!response.destroyed)
+        response
+          .writeHead(code, {
+            "content-type": "application/json",
+            "cache-control": "no-store",
+            "x-content-type-options": "nosniff",
+          })
+          .end(JSON.stringify(value));
+    }
+    try {
+      if (request.headers.host !== `127.0.0.1:${request.socket.localPort}`) throw fault(403);
+      const origin = request.headers.origin;
+      if (origin && !origins.has(origin)) throw fault(403);
+      if (origin) response.setHeader("access-control-allow-origin", origin);
+      response.setHeader("vary", "Origin");
+      if (request.method === "OPTIONS") {
+        response
+          .writeHead(204, {
+            "access-control-allow-methods": "GET,POST",
+            "access-control-allow-headers": "content-type,authorization",
+          })
+          .end();
+        return;
+      }
+      if (request.method === "GET" && request.url === "/health") {
+        json(200, { ready: true });
+        return;
+      }
+      if (request.method === "POST" && request.url === "/sessions") {
+        const input = await body(request);
+        if (!input || Object.keys(input).join() !== "scenario" || !scenarios.has(input.scenario))
+          throw fault(400);
+        // Expired sessions already reject every request; removing them preserves active receipts.
+        for (const [id, session] of sessions) if (session.expires <= now()) sessions.delete(id);
+        // Keep the fixture bounded and refuse new work instead of dropping replay protection.
+        if (sessions.size >= 200) throw fault(503);
+        const changes = input.scenario === "empty" ? [] : clone(reviewFixture.changes);
+        const session = {
+          id: randomUUID(),
+          token: randomBytes(32).toString("hex"),
+          scenario: input.scenario,
+          expires: now() + 30 * 60_000,
+          record: {
+            proposal: {
+              id: randomUUID(),
+              revision: 1,
+              title: reviewFixture.title,
+              destination: reviewFixture.destination,
+              canDecide: input.scenario !== "blocked",
+              changes,
+            },
+            appliedIds: [],
+            remainingIds: changes.map((c) => c.id),
+            outcome: "pending",
+          },
+          document: Object.fromEntries(changes.map((c) => [c.id, c.before])),
+          applyCount: 0,
+          receipts: new Map(),
+          queue: Promise.resolve(),
+          failed: false,
+          partial: false,
+          lost: false,
+          stale: false,
+          loadFailed: false,
+        };
+        session.driver = createLangGraphReviewDriver((decision) => commit(session, decision));
+        sessions.set(session.id, session);
+        try {
+          await pause(session);
+        } catch (error) {
+          sessions.delete(session.id);
+          throw error;
+        }
+        json(201, { id: session.id, token: session.token });
+        return;
+      }
+      const match = /^\/reviews\/([\w-]+)(?:\/(decisions|document|receipts\/([\w-]+)))?$/.exec(
+        request.url ?? "",
+      );
+      if (!match) throw fault(404);
+      const session = sessions.get(match[1]);
+      authorize(request, session);
+      const action = match[2];
+      if (request.method === "POST" && action === "decisions") {
+        let decision;
+        try {
+          decision = parseReviewDecision(await body(request));
+        } catch (error) {
+          throw error.code ? error : fault(400);
+        }
+        const process = async () => {
+          const seen = session.receipts.get(decision.requestId);
+          if (seen) {
+            if (seen.fingerprint !== JSON.stringify(decision)) throw fault(409);
+            return clone(seen.receipt);
+          }
+          if (session.scenario === "conflict" && !session.stale) {
+            session.stale = true;
+            session.record.proposal.revision++;
+            session.record.proposal.changes[0].after = "Your new workspace is ready";
+            await pause(session);
+            throw fault(409);
+          }
+          validate(session, decision);
+          if (session.scenario === "send-fails" && !session.failed) {
+            session.failed = true;
+            throw fault(503);
+          }
+          await delay(session.scenario === "slow" ? wait * 12 : wait);
+          const receipt = await session.driver.resume(decision, session.thread);
+          if (session.record.outcome === "partial") await pause(session);
+          if (session.scenario === "lost-response" && !session.lost) {
+            session.lost = true;
+            response
+              .writeHead(200, { "content-type": "application/json", "cache-control": "no-store" })
+              .end('{"receipt":');
+            return null;
+          }
+          return receipt;
+        };
+        const job = session.queue.then(process);
+        session.queue = job.then(
+          () => {},
+          () => {},
+        );
+        const result = await job;
+        if (result) json(200, result);
+        return;
+      }
+      if (request.method !== "GET") throw fault(405);
+      await session.queue;
+      if (!action) {
+        if (session.scenario === "load-fails" && !session.loadFailed) {
+          session.loadFailed = true;
+          throw fault(503);
+        }
+        await delay(wait);
+        json(200, clone(session.record));
+      } else if (action === "document")
+        json(200, { fields: clone(session.document), applyCount: session.applyCount });
+      else if (action.startsWith("receipts/"))
+        json(200, {
+          record: clone(session.record),
+          receipt: clone(session.receipts.get(match[3])?.receipt ?? null),
+        });
+      else throw fault(404);
+    } catch (error) {
+      json(error.code ?? 500, { unavailable: true });
+    }
+  });
+  return server;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  createReviewServer().listen(5194, "127.0.0.1", () =>
+    console.log("Local review example ready at http://127.0.0.1:5194"),
+  );
+}

package/examples/web-ai-sdk/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>SuperXD conversation with files</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/examples/web-ai-sdk/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "superxd-sdk-consumer",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1 --port 5300",
+    "build": "tsc --noEmit && vite build"
+  },
+  "dependencies": {
+    "@superxd-studio/adptr": "file:../..",
+    "ai": "7.0.126",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "typescript": "~6.0",
+    "vite": "^8.3.1"
+  }
+}

package/examples/web-ai-sdk/src/copy.ts

@@ -0,0 +1 @@
+export const exampleCopy = { description: "PNG, JPEG, PDF or text · up to 4 files · 5 MB each" };

package/examples/web-ai-sdk/src/main.tsx

@@ -0,0 +1,64 @@
+import { useEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { AttachmentController, ChatController } from "@superxd-studio/adptr/core";
+import { createAiSdkChatAdapter } from "@superxd-studio/adptr/ai-sdk";
+import { createHttpUploadAdapter } from "@superxd-studio/adptr/uploads";
+import {
+  Chat,
+  AttachmentPicker,
+  useAttachments,
+  useChatController,
+} from "@superxd-studio/adptr/web";
+import "@superxd-studio/adptr/styles.css";
+import "@superxd-studio/adptr/fonts.css";
+import { exampleCopy } from "./copy";
+
+function App() {
+  const [controller] = useState(
+    () =>
+      new ChatController(createAiSdkChatAdapter({ endpoint: "http://127.0.0.1:5193/chat" }), () =>
+        crypto.randomUUID(),
+      ),
+  );
+  const [uploads] = useState(
+    () =>
+      new AttachmentController(
+        createHttpUploadAdapter({
+          endpoint: "http://127.0.0.1:5193/uploads",
+          releaseEndpoint: (id) => `http://127.0.0.1:5193/files/${id}`,
+        }),
+        {
+          maxFiles: 4,
+          maxBytes: 5_000_000,
+          mediaTypes: ["image/png", "image/jpeg", "application/pdf", "text/plain"],
+        },
+        () => crypto.randomUUID(),
+      ),
+  );
+  useEffect(
+    () => () => {
+      controller.dispose();
+      uploads.dispose();
+    },
+    [controller, uploads],
+  );
+  const snapshot = useChatController(controller);
+  const queue = useAttachments(uploads);
+  return (
+    <main className="mx-auto max-w-3xl p-6">
+      <Chat
+        snapshot={snapshot}
+        actions={controller}
+        draftFiles={queue.items.flatMap((item) => (item.file ? [item.file] : []))}
+        isAttachmentBlocked={queue.items.some((item) => item.status !== "ready")}
+        onSent={uploads.transfer}
+        attachmentPicker={
+          <AttachmentPicker controller={uploads} description={exampleCopy.description} />
+        }
+      />
+    </main>
+  );
+}
+const root = document.getElementById("root");
+if (!root) throw new Error("Missing root");
+createRoot(root).render(<App />);

package/examples/web-ai-sdk/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/examples/web-generative/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>SuperXD structured response consumer</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/examples/web-generative/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "superxd-generative-consumer",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1 --port 5302",
+    "build": "tsc --noEmit && vite build"
+  },
+  "dependencies": {
+    "@superxd-studio/adptr": "file:../..",
+    "@assistant-ui/react": "0.15.22",
+    "@assistant-ui/react-generative-ui": "0.0.22",
+    "react-aria-components": "^1.21.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "typescript": "~6.0",
+    "vite": "^8.3.1"
+  }
+}

package/examples/web-generative/src/copy.ts

@@ -0,0 +1,42 @@
+export const copy = {
+  title: "Your task. Your decision.",
+  note: "Local example. Nothing is sent to a service.",
+  replace: "Update the supplied response",
+  reset: "Open a fresh response",
+  hostLabel: "Create this task",
+  hostDescription: "Save the reviewed title in this local example.",
+  receipt: "Task saved in this local example.",
+  taskTitle: "Task title",
+  initial: "Prepare the design review",
+  updated: "A different suggested title",
+  submit: "Create task",
+  trend: "Tasks this week",
+};
+export function taskSpec(title: string) {
+  return {
+    $type: "Card",
+    asForm: true,
+    title: copy.title,
+    confirm: { label: copy.submit, $action: { type: "create_task" } },
+    children: [
+      { $type: "Input", name: "title", label: copy.taskTitle, defaultValue: title, required: true },
+    ],
+  };
+}
+export const trendSpec = {
+  $type: "Card",
+  title: copy.trend,
+  children: [
+    {
+      $type: "Chart",
+      label: copy.trend,
+      variant: "bar",
+      showAxis: true,
+      data: [
+        { label: "Monday", value: 2 },
+        { label: "Tuesday", value: 3 },
+        { label: "Wednesday", value: 4 },
+      ],
+    },
+  ],
+};

package/examples/web-generative/src/main.tsx

@@ -0,0 +1,74 @@
+import { useState } from "react";
+import { createRoot } from "react-dom/client";
+import { Button } from "react-aria-components";
+import {
+  StructuredResponse,
+  type GenerativeActions,
+  type GenerativeReceipt,
+} from "@superxd-studio/adptr/generative";
+import "@superxd-studio/adptr/styles.css";
+import "@superxd-studio/adptr/fonts.css";
+import { copy, taskSpec, trendSpec } from "./copy";
+
+function App() {
+  const [suggested, setSuggested] = useState<string>(copy.initial);
+  const [response, setResponse] = useState(0);
+  const [actions] = useState<GenerativeActions>(() => {
+    const receipts = new Map<string, GenerativeReceipt>();
+    return {
+      create_task: {
+        kind: "mutate",
+        label: copy.hostLabel,
+        description: copy.hostDescription,
+        execute: async (request, signal) => {
+          if (signal.aborted) throw new Error("Aborted");
+          const prior = receipts.get(request.key);
+          if (prior) return prior;
+          const receipt: GenerativeReceipt = {
+            key: request.key,
+            type: request.action.type,
+            state: "complete",
+            message: copy.receipt,
+          };
+          receipts.set(request.key, receipt);
+          // Model a lost reply after recording a receipt. Lookup recovers without another write.
+          throw new Error("Local reply lost");
+        },
+        lookup: async (request, signal) =>
+          signal.aborted ? null : (receipts.get(request.key) ?? null),
+      },
+    };
+  });
+  return (
+    <main className="mx-auto flex max-w-2xl flex-col gap-6 bg-surface-muted p-6">
+      <h1 className="type-title text-fg-emphasis">{copy.title}</h1>
+      <p className="type-body text-fg-subtle">{copy.note}</p>
+      <div className="flex flex-wrap gap-3">
+        <Button
+          className="rounded-control border border-line-input bg-surface px-control-md-x py-control-y type-body text-fg data-focus-visible:focus-ring"
+          onPress={() => setSuggested(copy.updated)}
+        >
+          {copy.replace}
+        </Button>
+        <Button
+          className="rounded-control border border-line-input bg-surface px-control-md-x py-control-y type-body text-fg data-focus-visible:focus-ring"
+          onPress={() => {
+            setResponse((n) => n + 1);
+            setSuggested(copy.initial);
+          }}
+        >
+          {copy.reset}
+        </Button>
+      </div>
+      <StructuredResponse
+        responseId={`task-${response}`}
+        spec={taskSpec(suggested)}
+        actions={actions}
+      />
+      <StructuredResponse responseId="trend" spec={trendSpec} />
+    </main>
+  );
+}
+const root = document.getElementById("root");
+if (!root) throw new Error("Missing root");
+createRoot(root).render(<App />);

package/examples/web-generative/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowArbitraryExtensions": true
+  },
+  "include": ["src"]
+}

package/examples/web-independent/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>SuperXD independent consumer</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/examples/web-independent/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "superxd-independent-consumer",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1 --port 5300",
+    "build": "tsc --noEmit && vite build"
+  },
+  "dependencies": {
+    "@superxd-studio/adptr": "file:../..",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "typescript": "~6.0",
+    "vite": "^8.3.1"
+  }
+}

package/examples/web-independent/src/main.tsx

@@ -0,0 +1,32 @@
+import { useEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { ChatController } from "@superxd-studio/adptr/core";
+import { createHttpChatAdapter } from "@superxd-studio/adptr/custom";
+import { Chat, useChatController } from "@superxd-studio/adptr/web";
+import "@superxd-studio/adptr/styles.css";
+import "@superxd-studio/adptr/fonts.css";
+
+function App() {
+  const [controller] = useState(() => {
+    const session = crypto.randomUUID();
+    return new ChatController(
+      createHttpChatAdapter({
+        endpoint: "http://127.0.0.1:5192/chat",
+        conversationActions: true,
+        headers: () => ({ "x-demo-format": "rich", "x-demo-session": session }),
+      }),
+      () => crypto.randomUUID(),
+    );
+  });
+  const snapshot = useChatController(controller);
+  useEffect(() => () => controller.dispose(), [controller]);
+  return (
+    <main className="mx-auto max-w-3xl p-6">
+      <h1 className="type-title text-fg-emphasis">Your product. Your backend.</h1>
+      <Chat snapshot={snapshot} actions={controller} />
+    </main>
+  );
+}
+const root = document.getElementById("root");
+if (!root) throw new Error("Missing root");
+createRoot(root).render(<App />);