sh3-core 0.10.5 → 0.11.2

package/dist/overlays/popup.test.js

@@ -0,0 +1,95 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { tick } from 'svelte';
+import { popupManager, __resetPopupManagerForTest } from './popup';
+import { registerLayerRoot, unregisterLayerRoot } from './roots';
+import DummyFrame from './__test__/DummyFrame.svelte';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeLayerRoot() {
+    const el = document.createElement('div');
+    el.style.position = 'relative';
+    document.body.appendChild(el);
+    registerLayerRoot('popup', el);
+    return el;
+}
+function teardownLayerRoot(el) {
+    unregisterLayerRoot('popup');
+    el.remove();
+}
+// ---------------------------------------------------------------------------
+// P.1 — virtual-point anchor (context-menu use case)
+// ---------------------------------------------------------------------------
+describe('popup — P.1 virtual-point anchor', () => {
+    let layerRoot;
+    beforeEach(() => {
+        // Give the viewport a real size so the overflow clamp in PopupFrame
+        // doesn't crush our anchor coordinates to the clamped minimum.
+        vi.stubGlobal('innerWidth', 2000);
+        vi.stubGlobal('innerHeight', 2000);
+        layerRoot = makeLayerRoot();
+    });
+    afterEach(() => {
+        __resetPopupManagerForTest();
+        teardownLayerRoot(layerRoot);
+        vi.unstubAllGlobals();
+    });
+    it('accepts { x, y } as anchor without throwing', () => {
+        expect(() => {
+            popupManager.show(DummyFrame, { anchor: { x: 100, y: 200 } }, {});
+        }).not.toThrow();
+    });
+    it('mounts the popup host inside the layer root', () => {
+        popupManager.show(DummyFrame, { anchor: { x: 100, y: 200 } }, {});
+        const host = layerRoot.querySelector('.sh3-popup-host');
+        expect(host).not.toBeNull();
+    });
+    it('renders the dummy frame content inside the host', async () => {
+        popupManager.show(DummyFrame, { anchor: { x: 100, y: 200 } }, {});
+        await tick();
+        const content = layerRoot.querySelector('.dummy-popup-content');
+        expect(content).not.toBeNull();
+    });
+    it('positions the popup frame at bottom-start of the virtual point', async () => {
+        popupManager.show(DummyFrame, { anchor: { x: 100, y: 200 } }, {});
+        await tick();
+        // PopupFrame sets top = anchor.bottom + 4 = 200 + 4 = 204 (zero-size rect: bottom === y).
+        // left = anchor.left = 100 (no overflow with 2000px viewport).
+        const frame = layerRoot.querySelector('.popup-frame');
+        expect(frame).not.toBeNull();
+        expect(frame.style.top).toBe('204px');
+        expect(frame.style.left).toBe('100px');
+    });
+    it('close() removes the host from the DOM', async () => {
+        popupManager.show(DummyFrame, { anchor: { x: 50, y: 80 } }, {});
+        await tick();
+        expect(layerRoot.querySelector('.sh3-popup-host')).not.toBeNull();
+        popupManager.close();
+        await tick();
+        expect(layerRoot.querySelector('.sh3-popup-host')).toBeNull();
+    });
+});
+// ---------------------------------------------------------------------------
+// P.2 — HTMLElement anchor still works (regression guard)
+// ---------------------------------------------------------------------------
+describe('popup — P.2 HTMLElement anchor regression', () => {
+    let layerRoot;
+    beforeEach(() => {
+        vi.stubGlobal('innerWidth', 2000);
+        vi.stubGlobal('innerHeight', 2000);
+        layerRoot = makeLayerRoot();
+    });
+    afterEach(() => {
+        __resetPopupManagerForTest();
+        teardownLayerRoot(layerRoot);
+        vi.unstubAllGlobals();
+    });
+    it('accepts an HTMLElement anchor without throwing', () => {
+        const anchor = document.createElement('button');
+        document.body.appendChild(anchor);
+        expect(() => {
+            popupManager.show(DummyFrame, { anchor }, {});
+        }).not.toThrow();
+        anchor.remove();
+    });
+});

package/dist/overlays/types.d.ts

@@ -9,8 +9,17 @@ export type ToastHandle = OverlayHandle;
 export type ToastLevel = 'info' | 'warn' | 'error' | 'success';
 /** Where a popup should sit relative to its anchor. Phase 5 ships bottom-start. */
 export type PopupPlacement = 'bottom-start';
+/**
+ * Anchor for a popup — either an HTMLElement whose bounding rect is used, or
+ * a virtual point `{ x, y }` in viewport coordinates (used by context menus
+ * that anchor at pointer coordinates).
+ */
+export type PopupAnchor = HTMLElement | {
+    x: number;
+    y: number;
+};
 export interface PopupOptions {
-    anchor: HTMLElement;
+    anchor: PopupAnchor;
     placement?: PopupPlacement;
 }
 export interface ToastOptions {
@@ -28,4 +37,11 @@ export interface ModalOptions {
      * views like non-centered palettes or inspectors.
      */
     boxStyle?: string;
+    /**
+     * When true, a click on the frame area outside the dialog box closes the
+     * modal. Default false — content owns its own close UI. Opt-in is for
+     * picker-style modals like the command palette where outside-click is the
+     * expected dismissal gesture.
+     */
+    dismissOnBackdrop?: boolean;
 }

package/dist/primitives/Button.svelte

@@ -0,0 +1,144 @@
+<script lang="ts">
+  /*
+   * Button — themed button primitive for shards and apps.
+   *
+   * Icons resolve via a three-tier lookup (see primitives/icon-context.ts).
+   * `icon` accepts either a sprite symbol id ("save") or a direct URL
+   * ending in .svg / containing a slash ("./foo.svg"); the URL form
+   * bypasses the active sprite entirely.
+   */
+
+  import type { Snippet } from 'svelte';
+  import coreSpriteUrl from '../assets/icons.svg';
+  import { getIconSprite, type ButtonVariant } from './icon-context';
+
+  let {
+    variant = 'default',
+    icon,
+    sprite,
+    disabled = false,
+    type = 'button',
+    title,
+    ariaLabel,
+    onclick,
+    children,
+  }: {
+    variant?: ButtonVariant;
+    /** Sprite symbol id, or a direct .svg URL. */
+    icon?: string;
+    /** Override the sprite sheet URL for this button only. */
+    sprite?: string;
+    disabled?: boolean;
+    type?: 'button' | 'submit' | 'reset';
+    title?: string;
+    ariaLabel?: string;
+    onclick?: (event: MouseEvent) => void;
+    children?: Snippet;
+  } = $props();
+
+  const contextSprite = getIconSprite();
+
+  function isDirectUrl(value: string): boolean {
+    return value.includes('/') || value.endsWith('.svg');
+  }
+
+  const iconHref = $derived.by(() => {
+    if (!icon) return undefined;
+    if (isDirectUrl(icon)) return icon;
+    const base = sprite ?? contextSprite ?? coreSpriteUrl;
+    return `${base}#${icon}`;
+  });
+
+  const iconOnly = $derived(variant === 'icon' || (!!icon && !children));
+</script>
+
+<button
+  {type}
+  class="sh3-btn sh3-btn--{variant}"
+  class:sh3-btn--icon-only={iconOnly}
+  {disabled}
+  {title}
+  aria-label={ariaLabel ?? (iconOnly ? title : undefined)}
+  {onclick}
+>
+  {#if iconHref}
+    <svg class="sh3-btn__icon" aria-hidden="true">
+      <use href={iconHref} />
+    </svg>
+  {/if}
+  {#if children}
+    <span class="sh3-btn__label">{@render children()}</span>
+  {/if}
+</button>
+
+<style>
+  .sh3-btn {
+    appearance: none;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--shell-pad-sm);
+    padding: 6px 14px;
+    background: var(--shell-accent);
+    color: var(--shell-fg-on-accent);
+    border: none;
+    border-radius: var(--shell-radius);
+    cursor: pointer;
+    font-family: inherit;
+    font-size: 0.875rem;
+    line-height: var(--shell-line);
+  }
+  .sh3-btn:hover:not(:disabled) { filter: brightness(1.12); }
+  .sh3-btn:active:not(:disabled) { filter: brightness(0.92); }
+  .sh3-btn:focus-visible {
+    box-shadow: var(--shell-focus-ring);
+    outline: none;
+  }
+  .sh3-btn:disabled {
+    opacity: 0.55;
+    cursor: not-allowed;
+  }
+
+  .sh3-btn--alert {
+    background: var(--shell-error);
+    color: var(--shell-fg-on-error);
+  }
+
+  .sh3-btn--ghost {
+    background: transparent;
+    color: var(--shell-fg);
+    border: 1px solid var(--shell-border);
+  }
+  .sh3-btn--ghost:hover:not(:disabled) {
+    background: var(--shell-bg-elevated);
+    filter: none;
+  }
+
+  .sh3-btn--icon {
+    background: transparent;
+    color: var(--shell-fg-muted);
+    padding: var(--shell-pad-sm);
+  }
+  .sh3-btn--icon:hover:not(:disabled) {
+    background: var(--shell-bg-elevated);
+    color: var(--shell-fg);
+    filter: none;
+  }
+
+  .sh3-btn--icon-only {
+    padding: var(--shell-pad-sm);
+    width: 26px;
+    height: 26px;
+  }
+
+  .sh3-btn__icon {
+    width: 16px;
+    height: 16px;
+    flex-shrink: 0;
+  }
+
+  .sh3-btn__label {
+    display: inline-flex;
+    white-space: nowrap;
+  }
+</style>

package/dist/primitives/Button.svelte.d.ts

@@ -0,0 +1,18 @@
+import type { Snippet } from 'svelte';
+import { type ButtonVariant } from './icon-context';
+type $$ComponentProps = {
+    variant?: ButtonVariant;
+    /** Sprite symbol id, or a direct .svg URL. */
+    icon?: string;
+    /** Override the sprite sheet URL for this button only. */
+    sprite?: string;
+    disabled?: boolean;
+    type?: 'button' | 'submit' | 'reset';
+    title?: string;
+    ariaLabel?: string;
+    onclick?: (event: MouseEvent) => void;
+    children?: Snippet;
+};
+declare const Button: import("svelte").Component<$$ComponentProps, {}, "">;
+type Button = ReturnType<typeof Button>;
+export default Button;

package/dist/primitives/icon-context.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Visual variants for <Button>. Exported from this module (rather than
+ * from Button.svelte itself) so TypeDoc, which only sees `.svelte`
+ * imports through the ambient `*.svelte` asset declaration, can
+ * discover it. Button.svelte re-imports this type.
+ */
+export type ButtonVariant = 'default' | 'alert' | 'ghost' | 'icon';
+/**
+ * Register an icon sprite URL for this subtree. Call from a view's
+ * <script> block to have every descendant <Button icon="..."/> resolve
+ * the icon name against this sprite.
+ */
+export declare function provideIcons(spriteUrl: string): void;
+/** Read the currently-active sprite URL, or undefined if none set. */
+export declare function getIconSprite(): string | undefined;

package/dist/primitives/icon-context.js

@@ -0,0 +1,29 @@
+/*
+ * Icon sprite context — lets a view opt all descendant <Button> (and any
+ * future icon-consuming primitive) into using a different sprite sheet
+ * than sh3-core's default assets/icons.svg.
+ *
+ * Resolution order inside Button is:
+ *   1. `sprite` prop on the Button (explicit one-off override)
+ *   2. nearest `provideIcons(url)` call up the Svelte tree (this module)
+ *   3. sh3-core's bundled sprite (fallback)
+ *
+ * This is tree-scoped (Svelte context), so it does not cross custom
+ * element / iframe boundaries. Shards that render inside such boundaries
+ * should pass `sprite` explicitly or call provideIcons() from their own
+ * root component.
+ */
+import { getContext, setContext } from 'svelte';
+const ICON_SPRITE_KEY = Symbol('sh3.icon-sprite');
+/**
+ * Register an icon sprite URL for this subtree. Call from a view's
+ * <script> block to have every descendant <Button icon="..."/> resolve
+ * the icon name against this sprite.
+ */
+export function provideIcons(spriteUrl) {
+    setContext(ICON_SPRITE_KEY, spriteUrl);
+}
+/** Read the currently-active sprite URL, or undefined if none set. */
+export function getIconSprite() {
+    return getContext(ICON_SPRITE_KEY);
+}

package/dist/sh3core-shard/sh3coreShard.svelte.js

@@ -25,6 +25,9 @@ import { mount, unmount } from 'svelte';
 import ShellHome from './ShellHome.svelte';
 import KeysAndPeers from '../shell/views/KeysAndPeers.svelte';
 import { VERSION } from '../version';
+import { __setBindingsZone } from '../actions/bindings-store';
+import { registeredApps } from '../apps/registry.svelte';
+import { launchApp } from '../apps/lifecycle';
 export const sh3coreShard = {
     manifest: {
         id: '__sh3core__',
@@ -36,6 +39,24 @@ export const sh3coreShard = {
         ],
     },
     activate(ctx) {
+        const zones = ctx.state({
+            user: {
+                bindings: {},
+            },
+        });
+        __setBindingsZone(zones.user);
+        ctx.actions.register({
+            id: 'sh3.palette.open',
+            label: 'Command Palette…',
+            scope: ['home', 'app'],
+            defaultShortcut: 'Mod+K',
+            contextItem: false,
+            paletteItem: false,
+            run(_dispatchCtx) {
+                // Lazy import to avoid circular module load at boot.
+                import('../actions/listeners').then(({ openPalette }) => openPalette());
+            },
+        });
         const factory = {
             mount(container, _context) {
                 const instance = mount(ShellHome, { target: container });
@@ -55,6 +76,35 @@ export const sh3coreShard = {
         };
         ctx.registerView('sh3core:home', factory);
         ctx.registerView('shell:keys-and-peers', keysFactory);
+        // Dynamic launcher actions: one "Launch <App>" per registered app, kept
+        // in sync as packages install/uninstall via the registry. Re-launching
+        // the active app is harmless (lifecycle treats it as a resume).
+        const launcherUnregisters = new Map();
+        $effect.root(() => {
+            $effect(() => {
+                const currentIds = new Set();
+                for (const [id, app] of registeredApps) {
+                    currentIds.add(id);
+                    if (launcherUnregisters.has(id))
+                        continue;
+                    const off = ctx.actions.register({
+                        id: `sh3.app.launch:${id}`,
+                        label: `Launch ${app.manifest.label}`,
+                        scope: ['home', 'app'],
+                        run() {
+                            void launchApp(id);
+                        },
+                    });
+                    launcherUnregisters.set(id, off);
+                }
+                for (const id of [...launcherUnregisters.keys()]) {
+                    if (!currentIds.has(id)) {
+                        launcherUnregisters.get(id)();
+                        launcherUnregisters.delete(id);
+                    }
+                }
+            });
+        });
     },
     autostart() {
         // Intentionally empty. Defining this field is what puts the sh3core

package/dist/shards/activate.svelte.js

@@ -29,6 +29,9 @@ import { createShardKeysApi } from '../keys/client';
 import { PERMISSION_KEYS_MINT } from '../keys/types';
 import { subscribe } from '../keys/revocation-bus.svelte';
 import { register as contributionsRegister, list as contributionsList, listPoints as contributionsListPoints, onChange as contributionsOnChange, } from '../contributions';
+import { registerAction } from '../actions/registry';
+import { makeSelectionApi, clearSelectionForShard } from '../actions/selection.svelte';
+import { openContextMenu as shellOpenContextMenu, openPalette as shellOpenPalette } from '../actions/listeners';
 /**
  * Reactive registry of every shard known to the host. Keys are shard ids.
  * Populated once at boot by the glob-discovery loop in main.ts (through
@@ -171,6 +174,16 @@ export async function activateShard(id) {
             })
             : undefined,
         contributions,
+        actions: {
+            register(action) {
+                const dispose = registerAction(action, id);
+                entry.cleanupFns.push(async () => dispose());
+                return dispose;
+            },
+            selection: makeSelectionApi(id),
+            openContextMenu(opts) { shellOpenContextMenu(opts); },
+            openPalette(opts) { shellOpenPalette(opts); },
+        },
     };
     entry.ctx = ctx;
     // Wire onKeyRevoked hook: subscribe to the revocation bus for this shard.
@@ -228,6 +241,7 @@ export function deactivateShard(id) {
         fwUnregisterVerb(name);
     for (const viewId of entry.viewIds)
         unregisterView(viewId);
+    clearSelectionForShard(id);
     active.delete(id);
     activeShards.delete(id);
 }

package/dist/shards/types.d.ts

@@ -6,6 +6,8 @@ import type { EnvState } from '../env/types';
 import type { Verb } from '../verbs/types';
 import type { ShardContextKeys } from '../keys/types';
 import type { ContributionsApi } from '../contributions/types';
+import type { ActionsApi } from '../actions/types';
+import type { TreeRootRef } from '../layout/types';
 export { PERMISSION_KEYS_MINT, type ShardContextKeys, type ApiKeyPublic, type MintOpts, ScopeEscalationError, ConsentDeniedError } from '../keys/types';
 /**
  * The object returned by `ViewFactory.mount`. The framework calls
@@ -59,6 +61,18 @@ export interface MountContext {
      * Call this whenever the view's save-state changes.
      */
     setDirty(dirty: boolean): void;
+    /**
+     * Snapshot of this view's current host location. Returns
+     * `{ kind: 'docked' }` when the containing slot is anywhere in the
+     * active docked tree, `{ kind: 'float', floatId }` when it lives
+     * inside a float's subtree, or `null` when the slot is no longer
+     * present in the active layout.
+     *
+     * Not reactive — each call walks the current layout. Call it when
+     * you need to decide something (e.g. toggle a pop-out button,
+     * branch in a context-menu handler).
+     */
+    location(): TreeRootRef | null;
 }
 /**
  * The shard-side adapter that knows how to bring a view to life inside a
@@ -232,6 +246,11 @@ export interface ShardContext {
      * docs/sh3-rfcs/2026-04-20-shard-contribution-points.md.
      */
     contributions: ContributionsApi;
+    /**
+     * Register UI actions (keyboard shortcuts, context-menu items, palette
+     * entries). Actions are auto-unregistered when the shard deactivates.
+     */
+    actions: ActionsApi;
 }
 /**
  * A shard module. Shards are the fundamental unit of contribution in SH3.

package/dist/shards/types.js

@@ -12,9 +12,10 @@
  *   - A ViewFactory knows how to mount a view into a raw HTMLElement and
  *     return a handle the framework uses to unmount / notify of resizes.
  *
- * Deferred to later phases: bus scoping, command/toolbar/menu/hotkey
- * registration, modal provider contributions, background services, lazy
- * activation events. They'll slot into `ShardContext` as new `register*`
- * methods without disturbing the phase-4 shape.
+ * Action contributions (commands, hotkeys, context menus) shipped in v0.11.0
+ * via `ctx.actions` (see `../actions/types.ts`). Still deferred to later
+ * phases: bus scoping, toolbar registration, modal provider contributions,
+ * background services, lazy activation events. They'll slot into `ShardContext`
+ * as new `register*` methods without disturbing the phase-4 shape.
  */
 export { PERMISSION_KEYS_MINT, ScopeEscalationError, ConsentDeniedError } from '../keys/types';

package/dist/shell-shard/locateSlot.test.d.ts

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

package/dist/shell-shard/locateSlot.test.js

@@ -0,0 +1,101 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { resetFramework } from '../__test__/reset';
+import { makeApp, makeAppManifest, makeTabEntry, makeTabsNode, makeTree } from '../__test__/fixtures';
+import { registerApp } from '../apps/registry.svelte';
+import { launchApp } from '../apps/lifecycle';
+import { floatManager, bindFloatStore } from '../overlays/float';
+import { layoutStore } from '../layout/store.svelte';
+import { makeShellApiForTest } from './shellShard.svelte';
+describe('ShellApi.locateSlot', () => {
+    beforeEach(resetFramework);
+    it('returns docked for a slot in the docked tree', async () => {
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'test-app-docked' }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree(makeTabsNode([makeTabEntry({ slotId: 'dock-x' })])),
+                },
+            ],
+        }));
+        await launchApp('test-app-docked');
+        const shell = makeShellApiForTest();
+        expect(shell.locateSlot('dock-x')).toEqual({ kind: 'docked' });
+    });
+    it('returns float for a slot in a float', async () => {
+        var _a;
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'test-app-float' }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree(makeTabsNode([makeTabEntry({ slotId: 'stay-docked' })])),
+                },
+            ],
+        }));
+        await launchApp('test-app-float');
+        // Shell.svelte normally binds the float manager to the active tree's
+        // floats array during boot. In tests we bind it manually so
+        // floatManager.open() writes into the tree that locateSlot walks.
+        bindFloatStore(layoutStore.floats, () => ({ w: 1024, h: 768 }));
+        const floatId = floatManager.open('v', { title: 'Float X' });
+        const openedFloat = layoutStore.floats.find((f) => f.id === floatId);
+        expect(openedFloat).toBeDefined();
+        const tabs = openedFloat.content.type === 'tabs' ? openedFloat.content : null;
+        const floatSlotId = (_a = tabs === null || tabs === void 0 ? void 0 : tabs.tabs[0]) === null || _a === void 0 ? void 0 : _a.slotId;
+        expect(floatSlotId).toBeTruthy();
+        const shell = makeShellApiForTest();
+        expect(shell.locateSlot(floatSlotId)).toEqual({ kind: 'float', floatId });
+    });
+    it('returns null for an absent slot', async () => {
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'test-app-absent' }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree(makeTabsNode([makeTabEntry({ slotId: 'existing' })])),
+                },
+            ],
+        }));
+        await launchApp('test-app-absent');
+        const shell = makeShellApiForTest();
+        expect(shell.locateSlot('nonexistent-slot')).toBeNull();
+    });
+});
+import { popoutView, inspectActiveLayout } from '../layout/inspection';
+describe('ShellApi.locateSlot — round-trip', () => {
+    beforeEach(resetFramework);
+    it('tracks the docked → popout → float transition', async () => {
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'test-app-rt' }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree(makeTabsNode([
+                        makeTabEntry({ slotId: 'rt-1', viewId: 'rt:one' }),
+                        makeTabEntry({ slotId: 'rt-anchor', viewId: 'rt:anchor' }),
+                    ])),
+                },
+            ],
+        }));
+        await launchApp('test-app-rt');
+        // Shell.svelte would bind this at boot; in tests we do it ourselves.
+        bindFloatStore(layoutStore.floats, () => ({ w: 1024, h: 768 }));
+        const shell = makeShellApiForTest();
+        // Starts docked.
+        expect(shell.locateSlot('rt-1')).toEqual({ kind: 'docked' });
+        // Popout removes the original docked tab and opens a float with a
+        // fresh slotId wrapped around the same view.
+        const floatId = popoutView('rt-1');
+        expect(floatId).not.toBeNull();
+        expect(shell.locateSlot('rt-1')).toBeNull();
+        // The float-era slotId resolves to the new float.
+        const { root } = inspectActiveLayout();
+        const fl = root.floats.find((f) => f.id === floatId);
+        const floatSlot = fl.content.type === 'tabs' ? fl.content.tabs[0].slotId : '';
+        expect(floatSlot).toBeTruthy();
+        expect(shell.locateSlot(floatSlot)).toEqual({ kind: 'float', floatId });
+        // Anchor tab is untouched and still docked.
+        expect(shell.locateSlot('rt-anchor')).toEqual({ kind: 'docked' });
+    });
+});

package/dist/shell-shard/shellShard.svelte.d.ts

@@ -1,2 +1,9 @@
 import type { Shard } from '../api';
+import type { ShellApi } from './registry';
+/**
+ * Test-only ShellApi constructor. Bypasses the admin gate and uses a
+ * stub ShardContext. Only methods that do not consult `ctx` are
+ * guaranteed to work — `locateSlot`, `listFloats`, `listApps`, etc.
+ */
+export declare function makeShellApiForTest(): ShellApi;
 export declare const shellShard: Shard;

package/dist/shell-shard/shellShard.svelte.js

@@ -19,7 +19,7 @@ import { registerV1Verbs } from './verbs';
 import { listRegisteredApps, getActiveApp } from '../apps/registry.svelte';
 import { launchApp } from '../apps/lifecycle';
 import { registeredShards } from '../shards/activate.svelte';
-import { inspectActiveLayout, focusView, closeTab, popoutView, dockFloat, dockIntoActiveLayout } from '../layout/inspection';
+import { inspectActiveLayout, focusView, closeTab, popoutView, dockFloat, dockIntoActiveLayout, locateSlot as locateSlotInActiveLayout } from '../layout/inspection';
 import { floatManager } from '../overlays/float';
 import { listStandaloneViews } from '../shards/activate.svelte';
 import { getUser, isAdmin } from '../auth/index';
@@ -121,6 +121,15 @@ function makeShellApi(_ctx) {
                 return { ok: false, error: err instanceof Error ? err.message : String(err) };
             }
         },
+        // → layout/inspection: locateSlot(slotId) returns TreeRootRef | null
+        locateSlot(slotId) {
+            try {
+                return locateSlotInActiveLayout(slotId);
+            }
+            catch (_a) {
+                return null;
+            }
+        },
         // → overlays/float: floatManager.list() returns FloatEntry[]
         listFloats() {
             return floatManager.list().map((f) => {
@@ -156,6 +165,14 @@ function makeShellApi(_ctx) {
         },
     };
 }
+/**
+ * Test-only ShellApi constructor. Bypasses the admin gate and uses a
+ * stub ShardContext. Only methods that do not consult `ctx` are
+ * guaranteed to work — `locateSlot`, `listFloats`, `listApps`, etc.
+ */
+export function makeShellApiForTest() {
+    return makeShellApi({});
+}
 export const shellShard = {
     manifest,
     activate(ctx) {
@@ -165,6 +182,22 @@ export const shellShard = {
         }
         registerV1Verbs(ctx);
         const shell = makeShellApi(ctx);
+        // The AZERTY `²` key (top-left on FR keyboards, below Escape) opens the
+        // terminal view — focusing it if already mounted, floating it otherwise.
+        // Migrated from Shell.svelte's inline keydown handler as proof-of-concept
+        // for the Actions framework (Task 23 / DF1). Registered here because this
+        // shard owns the terminal view and is already admin-gated.
+        ctx.actions.register({
+            id: 'shell.terminal.toggle',
+            label: 'Open Terminal',
+            scope: ['home', 'app'],
+            defaultShortcut: '²',
+            allowInInputs: false,
+            run() {
+                if (!focusView('shell:terminal'))
+                    floatManager.open('shell:terminal', { title: 'Shell' });
+            },
+        });
         const factory = {
             mount(container, _context) {
                 var _a;