sh3-core 0.15.0 → 0.15.2

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

@@ -1,7 +1,7 @@
 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 { ModeBuffer } from './mode-buffer.svelte';
 import type { ShellMode, ShellRole } from './modes/types';
 import type { ShellModeDescriptor } from './contract';
 export interface DispatchDeps {
@@ -9,7 +9,12 @@ export interface DispatchDeps {
     /** Current shell role — used by invoke() role-gating. */
     role: () => ShellRole;
     resolver: VerbRegistry;
-    scrollback: Scrollback;
+    /**
+     * Active-mode buffer getter. Returns the ModeBuffer for the current
+     * mode id; reads its `scrollback` and `history` to fold dispatched
+     * activity into per-mode state.
+     */
+    buffer: () => ModeBuffer;
     session: SessionClient;
     shell: ShellApi;
     fs: TenantFsClient;

package/dist/shell-shard/dispatch.js

@@ -20,7 +20,6 @@ export function makeDispatch(deps) {
      * because the caller is a trusted mode shard, not user input from a
      * different mode.
      */
-    let bashConnected = false;
     async function invoke(modeId, line) {
         var _a, _b, _c, _d;
         const current = deps.mode();
@@ -35,7 +34,7 @@ export function makeDispatch(deps) {
             }
             await resolution.verb.run({
                 shell: deps.shell,
-                scrollback: deps.scrollback,
+                scrollback: deps.buffer().scrollback,
                 session: deps.session,
                 cwd: deps.cwd(),
                 dispatch,
@@ -47,11 +46,7 @@ export function makeDispatch(deps) {
             if (deps.role() !== 'admin') {
                 throw new Error("invoke: 'bash' requires admin role");
             }
-            if (!bashConnected) {
-                bashConnected = true;
-                deps.session.connect();
-            }
-            deps.session.send({ t: 'submit', line });
+            deps.session.send({ t: 'submit', line, mode: 'bash' });
             return;
         }
         // Custom mode
@@ -66,7 +61,7 @@ export function makeDispatch(deps) {
             throw new Error('invoke: server-side modes are not yet supported');
         }
         const subOutput = makeShellModeOutput({
-            scrollback: deps.scrollback,
+            scrollback: deps.buffer().scrollback,
             busy: deps.busy,
             invoke,
         });
@@ -79,26 +74,27 @@ export function makeDispatch(deps) {
         const controller = new AbortController();
         activeController = controller;
         const mode = deps.mode();
-        deps.session.history.push(line);
+        deps.buffer().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() });
+            deps.buffer().scrollback.push({ kind: 'prompt', cwd: deps.cwd(), line, ts: Date.now() });
+            deps.buffer().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, {
             globalOnly: mode.id !== 'sh3',
         });
         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() });
+            // Log locally-dispatched verbs to the server's per-mode history.
+            // The session-client queues this message while disconnected and
+            // flushes on reconnect; sh3/custom modes don't depend on a live
+            // bash WS for history persistence.
+            deps.session.send({ t: 'history-log', line, mode: mode.id });
+            deps.buffer().scrollback.push({ kind: 'prompt', cwd: deps.cwd(), line, ts: Date.now() });
             try {
                 await resolution.verb.run({
                     shell: deps.shell,
-                    scrollback: deps.scrollback,
+                    scrollback: deps.buffer().scrollback,
                     session: deps.session,
                     cwd: deps.cwd(),
                     dispatch,
@@ -106,7 +102,7 @@ export function makeDispatch(deps) {
                 }, resolution.args);
             }
             catch (err) {
-                deps.scrollback.push({
+                deps.buffer().scrollback.push({
                     kind: 'status',
                     text: `shell: verb ${resolution.verb.name} threw — ${err.message}`,
                     level: 'error',
@@ -117,14 +113,14 @@ export function makeDispatch(deps) {
         }
         // forward path
         if (mode.transport === 'ws') {
-            deps.session.send({ t: 'submit', line: resolution.line });
+            deps.session.send({ t: 'submit', line: resolution.line, mode: mode.id });
             return;
         }
         if (mode.transport === 'custom') {
-            deps.scrollback.push({ kind: 'prompt', cwd: deps.cwd(), line: resolution.line, ts: Date.now() });
+            deps.buffer().scrollback.push({ kind: 'prompt', cwd: deps.cwd(), line: resolution.line, ts: Date.now() });
             const desc = (_b = (_a = deps.customMode) === null || _a === void 0 ? void 0 : _a.call(deps, mode.id)) !== null && _b !== void 0 ? _b : null;
             if (!desc) {
-                deps.scrollback.push({
+                deps.buffer().scrollback.push({
                     kind: 'status',
                     text: `mode '${mode.id}' is no longer available`,
                     level: 'error',
@@ -133,7 +129,7 @@ export function makeDispatch(deps) {
                 return;
             }
             if (desc.runsOn === 'server') {
-                deps.scrollback.push({
+                deps.buffer().scrollback.push({
                     kind: 'status',
                     text: 'server-side modes are not yet supported (planned for a future release)',
                     level: 'error',
@@ -142,7 +138,7 @@ export function makeDispatch(deps) {
                 return;
             }
             const output = makeShellModeOutput({
-                scrollback: deps.scrollback,
+                scrollback: deps.buffer().scrollback,
                 busy: deps.busy,
                 invoke,
             });
@@ -152,10 +148,10 @@ export function makeDispatch(deps) {
             }
             catch (err) {
                 if ((err === null || err === void 0 ? void 0 : err.name) === 'AbortError') {
-                    deps.scrollback.push({ kind: 'status', text: 'mode dispatch aborted', level: 'info', ts: Date.now() });
+                    deps.buffer().scrollback.push({ kind: 'status', text: 'mode dispatch aborted', level: 'info', ts: Date.now() });
                 }
                 else {
-                    deps.scrollback.push({
+                    deps.buffer().scrollback.push({
                         kind: 'status',
                         text: `mode '${mode.id}' threw — ${(_c = err === null || err === void 0 ? void 0 : err.message) !== null && _c !== void 0 ? _c : String(err)}`,
                         level: 'error',
@@ -170,8 +166,8 @@ export function makeDispatch(deps) {
         }
         // 'none' transport, unknown verb: print error
         const firstToken = (_d = resolution.line.split(/\s+/)[0]) !== null && _d !== void 0 ? _d : '';
-        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() });
+        deps.buffer().scrollback.push({ kind: 'prompt', cwd: deps.cwd(), line: resolution.line, ts: Date.now() });
+        deps.buffer().scrollback.push({ kind: 'status', text: `unknown verb: ${firstToken}`, level: 'error', ts: Date.now() });
     }
     return {
         dispatch,

package/dist/shell-shard/display-cwd.d.ts

@@ -0,0 +1 @@
+export declare function shortenCwd(cwd: string, tenantRoot: string): string;

package/dist/shell-shard/display-cwd.js

@@ -0,0 +1,27 @@
+/*
+ * shortenCwd — render a server cwd relative to the per-user tenant root.
+ *
+ * - Equal to tenant root → `~`
+ * - Inside tenant root  → `~/<rest>` (forward-slash separators)
+ * - Outside tenant root → cwd unchanged
+ *
+ * Boundary-aware: a tenant root of `/foo` does not match `/foobar`. Handles
+ * both POSIX (`/`) and Windows (`\`) path separators in the input; the
+ * resulting display path always uses forward slashes for readability.
+ */
+export function shortenCwd(cwd, tenantRoot) {
+    if (!cwd || !tenantRoot)
+        return cwd;
+    if (cwd === tenantRoot)
+        return '~';
+    // Boundary check: the next character after the tenant prefix must be a
+    // path separator; otherwise we'd shorten /foobar against /foo.
+    if (cwd.length > tenantRoot.length && cwd.startsWith(tenantRoot)) {
+        const next = cwd.charAt(tenantRoot.length);
+        if (next === '/' || next === '\\') {
+            const rest = cwd.slice(tenantRoot.length + 1).replace(/\\/g, '/');
+            return `~/${rest}`;
+        }
+    }
+    return cwd;
+}

package/dist/shell-shard/display-cwd.test.d.ts

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

package/dist/shell-shard/display-cwd.test.js

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { shortenCwd } from './display-cwd';
+describe('shortenCwd', () => {
+    it('returns ~ when cwd equals tenant root', () => {
+        expect(shortenCwd('/home/u/data/users/x/documents/shell', '/home/u/data/users/x/documents/shell')).toBe('~');
+    });
+    it('substitutes ~ for tenant-root prefix (POSIX)', () => {
+        expect(shortenCwd('/home/u/data/users/x/documents/shell/notes', '/home/u/data/users/x/documents/shell')).toBe('~/notes');
+    });
+    it('substitutes ~ for tenant-root prefix (Windows)', () => {
+        expect(shortenCwd('C:\\a\\b\\users\\x\\documents\\shell\\notes', 'C:\\a\\b\\users\\x\\documents\\shell')).toBe('~/notes');
+    });
+    it('normalizes Windows backslashes to forward slashes after the tilde', () => {
+        expect(shortenCwd('C:\\root\\a\\b\\c', 'C:\\root')).toBe('~/a/b/c');
+    });
+    it('returns the absolute cwd when outside the tenant root', () => {
+        expect(shortenCwd('/tmp', '/home/u/data/users/x/documents/shell')).toBe('/tmp');
+    });
+    it('does not match when cwd matches the tenant root prefix without a separator boundary', () => {
+        // tenant=/foo, cwd=/foobar → must NOT shorten to ~bar
+        expect(shortenCwd('/foobar', '/foo')).toBe('/foobar');
+    });
+    it('returns cwd unchanged when tenantRoot is empty', () => {
+        expect(shortenCwd('/some/path', '')).toBe('/some/path');
+    });
+    it('returns cwd unchanged when cwd is empty', () => {
+        expect(shortenCwd('', '/tenant')).toBe('');
+    });
+});

package/dist/shell-shard/entries/StatusEntry.svelte

@@ -15,6 +15,8 @@
     padding: 2px 8px;
     font-family: var(--shell-font-mono, monospace);
     font-style: italic;
+    white-space: pre-wrap;
+    word-break: break-word;
   }
   .shell-status.info { color: var(--shell-fg-muted, #888); }
   .shell-status.warn { color: var(--shell-fg-warn, #fc6); }

package/dist/shell-shard/manifest.js

@@ -1,4 +1,5 @@
 import { VERSION } from '../version';
+import { PERMISSION_STATE_MANAGE } from '../state/types';
 export const manifest = {
     id: 'shell',
     label: 'Shell',
@@ -8,5 +9,5 @@ export const manifest = {
     // and is statically mounted at sh3-server boot. The existing contract in
     // sh3-core/src/shards/types.ts documents that framework-shipped shards do
     // not use this field.
-    permissions: [],
+    permissions: [PERMISSION_STATE_MANAGE],
 };

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

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

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

@@ -0,0 +1,8 @@
+import { describe, it, expect } from 'vitest';
+import { manifest } from './manifest';
+import { PERMISSION_STATE_MANAGE } from '../state/types';
+describe('shell manifest', () => {
+    it('declares state:manage permission for cross-shard zone introspection', () => {
+        expect(manifest.permissions).toContain(PERMISSION_STATE_MANAGE);
+    });
+});

package/dist/shell-shard/mode-buffer.svelte.d.ts

@@ -0,0 +1,8 @@
+import { Scrollback } from './scrollback.svelte';
+export declare class ModeBuffer {
+    readonly modeId: string;
+    readonly scrollback: Scrollback;
+    history: string[];
+    locked: boolean;
+    constructor(modeId: string);
+}

package/dist/shell-shard/mode-buffer.svelte.js

@@ -0,0 +1,19 @@
+/*
+ * ModeBuffer — per-mode bundle of scrollback + history + locked flag.
+ *
+ * Owned by Terminal.svelte's Map<modeId, ModeBuffer>. Switching mode
+ * rebinds the visible buffer; each buffer remains in the map so the
+ * user can flip back without losing state.
+ *
+ * `locked` is bash-specific today (set true while a process runs).
+ * sh3 / custom modes leave it false.
+ */
+import { Scrollback } from './scrollback.svelte';
+export class ModeBuffer {
+    constructor(modeId) {
+        this.history = $state([]);
+        this.locked = $state(false);
+        this.modeId = modeId;
+        this.scrollback = new Scrollback();
+    }
+}

package/dist/shell-shard/mode-buffer.svelte.test.d.ts

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

package/dist/shell-shard/mode-buffer.svelte.test.js

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { ModeBuffer } from './mode-buffer.svelte';
+describe('ModeBuffer', () => {
+    it('constructs with empty scrollback and history', () => {
+        const buf = new ModeBuffer('sh3');
+        expect(buf.modeId).toBe('sh3');
+        expect(buf.scrollback.entries).toEqual([]);
+        expect(buf.history).toEqual([]);
+        expect(buf.locked).toBe(false);
+    });
+    it('history is independently mutable per buffer', () => {
+        const a = new ModeBuffer('a');
+        const b = new ModeBuffer('b');
+        a.history.push('one');
+        expect(a.history).toEqual(['one']);
+        expect(b.history).toEqual([]);
+    });
+    it('locked flag is independently mutable per buffer', () => {
+        const a = new ModeBuffer('a');
+        const b = new ModeBuffer('b');
+        a.locked = true;
+        expect(a.locked).toBe(true);
+        expect(b.locked).toBe(false);
+    });
+});

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

@@ -5,12 +5,14 @@ export const BASH_MODE = {
     requiresRole: 'admin',
     transport: 'ws',
     autoRelocate: false,
+    showCwd: true,
 };
 export const SH3_MODE = {
     id: 'sh3',
     label: 'SH3',
     transport: 'none',
     autoRelocate: true,
+    showCwd: false,
 };
 export function registerBuiltinModes(reg) {
     reg.register(BASH_MODE);

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

@@ -5,4 +5,12 @@ export interface ShellMode {
     requiresRole?: 'admin';
     transport: 'ws' | 'none' | 'custom';
     autoRelocate: boolean;
+    /**
+     * Whether the input prompt should display the current working directory.
+     * Builtin shell modes (sh3, bash) set this true; custom modes default to
+     * false (a `cwd` chip in front of every prompt is rarely meaningful for
+     * LLM/agent-style modes). Undefined falls through to the consumer's
+     * default — InputLine renders the cwd unless this is explicitly false.
+     */
+    showCwd?: boolean;
 }

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

@@ -5,20 +5,23 @@ export type ClientMessage =
     t: 'hello';
     replayFrom?: number;
 }
-/** A line the client could not resolve locally. */
+/** A line the client could not resolve locally. `mode` tags the active
+ *  mode at submit time; the server records it on the history entry. */
  | {
     t: 'submit';
     line: string;
+    mode: string;
 }
 /** Ctrl+C / Ctrl+D while a process runs. */
  | {
     t: 'signal';
     sig: 'SIGINT' | 'EOF';
 }
-/** Local verb dispatch — tell the server to append to shared history. */
+/** Local verb dispatch — tell the server to append to per-mode history. */
  | {
     t: 'history-log';
     line: string;
+    mode: string;
 }
 /** Ask the server for its current cwd. */
  | {
@@ -31,11 +34,14 @@ export type ClientMessage =
     path: string;
 };
 export type ServerMessage = 
-/** Sent once on successful attach, immediately after hello. */
+/** Sent once on successful attach, immediately after hello.
+ *  `tenantRoot` is the initial per-user shell cwd; clients use it to
+ *  shorten displayed paths (e.g., render the tenant root as `~`). */
 {
     t: 'welcome';
     userId: string;
     cwd: string;
+    tenantRoot: string;
     env: Record<string, string>;
     seq: number;
 }
@@ -44,10 +50,10 @@ export type ServerMessage =
     t: 'replay';
     events: ServerEvent[];
 }
-/** Persisted history for up-arrow navigation. */
+/** Per-mode persisted history for up-arrow navigation. Keyed by mode id. */
  | {
-    t: 'history';
-    lines: string[];
+    t: 'history-bundle';
+    byMode: Record<string, string[]>;
 }
 /** Live event. */
  | {

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

@@ -0,0 +1,3 @@
+import type { ModeBuffer } from './mode-buffer.svelte';
+import type { ServerEvent } from './protocol';
+export declare function applyReplayEvents(buf: ModeBuffer, events: ServerEvent[]): void;

package/dist/shell-shard/replay.js

@@ -0,0 +1,44 @@
+/*
+ * Pure replay-folder. Takes a list of server events and folds them into
+ * a ModeBuffer in the same order, using the same routing rules as the
+ * live event-handler in Terminal.svelte. Extracted so it can be unit-
+ * tested without DOM mounting and so the live handler and the on-attach
+ * replay path share one implementation of the rules.
+ *
+ * Used by Terminal.svelte's `t: 'replay'` handler to fill the gap between
+ * the last persisted bash-buffer snapshot (workspace zone) and the WS
+ * reconnect — events the server still has in its ring buffer but the
+ * client hasn't seen since the last page load.
+ */
+export function applyReplayEvents(buf, events) {
+    for (const e of events) {
+        switch (e.kind) {
+            case 'prompt':
+                buf.scrollback.push({ kind: 'prompt', cwd: e.cwd, line: e.line, ts: e.ts });
+                buf.locked = true;
+                break;
+            case 'stdout':
+                buf.scrollback.push({ kind: 'text', stream: 'stdout', chunks: [e.data], ts: e.ts });
+                break;
+            case 'stderr':
+                buf.scrollback.push({ kind: 'text', stream: 'stderr', chunks: [e.data], ts: e.ts });
+                break;
+            case 'exit':
+                if (e.signal || (e.code !== null && e.code !== 0)) {
+                    buf.scrollback.push({
+                        kind: 'status',
+                        text: e.signal
+                            ? `shell: process exited (${e.signal})`
+                            : `shell: process exited (${e.code})`,
+                        level: 'error',
+                        ts: e.ts,
+                    });
+                }
+                buf.locked = false;
+                break;
+            case 'status':
+                buf.scrollback.push({ kind: 'status', text: e.text, level: e.level, ts: e.ts });
+                break;
+        }
+    }
+}

package/dist/shell-shard/replay.svelte.test.d.ts

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

package/dist/shell-shard/replay.svelte.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { applyReplayEvents } from './replay';
+import { ModeBuffer } from './mode-buffer.svelte';
+describe('applyReplayEvents', () => {
+    it('folds events into a fresh bash buffer like live events', () => {
+        const buf = new ModeBuffer('bash');
+        const events = [
+            { seq: 5, kind: 'prompt', line: 'ls', cwd: '/', ts: 100 },
+            { seq: 6, kind: 'stdout', data: 'a\nb\n', ts: 101 },
+            { seq: 7, kind: 'exit', code: 0, signal: null, ts: 102 },
+        ];
+        applyReplayEvents(buf, events);
+        // prompt + coalesced text — exit code 0 is silent (matches Terminal.svelte UX).
+        expect(buf.scrollback.entries).toHaveLength(2);
+        expect(buf.locked).toBe(false);
+    });
+    it('locks the buffer if replay ends with a prompt without exit', () => {
+        const buf = new ModeBuffer('bash');
+        const events = [
+            { seq: 10, kind: 'prompt', line: 'sleep 5', cwd: '/', ts: 200 },
+        ];
+        applyReplayEvents(buf, events);
+        expect(buf.locked).toBe(true);
+    });
+    it('emits a status entry on non-zero exit', () => {
+        const buf = new ModeBuffer('bash');
+        const events = [
+            { seq: 1, kind: 'prompt', line: 'false', cwd: '/', ts: 1 },
+            { seq: 2, kind: 'exit', code: 1, signal: null, ts: 2 },
+        ];
+        applyReplayEvents(buf, events);
+        const last = buf.scrollback.entries[buf.scrollback.entries.length - 1];
+        expect(last.kind).toBe('status');
+        if (last.kind === 'status')
+            expect(last.text).toMatch(/exited \(1\)/);
+    });
+    it('routes stderr to a stderr text entry', () => {
+        const buf = new ModeBuffer('bash');
+        applyReplayEvents(buf, [
+            { seq: 1, kind: 'stderr', data: 'oops\n', ts: 1 },
+        ]);
+        const e = buf.scrollback.entries[0];
+        expect(e.kind).toBe('text');
+        if (e.kind === 'text')
+            expect(e.stream).toBe('stderr');
+    });
+});

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

@@ -0,0 +1,5 @@
+import type { Component } from 'svelte';
+export declare function registerRichComponent(key: string, component: Component<any>): void;
+export declare function lookupRichComponent(key: string): Component<any> | null;
+/** Test-only seam. Do not call from production code. */
+export declare function __resetRichRegistryForTests(): void;

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

@@ -0,0 +1,25 @@
+/*
+ * Stable string-keyed registry mapping a componentKey to a Svelte
+ * component. Used by ScrollbackView (live render) and BufferStore
+ * (rehydrate persisted rich entries).
+ *
+ * Each rich-emitting verb registers its component once at module load.
+ * Keys must be globally unique within the shell-shard namespace.
+ */
+const components = new Map();
+export function registerRichComponent(key, component) {
+    const existing = components.get(key);
+    if (existing && existing !== component) {
+        console.warn(`[shell-shard/rich-registry] duplicate registration for key "${key}" — keeping first`);
+        return;
+    }
+    components.set(key, component);
+}
+export function lookupRichComponent(key) {
+    var _a;
+    return (_a = components.get(key)) !== null && _a !== void 0 ? _a : null;
+}
+/** Test-only seam. Do not call from production code. */
+export function __resetRichRegistryForTests() {
+    components.clear();
+}

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

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

package/dist/shell-shard/rich-registry.test.js

@@ -0,0 +1,31 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { registerRichComponent, lookupRichComponent, __resetRichRegistryForTests, } from './rich-registry';
+const FakeComp = {};
+const OtherComp = {};
+describe('rich-registry', () => {
+    beforeEach(() => {
+        __resetRichRegistryForTests();
+    });
+    it('returns null for unknown keys', () => {
+        expect(lookupRichComponent('nope')).toBe(null);
+    });
+    it('roundtrips a registered key', () => {
+        registerRichComponent('test', FakeComp);
+        expect(lookupRichComponent('test')).toBe(FakeComp);
+    });
+    it('warns and ignores duplicate registrations of a different component', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        registerRichComponent('dup', FakeComp);
+        registerRichComponent('dup', OtherComp);
+        expect(lookupRichComponent('dup')).toBe(FakeComp);
+        expect(warn).toHaveBeenCalledOnce();
+        warn.mockRestore();
+    });
+    it('idempotent registration of the same component is silent', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        registerRichComponent('idem', FakeComp);
+        registerRichComponent('idem', FakeComp);
+        expect(warn).not.toHaveBeenCalled();
+        warn.mockRestore();
+    });
+});

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

@@ -15,6 +15,7 @@ export type ScrollbackEntry = {
 } | {
     kind: 'rich';
     id: string;
+    componentKey?: string;
     component: RichComponent;
     props: Record<string, unknown>;
     ts: number;
@@ -32,5 +33,6 @@ export declare class Scrollback {
     constructor(cap?: number);
     push(entry: DistributiveOmit<ScrollbackEntry, 'id'>): void;
     clear(): void;
+    restore(entries: ScrollbackEntry[]): void;
 }
 export {};

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

@@ -16,6 +16,14 @@ let nextId = 0;
 function mkId() {
     return `e${++nextId}`;
 }
+// Parses the numeric suffix of an id minted by mkId (`e<n>`). Returns NaN
+// for any other shape so restore() can ignore it without throwing.
+function parseIdNumber(id) {
+    if (id.length < 2 || id.charCodeAt(0) !== 101 /* 'e' */)
+        return NaN;
+    const n = Number(id.slice(1));
+    return Number.isInteger(n) ? n : NaN;
+}
 export class Scrollback {
     constructor(cap = DEFAULT_CAP) {
         this.entries = $state([]);
@@ -40,4 +48,19 @@ export class Scrollback {
     clear() {
         this.entries.length = 0;
     }
+    // Replace entries from a persisted snapshot. Splices in place to keep the
+    // $state proxy identity stable, and bumps the module-scoped id counter
+    // past any restored numeric id so subsequent push()es never collide with
+    // hydrated keys (which would crash Svelte's keyed {#each}).
+    restore(entries) {
+        let max = 0;
+        for (const e of entries) {
+            const n = parseIdNumber(e.id);
+            if (Number.isFinite(n) && n > max)
+                max = n;
+        }
+        if (max > nextId)
+            nextId = max;
+        this.entries.splice(0, this.entries.length, ...entries);
+    }
 }

package/dist/shell-shard/scrollback.svelte.test.d.ts

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