sh3-core 0.13.2 → 0.13.4

package/dist/app-appearance/appearanceShard.svelte.js

@@ -0,0 +1,61 @@
+/*
+ * `__app-appearance__` shard — owns the user-zone for per-app overrides
+ * and registers the `app.customize` element-scope action. The state
+ * itself lives in appearanceState.svelte.ts (so unit tests don't have
+ * to boot a real ShardContext). This file binds the zone on activate
+ * and unbinds on deactivate, and contributes the action.
+ */
+import { VERSION } from '../version';
+import { listRegisteredApps } from '../api';
+import { getSelection } from '../actions/selection.svelte';
+import { modalManager } from '../overlays/modal';
+import AppAppearanceModal from './AppAppearanceModal.svelte';
+import { __bindZone, __unbindZone, } from './appearanceState.svelte';
+function readSelection() {
+    const sel = getSelection();
+    if (!sel || sel.type !== 'app')
+        return null;
+    return sel.ref;
+}
+function runCustomize(_ctx) {
+    var _a;
+    const ref = readSelection();
+    if (!ref)
+        return;
+    const m = listRegisteredApps().find((x) => x.id === ref.appId);
+    const props = {
+        appId: ref.appId,
+        appLabel: (_a = m === null || m === void 0 ? void 0 : m.label) !== null && _a !== void 0 ? _a : ref.appId,
+    };
+    modalManager.open(AppAppearanceModal, props);
+}
+export const appearanceShard = {
+    manifest: {
+        id: '__app-appearance__',
+        label: 'App Appearance',
+        version: VERSION,
+        views: [],
+    },
+    activate(ctx) {
+        const zone = ctx.state({
+            user: { overrides: {} },
+        });
+        __bindZone(zone);
+        const customize = {
+            id: 'app.customize',
+            label: 'Customize…',
+            scope: { element: 'app' },
+            contextItem: true,
+            group: 'appearance',
+            run: runCustomize,
+        };
+        ctx.actions.register(customize);
+    },
+    autostart() {
+        // Self-start so the `app.customize` action is registered before the
+        // user right-clicks a home card. No imperative work required.
+    },
+    deactivate() {
+        __unbindZone();
+    },
+};

package/dist/app-appearance/appearanceState.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { StateZones } from '../state/zones.svelte';
+import type { AppAppearance } from './types';
+export interface AppearanceZoneSchema {
+    user: {
+        overrides: Record<string, AppAppearance>;
+    };
+}
+/** Bind the shard's zone to this module. Called by the shard's activate. */
+export declare function __bindZone(s: StateZones<AppearanceZoneSchema>): void;
+/** Unbind the zone (deactivate). */
+export declare function __unbindZone(): void;
+export declare function getAppearance(appId: string): AppAppearance | undefined;
+export declare function setAppearance(appId: string, value: AppAppearance | undefined): void;
+/** Test-only: replace the bound zone with a memory shim. */
+export declare function __resetForTests(): void;

package/dist/app-appearance/appearanceState.svelte.js

@@ -0,0 +1,59 @@
+/*
+ * Per-user-per-browser visual overrides for apps. The store + helpers
+ * live separately from the shard so the state can be unit-tested without
+ * booting the shard system, and so the AppAppearanceModal can import
+ * get/set without creating an import cycle through the shard's modal
+ * import.
+ *
+ * EXPLICITLY TEMPORARY. A future ADR is expected to add icon/color
+ * fields to the app manifest itself.
+ */
+let zoneState = null;
+/** Bind the shard's zone to this module. Called by the shard's activate. */
+export function __bindZone(s) {
+    zoneState = s;
+}
+/** Unbind the zone (deactivate). */
+export function __unbindZone() {
+    zoneState = null;
+}
+function isEmpty(v) {
+    return v.icon === undefined && v.color === undefined && v.label === undefined;
+}
+export function getAppearance(appId) {
+    const map = zoneState === null || zoneState === void 0 ? void 0 : zoneState.user.overrides;
+    if (!map)
+        return undefined;
+    const v = map[appId];
+    if (!v)
+        return undefined;
+    if (isEmpty(v))
+        return undefined;
+    return v;
+}
+export function setAppearance(appId, value) {
+    if (!zoneState)
+        return;
+    const map = zoneState.user.overrides;
+    const next = Object.assign({}, map);
+    if (value === undefined || isEmpty(value)) {
+        delete next[appId];
+    }
+    else {
+        next[appId] = value;
+    }
+    zoneState.user.overrides = next;
+}
+/** Test-only: replace the bound zone with a memory shim. */
+export function __resetForTests() {
+    zoneState = {
+        ephemeral: {},
+        session: {},
+        workspace: {},
+        user: { overrides: {} },
+    };
+}
+// Initialise the memory shim at module load so tests can call set/get
+// without first invoking activate. Production replaces this via
+// __bindZone() inside appearanceShard.activate().
+__resetForTests();

package/dist/app-appearance/appearanceState.test.d.ts

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

package/dist/app-appearance/appearanceState.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { setAppearance, getAppearance, __resetForTests } from './appearanceState.svelte';
+describe('appearanceShard get/set', () => {
+    beforeEach(() => __resetForTests());
+    it('returns undefined for an unset app', () => {
+        expect(getAppearance('foo')).toBeUndefined();
+    });
+    it('round-trips an icon override', () => {
+        setAppearance('foo', { icon: 'house' });
+        expect(getAppearance('foo')).toEqual({ icon: 'house' });
+    });
+    it('round-trips a color override', () => {
+        setAppearance('foo', { color: '#ff0000' });
+        expect(getAppearance('foo')).toEqual({ color: '#ff0000' });
+    });
+    it('round-trips a label override', () => {
+        setAppearance('foo', { label: 'My Label' });
+        expect(getAppearance('foo')).toEqual({ label: 'My Label' });
+    });
+    it('clears the entry when all fields are undefined', () => {
+        setAppearance('foo', { icon: 'house', color: '#ff0000', label: 'X' });
+        setAppearance('foo', { icon: undefined, color: undefined, label: undefined });
+        expect(getAppearance('foo')).toBeUndefined();
+    });
+    it('clears the entry when given undefined directly', () => {
+        setAppearance('foo', { icon: 'house' });
+        setAppearance('foo', undefined);
+        expect(getAppearance('foo')).toBeUndefined();
+    });
+});

package/dist/app-appearance/index.d.ts

@@ -0,0 +1,3 @@
+export { appearanceShard } from './appearanceShard.svelte';
+export { getAppearance, setAppearance } from './appearanceState.svelte';
+export type { AppAppearance } from './types';

package/dist/app-appearance/index.js

@@ -0,0 +1,2 @@
+export { appearanceShard } from './appearanceShard.svelte';
+export { getAppearance, setAppearance } from './appearanceState.svelte';

package/dist/app-appearance/types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Per-app per-user-per-browser visual override. Stored in the user zone
+ * of the __app-appearance__ shard. Every field is optional — an empty
+ * AppAppearance object is treated as "no override" and removed from the
+ * map by setAppearance().
+ */
+export interface AppAppearance {
+    icon?: string;
+    color?: string;
+    label?: string;
+}

package/dist/app-appearance/types.js

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

package/dist/apps/types.d.ts

@@ -74,6 +74,13 @@ export interface AppManifest {
      * When absent, the canonical fallback is used. See MenuContainer.
      */
     menus?: MenuContainer[];
+    /**
+     * Optional default home-card icon — a lucide icon id from the bundled
+     * sprite (see `src/assets/icons.svg`). User-set per-browser overrides
+     * (via the home-card Customize action) take precedence; if neither is
+     * set the framework falls back to `box`.
+     */
+    icon?: string;
 }
 /**
  * Context object passed to `App.activate`. Provides app-scoped state zones

package/dist/assets/iconIds.generated.d.ts

@@ -0,0 +1,2 @@
+export declare const ICON_IDS: readonly ["activity", "align-horizontal-justify-center", "align-horizontal-justify-end", "align-horizontal-justify-start", "app-window", "archive", "archive-restore", "axis-3d", "box", "brick-wall", "bug", "building-2", "cable", "calendar", "camera", "check", "chevron-down", "chevron-right", "circle-check", "circle-dot", "circle-minus", "circle-x", "clipboard", "clipboard-paste", "clock", "compass", "component", "copy", "cpu", "crop", "crosshair", "crown", "dollar-sign", "download", "droplet", "eraser", "euro", "external-link", "eye", "eye-off", "file", "file-archive", "file-diff", "file-plus", "file-text", "flame", "flip-horizontal-2", "flip-vertical-2", "folder", "folder-open", "folder-plus", "folder-tree", "gallery-vertical-end", "gamepad-2", "gauge", "gem", "git-branch", "git-commit-horizontal", "git-merge", "globe", "grid-2x2", "grid-3x3", "group", "hard-drive", "heart", "history", "house", "image", "info", "joystick", "key", "layers", "layout-dashboard", "layout-grid", "layout-list", "layout-panel-left", "layout-panel-top", "layout-template", "lightbulb", "link", "list-ordered", "list-tree", "lock", "log-out", "magnet", "mail", "map", "maximize", "minimize", "moon", "mouse-pointer", "move", "move-3d", "music", "navigation", "network", "notebook-pen", "palette", "pause", "pencil", "pipette", "play", "plus", "pointer", "pound-sterling", "receipt", "redo-2", "refresh-cw", "rocket", "rotate-3d", "rotate-ccw", "rotate-cw", "ruler", "save", "scissors", "scroll-text", "search", "send", "server", "settings", "shield", "skull", "sliders-horizontal", "snowflake", "sparkles", "square", "square-terminal", "star", "sun", "sword", "table-properties", "target", "texture", "timer", "trash-2", "triangle-alert", "type", "undo-2", "ungroup", "unity", "upload", "user", "users", "video", "volume-2", "wand-sparkles", "wind", "x", "zap", "zoom-in", "zoom-out"];
+export type IconId = (typeof ICON_IDS)[number];

package/dist/assets/iconIds.generated.js

@@ -0,0 +1,154 @@
+// GENERATED — do not edit. See scripts/sync-icon-ids.ts
+export const ICON_IDS = [
+    'activity',
+    'align-horizontal-justify-center',
+    'align-horizontal-justify-end',
+    'align-horizontal-justify-start',
+    'app-window',
+    'archive',
+    'archive-restore',
+    'axis-3d',
+    'box',
+    'brick-wall',
+    'bug',
+    'building-2',
+    'cable',
+    'calendar',
+    'camera',
+    'check',
+    'chevron-down',
+    'chevron-right',
+    'circle-check',
+    'circle-dot',
+    'circle-minus',
+    'circle-x',
+    'clipboard',
+    'clipboard-paste',
+    'clock',
+    'compass',
+    'component',
+    'copy',
+    'cpu',
+    'crop',
+    'crosshair',
+    'crown',
+    'dollar-sign',
+    'download',
+    'droplet',
+    'eraser',
+    'euro',
+    'external-link',
+    'eye',
+    'eye-off',
+    'file',
+    'file-archive',
+    'file-diff',
+    'file-plus',
+    'file-text',
+    'flame',
+    'flip-horizontal-2',
+    'flip-vertical-2',
+    'folder',
+    'folder-open',
+    'folder-plus',
+    'folder-tree',
+    'gallery-vertical-end',
+    'gamepad-2',
+    'gauge',
+    'gem',
+    'git-branch',
+    'git-commit-horizontal',
+    'git-merge',
+    'globe',
+    'grid-2x2',
+    'grid-3x3',
+    'group',
+    'hard-drive',
+    'heart',
+    'history',
+    'house',
+    'image',
+    'info',
+    'joystick',
+    'key',
+    'layers',
+    'layout-dashboard',
+    'layout-grid',
+    'layout-list',
+    'layout-panel-left',
+    'layout-panel-top',
+    'layout-template',
+    'lightbulb',
+    'link',
+    'list-ordered',
+    'list-tree',
+    'lock',
+    'log-out',
+    'magnet',
+    'mail',
+    'map',
+    'maximize',
+    'minimize',
+    'moon',
+    'mouse-pointer',
+    'move',
+    'move-3d',
+    'music',
+    'navigation',
+    'network',
+    'notebook-pen',
+    'palette',
+    'pause',
+    'pencil',
+    'pipette',
+    'play',
+    'plus',
+    'pointer',
+    'pound-sterling',
+    'receipt',
+    'redo-2',
+    'refresh-cw',
+    'rocket',
+    'rotate-3d',
+    'rotate-ccw',
+    'rotate-cw',
+    'ruler',
+    'save',
+    'scissors',
+    'scroll-text',
+    'search',
+    'send',
+    'server',
+    'settings',
+    'shield',
+    'skull',
+    'sliders-horizontal',
+    'snowflake',
+    'sparkles',
+    'square',
+    'square-terminal',
+    'star',
+    'sun',
+    'sword',
+    'table-properties',
+    'target',
+    'texture',
+    'timer',
+    'trash-2',
+    'triangle-alert',
+    'type',
+    'undo-2',
+    'ungroup',
+    'unity',
+    'upload',
+    'user',
+    'users',
+    'video',
+    'volume-2',
+    'wand-sparkles',
+    'wind',
+    'x',
+    'zap',
+    'zoom-in',
+    'zoom-out',
+];

package/dist/host.js

@@ -23,6 +23,7 @@ import { sh3coreShard } from './sh3core-shard/sh3coreShard.svelte';
 import { shellShard } from './shell-shard/shellShard.svelte';
 import { storeShard } from './app/store/storeShard.svelte';
 import { projectsShard } from './projects-shard/projectsShard.svelte';
+import { appearanceShard } from './app-appearance';
 import { __setBackend, backends } from './state/zones.svelte';
 import { loadInstalledPackages } from './registry/installer';
 import { setLocalOwner } from './auth/index';
@@ -67,7 +68,7 @@ export async function bootstrap(config) {
     }
     const exShards = new Set(config === null || config === void 0 ? void 0 : config.excludeShards);
     // 1. Framework-owned shards
-    const frameworkShards = [sh3coreShard, shellShard, storeShard, adminShard, projectsShard];
+    const frameworkShards = [sh3coreShard, shellShard, storeShard, adminShard, projectsShard, appearanceShard];
     for (const shard of frameworkShards) {
         if (!exShards.has(shard.manifest.id)) {
             registerShardInternal(shard);

package/dist/overlays/FloatFrame.svelte

@@ -17,7 +17,7 @@
 -->
 <script lang="ts">
   import LayoutRenderer from '../layout/LayoutRenderer.svelte';
-  import { floatManager } from './float';
+  import { floatManager, getFloatParentHost } from './float';
   import { registerDismissableFrame, unregisterDismissableFrame } from './floatDismiss';
   import type { FloatEntry } from '../layout/types';
 
@@ -37,6 +37,22 @@
     return () => unregisterDismissableFrame(entry.id);
   });
 
+  // Portal the frame into the anchor's enclosing overlay host when one was
+  // resolved at open() time. This puts the frame inside the opener's
+  // stacking context — so a picker opened from inside a modal stacks above
+  // that modal without writing any z-index. The Svelte component lifecycle
+  // is unaffected; we're only relocating the rendered DOM node.
+  $effect(() => {
+    if (!frameEl) return;
+    const host = getFloatParentHost(entry.id);
+    if (!host) return;
+    const original = frameEl.parentNode;
+    host.appendChild(frameEl);
+    return () => {
+      if (frameEl?.parentNode === host && original) original.appendChild(frameEl);
+    };
+  });
+
   function onHeaderPointerDown(e: PointerEvent): void {
     if (e.button !== 0) return;
     if ((e.target as HTMLElement).closest('.sh3-float-close')) return;
@@ -76,6 +92,7 @@
 <!-- svelte-ignore a11y_click_events_have_key_events -->
 <div
   class="sh3-float-frame"
+  data-shell-overlay-host="float"
   bind:this={frameEl}
   style:left="{entry.position.x}px"
   style:top="{entry.position.y}px"

package/dist/overlays/float.d.ts

@@ -15,6 +15,17 @@ export interface FloatOptions {
      * See docs/superpowers/specs/2026-04-21-dismissable-float-design.md.
      */
     dismissable?: boolean;
+    /**
+     * For `dismissable` floats only: anchor element used to determine the
+     * mount host. When the anchor is inside another overlay (modal, popup,
+     * float frame), the float frame is portaled into that host so it stacks
+     * above its opener instead of sitting at layer 1. Without an anchor —
+     * or for non-dismissable floats — the frame renders at the FloatLayer
+     * root as usual. The anchor isn't stored on FloatEntry (HTMLElement
+     * isn't serializable through the workspace-zone proxy); only the
+     * resolved parent host is, in a sidecar map keyed by float id.
+     */
+    anchor?: HTMLElement;
 }
 export interface FloatManager {
     open(viewId: string, options?: FloatOptions): string;
@@ -34,4 +45,5 @@ export declare function bindFloatStore(floats: FloatEntry[], getBounds: () => {
 export declare function unbindFloatStore(): void;
 /** Test-only reset. Clears in-memory fallback and unbinds any store. */
 export declare function __resetFloatManagerForTest(): void;
+export declare function getFloatParentHost(id: string): HTMLElement | undefined;
 export declare const floatManager: FloatManager;

package/dist/overlays/float.js

@@ -27,6 +27,7 @@
  *   and the pre-boot state.
  */
 import { computeMinSize, cascadePosition, generateFloatId } from '../layout/floats';
+import { findEnclosingOverlayHost } from './parentHost';
 // ----- storage binding ---------------------------------------------------
 let fallbackFloats = [];
 let boundFloats = null;
@@ -49,10 +50,19 @@ export function __resetFloatManagerForTest() {
     fallbackFloats = [];
     boundFloats = null;
     getTreeBounds = () => ({ w: 1600, h: 900 });
+    parentHosts.clear();
 }
 function activeStore() {
     return boundFloats !== null && boundFloats !== void 0 ? boundFloats : fallbackFloats;
 }
+// ----- parent host sidecar ------------------------------------------------
+// HTMLElement can't live on FloatEntry (workspace-zone proxy state), so the
+// resolved parent host is stored here keyed by float id and consumed by
+// FloatFrame to portal the rendered DOM into the opener's stacking context.
+const parentHosts = new Map();
+export function getFloatParentHost(id) {
+    return parentHosts.get(id);
+}
 // ----- slot id minting ---------------------------------------------------
 let floatSlotCounter = 0;
 function mintFloatSlotId(viewId) {
@@ -107,6 +117,11 @@ function openFloat(viewId, options = {}) {
     };
     if (options.dismissable)
         entry.dismissable = true;
+    if (options.dismissable && options.anchor) {
+        const host = findEnclosingOverlayHost(options.anchor);
+        if (host)
+            parentHosts.set(id, host);
+    }
     store.push(entry);
     return id;
 }
@@ -116,6 +131,7 @@ function closeFloat(floatId) {
     if (idx < 0)
         return;
     store.splice(idx, 1);
+    parentHosts.delete(floatId);
 }
 function listFloats() {
     // Return a snapshot so callers can iterate without racing mutations.

package/dist/overlays/float.test.js

@@ -1,5 +1,5 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { floatManager, __resetFloatManagerForTest, bindFloatStore } from './float';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { floatManager, __resetFloatManagerForTest, bindFloatStore, getFloatParentHost, } from './float';
 import { layoutStore } from '../layout/store.svelte';
 describe('floatManager', () => {
     beforeEach(() => {
@@ -80,6 +80,49 @@ describe('floatManager', () => {
         expect(f.content.type).toBe('tabs');
     });
 });
+describe('floatManager — anchor-aware parent host', () => {
+    beforeEach(() => {
+        __resetFloatManagerForTest();
+    });
+    afterEach(() => {
+        document.body.innerHTML = '';
+    });
+    function makeOverlayHost(kind) {
+        const host = document.createElement('div');
+        host.dataset.shellOverlayHost = kind;
+        const anchor = document.createElement('button');
+        host.appendChild(anchor);
+        document.body.appendChild(host);
+        return { host, anchor };
+    }
+    it('getFloatParentHost is undefined when no anchor was passed', () => {
+        const id = floatManager.open('test:view', { dismissable: true });
+        expect(getFloatParentHost(id)).toBeUndefined();
+    });
+    it('getFloatParentHost is undefined when the anchor lives outside any overlay host', () => {
+        const anchor = document.createElement('button');
+        document.body.appendChild(anchor);
+        const id = floatManager.open('test:view', { dismissable: true, anchor });
+        expect(getFloatParentHost(id)).toBeUndefined();
+    });
+    it('getFloatParentHost returns the enclosing host for a dismissable+anchored float', () => {
+        const { host, anchor } = makeOverlayHost('modal');
+        const id = floatManager.open('test:view', { dismissable: true, anchor });
+        expect(getFloatParentHost(id)).toBe(host);
+    });
+    it('getFloatParentHost is undefined for non-dismissable floats even with an anchor', () => {
+        const { anchor } = makeOverlayHost('modal');
+        const id = floatManager.open('test:view', { anchor });
+        expect(getFloatParentHost(id)).toBeUndefined();
+    });
+    it('getFloatParentHost is cleared when the float is closed', () => {
+        const { anchor } = makeOverlayHost('modal');
+        const id = floatManager.open('test:view', { dismissable: true, anchor });
+        expect(getFloatParentHost(id)).toBeDefined();
+        floatManager.close(id);
+        expect(getFloatParentHost(id)).toBeUndefined();
+    });
+});
 // ---------------------------------------------------------------------------
 // DOM tests — floatManager + FloatLayer.svelte in happy-dom
 // ---------------------------------------------------------------------------
@@ -311,3 +354,55 @@ describe('floats — F.6 multi-picker interaction', () => {
         expect(floatManager.list().some((f) => f.id === id)).toBe(false);
     });
 });
+// ---------------------------------------------------------------------------
+// F.7 — anchor portals dismissable float into the enclosing overlay host
+// ---------------------------------------------------------------------------
+describe('floats — F.7 anchor portals to enclosing overlay host', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('reparents the FloatFrame into the anchor’s enclosing overlay host', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const fakeModalHost = document.createElement('div');
+        fakeModalHost.className = 'fake-modal-host';
+        fakeModalHost.dataset.shellOverlayHost = 'modal';
+        const anchor = document.createElement('button');
+        fakeModalHost.appendChild(anchor);
+        document.body.appendChild(fakeModalHost);
+        floatManager.open('test:view', {
+            dismissable: true,
+            anchor,
+            title: 'Picker',
+        });
+        await tick();
+        const frame = document.querySelector('[role="dialog"][aria-label="Picker"]');
+        expect(frame).toBeTruthy();
+        expect(fakeModalHost.contains(frame)).toBe(true);
+        expect(container.contains(frame)).toBe(false);
+    });
+    it('renders inside FloatLayer when no anchor is provided', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        floatManager.open('test:view', { dismissable: true, title: 'NoAnchor' });
+        await tick();
+        const frame = container.querySelector('[role="dialog"][aria-label="NoAnchor"]');
+        expect(frame).toBeTruthy();
+    });
+});
+// ---------------------------------------------------------------------------
+// F.8 — overlay host marker on FloatFrame
+// ---------------------------------------------------------------------------
+describe('floats — F.8 overlay host marker', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('marks each FloatFrame with data-shell-overlay-host="float"', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        floatManager.open('test:view', { title: 'Marked' });
+        await tick();
+        const frame = container.querySelector('[role="dialog"][aria-label="Marked"]');
+        expect(frame).toBeTruthy();
+        expect(frame.dataset.shellOverlayHost).toBe('float');
+    });
+});

package/dist/overlays/modal.js

@@ -109,6 +109,7 @@ function openModal(Content, props, options) {
     const root = getLayerRoot('modal');
     const host = document.createElement('div');
     host.className = 'sh3-modal-host';
+    host.dataset.shellOverlayHost = 'modal';
     host.style.position = 'absolute';
     host.style.inset = '0';
     host.style.pointerEvents = 'auto';

package/dist/overlays/modal.test.js

@@ -88,3 +88,20 @@ describe('modal — back-cascade integration', () => {
         expect(layerRoot.querySelectorAll('.sh3-modal-host').length).toBe(0);
     });
 });
+describe('modal — overlay host marker', () => {
+    let layerRoot;
+    beforeEach(() => {
+        layerRoot = makeLayerRoot();
+    });
+    afterEach(() => {
+        modalManager.closeAll();
+        teardownLayerRoot(layerRoot);
+    });
+    it('marks the modal host with data-shell-overlay-host="modal"', async () => {
+        modalManager.open(DummyFrame, {});
+        await tick();
+        const host = layerRoot.querySelector('.sh3-modal-host');
+        expect(host).not.toBeNull();
+        expect(host.dataset.shellOverlayHost).toBe('modal');
+    });
+});

package/dist/overlays/parentHost.d.ts

@@ -0,0 +1 @@
+export declare function findEnclosingOverlayHost(anchor: HTMLElement): HTMLElement | null;

package/dist/overlays/parentHost.js

@@ -0,0 +1,15 @@
+/*
+ * Walks up from `anchor` looking for an element marked as an overlay host
+ * via `data-shell-overlay-host`. Modal hosts, popup hosts, and float frames
+ * tag themselves so anchored overlays (popups, dismissable picker floats)
+ * can mount inside their opener's stacking context instead of at a global
+ * layer root — which is what the layer-z-index invariant gives us when a
+ * popover is logically "inside" a modal.
+ *
+ * Returns null when the anchor lives in the docked tree; callers fall back
+ * to their configured layer root in that case. The marker is read via
+ * `Element.closest`, so a marker on the anchor itself counts.
+ */
+export function findEnclosingOverlayHost(anchor) {
+    return anchor.closest('[data-shell-overlay-host]');
+}

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

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