sh3-core 0.7.3 → 0.8.0

package/dist/primitives/TabbedPanel.svelte

@@ -76,6 +76,7 @@
     closable,
     dirty,
     onClose,
+    tabIds,
   }: {
     labels: string[];
     icons?: (string | undefined)[];
@@ -100,6 +101,8 @@
     dirty?: (boolean | undefined)[];
     /** Called when the user clicks a tab's close button. */
     onClose?: (index: number) => void;
+    /** Optional stable ids for each tab (e.g. slotId). Used as data-testid suffixes on close buttons. */
+    tabIds?: (string | undefined)[];
   } = $props();
 
   function select(i: number) {
@@ -172,6 +175,7 @@
             role="button"
             tabindex="-1"
             title="Close"
+            data-testid={tabIds?.[i] ? `tab-close-${tabIds[i]}` : undefined}
             onclick={(e) => handleClose(i, e)}
             onkeydown={(e) => { if (e.key === 'Enter' || e.key === ' ') handleClose(i, e); }}
           >&#x2715;</span>

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

@@ -44,6 +44,8 @@ type $$ComponentProps = {
     dirty?: (boolean | undefined)[];
     /** Called when the user clicks a tab's close button. */
     onClose?: (index: number) => void;
+    /** Optional stable ids for each tab (e.g. slotId). Used as data-testid suffixes on close buttons. */
+    tabIds?: (string | undefined)[];
 };
 declare const TabbedPanel: import("svelte").Component<$$ComponentProps, {}, "">;
 type TabbedPanel = ReturnType<typeof TabbedPanel>;

package/dist/registry/installer.d.ts

@@ -7,9 +7,10 @@
  *
  * Flow:
  *   1. `installPackage(bundle, meta)` -- load module from bytes, verify
- *      declared type matches actual type, persist to IndexedDB, register
- *      with framework.
- *   2. `uninstallPackage(id)` -- deactivate if active, remove from storage.
+ *      declared type matches actual type, persist to IndexedDB, evict any
+ *      existing registration, then register via the shared helper.
+ *   2. `uninstallPackage(id)` -- deactivate if active, unregister app, remove
+ *      from storage.
  *   3. `loadInstalledPackages()` -- called at boot, re-loads all installed
  *      packages from IndexedDB and registers them.
  */
@@ -18,9 +19,10 @@ import type { InstalledPackage, InstallResult, PackageMeta } from './types';
  * Install a package from raw bundle bytes and metadata.
  *
  * Loads the ESM module, verifies the declared type matches the actual module
- * shape, persists to IndexedDB, and registers with the framework. If
- * registration fails (e.g. duplicate id from a shard that was already
- * glob-discovered), the package is still persisted but `hotLoaded` is false.
+ * shape, persists to IndexedDB, evicts any existing registration for the same
+ * id, and registers with the framework via the shared helper. If registration
+ * fails (e.g. a shard that was already glob-discovered), the package is still
+ * persisted but `hotLoaded` is false.
  *
  * @param bundle - Raw verified ESM bundle bytes.
  * @param meta - Provenance metadata for the install record.
@@ -31,7 +33,8 @@ export declare function installPackage(bundle: ArrayBuffer, meta: PackageMeta):
  * Uninstall a package by id.
  *
  * If the package is a shard and currently active, deactivates it first.
- * Removes both the bundle and metadata from IndexedDB.
+ * Unregisters any app entry for the id, then removes both the bundle and
+ * metadata from IndexedDB.
  *
  * @param id - The package id to uninstall.
  */

package/dist/registry/installer.js

@@ -7,24 +7,27 @@
  *
  * Flow:
  *   1. `installPackage(bundle, meta)` -- load module from bytes, verify
- *      declared type matches actual type, persist to IndexedDB, register
- *      with framework.
- *   2. `uninstallPackage(id)` -- deactivate if active, remove from storage.
+ *      declared type matches actual type, persist to IndexedDB, evict any
+ *      existing registration, then register via the shared helper.
+ *   2. `uninstallPackage(id)` -- deactivate if active, unregister app, remove
+ *      from storage.
  *   3. `loadInstalledPackages()` -- called at boot, re-loads all installed
  *      packages from IndexedDB and registers them.
  */
 import { loadBundleModule } from './loader';
 import { savePackage, loadBundle, listInstalled, removePackage } from './storage';
 import { verifyIntegrity } from './integrity';
-import { registerShard, deactivateShard } from '../shards/activate.svelte';
-import { registerApp } from '../apps/registry.svelte';
+import { deactivateShard } from '../shards/activate.svelte';
+import { unregisterApp } from '../apps/lifecycle';
+import { registerLoadedBundle } from './register';
 /**
  * Install a package from raw bundle bytes and metadata.
  *
  * Loads the ESM module, verifies the declared type matches the actual module
- * shape, persists to IndexedDB, and registers with the framework. If
- * registration fails (e.g. duplicate id from a shard that was already
- * glob-discovered), the package is still persisted but `hotLoaded` is false.
+ * shape, persists to IndexedDB, evicts any existing registration for the same
+ * id, and registers with the framework via the shared helper. If registration
+ * fails (e.g. a shard that was already glob-discovered), the package is still
+ * persisted but `hotLoaded` is false.
  *
  * @param bundle - Raw verified ESM bundle bytes.
  * @param meta - Provenance metadata for the install record.
@@ -88,20 +91,27 @@ export async function installPackage(bundle, meta) {
             error: `Failed to persist package: ${err instanceof Error ? err.message : String(err)}`,
         };
     }
-    // 5. Stamp loader-assigned version (ADR-013) then register all shards
-    //    and apps from the bundle. External package authors omit `version`
-    //    from their source manifests; the authoritative value is the
-    //    registry entry's `PackageVersion.version`, carried on `meta.version`.
+    // 5. Evict any existing registration for this id before re-registering.
+    //    Without this, reinstall at the same version leaks activation state
+    //    (shards stay active) or app entries (apps silently replace but the
+    //    old module instance's module-scope state is never torn down).
+    if (meta.type === 'shard' || meta.type === 'combo') {
+        try {
+            deactivateShard(meta.id);
+        }
+        catch ( /* not active or not a shard */_a) { /* not active or not a shard */ }
+    }
+    if (meta.type === 'app' || meta.type === 'combo') {
+        unregisterApp(meta.id);
+    }
+    // 6. Register all shards and apps from the bundle via the shared helper.
     let hotLoaded = true;
     try {
-        for (const shard of loaded.shards) {
-            shard.manifest = Object.assign(Object.assign({}, shard.manifest), { version: meta.version });
-            registerShard(shard);
-        }
-        for (const app of loaded.apps) {
-            app.manifest = Object.assign(Object.assign({}, app.manifest), { version: meta.version });
-            registerApp(app);
-        }
+        registerLoadedBundle(loaded, {
+            version: meta.version,
+            sourceRegistry: meta.sourceRegistry,
+            contractVersion: meta.contractVersion,
+        });
     }
     catch (err) {
         console.warn(`[sh3] Package "${meta.id}" installed but registration failed (will retry on next boot):`, err instanceof Error ? err.message : err);
@@ -113,18 +123,17 @@ export async function installPackage(bundle, meta) {
  * Uninstall a package by id.
  *
  * If the package is a shard and currently active, deactivates it first.
- * Removes both the bundle and metadata from IndexedDB.
+ * Unregisters any app entry for the id, then removes both the bundle and
+ * metadata from IndexedDB.
  *
  * @param id - The package id to uninstall.
  */
 export async function uninstallPackage(id) {
-    // Attempt deactivation (no-op if not active or not a shard).
     try {
         deactivateShard(id);
     }
-    catch (_a) {
-        // Ignore -- may not be a shard, or may not be active.
-    }
+    catch ( /* no-op */_a) { /* no-op */ }
+    unregisterApp(id);
     await removePackage(id);
 }
 /**
@@ -160,16 +169,11 @@ export async function loadInstalledPackages() {
                 continue;
             }
             const loaded = await loadBundleModule(bytes);
-            // Stamp loader-assigned version (ADR-013) from the persisted
-            // InstalledPackage record before registration.
-            for (const shard of loaded.shards) {
-                shard.manifest = Object.assign(Object.assign({}, shard.manifest), { version: pkg.version });
-                registerShard(shard);
-            }
-            for (const app of loaded.apps) {
-                app.manifest = Object.assign(Object.assign({}, app.manifest), { version: pkg.version });
-                registerApp(app);
-            }
+            registerLoadedBundle(loaded, {
+                version: pkg.version,
+                sourceRegistry: pkg.sourceRegistry,
+                contractVersion: pkg.contractVersion,
+            });
             if (loaded.shards.length === 0 && loaded.apps.length === 0) {
                 console.warn(`[sh3] Package "${pkg.id}" contains no valid shards or apps, skipping`);
             }

package/dist/registry/register.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Unified bundle registration — stamps loader-assigned metadata onto every
+ * shard/app manifest from a loaded bundle, then registers each. Shared by
+ * `installer.installPackage`, `installer.loadInstalledPackages`, and
+ * `createShell` discoveredPackages so the three boot paths stay in sync.
+ *
+ * Per ADR-013, external package authors omit `version` from their source
+ * manifests; the authoritative value comes from the persisted/server
+ * metadata and must be stamped here before any consumer reads the manifest.
+ */
+import type { LoadedBundle } from './loader';
+export interface BundleStampMeta {
+    version: string;
+    sourceRegistry: string;
+    contractVersion: string;
+}
+export declare function registerLoadedBundle(loaded: LoadedBundle, meta: BundleStampMeta): void;

package/dist/registry/register.js

@@ -0,0 +1,22 @@
+/**
+ * Unified bundle registration — stamps loader-assigned metadata onto every
+ * shard/app manifest from a loaded bundle, then registers each. Shared by
+ * `installer.installPackage`, `installer.loadInstalledPackages`, and
+ * `createShell` discoveredPackages so the three boot paths stay in sync.
+ *
+ * Per ADR-013, external package authors omit `version` from their source
+ * manifests; the authoritative value comes from the persisted/server
+ * metadata and must be stamped here before any consumer reads the manifest.
+ */
+import { registerShard } from '../shards/activate.svelte';
+import { registerApp } from '../apps/registry.svelte';
+export function registerLoadedBundle(loaded, meta) {
+    for (const shard of loaded.shards) {
+        shard.manifest = Object.assign(Object.assign({}, shard.manifest), { version: meta.version });
+        registerShard(shard);
+    }
+    for (const app of loaded.apps) {
+        app.manifest = Object.assign(Object.assign({}, app.manifest), { version: meta.version });
+        registerApp(app);
+    }
+}

package/dist/registry/register.test.d.ts

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

package/dist/registry/register.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { resetFramework } from '../__test__/reset';
+import { makeApp, makeAppManifest, makeShard, makeShardManifest } from '../__test__/fixtures';
+import { registerLoadedBundle } from './register';
+import { registeredApps } from '../apps/registry.svelte';
+import { registeredShards } from '../shards/activate.svelte';
+describe('registerLoadedBundle', () => {
+    beforeEach(resetFramework);
+    it('stamps meta.version onto every shard manifest before registering', () => {
+        var _a;
+        const shard = makeShard({ manifest: makeShardManifest({ id: 'shard-1', version: '' }) });
+        registerLoadedBundle({ shards: [shard], apps: [] }, { version: '2.3.4', sourceRegistry: 'https://r', contractVersion: '1' });
+        expect((_a = registeredShards.get('shard-1')) === null || _a === void 0 ? void 0 : _a.manifest.version).toBe('2.3.4');
+    });
+    it('stamps meta.version onto every app manifest before registering', () => {
+        var _a;
+        const app = makeApp({ manifest: makeAppManifest({ id: 'app-1', version: '' }) });
+        registerLoadedBundle({ shards: [], apps: [app] }, { version: '2.3.4', sourceRegistry: 'https://r', contractVersion: '1' });
+        expect((_a = registeredApps.get('app-1')) === null || _a === void 0 ? void 0 : _a.manifest.version).toBe('2.3.4');
+    });
+    it('registers combo bundles (both shards and apps)', () => {
+        const shard = makeShard({ manifest: makeShardManifest({ id: 'combo-s' }) });
+        const app = makeApp({ manifest: makeAppManifest({ id: 'combo-a', requiredShards: ['combo-s'] }) });
+        registerLoadedBundle({ shards: [shard], apps: [app] }, { version: '1.0.0', sourceRegistry: '', contractVersion: '1' });
+        expect(registeredShards.has('combo-s')).toBe(true);
+        expect(registeredApps.has('combo-a')).toBe(true);
+    });
+});

package/dist/shards/activate.svelte.d.ts

@@ -50,3 +50,9 @@ export declare function isActive(id: string): boolean;
  * Used by lifecycle.ts to pass context to `shard.resume()`.
  */
 export declare function getShardContext(id: string): ShardContext | undefined;
+/**
+ * Test-only reset. Tears down any active shard entries (without running
+ * deactivate hooks — tests should run deactivate explicitly if they care)
+ * and clears both registered and active maps.
+ */
+export declare function __resetShardRegistryForTest(): void;

package/dist/shards/activate.svelte.js

@@ -23,6 +23,9 @@ import { fetchEnvState, putEnvState } from '../env/client';
 import { isAdmin as checkIsAdmin } from '../auth/index';
 import { createZoneManager } from '../state/manage';
 import { PERMISSION_STATE_MANAGE } from '../state/types';
+import { PERMISSION_DOCUMENTS_SYNC } from '../documents/sync/types';
+import { getSyncBundle } from '../documents/sync/singleton';
+import { createSyncHandle } from '../documents/sync/handle';
 /**
  * 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
@@ -65,7 +68,7 @@ export function registerShard(shard) {
  * @throws If the shard is not registered, or if a manifest view has no factory after activation.
  */
 export async function activateShard(id) {
-    var _a, _b;
+    var _a, _b, _c;
     const shard = registeredShards.get(id);
     if (!shard) {
         throw new Error(`Cannot activate shard "${id}": not registered`);
@@ -128,6 +131,24 @@ export async function activateShard(id) {
         zones: ((_a = shard.manifest.permissions) === null || _a === void 0 ? void 0 : _a.includes(PERMISSION_STATE_MANAGE))
             ? createZoneManager()
             : undefined,
+        sync: ((_b = shard.manifest.permissions) === null || _b === void 0 ? void 0 : _b.includes(PERMISSION_DOCUMENTS_SYNC))
+            ? () => {
+                const backend = getDocumentBackend();
+                const tenantId = getTenantId();
+                const bundlePromise = getSyncBundle(backend, tenantId);
+                const handlePromise = bundlePromise.then(({ engine, registry }) => createSyncHandle({ tenantId, connectorId: id, engine, registry }));
+                return {
+                    connectorId: id,
+                    grantedScopes: async () => (await handlePromise).grantedScopes(),
+                    getManifest: async (scope) => (await handlePromise).getManifest(scope),
+                    changesSince: async (scope, cursor) => (await handlePromise).changesSince(scope, cursor),
+                    ack: async (scope, cursor) => (await handlePromise).ack(scope, cursor),
+                    apply: async (scope, entry, opts) => (await handlePromise).apply(scope, entry, opts),
+                    applyBatch: async (scope, manifest, opts) => (await handlePromise).applyBatch(scope, manifest, opts),
+                    forget: async (scope, path) => (await handlePromise).forget(scope, path),
+                };
+            }
+            : undefined,
     };
     entry.ctx = ctx;
     active.set(id, entry);
@@ -149,7 +170,7 @@ export async function activateShard(id) {
             console.warn(`[sh3] Failed to hydrate env state for shard "${id}":`, err instanceof Error ? err.message : err);
         }
     }
-    void ((_b = shard.autostart) === null || _b === void 0 ? void 0 : _b.call(shard, ctx));
+    void ((_c = shard.autostart) === null || _c === void 0 ? void 0 : _c.call(shard, ctx));
 }
 /**
  * Deactivate an active shard. Calls `shard.deactivate`, flushes and disposes
@@ -191,3 +212,13 @@ export function getShardContext(id) {
     var _a;
     return (_a = active.get(id)) === null || _a === void 0 ? void 0 : _a.ctx;
 }
+/**
+ * Test-only reset. Tears down any active shard entries (without running
+ * deactivate hooks — tests should run deactivate explicitly if they care)
+ * and clears both registered and active maps.
+ */
+export function __resetShardRegistryForTest() {
+    active.clear();
+    activeShards.clear();
+    registeredShards.clear();
+}

package/dist/shards/registry.d.ts

@@ -1,4 +1,6 @@
 import type { ViewFactory } from './types';
+export declare function __addViewRegistrationListener(fn: (viewId: string, factory: ViewFactory) => void): void;
+export declare function __removeViewRegistrationListener(fn: (viewId: string, factory: ViewFactory) => void): void;
 export declare function registerView(viewId: string, factory: ViewFactory): void;
 export declare function getView(viewId: string): ViewFactory | undefined;
 export declare function unregisterView(viewId: string): void;
@@ -7,3 +9,5 @@ export declare function registerVerb(name: string, verb: Verb): void;
 export declare function getVerb(name: string): Verb | undefined;
 export declare function unregisterVerb(name: string): void;
 export declare function listVerbs(): Verb[];
+/** Test-only reset: clear the view and verb registries. */
+export declare function __resetViewRegistryForTest(): void;

package/dist/shards/registry.js

@@ -14,11 +14,22 @@
  *     hotkeys get their own sibling maps when those kinds land.
  */
 const views = new Map();
+/** Listeners called after a new view factory is registered. */
+const viewRegistrationListeners = new Set();
+export function __addViewRegistrationListener(fn) {
+    viewRegistrationListeners.add(fn);
+}
+export function __removeViewRegistrationListener(fn) {
+    viewRegistrationListeners.delete(fn);
+}
 export function registerView(viewId, factory) {
     if (views.has(viewId)) {
         throw new Error(`View "${viewId}" is already registered`);
     }
     views.set(viewId, factory);
+    for (const listener of viewRegistrationListeners) {
+        listener(viewId, factory);
+    }
 }
 export function getView(viewId) {
     return views.get(viewId);
@@ -42,3 +53,10 @@ export function unregisterVerb(name) {
 export function listVerbs() {
     return Array.from(verbs.values()).sort((a, b) => a.name.localeCompare(b.name));
 }
+/** Test-only reset: clear the view and verb registries. */
+export function __resetViewRegistryForTest() {
+    views.clear();
+    verbs.clear();
+    // Do NOT clear viewRegistrationListeners — they are module-level subscriptions
+    // (e.g. slotHostPool's late-factory listener) that must survive registry resets.
+}

package/dist/shards/types.d.ts

@@ -1,6 +1,7 @@
 import type { StateZones } from '../state/zones.svelte';
 import type { ZoneSchema, ZoneManager } from '../state/types';
 import type { DocumentHandle, DocumentHandleOptions } from '../documents/types';
+import type { SyncHandle } from '../documents/sync/types';
 import type { EnvState } from '../env/types';
 import type { Verb } from '../verbs/types';
 /**
@@ -43,6 +44,12 @@ export interface MountContext {
     viewId: string;
     /** Initial label for the tab; may be updated by the view via future API. */
     label: string;
+    /**
+     * Caller-supplied instance data. Present when the mount was triggered with
+     * metadata (e.g. `shell.float.open(viewId, { meta: { ... } })`).
+     * Not persisted with the layout — ephemeral per mount.
+     */
+    meta?: Record<string, unknown>;
     /**
      * Push dirty-state to the tab strip. The framework renders a dirty
      * indicator (filled dot) on the tab when true, clears it when false.
@@ -110,7 +117,9 @@ export interface ShardManifest {
     /**
      * Optional permissions this shard requests beyond the default sandbox.
      * Declared in the manifest and surfaced to the user at install time.
-     * Currently recognized: `'state:manage'` — cross-shard zone access.
+     * Currently recognized:
+     *   - 'state:manage' — cross-shard zone access.
+     *   - 'documents:sync' — cross-shard document sync API.
      */
     permissions?: string[];
 }
@@ -185,6 +194,12 @@ export interface ShardContext {
      * `if (ctx.zones)` before use.
      */
     zones?: ZoneManager;
+    /**
+     * Cross-shard document sync API. Only present when the shard's
+     * manifest declares the `'documents:sync'` permission. Check with
+     * `if (ctx.sync)` before use.
+     */
+    sync?: () => SyncHandle;
 }
 /**
  * A shard module. Shards are the fundamental unit of contribution in SH3.

package/dist/shell-shard/Terminal.svelte

@@ -6,55 +6,149 @@
   import { SessionClient } from './session-client.svelte';
   import { VerbRegistry, type ShellApi } from './registry';
   import type { ServerMessage } from './protocol';
+  import { TenantFsClient } from './tenant-fs-client';
+  import { ShellModeRegistry } from './modes/registry';
+  import { registerBuiltinModes } from './modes/builtin';
+  import { resolveInitialMode, writeLastMode } from './modes/prefs';
+  import type { ShellMode, ShellRole } from './modes/types';
+  import { makeDispatch } from './dispatch';
+  import { computeRelocate } from './auto-relocate';
+  import { activeLayout } from '../layout/store.svelte';
+  import type { LayoutNode } from '../layout/types';
+  import Toolbar from './toolbar/Toolbar.svelte';
+  import { ToolbarSlotRegistry } from './toolbar/slots';
+  import ModeSlot from './toolbar/slots/ModeSlot.svelte';
+  import FocusLockSlot from './toolbar/slots/FocusLockSlot.svelte';
+  import TargetShardSlot from './toolbar/slots/TargetShardSlot.svelte';
 
   interface Props {
     shell: ShellApi;
     wsUrl: string;
+    userId: string;
+    role: ShellRole;
   }
-  let { shell, wsUrl }: Props = $props();
+  let { shell, wsUrl, userId, role }: Props = $props();
 
   const scrollback = new Scrollback();
+  const resolver = new VerbRegistry();
+  const fs = new TenantFsClient();
+
+  // Mode registry
+  const modeRegistry = new ShellModeRegistry();
+  registerBuiltinModes(modeRegistry);
+
+  // Reactive current mode
+  let mode = $state<ShellMode>(
+    untrack(() => resolveInitialMode(modeRegistry, userId, role)),
+  );
+
+  function setMode(id: string): void {
+    const next = modeRegistry.get(id);
+    if (!next) return;
+    if (next.requiresRole && next.requiresRole !== role) return;
+    mode = next;
+    writeLastMode(userId, id);
+    if (next.transport !== 'ws') {
+      scrollback.push({ kind: 'status', text: 'mode switch: reload to take effect for server-shell changes', level: 'info', ts: Date.now() });
+    }
+  }
+
   // wsUrl is a prop read at construction only. untrack prevents Svelte 5's
   // "referenced outside a closure" warning; the URL never changes at runtime.
   const session = untrack(() => new SessionClient(wsUrl));
-  const resolver = new VerbRegistry();
+
+  const dispatch = untrack(() => makeDispatch({
+    mode: () => mode,
+    resolver,
+    scrollback,
+    session,
+    shell,
+    fs,
+    cwd: () => session.cwd,
+  }));
 
   let locked = $state(false);
 
-  async function dispatch(line: string): Promise<void> {
-    session.history.push(line);
-    const resolution = resolver.resolve(line);
-    if (resolution.kind === 'local') {
-      // Log locally-dispatched verbs for shared history
-      session.send({ t: 'history-log', line });
-      scrollback.push({
-        kind: 'prompt',
-        cwd: session.cwd,
-        line,
-        ts: Date.now(),
-      });
-      try {
-        await resolution.verb.run({
-          shell,
-          scrollback,
-          session,
-          cwd: session.cwd,
-          dispatch,
-        }, resolution.args);
-      } catch (err) {
-        scrollback.push({
-          kind: 'status',
-          text: `shell: verb ${resolution.verb.name} threw — ${(err as Error).message}`,
-          level: 'error',
-          ts: Date.now(),
-        });
+  // ---------------------------------------------------------------------------
+  // Auto-relocate: track the focused shard and update session.cwd when focus
+  // changes to a shard whose documents directory exists. focusLocked and
+  // targetShard are read by Task 13's toolbar component via props.
+  // ---------------------------------------------------------------------------
+
+  let focusLocked = $state(false);
+  let targetShard = $state<string | null>(null);
+
+  function toggleFocusLock(): void {
+    focusLocked = !focusLocked;
+  }
+
+  // Toolbar slot registry
+  const toolbarRegistry = new ToolbarSlotRegistry();
+  toolbarRegistry.register({ id: 'mode', order: 10, visible: () => true, component: ModeSlot });
+  toolbarRegistry.register({ id: 'focus-lock', order: 20, visible: (ctx) => ctx.mode.id === 'user', component: FocusLockSlot });
+  toolbarRegistry.register({ id: 'target-shard', order: 30, visible: (ctx) => ctx.mode.id === 'user', component: TargetShardSlot });
+
+  let toolbarExpanded = $state((() => {
+    try { return localStorage.getItem('sh3.shell.toolbarExpanded') !== '0'; } catch { return true; }
+  })());
+
+  function toggleToolbar() {
+    toolbarExpanded = !toolbarExpanded;
+    try { localStorage.setItem('sh3.shell.toolbarExpanded', toolbarExpanded ? '1' : '0'); } catch {}
+  }
+
+  /** Walk the layout tree and return the viewId of the active tab in the first
+   *  TabsNode found (breadth-first). Returns null if the layout contains no
+   *  tabs node with a populated active tab. */
+  function getActiveViewId(node: LayoutNode): string | null {
+    if (node.type === 'tabs') {
+      const entry = node.tabs[node.activeTab];
+      return entry?.viewId ?? null;
+    }
+    if (node.type === 'split') {
+      for (const child of node.children) {
+        const found = getActiveViewId(child);
+        if (found !== null) return found;
       }
-    } else {
-      // Forward to server
-      session.send({ t: 'submit', line: resolution.line });
     }
+    // slot node
+    return node.viewId ?? null;
   }
 
+  /** Derive the focused shard id from the currently-active layout. The shard
+   *  id is the prefix before the first ':' in a viewId (e.g. 'shell:terminal'
+   *  → 'shell'). Returns null when no view is active. */
+  function getFocusedShardId(): string | null {
+    try {
+      const tree = activeLayout();
+      const viewId = getActiveViewId(tree.docked);
+      if (!viewId) return null;
+      const colon = viewId.indexOf(':');
+      return colon >= 0 ? viewId.slice(0, colon) : viewId;
+    } catch {
+      return null;
+    }
+  }
+
+  $effect(() => {
+    const focused = getFocusedShardId();
+    const autoRelocate = mode.autoRelocate;
+    const isFocusLocked = focusLocked;
+    (async () => {
+      const r = await computeRelocate({
+        modeAutoRelocate: autoRelocate,
+        focusLocked: isFocusLocked,
+        focusedShardId: focused,
+        currentShardId: 'shell',
+      }, fs);
+      if (r.kind === 'relocate' && r.path !== undefined) {
+        session.cwd = r.path;
+      }
+      if (focused && focused !== 'shell') targetShard = focused;
+      else if (!focused) targetShard = null;
+    })();
+  });
+
   function handleServerMessage(msg: ServerMessage) {
     if (msg.t !== 'event') return;
     const e = msg.event;
@@ -96,7 +190,9 @@
 
   onMount(() => {
     unsub = session.onMessage(handleServerMessage);
-    session.connect();
+    if (mode.transport === 'ws') {
+      session.connect();
+    }
   });
 
   onDestroy(() => {
@@ -106,6 +202,17 @@
 </script>
 
 <div class="shell-terminal">
+  <Toolbar
+    registry={toolbarRegistry}
+    ctx={{ mode, role }}
+    expanded={toolbarExpanded}
+    onToggle={toggleToolbar}
+    slotProps={{
+      mode: { mode, role, registry: modeRegistry, onSelect: setMode },
+      'focus-lock': { locked: focusLocked, onToggle: () => (focusLocked = !focusLocked) },
+      'target-shard': { target: targetShard },
+    }}
+  />
   <ScrollbackView {scrollback} />
   <InputLine
     cwd={session.cwd}