@superxd-studio/adptr 0.5.0

package/source/reusable/interactions/threads.ts

@@ -0,0 +1,126 @@
+import { z } from "zod";
+import { InteractionStore, identity, shortText, jsonSchema } from "./store.js";
+export const threadSummarySchema = z.strictObject({
+  id: identity,
+  title: shortText,
+  archived: z.boolean(),
+});
+export const threadDocumentSchema = threadSummarySchema.extend({ payload: jsonSchema });
+export type ThreadSummary = z.infer<typeof threadSummarySchema>;
+export type ThreadDocument = z.infer<typeof threadDocumentSchema>;
+export interface ThreadAdapter {
+  list(signal: AbortSignal): Promise<readonly ThreadSummary[]>;
+  load(id: string, signal: AbortSignal): Promise<ThreadDocument>;
+  rename(id: string, title: string, signal: AbortSignal): Promise<ThreadSummary>;
+  archive(id: string, archived: boolean, signal: AbortSignal): Promise<ThreadSummary>;
+}
+export interface ThreadSnapshot {
+  phase: "idle" | "listing" | "opening" | "mutating" | "ready" | "error";
+  items: readonly ThreadSummary[];
+  selected?: ThreadDocument;
+  pendingId?: string;
+  operation?: "list" | "open" | "rename" | "archive";
+}
+export class ThreadController extends InteractionStore<ThreadSnapshot> {
+  constructor(
+    private adapter: ThreadAdapter,
+    private canLeave: () => boolean = () => true,
+  ) {
+    super({ phase: "idle", items: [] });
+  }
+  refresh() {
+    if (this.disposed || ["listing", "mutating", "opening"].includes(this.state.phase))
+      return false;
+    const { token, signal } = this.request();
+    this.publish({ ...this.state, phase: "listing", operation: "list" });
+    void (async () => {
+      try {
+        const items = z
+          .array(threadSummarySchema)
+          .max(1000)
+          .parse(await this.adapter.list(signal));
+        if (new Set(items.map((item) => item.id)).size !== items.length)
+          throw new Error("Duplicate thread");
+        if (this.current(token))
+          this.publish({ ...this.state, items, phase: "ready", operation: undefined });
+      } catch {
+        if (this.current(token)) this.publish({ ...this.state, phase: "error" });
+      }
+    })();
+    return true;
+  }
+  open(id: string) {
+    if (
+      this.disposed ||
+      ["listing", "mutating"].includes(this.state.phase) ||
+      !this.state.items.some((item) => item.id === id) ||
+      !this.canLeave()
+    )
+      return false;
+    const { token, signal } = this.request();
+    this.publish({ ...this.state, phase: "opening", pendingId: id, operation: "open" });
+    void (async () => {
+      try {
+        const selected = threadDocumentSchema.parse(await this.adapter.load(id, signal));
+        if (selected.id !== id) throw new Error("Wrong thread");
+        if (this.current(token))
+          this.publish({
+            ...this.state,
+            selected,
+            phase: "ready",
+            pendingId: undefined,
+            operation: undefined,
+          });
+      } catch {
+        if (this.current(token))
+          this.publish({ ...this.state, phase: "error", pendingId: undefined });
+      }
+    })();
+    return true;
+  }
+  rename(id: string, title: string) {
+    const parsed = shortText.safeParse(title);
+    if (!parsed.success) return false;
+    return this.mutate(id, "rename", (signal) => this.adapter.rename(id, parsed.data, signal));
+  }
+  archive(id: string, archived: boolean) {
+    if (this.state.selected?.id === id && !this.canLeave()) return false;
+    return this.mutate(id, "archive", (signal) => this.adapter.archive(id, archived, signal));
+  }
+  private mutate(
+    id: string,
+    operation: "rename" | "archive",
+    run: (signal: AbortSignal) => Promise<ThreadSummary>,
+  ) {
+    if (
+      this.disposed ||
+      !["ready", "error"].includes(this.state.phase) ||
+      !this.state.items.some((item) => item.id === id)
+    )
+      return false;
+    const { token, signal } = this.request();
+    this.publish({ ...this.state, phase: "mutating", pendingId: id, operation });
+    void (async () => {
+      try {
+        const item = threadSummarySchema.parse(await run(signal));
+        if (item.id !== id) throw new Error("Wrong thread");
+        if (this.current(token))
+          this.publish({
+            ...this.state,
+            phase: "ready",
+            pendingId: undefined,
+            operation: undefined,
+            items: this.state.items.map((old) => (old.id === id ? item : old)),
+            selected:
+              this.state.selected?.id === id
+                ? { ...this.state.selected, ...item }
+                : this.state.selected,
+          });
+      } catch {
+        if (this.current(token))
+          this.publish({ ...this.state, phase: "error", pendingId: undefined });
+      }
+    })();
+    return true;
+  }
+}

package/source/reusable/interactions/web.tsx

@@ -0,0 +1,574 @@
+import { useInteractionCopy } from "./context.js";
+import { useLayoutEffect, useRef, useState, useSyncExternalStore, type ReactNode } from "react";
+import { Button } from "../../components/button.js";
+import { TextField } from "../../components/text-field.js";
+import { Callout } from "../../components/callout.js";
+import { Spinner } from "../../components/spinner.js";
+import { Card, Badge, RadioGroup, Select, Tabs } from "../ui/index.js";
+import { CanvasSequence, CanvasStage } from "../../components/canvas/index.js";
+import { ToolCall } from "./presentation.js";
+import type { AgentController, AgentSnapshot } from "./agent.js";
+import type { ArtifactController, ArtifactSnapshot } from "./artifact.js";
+import type { FeedbackController, FeedbackSnapshot } from "./feedback.js";
+import type { ThreadController, ThreadSnapshot, ThreadDocument } from "./threads.js";
+
+/** Presentations receive immutable snapshots; retained canvas frames never mount an owner. */
+function Observed({
+  phase,
+  label,
+  children,
+  terminal = false,
+}: {
+  phase: string;
+  label: string;
+  children: ReactNode;
+  terminal?: boolean;
+}) {
+  const root = useRef<HTMLDivElement>(null);
+  const initiated = useRef(false);
+  useLayoutEffect(() => {
+    if (initiated.current && document.activeElement === document.body)
+      root.current?.focus({ preventScroll: true });
+    initiated.current = false;
+  }, [phase]);
+  return (
+    <CanvasStage phase={phase} label={label} terminal={terminal} frameClassName="max-w-2xl">
+      <div
+        ref={root}
+        tabIndex={-1}
+        role="group"
+        aria-label={label}
+        onPointerDownCapture={() => {
+          initiated.current = true;
+        }}
+        onKeyDownCapture={() => {
+          initiated.current = true;
+        }}
+        onClickCapture={() => {
+          initiated.current = true;
+        }}
+        className="mx-auto w-full max-w-2xl min-w-0 outline-none"
+      >
+        {children}
+      </div>
+    </CanvasStage>
+  );
+}
+export function AgentSupervision({
+  controller,
+  label,
+}: {
+  controller: AgentController;
+  label?: string;
+}) {
+  const copy = useInteractionCopy();
+  label ??= copy.agent;
+  return (
+    <CanvasSequence>
+      <AgentLive controller={controller} label={label} />
+    </CanvasSequence>
+  );
+}
+function AgentLive({ controller, label }: { controller: AgentController; label: string }) {
+  const copy = useInteractionCopy();
+
+  const state = useSyncExternalStore(
+    controller.subscribe,
+    controller.getSnapshot,
+    controller.getSnapshot,
+  );
+  return (
+    <Observed
+      phase={`agent-${state.completed.length}-${state.phase}`}
+      label={copy.agentStates[state.phase]}
+      terminal={state.phase === "complete" || state.phase === "denied"}
+    >
+      <AgentPanel state={state} label={label} controller={controller} />
+    </Observed>
+  );
+}
+function AgentPanel({
+  state,
+  label,
+  controller,
+}: {
+  state: AgentSnapshot;
+  label: string;
+  controller: AgentController;
+}) {
+  const copy = useInteractionCopy();
+
+  return (
+    <Card aria-label={label}>
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <h2 className="type-heading text-fg-emphasis">{label}</h2>
+        <span role="status" className="type-caption text-fg-subtle">
+          {copy.agentStates[state.phase]}
+        </span>
+      </div>
+      <ol aria-label={copy.plan} className="mt-4 flex flex-col gap-3">
+        {state.steps.map((step) => (
+          <li key={step.id} className="flex flex-wrap items-center justify-between gap-3 type-body">
+            <span>{step.title}</span>
+            <Badge
+              tone={
+                state.completed.some((result) => result.stepId === step.id) ? "success" : "neutral"
+              }
+            >
+              {state.completed.some((result) => result.stepId === step.id)
+                ? copy.toolStates.completed
+                : copy.toolStates.pending}
+            </Badge>
+          </li>
+        ))}
+      </ol>
+      {state.completed.map((result) => (
+        <ToolCall
+          key={result.requestId}
+          title={state.steps.find((step) => step.id === result.stepId)?.title ?? copy.tool}
+          status="completed"
+          input={state.steps.find((step) => step.id === result.stepId)?.input ?? null}
+          output={result.output}
+        />
+      ))}
+      {state.request && (
+        <div className="mt-6 flex flex-col gap-4">
+          <ToolCall
+            title={state.request.step.title}
+            status={
+              state.phase === "approval"
+                ? "approval"
+                : state.phase === "running"
+                  ? "running"
+                  : state.phase === "failed"
+                    ? "rejected"
+                    : "unknown"
+            }
+            input={state.request.step.input}
+          />
+          <p className="type-body">
+            <span className="type-label">{copy.scope}: </span>
+            {state.request.step.scope}
+          </p>
+          {state.phase === "approval" && (
+            <p className="type-caption text-fg-subtle">{copy.approvalHint}</p>
+          )}
+        </div>
+      )}
+      {state.progress && (
+        <p role="status" className="mt-4 type-body">
+          {state.progress}
+        </p>
+      )}
+      {state.phase === "uncertain" && (
+        <Callout tone="attention" className="mt-4">
+          {copy.unknown}
+        </Callout>
+      )}
+      {state.reason && (
+        <Callout tone="error" className="mt-4">
+          {state.reason}
+        </Callout>
+      )}
+      {state.phase === "expired" && (
+        <Callout tone="attention" className="mt-4">
+          {copy.expires}
+        </Callout>
+      )}
+      {state.phase === "denied" && <p className="mt-4 type-body">{copy.denied}</p>}
+      {state.phase === "complete" && <p className="mt-4 type-body">{copy.complete}</p>}
+      <div className="mt-6 flex flex-wrap gap-3">
+        {state.phase === "ready" && (
+          <Button onPress={() => controller.next()}>{copy.request}</Button>
+        )}
+        {state.phase === "approval" && (
+          <>
+            <Button variant="primary" onPress={() => controller.approve()}>
+              {copy.allow}
+            </Button>
+            <Button onPress={() => controller.deny()}>{copy.deny}</Button>
+          </>
+        )}
+        {state.phase === "running" && (
+          <Button onPress={() => controller.stop()}>{copy.stop}</Button>
+        )}
+        {state.phase === "uncertain" && (
+          <Button onPress={() => controller.check()}>{copy.check}</Button>
+        )}
+        {(state.phase === "failed" || state.phase === "expired") && (
+          <Button onPress={() => controller.renew()}>{copy.renew}</Button>
+        )}
+        {state.phase === "checking" && <Spinner />}
+      </div>
+    </Card>
+  );
+}
+export function ArtifactWorkspace({
+  controller,
+  label,
+}: {
+  controller: ArtifactController;
+  label?: string;
+}) {
+  const copy = useInteractionCopy();
+  label ??= copy.artifact;
+  return (
+    <CanvasSequence>
+      <ArtifactLive controller={controller} label={label} />
+    </CanvasSequence>
+  );
+}
+function ArtifactLive({ controller, label }: { controller: ArtifactController; label: string }) {
+  const copy = useInteractionCopy();
+
+  const state = useSyncExternalStore(
+    controller.subscribe,
+    controller.getSnapshot,
+    controller.getSnapshot,
+  );
+  return (
+    <Observed
+      phase={`artifact-${state.record?.revision ?? "idle"}-${state.phase}`}
+      label={copy.artifactStates[state.phase]}
+    >
+      <ArtifactPanel state={state} label={label} controller={controller} />
+    </Observed>
+  );
+}
+function ArtifactPanel({
+  state,
+  label,
+  controller,
+}: {
+  state: ArtifactSnapshot;
+  label: string;
+  controller: ArtifactController;
+}) {
+  const copy = useInteractionCopy();
+
+  const [revision, setRevision] = useState<string>();
+  const record = state.record;
+  const historical = record?.history.find((item) => item.revision === revision);
+  return (
+    <Card aria-label={label}>
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <h2 className="type-heading text-fg-emphasis">{record?.title ?? label}</h2>
+        <span role="status" className="type-caption text-fg-subtle">
+          {copy.artifactStates[state.phase]}
+        </span>
+      </div>
+      {(state.phase === "loading" || state.phase === "checking") && <Spinner />}
+      {state.phase === "idle" && <p className="mt-4 type-body">{copy.idleArtifact}</p>}
+      {state.phase === "load-error" && (
+        <Callout
+          tone="error"
+          className="mt-4"
+          actions={
+            <Button size="sm" onPress={() => state.loadId && controller.open(state.loadId)}>
+              {copy.retry}
+            </Button>
+          }
+        >
+          {copy.loadError}
+        </Callout>
+      )}
+      {record && (
+        <div className="mt-4 flex flex-col gap-4">
+          <Badge>
+            {copy.revision}: {record.revision}
+          </Badge>
+          {state.phase === "viewing" && record.history.length > 0 && (
+            <Select
+              label={copy.revision}
+              options={[
+                { id: record.revision, label: record.revision },
+                ...record.history
+                  .filter((item) => item.revision !== record.revision)
+                  .map((item) => ({ id: item.revision, label: item.revision })),
+              ]}
+              selectedKey={historical?.revision ?? record.revision}
+              onSelectionChange={(key) => setRevision(key === null ? undefined : String(key))}
+            />
+          )}
+          {state.phase === "conflict" && state.latest ? (
+            <>
+              <Callout tone="attention">{copy.conflict}</Callout>
+              <Tabs
+                label={copy.revision}
+                items={[
+                  {
+                    id: "draft",
+                    label: copy.localDraft,
+                    content: (
+                      <pre className="type-body break-words whitespace-pre-wrap">{state.draft}</pre>
+                    ),
+                  },
+                  {
+                    id: "latest",
+                    label: copy.latest,
+                    content: (
+                      <pre className="type-body break-words whitespace-pre-wrap">
+                        {state.latest.content}
+                      </pre>
+                    ),
+                  },
+                ]}
+              />
+              <div className="flex flex-wrap gap-3">
+                <Button onPress={() => controller.adoptLatest(false)}>{copy.useLatest}</Button>
+                <Button onPress={() => controller.adoptLatest(true)}>{copy.keepDraft}</Button>
+              </div>
+            </>
+          ) : state.phase === "viewing" ? (
+            <>
+              <pre className="type-body break-words whitespace-pre-wrap">
+                {historical?.content ?? record.content}
+              </pre>
+              {record.canEdit && !historical && (
+                <Button onPress={() => controller.edit(record.content)}>{copy.edit}</Button>
+              )}
+            </>
+          ) : (
+            <TextField
+              label={copy.artifactContent}
+              multiline
+              value={state.draft}
+              onChange={(value) => controller.edit(value)}
+              isDisabled={state.phase !== "editing"}
+            />
+          )}
+          {state.reason && <Callout tone="error">{state.reason}</Callout>}
+          {state.phase === "editing" && (
+            <div className="flex flex-wrap gap-3">
+              <Button
+                variant="primary"
+                isDisabled={state.draft === record.content}
+                onPress={() => controller.save()}
+              >
+                {copy.save}
+              </Button>
+              <Button onPress={() => controller.discard()}>{copy.discard}</Button>
+            </div>
+          )}
+          {state.phase === "unknown" && (
+            <Callout
+              tone="attention"
+              actions={<Button onPress={() => controller.check()}>{copy.check}</Button>}
+            >
+              {copy.unknown}
+            </Callout>
+          )}
+        </div>
+      )}
+    </Card>
+  );
+}
+export function ResponseFeedback({
+  controller,
+  label,
+}: {
+  controller: FeedbackController;
+  label?: string;
+}) {
+  const copy = useInteractionCopy();
+  label ??= copy.feedback;
+  const state = useSyncExternalStore(
+    controller.subscribe,
+    controller.getSnapshot,
+    controller.getSnapshot,
+  );
+  return <FeedbackPanel state={state} label={label} controller={controller} />;
+}
+function FeedbackPanel({
+  state,
+  label,
+  controller,
+}: {
+  state: FeedbackSnapshot;
+  label: string;
+  controller: FeedbackController;
+}) {
+  const copy = useInteractionCopy();
+
+  const locked = state.phase === "saving" || state.phase === "error";
+  return (
+    <Card aria-label={label}>
+      <RadioGroup
+        label={label}
+        options={[
+          { id: "helpful", label: copy.helpful },
+          { id: "unhelpful", label: copy.unhelpful },
+        ]}
+        value={state.rating ?? ""}
+        onChange={(value) => controller.edit(value as "helpful" | "unhelpful")}
+        isDisabled={locked}
+      />
+      <TextField
+        className="mt-4"
+        label={copy.comment}
+        multiline
+        value={state.comment}
+        onChange={(value) => controller.edit(state.rating, value)}
+        isDisabled={locked}
+      />
+      <div className="mt-4">
+        <Button
+          isDisabled={!state.rating || state.phase === "saving" || state.phase === "saved"}
+          onPress={() => controller.save()}
+        >
+          {state.phase === "error" ? copy.retry : copy.sendFeedback}
+        </Button>
+      </div>
+      <p role="status" className="mt-3 type-body text-fg-subtle">
+        {state.phase === "saved"
+          ? copy.savedFeedback
+          : state.phase === "error"
+            ? copy.failedFeedback
+            : state.phase === "saving"
+              ? copy.saving
+              : ""}
+      </p>
+    </Card>
+  );
+}
+export function ConversationHistory({
+  controller,
+  renderThread,
+  label,
+}: {
+  controller: ThreadController;
+  renderThread: (thread: ThreadDocument) => ReactNode;
+  label?: string;
+}) {
+  const copy = useInteractionCopy();
+  label ??= copy.threads;
+  const state = useSyncExternalStore(
+    controller.subscribe,
+    controller.getSnapshot,
+    controller.getSnapshot,
+  );
+  return (
+    <HistoryPanel state={state} controller={controller} renderThread={renderThread} label={label} />
+  );
+}
+function HistoryPanel({
+  state,
+  controller,
+  renderThread,
+  label,
+}: {
+  state: ThreadSnapshot;
+  controller: ThreadController;
+  renderThread: (thread: ThreadDocument) => ReactNode;
+  label: string;
+}) {
+  const copy = useInteractionCopy();
+
+  const [view, setView] = useState("active");
+  const [editing, setEditing] = useState<string>();
+  const [title, setTitle] = useState("");
+  const root = useRef<HTMLDivElement>(null);
+  const busy = !["ready", "error"].includes(state.phase);
+  const items = state.items.filter((item) => item.archived === (view === "archived"));
+  return (
+    <div ref={root} role="group" aria-label={label} tabIndex={-1} className="min-w-0 outline-none">
+      <Card aria-label={label}>
+        <div className="flex flex-wrap items-center justify-between gap-3">
+          <h2 className="type-heading text-fg-emphasis">{label}</h2>
+          <Button
+            size="sm"
+            isDisabled={busy && state.phase !== "idle"}
+            onPress={() => controller.refresh()}
+          >
+            {copy.refresh}
+          </Button>
+        </div>
+        <Select
+          className="mt-4"
+          label={label}
+          selectedKey={view}
+          onSelectionChange={(key) => setView(String(key))}
+          options={[
+            { id: "active", label: copy.active },
+            { id: "archived", label: copy.archived },
+          ]}
+        />
+        {state.phase === "error" && (
+          <Callout tone="error" className="mt-4">
+            {copy.threadError}
+          </Callout>
+        )}
+        <ul className="mt-4 flex flex-col gap-4">
+          {items.map((item) => (
+            <li
+              key={item.id}
+              className="flex flex-col gap-3 rounded-control border border-line-subtle p-3"
+            >
+              <Button
+                className="justify-start text-left whitespace-normal"
+                isDisabled={["listing", "mutating"].includes(state.phase)}
+                onPress={() => {
+                  if (controller.open(item.id)) setEditing(undefined);
+                }}
+              >
+                {item.title}
+              </Button>
+              <div className="flex flex-wrap gap-3">
+                <Button
+                  size="sm"
+                  isDisabled={busy}
+                  onPress={() => {
+                    setEditing(item.id);
+                    setTitle(item.title);
+                  }}
+                >
+                  {copy.rename}
+                </Button>
+                <Button
+                  size="sm"
+                  isDisabled={busy}
+                  onPress={() => {
+                    // Archiving removes this row after confirmation; keep the visitor in the list.
+                    if (controller.archive(item.id, !item.archived))
+                      root.current?.focus({ preventScroll: true });
+                  }}
+                >
+                  {item.archived ? copy.restore : copy.archive}
+                </Button>
+              </div>
+              {editing === item.id && (
+                <div className="flex flex-col gap-3">
+                  <TextField
+                    label={copy.title}
+                    value={title}
+                    onChange={setTitle}
+                    isDisabled={busy}
+                  />
+                  <Button
+                    isDisabled={busy || !title.trim()}
+                    onPress={() => controller.rename(item.id, title)}
+                  >
+                    {copy.saveTitle}
+                  </Button>
+                </div>
+              )}
+            </li>
+          ))}
+        </ul>
+        {!items.length && state.phase !== "idle" && (
+          <p className="mt-4 type-body text-fg-subtle">{copy.noThreads}</p>
+        )}
+        <div role="status" className="mt-4 type-caption text-fg-subtle">
+          {busy && state.phase !== "idle" ? copy.loading : ""}
+        </div>
+        <div className="mt-6 min-w-0">
+          {state.selected ? (
+            renderThread(state.selected)
+          ) : (
+            <p className="type-body text-fg-subtle">{copy.chooseThread}</p>
+          )}
+        </div>
+      </Card>
+    </div>
+  );
+}