sh3-core 0.7.5 → 0.8.0

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.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

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';
 /**
@@ -116,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[];
 }
@@ -191,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}

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

@@ -1,7 +1,10 @@
 import { type ShellApi } from './registry';
+import type { ShellRole } from './modes/types';
 interface Props {
     shell: ShellApi;
     wsUrl: string;
+    userId: string;
+    role: ShellRole;
 }
 declare const Terminal: import("svelte").Component<Props, {}, "">;
 type Terminal = ReturnType<typeof Terminal>;

package/dist/shell-shard/auto-relocate.d.ts

@@ -0,0 +1,12 @@
+import type { TenantFsClient } from './tenant-fs-client';
+export interface RelocateInput {
+    modeAutoRelocate: boolean;
+    focusLocked: boolean;
+    focusedShardId: string | null;
+    currentShardId: string;
+}
+export interface RelocateEffect {
+    kind: 'noop' | 'relocate';
+    path?: string;
+}
+export declare function computeRelocate(input: RelocateInput, fs: TenantFsClient): Promise<RelocateEffect>;

package/dist/shell-shard/auto-relocate.js

@@ -0,0 +1,20 @@
+export async function computeRelocate(input, fs) {
+    if (!input.modeAutoRelocate)
+        return { kind: 'noop' };
+    if (input.focusLocked)
+        return { kind: 'noop' };
+    if (input.focusedShardId === null)
+        return { kind: 'noop' };
+    if (input.focusedShardId === input.currentShardId)
+        return { kind: 'noop' };
+    const path = input.focusedShardId;
+    try {
+        const s = await fs.stat(path);
+        if (s.kind !== 'dir')
+            return { kind: 'noop' };
+    }
+    catch (_a) {
+        return { kind: 'noop' };
+    }
+    return { kind: 'relocate', path };
+}

package/dist/shell-shard/auto-relocate.test.d.ts

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

package/dist/shell-shard/auto-relocate.test.js

@@ -0,0 +1,35 @@
+import { describe, it, expect, vi } from 'vitest';
+import { computeRelocate } from './auto-relocate';
+const statOk = { list: vi.fn(), read: vi.fn(), stat: async () => ({ name: 'notes', kind: 'dir', size: 0, mtime: 0 }) };
+const statMissing = { list: vi.fn(), read: vi.fn(), stat: async () => { throw new Error('not found'); } };
+const statFile = { list: vi.fn(), read: vi.fn(), stat: async () => ({ name: 'notes', kind: 'file', size: 0, mtime: 0 }) };
+describe('computeRelocate', () => {
+    it('noop when mode disables auto-relocate', async () => {
+        const r = await computeRelocate({ modeAutoRelocate: false, focusLocked: false, focusedShardId: 'notes', currentShardId: 'shell' }, statOk);
+        expect(r.kind).toBe('noop');
+    });
+    it('noop when focus-lock is on', async () => {
+        const r = await computeRelocate({ modeAutoRelocate: true, focusLocked: true, focusedShardId: 'notes', currentShardId: 'shell' }, statOk);
+        expect(r.kind).toBe('noop');
+    });
+    it('noop when nothing relevant is focused', async () => {
+        const r = await computeRelocate({ modeAutoRelocate: true, focusLocked: false, focusedShardId: null, currentShardId: 'shell' }, statOk);
+        expect(r.kind).toBe('noop');
+    });
+    it('noop when focusing the shell itself', async () => {
+        const r = await computeRelocate({ modeAutoRelocate: true, focusLocked: false, focusedShardId: 'shell', currentShardId: 'shell' }, statOk);
+        expect(r.kind).toBe('noop');
+    });
+    it('noop when target documents folder does not exist', async () => {
+        const r = await computeRelocate({ modeAutoRelocate: true, focusLocked: false, focusedShardId: 'notes', currentShardId: 'shell' }, statMissing);
+        expect(r.kind).toBe('noop');
+    });
+    it('noop when target is a file, not a directory', async () => {
+        const r = await computeRelocate({ modeAutoRelocate: true, focusLocked: false, focusedShardId: 'notes', currentShardId: 'shell' }, statFile);
+        expect(r.kind).toBe('noop');
+    });
+    it('relocates to the shard id path on happy path', async () => {
+        const r = await computeRelocate({ modeAutoRelocate: true, focusLocked: false, focusedShardId: 'notes', currentShardId: 'shell' }, statOk);
+        expect(r).toEqual({ kind: 'relocate', path: 'notes' });
+    });
+});

package/dist/shell-shard/dispatch.d.ts

@@ -0,0 +1,15 @@
+import type { VerbRegistry, ShellApi } from './registry';
+import type { Scrollback } from './scrollback.svelte';
+import type { SessionClient } from './session-client.svelte';
+import type { TenantFsClient } from './tenant-fs-client';
+import type { ShellMode } from './modes/types';
+export interface DispatchDeps {
+    mode: () => ShellMode;
+    resolver: VerbRegistry;
+    scrollback: Scrollback;
+    session: SessionClient;
+    shell: ShellApi;
+    fs: TenantFsClient;
+    cwd: () => string;
+}
+export declare function makeDispatch(deps: DispatchDeps): (line: string) => Promise<void>;

package/dist/shell-shard/dispatch.js

@@ -0,0 +1,56 @@
+/*
+ * makeDispatch — mode-aware verb dispatch factory for Terminal.svelte.
+ *
+ * Pure function (no Svelte reactivity) so it can be unit-tested independently.
+ * The mode is passed as a getter so the dispatch closure always sees the
+ * current mode without being reconstructed on every mode change.
+ */
+export function makeDispatch(deps) {
+    return async function dispatch(line) {
+        var _a;
+        const mode = deps.mode();
+        deps.session.history.push(line);
+        // User-mode $ escape: block server-shell access
+        if (mode.transport === 'none' && line.trimStart().startsWith('$ ')) {
+            deps.scrollback.push({ kind: 'prompt', cwd: deps.cwd(), line, ts: Date.now() });
+            deps.scrollback.push({ kind: 'status', text: 'shell: server shell not available in user mode', level: 'error', ts: Date.now() });
+            return;
+        }
+        const resolution = deps.resolver.resolve(line);
+        if (resolution.kind === 'local') {
+            // Log locally-dispatched verbs for shared history (ws only)
+            if (mode.transport === 'ws') {
+                deps.session.send({ t: 'history-log', line });
+            }
+            deps.scrollback.push({ kind: 'prompt', cwd: deps.cwd(), line, ts: Date.now() });
+            try {
+                await resolution.verb.run({
+                    shell: deps.shell,
+                    scrollback: deps.scrollback,
+                    session: deps.session,
+                    cwd: deps.cwd(),
+                    dispatch,
+                    fs: deps.fs,
+                }, resolution.args);
+            }
+            catch (err) {
+                deps.scrollback.push({
+                    kind: 'status',
+                    text: `shell: verb ${resolution.verb.name} threw — ${err.message}`,
+                    level: 'error',
+                    ts: Date.now(),
+                });
+            }
+            return;
+        }
+        // forward path
+        if (mode.transport === 'ws') {
+            deps.session.send({ t: 'submit', line: resolution.line });
+        }
+        else {
+            const firstToken = (_a = resolution.line.split(/\s+/)[0]) !== null && _a !== void 0 ? _a : '';
+            deps.scrollback.push({ kind: 'prompt', cwd: deps.cwd(), line: resolution.line, ts: Date.now() });
+            deps.scrollback.push({ kind: 'status', text: `unknown verb: ${firstToken}`, level: 'error', ts: Date.now() });
+        }
+    };
+}

package/dist/shell-shard/modes/builtin.d.ts

@@ -0,0 +1,5 @@
+import { ShellModeRegistry } from './registry';
+import type { ShellMode } from './types';
+export declare const DEV_MODE: ShellMode;
+export declare const USER_MODE: ShellMode;
+export declare function registerBuiltinModes(reg: ShellModeRegistry): void;

package/dist/shell-shard/modes/builtin.js

@@ -0,0 +1,18 @@
+import { ShellModeRegistry } from './registry';
+export const DEV_MODE = {
+    id: 'dev',
+    label: 'Dev',
+    requiresRole: 'admin',
+    transport: 'ws',
+    autoRelocate: false,
+};
+export const USER_MODE = {
+    id: 'user',
+    label: 'User',
+    transport: 'none',
+    autoRelocate: true,
+};
+export function registerBuiltinModes(reg) {
+    reg.register(DEV_MODE);
+    reg.register(USER_MODE);
+}

package/dist/shell-shard/modes/prefs.d.ts

@@ -0,0 +1,5 @@
+import type { ShellMode, ShellRole } from './types';
+import type { ShellModeRegistry } from './registry';
+export declare function readLastMode(userId: string): string | null;
+export declare function writeLastMode(userId: string, modeId: string): void;
+export declare function resolveInitialMode(reg: ShellModeRegistry, userId: string, role: ShellRole): ShellMode;

package/dist/shell-shard/modes/prefs.js

@@ -0,0 +1,31 @@
+function key(userId) {
+    return `sh3.shell.lastMode.${userId}`;
+}
+export function readLastMode(userId) {
+    var _a, _b;
+    try {
+        return (_b = (_a = globalThis.localStorage) === null || _a === void 0 ? void 0 : _a.getItem(key(userId))) !== null && _b !== void 0 ? _b : null;
+    }
+    catch (_c) {
+        return null;
+    }
+}
+export function writeLastMode(userId, modeId) {
+    var _a;
+    try {
+        (_a = globalThis.localStorage) === null || _a === void 0 ? void 0 : _a.setItem(key(userId), modeId);
+    }
+    catch (_b) {
+        // Non-browser host or storage disabled — persistence is best-effort.
+    }
+}
+export function resolveInitialMode(reg, userId, role) {
+    const persisted = readLastMode(userId);
+    if (persisted) {
+        const m = reg.get(persisted);
+        if (m && (!m.requiresRole || m.requiresRole === role))
+            return m;
+    }
+    const fallback = role === 'admin' ? 'dev' : 'user';
+    return reg.get(fallback);
+}

package/dist/shell-shard/modes/prefs.test.d.ts

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

package/dist/shell-shard/modes/prefs.test.js

@@ -0,0 +1,46 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { readLastMode, writeLastMode, resolveInitialMode } from './prefs';
+import { ShellModeRegistry } from './registry';
+import { registerBuiltinModes } from './builtin';
+class MemStorage {
+    constructor() {
+        this.m = new Map();
+    }
+    getItem(k) { var _a; return (_a = this.m.get(k)) !== null && _a !== void 0 ? _a : null; }
+    setItem(k, v) { this.m.set(k, v); }
+    removeItem(k) { this.m.delete(k); }
+}
+beforeEach(() => {
+    globalThis.localStorage = new MemStorage();
+});
+describe('readLastMode / writeLastMode', () => {
+    it('round-trips a mode id for a user', () => {
+        writeLastMode('alice', 'user');
+        expect(readLastMode('alice')).toBe('user');
+    });
+    it('returns null when nothing persisted', () => {
+        expect(readLastMode('bob')).toBeNull();
+    });
+});
+describe('resolveInitialMode', () => {
+    const reg = new ShellModeRegistry();
+    registerBuiltinModes(reg);
+    it('admin with no pref → dev', () => {
+        expect(resolveInitialMode(reg, 'alice', 'admin').id).toBe('dev');
+    });
+    it('user with no pref → user', () => {
+        expect(resolveInitialMode(reg, 'alice', 'user').id).toBe('user');
+    });
+    it('admin with persisted user → user', () => {
+        writeLastMode('alice', 'user');
+        expect(resolveInitialMode(reg, 'alice', 'admin').id).toBe('user');
+    });
+    it('user with persisted dev (not allowed) → falls back to user', () => {
+        writeLastMode('alice', 'dev');
+        expect(resolveInitialMode(reg, 'alice', 'user').id).toBe('user');
+    });
+    it('persisted unknown id → role default', () => {
+        writeLastMode('alice', 'nonsense');
+        expect(resolveInitialMode(reg, 'alice', 'admin').id).toBe('dev');
+    });
+});

package/dist/shell-shard/modes/registry.d.ts

@@ -0,0 +1,7 @@
+import type { ShellMode, ShellRole } from './types';
+export declare class ShellModeRegistry {
+    #private;
+    register(mode: ShellMode): void;
+    get(id: string): ShellMode | undefined;
+    list(role: ShellRole): ShellMode[];
+}

package/dist/shell-shard/modes/registry.js

@@ -0,0 +1,27 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _ShellModeRegistry_modes;
+export class ShellModeRegistry {
+    constructor() {
+        _ShellModeRegistry_modes.set(this, new Map());
+    }
+    register(mode) {
+        __classPrivateFieldGet(this, _ShellModeRegistry_modes, "f").set(mode.id, mode);
+    }
+    get(id) {
+        return __classPrivateFieldGet(this, _ShellModeRegistry_modes, "f").get(id);
+    }
+    list(role) {
+        const out = [];
+        for (const m of __classPrivateFieldGet(this, _ShellModeRegistry_modes, "f").values()) {
+            if (m.requiresRole && m.requiresRole !== role)
+                continue;
+            out.push(m);
+        }
+        return out;
+    }
+}
+_ShellModeRegistry_modes = new WeakMap();

package/dist/shell-shard/modes/registry.test.d.ts

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