@carlonicora/nextjs-jsonapi 1.112.1 → 1.114.0

package/src/features/assistant/contexts/AssistantContext.tsx

@@ -26,6 +26,11 @@ interface AssistantContextValue {
   startNew(): void;
   renameThread(id: string, title: string): Promise<void>;
   deleteThread(id: string): Promise<void>;
+  /** When true, create/append route to the operator-engine endpoints. */
+  operatorMode: boolean;
+  setOperatorMode(value: boolean): void;
+  /** Appends a message returned outside the send flow (e.g. an approve/deny resume). */
+  appendResolvedMessage(message: AssistantMessageInterface): void;
 }
 
 const AssistantContext = createContext<AssistantContextValue | undefined>(undefined);
@@ -77,6 +82,12 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
   const [sending, setSending] = useState<boolean>(false);
   const [status, setStatus] = useState<string | undefined>(undefined);
   const [failedMessageIds, setFailedMessageIds] = useState<Set<string>>(() => new Set());
+  // The engine is persisted on the Assistant resource: an existing operator
+  // thread must keep routing to the operator endpoints after a reload, so the
+  // initial mode is derived from the hydrated thread instead of defaulting off.
+  const [operatorMode, setOperatorMode] = useState<boolean>(
+    () => dehydratedAssistant?.jsonApi?.attributes?.engine === "operator",
+  );
   const { socket } = useSocketContext();
 
   const sendMessage = useCallback(
@@ -101,11 +112,14 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
 
       try {
         if (!assistant) {
-          const created = await AssistantService.create({
+          const input = {
             firstMessage: trimmed,
             howToMode: opts?.howToMode,
             limitToHowToId: opts?.limitToHowToId,
-          });
+          };
+          const created = operatorMode
+            ? await AssistantService.createOperator(input)
+            : await AssistantService.create(input);
           const msgs = await AssistantMessageService.findByAssistant({ assistantId: created.id });
           setAssistant(created);
           setMessages(msgs);
@@ -114,12 +128,17 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
             window.history.replaceState(null, "", `/assistants/${created.id}`);
           }
         } else {
-          const result = await AssistantService.appendMessage({
-            assistantId: assistant.id,
-            content: trimmed,
-            howToMode: opts?.howToMode,
-            limitToHowToId: opts?.limitToHowToId,
-          });
+          const result = operatorMode
+            ? await AssistantService.appendMessageOperator({
+                assistantId: assistant.id,
+                content: trimmed,
+              })
+            : await AssistantService.appendMessage({
+                assistantId: assistant.id,
+                content: trimmed,
+                howToMode: opts?.howToMode,
+                limitToHowToId: opts?.limitToHowToId,
+              });
           setMessages((prev) => [...stripOptimistic(prev), ...result]);
         }
       } catch {
@@ -134,9 +153,13 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
         setStatus(undefined);
       }
     },
-    [assistant, messages, socket],
+    [assistant, messages, socket, operatorMode],
   );
 
+  const appendResolvedMessage = useCallback((message: AssistantMessageInterface) => {
+    setMessages((prev) => (prev.some((m) => m.id === message.id) ? prev : [...prev, message]));
+  }, []);
+
   const retrySend = useCallback(
     async (tempId: string) => {
       const failed = messages.find((m) => m.id === tempId);
@@ -163,6 +186,10 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
       ]);
       setAssistant(target);
       setMessages(msgs);
+      // Route follow-up sends by the thread's persisted engine: operator
+      // threads stay on the operator endpoints, everything else (engine
+      // absent) keeps the default responder flow.
+      setOperatorMode(target.engine === "operator");
       if (manageUrl && typeof window !== "undefined") {
         window.history.replaceState(null, "", `/assistants/${id}`);
       }
@@ -180,6 +207,7 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
     setAssistant(undefined);
     setMessages([]);
     setFailedMessageIds(new Set());
+    setOperatorMode(false);
     if (manageUrl && typeof window !== "undefined") {
       window.history.replaceState(null, "", "/assistants");
     }
@@ -228,6 +256,9 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
       startNew,
       renameThread,
       deleteThread,
+      operatorMode,
+      setOperatorMode,
+      appendResolvedMessage,
     }),
     [
       assistant,
@@ -243,6 +274,8 @@ export function AssistantProvider({ children, dehydratedAssistant, dehydratedMes
       startNew,
       renameThread,
       deleteThread,
+      operatorMode,
+      appendResolvedMessage,
     ],
   );
 

package/src/features/assistant/contexts/__tests__/AssistantContext.spec.tsx

@@ -18,22 +18,32 @@ function wrapper({ children }: { children: React.ReactNode }) {
   return <AssistantProvider>{children}</AssistantProvider>;
 }
 
-function buildAssistantStub({ id, title = "Stub" }: { id: string; title?: string }) {
-  return { id, title, messageCount: 0, type: "assistants", createdAt: new Date(), updatedAt: new Date() } as any;
+function buildAssistantStub({ id, title = "Stub", engine }: { id: string; title?: string; engine?: string }) {
+  return {
+    id,
+    title,
+    engine,
+    messageCount: 0,
+    type: "assistants",
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  } as any;
 }
 
 function buildAssistantDehydrated({
   id,
   title = "Stub",
+  engine,
 }: {
   id: string;
   title?: string;
+  engine?: string;
 }): JsonApiHydratedDataInterface {
   return {
     jsonApi: {
       type: "assistants",
       id,
-      attributes: { title, messageCount: 0 },
+      attributes: { title, messageCount: 0, ...(engine !== undefined ? { engine } : {}) },
     },
     included: [],
   };
@@ -123,6 +133,87 @@ describe("AssistantContext", () => {
     expect(replaceState).toHaveBeenCalledWith(null, "", "/assistants/a-3");
   });
 
+  it("selectThread on an operator thread enables operatorMode and routes follow-ups to the operator endpoint", async () => {
+    const target = buildAssistantStub({ id: "a-op", title: "Operator", engine: "operator" });
+    AssistantService.findOne = vi.fn().mockResolvedValue(target);
+    AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([]);
+    AssistantService.appendMessage = vi.fn().mockResolvedValue([]);
+    AssistantService.appendMessageOperator = vi.fn().mockResolvedValue([]);
+    vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider>{children}</AssistantProvider>,
+    });
+    await act(async () => {
+      await result.current.selectThread("a-op");
+    });
+    expect(result.current.operatorMode).toBe(true);
+
+    await act(async () => {
+      await result.current.sendMessage("continue");
+    });
+    expect(AssistantService.appendMessageOperator).toHaveBeenCalledWith({ assistantId: "a-op", content: "continue" });
+    expect(AssistantService.appendMessage).not.toHaveBeenCalled();
+  });
+
+  it("selectThread on a responder thread (engine absent) resets operatorMode and keeps the responder endpoint", async () => {
+    const operatorThread = buildAssistantStub({ id: "a-op", engine: "operator" });
+    const responderThread = buildAssistantStub({ id: "a-resp" });
+    AssistantService.findOne = vi.fn().mockResolvedValueOnce(operatorThread).mockResolvedValueOnce(responderThread);
+    AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([]);
+    AssistantService.appendMessage = vi.fn().mockResolvedValue([]);
+    AssistantService.appendMessageOperator = vi.fn().mockResolvedValue([]);
+    vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider>{children}</AssistantProvider>,
+    });
+    await act(async () => {
+      await result.current.selectThread("a-op");
+    });
+    expect(result.current.operatorMode).toBe(true);
+    await act(async () => {
+      await result.current.selectThread("a-resp");
+    });
+    expect(result.current.operatorMode).toBe(false);
+
+    await act(async () => {
+      await result.current.sendMessage("hello");
+    });
+    expect(AssistantService.appendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ assistantId: "a-resp", content: "hello" }),
+    );
+    expect(AssistantService.appendMessageOperator).not.toHaveBeenCalled();
+  });
+
+  it("hydrating an operator thread (reload) initialises operatorMode and routes sends to the operator endpoint", async () => {
+    const existing = buildAssistantDehydrated({ id: "a-op", title: "Operator", engine: "operator" });
+    AssistantService.appendMessage = vi.fn().mockResolvedValue([]);
+    AssistantService.appendMessageOperator = vi.fn().mockResolvedValue([]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider dehydratedAssistant={existing}>{children}</AssistantProvider>,
+    });
+    expect(result.current.operatorMode).toBe(true);
+
+    await act(async () => {
+      await result.current.sendMessage("after reload");
+    });
+    expect(AssistantService.appendMessageOperator).toHaveBeenCalledWith({
+      assistantId: "a-op",
+      content: "after reload",
+    });
+    expect(AssistantService.appendMessage).not.toHaveBeenCalled();
+  });
+
+  it("hydrating a responder thread (engine absent) keeps operatorMode off", () => {
+    const existing = buildAssistantDehydrated({ id: "a-resp", title: "Responder" });
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider dehydratedAssistant={existing}>{children}</AssistantProvider>,
+    });
+    expect(result.current.operatorMode).toBe(false);
+  });
+
   it("renameThread calls the service + updates active assistant title", async () => {
     AssistantService.rename = vi.fn().mockResolvedValue(undefined);
     const active = buildAssistantDehydrated({ id: "a-1", title: "Old" });

package/src/features/assistant/data/Assistant.ts

@@ -4,6 +4,7 @@ import { AssistantInput, AssistantInterface } from "./AssistantInterface";
 export class Assistant extends AbstractApiData implements AssistantInterface {
   private _title?: string;
   private _messageCount?: number;
+  private _engine?: string;
 
   get title(): string {
     return this._title ?? "";
@@ -13,9 +14,14 @@ export class Assistant extends AbstractApiData implements AssistantInterface {
     return this._messageCount ?? 0;
   }
 
+  get engine(): string | undefined {
+    return this._engine;
+  }
+
   rehydrate(data: JsonApiHydratedDataInterface): this {
     super.rehydrate(data);
     this._title = data.jsonApi.attributes?.title;
+    this._engine = data.jsonApi.attributes?.engine;
     const fromMeta = data.jsonApi.meta?.messageCount;
     const fromAttrs = data.jsonApi.attributes?.messageCount;
     this._messageCount = typeof fromMeta === "number" ? fromMeta : typeof fromAttrs === "number" ? fromAttrs : 0;

package/src/features/assistant/data/AssistantInterface.ts

@@ -10,4 +10,6 @@ export type AssistantInput = {
 export interface AssistantInterface extends ApiDataInterface {
   get title(): string;
   get messageCount(): number;
+  /** Agent engine the thread runs on — `"operator"` or undefined (responder). */
+  get engine(): string | undefined;
 }

package/src/features/assistant/data/AssistantService.ts

@@ -31,6 +31,20 @@ export class AssistantService extends AbstractService {
     });
   }
 
+  /**
+   * Creates an assistant whose first turn runs on the operator engine
+   * (durable checkpointing + approval gates). Mirrors `create()` against the
+   * standalone operator module's create route (`POST operator`).
+   */
+  static async createOperator(params: AssistantInput): Promise<AssistantInterface> {
+    return this.callApi({
+      type: Modules.Assistant,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: "operator" }).generate(),
+      input: params,
+    });
+  }
+
   /**
    * Sends a new user message to an existing assistant thread. The agent turn
    * runs synchronously; the response is a two-element list: [user, assistant].
@@ -63,6 +77,30 @@ export class AssistantService extends AbstractService {
     });
   }
 
+  /**
+   * Operator-engine variant of `appendMessage()`. Targets
+   * `POST operator/:assistantId/assistant-messages`; the turn may freeze on a
+   * destructive tool call, in which case the returned list ends with an
+   * `approval-request` assistant message linked to a pending AssistantAction.
+   */
+  static async appendMessageOperator(params: {
+    assistantId: string;
+    content: string;
+  }): Promise<AssistantMessageInterface[]> {
+    const message = new AssistantMessage();
+    return this.callApi<AssistantMessageInterface[]>({
+      type: Modules.AssistantMessage,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: "operator",
+        id: params.assistantId,
+        childEndpoint: Modules.AssistantMessage,
+      }).generate(),
+      input: message.createAppendMessageJsonApi({ content: params.content }),
+      overridesJsonApiCreation: true,
+    });
+  }
+
   static async rename(params: { id: string; title: string }): Promise<void> {
     await this.callApi({
       type: Modules.Assistant,

package/src/features/assistant/data/__tests__/Assistant.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { Assistant } from "../Assistant";
+
+describe("Assistant model", () => {
+  it("rehydrates engine from attributes (operator thread)", () => {
+    const assistant = new Assistant().rehydrate({
+      jsonApi: { type: "assistants", id: "a-1", attributes: { title: "T", engine: "operator" } },
+      included: [],
+    });
+    expect(assistant.engine).toBe("operator");
+    expect(assistant.title).toBe("T");
+  });
+
+  it("leaves engine undefined when the attribute is absent (responder thread)", () => {
+    const assistant = new Assistant().rehydrate({
+      jsonApi: { type: "assistants", id: "a-2", attributes: { title: "T" } },
+      included: [],
+    });
+    expect(assistant.engine).toBeUndefined();
+  });
+
+  it("preserves engine through dehydrate/rehydrate round-trips", () => {
+    const original = new Assistant().rehydrate({
+      jsonApi: { type: "assistants", id: "a-3", attributes: { title: "T", engine: "operator" } },
+      included: [],
+    });
+    const roundTripped = new Assistant().rehydrate(original.dehydrate());
+    expect(roundTripped.engine).toBe("operator");
+  });
+});

package/src/features/assistant-message/AssistantMessageModule.ts

@@ -21,8 +21,10 @@ export const AssistantMessageModule = (factory: ModuleFactory) =>
             `suggestedQuestions`,
             `inputTokens`,
             `outputTokens`,
+            `messageType`,
             `references`,
             `citations`,
+            `action`,
           ]),
           createJsonApiInclusion("chunks", [`content`, `nodeId`, `nodeType`, `imagePath`, `source`]),
           createJsonApiInclusion("users", [`name`, `avatar`]),

package/src/features/assistant-message/components/MessageItem.tsx

@@ -2,20 +2,36 @@
 
 import { useTranslations } from "next-intl";
 import { Sparkles, AlertCircle } from "lucide-react";
+import type { ReactNode } from "react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import type { AssistantMessageInterface } from "../data/AssistantMessageInterface";
 import { MessageSourcesContainer } from "./parts/MessageSourcesContainer";
 
+/**
+ * Render slot for `approval-request` messages. The approval card lives in the
+ * consuming app (it depends on the app-registered AssistantAction module), so
+ * the chat renderer receives it as a function instead of importing it.
+ */
+export type ApprovalActionRenderer = (message: AssistantMessageInterface) => ReactNode;
+
 interface Props {
   message: AssistantMessageInterface;
   isLatestAssistant: boolean;
   onSelectFollowUp: (q: string) => void;
   failedMessageIds?: Set<string>;
   onRetry?: (tempId: string) => void;
+  renderApprovalAction?: ApprovalActionRenderer;
 }
 
-export function MessageItem({ message, isLatestAssistant, onSelectFollowUp, failedMessageIds, onRetry }: Props) {
+export function MessageItem({
+  message,
+  isLatestAssistant,
+  onSelectFollowUp,
+  failedMessageIds,
+  onRetry,
+  renderApprovalAction,
+}: Props) {
   const t = useTranslations();
   const isUser = message.role === "user";
   const isFailed = isUser && !!failedMessageIds?.has(message.id);
@@ -39,6 +55,8 @@ export function MessageItem({ message, isLatestAssistant, onSelectFollowUp, fail
     );
   }
 
+  const isApprovalRequest = message.messageType === "approval-request" && !!renderApprovalAction;
+
   return (
     <div className="flex min-w-0 max-w-[78%] flex-col gap-1.5">
       <div className="text-muted-foreground flex items-center gap-2 pl-1 text-xs">
@@ -47,9 +65,13 @@ export function MessageItem({ message, isLatestAssistant, onSelectFollowUp, fail
         </span>
         <span>{t("features.assistant.agent_name")}</span>
       </div>
-      <div className="bg-muted text-foreground rounded-2xl rounded-bl-sm px-3.5 py-2.5 text-sm leading-relaxed">
-        <ReactMarkdown remarkPlugins={[remarkGfm]}>{message.content}</ReactMarkdown>
-      </div>
+      {isApprovalRequest ? (
+        renderApprovalAction(message)
+      ) : (
+        <div className="bg-muted text-foreground rounded-2xl rounded-bl-sm px-3.5 py-2.5 text-sm leading-relaxed">
+          <ReactMarkdown remarkPlugins={[remarkGfm]}>{message.content}</ReactMarkdown>
+        </div>
+      )}
       <MessageSourcesContainer
         message={message}
         isLatestAssistant={isLatestAssistant}

package/src/features/assistant-message/components/MessageList.tsx

@@ -1,16 +1,17 @@
 "use client";
 
 import { AssistantMessageInterface } from "../data/AssistantMessageInterface";
-import { MessageItem } from "./MessageItem";
+import { MessageItem, type ApprovalActionRenderer } from "./MessageItem";
 
 interface Props {
   messages: AssistantMessageInterface[];
   onSelectFollowUp: (q: string) => void;
   failedMessageIds?: Set<string>;
   onRetry?: (tempId: string) => void;
+  renderApprovalAction?: ApprovalActionRenderer;
 }
 
-export function MessageList({ messages, onSelectFollowUp, failedMessageIds, onRetry }: Props) {
+export function MessageList({ messages, onSelectFollowUp, failedMessageIds, onRetry, renderApprovalAction }: Props) {
   const ordered = [...messages].sort((a, b) => a.position - b.position);
 
   let lastAssistantIndex = -1;
@@ -31,6 +32,7 @@ export function MessageList({ messages, onSelectFollowUp, failedMessageIds, onRe
           onSelectFollowUp={onSelectFollowUp}
           failedMessageIds={failedMessageIds}
           onRetry={onRetry}
+          renderApprovalAction={renderApprovalAction}
         />
       ))}
     </div>

package/src/features/assistant-message/data/AssistantMessage.ts

@@ -1,6 +1,11 @@
 import { v4 as uuidv4 } from "uuid";
 import { AbstractApiData, ApiDataInterface, JsonApiHydratedDataInterface, Modules } from "../../../core";
-import { AssistantMessageInput, AssistantMessageInterface, AssistantMessageRole } from "./AssistantMessageInterface";
+import {
+  AssistantMessageInput,
+  AssistantMessageInterface,
+  AssistantMessageRole,
+  AssistantMessageType,
+} from "./AssistantMessageInterface";
 import { resolveReferenceableModules } from "../../assistant/utils/resolveReferenceableModules";
 import { ChunkInterface, ChunkRelationshipMeta } from "../../chunk/data/ChunkInterface";
 
@@ -14,6 +19,8 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
   private _references?: ApiDataInterface[];
   private _citations?: (ChunkInterface & ChunkRelationshipMeta)[];
   private _isOptimistic = false;
+  private _messageType?: AssistantMessageType;
+  private _actionId?: string;
 
   get role(): AssistantMessageRole {
     return this._role ?? "assistant";
@@ -51,6 +58,14 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
     return this._isOptimistic;
   }
 
+  get messageType(): AssistantMessageType {
+    return this._messageType ?? "text";
+  }
+
+  get actionId(): string | undefined {
+    return this._actionId;
+  }
+
   rehydrate(data: JsonApiHydratedDataInterface): this {
     super.rehydrate(data);
     const attrs = data.jsonApi.attributes ?? {};
@@ -60,6 +75,11 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
     this._suggestedQuestions = Array.isArray(attrs.suggestedQuestions) ? attrs.suggestedQuestions : [];
     this._inputTokens = attrs.inputTokens;
     this._outputTokens = attrs.outputTokens;
+    this._messageType = attrs.messageType as AssistantMessageType | undefined;
+    // The AssistantAction module is app-registered, so only the raw
+    // relationship id is exposed (no hydration of the included resource here).
+    const actionRelationship = data.jsonApi.relationships?.action?.data;
+    this._actionId = Array.isArray(actionRelationship) ? actionRelationship[0]?.id : actionRelationship?.id;
     const refs = this._readIncludedPolymorphic<ApiDataInterface>(data, "references", resolveReferenceableModules());
     this._references = Array.isArray(refs) ? refs : refs ? [refs] : [];
     if (data.jsonApi.relationships?.citations?.data) {

package/src/features/assistant-message/data/AssistantMessageInterface.ts

@@ -3,6 +3,14 @@ import { ChunkInterface, ChunkRelationshipMeta } from "../../chunk/data/ChunkInt
 
 export type AssistantMessageRole = "user" | "assistant" | "system";
 
+/**
+ * "text" is the default chat message; "approval-request" marks the message
+ * created while an operator run is frozen on a destructive tool call,
+ * awaiting human approval (linked AssistantAction via the `action`
+ * relationship).
+ */
+export type AssistantMessageType = "text" | "approval-request";
+
 export type AssistantMessageInput = {
   id: string;
   role: AssistantMessageRole;
@@ -21,4 +29,12 @@ export interface AssistantMessageInterface extends ApiDataInterface {
   get references(): ApiDataInterface[];
   get citations(): (ChunkInterface & ChunkRelationshipMeta)[];
   get isOptimistic(): boolean;
+  get messageType(): AssistantMessageType;
+  /**
+   * Id of the AssistantAction linked through the `action` relationship.
+   * Only present on `approval-request` messages. Exposed as a raw id (not a
+   * hydrated model) because the AssistantAction module is registered by the
+   * consuming app, not by this library.
+   */
+  get actionId(): string | undefined;
 }

package/src/shadcnui/index.ts

@@ -16,10 +16,12 @@ export * from "./ui/checkbox";
 export * from "./ui/collapsible";
 export * from "./ui/combobox";
 export * from "./ui/command";
+export * from "./ui/confirm-dialog";
 export * from "./ui/context-menu";
 export * from "./ui/dialog";
 export * from "./ui/drawer";
 export * from "./ui/dropdown-menu";
+export * from "./ui/empty-state";
 export * from "./ui/field";
 export * from "./ui/form";
 export * from "./ui/hover-card";
@@ -40,6 +42,7 @@ export * from "./ui/sidebar";
 export * from "./ui/skeleton";
 export * from "./ui/slider";
 export * from "./ui/sonner";
+export * from "./ui/spinner";
 export * from "./ui/switch";
 export * from "./ui/table";
 export * from "./ui/tabs";

package/src/shadcnui/ui/__tests__/confirm-dialog.test.tsx

@@ -0,0 +1,46 @@
+// packages/nextjs-jsonapi/src/shadcnui/ui/__tests__/confirm-dialog.test.tsx
+import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { ConfirmDialog } from "../confirm-dialog";
+
+describe("ConfirmDialog", () => {
+  it("renders title/description and calls onConfirm then closes", async () => {
+    const onConfirm = vi.fn();
+    const onOpenChange = vi.fn();
+    render(
+      <ConfirmDialog
+        open
+        onOpenChange={onOpenChange}
+        title="Reveal plot secrets?"
+        description="Spoilers ahead."
+        confirmLabel="Reveal"
+        cancelLabel="Keep hidden"
+        destructive
+        onConfirm={onConfirm}
+      />,
+    );
+    expect(screen.getByText("Reveal plot secrets?")).toBeInTheDocument();
+    expect(screen.getByText("Spoilers ahead.")).toBeInTheDocument();
+    await userEvent.click(screen.getByRole("button", { name: "Reveal" }));
+    expect(onConfirm).toHaveBeenCalledTimes(1);
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it("cancel closes without confirming", async () => {
+    const onConfirm = vi.fn();
+    const onOpenChange = vi.fn();
+    render(
+      <ConfirmDialog
+        open
+        onOpenChange={onOpenChange}
+        title="t"
+        confirmLabel="Yes"
+        cancelLabel="No"
+        onConfirm={onConfirm}
+      />,
+    );
+    await userEvent.click(screen.getByRole("button", { name: "No" }));
+    expect(onConfirm).not.toHaveBeenCalled();
+  });
+});

package/src/shadcnui/ui/__tests__/empty-state.test.tsx

@@ -0,0 +1,26 @@
+// packages/nextjs-jsonapi/src/shadcnui/ui/__tests__/empty-state.test.tsx
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { InboxIcon } from "lucide-react";
+import { EmptyState } from "../empty-state";
+
+describe("EmptyState", () => {
+  it("renders title, description and action", () => {
+    render(
+      <EmptyState
+        icon={InboxIcon}
+        title="No games yet"
+        description="Create your first game."
+        action={<button type="button">New game</button>}
+      />,
+    );
+    expect(screen.getByText("No games yet")).toBeInTheDocument();
+    expect(screen.getByText("Create your first game.")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "New game" })).toBeInTheDocument();
+  });
+
+  it("renders without optional parts", () => {
+    render(<EmptyState title="Empty" />);
+    expect(screen.getByText("Empty")).toBeInTheDocument();
+  });
+});

package/src/shadcnui/ui/__tests__/spinner.test.tsx

@@ -0,0 +1,18 @@
+// packages/nextjs-jsonapi/src/shadcnui/ui/__tests__/spinner.test.tsx
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Spinner } from "../spinner";
+
+describe("Spinner", () => {
+  it("renders a status indicator with animate-spin", () => {
+    render(<Spinner />);
+    const spinner = screen.getByRole("status");
+    expect(spinner).toHaveClass("animate-spin");
+    expect(spinner).toHaveClass("size-4");
+  });
+
+  it("applies the size variant", () => {
+    render(<Spinner size="lg" />);
+    expect(screen.getByRole("status")).toHaveClass("size-8");
+  });
+});