sh3-core 0.6.0

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

@@ -0,0 +1,25 @@
+<script lang="ts">
+  interface Props {
+    stream: 'stdout' | 'stderr';
+    chunks: string[];
+  }
+  let { stream, chunks }: Props = $props();
+
+  // v1: strip ANSI escapes; render plain text. ANSI-to-HTML is deferred.
+  const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+  const text = $derived(chunks.join('').replace(ANSI_RE, ''));
+</script>
+
+<pre class="shell-text" class:stderr={stream === 'stderr'}>{text}</pre>
+
+<style>
+  .shell-text {
+    margin: 0;
+    padding: 0 8px;
+    font-family: var(--shell-font-mono, monospace);
+    white-space: pre-wrap;
+    word-break: break-word;
+    color: var(--shell-fg, #ddd);
+  }
+  .shell-text.stderr { color: var(--shell-fg-error, #f88); }
+</style>

package/dist/shell-shard/entries/TextEntry.svelte.d.ts

@@ -0,0 +1,7 @@
+interface Props {
+    stream: 'stdout' | 'stderr';
+    chunks: string[];
+}
+declare const TextEntry: import("svelte").Component<Props, {}, "">;
+type TextEntry = ReturnType<typeof TextEntry>;
+export default TextEntry;

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

@@ -0,0 +1,2 @@
+import type { ShardManifest } from '../api';
+export declare const manifest: ShardManifest;

package/dist/shell-shard/manifest.js

@@ -0,0 +1,11 @@
+export const manifest = {
+    id: 'shell',
+    label: 'Shell',
+    version: '0.1.0',
+    views: [{ id: 'shell:terminal', label: 'Shell' }],
+    // serverBundle intentionally omitted — this shard is a framework built-in
+    // 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: [],
+};

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

@@ -0,0 +1,90 @@
+export declare const PROTOCOL_VERSION: 1;
+export type ClientMessage = 
+/** Sent on WS open. Optional cursor for replay resume after a reconnect. */
+{
+    t: 'hello';
+    replayFrom?: number;
+}
+/** A line the client could not resolve locally. */
+ | {
+    t: 'submit';
+    line: 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. */
+ | {
+    t: 'history-log';
+    line: string;
+}
+/** Ask the server for its current cwd. */
+ | {
+    t: 'cwd-query';
+};
+export type ServerMessage = 
+/** Sent once on successful attach, immediately after hello. */
+{
+    t: 'welcome';
+    userId: string;
+    cwd: string;
+    env: Record<string, string>;
+    seq: number;
+}
+/** Recent ring contents, sent after welcome (or on explicit replayFrom). */
+ | {
+    t: 'replay';
+    events: ServerEvent[];
+}
+/** Persisted history for up-arrow navigation. */
+ | {
+    t: 'history';
+    lines: string[];
+}
+/** Live event. */
+ | {
+    t: 'event';
+    event: ServerEvent;
+}
+/** Proactive cwd update after a successful cd. */
+ | {
+    t: 'cwd';
+    cwd: string;
+}
+/** Protocol-level error — not the same as a stderr event. */
+ | {
+    t: 'error';
+    message: string;
+    code?: string;
+};
+export type ServerEvent = {
+    seq: number;
+    kind: 'prompt';
+    line: string;
+    cwd: string;
+    ts: number;
+} | {
+    seq: number;
+    kind: 'stdout';
+    data: string;
+    ts: number;
+} | {
+    seq: number;
+    kind: 'stderr';
+    data: string;
+    ts: number;
+} | {
+    seq: number;
+    kind: 'exit';
+    code: number | null;
+    signal: string | null;
+    ts: number;
+} | {
+    seq: number;
+    kind: 'status';
+    text: string;
+    level: 'info' | 'warn' | 'error';
+    ts: number;
+};

package/dist/shell-shard/protocol.js

@@ -0,0 +1,11 @@
+/*
+ * shell-shard WebSocket protocol.
+ *
+ * Shared by the sh3-core client half (`src/shell-shard/`) and the
+ * sh3-server server half (`packages/sh3-server/src/shell-shard/`). Type-
+ * only module — no runtime imports, safe to load from either side.
+ *
+ * See docs/superpowers/specs/2026-04-10-shell-shard-design.md § WebSocket
+ * protocol for the authoritative description.
+ */
+export const PROTOCOL_VERSION = 1;

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

@@ -0,0 +1,69 @@
+import type { Scrollback } from './scrollback.svelte';
+import type { SessionClient } from './session-client.svelte';
+export interface ShellApi {
+    listApps(): Array<{
+        id: string;
+        label: string;
+    }>;
+    getActiveApp(): {
+        id: string;
+        label: string;
+    } | null;
+    launchApp(id: string): void;
+    listShards(): Array<{
+        id: string;
+        label: string;
+        version: string;
+    }>;
+    listViewsInCurrentLayout(): Array<{
+        slotId: string;
+        viewId: string;
+        label: string;
+    }>;
+    openViewInCurrentLayout(viewId: string): {
+        ok: boolean;
+        error?: string;
+    };
+    closeSlot(slotId: string): {
+        ok: boolean;
+        error?: string;
+    };
+    listZones(shardId?: string): Array<{
+        shardId: string;
+        zones: string[];
+    }>;
+    readZone(shardId: string, zoneName: string): unknown;
+    whoAmI(): {
+        userId: string;
+        admin: boolean;
+    };
+}
+export interface VerbContext {
+    shell: ShellApi;
+    scrollback: Scrollback;
+    session: SessionClient;
+    cwd: string;
+    /** Invoke another registered verb programmatically (used by rich-entry clicks). */
+    dispatch(line: string): Promise<void>;
+}
+export interface Verb {
+    name: string;
+    summary: string;
+    run(ctx: VerbContext, args: string[]): Promise<void>;
+}
+export type Resolution = {
+    kind: 'local';
+    verb: Verb;
+    args: string[];
+    line: string;
+} | {
+    kind: 'forward';
+    line: string;
+};
+export declare class VerbRegistry {
+    private readonly verbs;
+    register(verb: Verb): void;
+    list(): Verb[];
+    get(name: string): Verb | undefined;
+    resolve(line: string): Resolution;
+}

package/dist/shell-shard/registry.js

@@ -0,0 +1,47 @@
+/*
+ * Verb registry for shell-shard.
+ *
+ * v1 is internal to shell-shard (not a contribution kind). Holds a map of
+ * verb name → Verb definition. Resolution:
+ *   1. If first token matches a registered verb → { kind: 'local', verb, args }
+ *   2. If first token is '$' → { kind: 'forward', line: rest } (escape hatch)
+ *   3. Otherwise → { kind: 'forward', line } (unknown, ship to server)
+ *
+ * Future: other shards register verbs via a new contribution kind.
+ */
+export class VerbRegistry {
+    constructor() {
+        this.verbs = new Map();
+    }
+    register(verb) {
+        this.verbs.set(verb.name, verb);
+    }
+    list() {
+        return Array.from(this.verbs.values()).sort((a, b) => a.name.localeCompare(b.name));
+    }
+    get(name) {
+        return this.verbs.get(name);
+    }
+    resolve(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return { kind: 'forward', line };
+        // Escape hatch: '$ <rest>' always forwards
+        if (trimmed.startsWith('$ ')) {
+            return { kind: 'forward', line: trimmed.slice(2) };
+        }
+        if (trimmed === '$') {
+            return { kind: 'forward', line: '' };
+        }
+        // First whitespace-separated token
+        const space = trimmed.indexOf(' ');
+        const head = space === -1 ? trimmed : trimmed.slice(0, space);
+        const rest = space === -1 ? '' : trimmed.slice(space + 1);
+        const verb = this.verbs.get(head);
+        if (!verb)
+            return { kind: 'forward', line };
+        // Simple space-split for args — verbs can re-tokenize if they need quoting
+        const args = rest.length ? rest.split(/\s+/) : [];
+        return { kind: 'local', verb, args, line };
+    }
+}

package/dist/shell-shard/rich/AppCard.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+  interface Props {
+    data: { id: string; label: string; shards: string[] };
+  }
+  let { data }: Props = $props();
+</script>
+
+<div class="shell-rich-appcard">
+  <h3>{data.label}</h3>
+  <p><strong>ID:</strong> {data.id}</p>
+  <p><strong>Shards:</strong> {data.shards.join(', ')}</p>
+</div>
+
+<style>
+  .shell-rich-appcard {
+    padding: 8px;
+    border: 1px solid var(--shell-border, #444);
+  }
+  .shell-rich-appcard h3 {
+    margin: 0 0 8px 0;
+  }
+  .shell-rich-appcard p {
+    margin: 4px 0;
+  }
+</style>

package/dist/shell-shard/rich/AppCard.svelte.d.ts

@@ -0,0 +1,10 @@
+interface Props {
+    data: {
+        id: string;
+        label: string;
+        shards: string[];
+    };
+}
+declare const AppCard: import("svelte").Component<Props, {}, "">;
+type AppCard = ReturnType<typeof AppCard>;
+export default AppCard;

package/dist/shell-shard/rich/AppsTable.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+  interface Props {
+    data: { apps: Array<{ id: string; label: string }>; onClickApp: (id: string) => void };
+  }
+  let { data }: Props = $props();
+</script>
+
+<div class="shell-rich-apps">
+  <table>
+    <thead>
+      <tr><th>ID</th><th>Label</th></tr>
+    </thead>
+    <tbody>
+      {#each data.apps as app (app.id)}
+        <tr>
+          <td><button type="button" onclick={() => data.onClickApp(app.id)}>{app.id}</button></td>
+          <td>{app.label}</td>
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+</div>
+
+<style>
+  .shell-rich-apps table { border-collapse: collapse; width: 100%; }
+  .shell-rich-apps th, .shell-rich-apps td { padding: 2px 8px; text-align: left; }
+  .shell-rich-apps button { background: none; border: 0; color: var(--shell-link, #6cf); cursor: pointer; padding: 0; font: inherit; }
+  .shell-rich-apps button:hover { text-decoration: underline; }
+</style>

package/dist/shell-shard/rich/AppsTable.svelte.d.ts

@@ -0,0 +1,12 @@
+interface Props {
+    data: {
+        apps: Array<{
+            id: string;
+            label: string;
+        }>;
+        onClickApp: (id: string) => void;
+    };
+}
+declare const AppsTable: import("svelte").Component<Props, {}, "">;
+type AppsTable = ReturnType<typeof AppsTable>;
+export default AppsTable;

package/dist/shell-shard/rich/EnvTable.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+  interface Props {
+    data: { env: Record<string, string> };
+  }
+  let { data }: Props = $props();
+</script>
+
+<div class="shell-rich-env">
+  <table>
+    <thead>
+      <tr><th>Key</th><th>Value</th></tr>
+    </thead>
+    <tbody>
+      {#each Object.entries(data.env) as [key, value] (key)}
+        <tr>
+          <td>{key}</td>
+          <td>{value}</td>
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+</div>
+
+<style>
+  .shell-rich-env table { border-collapse: collapse; width: 100%; }
+  .shell-rich-env th, .shell-rich-env td { padding: 2px 8px; text-align: left; }
+</style>

package/dist/shell-shard/rich/EnvTable.svelte.d.ts

@@ -0,0 +1,8 @@
+interface Props {
+    data: {
+        env: Record<string, string>;
+    };
+}
+declare const EnvTable: import("svelte").Component<Props, {}, "">;
+type EnvTable = ReturnType<typeof EnvTable>;
+export default EnvTable;

package/dist/shell-shard/rich/HelpTable.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+  interface Props {
+    data: { rows: Array<{ name: string; summary: string }>; onClickName: (name: string) => void };
+  }
+  let { data }: Props = $props();
+</script>
+
+<div class="shell-rich-help">
+  <table>
+    <thead>
+      <tr><th>Name</th><th>Summary</th></tr>
+    </thead>
+    <tbody>
+      {#each data.rows as row (row.name)}
+        <tr>
+          <td><button type="button" onclick={() => data.onClickName(row.name)}>{row.name}</button></td>
+          <td>{row.summary}</td>
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+</div>
+
+<style>
+  .shell-rich-help table { border-collapse: collapse; width: 100%; }
+  .shell-rich-help th, .shell-rich-help td { padding: 2px 8px; text-align: left; }
+  .shell-rich-help button { background: none; border: 0; color: var(--shell-link, #6cf); cursor: pointer; padding: 0; font: inherit; }
+  .shell-rich-help button:hover { text-decoration: underline; }
+</style>

package/dist/shell-shard/rich/HelpTable.svelte.d.ts

@@ -0,0 +1,12 @@
+interface Props {
+    data: {
+        rows: Array<{
+            name: string;
+            summary: string;
+        }>;
+        onClickName: (name: string) => void;
+    };
+}
+declare const HelpTable: import("svelte").Component<Props, {}, "">;
+type HelpTable = ReturnType<typeof HelpTable>;
+export default HelpTable;

package/dist/shell-shard/rich/HistoryList.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+  interface Props {
+    data: { lines: string[]; onClickLine: (line: string) => void };
+  }
+  let { data }: Props = $props();
+</script>
+
+<div class="shell-rich-history">
+  <ol>
+    {#each data.lines as line, i (i)}
+      <li><button type="button" onclick={() => data.onClickLine(line)}>{line}</button></li>
+    {/each}
+  </ol>
+</div>
+
+<style>
+  .shell-rich-history ol {
+    list-style-position: inside;
+    margin: 0;
+    padding: 0;
+  }
+  .shell-rich-history li {
+    padding: 2px 0;
+  }
+  .shell-rich-history button {
+    background: none;
+    border: 0;
+    color: var(--shell-link, #6cf);
+    cursor: pointer;
+    padding: 0;
+    font: inherit;
+    text-align: left;
+  }
+  .shell-rich-history button:hover {
+    text-decoration: underline;
+  }
+</style>

package/dist/shell-shard/rich/HistoryList.svelte.d.ts

@@ -0,0 +1,9 @@
+interface Props {
+    data: {
+        lines: string[];
+        onClickLine: (line: string) => void;
+    };
+}
+declare const HistoryList: import("svelte").Component<Props, {}, "">;
+type HistoryList = ReturnType<typeof HistoryList>;
+export default HistoryList;

package/dist/shell-shard/rich/ShardsTable.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+  interface Props {
+    data: { shards: Array<{ id: string; label: string; version: string }> };
+  }
+  let { data }: Props = $props();
+</script>
+
+<div class="shell-rich-shards">
+  <table>
+    <thead>
+      <tr><th>ID</th><th>Label</th><th>Version</th></tr>
+    </thead>
+    <tbody>
+      {#each data.shards as shard (shard.id)}
+        <tr>
+          <td>{shard.id}</td>
+          <td>{shard.label}</td>
+          <td>{shard.version}</td>
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+</div>
+
+<style>
+  .shell-rich-shards table { border-collapse: collapse; width: 100%; }
+  .shell-rich-shards th, .shell-rich-shards td { padding: 2px 8px; text-align: left; }
+</style>

package/dist/shell-shard/rich/ShardsTable.svelte.d.ts

@@ -0,0 +1,12 @@
+interface Props {
+    data: {
+        shards: Array<{
+            id: string;
+            label: string;
+            version: string;
+        }>;
+    };
+}
+declare const ShardsTable: import("svelte").Component<Props, {}, "">;
+type ShardsTable = ReturnType<typeof ShardsTable>;
+export default ShardsTable;

package/dist/shell-shard/rich/ViewsTable.svelte

@@ -0,0 +1,31 @@
+<script lang="ts">
+  interface Props {
+    data: { views: Array<{ slotId: string; viewId: string; label: string }>; onClose: (slotId: string) => void };
+  }
+  let { data }: Props = $props();
+</script>
+
+<div class="shell-rich-views">
+  <table>
+    <thead>
+      <tr><th>Slot ID</th><th>View ID</th><th>Label</th><th>Action</th></tr>
+    </thead>
+    <tbody>
+      {#each data.views as view (view.slotId)}
+        <tr>
+          <td>{view.slotId}</td>
+          <td>{view.viewId}</td>
+          <td>{view.label}</td>
+          <td><button type="button" onclick={() => data.onClose(view.slotId)}>Close</button></td>
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+</div>
+
+<style>
+  .shell-rich-views table { border-collapse: collapse; width: 100%; }
+  .shell-rich-views th, .shell-rich-views td { padding: 2px 8px; text-align: left; }
+  .shell-rich-views button { background: none; border: 0; color: var(--shell-link, #6cf); cursor: pointer; padding: 0; font: inherit; }
+  .shell-rich-views button:hover { text-decoration: underline; }
+</style>

package/dist/shell-shard/rich/ViewsTable.svelte.d.ts

@@ -0,0 +1,13 @@
+interface Props {
+    data: {
+        views: Array<{
+            slotId: string;
+            viewId: string;
+            label: string;
+        }>;
+        onClose: (slotId: string) => void;
+    };
+}
+declare const ViewsTable: import("svelte").Component<Props, {}, "">;
+type ViewsTable = ReturnType<typeof ViewsTable>;
+export default ViewsTable;

package/dist/shell-shard/rich/ZoneTree.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+  interface Props {
+    data: { value: unknown };
+  }
+  let { data }: Props = $props();
+</script>
+
+<div class="shell-rich-zonetree">
+  <pre>{JSON.stringify(data.value, null, 2)}</pre>
+</div>
+
+<style>
+  .shell-rich-zonetree pre {
+    overflow: auto;
+    padding: 8px;
+    background: var(--shell-bg, #000);
+    color: var(--shell-fg, #fff);
+  }
+</style>

package/dist/shell-shard/rich/ZoneTree.svelte.d.ts

@@ -0,0 +1,8 @@
+interface Props {
+    data: {
+        value: unknown;
+    };
+}
+declare const ZoneTree: import("svelte").Component<Props, {}, "">;
+type ZoneTree = ReturnType<typeof ZoneTree>;
+export default ZoneTree;

package/dist/shell-shard/rich/ZonesTable.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+  interface Props {
+    data: { rows: Array<{ shardId: string; zones: string[] }> };
+  }
+  let { data }: Props = $props();
+</script>
+
+<div class="shell-rich-zones">
+  <table>
+    <thead>
+      <tr><th>Shard ID</th><th>Zones</th></tr>
+    </thead>
+    <tbody>
+      {#each data.rows as row (row.shardId)}
+        <tr>
+          <td>{row.shardId}</td>
+          <td>{row.zones.join(', ')}</td>
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+</div>
+
+<style>
+  .shell-rich-zones table { border-collapse: collapse; width: 100%; }
+  .shell-rich-zones th, .shell-rich-zones td { padding: 2px 8px; text-align: left; }
+</style>

package/dist/shell-shard/rich/ZonesTable.svelte.d.ts

@@ -0,0 +1,11 @@
+interface Props {
+    data: {
+        rows: Array<{
+            shardId: string;
+            zones: string[];
+        }>;
+    };
+}
+declare const ZonesTable: import("svelte").Component<Props, {}, "">;
+type ZonesTable = ReturnType<typeof ZonesTable>;
+export default ZonesTable;

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

@@ -0,0 +1,36 @@
+import type { Component } from 'svelte';
+export type RichComponent = Component<any>;
+export type ScrollbackEntry = {
+    kind: 'prompt';
+    id: string;
+    cwd: string;
+    line: string;
+    ts: number;
+} | {
+    kind: 'text';
+    id: string;
+    stream: 'stdout' | 'stderr';
+    chunks: string[];
+    ts: number;
+} | {
+    kind: 'rich';
+    id: string;
+    component: RichComponent;
+    props: Record<string, unknown>;
+    ts: number;
+} | {
+    kind: 'status';
+    id: string;
+    text: string;
+    level: 'info' | 'warn' | 'error';
+    ts: number;
+};
+type DistributiveOmit<T, K extends keyof any> = T extends unknown ? Omit<T, K> : never;
+export declare class Scrollback {
+    entries: ScrollbackEntry[];
+    private readonly cap;
+    constructor(cap?: number);
+    push(entry: DistributiveOmit<ScrollbackEntry, 'id'>): void;
+    clear(): void;
+}
+export {};