sh3-core 0.1.0

package/dist/shell-shard/ShellHome.svelte

@@ -0,0 +1,285 @@
+<script lang="ts">
+  /*
+   * Shell home — the view shown when no app is active. Sections:
+   *   1. User apps — always visible
+   *   2. Admin apps — visible when elevated (admin mode)
+   *   3. Elevate prompt — shown when not elevated
+   */
+
+  import { listRegisteredApps, launchApp, isAdmin } from '../api';
+  import { elevate, deescalate } from '../auth/index';
+  import { adminAppIds } from '../host';
+
+  const apps = $derived(listRegisteredApps());
+  const userApps = $derived(apps.filter(m => !adminAppIds.has(m.id)));
+  const adminApps = $derived(apps.filter(m => adminAppIds.has(m.id)));
+  const elevated = $derived(isAdmin());
+
+  let keyInput = $state('');
+  let elevateError = $state<string | null>(null);
+  let elevating = $state(false);
+
+  async function handleElevate() {
+    if (!keyInput.trim() || elevating) return;
+    elevating = true;
+    elevateError = null;
+    const ok = await elevate(keyInput.trim());
+    if (!ok) {
+      elevateError = 'Invalid API key';
+    }
+    keyInput = '';
+    elevating = false;
+  }
+
+  function handleDeescalate() {
+    deescalate();
+  }
+</script>
+
+<div class="shell-home">
+  <header class="shell-home-header">
+    <h1>SH3</h1>
+    <span class="shell-home-alpha">alpha</span>
+    {#if elevated}
+      <button type="button" class="shell-home-deescalate" onclick={handleDeescalate}>
+        Exit admin mode
+      </button>
+    {/if}
+  </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}
+    {#if 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}
+  {:else}
+    <section class="shell-home-section">
+      <h2 class="shell-home-section-title">Admin Mode</h2>
+      <p class="shell-home-elevate-hint">
+        Enter an API key to access admin apps like the Package Store.
+      </p>
+      <form class="shell-home-elevate-form" onsubmit={(e) => { e.preventDefault(); handleElevate(); }}>
+        <input
+          class="shell-home-key-input"
+          type="password"
+          placeholder="API key"
+          bind:value={keyInput}
+          disabled={elevating}
+        />
+        <button
+          type="submit"
+          class="shell-home-elevate-btn"
+          disabled={elevating || !keyInput.trim()}
+        >
+          {elevating ? 'Verifying...' : 'Elevate'}
+        </button>
+      </form>
+      {#if elevateError}
+        <div class="shell-home-elevate-error">{elevateError}</div>
+      {/if}
+    </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-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-header h1 {
+    margin: 0;
+    font-size: 42px;
+    color: var(--shell-accent);
+    letter-spacing: 2px;
+  }
+  .shell-home-alpha {
+    font-size: 11px;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: #fff;
+    background: var(--shell-accent);
+    padding: 2px 10px;
+    border-radius: 10px;
+  }
+  .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-bg-elevated);
+    border: 1px solid var(--shell-border);
+    border-radius: 6px;
+  }
+  .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;
+    background: var(--shell-accent);
+    color: var(--shell-bg);
+    border: none;
+    border-radius: 4px;
+    font-weight: 600;
+    cursor: pointer;
+  }
+  .shell-home-launch:hover {
+    filter: brightness(1.1);
+  }
+  .shell-home-deescalate {
+    padding: 6px 12px;
+    background: transparent;
+    color: var(--shell-fg-subtle);
+    border: 1px solid var(--shell-border);
+    border-radius: 4px;
+    cursor: pointer;
+    font-size: 12px;
+  }
+  .shell-home-deescalate:hover {
+    color: var(--shell-fg);
+    border-color: var(--shell-fg-subtle);
+  }
+  .shell-home-elevate-hint {
+    margin: 0 0 12px;
+    font-size: 13px;
+    color: var(--shell-fg-muted);
+  }
+  .shell-home-elevate-form {
+    display: flex;
+    gap: 8px;
+  }
+  .shell-home-key-input {
+    flex: 1;
+    padding: 8px 12px;
+    background: var(--shell-bg-elevated);
+    color: var(--shell-fg);
+    border: 1px solid var(--shell-border);
+    border-radius: 4px;
+    font-family: monospace;
+    font-size: 13px;
+  }
+  .shell-home-key-input::placeholder {
+    color: var(--shell-fg-muted);
+  }
+  .shell-home-elevate-btn {
+    padding: 8px 16px;
+    background: var(--shell-accent);
+    color: var(--shell-bg);
+    border: none;
+    border-radius: 4px;
+    font-weight: 600;
+    cursor: pointer;
+    white-space: nowrap;
+  }
+  .shell-home-elevate-btn:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+  }
+  .shell-home-elevate-error {
+    margin-top: 8px;
+    padding: 6px 10px;
+    font-size: 12px;
+    color: var(--shell-error, #d32f2f);
+    background: color-mix(in srgb, var(--shell-error, #d32f2f) 10%, transparent);
+    border-radius: 4px;
+  }
+</style>

package/dist/shell-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/shell-shard/shellShard.svelte.d.ts

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

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

@@ -0,0 +1,47 @@
+/*
+ * Shell pseudo-shard — the framework-owned shard with reserved id
+ * `__shell__`. Contributes exactly one view, `shell:home`, which the
+ * layout manager's home tree references.
+ *
+ * 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 `__shell__`
+ *   - 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';
+export const shellShard = {
+    manifest: {
+        id: '__shell__',
+        label: 'SH3 Shell',
+        version: '0.1.0',
+        views: [{ id: 'shell: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('shell:home', factory);
+    },
+    autostart() {
+        // Intentionally empty. Defining this field is what puts the shell
+        // pseudo-shard on the self-starting path at boot (see bootstrap),
+        // so `shell:home` is available before any app launches.
+    },
+};

package/dist/shellRuntime.svelte.d.ts

@@ -0,0 +1,27 @@
+import type { StateZones } from './state/zones.svelte';
+import type { ZoneSchema } from './state/types';
+import { type ModalManager } from './overlays/modal';
+import { type PopupManager } from './overlays/popup';
+import { type ToastManager } from './overlays/toast';
+/**
+ * The process-wide shell singleton exposed to shards and the shell's own
+ * internal code. Provides state zone creation and overlay managers.
+ * Shards receive a pre-bound version via `ShardContext` rather than
+ * accessing `shell` directly.
+ */
+export interface Shell {
+    /**
+     * Declare the state zones a shard (or the shell itself) wants to use.
+     * Returns a live reactive object per declared zone. Persistent zones
+     * are hydrated from the backend before the call returns.
+     */
+    state<T extends ZoneSchema>(shardId: string, schema: T): StateZones<T>;
+    /** Stackable, focus-trapped dialogs. See overlays/modal.ts. */
+    modal: ModalManager;
+    /** Anchored, single-item, outside-click-dismissable popups. */
+    popup: PopupManager;
+    /** Auto-dismissing notification toasts. */
+    toast: ToastManager;
+}
+/** The process-wide shell instance. Framework-internal code uses this directly; shards receive a scoped view via `ShardContext`. */
+export declare const shell: Shell;

package/dist/shellRuntime.svelte.js

@@ -0,0 +1,27 @@
+/*
+ * shell — the framework-facing entry point passed to shards.
+ *
+ * Conceptually this is the object a shard receives from its activation
+ * callback; it exposes the APIs the shard is allowed to touch.
+ *
+ *   Phase 3: state zones.
+ *   Phase 4: registerView (lives on ShardContext, not here).
+ *   Phase 5: modal / popup / toast overlay managers.
+ *
+ * For now `shell` is a module-level singleton. Once the shard lifecycle
+ * exists in a fuller form, per-shard shells will be constructed per
+ * activation with the shardId baked in, so shards no longer need to pass
+ * their own id to `state`. Overlay managers stay process-wide because
+ * the layer stack is a shell-global resource.
+ */
+import { createStateZones } from './state/zones.svelte';
+import { modalManager } from './overlays/modal';
+import { popupManager } from './overlays/popup';
+import { toastManager } from './overlays/toast';
+/** The process-wide shell instance. Framework-internal code uses this directly; shards receive a scoped view via `ShardContext`. */
+export const shell = {
+    state: createStateZones,
+    modal: modalManager,
+    popup: popupManager,
+    toast: toastManager,
+};

package/dist/state/backends.d.ts

@@ -0,0 +1,26 @@
+import type { Backend } from './types';
+export declare class MemoryBackend implements Backend {
+    #private;
+    read(shardId: string): unknown | undefined;
+    write(shardId: string, value: unknown): void;
+    delete(shardId: string): void;
+    list(): string[];
+}
+/**
+ * Persists one JSON blob per shardId under a prefixed localStorage key.
+ *
+ * Keys are of the form `${prefix}${shardId}`. Each zone that uses this
+ * backend picks its own prefix so keys don't collide across zones (e.g.
+ * `sh3:workspace:` for the workspace zone, `sh3:user:` for the user zone).
+ *
+ * Values are JSON-serialized; non-serializable values are silently dropped
+ * by `JSON.stringify`. Callers are expected to keep zone contents plain.
+ */
+export declare class LocalStorageBackend implements Backend {
+    #private;
+    constructor(prefix: string);
+    read(shardId: string): unknown | undefined;
+    write(shardId: string, value: unknown): void;
+    delete(shardId: string): void;
+    list(): string[];
+}

package/dist/state/backends.js

@@ -0,0 +1,99 @@
+/*
+ * Backend implementations for phase 3.
+ *
+ *   MemoryBackend       — ephemeral/session zones (and tests)
+ *   LocalStorageBackend — workspace/user zones on web
+ *
+ * Tauri FS backends, IndexedDB, and remote sync are deferred per the
+ * roadmap. Any future backend need only conform to the `Backend` interface
+ * in ./types.ts for shard code to work against it unchanged.
+ */
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _MemoryBackend_map, _LocalStorageBackend_prefix;
+export class MemoryBackend {
+    constructor() {
+        _MemoryBackend_map.set(this, new Map());
+    }
+    read(shardId) {
+        return __classPrivateFieldGet(this, _MemoryBackend_map, "f").get(shardId);
+    }
+    write(shardId, value) {
+        __classPrivateFieldGet(this, _MemoryBackend_map, "f").set(shardId, value);
+    }
+    delete(shardId) {
+        __classPrivateFieldGet(this, _MemoryBackend_map, "f").delete(shardId);
+    }
+    list() {
+        return [...__classPrivateFieldGet(this, _MemoryBackend_map, "f").keys()];
+    }
+}
+_MemoryBackend_map = new WeakMap();
+/**
+ * Persists one JSON blob per shardId under a prefixed localStorage key.
+ *
+ * Keys are of the form `${prefix}${shardId}`. Each zone that uses this
+ * backend picks its own prefix so keys don't collide across zones (e.g.
+ * `sh3:workspace:` for the workspace zone, `sh3:user:` for the user zone).
+ *
+ * Values are JSON-serialized; non-serializable values are silently dropped
+ * by `JSON.stringify`. Callers are expected to keep zone contents plain.
+ */
+export class LocalStorageBackend {
+    constructor(prefix) {
+        _LocalStorageBackend_prefix.set(this, void 0);
+        __classPrivateFieldSet(this, _LocalStorageBackend_prefix, prefix, "f");
+    }
+    read(shardId) {
+        if (typeof localStorage === 'undefined')
+            return undefined;
+        const raw = localStorage.getItem(__classPrivateFieldGet(this, _LocalStorageBackend_prefix, "f") + shardId);
+        if (raw == null)
+            return undefined;
+        try {
+            return JSON.parse(raw);
+        }
+        catch (_a) {
+            // Corrupt entry — treat as missing rather than crashing the shard.
+            return undefined;
+        }
+    }
+    write(shardId, value) {
+        if (typeof localStorage === 'undefined')
+            return;
+        try {
+            localStorage.setItem(__classPrivateFieldGet(this, _LocalStorageBackend_prefix, "f") + shardId, JSON.stringify(value));
+        }
+        catch (_a) {
+            // Quota exceeded or serialization failure — swallow for phase 3;
+            // phase "post-prototype" will surface a proper error channel.
+        }
+    }
+    delete(shardId) {
+        if (typeof localStorage === 'undefined')
+            return;
+        localStorage.removeItem(__classPrivateFieldGet(this, _LocalStorageBackend_prefix, "f") + shardId);
+    }
+    list() {
+        if (typeof localStorage === 'undefined')
+            return [];
+        const out = [];
+        for (let i = 0; i < localStorage.length; i++) {
+            const key = localStorage.key(i);
+            if (key && key.startsWith(__classPrivateFieldGet(this, _LocalStorageBackend_prefix, "f"))) {
+                out.push(key.slice(__classPrivateFieldGet(this, _LocalStorageBackend_prefix, "f").length));
+            }
+        }
+        return out;
+    }
+}
+_LocalStorageBackend_prefix = new WeakMap();

package/dist/state/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The four state zones available to shards. Each zone has different lifetime
+ * and persistence semantics:
+ * - `ephemeral`: in-memory only; cleared when the shard is unloaded.
+ * - `session`: in-memory only; cleared when the app is closed.
+ * - `workspace`: persisted to localStorage; survives page reload.
+ * - `user`: persisted to localStorage; shared across all workspaces for this user.
+ */
+export type ZoneName = 'ephemeral' | 'session' | 'workspace' | 'user';
+/** Zones whose contents are flushed to a persistent backend on change. */
+export declare const PERSISTENT_ZONES: readonly ZoneName[];
+/**
+ * A backend is a tiny KV store keyed by shardId. Each zone owns one backend.
+ * Values are arbitrary JSON-serializable objects — the backend is responsible
+ * for any (de)serialization needed for its medium.
+ *
+ * Future backends: IndexedDB, Tauri FS, remote sync — all conform to this
+ * interface so shard code is unaffected by deployment target.
+ */
+export interface Backend {
+    /** Read the stored value for a shard. Returns undefined if not present. */
+    read(shardId: string): unknown | undefined;
+    /** Write (create or overwrite) the stored value for a shard. */
+    write(shardId: string, value: unknown): void;
+    /** Delete the stored value for a shard. No-op if not present. */
+    delete(shardId: string): void;
+    /** Return all shard ids that have stored entries in this backend. */
+    list(): string[];
+}
+/**
+ * A zone schema is a record of zone name → initial state object. Any subset
+ * of zones may be declared; unused zones are simply omitted. Values inside
+ * each zone object become the defaults used when the backend has no prior
+ * entry for this shard.
+ */
+export type ZoneSchema = {
+    [K in ZoneName]?: Record<string, unknown>;
+};

package/dist/state/types.js

@@ -0,0 +1,15 @@
+/*
+ * State zone types — framework plumbing for docs/design/state-zones.md.
+ *
+ * Phase 3 implements four of the six zones:
+ *   ephemeral   — in-memory, cleared on shard unload
+ *   session     — in-memory, cleared on app close
+ *   workspace   — persisted (localStorage KV for web)
+ *   user        — persisted (localStorage KV for web)
+ *
+ * Deferred until later phases:
+ *   document    — file-on-disk (phase "post-prototype")
+ *   shared      — lives on the bus, not storage (not a zone in the same sense)
+ */
+/** Zones whose contents are flushed to a persistent backend on change. */
+export const PERSISTENT_ZONES = ['workspace', 'user'];

package/dist/state/zones.svelte.d.ts

@@ -0,0 +1,52 @@
+import type { Backend, ZoneName, ZoneSchema } from './types';
+/**
+ * Live reactive state object returned by `createStateZones`. Each key
+ * mirrors a zone declared in the schema; the value is a deeply-reactive
+ * proxy of the same shape. Undeclared zones are absent from the result.
+ *
+ * @typeParam T - The `ZoneSchema` used to declare zones and their defaults.
+ */
+export type StateZones<T extends ZoneSchema> = {
+    [K in keyof T]: T[K];
+};
+/**
+ * Create live reactive state zones for a shard (or the shell itself).
+ *
+ * Each zone declared in `schema` is backed by the appropriate store:
+ * `ephemeral` and `session` are in-memory; `workspace` and `user` are
+ * persisted to localStorage and hydrated before this call returns.
+ *
+ * Writes to persistent zones are debounced and coalesced per microtask.
+ * Zones not declared in `schema` are not created; the result only
+ * contains the keys the caller asked for.
+ *
+ * @param shardId - Unique shard identifier used as the storage namespace.
+ * @param schema  - Record of zone names to their default values.
+ * @returns A reactive `StateZones<T>` object keyed to the declared zones.
+ */
+export declare function createStateZones<T extends ZoneSchema>(shardId: string, schema: T): StateZones<T>;
+/**
+ * Swap a backend implementation. Intended for tests and for phase 4+ when
+ * Tauri or IndexedDB backends replace the defaults. Not part of the shard-
+ * facing API.
+ */
+export declare function __setBackend(zone: ZoneName, backend: Backend): void;
+/**
+ * Read a raw persisted zone entry without creating a reactive proxy.
+ *
+ * Intended for framework-internal consumers (e.g. the shell's layout
+ * persistence) that need to inspect a stored value before deciding
+ * whether to pass it to `createStateZones`. Not part of the shard-facing
+ * API — shards always go through `createStateZones` so hydration is
+ * reactive and debounced-flush applies.
+ *
+ * Returns `undefined` for missing, corrupt, or memory-only-zone entries
+ * that have no stored value.
+ */
+export declare function peekZone(zone: ZoneName, shardId: string): unknown | undefined;
+/**
+ * Delete a persisted zone entry. Intended for framework-internal use
+ * when a stored value is known to be incompatible (version mismatch,
+ * corruption) and should be removed before `createStateZones` hydrates.
+ */
+export declare function clearZone(zone: ZoneName, shardId: string): void;