sh3-core 0.17.0 → 0.19.0

package/dist/layout/presets.d.ts

@@ -1,2 +1,14 @@
 import type { LayoutNode, LayoutTree, LayoutPreset, CanonicalPreset } from './types';
+import type { ViewportClass } from '../viewport/types';
+/**
+ * Pick the active LayoutTree for a preset given the current viewport
+ * class. Compact viewport uses `variants.compact` if authored, else
+ * falls back to `variants.default`. Desktop always uses `variants.default`.
+ *
+ * Per spec §4 (Override path): when the compact variant is taken as-is,
+ * any role-tagged sidebar/inspector slots in *it* still get extracted
+ * into drawers by the derive() transform. So an explicit override
+ * doesn't have to author drawer chrome — only the docked structure.
+ */
+export declare function resolveActiveTree(preset: CanonicalPreset, cls: ViewportClass): LayoutTree;
 export declare function normalizeInitialLayout(input: LayoutNode | LayoutTree | LayoutPreset[]): CanonicalPreset[];

package/dist/layout/presets.js

@@ -35,6 +35,22 @@ function canonicalizePreset(p) {
     }
     return { name: p.name, variants };
 }
+/**
+ * Pick the active LayoutTree for a preset given the current viewport
+ * class. Compact viewport uses `variants.compact` if authored, else
+ * falls back to `variants.default`. Desktop always uses `variants.default`.
+ *
+ * Per spec §4 (Override path): when the compact variant is taken as-is,
+ * any role-tagged sidebar/inspector slots in *it* still get extracted
+ * into drawers by the derive() transform. So an explicit override
+ * doesn't have to author drawer chrome — only the docked structure.
+ */
+export function resolveActiveTree(preset, cls) {
+    if (cls === 'compact' && preset.variants.compact) {
+        return preset.variants.compact;
+    }
+    return preset.variants.default;
+}
 export function normalizeInitialLayout(input) {
     if (Array.isArray(input)) {
         return input.map(canonicalizePreset);

package/dist/layout/store.drawers.svelte.test.d.ts

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

package/dist/layout/store.drawers.svelte.test.js

@@ -0,0 +1,49 @@
+/*
+ * Drawer persistence round-trip — open the right drawer, simulate a
+ * remount (call attachApp twice on the same blob), assert the open
+ * state survived.
+ *
+ * The test uses the layoutStore's app-attach machinery directly rather
+ * than going through createShell, since the drawerStore <→ blob binding
+ * is the unit under test.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { flushSync } from 'svelte';
+import { attachApp, detachApp, __resetLayoutStoreForTest } from './store.svelte';
+import { drawerStore } from './compact/drawerStore.svelte';
+function fakeApp() {
+    // Minimal App shape — only fields attachApp reads.
+    return {
+        manifest: { id: 'test-app', layoutVersion: 5 },
+        initialLayout: {
+            type: 'split', direction: 'horizontal', sizes: [0.3, 0.7],
+            children: [
+                { type: 'slot', slotId: 'sb', viewId: 'v:sb', role: 'sidebar' },
+                { type: 'slot', slotId: 'body', viewId: 'v:body', role: 'body' },
+            ],
+        },
+    };
+}
+describe('drawer persistence round-trip', () => {
+    beforeEach(() => {
+        __resetLayoutStoreForTest();
+        drawerStore.__reset();
+    });
+    it('drawer state survives detach + re-attach', async () => {
+        const app = fakeApp();
+        attachApp(app);
+        // Run the proxy's initial $effect so the "first run skip" is consumed
+        // before our mutations. Subsequent mutations will trigger real flushes.
+        flushSync();
+        drawerStore.open('right');
+        drawerStore.activate('right', 'sb');
+        flushSync();
+        await new Promise((r) => queueMicrotask(r));
+        detachApp();
+        drawerStore.__reset();
+        expect(drawerStore.state.right.open).toBe(false);
+        attachApp(app);
+        expect(drawerStore.state.right.open).toBe(true);
+        expect(drawerStore.state.right.activeSlotId).toBe('sb');
+    });
+});

package/dist/layout/store.schemaVersion.test.d.ts

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

package/dist/layout/store.schemaVersion.test.js

@@ -0,0 +1,35 @@
+/*
+ * Schema-version regression — a stored AppLayoutBlob written under
+ * LAYOUT_SCHEMA_VERSION 4 (no role hints, no drawers) must load cleanly
+ * under v5. The bump is purely additive; if this test breaks, the
+ * additive promise is broken.
+ */
+import { describe, it, expect } from 'vitest';
+import { LAYOUT_SCHEMA_VERSION } from './types';
+describe('layout schema v4 → v5 backward compatibility', () => {
+    it('a v4 blob loads with all roles undefined and drawers absent', () => {
+        const tree = {
+            docked: {
+                type: 'split',
+                direction: 'horizontal',
+                sizes: [0.3, 0.7],
+                children: [
+                    { type: 'slot', slotId: 'a', viewId: 'view:a' },
+                    { type: 'slot', slotId: 'b', viewId: 'view:b' },
+                ],
+            },
+            floats: [],
+        };
+        const v4Blob = {
+            layoutVersion: 4,
+            activePreset: 'default',
+            presets: { default: { default: tree } },
+        };
+        const slotA = v4Blob.presets.default.default.docked.children[0];
+        expect(slotA.role).toBeUndefined();
+        expect(v4Blob.drawers).toBeUndefined();
+    });
+    it('LAYOUT_SCHEMA_VERSION is 6', () => {
+        expect(LAYOUT_SCHEMA_VERSION).toBe(6);
+    });
+});

package/dist/layout/store.svelte.js

@@ -31,10 +31,12 @@
  */
 import { createStateZones, peekZone, clearZone } from '../state/zones.svelte';
 import { acquireSlotHost, releaseSlotHost } from './slotHostPool.svelte';
-import { normalizeInitialLayout } from './presets';
+import { normalizeInitialLayout, resolveActiveTree } from './presets';
+import { viewportStore } from '../viewport/store.svelte';
 import { collectTreeSlotRefs } from './tree-walk';
 import { bindPresetBlob, unbindPresetBlob } from '../overlays/presets';
 import { getRegisteredApp } from '../apps/registry.svelte';
+import { drawerStore } from './compact/drawerStore.svelte';
 // ---------- orphan cleanup of pre-phase-8 sh3 layout key ----------------
 // Legacy pre-phase-8 orphan cleanup. The literal '__shell__' here is
 // intentional — it clears data written under the old reserved id before
@@ -140,6 +142,44 @@ export function attachApp(app) {
     // so shards can read/switch presets from their activate() hook.
     appEntry = { appId: app.manifest.id, proxy, heldSlotIds: [] };
     bindPresetBlob(proxy);
+    bindDrawerStoreToBlob(proxy);
+}
+/**
+ * Sync drawerStore <→ AppLayoutBlob.drawers.
+ *
+ * On attach (or preset/viewport change): read the persisted snapshot for
+ * (activePreset, 'compact') and hydrate drawerStore. Bind a
+ * write-through callback so subsequent mutations persist.
+ *
+ * v1 only persists the 'compact' viewport class; future viewport classes
+ * (e.g. 'phone') would extend this map without schema work.
+ */
+function bindDrawerStoreToBlob(blob) {
+    const presetName = blob.activePreset;
+    const ensure = () => {
+        if (!blob.drawers)
+            blob.drawers = {};
+        if (!blob.drawers[presetName])
+            blob.drawers[presetName] = {};
+        if (!blob.drawers[presetName].compact) {
+            blob.drawers[presetName].compact = {
+                left: { open: false, activeSlotId: null },
+                right: { open: false, activeSlotId: null },
+                top: { open: false, activeSlotId: null },
+            };
+        }
+        return blob.drawers;
+    };
+    const persisted = ensure();
+    drawerStore.__hydrate(persisted[presetName].compact);
+    drawerStore.__setWriteThrough((next) => {
+        const drawers = ensure();
+        drawers[presetName].compact = {
+            left: Object.assign({}, next.left),
+            right: Object.assign({}, next.right),
+            top: Object.assign({}, next.top),
+        };
+    });
 }
 /**
  * Second-phase attach: take refcount holds on every slot in the active
@@ -231,6 +271,12 @@ export function detachApp() {
     if (!appEntry)
         return;
     unbindPresetBlob();
+    drawerStore.__setWriteThrough(null);
+    drawerStore.__hydrate({
+        left: { open: false, activeSlotId: null },
+        right: { open: false, activeSlotId: null },
+        top: { open: false, activeSlotId: null },
+    });
     for (const slotId of appEntry.heldSlotIds) {
         releaseSlotHost(slotId);
     }
@@ -271,7 +317,11 @@ const activeTree = $derived.by(() => {
         if (!preset) {
             throw new Error(`AppLayoutBlob active preset "${presetName}" not found in presets map`);
         }
-        return preset.default;
+        // Per ADR-024: when the viewport is compact and the preset declares
+        // a `compact` variant, that variant wins. Otherwise the default
+        // variant is used and the framework derives drawer chrome from
+        // role-tagged slots in it.
+        return resolveActiveTree({ name: presetName, variants: preset }, viewportStore.current.class);
     }
     return HOME_TREE;
 });

package/dist/layout/types.d.ts

@@ -1,5 +1,15 @@
 /** Axis along which a split node divides its children. */
 export type SplitDirection = 'horizontal' | 'vertical';
+/**
+ * Slot role hint. Inert on desktop; the framework reads it on small
+ * viewports to derive a compact rendering (sidebars/inspectors lift into
+ * drawer surfaces, body slots fill the page).
+ *
+ * Default `'body'`. Authored on a slot or tab entry; if unset, falls back
+ * to the view's `defaultRole` (registered via the shard contract). See
+ * `layout/compact/resolveRole.ts`.
+ */
+export type SlotRole = 'body' | 'sidebar' | 'inspector';
 /** How a child of a split node is sized. */
 export type SizeMode = 'fr' | 'px';
 /**
@@ -46,6 +56,11 @@ export interface TabEntry {
     label: string;
     /** Optional icon hint (not yet rendered in phase 8). */
     icon?: string;
+    /**
+     * Slot-role hint for compact rendering. Default `'body'` via
+     * `resolveRole(slot, viewDefault)`. Inert on desktop.
+     */
+    role?: SlotRole;
     /**
      * Caller-supplied instance data, threaded to `MountContext.meta`.
      * Ephemeral — not serialized with the layout tree.
@@ -74,6 +89,14 @@ export interface TabsNode {
      * Runtime-only — not serialized with the layout tree.
      */
     emptyRenderer?: (container: HTMLElement) => void;
+    /**
+     * When the framework renders this group as a compact-mode carousel,
+     * controls end-of-track behavior:
+     *   - false (default): edge-resist (rubber-band, snap back).
+     *   - true: warpback (swipe past last → first; past first → last).
+     * Inert when not rendered as a carousel.
+     */
+    wrap?: boolean;
 }
 /**
  * A leaf layout node that holds a single mounted view. `slotId` is the stable
@@ -86,6 +109,11 @@ export interface SlotNode {
     slotId: string;
     /** View id to mount into this slot, or null for an empty slot. */
     viewId: string | null;
+    /**
+     * Slot-role hint for compact rendering. Default `'body'` via
+     * `resolveRole(slot, viewDefault)`. Inert on desktop.
+     */
+    role?: SlotRole;
     /**
      * Caller-supplied instance data, threaded to `MountContext.meta`.
      * Ephemeral — not serialized with the layout tree. Mirrors
@@ -187,7 +215,7 @@ export type TreeRootRef = {
  * the default tree takes over — phase 7 deliberately does not ship a
  * migration framework, only the hook for one.
  */
-export declare const LAYOUT_SCHEMA_VERSION = 4;
+export declare const LAYOUT_SCHEMA_VERSION = 6;
 /**
  * The wire shape of a persisted layout in the workspace state zone.
  * One blob per sh3 (or per program, once per-program layouts exist);
@@ -208,6 +236,14 @@ export interface PersistedLayout {
  * The `attachApp` read path wraps that shape into the new form rather
  * than discarding it; see `layout/store.svelte.ts`.
  */
+/**
+ * Persisted per-anchor drawer state — open flag and active slot id.
+ * Lives on `AppLayoutBlob.drawers[presetName][viewportClass][anchor]`.
+ */
+export interface DrawerStateBlob {
+    open: boolean;
+    activeSlotId: string | null;
+}
 export interface AppLayoutBlob {
     layoutVersion: number;
     /** Name of the currently-active preset. Must be a key of `presets`. */
@@ -222,4 +258,18 @@ export interface AppLayoutBlob {
             [variantName: string]: LayoutTree;
         };
     };
+    /**
+     * Drawer state keyed by `(presetName, viewportClass)`. Optional so
+     * legacy blobs without this field still load. v1 only writes the
+     * `'compact'` viewport-class key. See ADR-024.
+     */
+    drawers?: {
+        [presetName: string]: {
+            [viewportClass: string]: {
+                left: DrawerStateBlob;
+                right: DrawerStateBlob;
+                top: DrawerStateBlob;
+            };
+        };
+    };
 }

package/dist/layout/types.js

@@ -22,4 +22,4 @@
  * the default tree takes over — phase 7 deliberately does not ship a
  * migration framework, only the hook for one.
  */
-export const LAYOUT_SCHEMA_VERSION = 4;
+export const LAYOUT_SCHEMA_VERSION = 6;

package/dist/layout/types.test.d.ts

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

package/dist/layout/types.test.js

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { LAYOUT_SCHEMA_VERSION } from './types';
+describe('TabsNode.wrap', () => {
+    it('accepts the optional wrap field', () => {
+        const tabs = {
+            type: 'tabs',
+            tabs: [{ slotId: 's1', viewId: null, label: 'A' }],
+            activeTab: 0,
+            wrap: true,
+        };
+        expect(tabs.wrap).toBe(true);
+    });
+    it('defaults to undefined (consumers treat as false)', () => {
+        const tabs = {
+            type: 'tabs',
+            tabs: [{ slotId: 's1', viewId: null, label: 'A' }],
+            activeTab: 0,
+        };
+        expect(tabs.wrap).toBeUndefined();
+    });
+});
+describe('LAYOUT_SCHEMA_VERSION', () => {
+    it('is 6 (bumped for TabsNode.wrap)', () => {
+        expect(LAYOUT_SCHEMA_VERSION).toBe(6);
+    });
+});

package/dist/overlays/DrawerSurface.svelte

@@ -0,0 +1,141 @@
+<script lang="ts">
+  /*
+   * One drawer frame anchored to an edge. Renders nothing when closed.
+   * Open state slides the panel in over a backdrop. Tapping the backdrop
+   * fires onClose; tapping the close button does the same.
+   *
+   * Multi-slot drawers render a tab strip in the header. Single-slot
+   * drawers show the slot label only.
+   *
+   * Slot rendering goes through the standard SlotContainer path so the
+   * pooled host (and the mounted view) survives mount/unmount via the
+   * slot host pool — same mechanism as tab-drag re-parents.
+   */
+  import type { DrawerAnchor, DrawerSpec } from '../layout/compact/types';
+  import type { SlotNode } from '../layout/types';
+  import SlotContainer from '../layout/SlotContainer.svelte';
+
+  let {
+    anchor,
+    spec,
+    open,
+    activeSlotId,
+    onClose,
+    onActivate,
+  }: {
+    anchor: DrawerAnchor;
+    spec: DrawerSpec;
+    open: boolean;
+    activeSlotId: string | null;
+    onClose: () => void;
+    onActivate: (slotId: string) => void;
+  } = $props();
+
+  const activeSlot = $derived(
+    spec.slots.find((s) => s.slotId === activeSlotId) ?? spec.slots[0],
+  );
+
+  const slotNode: SlotNode = $derived({
+    type: 'slot',
+    slotId: activeSlot.slotId,
+    viewId: activeSlot.viewId,
+    role: activeSlot.role,
+  });
+</script>
+
+{#if open}
+  <div
+    class="drawer-backdrop"
+    onclick={onClose}
+    onkeydown={(e) => { if (e.key === 'Escape') onClose(); }}
+    role="presentation"
+  ></div>
+  <div
+    class="drawer drawer-{anchor}"
+    data-sh3-region="drawer"
+    data-sh3-anchor={anchor}
+  >
+    <header>
+      <span class="title">{activeSlot.label}</span>
+      <button
+        class="close"
+        onclick={onClose}
+        aria-label="Close drawer"
+      >×</button>
+    </header>
+    {#if spec.slots.length > 1}
+      <div class="tab-strip" role="tablist">
+        {#each spec.slots as s (s.slotId)}
+          <button
+            role="tab"
+            aria-selected={s.slotId === activeSlot.slotId}
+            class:active={s.slotId === activeSlot.slotId}
+            onclick={() => onActivate(s.slotId)}
+          >
+            {s.label}
+          </button>
+        {/each}
+      </div>
+    {/if}
+    <div class="body">
+      <SlotContainer node={slotNode} label={activeSlot.label} />
+    </div>
+  </div>
+{/if}
+
+<style>
+  .drawer-backdrop {
+    position: absolute;
+    inset: 0;
+    background: var(--sh3-overlay-backdrop, rgba(0, 0, 0, 0.35));
+    pointer-events: auto;
+  }
+  .drawer {
+    position: absolute;
+    background: var(--sh3-bg);
+    color: var(--sh3-fg);
+    box-shadow: var(--sh3-shadow-md, 0 0 16px rgba(0, 0, 0, 0.2));
+    display: flex;
+    flex-direction: column;
+    border: 1px solid var(--sh3-border);
+    pointer-events: auto;
+  }
+  .drawer-left  { top: 0; bottom: 0; left: 0;  width: min(360px, 80vw); }
+  .drawer-right { top: 0; bottom: 0; right: 0; width: min(360px, 80vw); }
+  .drawer-top   { left: 0; right: 0; top: 0;   height: min(50vh, 360px); }
+  header {
+    display: flex;
+    align-items: center;
+    padding: var(--sh3-pad-sm) var(--sh3-pad-md);
+    gap: var(--sh3-pad-md);
+    border-bottom: 1px solid var(--sh3-border);
+    background: var(--sh3-bg-elevated);
+  }
+  .title { font-weight: 600; }
+  .close {
+    margin-left: auto;
+    background: none;
+    border: none;
+    font-size: var(--sh3-font-lg);
+    cursor: pointer;
+    color: var(--sh3-fg-muted);
+    padding: 0 var(--sh3-pad-sm);
+  }
+  .close:hover { color: var(--sh3-fg); }
+  .tab-strip {
+    display: flex;
+    gap: 2px;
+    padding: var(--sh3-pad-xs) var(--sh3-pad-sm) 0;
+    background: var(--sh3-bg-sunken);
+  }
+  .tab-strip button {
+    padding: var(--sh3-pad-xs) var(--sh3-pad-sm);
+    border: 1px solid var(--sh3-border);
+    background: var(--sh3-bg-elevated);
+    border-bottom: none;
+    cursor: pointer;
+    color: var(--sh3-fg);
+  }
+  .tab-strip button.active { background: var(--sh3-bg); }
+  .body { flex: 1; min-height: 0; overflow: auto; }
+</style>

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

@@ -0,0 +1,12 @@
+import type { DrawerAnchor, DrawerSpec } from '../layout/compact/types';
+type $$ComponentProps = {
+    anchor: DrawerAnchor;
+    spec: DrawerSpec;
+    open: boolean;
+    activeSlotId: string | null;
+    onClose: () => void;
+    onActivate: (slotId: string) => void;
+};
+declare const DrawerSurface: import("svelte").Component<$$ComponentProps, {}, "">;
+type DrawerSurface = ReturnType<typeof DrawerSurface>;
+export default DrawerSurface;

package/dist/overlays/DrawerSurface.svelte.test.d.ts

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

package/dist/overlays/DrawerSurface.svelte.test.js

@@ -0,0 +1,67 @@
+/*
+ * DOM smoke test for DrawerSurface — when open with a single-slot spec,
+ * the drawer renders the slot's label in its header. When closed, it
+ * renders nothing.
+ *
+ * Re-parent contract testing (slot DOM container actually moves, doesn't
+ * remount) is handled by the browser-mode handheld-flip test.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import { mount, unmount, flushSync } from 'svelte';
+import DrawerSurface from './DrawerSurface.svelte';
+const DrawerSurfaceAny = DrawerSurface;
+const spec = {
+    slots: [{ slotId: 'sb', viewId: 'v:sb', label: 'Files', role: 'sidebar' }],
+};
+const multiSpec = {
+    slots: [
+        { slotId: 'sb', viewId: 'v:sb', label: 'Files', role: 'sidebar' },
+        { slotId: 'pin', viewId: 'v:pin', label: 'Pinned', role: 'sidebar' },
+    ],
+};
+let mounted = null;
+let host = null;
+function renderHost(props) {
+    host = document.createElement('div');
+    host.style.position = 'relative';
+    document.body.appendChild(host);
+    mounted = mount(DrawerSurfaceAny, { target: host, props });
+    flushSync();
+    return host;
+}
+afterEach(() => {
+    if (mounted) {
+        unmount(mounted);
+        mounted = null;
+    }
+    if (host) {
+        host.remove();
+        host = null;
+    }
+});
+describe('DrawerSurface (dom)', () => {
+    it('renders nothing when closed', () => {
+        const el = renderHost({
+            anchor: 'left', spec, open: false, activeSlotId: null,
+            onClose: () => { }, onActivate: () => { },
+        });
+        expect(el.querySelector('[data-sh3-region="drawer"]')).toBeNull();
+    });
+    it('renders header with slot label when open', () => {
+        const el = renderHost({
+            anchor: 'left', spec, open: true, activeSlotId: 'sb',
+            onClose: () => { }, onActivate: () => { },
+        });
+        const header = el.querySelector('[data-sh3-region="drawer"] header');
+        expect(header === null || header === void 0 ? void 0 : header.textContent).toContain('Files');
+    });
+    it('multi-slot drawer renders a tab strip with one button per slot', () => {
+        const el = renderHost({
+            anchor: 'left', spec: multiSpec, open: true, activeSlotId: 'pin',
+            onClose: () => { }, onActivate: () => { },
+        });
+        const tabs = el.querySelectorAll('[data-sh3-region="drawer"] .tab-strip button');
+        expect(tabs.length).toBe(2);
+        expect(tabs[1].classList.contains('active')).toBe(true);
+    });
+});

package/dist/overlays/ModalFrame.svelte

@@ -35,19 +35,21 @@
     close,
     boxStyle,
     onBackdropClick,
+    initialFocus = true,
   }: {
     Content: Component<Record<string, unknown>>;
     contentProps: Record<string, unknown>;
     close: () => void;
     boxStyle?: string;
     onBackdropClick?: () => void;
+    initialFocus?: boolean;
   } = $props();
 
   let box: HTMLDivElement;
 
   $effect(() => {
     if (!box) return;
-    return createFocusTrap(box);
+    return createFocusTrap(box, { initialFocus });
   });
 
   function handleFrameClick(ev: MouseEvent): void {

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

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

package/dist/overlays/OverlayRoots.svelte

@@ -23,13 +23,16 @@
 
   // Layer metadata — order matches the stack in docs/design/layout.md.
   // Index 0 here is layer 1 (floating panels); layer 0 is the content area.
-  const overlayLayers: { layer: number; name: OverlayLayer }[] = [
-    { layer: 1, name: 'floating'     },
-    { layer: 2, name: 'drag-preview' },
-    { layer: 3, name: 'popup'        },
-    { layer: 4, name: 'modal'        },
-    { layer: 5, name: 'toast'        },
-    { layer: 6, name: 'command'      },
+  // The 'drawers' layer (compact-mode side panels) sits between docked (0)
+  // and floating (1); its z-index comes from --sh3-z-layer-drawers.
+  const overlayLayers: { layer: number | string; name: OverlayLayer; zToken: string }[] = [
+    { layer: 'drawers',     name: 'drawers',      zToken: '--sh3-z-layer-drawers' },
+    { layer: 1, name: 'floating',     zToken: '--sh3-z-layer-1' },
+    { layer: 2, name: 'drag-preview', zToken: '--sh3-z-layer-2' },
+    { layer: 3, name: 'popup',        zToken: '--sh3-z-layer-3' },
+    { layer: 4, name: 'modal',        zToken: '--sh3-z-layer-4' },
+    { layer: 5, name: 'toast',        zToken: '--sh3-z-layer-5' },
+    { layer: 6, name: 'command',      zToken: '--sh3-z-layer-6' },
   ];
 
   const overlayRoots: Partial<Record<OverlayLayer, HTMLDivElement>> = $state({});
@@ -55,12 +58,12 @@
 </script>
 
 <div class="sh3-overlays" aria-hidden="true">
-  {#each overlayLayers as { layer, name } (layer)}
+  {#each overlayLayers as { layer, name, zToken } (layer)}
     <div
       class="sh3-overlay-root"
       data-sh3-overlay={name}
       data-sh3-layer={layer}
-      style="z-index: var(--sh3-z-layer-{layer});"
+      style="z-index: var({zToken});"
       bind:this={overlayRoots[name]}
     >
       {#if name === 'floating'}

package/dist/overlays/floatDismiss.js

@@ -12,11 +12,16 @@
  * own action handlers fire on `click`/`pointerup` and are unaffected.
  */
 import { floatManager } from './float';
+import { getOwner } from '../gestures';
 const registry = new Map();
 let listenerAttached = false;
 function onDocumentPointerDown(event) {
     if (registry.size === 0)
         return;
+    // Skip dismiss if a gesture has claimed this pointer — a swipe or drag
+    // is in progress and this pointerdown is not a real outside-click.
+    if (getOwner(event.pointerId))
+        return;
     const target = event.target;
     if (!target)
         return;