@cosmicdrift/kumiko-renderer-web 0.256.0 → 0.258.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.256.0",
+  "version": "0.258.0",
   "description": "Web-platform bindings for @cosmicdrift/kumiko-renderer. HTML default-primitives, browser history-based navigation, EventSource-backed live events, and a one-call createKumikoApp that mounts the whole stack via react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -16,9 +16,9 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.256.0",
-    "@cosmicdrift/kumiko-headless": "0.256.0",
-    "@cosmicdrift/kumiko-renderer": "0.256.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.258.0",
+    "@cosmicdrift/kumiko-headless": "0.258.0",
+    "@cosmicdrift/kumiko-renderer": "0.258.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",
@@ -32,6 +32,7 @@
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
     "lucide-react": "^1.14.0",
+    "qrcode": "^1.5.4",
     "radix-ui": "^1.4.3",
     "react": "^19.2.6",
     "react-day-picker": "^10.0.0",
@@ -60,11 +61,12 @@
     "@tailwindcss/cli": "^4.3.0",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
+    "@types/qrcode": "^1.5.5",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "tailwindcss": "^4.3.0",
-    "@cosmicdrift/kumiko-locale-de": "0.256.0"
+    "@cosmicdrift/kumiko-locale-de": "0.258.0"
   },
   "repository": {
     "type": "git",

package/src/__tests__/render-edit.test.tsx

@@ -1851,6 +1851,77 @@ describe("RenderEdit wizard draft", () => {
     expect(titleInputAgain.value).toBe("Acme");
   });
 
+  // fw#2548 security: a `format: "password"` field must never reach the
+  // persisted draft blob — it would be stored in the clear server-side and
+  // restored in plaintext on resume.
+  test("a password-format field is stripped from the draft save payload", async () => {
+    const passwordEntity = {
+      fields: {
+        title: { type: "text", required: true },
+        apiToken: { type: "text", format: "password" },
+        count: { type: "number" },
+      },
+    } as unknown as EntityDefinition;
+
+    const passwordScreen: EntityEditScreenDefinition = {
+      id: "orders:screen:order-wizard-draft-password",
+      type: "entityEdit",
+      entity: "order",
+      layout: {
+        mode: "wizard",
+        draft: true,
+        sections: [
+          { title: "Basics", columns: 1, fields: [{ field: "title" }, { field: "apiToken" }] },
+          { title: "Details", columns: 1, fields: [{ field: "count" }] },
+        ],
+      },
+    };
+
+    const savedPayloads: DraftBlob[] = [];
+    const dispatcher = createMockDispatcher({
+      query: (async () => ({ isSuccess: true, data: {} })) as Dispatcher["query"],
+      write: (async (type: string, payload: unknown) => {
+        if (type === "form-draft:write:save" && isDraftSavePayload(payload)) {
+          savedPayloads.push(payload);
+        }
+        return { isSuccess: true, data: { id: "1" } };
+      }) as Dispatcher["write"],
+    });
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <DraftStorageProvider value={createFakeDraftStorage()}>
+          <RenderEdit<TestValues & { apiToken?: string }>
+            screen={passwordScreen}
+            entity={passwordEntity}
+            featureName="orders"
+            initial={{ title: "", count: 0, apiToken: "" }}
+            writeCommand="order:create"
+          />
+        </DraftStorageProvider>
+      </DispatcherProvider>,
+    );
+
+    fireEvent.change(screen.getByTestId("field-title").querySelector("input") as HTMLInputElement, {
+      target: { value: "Acme" },
+    });
+    fireEvent.change(
+      screen.getByTestId("field-apiToken").querySelector("input") as HTMLInputElement,
+      { target: { value: "hunter2" } },
+    );
+
+    await act(async () => {
+      fireEvent.click(screen.getByTestId("render-edit-wizard-next"));
+      await Promise.resolve();
+    });
+
+    expect(savedPayloads.length).toBeGreaterThan(0);
+    const saved = savedPayloads[0] as DraftBlob;
+    expect(saved.values["title"]).toBe("Acme");
+    expect(Object.keys(saved.values)).not.toContain("apiToken");
+    expect(JSON.stringify(saved.values)).not.toContain("hunter2");
+  });
+
   // fw#1929: bare crypto.randomUUID() breaks in non-secure contexts and
   // React Native/Hermes without a polyfill. With it deleted, minting a
   // draftId must still work through the mintDraftId() fallback instead of

package/src/icons.tsx

@@ -27,6 +27,7 @@ import {
   CheckCircle2,
   ChevronDown,
   ChevronRight,
+  CircleStop,
   ClipboardList,
   Clock,
   Coins,
@@ -57,6 +58,7 @@ import {
   Lock,
   Mail,
   MapPin,
+  Mic,
   MoreHorizontal,
   MoreVertical,
   Package,
@@ -175,6 +177,8 @@ export const NAV_ICONS = {
   "check-circle": CheckCircle2,
   "x-circle": XCircle,
   loader: Loader2,
+  mic: Mic,
+  "circle-stop": CircleStop,
 } as const satisfies Readonly<Record<NavIconKey, typeof Folder>>;
 
 // Widened alias for runtime lookups against the plain `string` icon keys

package/src/layout/shell-breadcrumb.ts

@@ -19,6 +19,7 @@ function explicitListScreenId(screen: ScreenDefinition): string | undefined {
     case "projectionDetail":
     case "entityEdit":
     case "actionForm":
+    case "secretMint":
       return screen.listScreenId;
     default:
       return undefined;

package/src/primitives/__tests__/button.test.tsx

@@ -50,6 +50,14 @@ describe("DefaultButton icon (fw-ui-defaults)", () => {
     expect(btn.getAttribute("aria-label")).toBe("Delete");
   });
 
+  test("size='icon' without children renders the icon, accessible name comes from ariaLabel", () => {
+    render(<Button icon="trash" size="icon" ariaLabel="Delete" testId="btn" />);
+    const btn = screen.getByTestId("btn");
+    expect(btn.querySelector("svg")).not.toBeNull();
+    expect(btn.textContent).toBe("");
+    expect(screen.getByRole("button", { name: "Delete" })).toBe(btn);
+  });
+
   test("unknown icon key: no crash, falls back to rendering children only", () => {
     render(
       // @ts-expect-error — exercising the runtime fallback for a schema-supplied key outside the closed IconKey union

package/src/primitives/__tests__/number-placeholder.test.tsx

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { render } from "@testing-library/react";
+import { defaultPrimitives } from "../index";
+
+const { Input } = defaultPrimitives;
+const noop = () => {};
+
+describe("number placeholder", () => {
+  test("a declared placeholder reaches the rendered input", () => {
+    const { getByPlaceholderText } = render(
+      <Input kind="number" id="qty" name="qty" value="" onChange={noop} placeholder="0" />,
+    );
+    expect(getByPlaceholderText("0").tagName).toBe("INPUT");
+  });
+
+  test("without placeholder the attribute is not set", () => {
+    const { container } = render(
+      <Input kind="number" id="qty" name="qty" value="" onChange={noop} />,
+    );
+    const input = container.querySelector("input");
+    if (input === null) throw new Error("no input rendered");
+    expect(input.hasAttribute("placeholder")).toBe(false);
+  });
+});

package/src/primitives/__tests__/password-placeholder.test.tsx

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+import { render } from "@testing-library/react";
+import { defaultPrimitives } from "../index";
+
+const { Input } = defaultPrimitives;
+const noop = () => {};
+
+describe("password placeholder", () => {
+  test("a declared placeholder reaches the rendered input", () => {
+    const { getByPlaceholderText } = render(
+      <Input
+        kind="password"
+        id="pw"
+        name="pw"
+        value=""
+        onChange={noop}
+        placeholder="Passwort eingeben"
+      />,
+    );
+    expect(getByPlaceholderText("Passwort eingeben").tagName).toBe("INPUT");
+  });
+
+  test("without placeholder the attribute is not set", () => {
+    const { container } = render(
+      <Input kind="password" id="pw" name="pw" value="" onChange={noop} />,
+    );
+    const input = container.querySelector("input");
+    if (input === null) throw new Error("no input rendered");
+    expect(input.hasAttribute("placeholder")).toBe(false);
+  });
+});

package/src/primitives/__tests__/secret-reveal.test.tsx

@@ -0,0 +1,48 @@
+// fw#2838: SecretRevealValue.qr renders a scannable QR code (otpauth://-style
+// enrollment URI) instead of the default monospaced text display.
+import { describe, expect, test } from "bun:test";
+import { render, screen, waitFor } from "@testing-library/react";
+import { defaultPrimitives } from "../index";
+
+const { SecretReveal } = defaultPrimitives;
+if (SecretReveal === undefined) {
+  throw new Error("defaultPrimitives.SecretReveal is not registered");
+}
+
+describe("DefaultSecretReveal (fw#2548 / fw#2838)", () => {
+  test("without qr, renders the value as monospaced text", () => {
+    render(
+      <SecretReveal
+        values={[{ label: "Token", value: "kpat_secret", copyable: true, multiline: false }]}
+        copyLabel="Copy"
+        copiedLabel="Copied"
+        testId="reveal"
+      />,
+    );
+    const reveal = screen.getByTestId("reveal");
+    expect(reveal.textContent).toContain("kpat_secret");
+    expect(reveal.querySelector("svg")).toBeNull();
+  });
+
+  test("with qr: true, renders a scannable QR code instead of monospaced text", async () => {
+    render(
+      <SecretReveal
+        values={[
+          {
+            label: "Token",
+            value: "otpauth://totp/Example:alice?secret=ABC&issuer=Example",
+            copyable: false,
+            multiline: false,
+            qr: true,
+          },
+        ]}
+        copyLabel="Copy"
+        copiedLabel="Copied"
+        testId="reveal"
+      />,
+    );
+    const reveal = screen.getByTestId("reveal");
+    await waitFor(() => expect(reveal.querySelector("svg")).not.toBeNull());
+    expect(reveal.textContent).not.toContain("otpauth://");
+  });
+});

package/src/primitives/__tests__/textarea-placeholder.test.tsx

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+import { render } from "@testing-library/react";
+import { defaultPrimitives } from "../index";
+
+const { Input } = defaultPrimitives;
+const noop = () => {};
+
+describe("textarea placeholder", () => {
+  test("a declared placeholder reaches the rendered textarea", () => {
+    const { getByPlaceholderText } = render(
+      <Input
+        kind="textarea"
+        id="notes"
+        name="notes"
+        value=""
+        onChange={noop}
+        placeholder="Nachricht an den Agenten …"
+      />,
+    );
+    expect(getByPlaceholderText("Nachricht an den Agenten …").tagName).toBe("TEXTAREA");
+  });
+
+  test("without placeholder the attribute is not set", () => {
+    const { container } = render(
+      <Input kind="textarea" id="notes" name="notes" value="" onChange={noop} />,
+    );
+    const textarea = container.querySelector("textarea");
+    if (textarea === null) throw new Error("no textarea rendered");
+    expect(textarea.hasAttribute("placeholder")).toBe(false);
+  });
+});

package/src/primitives/index.tsx

@@ -36,6 +36,7 @@ import {
   type InputProps,
   type LinkProps,
   type ProgressProps,
+  type SecretRevealProps,
   type SectionProps,
   type StepBarProps,
   shouldRenderActionsIconOnly,
@@ -73,6 +74,7 @@ import {
   User,
   X,
 } from "lucide-react";
+import QRCode from "qrcode";
 import {
   type ChangeEvent,
   Children,
@@ -240,6 +242,7 @@ function DefaultBanner({
   id,
 }: BannerProps): ReactNode {
   const isError = variant === "error";
+  const isWarning = variant === "warning";
   // `id` is set when a <Field> wraps this Banner as its control (see
   // BannerProps.id). A <div> isn't labelable, so a <label htmlFor> pointing
   // at it is inert for screen readers — role="group" + aria-labelledby is
@@ -255,7 +258,9 @@ function DefaultBanner({
         "relative w-full rounded-lg border px-4 py-3 text-sm flex items-center gap-3",
         isError
           ? "border-destructive/50 text-destructive bg-destructive/10 dark:border-destructive"
-          : "bg-card text-card-foreground",
+          : isWarning
+            ? "border-status-warn/30 bg-status-warn/10 text-status-warn"
+            : "bg-card text-card-foreground",
       )}
     >
       <div className="flex-1">{children}</div>
@@ -591,6 +596,7 @@ function DefaultInput(props: InputProps): ReactNode {
           data-testid={props.testId}
           value={props.value}
           onChange={(e: ChangeEvent<HTMLInputElement>) => props.onChange(e.target.value)}
+          {...(props.placeholder !== undefined && { placeholder: props.placeholder })}
           autoComplete={props.autoComplete ?? "current-password"}
         />
       );
@@ -609,6 +615,7 @@ function DefaultInput(props: InputProps): ReactNode {
               const v = e.target.value;
               props.onChange(v === "" ? undefined : Number(v));
             }}
+            {...(props.placeholder !== undefined && { placeholder: props.placeholder })}
             className={cn(
               "text-right tabular-nums",
               fieldIconFor(props.icon) !== undefined ? "pl-8" : undefined,
@@ -815,6 +822,7 @@ function DefaultInput(props: InputProps): ReactNode {
           onChange={(e: ChangeEvent<HTMLTextAreaElement>) => props.onChange(e.target.value)}
           rows={rows ?? 4}
           className="resize-y"
+          {...(props.placeholder !== undefined && { placeholder: props.placeholder })}
           {...(rows !== undefined && { style: textareaMinHeight(rows) })}
         />
       );
@@ -2892,6 +2900,89 @@ export function DefaultCard({ slots, options, className, testId, children }: Car
   );
 }
 
+// otpauth:// enrollment URI → scannable QR (errorCorrectionLevel "H", ~30%
+// redundancy — more resilient to camera/lighting issues than the default, no
+// downside for a code this short-lived). Own component (not inline in
+// values.map) because QRCode.toString is async — a hook inside .map would
+// violate the rules of hooks.
+function QrSecretValue({ value }: { readonly value: string }): ReactNode {
+  const [svg, setSvg] = useState<string | null>(null);
+  useEffect(() => {
+    let cancelled = false;
+    QRCode.toString(value, { type: "svg", errorCorrectionLevel: "H" })
+      .then((result) => {
+        if (!cancelled) setSvg(result);
+      })
+      .catch(() => {
+        // a reveal value always has the plaintext/manual-entry display alongside — QR is just convenience
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [value]);
+  if (svg === null) return null;
+  return (
+    <div
+      className="h-40 w-40"
+      // qrcode's own SVG string output, not user input — safe to inline
+      // biome-ignore lint/security/noDangerouslySetInnerHtml: qrcode-generated SVG, no user input
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  );
+}
+
+// One-time secret reveal (fw#2548, secretMint confirm phase) — monospaced
+// per-value display with a copy button that flips to `copiedLabel` on
+// success. Silent-catch on clipboard error mirrors the copy-link pattern in
+// create-app.tsx.
+function DefaultSecretReveal({
+  values,
+  copyLabel,
+  copiedLabel,
+  testId,
+}: SecretRevealProps): ReactNode {
+  const [copiedIndex, setCopiedIndex] = useState<number | null>(null);
+  return (
+    <div data-testid={testId} className="flex flex-col gap-3">
+      {values.map((v, i) => (
+        <div key={v.label} className="flex flex-col gap-1.5">
+          <span className="text-sm font-medium text-muted-foreground">{v.label}</span>
+          <div className="flex items-start gap-2">
+            {v.qr === true ? (
+              <QrSecretValue value={v.value} />
+            ) : v.multiline ? (
+              <pre className="flex-1 overflow-x-auto whitespace-pre-wrap break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+                {v.value}
+              </pre>
+            ) : (
+              <code className="flex-1 overflow-x-auto whitespace-pre-wrap break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+                {v.value}
+              </code>
+            )}
+            {v.copyable && (
+              <UiButton
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={async () => {
+                  try {
+                    await navigator.clipboard.writeText(v.value);
+                    setCopiedIndex(i);
+                  } catch {
+                    // clipboard blocked (non-secure context) — no fallback UI needed here
+                  }
+                }}
+              >
+                {copiedIndex === i ? copiedLabel : copyLabel}
+              </UiButton>
+            )}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
 export const defaultPrimitives: CorePrimitives = {
   Button: DefaultButton,
   Banner: DefaultBanner,
@@ -2922,4 +3013,5 @@ export const defaultPrimitives: CorePrimitives = {
   JsonView: DefaultJsonView,
   FillContainer: DefaultFillContainer,
   ActionOverflowMenu,
+  SecretReveal: DefaultSecretReveal,
 };

package/src/widgets/__tests__/drawer.test.tsx

@@ -111,6 +111,100 @@ describe("Drawer", () => {
     });
   });
 
+  describe("variant", () => {
+    test("default (no variant prop): floating classes unchanged (inset-y-8, right-8, rounded-[2rem], default width)", () => {
+      render(
+        <Drawer open={true} onOpenChange={() => {}} side="right" testId="drawer">
+          <div>Body</div>
+        </Drawer>,
+      );
+      const content = screen.getByTestId("drawer");
+      expect(content.className).toContain("inset-y-8");
+      expect(content.className).toContain("right-8");
+      expect(content.className).toContain("rounded-[2rem]");
+      expect(content.className).toContain("w-[max(600px,37.5vw)]");
+    });
+
+    test('variant="flush" with side="right": inset-y-0, no radius, border-l only', () => {
+      render(
+        <Drawer open={true} onOpenChange={() => {}} side="right" variant="flush" testId="drawer">
+          <div>Body</div>
+        </Drawer>,
+      );
+      const content = screen.getByTestId("drawer");
+      expect(content.className).toContain("inset-y-0");
+      expect(content.className).not.toContain("rounded-[2rem]");
+      expect(content.className).not.toContain("inset-y-8");
+      expect(content.className).toContain("border-l");
+      expect(content.className).not.toContain("border-r");
+    });
+
+    test('variant="flush" with side="left": border-r only', () => {
+      render(
+        <Drawer open={true} onOpenChange={() => {}} side="left" variant="flush" testId="drawer">
+          <div>Body</div>
+        </Drawer>,
+      );
+      const content = screen.getByTestId("drawer");
+      expect(content.className).toContain("border-r");
+      expect(content.className).not.toContain("border-l");
+    });
+  });
+
+  describe("width", () => {
+    test("width={420}: reflected as inline pixel width", () => {
+      render(
+        <Drawer open={true} onOpenChange={() => {}} side="right" width={420} testId="drawer">
+          <div>Body</div>
+        </Drawer>,
+      );
+      expect(screen.getByTestId("drawer").style.width).toBe("420px");
+    });
+
+    test('width="30rem": reflected as-is (CSS length string)', () => {
+      render(
+        <Drawer open={true} onOpenChange={() => {}} side="right" width="30rem" testId="drawer">
+          <div>Body</div>
+        </Drawer>,
+      );
+      expect(screen.getByTestId("drawer").style.width).toBe("30rem");
+    });
+
+    test("no width prop: no inline width style (default stays class-driven)", () => {
+      render(
+        <Drawer open={true} onOpenChange={() => {}} side="right" testId="drawer">
+          <div>Body</div>
+        </Drawer>,
+      );
+      expect(screen.getByTestId("drawer").style.width).toBe("");
+    });
+
+    test('side="top": width prop is ignored', () => {
+      render(
+        <Drawer open={true} onOpenChange={() => {}} side="top" width={420} testId="drawer">
+          <div>Body</div>
+        </Drawer>,
+      );
+      expect(screen.getByTestId("drawer").style.width).toBe("");
+    });
+
+    test("resize set + width set: resize wins", () => {
+      render(
+        <Drawer
+          open={true}
+          onOpenChange={() => {}}
+          side="right"
+          width={420}
+          resize={{ defaultWidthPx: 350, minWidthPx: 300, maxWidthPx: 500 }}
+          testId="drawer"
+        >
+          <div>Body</div>
+        </Drawer>,
+      );
+      expect(screen.getByTestId("drawer").style.width).toBe("350px");
+    });
+  });
+
   describe("resize", () => {
     // happy-dom exposes innerWidth as an accessor (get/set) on the window
     // instance. Object.defineProperty(...) with a plain `value` replaces
@@ -423,6 +517,29 @@ describe("Drawer", () => {
       expect(content.className).not.toContain("inset-y-8");
     });
 
+    test('narrow with variant="flush": fullscreen branch unaffected, no inline width', () => {
+      mockMatchMedia(true);
+      render(
+        <Drawer
+          open={true}
+          onOpenChange={() => {}}
+          side="right"
+          variant="flush"
+          width={420}
+          testId="drawer"
+        >
+          <div>Body</div>
+        </Drawer>,
+      );
+      const content = screen.getByTestId("drawer");
+      expect(content.className).toContain("inset-0");
+      expect(content.className).toContain("w-full");
+      expect(content.className).not.toContain("rounded-[2rem]");
+      expect(content.className).not.toContain("inset-y-8");
+      expect(content.className).not.toContain("border-l");
+      expect(content.style.width).toBe("");
+    });
+
     test("narrow with resize set: no inline width style", () => {
       mockMatchMedia(true);
       render(

package/src/widgets/drawer.tsx

@@ -28,6 +28,17 @@ export type DrawerProps = {
    *  footer already has a dedicated close/cancel action, so there is only
    *  one way to dismiss the drawer. */
   readonly showCloseButton?: boolean;
+  /** Panel treatment. `"floating"` (default) keeps the detached-panel look
+   *  (margin to the viewport edge, full corner radius). `"flush"` docks the
+   *  panel against the edge instead — full extent, no radius, and a border
+   *  only on the edge facing the app content. Ignored in the narrow-viewport
+   *  fullscreen layout. */
+  readonly variant?: "floating" | "flush";
+  /** Panel width for `side="left"|"right"` (ignored for top/bottom and in
+   *  the narrow-viewport layout). A number is pixels, a string any CSS
+   *  length. Superseded by `resize` when that's set. Default matches the
+   *  panel's built-in `max(600px, 37.5vw)`. */
+  readonly width?: number | string;
   /** Opt-in drag-to-resize + maximize toggle (left/right sides only). */
   readonly resize?: {
     readonly defaultWidthPx?: number;
@@ -65,22 +76,49 @@ function defaultWidthFromViewport(): number {
     : Math.max(DEFAULT_WIDTH_MIN_PX, Math.round(window.innerWidth * DEFAULT_WIDTH_VIEWPORT_RATIO));
 }
 
-// 32px margin + 32px radius so the panel reads as detached from the
-// viewport edge, unlike the sheet primitive's flush-edge default. Below the
-// narrow-viewport breakpoint the floating treatment doesn't fit — the JS
-// hook decides, not a `sm:` Tailwind prefix, since the resize width below
-// already comes from JS and two decision sources is the bug this avoids.
-function floatingSideClass(side: "left" | "right" | "top" | "bottom", narrow: boolean): string {
+function normalizeWidth(width: number | string): string {
+  return typeof width === "number" ? `${width}px` : width;
+}
+
+// Must match the static `max(600px,37.5vw)` in sidePanelClass — Tailwind's
+// JIT can't read DEFAULT_WIDTH_MIN_PX/DEFAULT_WIDTH_VIEWPORT_RATIO at
+// runtime, so the two are kept in sync by hand.
+const WIDTH_CLASS = "w-[max(600px,37.5vw)] max-w-[85vw] sm:max-w-[max(600px,37.5vw)]";
+
+// "floating": 32px margin + 32px radius so the panel reads as detached from
+// the viewport edge, unlike the sheet primitive's flush-edge default.
+// "flush" docks it back to that flush-edge default instead, borrowing the
+// vendored Sheet's per-side border (only the edge facing the app content).
+// Below the narrow-viewport breakpoint neither treatment fits — the JS hook
+// decides, not a `sm:` Tailwind prefix, since the resize width below already
+// comes from JS and two decision sources is the bug this avoids.
+function sidePanelClass(
+  side: "left" | "right" | "top" | "bottom",
+  narrow: boolean,
+  variant: "floating" | "flush",
+): string {
   if (narrow) return "inset-0 h-full w-full max-w-none rounded-none border-0 overflow-hidden";
+  if (variant === "flush") {
+    switch (side) {
+      case "left":
+        return `inset-y-0 left-0 h-full ${WIDTH_CLASS} border-r shadow-2xl overflow-hidden`;
+      case "top":
+        return "inset-x-0 top-0 h-auto max-h-[80vh] border-b shadow-2xl overflow-hidden";
+      case "bottom":
+        return "inset-x-0 bottom-0 h-auto max-h-[80vh] border-t shadow-2xl overflow-hidden";
+      default:
+        return `inset-y-0 right-0 h-full ${WIDTH_CLASS} border-l shadow-2xl overflow-hidden`;
+    }
+  }
   switch (side) {
     case "left":
-      return "inset-y-8 left-8 h-auto w-[max(600px,37.5vw)] max-w-[85vw] sm:max-w-[max(600px,37.5vw)] rounded-[2rem] border shadow-2xl overflow-hidden";
+      return `inset-y-8 left-8 h-auto ${WIDTH_CLASS} rounded-[2rem] border shadow-2xl overflow-hidden`;
     case "top":
       return "inset-x-8 top-8 h-auto max-h-[80vh] rounded-[2rem] border shadow-2xl overflow-hidden";
     case "bottom":
       return "inset-x-8 bottom-8 h-auto max-h-[80vh] rounded-[2rem] border shadow-2xl overflow-hidden";
     default:
-      return "inset-y-8 right-8 h-auto w-[max(600px,37.5vw)] max-w-[85vw] sm:max-w-[max(600px,37.5vw)] rounded-[2rem] border shadow-2xl overflow-hidden";
+      return `inset-y-8 right-8 h-auto ${WIDTH_CLASS} rounded-[2rem] border shadow-2xl overflow-hidden`;
   }
 }
 
@@ -97,19 +135,25 @@ export function Drawer({
   children,
   testId,
   showCloseButton = true,
+  variant = "floating",
+  width,
   resize,
   backdrop,
 }: DrawerProps): ReactNode {
   const t = useTranslation();
   const narrow = useIsNarrowViewport();
   const canResize = resize !== undefined && (side === "left" || side === "right");
+  const customWidthStyle =
+    !canResize && !narrow && (side === "left" || side === "right") && width !== undefined
+      ? { width: normalizeWidth(width), maxWidth: "none" }
+      : undefined;
   const minWidthPx = resize?.minWidthPx ?? MIN_WIDTH_PX;
   const maxWidthPx = resize?.maxWidthPx ?? MAX_WIDTH_PX;
   const effectiveMaxWidthPx = () =>
     typeof window === "undefined"
       ? maxWidthPx
       : Math.min(maxWidthPx, Math.round(window.innerWidth * 0.9));
-  const [width, setWidth] = useState(() =>
+  const [resizedWidthPx, setResizedWidthPx] = useState(() =>
     clamp(resize?.defaultWidthPx ?? defaultWidthFromViewport(), minWidthPx, effectiveMaxWidthPx()),
   );
   const [maximized, setMaximized] = useState(false);
@@ -121,7 +165,7 @@ export function Drawer({
     ...(blurPx > 0 ? { backdropFilter: `blur(${blurPx}px)` } : {}),
   };
 
-  const effectiveWidthPx = maximized ? effectiveMaxWidthPx() : width;
+  const effectiveWidthPx = maximized ? effectiveMaxWidthPx() : resizedWidthPx;
 
   const onHandlePointerDown = (event: React.PointerEvent<HTMLDivElement>): void => {
     event.preventDefault();
@@ -137,7 +181,9 @@ export function Drawer({
     if (dragRef.current === null) return;
     const deltaX = event.clientX - dragRef.current.startX;
     const signedDelta = side === "right" ? -deltaX : deltaX;
-    setWidth(clamp(dragRef.current.startWidth + signedDelta, minWidthPx, effectiveMaxWidthPx()));
+    setResizedWidthPx(
+      clamp(dragRef.current.startWidth + signedDelta, minWidthPx, effectiveMaxWidthPx()),
+    );
   };
   const endHandlePointerDrag = (event: React.PointerEvent<HTMLDivElement>): void => {
     if (event.currentTarget.hasPointerCapture(event.pointerId)) {
@@ -154,11 +200,11 @@ export function Drawer({
     event.preventDefault();
     setMaximized(false);
     const delta = event.key === grow ? step : -step;
-    // Seed from the currently visible width, not the stale `width` state —
-    // while maximized, `width` still holds the pre-maximize value, so a key
-    // press would otherwise jump the drawer back to that old size instead
-    // of resizing relative to what's on screen.
-    setWidth((current) =>
+    // Seed from the currently visible width, not the stale `resizedWidthPx`
+    // state — while maximized, it still holds the pre-maximize value, so a
+    // key press would otherwise jump the drawer back to that old size
+    // instead of resizing relative to what's on screen.
+    setResizedWidthPx((current) =>
       clamp((maximized ? effectiveWidthPx : current) + delta, minWidthPx, effectiveMaxWidthPx()),
     );
   };
@@ -170,8 +216,10 @@ export function Drawer({
         data-testid={testId}
         overlayStyle={overlayStyle}
         showCloseButton={showCloseButton}
-        className={floatingSideClass(side, narrow)}
-        style={canResize && !narrow ? { width: effectiveWidthPx, maxWidth: "none" } : undefined}
+        className={sidePanelClass(side, narrow, variant)}
+        style={
+          canResize && !narrow ? { width: effectiveWidthPx, maxWidth: "none" } : customWidthStyle
+        }
       >
         {canResize && !narrow && (
           <button