@carlonicora/nextjs-jsonapi 3.23.0 → 3.24.1

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

@@ -4,6 +4,8 @@ import { AssistantProvider, useAssistantContext } from "../AssistantContext";
 import { AssistantService } from "../../data/AssistantService";
 import { AssistantMessageService } from "../../../assistant-message/data/AssistantMessageService";
 import { useSocketContext } from "../../../../contexts/SocketContext";
+import { useSharedContext } from "../../../../contexts";
+import { render, screen, fireEvent } from "@testing-library/react";
 import type { JsonApiHydratedDataInterface } from "../../../../core";
 import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
 import { DataClassRegistry } from "../../../../core/registry/DataClassRegistry";
@@ -636,4 +638,198 @@ describe("AssistantContext", () => {
 
     replaceState.mockRestore();
   });
+
+  it("setScope binds the first message's thread", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+    const create = vi.fn().mockResolvedValue(buildAssistantStub({ id: "a-scoped" }));
+    AssistantService.create = create;
+    AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider>{children}</AssistantProvider>,
+    });
+    expect(result.current.scope).toBeUndefined();
+
+    act(() => {
+      result.current.setScope({ type: "proceedings", id: "p1" });
+    });
+    expect(result.current.scope).toEqual({ type: "proceedings", id: "p1" });
+
+    await act(async () => {
+      await result.current.sendMessage("hello");
+    });
+
+    expect(create).toHaveBeenCalledWith(expect.objectContaining({ boundContent: { type: "proceedings", id: "p1" } }));
+
+    // Once a thread exists its scope is fixed.
+    act(() => {
+      result.current.setScope({ type: "proceedings", id: "p2" });
+    });
+    expect(result.current.scope).toEqual({ type: "proceedings", id: "p1" });
+    replaceState.mockRestore();
+  });
+
+  it("the provider scope prop still filters the thread list", async () => {
+    const findMany = vi.fn().mockResolvedValue([]);
+    AssistantService.findMany = findMany;
+
+    const scope = { type: "campaigns", id: "camp-1" };
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider scope={scope}>{children}</AssistantProvider>,
+    });
+
+    await waitFor(() => expect(findMany).toHaveBeenCalledWith({ boundType: "campaigns", boundId: "camp-1" }));
+    expect(result.current.scope).toEqual(scope);
+
+    act(() => {
+      result.current.setScope({ type: "proceedings", id: "p1" });
+    });
+
+    expect(findMany).not.toHaveBeenCalledWith({ boundType: "proceedings", boundId: "p1" });
+    expect(findMany).toHaveBeenLastCalledWith({ boundType: "campaigns", boundId: "camp-1" });
+  });
+
+  it("page heading: thread title as element and a new-thread button that resets the thread", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+    const existing = buildAssistantDehydrated({ id: "a-h", title: "A thread title longer than 25 chars" });
+    let ctx: ReturnType<typeof useAssistantContext> | undefined;
+    function Probe() {
+      ctx = useAssistantContext();
+      const { title } = useSharedContext();
+      return (
+        <div>
+          <span data-testid="element">{title.element}</span>
+          {title.functions}
+        </div>
+      );
+    }
+    render(
+      <AssistantProvider dehydratedAssistant={existing}>
+        <Probe />
+      </AssistantProvider>,
+    );
+    expect(screen.getByTestId("element")).toHaveTextContent("A thread title longer tha...");
+    fireEvent.click(screen.getByTestId("assistant-new-button"));
+    await waitFor(() => expect(ctx?.assistant).toBeUndefined());
+    expect(screen.getByTestId("element")).toBeEmptyDOMElement();
+    expect(replaceState).toHaveBeenCalledWith(null, "", "/assistants");
+  });
+
+  describe("assistant:created", () => {
+    function fakeSocket() {
+      const handlers: Record<string, (payload: any) => void> = {};
+      const socket = {
+        on: vi.fn((evt: string, h: any) => {
+          handlers[evt] = h;
+        }),
+        off: vi.fn((evt: string) => {
+          delete handlers[evt];
+        }),
+      };
+      vi.mocked(useSocketContext).mockReturnValue({ socket, isConnected: true } as any);
+      return { socket, handlers };
+    }
+
+    function createdEvent(id: string, title: string) {
+      return {
+        assistant: {
+          data: { type: "assistants", id, attributes: { title, messageCount: 0 } },
+          included: [],
+        },
+      };
+    }
+
+    it("names the thread, lists it and swaps the URL before the create request returns", async () => {
+      const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+      const { socket, handlers } = fakeSocket();
+      let resolveCreate!: (value: unknown) => void;
+      AssistantService.create = vi.fn().mockImplementation(() => new Promise((resolve) => (resolveCreate = resolve)));
+      AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([buildMessageStub({ role: "user" })]);
+
+      const { result } = renderHook(() => useAssistantContext(), {
+        wrapper: ({ children }) => <AssistantProvider>{children}</AssistantProvider>,
+      });
+      await waitFor(() => expect(result.current.threadsLoading).toBe(false));
+
+      let sendPromise: Promise<void>;
+      await act(async () => {
+        sendPromise = result.current.sendMessage("first question");
+        await Promise.resolve();
+      });
+      expect(socket.on).toHaveBeenCalledWith("assistant:created", expect.any(Function));
+
+      await act(async () => {
+        handlers["assistant:created"]({ assistant: { data: null } });
+        handlers["assistant:created"](createdEvent("a-new", "Named thread"));
+        handlers["assistant:created"](createdEvent("a-other", "Second event"));
+      });
+
+      expect(result.current.assistant?.id).toBe("a-new");
+      expect(result.current.assistant?.title).toBe("Named thread");
+      expect(result.current.threads.map((t) => t.id)).toEqual(["a-new"]);
+      expect(replaceState).toHaveBeenCalledWith(null, "", "/assistants/a-new");
+      expect(result.current.sending).toBe(true);
+      expect(result.current.messages.map((m) => m.content)).toEqual(["first question"]);
+
+      await act(async () => {
+        resolveCreate(buildAssistantStub({ id: "a-new", title: "Named thread" }));
+        await sendPromise!;
+      });
+
+      expect(result.current.threads.filter((t) => t.id === "a-new")).toHaveLength(1);
+      expect(result.current.threads).toHaveLength(1);
+      expect(result.current.assistant?.id).toBe("a-new");
+      expect(socket.off).toHaveBeenCalledWith("assistant:created", expect.any(Function));
+      replaceState.mockRestore();
+    });
+
+    it("does not touch the URL from the event when manageUrl is false", async () => {
+      const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+      const { handlers } = fakeSocket();
+      let resolveCreate!: (value: unknown) => void;
+      AssistantService.create = vi.fn().mockImplementation(() => new Promise((resolve) => (resolveCreate = resolve)));
+      AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([]);
+
+      const { result } = renderHook(() => useAssistantContext(), {
+        wrapper: ({ children }) => <AssistantProvider manageUrl={false}>{children}</AssistantProvider>,
+      });
+      await waitFor(() => expect(result.current.threadsLoading).toBe(false));
+
+      let sendPromise: Promise<void>;
+      await act(async () => {
+        sendPromise = result.current.sendMessage("hello");
+        await Promise.resolve();
+      });
+      await act(async () => {
+        handlers["assistant:created"](createdEvent("a-sheet", "Sheet thread"));
+      });
+
+      expect(result.current.assistant?.id).toBe("a-sheet");
+      expect(result.current.threads.map((t) => t.id)).toEqual(["a-sheet"]);
+      expect(replaceState).not.toHaveBeenCalled();
+
+      await act(async () => {
+        resolveCreate(buildAssistantStub({ id: "a-sheet", title: "Sheet thread" }));
+        await sendPromise!;
+      });
+      expect(replaceState).not.toHaveBeenCalled();
+      replaceState.mockRestore();
+    });
+
+    it("does not subscribe to assistant:created when appending to an existing thread", async () => {
+      const { socket } = fakeSocket();
+      AssistantService.appendMessage = vi.fn().mockResolvedValue([]);
+      const { result } = renderHook(() => useAssistantContext(), {
+        wrapper: ({ children }) => (
+          <AssistantProvider dehydratedAssistant={buildAssistantDehydrated({ id: "a-ex" })}>
+            {children}
+          </AssistantProvider>
+        ),
+      });
+      await act(async () => {
+        await result.current.sendMessage("follow-up");
+      });
+      expect(socket.on).not.toHaveBeenCalledWith("assistant:created", expect.any(Function));
+    });
+  });
 });

package/src/features/assistant-action/components/AssistantContainerWithApprovals.tsx

@@ -1,21 +1,43 @@
 "use client";
 
+import type { ReactNode } from "react";
+import type { MentionRenderer } from "../../assistant-message/components/MessageItem";
 import type { AssistantMessageInterface } from "../../assistant-message/data/AssistantMessageInterface";
 import { AssistantContainer } from "../../assistant/components/containers/AssistantContainer";
+import type { AssistantInterface } from "../../assistant/data/AssistantInterface";
 import { useAssistantContext } from "../../assistant/contexts/AssistantContext";
 import { ApprovalActionCard } from "./ApprovalActionCard";
 
+interface Props {
+  renderMention?: MentionRenderer;
+  embedded?: boolean;
+  renderScopePicker?: () => ReactNode;
+  renderThreadBadge?: (thread: AssistantInterface) => ReactNode;
+  showOperatorToggle?: boolean;
+}
+
 /**
  * AssistantContainer with the operator approval card wired in. The container
  * renders `approval-request` messages through the `renderApprovalAction` slot,
  * which stays a slot so the plain chat container has no dependency on the
  * AssistantAction module. Must be rendered inside an `AssistantProvider`.
  */
-export function AssistantContainerWithApprovals() {
+export function AssistantContainerWithApprovals({
+  renderMention,
+  embedded,
+  renderScopePicker,
+  renderThreadBadge,
+  showOperatorToggle,
+}: Props = {}) {
   const ctx = useAssistantContext();
 
   return (
     <AssistantContainer
+      renderMention={renderMention}
+      embedded={embedded}
+      renderScopePicker={renderScopePicker}
+      renderThreadBadge={renderThreadBadge}
+      showOperatorToggle={showOperatorToggle}
       renderApprovalAction={(message: AssistantMessageInterface) =>
         message.actionId ? (
           <ApprovalActionCard

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

@@ -0,0 +1,28 @@
+"use client";
+
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+import { usePageUrlGenerator } from "../../../hooks";
+import { Link } from "../../../shadcnui";
+import type { MentionRenderer } from "./MessageItem";
+
+function EntityMentionLinkView({ type, id, alias }: { type: string; id: string; alias: string }) {
+  const generate = usePageUrlGenerator();
+
+  let module;
+  try {
+    module = ModuleRegistry.findByName(type);
+  } catch {
+    return <>{alias}</>;
+  }
+  if (!module?.pageUrl) return <>{alias}</>;
+
+  return <Link href={generate({ page: module, id })}>{alias}</Link>;
+}
+
+/**
+ * Default mention renderer for assistant answers: a `mention://<type>/<id>`
+ * link becomes a link to the entity's page when `<type>` is a registered
+ * module with a `pageUrl`, and plain text otherwise. Rendered as a component
+ * so the URL hook runs inside React's component tree.
+ */
+export const EntityMentionLink: MentionRenderer = (p) => <EntityMentionLinkView {...p} />;

package/src/features/assistant-message/components/__tests__/EntityMentionLink.spec.tsx

@@ -0,0 +1,58 @@
+import { describe, it, expect, vi, beforeAll } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { configureI18n } from "../../../../i18n";
+import { EntityMentionLink } from "../EntityMentionLink";
+
+beforeAll(() => {
+  // The package Link resolves its inner component at runtime and throws if i18n
+  // was never configured (src/i18n/config.ts).
+  configureI18n({
+    useRouter: () => ({
+      push: vi.fn(),
+      replace: vi.fn(),
+      back: vi.fn(),
+      forward: vi.fn(),
+      refresh: vi.fn(),
+      prefetch: vi.fn(),
+    }),
+    useTranslations: () => (key: string) => key,
+    usePathname: () => "/",
+    Link: ({
+      href,
+      children,
+      prefetch: _prefetch,
+      ...rest
+    }: {
+      href: string;
+      children: React.ReactNode;
+      [key: string]: any;
+    }) => (
+      <a href={href} {...rest}>
+        {children}
+      </a>
+    ),
+  });
+  ModuleRegistry.register("Account" as any, { name: "accounts", pageUrl: "/accounts" } as any);
+});
+
+describe("EntityMentionLink", () => {
+  it("renders a link to the entity page for a registered module", () => {
+    render(<>{EntityMentionLink({ type: "accounts", id: "a1", alias: "Rossi" })}</>);
+    const link = screen.getByRole("link", { name: "Rossi" });
+    expect(link).toHaveAttribute("href", "/accounts/a1");
+    expect(link).toHaveTextContent("Rossi");
+  });
+
+  it("renders through the package Link (locale-aware, link typography role)", () => {
+    render(<>{EntityMentionLink({ type: "accounts", id: "a1", alias: "Rossi" })}</>);
+    const link = screen.getByRole("link", { name: "Rossi" });
+    expect(link.className).toContain("text-primary font-medium");
+  });
+
+  it("renders plain text with no link for an unknown type", () => {
+    render(<>{EntityMentionLink({ type: "unknown-things", id: "x1", alias: "Mystery" })}</>);
+    expect(screen.getByText("Mystery")).toBeInTheDocument();
+    expect(screen.queryByRole("link")).not.toBeInTheDocument();
+  });
+});

package/src/features/assistant-message/components/index.ts

@@ -1,3 +1,4 @@
 export * from "./MessageItem";
 export * from "./MessageList";
 export { MessageSourcesPanel } from "./parts/MessageSourcesPanel";
+export * from "./EntityMentionLink";

package/src/features/assistant-message/components/parts/tabs/ContentsTab.tsx

@@ -1,13 +1,13 @@
 "use client";
 
 import { useTranslations } from "next-intl";
-import Link from "next/link";
 import type { ApiDataInterface } from "../../../../../core";
 import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
 import { usePageUrlGenerator } from "../../../../../hooks";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "../../../../../shadcnui/ui/table";
 import type { ChunkInterface, ChunkRelationshipMeta } from "../../../../chunk/data/ChunkInterface";
 import { useEntityLabel } from "./useEntityLabel";
+import { Link } from "../../../../../shadcnui/custom/link";
 
 interface Props {
   citations: (ChunkInterface & ChunkRelationshipMeta)[];

package/src/features/assistant-message/components/parts/tabs/ReferencesTab.tsx

@@ -1,12 +1,12 @@
 "use client";
 
 import { useTranslations } from "next-intl";
-import Link from "next/link";
 import type { ApiDataInterface } from "../../../../../core";
 import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
 import { usePageUrlGenerator } from "../../../../../hooks";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "../../../../../shadcnui/ui/table";
 import { useEntityLabel } from "./useEntityLabel";
+import { Link } from "../../../../../shadcnui/custom/link";
 
 interface Props {
   references: ApiDataInterface[];
@@ -42,7 +42,7 @@ export function ReferencesTab({ references }: Props) {
           return (
             <TableRow key={`${ref.type}/${ref.id}`}>
               <TableCell>
-                <Link href={href} target="_blank" rel="noopener noreferrer" className="font-medium">
+                <Link href={href} target="_blank" rel="noopener noreferrer">
                   {ref.identifier}
                 </Link>
               </TableCell>

package/src/features/auth/components/forms/__tests__/Logout.spec.tsx

@@ -37,7 +37,8 @@ describe("Logout", () => {
     // We need to delete the original location first
     // @ts-expect-error - deleting window.location for mocking purposes
     delete window.location;
-    window.location = {
+    // The DOM lib types `window.location` as accessor-only; jsdom lets the test replace it.
+    (window as unknown as { location: Location }).location = {
       ...originalLocation,
       get href() {
         return windowLocationHref;
@@ -50,7 +51,7 @@ describe("Logout", () => {
 
   afterEach(() => {
     // Restore original location
-    window.location = originalLocation;
+    (window as unknown as { location: Location }).location = originalLocation;
   });
 
   describe("Scenario: Clears storage when storageKeys provided", () => {

package/src/features/billing/stripe-customer/data/stripe-customer.service.ts

@@ -22,6 +22,11 @@ export class StripeCustomerService extends AbstractService {
       type: Modules.StripeCustomer,
       method: HttpMethod.GET,
       endpoint: endpoint.generate(),
+      // A 404 here means the company has no billing customer yet — an expected
+      // state that BillingDashboardContainer turns into a setup prompt. Without
+      // this, the global error handler swallows it and replaces the page with a
+      // 404 screen.
+      suppressGlobalError: true,
     });
   }
 

package/src/features/billing/stripe-subscription/components/index.ts

@@ -3,3 +3,4 @@ export * from "./details";
 export * from "./forms";
 export * from "./lists";
 export * from "./widgets";
+export * from "./wizards";

package/src/features/notification/contexts/NotificationContext.tsx

@@ -95,7 +95,10 @@ export const NotificationContextProvider = ({ children }: NotificationContextPro
       setError(null);
 
       try {
-        const fetchedNotifications = await NotificationService.findMany({});
+        // Background load: a failure must throw into the catch below. Routed
+        // through the global error handler, callApi resolves to undefined
+        // instead, which lands in state and crashes every consumer.
+        const fetchedNotifications = await NotificationService.findMany({ suppressGlobalError: true });
         setNotifications(fetchedNotifications);
         setLastLoaded(Date.now());
       } catch (error) {
@@ -146,7 +149,7 @@ export const NotificationContextProvider = ({ children }: NotificationContextPro
       };
 
       await NotificationService.markAsRead({ data: data });
-      const allNotifications = await NotificationService.findMany({});
+      const allNotifications = await NotificationService.findMany({ suppressGlobalError: true });
       setNotifications(allNotifications);
       setLastLoaded(Date.now());
     } catch (error) {

package/src/features/notification/contexts/__tests__/NotificationContext.spec.tsx

@@ -94,3 +94,35 @@ describe("NotificationContextProvider mount load", () => {
     expect(NotificationService.findMany).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("NotificationContextProvider failed load", () => {
+  beforeEach(() => {
+    userMock.currentUser = undefined;
+    vi.mocked(NotificationService.findMany).mockReset();
+  });
+
+  it("asks the service to throw instead of routing to the global error handler", async () => {
+    vi.mocked(NotificationService.findMany).mockResolvedValue([] as never);
+
+    const { result } = renderHook(() => useNotificationContext(), { wrapper });
+
+    await act(async () => {
+      await result.current.loadNotifications();
+    });
+
+    expect(NotificationService.findMany).toHaveBeenCalledWith({ suppressGlobalError: true });
+  });
+
+  it("keeps notifications an array and records the error when the API is unreachable", async () => {
+    vi.mocked(NotificationService.findMany).mockRejectedValue(new Error("500:"));
+
+    const { result } = renderHook(() => useNotificationContext(), { wrapper });
+
+    await act(async () => {
+      await result.current.loadNotifications();
+    });
+
+    expect(result.current.notifications).toEqual([]);
+    expect(result.current.error).toBe("500:");
+  });
+});

package/src/features/notification/data/notification.service.ts

@@ -2,7 +2,11 @@ import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef } from "
 import { NotificationInterface } from "./notification.interface";
 
 export class NotificationService extends AbstractService {
-  static async findMany(params: { isArchived?: boolean; next?: NextRef }): Promise<NotificationInterface[]> {
+  static async findMany(params: {
+    isArchived?: boolean;
+    next?: NextRef;
+    suppressGlobalError?: boolean;
+  }): Promise<NotificationInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: Modules.Notification });
 
     if (params.isArchived) endpoint.addAdditionalParam("isArchived", "true");
@@ -12,6 +16,7 @@ export class NotificationService extends AbstractService {
       method: HttpMethod.GET,
       endpoint: endpoint.generate(),
       next: params.next,
+      suppressGlobalError: params.suppressGlobalError,
     });
   }
 

package/src/features/oauth/components/OAuthClientForm.tsx

@@ -17,7 +17,12 @@ import {
 } from "../../../shadcnui";
 import { OAuthRedirectUriInput } from "./OAuthRedirectUriInput";
 import { OAuthScopeSelector } from "./OAuthScopeSelector";
-import { OAuthClientCreateRequest, OAuthClientInterface, DEFAULT_GRANT_TYPES } from "../interfaces/oauth.interface";
+import {
+  OAuthClientCreateRequest,
+  OAuthClientInterface,
+  OAuthScopeInfo,
+  DEFAULT_GRANT_TYPES,
+} from "../interfaces/oauth.interface";
 
 export interface OAuthClientFormProps {
   /** Existing client for edit mode (undefined = create mode) */
@@ -28,6 +33,10 @@ export interface OAuthClientFormProps {
   onCancel: () => void;
   /** Whether form is submitting */
   isLoading?: boolean;
+  /** Scopes the app offers in the selector (defaults to AVAILABLE_OAUTH_SCOPES) */
+  availableScopes?: OAuthScopeInfo[];
+  /** Scopes preselected in create mode (edit mode uses client.allowedScopes) */
+  defaultScopes?: string[];
 }
 
 interface FormState {
@@ -47,14 +56,21 @@ interface FormErrors {
 /**
  * Form for creating or editing an OAuth client
  */
-export function OAuthClientForm({ client, onSubmit, onCancel, isLoading = false }: OAuthClientFormProps) {
+export function OAuthClientForm({
+  client,
+  onSubmit,
+  onCancel,
+  isLoading = false,
+  availableScopes,
+  defaultScopes = [],
+}: OAuthClientFormProps) {
   const isEditMode = !!client;
 
   const [formState, setFormState] = useState<FormState>({
     name: client?.name || "",
     description: client?.description || "",
     redirectUris: client?.redirectUris?.length ? client.redirectUris : [""],
-    allowedScopes: client?.allowedScopes || [],
+    allowedScopes: client ? client.allowedScopes || [] : defaultScopes,
     isConfidential: client?.isConfidential ?? true,
   });
 
@@ -117,7 +133,7 @@ export function OAuthClientForm({ client, onSubmit, onCancel, isLoading = false
               id="name"
               value={formState.name}
               onChange={(e) => setFormState((s) => ({ ...s, name: e.target.value }))}
-              placeholder="My Lightroom Plugin"
+              placeholder="My Application"
               disabled={isLoading}
               className={errors.name ? "border-destructive" : ""}
             />
@@ -149,6 +165,7 @@ export function OAuthClientForm({ client, onSubmit, onCancel, isLoading = false
           <OAuthScopeSelector
             value={formState.allowedScopes}
             onChange={(scopes) => setFormState((s) => ({ ...s, allowedScopes: scopes }))}
+            availableScopes={availableScopes}
             error={errors.allowedScopes}
             disabled={isLoading}
           />

package/src/features/oauth/components/__tests__/OAuthClientForm.spec.tsx

@@ -0,0 +1,63 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { OAuthClientForm } from "../OAuthClientForm";
+import { OAUTH_SCOPE_DISPLAY, OAuthClientInterface } from "../../interfaces/oauth.interface";
+
+const scopeCheckbox = (name: string) => screen.getByRole("checkbox", { name: new RegExp(name) });
+
+const makeClient = (allowedScopes: string[]): OAuthClientInterface =>
+  ({
+    name: "Existing app",
+    description: undefined,
+    redirectUris: ["https://example.com/callback"],
+    allowedScopes,
+    isConfidential: true,
+  }) as unknown as OAuthClientInterface;
+
+describe("OAuthClientForm", () => {
+  it("renders only the scopes passed in availableScopes", () => {
+    render(<OAuthClientForm onSubmit={vi.fn()} onCancel={vi.fn()} availableScopes={[OAUTH_SCOPE_DISPLAY.mcp]} />);
+
+    expect(screen.getByText("MCP Server Access")).toBeTruthy();
+    expect(screen.queryByText("Read Access")).toBeNull();
+    expect(screen.queryByText("Write Access")).toBeNull();
+  });
+
+  it("preselects defaultScopes in create mode", () => {
+    render(
+      <OAuthClientForm
+        onSubmit={vi.fn()}
+        onCancel={vi.fn()}
+        availableScopes={[OAUTH_SCOPE_DISPLAY.read, OAUTH_SCOPE_DISPLAY.mcp]}
+        defaultScopes={["mcp"]}
+      />,
+    );
+
+    expect(scopeCheckbox("MCP Server Access").getAttribute("aria-checked")).toBe("true");
+    expect(scopeCheckbox("Read Access").getAttribute("aria-checked")).toBe("false");
+  });
+
+  it("uses client.allowedScopes instead of defaultScopes in edit mode", () => {
+    render(
+      <OAuthClientForm
+        client={makeClient(["read"])}
+        onSubmit={vi.fn()}
+        onCancel={vi.fn()}
+        availableScopes={[OAUTH_SCOPE_DISPLAY.read, OAUTH_SCOPE_DISPLAY.mcp]}
+        defaultScopes={["mcp"]}
+      />,
+    );
+
+    expect(scopeCheckbox("Read Access").getAttribute("aria-checked")).toBe("true");
+    expect(scopeCheckbox("MCP Server Access").getAttribute("aria-checked")).toBe("false");
+  });
+
+  it("offers the generic scope list by default, without Only35 scopes", () => {
+    render(<OAuthClientForm onSubmit={vi.fn()} onCancel={vi.fn()} />);
+
+    expect(screen.getByText("MCP Server Access")).toBeTruthy();
+    expect(screen.getByText("Read Access")).toBeTruthy();
+    expect(screen.queryByText("View Photographs")).toBeNull();
+    expect(screen.queryByText("View Rolls")).toBeNull();
+  });
+});