@stigmer/react 3.12.2 → 3.12.3

package/src/internal/DialogShell.tsx

@@ -0,0 +1,169 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+import type { MouseEvent, ReactNode, SyntheticEvent } from "react";
+import { cn } from "@stigmer/theme";
+
+/**
+ * Width presets for {@link DialogShell}, mapping to Tailwind `max-w-*`
+ * utilities. Free-form sizes (e.g. a lightbox's `85vw`) ride `className`,
+ * which wins over the preset via `cn()`'s tailwind-merge.
+ */
+export type DialogShellWidth = "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl";
+
+const WIDTH_CLASS: Record<DialogShellWidth, string> = {
+  sm: "stg:max-w-sm",
+  md: "stg:max-w-md",
+  lg: "stg:max-w-lg",
+  xl: "stg:max-w-xl",
+  "2xl": "stg:max-w-2xl",
+  "3xl": "stg:max-w-3xl",
+  "4xl": "stg:max-w-4xl",
+};
+
+/** Props for {@link DialogShell}. */
+export interface DialogShellProps {
+  /** Whether the dialog is open (controlled — the SDK dialog convention). */
+  readonly open: boolean;
+  /**
+   * Called with `false` when the dialog should close: Escape / the platform
+   * cancel gesture, or a native close the host did not drive (e.g. a
+   * `method="dialog"` form submit). The shell never closes itself — state
+   * stays authoritative, so a host that ignores the callback keeps the
+   * dialog open (matching the pre-extraction per-dialog behavior).
+   */
+  readonly onOpenChange: (open: boolean) => void;
+  /** Max-width preset (default `"md"`). See {@link DialogShellWidth}. */
+  readonly width?: DialogShellWidth;
+  /**
+   * Modal (default) renders in the top layer via `showModal()` — focus trap,
+   * Escape, and the token backdrop. `modal={false}` renders the dialog
+   * in-flow (`open` attribute, relative positioning, no backdrop, no focus
+   * trap) — the channel-dialog embedding mode.
+   */
+  readonly modal?: boolean;
+  /**
+   * Light dismiss: a click on the backdrop (the dialog element itself —
+   * clicks inside the content land on descendants) reports close intent.
+   * The house rule from the pre-extraction census: read-only viewers
+   * (diff/YAML/explain/lightbox/pickers) dismiss on backdrop, form dialogs
+   * do NOT — a stray click must never discard a half-filled form. Default
+   * `false`.
+   */
+  readonly dismissOnBackdrop?: boolean;
+  /**
+   * Merged after the shell's own chrome, so deliberate outliers (a
+   * lightbox's viewport sizing, a fullscreen graph's `h-[90vh]`, a
+   * `bg-background` surface) override the defaults per class.
+   */
+  readonly className?: string;
+  /** Dialog content. Lazy-mounting bodies (`{open && …}`) stay caller-owned. */
+  readonly children: ReactNode;
+  /** Accessible name, when no visible heading labels the dialog. */
+  readonly "aria-label"?: string;
+  /** Id of the visible heading that labels the dialog. */
+  readonly "aria-labelledby"?: string;
+}
+
+/**
+ * The one dialog shell (stigmer#653). Owns everything every modal dialog in
+ * the SDK used to re-transcribe by hand: the `<dialog>` element and its
+ * `showModal()`/`close()` lifecycle, cancel/Escape wiring, the token
+ * backdrop (`--stgm-backdrop`), the open animation, and the base
+ * positioning/chrome — parameterized by {@link DialogShellWidth}.
+ *
+ * Converged chrome: `rounded-xl` + `shadow-xl` on the `popover` token
+ * surface (the token family for top-layer content). Before the extraction
+ * the 24 hand-rolled shells had drifted across `rounded-lg/xl`,
+ * `shadow-lg/xl/2xl`, three background tokens, two hardcoded backdrops that
+ * escaped the #652 fence, and animation classes present on some dialogs and
+ * missing from others.
+ *
+ * Internal on purpose — not exported from the package until a host needs it.
+ * The `stigmer/no-handrolled-dialog` lint rule fences new `<dialog>`
+ * elements onto this shell.
+ *
+ * @example
+ * ```tsx
+ * <DialogShell open={open} onOpenChange={setOpen} width="lg" aria-labelledby={titleId}>
+ *   {open && <MyDialogBody titleId={titleId} onClose={() => setOpen(false)} />}
+ * </DialogShell>
+ * ```
+ */
+export function DialogShell({
+  open,
+  onOpenChange,
+  width = "md",
+  modal = true,
+  dismissOnBackdrop = false,
+  className,
+  children,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledby,
+}: DialogShellProps) {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+
+  // Sync the native top-layer state to the controlled prop. Runs on mount
+  // too, so a shell mounted with `open` already true shows immediately.
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog || !modal) return;
+    if (open && !dialog.open) {
+      dialog.showModal();
+    } else if (!open && dialog.open) {
+      dialog.close();
+    }
+  }, [open, modal]);
+
+  // Escape / platform cancel: keep the native dialog open (preventDefault)
+  // and report the intent — the controlled `open` prop then drives the
+  // actual close through the effect above.
+  const handleCancel = useCallback(
+    (e: SyntheticEvent<HTMLDialogElement>) => {
+      e.preventDefault();
+      onOpenChange(false);
+    },
+    [onOpenChange],
+  );
+
+  // A native close the effect did not perform (e.g. a `method="dialog"`
+  // form submit) must not leave the controlled state stranded open.
+  const handleClose = useCallback(() => {
+    if (open) onOpenChange(false);
+  }, [open, onOpenChange]);
+
+  // Backdrop clicks hit the <dialog> element itself; clicks anywhere in the
+  // content land on a descendant, so the target check is exact.
+  const handleClick = useCallback(
+    (e: MouseEvent<HTMLDialogElement>) => {
+      if (e.target === e.currentTarget) onOpenChange(false);
+    },
+    [onOpenChange],
+  );
+
+  return (
+    <dialog
+      ref={dialogRef}
+      open={modal ? undefined : open || undefined}
+      onCancel={modal ? handleCancel : undefined}
+      onClose={modal ? handleClose : undefined}
+      onClick={modal && dismissOnBackdrop ? handleClick : undefined}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledby}
+      className={cn(
+        "stg:w-full stg:rounded-xl stg:border stg:border-border stg:bg-popover stg:p-0 stg:text-popover-foreground stg:shadow-xl",
+        modal
+          ? cn(
+              "stg:fixed stg:inset-0 stg:z-50 stg:m-auto",
+              "stg:backdrop:bg-backdrop",
+              "stg:open:animate-in stg:open:fade-in-0 stg:open:zoom-in-95",
+            )
+          : "stg:relative",
+        WIDTH_CLASS[width],
+        className,
+      )}
+    >
+      {children}
+    </dialog>
+  );
+}

package/src/internal/__tests__/DialogShell.test.tsx

@@ -0,0 +1,223 @@
+/**
+ * DialogShell (stigmer#653): the one modal shell — showModal lifecycle,
+ * cancel/Escape wiring with state authority, native-close sync, the token
+ * backdrop + converged chrome, and the non-modal in-flow mode.
+ */
+
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { render, cleanup, fireEvent } from "@testing-library/react";
+import { DialogShell } from "../DialogShell";
+
+// happy-dom does not implement the native dialog show/close methods.
+beforeAll(() => {
+  HTMLDialogElement.prototype.showModal = function showModal() {
+    this.open = true;
+  };
+  HTMLDialogElement.prototype.close = function close() {
+    this.open = false;
+  };
+});
+
+afterEach(cleanup);
+
+function dialogOf(container: HTMLElement): HTMLDialogElement {
+  return container.querySelector("dialog")!;
+}
+
+describe("DialogShell lifecycle", () => {
+  it("opens via showModal when the controlled prop flips true", () => {
+    const { container, rerender } = render(
+      <DialogShell open={false} onOpenChange={() => {}}>
+        <p>body</p>
+      </DialogShell>,
+    );
+    expect(dialogOf(container).open).toBe(false);
+
+    rerender(
+      <DialogShell open onOpenChange={() => {}}>
+        <p>body</p>
+      </DialogShell>,
+    );
+    expect(dialogOf(container).open).toBe(true);
+  });
+
+  it("shows immediately when mounted already open", () => {
+    const { container } = render(
+      <DialogShell open onOpenChange={() => {}}>
+        <p>body</p>
+      </DialogShell>,
+    );
+    expect(dialogOf(container).open).toBe(true);
+  });
+
+  it("closes the native dialog when the controlled prop flips false", () => {
+    const { container, rerender } = render(
+      <DialogShell open onOpenChange={() => {}}>
+        <p>body</p>
+      </DialogShell>,
+    );
+    rerender(
+      <DialogShell open={false} onOpenChange={() => {}}>
+        <p>body</p>
+      </DialogShell>,
+    );
+    expect(dialogOf(container).open).toBe(false);
+  });
+
+  it("Escape/cancel reports intent but never closes on its own — state stays authoritative", () => {
+    const onOpenChange = vi.fn();
+    const { container } = render(
+      <DialogShell open onOpenChange={onOpenChange}>
+        <p>body</p>
+      </DialogShell>,
+    );
+
+    fireEvent(dialogOf(container), new Event("cancel", { cancelable: true }));
+
+    expect(onOpenChange).toHaveBeenCalledExactlyOnceWith(false);
+    // The shell prevented the native close; the dialog stays open until the
+    // host flips the prop.
+    expect(dialogOf(container).open).toBe(true);
+  });
+
+  it("syncs the controlled state when something else closes the dialog natively", () => {
+    const onOpenChange = vi.fn();
+    const { container } = render(
+      <DialogShell open onOpenChange={onOpenChange}>
+        <p>body</p>
+      </DialogShell>,
+    );
+
+    // e.g. a method="dialog" form submit closes without going through props.
+    const dialog = dialogOf(container);
+    dialog.close();
+    fireEvent(dialog, new Event("close"));
+
+    expect(onOpenChange).toHaveBeenCalledExactlyOnceWith(false);
+  });
+
+  it("does not re-report a close the host itself drove", () => {
+    const onOpenChange = vi.fn();
+    const { container, rerender } = render(
+      <DialogShell open onOpenChange={onOpenChange}>
+        <p>body</p>
+      </DialogShell>,
+    );
+    rerender(
+      <DialogShell open={false} onOpenChange={onOpenChange}>
+        <p>body</p>
+      </DialogShell>,
+    );
+    // The effect's own dialog.close() fires a native close event in real
+    // browsers — replay it against the now-false prop.
+    fireEvent(dialogOf(container), new Event("close"));
+    expect(onOpenChange).not.toHaveBeenCalled();
+  });
+});
+
+describe("DialogShell chrome", () => {
+  it("carries the token backdrop, animation, positioning, and width preset", () => {
+    const { container } = render(
+      <DialogShell open onOpenChange={() => {}} width="3xl">
+        <p>body</p>
+      </DialogShell>,
+    );
+    const cls = dialogOf(container).className;
+
+    expect(cls).toContain("stg:backdrop:bg-backdrop");
+    expect(cls).toContain("stg:open:animate-in");
+    expect(cls).toContain("stg:fixed");
+    expect(cls).toContain("stg:m-auto");
+    expect(cls).toContain("stg:max-w-3xl");
+    expect(cls).toContain("stg:bg-popover");
+  });
+
+  it("className overrides the shell's own chrome per class (tailwind-merge)", () => {
+    const { container } = render(
+      <DialogShell
+        open
+        onOpenChange={() => {}}
+        className="stg:bg-background stg:max-w-[85vw]"
+      >
+        <p>body</p>
+      </DialogShell>,
+    );
+    const cls = dialogOf(container).className;
+
+    expect(cls).toContain("stg:bg-background");
+    expect(cls).not.toContain("stg:bg-popover");
+    expect(cls).toContain("stg:max-w-[85vw]");
+    expect(cls).not.toContain("stg:max-w-md");
+  });
+
+  it("labels the dialog for assistive tech", () => {
+    const { container } = render(
+      <DialogShell open onOpenChange={() => {}} aria-label="Confirm delete">
+        <p>body</p>
+      </DialogShell>,
+    );
+    expect(dialogOf(container).getAttribute("aria-label")).toBe("Confirm delete");
+  });
+});
+
+describe("DialogShell backdrop dismiss", () => {
+  it("dismissOnBackdrop: a click on the dialog element itself reports close intent", () => {
+    const onOpenChange = vi.fn();
+    const { container } = render(
+      <DialogShell open onOpenChange={onOpenChange} dismissOnBackdrop>
+        <p>body</p>
+      </DialogShell>,
+    );
+
+    fireEvent.click(dialogOf(container));
+    expect(onOpenChange).toHaveBeenCalledExactlyOnceWith(false);
+  });
+
+  it("dismissOnBackdrop: clicks on content descendants never dismiss", () => {
+    const onOpenChange = vi.fn();
+    const { container, getByText } = render(
+      <DialogShell open onOpenChange={onOpenChange} dismissOnBackdrop>
+        <p>body</p>
+      </DialogShell>,
+    );
+
+    fireEvent.click(getByText("body"));
+    expect(onOpenChange).not.toHaveBeenCalled();
+    expect(dialogOf(container).open).toBe(true);
+  });
+
+  it("default: backdrop clicks are inert (form dialogs)", () => {
+    const onOpenChange = vi.fn();
+    const { container } = render(
+      <DialogShell open onOpenChange={onOpenChange}>
+        <p>body</p>
+      </DialogShell>,
+    );
+
+    fireEvent.click(dialogOf(container));
+    expect(onOpenChange).not.toHaveBeenCalled();
+  });
+});
+
+describe("DialogShell non-modal mode", () => {
+  it("renders in-flow: open attribute, no backdrop, no fixed positioning", () => {
+    const { container, rerender } = render(
+      <DialogShell open modal={false} onOpenChange={() => {}}>
+        <p>body</p>
+      </DialogShell>,
+    );
+    const dialog = dialogOf(container);
+
+    expect(dialog.open).toBe(true);
+    expect(dialog.className).toContain("stg:relative");
+    expect(dialog.className).not.toContain("stg:backdrop:bg-backdrop");
+    expect(dialog.className).not.toContain("stg:fixed");
+
+    rerender(
+      <DialogShell open={false} modal={false} onOpenChange={() => {}}>
+        <p>body</p>
+      </DialogShell>,
+    );
+    expect(dialogOf(container).open).toBe(false);
+  });
+});

package/src/manifest/ApplyManifestDialog.tsx

@@ -2,6 +2,7 @@
 
 import { lazy, Suspense, useCallback, useEffect, useRef } from "react";
 import { cn } from "@stigmer/theme";
+import { DialogShell } from "../internal/DialogShell.js";
 import { toast } from "../feedback/toast.js";
 import { RedactedSecretsNotice } from "./RedactedSecretsNotice.js";
 import {
@@ -71,22 +72,10 @@ export function ApplyManifestDialog({
   org,
   onApplied,
 }: ApplyManifestDialogProps) {
-  const dialogRef = useRef<HTMLDialogElement>(null);
   const fileInputRef = useRef<HTMLInputElement>(null);
   const manifest = useApplyManifest(org);
   const { reset } = manifest;
 
-  // Sync dialog open state with the native <dialog> element.
-  useEffect(() => {
-    const dialog = dialogRef.current;
-    if (!dialog) return;
-    if (open && !dialog.open) {
-      dialog.showModal();
-    } else if (!open && dialog.open) {
-      dialog.close();
-    }
-  }, [open]);
-
   // Start each session clean.
   useEffect(() => {
     if (open) {
@@ -109,10 +98,11 @@ export function ApplyManifestDialog({
     if (applied.length > 0) onApplied?.(applied);
   }, [onOpenChange, manifest.entries, onApplied]);
 
-  const handleCancel = useCallback(
-    (e: React.SyntheticEvent) => {
-      e.preventDefault();
-      closeAndMaybeRefresh();
+  // Escape/cancel routes through the same dismiss-after-partial path as the
+  // Close button, via the shell's single close-intent callback.
+  const handleShellOpenChange = useCallback(
+    (nextOpen: boolean) => {
+      if (!nextOpen) closeAndMaybeRefresh();
     },
     [closeAndMaybeRefresh],
   );
@@ -151,15 +141,7 @@ export function ApplyManifestDialog({
     !manifest.isApplying;
 
   return (
-    <dialog
-      ref={dialogRef}
-      onCancel={handleCancel}
-      className={cn(
-        "stg:fixed stg:inset-0 stg:z-50 stg:m-auto stg:w-full stg:max-w-3xl stg:rounded-lg stg:border stg:border-border stg:bg-popover stg:p-0 stg:text-popover-foreground stg:shadow-lg",
-        "stg:backdrop:bg-backdrop",
-        "stg:open:animate-in stg:open:fade-in-0 stg:open:zoom-in-95",
-      )}
-    >
+    <DialogShell open={open} onOpenChange={handleShellOpenChange} width="3xl" aria-label="Apply YAML">
       <div className="stg:flex stg:flex-col stg:gap-4 stg:p-6">
         {/* Header */}
         <div className="stg:flex stg:flex-col stg:gap-1">
@@ -252,7 +234,7 @@ export function ApplyManifestDialog({
           </div>
         </div>
       </div>
-    </dialog>
+    </DialogShell>
   );
 }
 

package/src/manifest/EditResourceYamlDialog.tsx

@@ -1,8 +1,9 @@
 "use client";
 
-import { lazy, Suspense, useCallback, useEffect, useRef } from "react";
+import { lazy, Suspense, useCallback, useEffect } from "react";
 import type { Message } from "@bufbuild/protobuf";
 import { cn } from "@stigmer/theme";
+import { DialogShell } from "../internal/DialogShell.js";
 import { getUserMessage, type AppliedManifest } from "@stigmer/sdk";
 import { toast } from "../feedback/toast.js";
 import { RedactedSecretsNotice } from "./RedactedSecretsNotice.js";
@@ -67,34 +68,14 @@ export function EditResourceYamlDialog({
   resource,
   onApplied,
 }: EditResourceYamlDialogProps) {
-  const dialogRef = useRef<HTMLDialogElement>(null);
   const edit = useEditResourceYaml({ resource });
   const { reset } = edit;
 
-  // Sync dialog open state with the native <dialog> element.
-  useEffect(() => {
-    const dialog = dialogRef.current;
-    if (!dialog) return;
-    if (open && !dialog.open) {
-      dialog.showModal();
-    } else if (!open && dialog.open) {
-      dialog.close();
-    }
-  }, [open]);
-
   // Discard stale edits from a previous session when the dialog opens.
   useEffect(() => {
     if (open) reset();
   }, [open, reset]);
 
-  const handleCancel = useCallback(
-    (e: React.SyntheticEvent) => {
-      e.preventDefault();
-      onOpenChange(false);
-    },
-    [onOpenChange],
-  );
-
   const handleApply = useCallback(async () => {
     try {
       const result = await edit.apply();
@@ -111,15 +92,7 @@ export function EditResourceYamlDialog({
     edit.validation.status === "valid" && edit.isDirty && !edit.isApplying;
 
   return (
-    <dialog
-      ref={dialogRef}
-      onCancel={handleCancel}
-      className={cn(
-        "stg:fixed stg:inset-0 stg:z-50 stg:m-auto stg:w-full stg:max-w-3xl stg:rounded-lg stg:border stg:border-border stg:bg-popover stg:p-0 stg:text-popover-foreground stg:shadow-lg",
-        "stg:backdrop:bg-backdrop",
-        "stg:open:animate-in stg:open:fade-in-0 stg:open:zoom-in-95",
-      )}
-    >
+    <DialogShell open={open} onOpenChange={onOpenChange} width="3xl" aria-label="Edit YAML">
       <div className="stg:flex stg:flex-col stg:gap-4 stg:p-6">
         {/* Header */}
         <div className="stg:flex stg:flex-col stg:gap-1">
@@ -233,7 +206,7 @@ export function EditResourceYamlDialog({
           </div>
         </div>
       </div>
-    </dialog>
+    </DialogShell>
   );
 }
 

package/src/mcp-server/McpServerConnectDialog.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { cn } from "@stigmer/theme";
+import { DialogShell } from "../internal/DialogShell.js";
 import type { EnvVarInput } from "@stigmer/sdk";
 import { useMcpServer } from "./useMcpServer.js";
 import { useMcpServerCredentials } from "./useMcpServerCredentials.js";
@@ -88,29 +89,11 @@ export function McpServerConnectDialog({
   onOpenDetails,
   className,
 }: McpServerConnectDialogProps) {
-  const dialogRef = useRef<HTMLDialogElement>(null);
   const resolvedOrg = activeOrg || org;
 
-  useEffect(() => {
-    const dialog = dialogRef.current;
-    if (!dialog) return;
-
-    if (open && !dialog.open) {
-      dialog.showModal();
-    } else if (!open && dialog.open) {
-      dialog.close();
-    }
-  }, [open]);
-
-  const handleDialogClose = useCallback(() => {
-    onClose();
-  }, [onClose]);
-
-  const handleBackdropClick = useCallback(
-    (e: React.MouseEvent<HTMLDialogElement>) => {
-      if (e.target === dialogRef.current) {
-        onClose();
-      }
+  const handleOpenChange = useCallback(
+    (nextOpen: boolean) => {
+      if (!nextOpen) onClose();
     },
     [onClose],
   );
@@ -118,15 +101,18 @@ export function McpServerConnectDialog({
   if (!open) return null;
 
   return (
-    <dialog
-      ref={dialogRef}
-      onClose={handleDialogClose}
-      onClick={handleBackdropClick}
+    <DialogShell
+      open
+      onOpenChange={handleOpenChange}
+      width="md"
+      dismissOnBackdrop
+      // Card surface + visible overflow are deliberate: the connect form
+      // hosts popovers that extend past the dialog bounds.
       className={cn(
-        "stg:m-auto stg:max-h-[85vh] stg:w-full stg:max-w-md stg:overflow-visible stg:rounded-lg stg:border stg:border-border stg:bg-card stg:p-0 stg:text-foreground stg:shadow-lg",
-        "stg:backdrop:bg-backdrop",
+        "stg:max-h-[85vh] stg:overflow-visible stg:bg-card stg:text-foreground",
         className,
       )}
+      aria-label={`Connect ${slug}`}
     >
       <div
         className="stg:flex stg:max-h-[85vh] stg:flex-col stg:overflow-y-auto stg:p-6"
@@ -141,7 +127,7 @@ export function McpServerConnectDialog({
           onOpenDetails={onOpenDetails}
         />
       </div>
-    </dialog>
+    </DialogShell>
   );
 }
 

package/src/mcp-server/McpServerDetailView.tsx

@@ -36,6 +36,7 @@ import { OAuthAppForm } from "./OAuthAppForm.js";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ErrorMessage } from "../error/ErrorMessage.js";
 import { Tooltip, TooltipContent, TooltipTrigger } from "../internal/tooltip.js";
+import { DialogShell } from "../internal/DialogShell.js";
 import { EnvVarForm } from "../environment/EnvVarForm.js";
 import type { EnvVarFormVariable } from "../environment/EnvVarForm.js";
 import { VisibilityBadge } from "../library/VisibilitySelector.js";
@@ -282,7 +283,6 @@ export function McpServerDetailView({
   const [showCredentialForm, setShowCredentialForm] = useState(defaultShowCredentialForm);
   const [showByoaForm, setShowByoaForm] = useState(false);
   const [capabilityTab, setCapabilityTab] = useState<CapabilityTab>(defaultCapabilityTab);
-  const byoaDialogRef = useRef<HTMLDialogElement>(null);
 
   const onResourceLoadRef = useRef(onResourceLoad);
   onResourceLoadRef.current = onResourceLoad;
@@ -388,20 +388,9 @@ export function McpServerDetailView({
     }
   }, [mcpServer, disconnectOAuth, credentials, refetch, activeOrg, org]);
 
-  // BYOA dialog lifecycle — native <dialog> toggle
-  useEffect(() => {
-    const dialog = byoaDialogRef.current;
-    if (!dialog) return;
-    if (showByoaForm && !dialog.open) {
-      dialog.showModal();
-    } else if (!showByoaForm && dialog.open) {
-      dialog.close();
-    }
-  }, [showByoaForm]);
-
-  const handleByoaDialogCancel = useCallback(
-    (e: React.SyntheticEvent) => {
-      e.preventDefault();
+  const handleByoaOpenChange = useCallback(
+    (nextOpen: boolean) => {
+      if (nextOpen) return;
       setShowByoaForm(false);
       orgOAuthApp.clearErrors();
     },
@@ -706,14 +695,13 @@ export function McpServerDetailView({
         )}
       </Section>
 
-      {/* BYOA dialog — native <dialog> for zero-dependency modal behavior */}
-      <dialog
-        ref={byoaDialogRef}
-        onCancel={handleByoaDialogCancel}
-        className={cn(
-          "stg:m-auto stg:w-full stg:max-w-md stg:rounded-lg stg:border stg:border-border stg:bg-background stg:p-6 stg:shadow-lg",
-          "stg:backdrop:bg-backdrop",
-        )}
+      {/* BYOA dialog */}
+      <DialogShell
+        open={showByoaForm}
+        onOpenChange={handleByoaOpenChange}
+        width="md"
+        className="stg:p-6"
+        aria-label="Use your own OAuth app"
       >
         <h3 className="stg:mb-4 stg:text-base stg:font-semibold stg:text-foreground">
           Use your own OAuth app
@@ -729,7 +717,7 @@ export function McpServerDetailView({
           isSubmitting={orgOAuthApp.isSetting}
           error={orgOAuthApp.setError}
         />
-      </dialog>
+      </DialogShell>
 
       <Section title="Capabilities" scrollTarget="mcp-capabilities">
         <Tabs