sh3-core 0.6.0

package/dist/shards/registry.js

@@ -0,0 +1,28 @@
+/*
+ * Contribution registry — phase 4 stub.
+ *
+ * Tracks which ViewFactory answers a given viewId. In this phase the
+ * registry is a flat module-level Map with no awareness of shard identity;
+ * writes come from `activateShard` which additionally remembers which
+ * viewIds a given shard registered so they can be torn down in
+ * `deactivateShard`.
+ *
+ * The shape of this registry is deliberately narrow so later phases can
+ * expand it without breaking callers:
+ *   - Resolution by viewId is the only query slots need.
+ *   - Commands, toolbar items, menus, hotkeys get their own sibling maps
+ *     (one per contribution kind) when those kinds land.
+ */
+const views = new Map();
+export function registerView(viewId, factory) {
+    if (views.has(viewId)) {
+        throw new Error(`View "${viewId}" is already registered`);
+    }
+    views.set(viewId, factory);
+}
+export function getView(viewId) {
+    return views.get(viewId);
+}
+export function unregisterView(viewId) {
+    views.delete(viewId);
+}

package/dist/shards/types.d.ts

@@ -0,0 +1,207 @@
+import type { StateZones } from '../state/zones.svelte';
+import type { ZoneSchema, ZoneManager } from '../state/types';
+import type { DocumentHandle, DocumentHandleOptions } from '../documents/types';
+import type { EnvState } from '../env/types';
+/**
+ * The object returned by `ViewFactory.mount`. The framework calls
+ * `unmount()` when the slot goes away, and `onResize(w, h)` whenever the
+ * slot's container changes size (including splitter drags and window
+ * resize). `remountOnMove` is the opt-out from the re-parenting-survival
+ * contract (rare, GL-edge-case shards); phase 4 does not exercise it.
+ */
+export interface ViewHandle {
+    /** Called by the framework when the slot is removed from the layout. Release all resources here. */
+    unmount(): void;
+    /** Optional callback invoked when the slot's container dimensions change. */
+    onResize?(width: number, height: number): void;
+    /**
+     * When true the framework will unmount and remount this view if its slot
+     * moves to a different DOM parent (e.g. a splitter drag). Set to false
+     * (or omit) if the view can survive DOM re-parenting without reinitializing.
+     */
+    remountOnMove?: boolean;
+    /**
+     * Closability mode for this view instance.
+     *   - undefined / false: non-closable (no close button rendered).
+     *   - true: pure close — instant removal, no confirmation.
+     *   - { canClose() }: guarded close — layout engine awaits the promise;
+     *     resolve true to allow, false to cancel.
+     */
+    closable?: boolean | {
+        canClose(): Promise<boolean>;
+    };
+}
+/**
+ * Context passed to `ViewFactory.mount` so the view knows which layout
+ * instance it is and can push reactive metadata back to the tab strip.
+ */
+export interface MountContext {
+    /** Stable identifier for the slot this view is mounted into. */
+    slotId: string;
+    /** The view id that was used to look up this factory. */
+    viewId: string;
+    /** Initial label for the tab; may be updated by the view via future API. */
+    label: string;
+    /**
+     * Push dirty-state to the tab strip. The framework renders a dirty
+     * indicator (filled dot) on the tab when true, clears it when false.
+     * Call this whenever the view's save-state changes.
+     */
+    setDirty(dirty: boolean): void;
+}
+/**
+ * The shard-side adapter that knows how to bring a view to life inside a
+ * given HTMLElement. The container is owned by the framework (the slot);
+ * the factory writes into it and returns a ViewHandle.
+ */
+export interface ViewFactory {
+    /**
+     * Mount the view into `container`. The container element is owned and sized
+     * by the framework; the factory should not modify its dimensions or position.
+     * Returns a `ViewHandle` the framework uses to communicate with the view.
+     */
+    mount(container: HTMLElement, context: MountContext): ViewHandle;
+}
+/**
+ * Static description of a view a shard provides. Lives inside
+ * `ShardManifest.views` so apps and tooling can enumerate a shard's views
+ * without running `activate()`. Phase 8 only uses `id` and `label`; `icon`
+ * is reserved and not rendered yet.
+ */
+export interface ViewDeclaration {
+    /** Unique view id within this shard. Used to look up the factory at mount time. */
+    id: string;
+    /** Human-readable label used in tab strips and launchers. */
+    label: string;
+    /** Optional icon hint (reserved; not yet rendered in phase 8). */
+    icon?: string;
+}
+/**
+ * Static description of a shard. Declared once and read by the framework
+ * before `activate` runs, so the shell can enumerate a shard's capabilities
+ * without executing any shard code.
+ */
+export interface ShardManifest {
+    /** Unique shard identifier. Used as the state namespace and view id prefix. */
+    id: string;
+    /** Human-readable display name. */
+    label: string;
+    /** Semver version string for the shard package. */
+    version: string;
+    /**
+     * Static list of the view ids this shard provides. Every id listed here
+     * must be backed by a `ctx.registerView(id, factory)` call from within
+     * `activate()`; the framework verifies this after `activate` returns and
+     * throws on any missing factory. Phase 8 adds this field; shards that
+     * predate phase 8 must be updated to declare their views here.
+     */
+    views: ViewDeclaration[];
+    /**
+     * Optional filename of a server-side bundle for this shard. When present,
+     * sh3-server loads the bundle at boot and mounts its routes at
+     * `/api/<shard-id>/`. The server bundle runs in Node with full access.
+     * Only relevant for shards installed via the package store; framework-
+     * shipped shards do not use this field.
+     */
+    serverBundle?: string;
+    /**
+     * 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.
+     */
+    permissions?: string[];
+}
+/**
+ * Handed to `shard.activate`. The shard uses it to declare state and
+ * register contributions. `state` is pre-bound to the shard's id so the
+ * shard never has to pass its own id through — the framework guarantees
+ * isolation by construction.
+ */
+export interface ShardContext {
+    /**
+     * Declare the state zones this shard uses and receive a live reactive
+     * object. The shard id is baked in — shards never pass their own id.
+     * Persistent zones (`workspace`, `user`) are hydrated before the call
+     * returns.
+     *
+     * @param schema - Zone names mapped to their default values.
+     */
+    state<T extends ZoneSchema>(schema: T): StateZones<T>;
+    /**
+     * Register a view factory for a view id declared in the shard manifest.
+     * Must be called for every id listed in `manifest.views` during `activate`.
+     *
+     * @param viewId  - Must match an entry in `manifest.views`.
+     * @param factory - The adapter that mounts the view into a container element.
+     */
+    registerView(viewId: string, factory: ViewFactory): void;
+    /** Obtain a file-oriented document handle scoped to this shard. */
+    documents(options: DocumentHandleOptions): DocumentHandle;
+    /**
+     * Declare environment state for this shard and receive a hydrated snapshot.
+     * Env state is server-authoritative, fetched once at activation, and
+     * shallow-merged with defaults (new fields get defaults even if the server
+     * has an older entry). Read-only for non-admin sessions.
+     *
+     * @param defaults - Default values for each env state field.
+     * @returns A reactive proxy of the env state.
+     */
+    env<T extends Record<string, unknown>>(defaults: T): EnvState<T>;
+    /**
+     * Update this shard's environment state on the server. Merges the patch
+     * into the current env state, writes to the server, and updates the local
+     * reactive proxy. Throws if the session is not admin-elevated.
+     *
+     * @param patch - Partial env state to merge.
+     */
+    envUpdate<T extends Record<string, unknown>>(patch: Partial<T>): Promise<void>;
+    /** Whether the current session has admin privileges. */
+    isAdmin: boolean;
+    /**
+     * Cross-shard zone management API. Only present when the shard's
+     * manifest declares the `'state:manage'` permission. Check with
+     * `if (ctx.zones)` before use.
+     */
+    zones?: ZoneManager;
+}
+/**
+ * A shard module. Shards are the fundamental unit of contribution in SH3.
+ * Each shard activates once, receives a `ShardContext`, and registers views
+ * and other capabilities that the shell and apps can use. Shard lifecycle is
+ * separate from view lifecycle — a shard may be active with no views visible.
+ */
+export interface Shard {
+    /** Static description of this shard's identity and declared contributions. */
+    manifest: ShardManifest;
+    /**
+     * Run once when the shard is activated. Use `ctx` to declare state zones,
+     * register view factories, and obtain document handles. Must register a
+     * factory for every view id declared in `manifest.views`.
+     */
+    activate(ctx: ShardContext): void | Promise<void>;
+    /**
+     * Optional self-starting hook. A shard that defines `autostart` is
+     * eagerly activated by the framework at boot (right after the register
+     * pass finishes) instead of waiting for an app to require it. `activate`
+     * runs first; `autostart` runs immediately after and may take imperative
+     * action — docking its own views into the active layout, opening a
+     * modal, subscribing to framework state, etc. The `__sh3core__` pseudo-
+     * shard uses this with a no-op body so its activation path is uniform
+     * with other self-starting shards. Diagnostic-style shards use it to
+     * do real work.
+     */
+    autostart?(ctx: ShardContext): void | Promise<void>;
+    /** Optional cleanup hook called when the shard is deactivated. Release timers, subscriptions, and external resources here. */
+    deactivate?(): void | Promise<void>;
+    /**
+     * Called when the owning app is suspended (Home button). The shard
+     * remains active; its views and state are preserved. Return `false`
+     * (sync or async) to cancel the navigation.
+     */
+    suspend?(): void | false | Promise<void | false>;
+    /**
+     * Called when the owning app resumes from Home. Receives the same
+     * `ShardContext` that `activate` received.
+     */
+    resume?(ctx: ShardContext): void | Promise<void>;
+}

package/dist/shards/types.js

@@ -0,0 +1,20 @@
+/*
+ * Shard contract — minimum viable draft for phase 4.
+ *
+ * A shard is a self-contained module that contributes capabilities (views,
+ * commands, services, …) to the shell. See docs/design/shards.md for the
+ * full design; phase 4 implements only the pieces needed to mount a view
+ * into a layout slot:
+ *
+ *   - A shard declares a manifest.
+ *   - `activate(ctx)` runs once, receives a ShardContext, and registers
+ *     whichever contributions it wants the shell to know about.
+ *   - A ViewFactory knows how to mount a view into a raw HTMLElement and
+ *     return a handle the framework uses to unmount / notify of resizes.
+ *
+ * Deferred to later phases: bus scoping, command/toolbar/menu/hotkey
+ * registration, modal provider contributions, background services, lazy
+ * activation events. They'll slot into `ShardContext` as new `register*`
+ * methods without disturbing the phase-4 shape.
+ */
+export {};

package/dist/shell-shard/InputLine.svelte

@@ -0,0 +1,133 @@
+<script lang="ts">
+  import type { SessionClient } from './session-client.svelte';
+
+  interface Props {
+    cwd: string;
+    locked: boolean;                       // true while a process is running
+    history: string[];                     // persisted history, newest last
+    session: SessionClient;
+    onSubmit: (line: string) => void;      // called with the raw entered line
+  }
+  let { cwd, locked, history, session, onSubmit }: Props = $props();
+
+  let draft = $state('');
+  let historyIndex = $state<number | null>(null);  // null = live draft
+  let savedDraft = $state('');                      // restored when user returns from history
+
+  let input: HTMLInputElement | null = $state(null);
+
+  function submit() {
+    if (locked) return;
+    const line = draft;
+    if (!line.trim()) return;
+    draft = '';
+    historyIndex = null;
+    onSubmit(line);
+  }
+
+  function navHistoryUp() {
+    if (history.length === 0) return;
+    if (historyIndex === null) {
+      savedDraft = draft;
+      historyIndex = history.length - 1;
+    } else if (historyIndex > 0) {
+      historyIndex--;
+    }
+    draft = history[historyIndex] ?? '';
+  }
+
+  function navHistoryDown() {
+    if (historyIndex === null) return;
+    if (historyIndex < history.length - 1) {
+      historyIndex++;
+      draft = history[historyIndex];
+    } else {
+      historyIndex = null;
+      draft = savedDraft;
+    }
+  }
+
+  function onKeyDown(e: KeyboardEvent) {
+    if (locked) {
+      if (e.ctrlKey && e.key === 'c') {
+        e.preventDefault();
+        session.send({ t: 'signal', sig: 'SIGINT' });
+        return;
+      }
+      if (e.ctrlKey && e.key === 'd') {
+        e.preventDefault();
+        session.send({ t: 'signal', sig: 'EOF' });
+        return;
+      }
+      // Drop all other input while locked
+      e.preventDefault();
+      return;
+    }
+
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      submit();
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      navHistoryUp();
+    } else if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      navHistoryDown();
+    } else if (e.ctrlKey && e.key === 'c') {
+      e.preventDefault();
+      draft = '';
+      historyIndex = null;
+    } else if (e.ctrlKey && e.key === 'l') {
+      e.preventDefault();
+      draft = 'clear';
+      submit();
+    }
+  }
+
+  // Re-focus the input when the locked state flips to false
+  $effect(() => {
+    if (!locked && input) {
+      input.focus();
+    }
+  });
+</script>
+
+<div class="shell-input" class:locked>
+  <span class="shell-input-cwd">{cwd}</span>
+  <span class="shell-input-arrow">❯</span>
+  <input
+    bind:this={input}
+    bind:value={draft}
+    type="text"
+    disabled={locked}
+    onkeydown={onKeyDown}
+    spellcheck="false"
+    autocomplete="off"
+    autocapitalize="off"
+    class="shell-input-field"
+  />
+</div>
+
+<style>
+  .shell-input {
+    display: flex;
+    gap: 8px;
+    padding: 4px 8px;
+    border-top: 1px solid var(--shell-border, #333);
+    font-family: var(--shell-font-mono, monospace);
+  }
+  .shell-input-cwd { color: var(--shell-fg-muted, #888); }
+  .shell-input-arrow { color: var(--shell-accent, #6cf); }
+  .shell-input-field {
+    flex: 1 1 auto;
+    background: transparent;
+    border: 0;
+    outline: 0;
+    color: var(--shell-fg, #ddd);
+    font: inherit;
+  }
+  .shell-input.locked .shell-input-field {
+    opacity: 0.5;
+    cursor: default;
+  }
+</style>

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

@@ -0,0 +1,11 @@
+import type { SessionClient } from './session-client.svelte';
+interface Props {
+    cwd: string;
+    locked: boolean;
+    history: string[];
+    session: SessionClient;
+    onSubmit: (line: string) => void;
+}
+declare const InputLine: import("svelte").Component<Props, {}, "">;
+type InputLine = ReturnType<typeof InputLine>;
+export default InputLine;

package/dist/shell-shard/ScrollbackView.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+  import type { Scrollback } from './scrollback.svelte';
+  import TextEntry from './entries/TextEntry.svelte';
+  import PromptEntry from './entries/PromptEntry.svelte';
+  import StatusEntry from './entries/StatusEntry.svelte';
+  import RichEntry from './entries/RichEntry.svelte';
+
+  interface Props {
+    scrollback: Scrollback;
+  }
+  let { scrollback }: Props = $props();
+
+  let container: HTMLDivElement | null = $state(null);
+
+  // Auto-scroll to bottom on new entries
+  $effect(() => {
+    // Depend on entries length so the effect re-runs
+    const _len = scrollback.entries.length;
+    void _len;
+    if (container) {
+      container.scrollTop = container.scrollHeight;
+    }
+  });
+</script>
+
+<div class="shell-scrollback" bind:this={container}>
+  {#each scrollback.entries as entry (entry.id)}
+    {#if entry.kind === 'text'}
+      <TextEntry stream={entry.stream} chunks={entry.chunks} />
+    {:else if entry.kind === 'prompt'}
+      <PromptEntry cwd={entry.cwd} line={entry.line} />
+    {:else if entry.kind === 'status'}
+      <StatusEntry text={entry.text} level={entry.level} />
+    {:else if entry.kind === 'rich'}
+      <RichEntry component={entry.component} componentProps={entry.props} />
+    {/if}
+  {/each}
+</div>
+
+<style>
+  .shell-scrollback {
+    flex: 1 1 auto;
+    overflow-y: auto;
+    background: var(--shell-bg, #111);
+    color: var(--shell-fg, #ddd);
+  }
+</style>

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

@@ -0,0 +1,7 @@
+import type { Scrollback } from './scrollback.svelte';
+interface Props {
+    scrollback: Scrollback;
+}
+declare const ScrollbackView: import("svelte").Component<Props, {}, "">;
+type ScrollbackView = ReturnType<typeof ScrollbackView>;
+export default ScrollbackView;

package/dist/shell-shard/Terminal.svelte

@@ -0,0 +1,122 @@
+<script lang="ts">
+  import { onMount, onDestroy, untrack } from 'svelte';
+  import { Scrollback } from './scrollback.svelte';
+  import ScrollbackView from './ScrollbackView.svelte';
+  import InputLine from './InputLine.svelte';
+  import { SessionClient } from './session-client.svelte';
+  import { VerbRegistry, type ShellApi } from './registry';
+  import { registerV1Verbs } from './verbs';
+  import type { ServerMessage } from './protocol';
+
+  interface Props {
+    shell: ShellApi;
+    wsUrl: string;
+  }
+  let { shell, wsUrl }: Props = $props();
+
+  const scrollback = new Scrollback();
+  // 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 registry = new VerbRegistry();
+  registerV1Verbs(registry);
+
+  let locked = $state(false);
+
+  async function dispatch(line: string): Promise<void> {
+    const resolution = registry.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(),
+        });
+      }
+    } else {
+      // Forward to server
+      session.send({ t: 'submit', line: resolution.line });
+    }
+  }
+
+  function handleServerMessage(msg: ServerMessage) {
+    if (msg.t !== 'event') return;
+    const e = msg.event;
+    switch (e.kind) {
+      case 'prompt':
+        scrollback.push({ kind: 'prompt', cwd: e.cwd, line: e.line, ts: e.ts });
+        locked = true;
+        break;
+      case 'stdout':
+        scrollback.push({ kind: 'text', stream: 'stdout', chunks: [e.data], ts: e.ts });
+        break;
+      case 'stderr':
+        scrollback.push({ kind: 'text', stream: 'stderr', chunks: [e.data], ts: e.ts });
+        break;
+      case 'exit':
+        scrollback.push({
+          kind: 'status',
+          text: e.signal
+            ? `shell: process exited (${e.signal})`
+            : `shell: process exited (${e.code ?? 0})`,
+          level: e.code === 0 || e.code === null ? 'info' : 'error',
+          ts: e.ts,
+        });
+        locked = false;
+        break;
+      case 'status':
+        scrollback.push({ kind: 'status', text: e.text, level: e.level, ts: e.ts });
+        break;
+    }
+  }
+
+  let unsub: (() => void) | null = null;
+
+  onMount(() => {
+    unsub = session.onMessage(handleServerMessage);
+    session.connect();
+  });
+
+  onDestroy(() => {
+    unsub?.();
+    session.close();
+  });
+</script>
+
+<div class="shell-terminal">
+  <ScrollbackView {scrollback} />
+  <InputLine
+    cwd={session.cwd}
+    {locked}
+    history={session.history}
+    {session}
+    onSubmit={dispatch}
+  />
+</div>
+
+<style>
+  .shell-terminal {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+    background: var(--shell-bg, #111);
+    color: var(--shell-fg, #ddd);
+  }
+</style>

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

@@ -0,0 +1,8 @@
+import { type ShellApi } from './registry';
+interface Props {
+    shell: ShellApi;
+    wsUrl: string;
+}
+declare const Terminal: import("svelte").Component<Props, {}, "">;
+type Terminal = ReturnType<typeof Terminal>;
+export default Terminal;

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

@@ -0,0 +1,25 @@
+<script lang="ts">
+  interface Props {
+    cwd: string;
+    line: string;
+  }
+  let { cwd, line }: Props = $props();
+</script>
+
+<div class="shell-prompt">
+  <span class="shell-prompt-cwd">{cwd}</span>
+  <span class="shell-prompt-arrow">❯</span>
+  <span class="shell-prompt-line">{line}</span>
+</div>
+
+<style>
+  .shell-prompt {
+    padding: 4px 8px 0 8px;
+    font-family: var(--shell-font-mono, monospace);
+    display: flex;
+    gap: 8px;
+  }
+  .shell-prompt-cwd { color: var(--shell-fg-muted, #888); }
+  .shell-prompt-arrow { color: var(--shell-accent, #6cf); }
+  .shell-prompt-line { color: var(--shell-fg, #ddd); }
+</style>

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

@@ -0,0 +1,7 @@
+interface Props {
+    cwd: string;
+    line: string;
+}
+declare const PromptEntry: import("svelte").Component<Props, {}, "">;
+type PromptEntry = ReturnType<typeof PromptEntry>;
+export default PromptEntry;

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

@@ -0,0 +1,19 @@
+<script lang="ts">
+  import type { Component } from 'svelte';
+
+  interface Props {
+    component: Component;
+    componentProps: Record<string, unknown>;
+  }
+  let { component: C, componentProps }: Props = $props();
+</script>
+
+<div class="shell-rich">
+  <C {...componentProps} />
+</div>
+
+<style>
+  .shell-rich {
+    padding: 4px 8px;
+  }
+</style>

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

@@ -0,0 +1,8 @@
+import type { Component } from 'svelte';
+interface Props {
+    component: Component;
+    componentProps: Record<string, unknown>;
+}
+declare const RichEntry: Component<Props, {}, "">;
+type RichEntry = ReturnType<typeof RichEntry>;
+export default RichEntry;

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

@@ -0,0 +1,22 @@
+<script lang="ts">
+  interface Props {
+    text: string;
+    level: 'info' | 'warn' | 'error';
+  }
+  let { text, level }: Props = $props();
+</script>
+
+<div class="shell-status" class:info={level === 'info'} class:warn={level === 'warn'} class:error={level === 'error'}>
+  {text}
+</div>
+
+<style>
+  .shell-status {
+    padding: 2px 8px;
+    font-family: var(--shell-font-mono, monospace);
+    font-style: italic;
+  }
+  .shell-status.info { color: var(--shell-fg-muted, #888); }
+  .shell-status.warn { color: var(--shell-fg-warn, #fc6); }
+  .shell-status.error { color: var(--shell-fg-error, #f88); }
+</style>

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

@@ -0,0 +1,7 @@
+interface Props {
+    text: string;
+    level: 'info' | 'warn' | 'error';
+}
+declare const StatusEntry: import("svelte").Component<Props, {}, "">;
+type StatusEntry = ReturnType<typeof StatusEntry>;
+export default StatusEntry;