sh3-core 0.10.4 → 0.11.2

package/dist/overlays/popup.d.ts

@@ -7,3 +7,5 @@ export interface PopupManager {
     close(): void;
 }
 export declare const popupManager: PopupManager;
+/** @internal — test helper only. Closes any active popup and resets state. */
+export declare function __resetPopupManagerForTest(): void;

package/dist/overlays/popup.js

@@ -9,8 +9,8 @@
  *   - Popups do NOT stack. Opening a second popup dismisses the first.
  *   - Clicking outside the popup dismisses it.
  *   - Pressing Escape dismisses it.
- *   - The caller provides an HTMLElement anchor; the popup positions
- *     itself relative to the anchor's current viewport rect.
+ *   - The caller provides a PopupAnchor (HTMLElement or {x,y} point);
+ *     the popup positions itself relative to the anchor's viewport rect.
  *
  * Implementation notes:
  *   - The manager keeps at most one active entry. show() closes any
@@ -28,6 +28,17 @@
 import { mount, unmount } from 'svelte';
 import PopupFrame from './PopupFrame.svelte';
 import { getLayerRoot } from './roots';
+/**
+ * Convert a PopupAnchor to a DOMRect.
+ * - HTMLElement: uses its live bounding rect.
+ * - { x, y } virtual point: zero-size rect at the viewport coordinates so
+ *   PopupFrame places itself at bottom-start of the cursor position.
+ */
+function anchorRect(anchor) {
+    if (anchor instanceof HTMLElement)
+        return anchor.getBoundingClientRect();
+    return new DOMRect(anchor.x, anchor.y, 0, 0);
+}
 let current = null;
 function onDocumentPointerDown(e) {
     if (!current)
@@ -75,7 +86,7 @@ function showPopup(Content, options, props) {
     host.style.inset = '0';
     host.style.pointerEvents = 'none'; // only the frame captures pointer events
     root.appendChild(host);
-    const anchorRect = options.anchor.getBoundingClientRect();
+    const rect = anchorRect(options.anchor);
     const entry = {};
     const handle = {
         close: () => removeEntry(entry),
@@ -85,7 +96,7 @@ function showPopup(Content, options, props) {
         props: {
             Content: Content,
             contentProps: (props !== null && props !== void 0 ? props : {}),
-            anchorRect,
+            anchorRect: rect,
             close: handle.close,
         },
     });
@@ -106,3 +117,12 @@ export const popupManager = {
     show: showPopup,
     close: closeCurrent,
 };
+/** @internal — test helper only. Closes any active popup and resets state. */
+export function __resetPopupManagerForTest() {
+    if (current) {
+        removeDismissListeners();
+        unmount(current.frame);
+        current.host.remove();
+        current = null;
+    }
+}

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

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

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/ResizableSplitter.svelte

@@ -28,6 +28,7 @@
     sizes,
     pinned,
     collapsed,
+    fixed,
     count,
     pane,
     onResize,
@@ -46,6 +47,13 @@
     pinned?: SizeMode[];
     /** Per-pane collapsed state. Omitted entries default to false. */
     collapsed?: boolean[];
+    /**
+     * Per-pane fixed flag. A fixed pane has no collapse widget and
+     * the handles on either side of it are frozen (non-interactive,
+     * rendered thinner). A non-fixed pane whose every neighbor is
+     * fixed also loses its collapse widget.
+     */
+    fixed?: boolean[];
     /** Number of panes — `sizes.length` should match. */
     count: number;
     /** Snippet invoked once per pane with the pane index. */
@@ -67,6 +75,15 @@
 
   const modeOf = (i: number): SizeMode => pinned?.[i] ?? 'fr';
   const isCollapsed = (i: number): boolean => collapsed?.[i] ?? false;
+  const isFixed = (i: number): boolean => fixed?.[i] ?? false;
+  const isHandleFrozen = (i: number): boolean => isFixed(i) || isFixed(i + 1);
+
+  function canCollapse(i: number): boolean {
+    if (isFixed(i)) return false;
+    const left = i > 0 ? !isFixed(i - 1) : false;
+    const right = i < count - 1 ? !isFixed(i + 1) : false;
+    return left || right;
+  }
 
   /** CSS `flex` shorthand for pane i. */
   function flexFor(i: number): string {
@@ -88,8 +105,9 @@
   let drag: DragState | null = $state(null);
 
   function beginDrag(e: PointerEvent, handleIndex: number) {
-    // Disable resize handles adjacent to collapsed panes.
+    // Disable resize handles adjacent to collapsed or fixed panes.
     if (isCollapsed(handleIndex) || isCollapsed(handleIndex + 1)) return;
+    if (isHandleFrozen(handleIndex)) return;
 
     e.preventDefault();
     (e.target as HTMLElement).setPointerCapture(e.pointerId);
@@ -198,12 +216,13 @@
           <span class="collapse-icon">{direction === 'horizontal' ? '▸' : '▾'}</span>
         </button>
       {:else}
-        {#if onCollapseToggle}
+        {#if onCollapseToggle && canCollapse(i)}
           <button
             type="button"
             class="collapse-header expanded"
             class:horizontal={direction === 'horizontal'}
             class:vertical={direction === 'vertical'}
+            data-testid="collapse-toggle-{i}"
             onclick={() => onCollapseToggle?.(i, true)}
             aria-label="Collapse pane"
           >
@@ -221,12 +240,17 @@
         class="splitter-handle"
         class:dragging={drag?.handleIndex === i}
         class:disabled={isCollapsed(i) || isCollapsed(i + 1)}
+        class:frozen={isHandleFrozen(i)}
         data-testid="splitter-handle-{i}"
         onpointerdown={(e) => beginDrag(e, i)}
         onpointermove={moveDrag}
         onpointerup={endDrag}
         onpointercancel={endDrag}
-        ondblclick={() => onCollapseToggle?.(i, !isCollapsed(i))}
+        ondblclick={() => {
+          if (isHandleFrozen(i)) return;
+          if (!canCollapse(i) && !isCollapsed(i)) return;
+          onCollapseToggle?.(i, !isCollapsed(i));
+        }}
         role="separator"
         aria-orientation={direction === 'horizontal' ? 'vertical' : 'horizontal'}
       ></div>
@@ -323,6 +347,15 @@
     cursor: default;
     pointer-events: none;
   }
+  .splitter-handle.frozen {
+    cursor: default;
+    pointer-events: none;
+    background: var(--shell-border);
+    opacity: 0.5;
+  }
+  .splitter-handle.frozen:hover {
+    background: var(--shell-border);
+  }
 
   .horizontal > .splitter-handle {
     width: 4px;
@@ -332,4 +365,6 @@
     height: 4px;
     cursor: row-resize;
   }
+  .horizontal > .splitter-handle.frozen { width: 1px; }
+  .vertical   > .splitter-handle.frozen { height: 1px; }
 </style>

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

@@ -14,6 +14,13 @@ type $$ComponentProps = {
     pinned?: SizeMode[];
     /** Per-pane collapsed state. Omitted entries default to false. */
     collapsed?: boolean[];
+    /**
+     * Per-pane fixed flag. A fixed pane has no collapse widget and
+     * the handles on either side of it are frozen (non-interactive,
+     * rendered thinner). A non-fixed pane whose every neighbor is
+     * fixed also loses its collapse widget.
+     */
+    fixed?: boolean[];
     /** Number of panes — `sizes.length` should match. */
     count: number;
     /** Snippet invoked once per pane with the pane index. */

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.