sh3-core 0.10.4 → 0.11.2

package/dist/actions/state.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { setActiveApp, setFocusedViewId, setMountedViewIds, setUserBindings, getLiveDispatcherState, __resetDispatcherStateForTest, } from './state.svelte';
+import { __resetSelectionForTest, makeSelectionApi } from './selection.svelte';
+describe('live dispatcher state', () => {
+    beforeEach(() => {
+        __resetDispatcherStateForTest();
+        __resetSelectionForTest();
+    });
+    it('starts in home state with empty sets', () => {
+        const s = getLiveDispatcherState();
+        expect(s.activeAppId).toBeNull();
+        expect(s.mountedViewIds.size).toBe(0);
+        expect(s.focusedViewId).toBeNull();
+        expect(s.selection).toBeNull();
+    });
+    it('setActiveApp updates activeAppId and requiredShards', () => {
+        setActiveApp('app.a', new Set(['shard.x']));
+        const s = getLiveDispatcherState();
+        expect(s.activeAppId).toBe('app.a');
+        expect(s.activeAppRequiredShards.has('shard.x')).toBe(true);
+    });
+    it('setFocusedViewId updates focus', () => {
+        setFocusedViewId('editor');
+        expect(getLiveDispatcherState().focusedViewId).toBe('editor');
+    });
+    it('setMountedViewIds updates mounted', () => {
+        setMountedViewIds(new Set(['a', 'b']));
+        expect(getLiveDispatcherState().mountedViewIds.has('a')).toBe(true);
+    });
+    it('setUserBindings updates bindings', () => {
+        setUserBindings({ 'shard.x.save': 'Ctrl+Alt+S' });
+        expect(getLiveDispatcherState().bindings['shard.x.save']).toBe('Ctrl+Alt+S');
+    });
+    it('reads selection reactively', () => {
+        var _a;
+        const api = makeSelectionApi('shard.a');
+        api.set({ type: 'orb', ref: 42 });
+        expect((_a = getLiveDispatcherState().selection) === null || _a === void 0 ? void 0 : _a.type).toBe('orb');
+    });
+});

package/dist/actions/syncMountedViewIds.test.d.ts

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

package/dist/actions/syncMountedViewIds.test.js

@@ -0,0 +1,97 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { resetFramework } from '../__test__/reset';
+import { makeApp, makeAppManifest, makeTabEntry, makeTabsNode, makeTree, makeSlotNode, makeSplitNode } from '../__test__/fixtures';
+import { registerApp } from '../apps/registry.svelte';
+import { launchApp } from '../apps/lifecycle';
+import { syncMountedViewIdsFromLayout, getLiveDispatcherState } from './state.svelte';
+import { bindFloatStore } from '../overlays/float';
+import { layoutStore } from '../layout/store.svelte';
+import { popoutView } from '../layout/inspection';
+describe('syncMountedViewIdsFromLayout', () => {
+    beforeEach(resetFramework);
+    it('collects viewIds from the docked tree after an app launches', async () => {
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'sync-app-docked' }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree(makeTabsNode([
+                        makeTabEntry({ slotId: 's1', viewId: 'view:a' }),
+                        makeTabEntry({ slotId: 's2', viewId: 'view:b' }),
+                    ])),
+                },
+            ],
+        }));
+        await launchApp('sync-app-docked');
+        syncMountedViewIdsFromLayout();
+        const mounted = getLiveDispatcherState().mountedViewIds;
+        expect(mounted.has('view:a')).toBe(true);
+        expect(mounted.has('view:b')).toBe(true);
+        expect(mounted.size).toBe(2);
+    });
+    it('collects viewIds from splits and bare slot leaves', async () => {
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'sync-app-split' }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree(makeSplitNode([
+                        makeSlotNode('leaf-s', 'view:leaf'),
+                        makeTabsNode([makeTabEntry({ slotId: 'tab-s', viewId: 'view:tabbed' })]),
+                    ])),
+                },
+            ],
+        }));
+        await launchApp('sync-app-split');
+        syncMountedViewIdsFromLayout();
+        const mounted = getLiveDispatcherState().mountedViewIds;
+        expect(mounted.has('view:leaf')).toBe(true);
+        expect(mounted.has('view:tabbed')).toBe(true);
+    });
+    it('includes viewIds inside floats', async () => {
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'sync-app-float' }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree(makeTabsNode([makeTabEntry({ slotId: 'anchor', viewId: 'view:anchor' })])),
+                },
+            ],
+        }));
+        await launchApp('sync-app-float');
+        // Bind the float manager to the live tree (Shell.svelte does this at boot).
+        bindFloatStore(layoutStore.floats, () => ({ w: 1024, h: 768 }));
+        // Popout the anchor → creates a float with view:anchor inside.
+        popoutView('anchor');
+        syncMountedViewIdsFromLayout();
+        const mounted = getLiveDispatcherState().mountedViewIds;
+        // Anchor was removed from docked and re-added inside a float.
+        expect(mounted.has('view:anchor')).toBe(true);
+    });
+    it('drops viewIds that leave the tree', async () => {
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'sync-app-remove' }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree(makeTabsNode([
+                        makeTabEntry({ slotId: 'keep', viewId: 'view:keep' }),
+                        makeTabEntry({ slotId: 'drop', viewId: 'view:drop' }),
+                    ])),
+                },
+            ],
+        }));
+        await launchApp('sync-app-remove');
+        syncMountedViewIdsFromLayout();
+        expect(getLiveDispatcherState().mountedViewIds.has('view:drop')).toBe(true);
+        // Mutate the tree directly — remove the 'drop' tab.
+        const tabs = layoutStore.tree.docked.type === 'tabs' ? layoutStore.tree.docked : null;
+        if (tabs) {
+            tabs.tabs = tabs.tabs.filter((t) => t.slotId !== 'drop');
+        }
+        syncMountedViewIdsFromLayout();
+        const mounted = getLiveDispatcherState().mountedViewIds;
+        expect(mounted.has('view:keep')).toBe(true);
+        expect(mounted.has('view:drop')).toBe(false);
+    });
+});

package/dist/actions/types.d.ts

@@ -0,0 +1,56 @@
+export type AtomicScope = 'home' | 'app' | `view:${string}` | `focus:${string}` | {
+    element: string;
+};
+export type ActionScope = AtomicScope | AtomicScope[];
+export interface Action {
+    id: string;
+    label: string;
+    scope: ActionScope;
+    contextItem?: boolean;
+    paletteItem?: boolean;
+    defaultShortcut?: string;
+    icon?: string;
+    group?: string;
+    allowInInputs?: boolean;
+    run(ctx: ActionDispatchContext): void | Promise<void>;
+}
+export interface Selection {
+    type: string;
+    ref: unknown;
+    ownerShardId: string;
+}
+export interface ActionDispatchContext {
+    action: {
+        id: string;
+        label: string;
+    };
+    appId: string | null;
+    viewId?: string;
+    selection?: Selection;
+    invokedVia: 'keyboard' | 'context-menu' | 'palette' | 'programmatic';
+    dispatch(actionId: string): void;
+}
+export interface SelectionApi {
+    get(): Selection | null;
+    set(sel: {
+        type: string;
+        ref: unknown;
+    }): void;
+    clear(): void;
+}
+export interface ActionsApi {
+    register(action: Action): () => void;
+    selection: SelectionApi;
+    openContextMenu(opts: {
+        x: number;
+        y: number;
+    }): void;
+    openPalette(opts?: {
+        prefill?: string;
+    }): void;
+}
+export interface ResolvedAction {
+    action: Action;
+    ownerShardId: string;
+    effectiveShortcut: string | null;
+}

package/dist/actions/types.js

@@ -0,0 +1,7 @@
+// packages/sh3-core/src/actions/types.ts
+/*
+ * Action primitive — scoped UI operations dispatched by keyboard,
+ * context menu, or command palette. See the spec at
+ * docs/superpowers/specs/2026-04-22-actions-contexts-design.md.
+ */
+export {};

package/dist/api.d.ts

@@ -1,7 +1,7 @@
 export { shell } from './shellRuntime.svelte';
 export type { Shell } from './shellRuntime.svelte';
 export type { Shard, ShardManifest, SourceShard, SourceShardManifest, ShardContext, ViewDeclaration, ViewFactory, ViewHandle, MountContext, } from './shards/types';
-export type { LayoutNode, SplitNode, TabsNode, SlotNode, TabEntry, SplitDirection, SizeMode, LayoutTree, FloatEntry, LayoutPreset, CanonicalPreset, } from './layout/types';
+export type { LayoutNode, SplitNode, TabsNode, SlotNode, TabEntry, SplitDirection, SizeMode, LayoutTree, FloatEntry, LayoutPreset, CanonicalPreset, TreeRootRef as SlotLocation, } from './layout/types';
 export type { FloatManager, FloatOptions } from './overlays/float';
 export type { ModalManager } from './overlays/modal';
 export type { PopupManager } from './overlays/popup';
@@ -15,7 +15,7 @@ export type { EnvState } from './env/types';
 export type { App, AppManifest, SourceApp, SourceAppManifest, AppContext, } from './apps/types';
 export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
 export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
-export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, } from './layout/inspection';
+export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, popoutView, dockFloat, locateSlot, } from './layout/inspection';
 export type { DocumentHandle, DocumentHandleOptions, DocumentFormat, DocumentMeta, DocumentChange, AutosaveController, } from './documents/types';
 export { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from './documents/types';
 export type { BrowseCapability } from './documents/browse';

package/dist/api.js

@@ -28,7 +28,7 @@ export { PERMISSION_STATE_MANAGE } from './state/types';
 export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
 export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
 // Layout inspection / mutation for advanced shards (diagnostic, etc.).
-export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, } from './layout/inspection';
+export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, popoutView, dockFloat, locateSlot, } from './layout/inspection';
 export { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from './documents/types';
 export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY } from './documents/sync-types';
 export { CONFLICT_RENDERER_POINT, ConflictPermissionError, ConflictSessionOrphanedError, } from './conflicts/api';

package/dist/apps/lifecycle.js

@@ -17,6 +17,9 @@ import { attachApp, acquireAppSlotHolds, detachApp, switchToApp, switchToHome, }
 import { activeApp, getRegisteredApp, registeredApps } from './registry.svelte';
 import { createZoneManager } from '../state/manage';
 import { PERMISSION_STATE_MANAGE } from '../state/types';
+import { setActiveApp, setUserBindings } from '../actions/state.svelte';
+import { clearSelectionUnconditional } from '../actions/selection.svelte';
+import { loadUserBindings } from '../actions/bindings-store';
 // ---------- last-active-app user zone ------------------------------------
 /**
  * Framework-reserved user-zone slot storing which app to boot into on
@@ -69,7 +72,7 @@ function getOrCreateAppContext(appId) {
  * @throws If the app is not registered or a required shard is not registered.
  */
 export async function launchApp(id) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f, _g;
     const app = getRegisteredApp(id);
     if (!app) {
         throw new Error(`Cannot launch app "${id}": not registered`);
@@ -93,6 +96,8 @@ export async function launchApp(id) {
         switchToApp();
         void ((_c = app.onAppReady) === null || _c === void 0 ? void 0 : _c.call(app, getOrCreateAppContext(id)));
         writeLastApp(id);
+        setActiveApp(id, new Set((_d = app.manifest.requiredShards) !== null && _d !== void 0 ? _d : []));
+        void loadUserBindings(id).then(setUserBindings);
         return;
     }
     // Validate required shards are registered before attaching anything,
@@ -123,10 +128,12 @@ export async function launchApp(id) {
     // refcount holds on the app's slots now (pool's factory lookup
     // happens in a microtask from this call).
     acquireAppSlotHolds();
-    void ((_d = app.activate) === null || _d === void 0 ? void 0 : _d.call(app, getOrCreateAppContext(id)));
+    void ((_e = app.activate) === null || _e === void 0 ? void 0 : _e.call(app, getOrCreateAppContext(id)));
     activeApp.id = id;
+    setActiveApp(id, new Set((_f = app.manifest.requiredShards) !== null && _f !== void 0 ? _f : []));
+    void loadUserBindings(id).then(setUserBindings);
     switchToApp();
-    void ((_e = app.onAppReady) === null || _e === void 0 ? void 0 : _e.call(app, getOrCreateAppContext(id)));
+    void ((_g = app.onAppReady) === null || _g === void 0 ? void 0 : _g.call(app, getOrCreateAppContext(id)));
     writeLastApp(id);
 }
 // ---------- unload --------------------------------------------------------
@@ -167,6 +174,9 @@ export function unloadApp(id) {
         deactivateShard(shardId);
     }
     activeApp.id = null;
+    setActiveApp(null, new Set());
+    clearSelectionUnconditional();
+    void loadUserBindings('sh3.home').then(setUserBindings);
     appContexts.delete(id);
 }
 // ---------- unregister -------------------------------------------------------

package/dist/createShell.js

@@ -17,6 +17,7 @@ import { initFromBoot } from './auth/index';
 import SignInWall from './auth/SignInWall.svelte';
 import { loadBundleModule } from './registry/loader';
 import { registerLoadedBundle } from './registry/register';
+import { attachGlobalListeners } from './actions/listeners';
 export async function createShell(config) {
     var _a, _b, _c, _d, _e;
     const sUrl = (_a = config === null || config === void 0 ? void 0 : config.serverUrl) !== null && _a !== void 0 ? _a : '';
@@ -110,7 +111,9 @@ export async function createShell(config) {
     if (config === null || config === void 0 ? void 0 : config.excludeShards)
         bootstrapConfig.excludeShards = config.excludeShards;
     await bootstrap(bootstrapConfig);
-    // 8. Mount the shell
+    // 8. Attach document-level keyboard / focus listeners
+    attachGlobalListeners();
+    // 9. Mount the shell
     mount(Shell, { target });
 }
 /**

package/dist/host.js

@@ -16,6 +16,7 @@
  * imports from `host.ts`.
  */
 import { registerShard as registerShardInternal, activateShard, registeredShards, } from './shards/activate.svelte';
+import { addAutostartShard } from './actions/state.svelte';
 import { registerApp, registeredApps } from './apps/registry.svelte';
 import { launchApp, readLastApp } from './apps/lifecycle';
 import { sh3coreShard } from './sh3core-shard/sh3coreShard.svelte';
@@ -27,7 +28,6 @@ import { setLocalOwner } from './auth/index';
 import { storeApp } from './app/store/storeApp';
 import { adminShard } from './app/admin/adminShard.svelte';
 import { adminApp } from './app/admin/adminApp';
-import { terminalApp } from './apps/terminal/terminal-app';
 import { runShellRenameMigration, } from './migrations/shell-rename';
 export { __setBackend };
 export { setLocalOwner };
@@ -65,15 +65,18 @@ export async function bootstrap(config) {
         }
     }
     // 2. Framework-shipped apps
-    const frameworkApps = [storeApp, adminApp, terminalApp];
+    const frameworkApps = [storeApp, adminApp];
     for (const app of frameworkApps) {
         registerApp(app);
     }
     // 3. Load any packages installed in a previous session from IndexedDB
     await loadInstalledPackages();
-    // 4. Activate every self-starting shard
+    // 4. Activate every self-starting shard. Track them in the dispatcher's
+    // autostartShards set so the `'app'` action scope treats their actions as
+    // ambient (active even inside apps that don't list them as required).
     for (const [id, shard] of registeredShards) {
         if (shard.autostart) {
+            addAutostartShard(id);
             await activateShard(id);
         }
     }

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './api';
 export { default as Shell } from './Shell.svelte';
+export { default as Button } from './primitives/Button.svelte';
+export { provideIcons, getIconSprite, type ButtonVariant } from './primitives/icon-context';
 export type { ArtifactManifest } from './artifact';
 export * from './shell-shard/protocol';

package/dist/index.js

@@ -11,4 +11,6 @@
  */
 export * from './api';
 export { default as Shell } from './Shell.svelte';
+export { default as Button } from './primitives/Button.svelte';
+export { provideIcons, getIconSprite } from './primitives/icon-context';
 export * from './shell-shard/protocol';

package/dist/layout/LayoutRenderer.browser.test.js

@@ -272,3 +272,81 @@ describe('LayoutRenderer browser — E.5 splitter collapse toggle', () => {
         expect((_a = root.collapsed) === null || _a === void 0 ? void 0 : _a[0]).toBe(true);
     });
 });
+// ---------------------------------------------------------------------------
+// E.6 — fixed[] slots: no collapse widget, frozen handles
+// ---------------------------------------------------------------------------
+describe('LayoutRenderer browser — E.6 fixed slots', () => {
+    beforeEach(() => { cleanupDOM(); resetFramework(); });
+    it('hides the collapse widget on a fixed pane but keeps it on panes with a non-fixed neighbor', async () => {
+        stubView();
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'e6a' }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree(makeSplitNode([
+                        makeSlotNode('a', 'test:view'),
+                        makeSlotNode('b', 'test:view'),
+                        makeSlotNode('c', 'test:view'),
+                    ], { fixed: [true, false, false] })),
+                },
+            ],
+        }));
+        await launchApp('e6a');
+        renderWithShell(LayoutRenderer, { path: [] });
+        await settle(30);
+        expect(document.querySelector('[data-testid="collapse-toggle-0"]')).toBeNull();
+        expect(document.querySelector('[data-testid="collapse-toggle-1"]')).not.toBeNull();
+        expect(document.querySelector('[data-testid="collapse-toggle-2"]')).not.toBeNull();
+    });
+    it('freezes the handle adjacent to a fixed pane: dblclick does not collapse', async () => {
+        var _a, _b, _c, _d;
+        stubView();
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'e6b' }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree(makeSplitNode([makeSlotNode('a', 'test:view'), makeSlotNode('b', 'test:view')], { fixed: [true, false] })),
+                },
+            ],
+        }));
+        await launchApp('e6b');
+        renderWithShell(LayoutRenderer, { path: [] });
+        await settle(30);
+        const handle = document.querySelector('[data-testid="splitter-handle-0"]');
+        expect(handle).not.toBeNull();
+        expect(handle.classList.contains('frozen')).toBe(true);
+        // pointer-events: none blocks Playwright clicks, so dispatch the event
+        // directly to verify the handler itself refuses to toggle.
+        handle.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }));
+        await settle(50);
+        const root = layoutStore.root;
+        if ((root === null || root === void 0 ? void 0 : root.type) !== 'split')
+            throw new Error('expected split root');
+        expect((_b = (_a = root.collapsed) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : false).toBe(false);
+        expect((_d = (_c = root.collapsed) === null || _c === void 0 ? void 0 : _c[1]) !== null && _d !== void 0 ? _d : false).toBe(false);
+    });
+    it('hides the collapse widget on a middle pane whose neighbors are both fixed', async () => {
+        stubView();
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'e6c' }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree(makeSplitNode([
+                        makeSlotNode('a', 'test:view'),
+                        makeSlotNode('b', 'test:view'),
+                        makeSlotNode('c', 'test:view'),
+                    ], { fixed: [true, false, true] })),
+                },
+            ],
+        }));
+        await launchApp('e6c');
+        renderWithShell(LayoutRenderer, { path: [] });
+        await settle(30);
+        expect(document.querySelector('[data-testid="collapse-toggle-0"]')).toBeNull();
+        expect(document.querySelector('[data-testid="collapse-toggle-1"]')).toBeNull();
+        expect(document.querySelector('[data-testid="collapse-toggle-2"]')).toBeNull();
+    });
+});

package/dist/layout/LayoutRenderer.svelte

@@ -169,6 +169,7 @@
       sizes={split.sizes}
       pinned={split.pinned}
       collapsed={split.collapsed}
+      fixed={split.fixed}
       count={split.children.length}
       pane={splitPane}
       onResize={(i, v) => (split.sizes[i] = v)}

package/dist/layout/inspection.d.ts

@@ -1,4 +1,4 @@
-import type { TabEntry, LayoutTree } from './types';
+import type { TabEntry, LayoutTree, TreeRootRef } from './types';
 /**
  * Read-only snapshot of the currently-rendered layout tree. The return
  * value is the live object — callers MUST NOT mutate it directly;
@@ -87,3 +87,13 @@ export declare function dockFloat(floatId: string): boolean;
  * was empty or otherwise un-dockable.
  */
 export declare function dockIntoActiveLayout(entry: TabEntry): boolean;
+/**
+ * Find which root a slot currently lives under in the active layout.
+ * Returns `{ kind: 'docked' }` when the slot is anywhere in the docked
+ * tree, `{ kind: 'float', floatId }` when it lives inside a float, or
+ * `null` when the slot is not present (stale id, post-unmount, or
+ * held-but-not-active app tree). Thin wrapper over the pure
+ * `locateSlotIn(tree, slotId)` from `ops.ts` — use this when you only
+ * have a slotId in hand; use `locateSlotIn` if you already hold the tree.
+ */
+export declare function locateSlot(slotId: string): TreeRootRef | null;

package/dist/layout/inspection.js

@@ -13,7 +13,7 @@
  * rendered.
  */
 import { activeLayout, getActiveRoot } from './store.svelte';
-import { nodeAtPath, findTabBySlotId, removeTabBySlotId, cleanupTree, splitNodeAtPath, } from './ops';
+import { nodeAtPath, findTabBySlotId, removeTabBySlotId, cleanupTree, splitNodeAtPath, locateSlotIn, } from './ops';
 import { getSlotHandle } from './slotHostPool.svelte';
 import { floatManager } from '../overlays/float';
 /**
@@ -311,3 +311,15 @@ export function dockIntoActiveLayout(entry) {
     splitNodeAtPath(root, slotPath, entry, 'right');
     return true;
 }
+/**
+ * Find which root a slot currently lives under in the active layout.
+ * Returns `{ kind: 'docked' }` when the slot is anywhere in the docked
+ * tree, `{ kind: 'float', floatId }` when it lives inside a float, or
+ * `null` when the slot is not present (stale id, post-unmount, or
+ * held-but-not-active app tree). Thin wrapper over the pure
+ * `locateSlotIn(tree, slotId)` from `ops.ts` — use this when you only
+ * have a slotId in hand; use `locateSlotIn` if you already hold the tree.
+ */
+export function locateSlot(slotId) {
+    return locateSlotIn(activeLayout(), slotId);
+}

package/dist/layout/ops-locate.test.d.ts

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

package/dist/layout/ops-locate.test.js

@@ -0,0 +1,103 @@
+import { describe, it, expect } from 'vitest';
+import { locateSlotIn } from './ops';
+describe('locateSlotIn', () => {
+    it('finds a tab-entry slot in the docked tree', () => {
+        const tree = {
+            docked: {
+                type: 'tabs',
+                tabs: [{ slotId: 'dock-a', viewId: 'v', label: 'A' }],
+                activeTab: 0,
+            },
+            floats: [],
+        };
+        expect(locateSlotIn(tree, 'dock-a')).toEqual({ kind: 'docked' });
+    });
+    it('finds a bare slot leaf in the docked tree', () => {
+        const tree = {
+            docked: { type: 'slot', slotId: 'dock-leaf', viewId: 'v' },
+            floats: [],
+        };
+        expect(locateSlotIn(tree, 'dock-leaf')).toEqual({ kind: 'docked' });
+    });
+    it('finds a slot nested inside a split', () => {
+        const tree = {
+            docked: {
+                type: 'split',
+                direction: 'horizontal',
+                sizes: [0.5, 0.5],
+                children: [
+                    { type: 'slot', slotId: 'left', viewId: 'v' },
+                    {
+                        type: 'tabs',
+                        tabs: [{ slotId: 'right', viewId: 'v', label: 'R' }],
+                        activeTab: 0,
+                    },
+                ],
+            },
+            floats: [],
+        };
+        expect(locateSlotIn(tree, 'left')).toEqual({ kind: 'docked' });
+        expect(locateSlotIn(tree, 'right')).toEqual({ kind: 'docked' });
+    });
+    it('finds a tab-entry slot inside a float', () => {
+        const tree = {
+            docked: { type: 'tabs', tabs: [], activeTab: 0 },
+            floats: [
+                {
+                    id: 'float-1',
+                    content: {
+                        type: 'tabs',
+                        tabs: [{ slotId: 'float-a', viewId: 'v', label: 'A' }],
+                        activeTab: 0,
+                    },
+                    position: { x: 0, y: 0 },
+                    size: { w: 600, h: 400 },
+                },
+            ],
+        };
+        expect(locateSlotIn(tree, 'float-a')).toEqual({ kind: 'float', floatId: 'float-1' });
+    });
+    it('finds a bare slot leaf inside a float', () => {
+        const tree = {
+            docked: { type: 'tabs', tabs: [], activeTab: 0 },
+            floats: [
+                {
+                    id: 'float-2',
+                    content: { type: 'slot', slotId: 'float-leaf', viewId: 'v' },
+                    position: { x: 0, y: 0 },
+                    size: { w: 600, h: 400 },
+                },
+            ],
+        };
+        expect(locateSlotIn(tree, 'float-leaf')).toEqual({ kind: 'float', floatId: 'float-2' });
+    });
+    it('returns null for an absent slot', () => {
+        const tree = {
+            docked: { type: 'tabs', tabs: [], activeTab: 0 },
+            floats: [],
+        };
+        expect(locateSlotIn(tree, 'nope')).toBeNull();
+    });
+    it('prefers docked when an id is (illegally) present in both', () => {
+        const tree = {
+            docked: {
+                type: 'tabs',
+                tabs: [{ slotId: 'dup', viewId: 'v', label: 'D' }],
+                activeTab: 0,
+            },
+            floats: [
+                {
+                    id: 'float-3',
+                    content: {
+                        type: 'tabs',
+                        tabs: [{ slotId: 'dup', viewId: 'v', label: 'D' }],
+                        activeTab: 0,
+                    },
+                    position: { x: 0, y: 0 },
+                    size: { w: 600, h: 400 },
+                },
+            ],
+        };
+        expect(locateSlotIn(tree, 'dup')).toEqual({ kind: 'docked' });
+    });
+});

package/dist/layout/ops.d.ts

@@ -33,6 +33,14 @@ export interface LocatedTabInTree {
  * Returns null if the slot id is not present in any root.
  */
 export declare function findTabInTree(tree: LayoutTree, slotId: string): LocatedTabInTree | 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 declare function locateSlotIn(tree: LayoutTree, slotId: string): TreeRootRef | null;
 /**
  * Remove a tab from its current location, returning the removed entry
  * (or null if not found). The tabs group it was in may become empty