sh3-core 0.1.0

package/dist/layout/store.svelte.js

@@ -0,0 +1,150 @@
+/*
+ * Layout manager — owns both the framework-constant shell home layout
+ * and the currently-active app's persisted layout, and swaps between
+ * them without tearing down the held tree.
+ *
+ * The manager is the sole owner of "which layout root is being rendered
+ * right now". LayoutRenderer reads `layoutStore.root` (a getter on the
+ * active tree); drag.svelte.ts and any other mutation site do the same.
+ * Neither needs to know whether the active tree is home or an app.
+ *
+ * Refcount-hold discipline:
+ *   The slot host pool is refcount-based with a microtask-deferred
+ *   destroy. A root swap (app → home) causes the app's SlotContainers
+ *   to unmount and release their pool entries; home's slots have
+ *   different ids, so nothing re-acquires the app's pool entries before
+ *   the microtask fires, and the app's views would be destroyed. To
+ *   prevent this, attaching an app calls `acquireSlotHost` for every
+ *   slot id in the app's current layout tree once (in addition to what
+ *   the renderer does when the tree is active). That hold keeps
+ *   refcount ≥ 1 across swaps. Detaching an app releases the holds.
+ *
+ *   Home does not need a hold — it is either rendered or unmounted
+ *   entirely (there is no "held home while rendering app" state).
+ *
+ * Orphan cleanup:
+ *   The pre-phase-8 shell wrote to `sh3:workspace:__shell__`. Phase 8
+ *   switches to per-app keys; the old entry would otherwise sit as dead
+ *   data. On first load after upgrade, the manager clears that orphan
+ *   unconditionally (clearing a non-existent entry is a no-op).
+ */
+import { createStateZones, peekZone, clearZone } from '../state/zones.svelte';
+import { acquireSlotHost, releaseSlotHost } from './slotHostPool.svelte';
+import { collectSlotRefs } from './tree-walk';
+// ---------- orphan cleanup of pre-phase-8 shell layout key ----------------
+clearZone('workspace', '__shell__');
+// ---------- home layout (framework constant, in-memory only) --------------
+/**
+ * The home layout is a single slot wrapping the shell:home view. The
+ * slot id is reserved (`shell.home`) and stable so the pool entry for
+ * home survives across boot/launch cycles.
+ */
+const HOME_LAYOUT = {
+    type: 'slot',
+    slotId: 'shell.home',
+    viewId: 'shell:home',
+};
+let appEntry = $state(null);
+let activeRoot = $state('home');
+// ---------- public (within-framework) API ---------------------------------
+/**
+ * Attach an app: create or hydrate its workspace-zone layout proxy,
+ * enforce the blueprint version gate, and take a refcount hold on all
+ * of the app's slot ids so root swaps don't destroy its pooled hosts.
+ * Does NOT switch the active root. Call switchToApp() separately.
+ */
+export function attachApp(app) {
+    if (appEntry) {
+        throw new Error(`Layout manager cannot attach app "${app.manifest.id}": app "${appEntry.appId}" is still attached`);
+    }
+    const shardId = `__shell__:app:${app.manifest.id}`;
+    // Version gate: if a stored blob's layoutVersion doesn't match the
+    // app's current declaration, discard it so createStateZones falls
+    // back to the defaults (the app's initialLayout).
+    const stored = peekZone('workspace', shardId);
+    if (stored != null) {
+        const asBlob = stored;
+        if (asBlob.layoutVersion !== app.manifest.layoutVersion) {
+            clearZone('workspace', shardId);
+        }
+    }
+    const state = createStateZones(shardId, {
+        workspace: {
+            layoutVersion: app.manifest.layoutVersion,
+            root: app.initialLayout,
+        },
+    });
+    const proxy = state.workspace;
+    // Take a refcount hold on every slot in the app's tree. These holds
+    // keep the pooled hosts alive across home⇄app swaps. They are
+    // acquired without attaching the returned host anywhere — the
+    // LayoutRenderer still acquires its own refs when it mounts the
+    // tree, so the active rendering doesn't double-hold harmfully (the
+    // pool's destroy logic just sees refcount 2, then 1 on release).
+    const refs = collectSlotRefs(proxy.root);
+    const heldSlotIds = [];
+    for (const { slotId, viewId, label } of refs) {
+        acquireSlotHost(slotId, viewId, label);
+        heldSlotIds.push(slotId);
+    }
+    appEntry = { appId: app.manifest.id, proxy, heldSlotIds };
+}
+/**
+ * Detach the currently-attached app. Releases its refcount holds; the
+ * pool's microtask cleanup drops the pooled hosts if they also have no
+ * active renderer refs. Must be called before attaching a different app.
+ */
+export function detachApp() {
+    if (!appEntry)
+        return;
+    for (const slotId of appEntry.heldSlotIds) {
+        releaseSlotHost(slotId);
+    }
+    appEntry = null;
+    // If we detach while the active root is 'app', the renderer now has
+    // nothing to show; callers must switchToHome() before or after
+    // detachApp. We don't auto-switch here so the ordering is explicit.
+}
+export function switchToHome() {
+    activeRoot = 'home';
+}
+export function switchToApp() {
+    if (!appEntry) {
+        throw new Error('Cannot switchToApp: no app is attached');
+    }
+    activeRoot = 'app';
+}
+/**
+ * The currently-rendered root. LayoutRenderer reads this through the
+ * `layoutStore` export below. Home uses the framework constant;
+ * app uses the workspace-zone proxy's `root` (which is reactive, so
+ * mutations from splitter/drag/ops reach the renderer unchanged).
+ */
+export function activeLayout() {
+    if (activeRoot === 'app' && appEntry)
+        return appEntry.proxy.root;
+    return HOME_LAYOUT;
+}
+export function getActiveRoot() {
+    return activeRoot;
+}
+export function getAttachedAppId() {
+    var _a;
+    return (_a = appEntry === null || appEntry === void 0 ? void 0 : appEntry.appId) !== null && _a !== void 0 ? _a : null;
+}
+// ---------- `layoutStore` back-compat shim -------------------------------
+/**
+ * Preserved for callers that still read `layoutStore.root`. The getter
+ * delegates to `activeLayout()` so every read walks through the
+ * manager. Writes to `layoutStore.root` are disallowed (mutation is
+ * expected to happen on the returned tree's nodes in place, as in
+ * phase 7 — splitter drags mutate `sizes[i]`, tab clicks mutate
+ * `activeTab`, drag-commit calls `ops.ts` functions that mutate
+ * children arrays). Nothing in the codebase currently reassigns
+ * `layoutStore.root`, so this getter-only shape is sufficient.
+ */
+export const layoutStore = {
+    get root() {
+        return activeLayout();
+    },
+};

package/dist/layout/tree-walk.d.ts

@@ -0,0 +1,15 @@
+import type { LayoutNode } from './types';
+/**
+ * Collect the slot id / view id pairs of every slot leaf (including the
+ * slots embedded inside tabs entries) in a layout tree. Used by the
+ * layout manager to hold pool refs for a non-rendered but still-resident
+ * app tree. Order is a pre-order walk; the returned list may contain
+ * the same slot id twice if the tree is malformed, but ops.ts maintains
+ * the invariant that slot ids are unique so that is not a concern in
+ * practice.
+ */
+export declare function collectSlotRefs(tree: LayoutNode): {
+    slotId: string;
+    viewId: string | null;
+    label: string;
+}[];

package/dist/layout/tree-walk.js

@@ -0,0 +1,33 @@
+/*
+ * Layout tree traversal utilities shared between the layout manager
+ * and other consumers (refcount-hold, diagnostic inspection).
+ */
+/**
+ * Collect the slot id / view id pairs of every slot leaf (including the
+ * slots embedded inside tabs entries) in a layout tree. Used by the
+ * layout manager to hold pool refs for a non-rendered but still-resident
+ * app tree. Order is a pre-order walk; the returned list may contain
+ * the same slot id twice if the tree is malformed, but ops.ts maintains
+ * the invariant that slot ids are unique so that is not a concern in
+ * practice.
+ */
+export function collectSlotRefs(tree) {
+    const out = [];
+    const walk = (node) => {
+        if (node.type === 'slot') {
+            out.push({ slotId: node.slotId, viewId: node.viewId, label: node.viewId || node.slotId });
+            return;
+        }
+        if (node.type === 'tabs') {
+            for (const t of node.tabs) {
+                out.push({ slotId: t.slotId, viewId: t.viewId, label: t.label });
+            }
+            return;
+        }
+        // split
+        for (const c of node.children)
+            walk(c);
+    };
+    walk(tree);
+    return out;
+}

package/dist/layout/types.d.ts

@@ -0,0 +1,108 @@
+/** Axis along which a split node divides its children. */
+export type SplitDirection = 'horizontal' | 'vertical';
+/** How a child of a split node is sized. */
+export type SizeMode = 'fr' | 'px';
+/**
+ * A layout node that divides its area into two or more children along an axis.
+ * Children are sized proportionally (`fr`) or pixel-pinned (`px`). Supports
+ * per-child collapsed state so panels can be hidden without removing them.
+ */
+export interface SplitNode {
+    type: 'split';
+    /** Axis along which children are arranged. */
+    direction: SplitDirection;
+    /**
+     * Per-child size. Interpretation depends on the parallel `pinned` entry:
+     *   - 'fr' (default): proportional weight; reflows on resize.
+     *   - 'px':           pixel-pinned; held fixed while 'fr' siblings absorb deltas.
+     */
+    sizes: number[];
+    /** Per-child sizing mode. Omitted entries default to 'fr'. */
+    pinned?: SizeMode[];
+    /** Per-child collapsed state. Omitted means all expanded. */
+    collapsed?: boolean[];
+    /** Ordered child nodes. Length must equal `sizes` length. */
+    children: LayoutNode[];
+}
+/**
+ * A single tab descriptor inside a `TabsNode`. Each entry corresponds to one
+ * slot: `slotId` is the stable identifier the framework uses to key persistent
+ * state, `viewId` names the shard view to mount (null means the slot is empty).
+ */
+export interface TabEntry {
+    /** Stable identifier for the slot. Persisted with the layout. */
+    slotId: string;
+    /** View id to mount into this slot, or null for an empty slot. */
+    viewId: string | null;
+    /** Human-readable label shown in the tab strip. */
+    label: string;
+    /** Optional icon hint (not yet rendered in phase 8). */
+    icon?: string;
+}
+/**
+ * A layout node that groups one or more slots as tabs, showing one at a time.
+ * The active tab index drives which slot is visible; the others stay mounted
+ * in the background so they survive tab switches without re-initialization.
+ */
+export interface TabsNode {
+    type: 'tabs';
+    tabs: TabEntry[];
+    activeTab: number;
+    /**
+     * If true, the node is not pruned by cleanupTree when its last tab is
+     * closed. The layout renderer shows an empty-state placeholder instead.
+     * Typically set by app layout blueprints on structural tab groups.
+     */
+    persistent?: boolean;
+    /**
+     * Custom renderer for the empty state when all tabs are closed (only
+     * meaningful when `persistent` is true). Called with the container
+     * element; the app has full control over what's rendered.
+     * Runtime-only — not serialized with the layout tree.
+     */
+    emptyRenderer?: (container: HTMLElement) => void;
+}
+/**
+ * A leaf layout node that holds a single mounted view. `slotId` is the stable
+ * identifier used to key view state; `viewId` is the shard-registered view to
+ * mount. A null `viewId` means the slot is present in the tree but empty.
+ */
+export interface SlotNode {
+    type: 'slot';
+    /** Stable identifier for this slot. Persisted with the layout. */
+    slotId: string;
+    /** View id to mount into this slot, or null for an empty slot. */
+    viewId: string | null;
+}
+/**
+ * Union of all layout node kinds. The recursive tree is composed entirely of
+ * these three types: `split` → children, `tabs` → slots, `slot` → leaf.
+ */
+export type LayoutNode = SplitNode | TabsNode | SlotNode;
+/**
+ * Schema version for persisted layouts. Bump this when the shape of
+ * `LayoutNode` (or anything reachable from it) changes incompatibly.
+ * A stored entry whose version does not match is discarded on boot and
+ * 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 = 3;
+/**
+ * The wire shape of a persisted layout in the workspace state zone.
+ * One blob per shell (or per program, once per-program layouts exist);
+ * the version field gates compatibility.
+ */
+export interface PersistedLayout {
+    version: typeof LAYOUT_SCHEMA_VERSION;
+    root: LayoutNode;
+}
+/**
+ * Per-app layout blob written to the workspace state zone under
+ * `__shell__:app:<appId>`. The `layoutVersion` is the app's own
+ * `AppManifest.layoutVersion`; on launch a mismatch discards the blob
+ * and the app's `initialLayout` is used.
+ */
+export interface AppLayoutBlob {
+    layoutVersion: number;
+    root: LayoutNode;
+}

package/dist/layout/types.js

@@ -0,0 +1,25 @@
+/*
+ * Layout tree types — the single source of truth for docked layout topology.
+ *
+ * See docs/design/layout.md for rationale. The tree is recursive with three
+ * node kinds:
+ *
+ *   - split: horizontal or vertical, with proportional sizes and optional
+ *            per-child pixel pinning.
+ *   - tabs:  a tab group with one active tab at a time. Each tab owns a slot.
+ *   - slot:  leaf. Carries a stable slotId so state can be keyed to it, and
+ *            a viewId that names the view a shard should mount into it.
+ *            viewId is null for empty slots.
+ *
+ * Views are mounted into slots by the shard registry (phase 4). Trees are
+ * serialized to the workspace state zone for persistence (phase 7) — see
+ * `PersistedLayout` at the bottom of this file.
+ */
+/**
+ * Schema version for persisted layouts. Bump this when the shape of
+ * `LayoutNode` (or anything reachable from it) changes incompatibly.
+ * A stored entry whose version does not match is discarded on boot and
+ * the default tree takes over — phase 7 deliberately does not ship a
+ * migration framework, only the hook for one.
+ */
+export const LAYOUT_SCHEMA_VERSION = 3;

package/dist/overlays/ModalFrame.svelte

@@ -0,0 +1,87 @@
+<script lang="ts">
+  /*
+   * ModalFrame — the internal wrapper that the modal manager mounts into
+   * a per-modal host div inside the layer-4 root.
+   *
+   * Responsibilities:
+   *   - Span the full layer as a transparent centering container so every
+   *     modal box renders in the middle of the shell.
+   *   - Catch pointer events on the area around the box so clicks outside
+   *     the top modal do not fall through to modals beneath or to the
+   *     underlying layout.
+   *   - Dynamically render the caller's content component with its props.
+   *   - Install a focus trap on the dialog box for as long as the frame
+   *     lives, restoring previous focus on teardown.
+   *
+   * The frame does NOT render a backdrop. The modal manager owns a single
+   * shared backdrop element under the layer-4 root whose opacity scales
+   * (capped) with stack depth — otherwise per-frame backdrops compound
+   * into full black once a few modals are stacked, and every layer also
+   * pays its own composite cost.
+   *
+   * Escape-to-close and backdrop-click policy are decided by the manager,
+   * not the frame — the manager holds the stack and knows which modal is
+   * on top. The frame just receives a `close` callback and invokes it if
+   * the caller wants a built-in close button (there is none by default —
+   * content owns its chrome).
+   */
+
+  import type { Component } from 'svelte';
+  import { createFocusTrap } from './focusTrap';
+
+  let {
+    Content,
+    contentProps,
+    close,
+    boxStyle,
+  }: {
+    Content: Component<Record<string, unknown>>;
+    contentProps: Record<string, unknown>;
+    close: () => void;
+    boxStyle?: string;
+  } = $props();
+
+  let box: HTMLDivElement;
+
+  $effect(() => {
+    if (!box) return;
+    return createFocusTrap(box);
+  });
+</script>
+
+<div class="modal-frame" role="presentation">
+  <div
+    class="modal-box"
+    role="dialog"
+    aria-modal="true"
+    tabindex="-1"
+    bind:this={box}
+    style={boxStyle}
+  >
+    <Content {...contentProps} {close} />
+  </div>
+</div>
+
+<style>
+  .modal-frame {
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-items: center;
+    /* Transparent but pointer-capturing so clicks around the box are
+       swallowed rather than falling through to modals beneath. */
+    pointer-events: auto;
+  }
+  .modal-box {
+    background: var(--shell-bg-elevated);
+    color: var(--shell-fg);
+    border: 1px solid var(--shell-border-strong);
+    border-radius: 4px;
+    min-width: 320px;
+    max-width: min(640px, 90vw);
+    max-height: 90vh;
+    overflow: auto;
+    box-shadow: 0 20px 48px rgba(0, 0, 0, 0.5);
+    outline: none;
+  }
+</style>

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

@@ -0,0 +1,10 @@
+import type { Component } from 'svelte';
+type $$ComponentProps = {
+    Content: Component<Record<string, unknown>>;
+    contentProps: Record<string, unknown>;
+    close: () => void;
+    boxStyle?: string;
+};
+declare const ModalFrame: Component<$$ComponentProps, {}, "">;
+type ModalFrame = ReturnType<typeof ModalFrame>;
+export default ModalFrame;

package/dist/overlays/PopupFrame.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+  /*
+   * PopupFrame — positioned wrapper for a popup's content component.
+   *
+   * Takes an anchor rect in viewport coordinates and places itself at
+   * bottom-start with a viewport overflow clamp. The measurement happens
+   * after mount via an $effect so we can read the real frame size; an
+   * initial render off-screen hides the flicker while we measure.
+   *
+   * Positioning policy for phase 5:
+   *   - Preferred: bottom-start (top = anchor.bottom + 4, left = anchor.left)
+   *   - If the frame's right edge would exit the viewport, shift left so it
+   *     sits flush with the right edge minus a small margin.
+   *   - If the frame's bottom edge would exit the viewport, flip to above
+   *     the anchor (top = anchor.top - frameHeight - 4).
+   *   - If it still doesn't fit, clamp to the viewport.
+   *
+   * Additional placements (right-start, left-start, etc.) arrive when a
+   * real shard needs them; phase 5 doesn't.
+   */
+
+  import type { Component } from 'svelte';
+
+  let {
+    Content,
+    contentProps,
+    anchorRect,
+    close,
+  }: {
+    Content: Component<Record<string, unknown>>;
+    contentProps: Record<string, unknown>;
+    anchorRect: DOMRect;
+    close: () => void;
+  } = $props();
+
+  let frame: HTMLDivElement;
+  let top = $state(-9999);
+  let left = $state(-9999);
+
+  $effect(() => {
+    if (!frame) return;
+    const rect = frame.getBoundingClientRect();
+    const margin = 4;
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+
+    let t = anchorRect.bottom + margin;
+    let l = anchorRect.left;
+
+    if (l + rect.width > vw - margin) {
+      l = Math.max(margin, vw - rect.width - margin);
+    }
+    if (t + rect.height > vh - margin) {
+      const flipped = anchorRect.top - rect.height - margin;
+      t = flipped >= margin ? flipped : Math.max(margin, vh - rect.height - margin);
+    }
+
+    top = t;
+    left = l;
+  });
+</script>
+
+<div
+  class="popup-frame"
+  role="menu"
+  tabindex="-1"
+  style="top: {top}px; left: {left}px;"
+  bind:this={frame}
+>
+  <Content {...contentProps} {close} />
+</div>
+
+<style>
+  .popup-frame {
+    position: absolute;
+    background: var(--shell-bg-elevated);
+    color: var(--shell-fg);
+    border: 1px solid var(--shell-border-strong);
+    border-radius: 3px;
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+    min-width: 120px;
+    outline: none;
+    pointer-events: auto;
+  }
+</style>

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

@@ -0,0 +1,10 @@
+import type { Component } from 'svelte';
+type $$ComponentProps = {
+    Content: Component<Record<string, unknown>>;
+    contentProps: Record<string, unknown>;
+    anchorRect: DOMRect;
+    close: () => void;
+};
+declare const PopupFrame: Component<$$ComponentProps, {}, "">;
+type PopupFrame = ReturnType<typeof PopupFrame>;
+export default PopupFrame;

package/dist/overlays/ToastItem.svelte

@@ -0,0 +1,77 @@
+<script lang="ts">
+  /*
+   * ToastItem — a single auto-dismissing notification.
+   *
+   * The toast manager mounts one ToastItem per notification into the
+   * layer-5 root. The item renders the message, applies level styling,
+   * and fades/slides in on mount. The manager (not the item) owns the
+   * auto-dismiss timer, so the item stays purely presentational.
+   *
+   * Dismiss-on-click is built into the item via the close prop so users
+   * can dismiss a toast early without waiting for its timer.
+   */
+
+  import type { ToastLevel } from './types';
+
+  let {
+    message,
+    level,
+    close,
+  }: {
+    message: string;
+    level: ToastLevel;
+    close: () => void;
+  } = $props();
+</script>
+
+<!-- svelte-ignore a11y_click_events_have_key_events -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<div
+  class="toast toast-{level}"
+  role="status"
+  aria-live="polite"
+  onclick={close}
+>
+  <span class="toast-level">{level}</span>
+  <span class="toast-message">{message}</span>
+</div>
+
+<style>
+  .toast {
+    pointer-events: auto;
+    display: flex;
+    align-items: center;
+    gap: var(--shell-pad-md);
+    padding: var(--shell-pad-sm) var(--shell-pad-md);
+    background: var(--shell-bg-elevated);
+    color: var(--shell-fg);
+    border: 1px solid var(--shell-border-strong);
+    border-left-width: 3px;
+    border-radius: 3px;
+    box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
+    font-size: 12px;
+    min-width: 220px;
+    max-width: 360px;
+    cursor: pointer;
+    animation: toast-in 160ms ease-out both;
+  }
+  .toast-level {
+    text-transform: uppercase;
+    font-family: var(--shell-font-mono);
+    font-size: 10px;
+    letter-spacing: 0.5px;
+    color: var(--shell-fg-muted);
+  }
+  .toast-message { flex: 1; }
+
+  .toast-info    { border-left-color: var(--shell-accent); }
+  .toast-success { border-left-color: #5cb176; }
+  .toast-warn    { border-left-color: #d6a84a; }
+  .toast-error   { border-left-color: #d06060; }
+
+  @keyframes toast-in {
+    from { opacity: 0; transform: translateY(8px); }
+    to   { opacity: 1; transform: translateY(0); }
+  }
+</style>

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

@@ -0,0 +1,9 @@
+import type { ToastLevel } from './types';
+type $$ComponentProps = {
+    message: string;
+    level: ToastLevel;
+    close: () => void;
+};
+declare const ToastItem: import("svelte").Component<$$ComponentProps, {}, "">;
+type ToastItem = ReturnType<typeof ToastItem>;
+export default ToastItem;

package/dist/overlays/focusTrap.d.ts

@@ -0,0 +1 @@
+export declare function createFocusTrap(container: HTMLElement): () => void;

package/dist/overlays/focusTrap.js

@@ -0,0 +1,64 @@
+/*
+ * createFocusTrap — minimal Tab-cycling focus trap for modal frames.
+ *
+ * On install: remembers the currently focused element, moves focus to the
+ * first focusable descendant of `container`, and intercepts Tab/Shift+Tab
+ * to cycle within the container.
+ *
+ * On teardown (the returned disposer): removes the listener and restores
+ * focus to the previously active element if it's still connected to the DOM.
+ *
+ * Phase 5 scope is deliberately narrow: no aria-hidden on siblings, no
+ * Inert attribute management, no MutationObserver for dynamic content.
+ * Those refinements arrive when accessibility work lands post-prototype.
+ */
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',');
+export function createFocusTrap(container) {
+    const previouslyFocused = document.activeElement;
+    function getFocusables() {
+        return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR));
+    }
+    function onKeydown(e) {
+        if (e.key !== 'Tab')
+            return;
+        const focusables = getFocusables();
+        if (focusables.length === 0) {
+            // Nothing to focus — swallow Tab so it can't escape the modal.
+            e.preventDefault();
+            return;
+        }
+        const first = focusables[0];
+        const last = focusables[focusables.length - 1];
+        const active = document.activeElement;
+        if (e.shiftKey && (active === first || !container.contains(active))) {
+            e.preventDefault();
+            last.focus();
+        }
+        else if (!e.shiftKey && (active === last || !container.contains(active))) {
+            e.preventDefault();
+            first.focus();
+        }
+    }
+    container.addEventListener('keydown', onKeydown);
+    // Defer initial focus to the next microtask so the container contents
+    // (which may still be rendering if createFocusTrap was called mid-mount)
+    // have a chance to appear in the DOM.
+    queueMicrotask(() => {
+        var _a;
+        const focusables = getFocusables();
+        ((_a = focusables[0]) !== null && _a !== void 0 ? _a : container).focus();
+    });
+    return () => {
+        container.removeEventListener('keydown', onKeydown);
+        if (previouslyFocused && document.contains(previouslyFocused)) {
+            previouslyFocused.focus();
+        }
+    };
+}