sh3-core 0.6.0

package/dist/sh3core-shard/ShellHome.svelte

@@ -0,0 +1,192 @@
+<script lang="ts">
+  /*
+   * Shell home — the view shown when no app is active. Sections:
+   *   1. User apps — always visible
+   *   2. Admin apps — visible when user has admin role
+   */
+
+  import { listRegisteredApps, launchApp, isAdmin, VERSION } from '../api';
+  import ShellTitle from './ShellTitle.svelte';
+
+  const apps = $derived(listRegisteredApps());
+  const userApps = $derived(apps.filter(m => !m.admin));
+  const adminApps = $derived(apps.filter(m => m.admin));
+  const elevated = $derived(isAdmin());
+</script>
+
+<div class="shell-home">
+  <header class="shell-home-header">
+    <div class="shell-home-title-row">
+      <ShellTitle/>
+      <span class="shell-home-version">v{VERSION}</span>
+      <span class="shell-home-alpha">alpha</span>
+    </div>
+    <div class="shell-home-credit">
+      Art: by <a href="https://www.andbc.co/" target="_blank" rel="noopener noreferrer">andbc</a>
+    </div>
+  </header>
+
+  {#if userApps.length > 0}
+    <section class="shell-home-section">
+      <h2 class="shell-home-section-title">Apps</h2>
+      <ul class="shell-home-list">
+        {#each userApps as manifest (manifest.id)}
+          <li class="shell-home-entry">
+            <div class="shell-home-entry-label">{manifest.label}</div>
+            <div class="shell-home-entry-meta">
+              {manifest.id} · v{manifest.version}
+            </div>
+            <button
+              type="button"
+              class="shell-home-launch"
+              onclick={() => launchApp(manifest.id)}
+            >
+              Launch
+            </button>
+          </li>
+        {/each}
+      </ul>
+    </section>
+  {/if}
+
+  {#if elevated && adminApps.length > 0}
+    <section class="shell-home-section">
+      <h2 class="shell-home-section-title">Admin</h2>
+      <ul class="shell-home-list">
+        {#each adminApps as manifest (manifest.id)}
+          <li class="shell-home-entry">
+            <div class="shell-home-entry-label">{manifest.label}</div>
+            <div class="shell-home-entry-meta">
+              {manifest.id} · v{manifest.version}
+            </div>
+            <button
+              type="button"
+              class="shell-home-launch"
+              onclick={() => launchApp(manifest.id)}
+            >
+              Launch
+            </button>
+          </li>
+        {/each}
+      </ul>
+    </section>
+  {/if}
+
+  {#if userApps.length === 0 && (!elevated || adminApps.length === 0)}
+    <p class="shell-home-empty">No apps registered.</p>
+  {/if}
+</div>
+
+<style>
+  .shell-home {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: flex-start;
+    padding: 48px 24px;
+    overflow: auto;
+    background: var(--shell-grad-bg, var(--shell-bg));
+    color: var(--shell-fg);
+    font-family: system-ui, sans-serif;
+  }
+  .shell-home-header {
+    text-align: center;
+    margin-bottom: 32px;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 12px;
+  }
+  .shell-home-title-row {
+    display: flex;
+    align-items: baseline;
+    gap: 6px;
+  }
+  .shell-home-credit {
+    font-size: 11px;
+    color: var(--shell-fg-muted);
+    letter-spacing: 0.04em;
+    margin-top: -4px;
+  }
+  .shell-home-credit a {
+    color: var(--shell-fg-subtle);
+    text-decoration: none;
+    border-bottom: 1px dotted var(--shell-fg-muted);
+  }
+  .shell-home-credit a:hover {
+    color: var(--shell-accent);
+    border-bottom-color: var(--shell-accent);
+  }
+  .shell-home-version {
+    font-size: 14px;
+    color: var(--shell-fg-subtle);
+    letter-spacing: 0.04em;
+  }
+  .shell-home-alpha {
+    font-size: 10px;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: #fff;
+    background: var(--shell-accent);
+    padding: 2px 8px;
+    border-radius: 8px;
+    position: relative;
+    top: -1px;
+  }
+  .shell-home-empty {
+    color: var(--shell-fg-muted);
+    font-style: italic;
+  }
+  .shell-home-section {
+    width: 100%;
+    max-width: 440px;
+    margin-bottom: 24px;
+  }
+  .shell-home-section-title {
+    font-size: 13px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--shell-fg-subtle);
+    margin: 0 0 12px;
+  }
+  .shell-home-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+  }
+  .shell-home-entry {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    grid-template-rows: auto auto;
+    gap: 4px 16px;
+    align-items: center;
+    padding: 14px 18px;
+    background: var(--shell-grad-bg-elevated, var(--shell-bg-elevated));
+    border: 1px solid var(--shell-border);
+    border-radius: var(--shell-radius-md);
+  }
+  .shell-home-entry-label {
+    grid-column: 1;
+    grid-row: 1;
+    font-weight: 600;
+  }
+  .shell-home-entry-meta {
+    grid-column: 1;
+    grid-row: 2;
+    font-size: 11px;
+    color: var(--shell-fg-subtle);
+  }
+  .shell-home-launch {
+    grid-column: 2;
+    grid-row: 1 / span 2;
+    padding: 8px 16px;
+    font-weight: 600;
+  }
+</style>

package/dist/sh3core-shard/ShellHome.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const ShellHome: import("svelte").Component<Record<string, never>, {}, "">;
+type ShellHome = ReturnType<typeof ShellHome>;
+export default ShellHome;

package/dist/sh3core-shard/ShellTitle.svelte

@@ -0,0 +1,171 @@
+<script lang="ts" module>
+  /*
+   * p5 is loaded from a CDN rather than bundled, to keep sh3-core's
+   * footprint small. The promise is cached at module scope so repeated
+   * mounts reuse a single <script> injection.
+   */
+  const P5_CDN = 'https://cdn.jsdelivr.net/npm/p5@1.11.13/lib/p5.min.js';
+  let p5Promise: Promise<any> | null = null;
+
+  function loadP5(): Promise<any> {
+    if (p5Promise) return p5Promise;
+    p5Promise = new Promise((resolve, reject) => {
+      const existing = (window as any).p5;
+      if (existing) {
+        resolve(existing);
+        return;
+      }
+      const s = document.createElement('script');
+      s.src = P5_CDN;
+      s.async = true;
+      s.onload = () => resolve((window as any).p5);
+      s.onerror = (err) => {
+        p5Promise = null;
+        reject(err);
+      };
+      document.head.appendChild(s);
+    });
+    return p5Promise;
+  }
+</script>
+
+<script lang="ts">
+  import sh3Img from '../assets/SH3.png';
+
+  const CHARS = '`.-\':;,^"~=+<>*?!/\\|()[]{}x1ltzrcvunsXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$';
+  const ASCII_W = 64;
+  const ASCII_H = Math.floor(64 / (442 / 193));  // ~28, matches image ratio
+  const CELL_W = 8;
+  const CELL_H = 7;
+  const DISPLAY_H = 80;  // rendered CSS height in px; width auto-derived from aspect ratio
+  // Canvas keeps its native pixel buffer (ASCII_W*CELL_W × ASCII_H*CELL_H) for full
+  // text resolution; CSS transform scales the painted output down to DISPLAY_H, and
+  // the container is sized to the scaled dimensions so layout sees the visible size.
+  const NATIVE_W = ASCII_W * CELL_W;
+  const NATIVE_H = ASCII_H * CELL_H;
+  const SCALE = DISPLAY_H / NATIVE_H;
+  const DISPLAY_W = NATIVE_W * SCALE;
+
+  let container = $state<HTMLDivElement | undefined>(undefined);
+  let p5inst: any = null;
+  let failed = $state(false);
+
+  const buildSketch = () => (p: any) => {
+    const rootStyle = getComputedStyle(document.documentElement);
+    const accentColor = rootStyle.getPropertyValue('--shell-accent').trim();
+    let gfx: any;
+    let src: any;
+    let ready = false;
+
+    p.setup = () => {
+      // Create the canvas synchronously in setup, otherwise p5 will auto-create
+      // a default 100x100 canvas and a later createCanvas() call would produce
+      // a SECOND canvas rather than replacing the first.
+      p.createCanvas(NATIVE_W, NATIVE_H);
+
+      p.noSmooth();
+      p.noStroke();
+      p.textAlign(p.CENTER, p.CENTER);
+      p.textFont('monospace');
+      p.textSize(10);
+      p.textStyle(p.BOLD);
+
+      src = p.loadImage(
+        sh3Img,
+        () => {
+          gfx = p.createGraphics(ASCII_W, ASCII_H);
+          gfx.pixelDensity(1);
+          gfx.image(src, 0, 0, ASCII_W, ASCII_H);
+          gfx.loadPixels();
+          ready = true;
+        },
+        () => { failed = true; },
+      );
+    };
+
+    p.draw = () => {
+      if (!ready) return;
+      const t = p.millis() * 0.001;
+      let n: number;
+
+      p.clear();
+      p.background(0, 0);
+      p.fill(accentColor);
+
+      for (let y = 0; y < ASCII_H; y++) {
+        for (let x = 0; x < ASCII_W; x++) {
+          const i = (y * ASCII_W + x) * 4;
+          if (gfx.pixels[i] < 64) {
+            n = p.noise(x / ASCII_W * 2.0, y / ASCII_H * 2.0, t * 0.15);
+            if (n > 0.33) continue;
+            p.text(CHARS[Math.floor(n * CHARS.length * 0.25)], (x + 0.5) * CELL_W, (y + 0.5) * CELL_H);
+            continue;
+          }
+          n = p.noise(x / ASCII_W * 4.0, y / ASCII_H * 4.0, t * 0.5);
+          p.text(CHARS[Math.floor(n * CHARS.length)], (x + 0.5) * CELL_W, (y + 0.5) * CELL_H);
+        }
+      }
+    };
+  };
+
+  $effect(() => {
+    if (failed) return;
+    let cancelled = false;
+    loadP5()
+      .then((P5) => {
+        if (cancelled || !container) return;
+        try {
+          p5inst = new P5(buildSketch(), container);
+        } catch (err) {
+          console.error('[ShellTitle] p5 sketch failed to start', err);
+          failed = true;
+        }
+      })
+      .catch((err) => {
+        console.error('[ShellTitle] failed to load p5 from CDN', err);
+        failed = true;
+      });
+
+    return () => {
+      cancelled = true;
+      if (p5inst) {
+        p5inst.remove();
+        p5inst = null;
+      }
+    };
+  });
+</script>
+
+{#if failed}
+  <h1 class="shell-title-fallback">SH3</h1>
+{:else}
+  <div
+    bind:this={container}
+    class="shell-title"
+    style:width="{DISPLAY_W}px"
+    style:height="{DISPLAY_H}px"
+    style:--shell-title-scale={SCALE}
+  ></div>
+{/if}
+
+<style>
+  .shell-title {
+    display: inline-block;
+    line-height: 0;
+    overflow: hidden;
+  }
+  /* canvas is injected by p5 at runtime, so scoped selectors don't reach it */
+  .shell-title :global(canvas) {
+    transform: scale(var(--shell-title-scale));
+    transform-origin: top left;
+    /* p5 sets inline width/height attributes on the canvas; override its inline
+       style so layout doesn't get the intrinsic pixel-buffer size. */
+    display: block;
+  }
+  .shell-title-fallback {
+    margin: 0;
+    font-size: 42px;
+    color: var(--shell-accent);
+    letter-spacing: 2px;
+  }
+</style>

package/dist/sh3core-shard/ShellTitle.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const ShellTitle: import("svelte").Component<Record<string, never>, {}, "">;
+type ShellTitle = ReturnType<typeof ShellTitle>;
+export default ShellTitle;

package/dist/sh3core-shard/sh3coreShard.svelte.d.ts

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

package/dist/sh3core-shard/sh3coreShard.svelte.js

@@ -0,0 +1,53 @@
+/*
+ * SH3-core pseudo-shard — the framework-owned shard with reserved id
+ * `__sh3core__`. Contributes exactly one view, `sh3core:home`, which the
+ * layout manager's home tree references.
+ *
+ * Renamed from the former `__shell__` pseudo-shard on 2026-04-10 to free
+ * the `shell` id and the `src/shell-shard/` directory for the new
+ * user-facing shell-shard (terminal). See
+ * `docs/superpowers/specs/2026-04-10-shell-shard-design.md` § Step 0.
+ *
+ * This shard uses the public contract same as any other shard (see
+ * ADR-008 / the phase-8 shell-as-shard feasibility check). Its only
+ * concession to being framework-owned is:
+ *   - The reserved id `__sh3core__`
+ *   - It is registered by `bootstrap()` itself, not by the glob loop
+ *
+ * Activation goes through the same `registerShard` / `activateShard`
+ * pipeline as mock and diagnostic. `autostart` is a no-op, defined only
+ * so activation is driven by the self-starting pass in bootstrap rather
+ * than by requiring a special code path.
+ *
+ * `.svelte.ts` because mounting Svelte components requires rune access.
+ */
+import { mount, unmount } from 'svelte';
+import ShellHome from './ShellHome.svelte';
+import { VERSION } from '../version';
+export const sh3coreShard = {
+    manifest: {
+        id: '__sh3core__',
+        label: 'SH3 Core',
+        version: VERSION,
+        views: [{ id: 'sh3core:home', label: 'Home' }],
+    },
+    activate(ctx) {
+        const factory = {
+            mount(container, _context) {
+                const instance = mount(ShellHome, { target: container });
+                return {
+                    unmount() {
+                        unmount(instance);
+                    },
+                    // Home does not need onResize — it uses absolute inset:0 layout.
+                };
+            },
+        };
+        ctx.registerView('sh3core:home', factory);
+    },
+    autostart() {
+        // Intentionally empty. Defining this field is what puts the sh3core
+        // pseudo-shard on the self-starting path at boot (see bootstrap),
+        // so `sh3core:home` is available before any app launches.
+    },
+};

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

@@ -0,0 +1,52 @@
+import type { Shard, ShardContext } from './types';
+/**
+ * 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
+ * `registerShard`); a future runtime loader appends late without touching
+ * the rest of the framework. Callers that need a live list subscribe via
+ * Svelte reactivity (e.g. shell home listing apps cross-references this
+ * map to show which shards they require).
+ */
+export declare const registeredShards: Map<string, Shard>;
+export declare const activeShards: Map<string, Shard>;
+/**
+ * Register (or re-register) a shard with the framework so it can later be
+ * activated. Records the shard in `registeredShards` but does not run
+ * `activate` — that happens at app launch (or for self-starting shards).
+ *
+ * If a shard with the same id already exists it is silently replaced,
+ * which is the expected path during package updates. If the old shard was
+ * active it is deactivated first so the new version can be cleanly
+ * activated on next launch.
+ */
+export declare function registerShard(shard: Shard): void;
+/**
+ * Activate a registered shard. Builds a `ShardContext`, calls `shard.activate`,
+ * verifies that every view declared in the manifest received a factory, then
+ * calls `shard.autostart` if defined. Idempotent — calling on an already-active
+ * shard is a no-op.
+ *
+ * @param id - The `ShardManifest.id` of the shard to activate. Must be registered.
+ * @throws If the shard is not registered, or if a manifest view has no factory after activation.
+ */
+export declare function activateShard(id: string): Promise<void>;
+/**
+ * Deactivate an active shard. Calls `shard.deactivate`, flushes and disposes
+ * all document handles, unregisters all view factories, and removes the shard
+ * from `activeShards`. The shard remains in `registeredShards` and can be
+ * re-activated. No-op if the shard is not currently active.
+ *
+ * @param id - The `ShardManifest.id` of the shard to deactivate.
+ */
+export declare function deactivateShard(id: string): void;
+/**
+ * Return true if the shard with the given id is currently active.
+ *
+ * @param id - The `ShardManifest.id` to check.
+ */
+export declare function isActive(id: string): boolean;
+/**
+ * Return the ShardContext for an active shard, or undefined if not active.
+ * Used by lifecycle.ts to pass context to `shard.resume()`.
+ */
+export declare function getShardContext(id: string): ShardContext | undefined;

package/dist/shards/activate.svelte.js

@@ -0,0 +1,186 @@
+/*
+ * Shard lifecycle — phase 8 split into register and activate.
+ *
+ * registerShard(shard): adds the shard's manifest to the reactive
+ *   `registeredShards` map. No side effects. The host (main.ts) calls
+ *   this once per shard via its glob-discovery boot loop. A future
+ *   runtime loader calls it after fetching a shard module.
+ *
+ * activateShard(id): looks up a registered shard, builds its
+ *   ShardContext, runs `activate(ctx)`, verifies every manifest view id
+ *   received a factory, then runs `autostart(ctx)` if present. The shard
+ *   moves into the reactive `activeShards` map. Called internally by
+ *   app launch and by the bootstrap self-starting pass. Not public.
+ *
+ * deactivateShard(id): inverse of activate. Calls `deactivate()`,
+ *   unregisters view factories, drops from `activeShards`. The shard
+ *   stays in `registeredShards` — it's still known, just not running.
+ */
+import { shell } from '../shellRuntime.svelte';
+import { registerView, unregisterView } from './registry';
+import { createDocumentHandle, getTenantId, getDocumentBackend } from '../documents';
+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';
+/**
+ * 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
+ * `registerShard`); a future runtime loader appends late without touching
+ * the rest of the framework. Callers that need a live list subscribe via
+ * Svelte reactivity (e.g. shell home listing apps cross-references this
+ * map to show which shards they require).
+ */
+export const registeredShards = $state(new Map());
+/**
+ * Reactive map of currently-active shards. A shard lands here when
+ * `activateShard` runs successfully and stays until `deactivateShard`.
+ */
+const active = new Map();
+export const activeShards = $state(new Map());
+/**
+ * Register (or re-register) a shard with the framework so it can later be
+ * activated. Records the shard in `registeredShards` but does not run
+ * `activate` — that happens at app launch (or for self-starting shards).
+ *
+ * If a shard with the same id already exists it is silently replaced,
+ * which is the expected path during package updates. If the old shard was
+ * active it is deactivated first so the new version can be cleanly
+ * activated on next launch.
+ */
+export function registerShard(shard) {
+    const id = shard.manifest.id;
+    if (registeredShards.has(id) && activeShards.has(id)) {
+        deactivateShard(id);
+    }
+    registeredShards.set(id, shard);
+}
+/**
+ * Activate a registered shard. Builds a `ShardContext`, calls `shard.activate`,
+ * verifies that every view declared in the manifest received a factory, then
+ * calls `shard.autostart` if defined. Idempotent — calling on an already-active
+ * shard is a no-op.
+ *
+ * @param id - The `ShardManifest.id` of the shard to activate. Must be registered.
+ * @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;
+    const shard = registeredShards.get(id);
+    if (!shard) {
+        throw new Error(`Cannot activate shard "${id}": not registered`);
+    }
+    if (active.has(id)) {
+        // Already active (e.g. self-starting shard that was activated at boot
+        // and is now being required by an app). Idempotent — no error.
+        return;
+    }
+    const entry = { shard, ctx: undefined, viewIds: new Set(), cleanupFns: [] };
+    // envState holds the reactive env data for this shard.
+    // Must be declared with $state at variable declaration time (Svelte 5 rule).
+    const envState = $state({
+        proxy: null,
+        defaults: null,
+    });
+    const ctx = {
+        state: (schema) => shell.state(id, schema),
+        registerView: (viewId, factory) => {
+            registerView(viewId, factory);
+            entry.viewIds.add(viewId);
+        },
+        documents: (options) => {
+            const handle = createDocumentHandle(getTenantId(), id, getDocumentBackend(), options);
+            entry.cleanupFns.push(() => handle.dispose());
+            return handle;
+        },
+        env(defaults) {
+            if (envState.proxy) {
+                console.warn(`[sh3] Shard "${id}" called ctx.env() more than once; extra calls are ignored.`);
+                return envState.proxy;
+            }
+            envState.defaults = defaults;
+            envState.proxy = Object.assign({}, defaults);
+            return envState.proxy;
+        },
+        async envUpdate(patch) {
+            if (!envState.proxy || !envState.defaults) {
+                throw new Error(`Shard "${id}" called envUpdate() without declaring env state`);
+            }
+            const previous = $state.snapshot(envState.proxy);
+            Object.assign(envState.proxy, patch);
+            try {
+                const snapshot = $state.snapshot(envState.proxy);
+                await putEnvState(id, snapshot);
+            }
+            catch (err) {
+                Object.assign(envState.proxy, previous);
+                throw err;
+            }
+        },
+        get isAdmin() {
+            return checkIsAdmin();
+        },
+        zones: ((_a = shard.manifest.permissions) === null || _a === void 0 ? void 0 : _a.includes(PERMISSION_STATE_MANAGE))
+            ? createZoneManager()
+            : undefined,
+    };
+    entry.ctx = ctx;
+    active.set(id, entry);
+    activeShards.set(id, shard);
+    await shard.activate(ctx);
+    for (const view of shard.manifest.views) {
+        if (!entry.viewIds.has(view.id)) {
+            throw new Error(`Shard "${id}" declared view "${view.id}" in its manifest but registered no factory for it.`);
+        }
+    }
+    // Hydrate env state if the shard declared it via ctx.env().
+    if (envState.proxy && envState.defaults) {
+        try {
+            const stored = await fetchEnvState(id);
+            const merged = Object.assign({}, envState.defaults, stored);
+            Object.assign(envState.proxy, merged);
+        }
+        catch (err) {
+            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));
+}
+/**
+ * Deactivate an active shard. Calls `shard.deactivate`, flushes and disposes
+ * all document handles, unregisters all view factories, and removes the shard
+ * from `activeShards`. The shard remains in `registeredShards` and can be
+ * re-activated. No-op if the shard is not currently active.
+ *
+ * @param id - The `ShardManifest.id` of the shard to deactivate.
+ */
+export function deactivateShard(id) {
+    var _a, _b;
+    const entry = active.get(id);
+    if (!entry)
+        return;
+    void ((_b = (_a = entry.shard).deactivate) === null || _b === void 0 ? void 0 : _b.call(_a));
+    // Flush and dispose document handles before tearing down views.
+    for (const fn of entry.cleanupFns)
+        void fn();
+    for (const viewId of entry.viewIds)
+        unregisterView(viewId);
+    active.delete(id);
+    activeShards.delete(id);
+}
+/**
+ * Return true if the shard with the given id is currently active.
+ *
+ * @param id - The `ShardManifest.id` to check.
+ */
+export function isActive(id) {
+    return active.has(id);
+}
+/**
+ * Return the ShardContext for an active shard, or undefined if not active.
+ * Used by lifecycle.ts to pass context to `shard.resume()`.
+ */
+export function getShardContext(id) {
+    var _a;
+    return (_a = active.get(id)) === null || _a === void 0 ? void 0 : _a.ctx;
+}

package/dist/shards/registry.d.ts

@@ -0,0 +1,4 @@
+import type { ViewFactory } from './types';
+export declare function registerView(viewId: string, factory: ViewFactory): void;
+export declare function getView(viewId: string): ViewFactory | undefined;
+export declare function unregisterView(viewId: string): void;