sh3-core 0.10.4 → 0.11.2

package/dist/layout/ops.js

@@ -93,6 +93,33 @@ export function findTabInTree(tree, slotId) {
     }
     return null;
 }
+/**
+ * Locate the root a slot currently lives under in the given tree. Handles
+ * both tab entries and bare slot leaves, docked first then each float's
+ * content. Returns null when the slot is not present anywhere. Pure —
+ * takes the tree as input so callers with an in-hand tree (and tests)
+ * don't need the layout store.
+ */
+export function locateSlotIn(tree, slotId) {
+    if (containsSlot(tree.docked, slotId))
+        return { kind: 'docked' };
+    for (const f of tree.floats) {
+        if (containsSlot(f.content, slotId))
+            return { kind: 'float', floatId: f.id };
+    }
+    return null;
+}
+function containsSlot(node, slotId) {
+    if (node.type === 'slot')
+        return node.slotId === slotId;
+    if (node.type === 'tabs')
+        return node.tabs.some((t) => t.slotId === slotId);
+    for (const child of node.children) {
+        if (containsSlot(child, slotId))
+            return true;
+    }
+    return false;
+}
 // ---------- Tab removal ----------------------------------------------------
 /**
  * Remove a tab from its current location, returning the removed entry

package/dist/layout/slotHostPool.svelte.js

@@ -33,6 +33,8 @@
  *   phase 6 has no view that needs it.
  */
 import { getView, __addViewRegistrationListener } from '../shards/registry';
+import { locateSlotIn } from './ops';
+import { activeLayout } from './store.svelte';
 const pool = new Map();
 const pendingDestroy = new Set();
 /**
@@ -59,6 +61,9 @@ function onViewRegistered(viewId, factory) {
             setDirty(dirty) {
                 dirtyState[slotId] = dirty;
             },
+            location() {
+                return locateSlotIn(activeLayout(), slotId);
+            },
         };
         queueMicrotask(() => {
             var _a, _b;
@@ -129,6 +134,8 @@ function createHost(slotId, viewId, label, meta) {
     const host = document.createElement('div');
     host.className = 'slot-host';
     host.dataset.slotId = slotId;
+    if (viewId)
+        host.setAttribute('data-sh3-view', viewId);
     // Position:absolute inset:0 so the host fills whichever wrapper it is
     // attached to. The wrapper is what the layout engine sizes; the host
     // just tracks it. Styles are set inline (not in a class) so consumers
@@ -163,6 +170,9 @@ function createHost(slotId, viewId, label, meta) {
             setDirty(dirty) {
                 dirtyState[slotId] = dirty;
             },
+            location() {
+                return locateSlotIn(activeLayout(), slotId);
+            },
         };
         entry.handle = factory === null || factory === void 0 ? void 0 : factory.mount(host, ctx);
         if (((_a = entry.handle) === null || _a === void 0 ? void 0 : _a.closable) || slotId.startsWith('float:')) {
@@ -201,6 +211,20 @@ export function acquireSlotHost(slotId, viewId, label, meta) {
         entry = createHost(slotId, viewId, label, meta);
         pool.set(slotId, entry);
     }
+    else if (entry.viewId !== viewId) {
+        // viewId on an existing slot should be stable — the pool does not support
+        // swapping views for the same slotId. Keep the focus-tracking attribute
+        // in sync with whatever we have and warn; the underlying view handle will
+        // not be reconstructed.
+        console.warn(`[sh3] acquireSlotHost("${slotId}") called with viewId "${viewId}" ` +
+            `but existing pooled entry has viewId "${entry.viewId}". Attribute synced; ` +
+            `view handle unchanged.`);
+        entry.viewId = viewId;
+        if (viewId)
+            entry.host.setAttribute('data-sh3-view', viewId);
+        else
+            entry.host.removeAttribute('data-sh3-view');
+    }
     entry.refcount++;
     return entry.host;
 }

package/dist/layout/slotHostPool.test.js

@@ -102,3 +102,17 @@ describe('slotHostPool — D.5 root swap preserves app slots', () => {
         expect(teardown).not.toHaveBeenCalled();
     });
 });
+// ─── D.6 ─────────────────────────────────────────────────────────────────────
+describe('slotHostPool — D.6 data-sh3-view attribute', () => {
+    beforeEach(resetFramework);
+    it('pooled host has data-sh3-view when viewId is set', () => {
+        const host = acquireSlotHost('slot-1', 'editor', 'Editor');
+        expect(host.getAttribute('data-sh3-view')).toBe('editor');
+        releaseSlotHost('slot-1');
+    });
+    it('pooled host has no data-sh3-view when viewId is null', () => {
+        const host = acquireSlotHost('slot-2', null, 'Empty');
+        expect(host.hasAttribute('data-sh3-view')).toBe(false);
+        releaseSlotHost('slot-2');
+    });
+});

package/dist/layout/types.d.ts

@@ -21,6 +21,14 @@ export interface SplitNode {
     pinned?: SizeMode[];
     /** Per-child collapsed state. Omitted means all expanded. */
     collapsed?: boolean[];
+    /**
+     * Per-child fixed flag. A fixed child has no collapse widget and the
+     * resize handles on either side of it are frozen (non-interactive,
+     * rendered thinner). A non-fixed child whose every neighbor is fixed
+     * also loses its collapse widget — there's nowhere for the freed
+     * space to be used.
+     */
+    fixed?: boolean[];
     /** Ordered child nodes. Length must equal `sizes` length. */
     children: LayoutNode[];
 }
@@ -107,6 +115,13 @@ export interface FloatEntry {
     };
     /** Optional human-readable title; defaults to the active view's label. */
     title?: string;
+    /**
+     * When true, this float dismisses on any pointerdown outside its frame,
+     * renders its content as a raw slot (no tab-strip handle, not dockable),
+     * and hides chrome when `title` is unset. See
+     * docs/superpowers/specs/2026-04-21-dismissable-float-design.md.
+     */
+    dismissable?: boolean;
 }
 /**
  * Root shape of a workspace layout. The docked tree is the primary

package/dist/overlays/FloatFrame.svelte

@@ -18,6 +18,7 @@
 <script lang="ts">
   import LayoutRenderer from '../layout/LayoutRenderer.svelte';
   import { floatManager } from './float';
+  import { registerDismissableFrame, unregisterDismissableFrame } from './floatDismiss';
   import type { FloatEntry } from '../layout/types';
 
   interface Props {
@@ -27,6 +28,14 @@
 
   let dragging = $state(false);
   let dragOffset = { x: 0, y: 0 };
+  let frameEl: HTMLDivElement | undefined = $state();
+
+  $effect(() => {
+    if (!entry.dismissable) return;
+    if (!frameEl) return;
+    registerDismissableFrame(entry.id, frameEl);
+    return () => unregisterDismissableFrame(entry.id);
+  });
 
   function onHeaderPointerDown(e: PointerEvent): void {
     if (e.button !== 0) return;
@@ -67,6 +76,7 @@
 <!-- svelte-ignore a11y_click_events_have_key_events -->
 <div
   class="sh3-float-frame"
+  bind:this={frameEl}
   style:left="{entry.position.x}px"
   style:top="{entry.position.y}px"
   style:width="{entry.size.w}px"
@@ -76,17 +86,19 @@
   aria-label={entry.title ?? 'Float panel'}
   tabindex="-1"
 >
-  <!-- svelte-ignore a11y_no_static_element_interactions -->
-  <header
-    class="sh3-float-header"
-    onpointerdown={onHeaderPointerDown}
-    onpointermove={onHeaderPointerMove}
-    onpointerup={onHeaderPointerUp}
-    onpointercancel={onHeaderPointerUp}
-  >
-    <span class="sh3-float-title">{entry.title ?? entry.content.type}</span>
-    <button class="sh3-float-close" onclick={onClose} aria-label="Close float">×</button>
-  </header>
+  {#if entry.title}
+    <!-- svelte-ignore a11y_no_static_element_interactions -->
+    <header
+      class="sh3-float-header"
+      onpointerdown={onHeaderPointerDown}
+      onpointermove={onHeaderPointerMove}
+      onpointerup={onHeaderPointerUp}
+      onpointercancel={onHeaderPointerUp}
+    >
+      <span class="sh3-float-title">{entry.title}</span>
+      <button class="sh3-float-close" onclick={onClose} aria-label="Close float">×</button>
+    </header>
+  {/if}
   <div class="sh3-float-body">
     <LayoutRenderer rootRef={{ kind: 'float', floatId: entry.id }} path={[]} />
   </div>

package/dist/overlays/ModalFrame.svelte

@@ -34,11 +34,13 @@
     contentProps,
     close,
     boxStyle,
+    onBackdropClick,
   }: {
     Content: Component<Record<string, unknown>>;
     contentProps: Record<string, unknown>;
     close: () => void;
     boxStyle?: string;
+    onBackdropClick?: () => void;
   } = $props();
 
   let box: HTMLDivElement;
@@ -47,9 +49,15 @@
     if (!box) return;
     return createFocusTrap(box);
   });
+
+  function handleFrameClick(ev: MouseEvent): void {
+    if (!onBackdropClick) return;
+    if (ev.target !== ev.currentTarget) return; // descendant click — let it through
+    onBackdropClick();
+  }
 </script>
 
-<div class="modal-frame" role="presentation">
+<div class="modal-frame" role="presentation" onclick={handleFrameClick}>
   <div
     class="modal-box"
     role="dialog"

package/dist/overlays/ModalFrame.svelte.d.ts

@@ -4,6 +4,7 @@ type $$ComponentProps = {
     contentProps: Record<string, unknown>;
     close: () => void;
     boxStyle?: string;
+    onBackdropClick?: () => void;
 };
 declare const ModalFrame: Component<$$ComponentProps, {}, "">;
 type ModalFrame = ReturnType<typeof ModalFrame>;

package/dist/overlays/__test__/DummyFrame.svelte

@@ -0,0 +1,6 @@
+<script lang="ts">
+  // Minimal component for tests that need a popupManager.show() target.
+  // Popup infrastructure passes `close` as a prop; we accept it but don't use it here.
+  let { close: _close }: { close: () => void } = $props();
+</script>
+<div class="dummy-popup-content" style="width:10px;height:10px"></div>

package/dist/overlays/__test__/DummyFrame.svelte.d.ts

@@ -0,0 +1,6 @@
+type $$ComponentProps = {
+    close: () => void;
+};
+declare const DummyFrame: import("svelte").Component<$$ComponentProps, {}, "">;
+type DummyFrame = ReturnType<typeof DummyFrame>;
+export default DummyFrame;

package/dist/overlays/float.d.ts

@@ -9,6 +9,12 @@ export interface FloatOptions {
     size?: Size;
     /** Instance data threaded to the view factory via `MountContext.meta`. */
     meta?: Record<string, unknown>;
+    /**
+     * When true, the float dismisses on any pointerdown outside its frame,
+     * is not dockable, and renders without a header when `title` is unset.
+     * See docs/superpowers/specs/2026-04-21-dismissable-float-design.md.
+     */
+    dismissable?: boolean;
 }
 export interface FloatManager {
     open(viewId: string, options?: FloatOptions): string;

package/dist/overlays/float.js

@@ -73,15 +73,28 @@ function openFloat(viewId, options = {}) {
     // docked tree. The TabsNode's tab strip appears at the top of the
     // float body; the frame header still moves the float as a whole.
     const slotId = mintFloatSlotId(viewId);
-    const label = (_a = options.title) !== null && _a !== void 0 ? _a : viewId;
-    const tab = { slotId, viewId, label };
-    if (options.meta)
-        tab.meta = options.meta;
-    const content = {
-        type: 'tabs',
-        tabs: [tab],
-        activeTab: 0,
-    };
+    let content;
+    if (options.dismissable) {
+        // Picker float: render the view directly as a leaf slot. No tab strip,
+        // no tabs wrapper, no drag-to-dock handle. Note: options.meta cannot
+        // thread through a bare SlotNode — only TabEntry carries meta.
+        content = {
+            type: 'slot',
+            slotId,
+            viewId,
+        };
+    }
+    else {
+        const label = (_a = options.title) !== null && _a !== void 0 ? _a : viewId;
+        const tab = { slotId, viewId, label };
+        if (options.meta)
+            tab.meta = options.meta;
+        content = {
+            type: 'tabs',
+            tabs: [tab],
+            activeTab: 0,
+        };
+    }
     const computedMin = computeMinSize(content);
     const size = (_b = options.size) !== null && _b !== void 0 ? _b : maxSize(DEFAULT_SIZE, computedMin);
     const position = (_c = options.position) !== null && _c !== void 0 ? _c : cascadePosition(store, getTreeBounds());
@@ -92,6 +105,8 @@ function openFloat(viewId, options = {}) {
         size,
         title: options.title,
     };
+    if (options.dismissable)
+        entry.dismissable = true;
     store.push(entry);
     return id;
 }

package/dist/overlays/float.test.js

@@ -54,6 +54,31 @@ describe('floatManager', () => {
             expect(tabs.tabs[0].meta).toBeUndefined();
         }
     });
+    it('open() persists options.dismissable onto the FloatEntry', () => {
+        const id = floatManager.open('test:view', { dismissable: true });
+        const f = floatManager.list().find((e) => e.id === id);
+        expect(f.dismissable).toBe(true);
+    });
+    it('open() without options.dismissable leaves FloatEntry.dismissable undefined', () => {
+        const id = floatManager.open('test:view');
+        const f = floatManager.list().find((e) => e.id === id);
+        expect(f.dismissable).toBeUndefined();
+    });
+    it('open() with dismissable=true places content as a raw slot (no tabs wrap)', () => {
+        const id = floatManager.open('test:view', { dismissable: true });
+        const f = floatManager.list().find((e) => e.id === id);
+        expect(f.content.type).toBe('slot');
+        if (f.content.type === 'slot') {
+            expect(f.content.viewId).toBe('test:view');
+            expect(typeof f.content.slotId).toBe('string');
+            expect(f.content.slotId.length).toBeGreaterThan(0);
+        }
+    });
+    it('open() without dismissable still wraps content in a TabsNode', () => {
+        const id = floatManager.open('test:view');
+        const f = floatManager.list().find((e) => e.id === id);
+        expect(f.content.type).toBe('tabs');
+    });
 });
 // ---------------------------------------------------------------------------
 // DOM tests — floatManager + FloatLayer.svelte in happy-dom
@@ -62,6 +87,7 @@ import { renderWithShell } from '../__test__/render';
 import FloatLayer from './FloatLayer.svelte';
 import { tick } from 'svelte';
 import { resetFramework } from '../__test__/reset';
+import { __isDismissListenerAttachedForTest } from './floatDismiss';
 /**
  * Wire the floatManager to the same FloatEntry[] that FloatLayer reads
  * (layoutStore.floats → HOME_TREE.floats). Without this binding, the
@@ -136,3 +162,152 @@ describe('floats — F.3 close button removes float', () => {
         expect(container.querySelector('[role="dialog"][aria-label="Closeable"]')).toBeNull();
     });
 });
+// ---------------------------------------------------------------------------
+// F.4 — header conditional on title
+// ---------------------------------------------------------------------------
+describe('floats — F.4 header conditional on title', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('renders no header when title is not provided', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        floatManager.open('test:view', { dismissable: true });
+        await tick();
+        const frame = container.querySelector('[role="dialog"]');
+        expect(frame).toBeTruthy();
+        expect(frame.querySelector('.sh3-float-header')).toBeNull();
+        expect(frame.querySelector('.sh3-float-close')).toBeNull();
+    });
+    it('renders the header with close button when title is provided', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        floatManager.open('test:view', { dismissable: true, title: 'Picker' });
+        await tick();
+        const frame = container.querySelector('[role="dialog"][aria-label="Picker"]');
+        expect(frame).toBeTruthy();
+        expect(frame.querySelector('.sh3-float-header')).not.toBeNull();
+        expect(frame.querySelector('button[aria-label="Close float"]')).not.toBeNull();
+    });
+});
+// ---------------------------------------------------------------------------
+// F.5a — dismiss-listener lifecycle
+// ---------------------------------------------------------------------------
+describe('floats — F.5a dismiss-listener lifecycle', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('attaches the document listener when a dismissable frame mounts', async () => {
+        renderWithShell(FloatLayer, {});
+        expect(__isDismissListenerAttachedForTest()).toBe(false);
+        floatManager.open('test:view', { dismissable: true });
+        await tick();
+        expect(__isDismissListenerAttachedForTest()).toBe(true);
+    });
+    it('detaches the document listener when the last dismissable frame unmounts', async () => {
+        renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', { dismissable: true });
+        await tick();
+        expect(__isDismissListenerAttachedForTest()).toBe(true);
+        floatManager.close(id);
+        await tick();
+        expect(__isDismissListenerAttachedForTest()).toBe(false);
+    });
+    it('does not attach the listener for non-dismissable floats', async () => {
+        renderWithShell(FloatLayer, {});
+        floatManager.open('test:view', { title: 'Regular' });
+        await tick();
+        expect(__isDismissListenerAttachedForTest()).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// F.5b — outside-pointerdown dismisses picker
+// ---------------------------------------------------------------------------
+describe('floats — F.5b outside-pointerdown dismisses picker', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    function pointerDown(el) {
+        el.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
+    }
+    it('closes a dismissable float when pointerdown fires outside its frame', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', { dismissable: true, title: 'Picker' });
+        await tick();
+        expect(floatManager.list().some((f) => f.id === id)).toBe(true);
+        pointerDown(document.body);
+        await tick();
+        expect(floatManager.list().some((f) => f.id === id)).toBe(false);
+        expect(container.querySelector('[role="dialog"][aria-label="Picker"]')).toBeNull();
+    });
+    it('does not close a dismissable float when pointerdown fires inside its frame', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', { dismissable: true, title: 'Picker' });
+        await tick();
+        const frame = container.querySelector('[role="dialog"][aria-label="Picker"]');
+        expect(frame).toBeTruthy();
+        pointerDown(frame);
+        await tick();
+        expect(floatManager.list().some((f) => f.id === id)).toBe(true);
+    });
+    it('does not close a non-dismissable float on outside pointerdown', async () => {
+        renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', { title: 'Regular' });
+        await tick();
+        pointerDown(document.body);
+        await tick();
+        expect(floatManager.list().some((f) => f.id === id)).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// F.6 — multi-picker interaction
+// ---------------------------------------------------------------------------
+describe('floats — F.6 multi-picker interaction', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    function pointerDown(el) {
+        el.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
+    }
+    it('clicking inside picker A closes picker B but keeps A', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const a = floatManager.open('test:view', { dismissable: true, title: 'A' });
+        const b = floatManager.open('test:view', { dismissable: true, title: 'B' });
+        await tick();
+        const frameA = container.querySelector('[role="dialog"][aria-label="A"]');
+        expect(frameA).toBeTruthy();
+        pointerDown(frameA);
+        await tick();
+        const ids = floatManager.list().map((f) => f.id);
+        expect(ids).toContain(a);
+        expect(ids).not.toContain(b);
+    });
+    it('clicking a persistent float closes every open picker', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const reg = floatManager.open('test:view', { title: 'Regular' });
+        const picker1 = floatManager.open('test:view', { dismissable: true, title: 'P1' });
+        const picker2 = floatManager.open('test:view', { dismissable: true, title: 'P2' });
+        await tick();
+        const frameReg = container.querySelector('[role="dialog"][aria-label="Regular"]');
+        expect(frameReg).toBeTruthy();
+        pointerDown(frameReg);
+        await tick();
+        const ids = floatManager.list().map((f) => f.id);
+        expect(ids).toContain(reg);
+        expect(ids).not.toContain(picker1);
+        expect(ids).not.toContain(picker2);
+    });
+    it('closing a picker via its × button fires exactly one close (no double-close from listener)', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', { dismissable: true, title: 'Picker' });
+        await tick();
+        const closeBtn = container.querySelector('[role="dialog"][aria-label="Picker"] button[aria-label="Close float"]');
+        expect(closeBtn).toBeTruthy();
+        pointerDown(closeBtn);
+        closeBtn.click();
+        await tick();
+        expect(floatManager.list().some((f) => f.id === id)).toBe(false);
+    });
+});

package/dist/overlays/floatDismiss.d.ts

@@ -0,0 +1,8 @@
+/** Register a dismissable float's root element. Idempotent per id. */
+export declare function registerDismissableFrame(id: string, el: HTMLElement): void;
+/** Unregister on frame destroy. Idempotent; safe to call for unknown ids. */
+export declare function unregisterDismissableFrame(id: string): void;
+/** Test-only inspector: is the singleton listener currently attached? */
+export declare function __isDismissListenerAttachedForTest(): boolean;
+/** Test-only reset. Clears the registry and detaches the listener. */
+export declare function __resetDismissRegistryForTest(): void;

package/dist/overlays/floatDismiss.js

@@ -0,0 +1,68 @@
+/*
+ * Dismiss-listener registry for dismissable ("picker") floats.
+ *
+ * Each `FloatFrame` whose entry is dismissable registers its root DOM
+ * element here on mount and unregisters on destroy. A singleton
+ * `pointerdown` listener is installed on `document` as soon as the
+ * registry becomes non-empty and removed when it empties.
+ *
+ * On pointerdown, every registered entry whose element does not contain
+ * the event target is closed via floatManager.close. The listener uses
+ * capture=true so it runs before any in-view click handlers; the picker's
+ * own action handlers fire on `click`/`pointerup` and are unaffected.
+ */
+import { floatManager } from './float';
+const registry = new Map();
+let listenerAttached = false;
+function onDocumentPointerDown(event) {
+    if (registry.size === 0)
+        return;
+    const target = event.target;
+    if (!target)
+        return;
+    // Snapshot ids — we mutate the registry (via close → unregister) while iterating.
+    const ids = Array.from(registry.keys());
+    for (const id of ids) {
+        const el = registry.get(id);
+        if (!el)
+            continue;
+        if (!el.contains(target)) {
+            floatManager.close(id);
+        }
+    }
+}
+function ensureListener() {
+    if (listenerAttached)
+        return;
+    if (typeof document === 'undefined')
+        return;
+    document.addEventListener('pointerdown', onDocumentPointerDown, true);
+    listenerAttached = true;
+}
+function teardownListenerIfEmpty() {
+    if (!listenerAttached)
+        return;
+    if (registry.size > 0)
+        return;
+    document.removeEventListener('pointerdown', onDocumentPointerDown, true);
+    listenerAttached = false;
+}
+/** Register a dismissable float's root element. Idempotent per id. */
+export function registerDismissableFrame(id, el) {
+    registry.set(id, el);
+    ensureListener();
+}
+/** Unregister on frame destroy. Idempotent; safe to call for unknown ids. */
+export function unregisterDismissableFrame(id) {
+    registry.delete(id);
+    teardownListenerIfEmpty();
+}
+/** Test-only inspector: is the singleton listener currently attached? */
+export function __isDismissListenerAttachedForTest() {
+    return listenerAttached;
+}
+/** Test-only reset. Clears the registry and detaches the listener. */
+export function __resetDismissRegistryForTest() {
+    registry.clear();
+    teardownListenerIfEmpty();
+}

package/dist/overlays/modal.js

@@ -8,7 +8,10 @@
  * Semantics (from docs/design/layout.md):
  *   - Modals stack. Opening a second modal pushes it on top of the first.
  *   - Escape pops the topmost modal.
- *   - Backdrop click does NOT dismiss. Content owns its own close UI.
+ *   - Backdrop click does NOT dismiss by default. Per-modal opt-in via
+ *     `ModalOptions.dismissOnBackdrop` (used by the command palette and
+ *     other picker-style modals where outside-click is the expected
+ *     dismissal gesture). See ADR-005 for the per-layer policy.
  *   - Each modal has its own focus trap (installed by ModalFrame).
  *
  * Implementation notes:
@@ -120,6 +123,7 @@ function openModal(Content, props, options) {
             contentProps: (props !== null && props !== void 0 ? props : {}),
             close: handle.close,
             boxStyle: options === null || options === void 0 ? void 0 : options.boxStyle,
+            onBackdropClick: (options === null || options === void 0 ? void 0 : options.dismissOnBackdrop) ? handle.close : undefined,
         },
     });
     entry.host = host;

package/dist/overlays/modal.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/overlays/modal.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { tick } from 'svelte';
+import { modalManager } from './modal';
+import { registerLayerRoot, unregisterLayerRoot } from './roots';
+import DummyFrame from './__test__/DummyFrame.svelte';
+function makeLayerRoot() {
+    const el = document.createElement('div');
+    el.style.position = 'relative';
+    document.body.appendChild(el);
+    registerLayerRoot('modal', el);
+    return el;
+}
+function teardownLayerRoot(el) {
+    unregisterLayerRoot('modal');
+    el.remove();
+}
+describe('modal — backdrop dismiss policy', () => {
+    let layerRoot;
+    beforeEach(() => {
+        layerRoot = makeLayerRoot();
+    });
+    afterEach(() => {
+        modalManager.closeAll();
+        teardownLayerRoot(layerRoot);
+    });
+    it('default modal: clicking the frame area outside the box does NOT dismiss', async () => {
+        modalManager.open(DummyFrame, {});
+        await tick();
+        const frame = layerRoot.querySelector('.modal-frame');
+        expect(frame).not.toBeNull();
+        // Click the frame itself (outside the box). target === currentTarget
+        // is what the handler keys off.
+        frame.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+        await tick();
+        expect(layerRoot.querySelector('.sh3-modal-host')).not.toBeNull();
+    });
+    it('opt-in modal: clicking the frame area outside the box closes it', async () => {
+        modalManager.open(DummyFrame, {}, { dismissOnBackdrop: true });
+        await tick();
+        const frame = layerRoot.querySelector('.modal-frame');
+        expect(frame).not.toBeNull();
+        frame.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+        await tick();
+        expect(layerRoot.querySelector('.sh3-modal-host')).toBeNull();
+    });
+    it('opt-in modal: clicks on the dialog box itself do NOT dismiss', async () => {
+        modalManager.open(DummyFrame, {}, { dismissOnBackdrop: true });
+        await tick();
+        const box = layerRoot.querySelector('.modal-box');
+        expect(box).not.toBeNull();
+        box.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+        await tick();
+        expect(layerRoot.querySelector('.sh3-modal-host')).not.toBeNull();
+    });
+});