sh3-core 0.1.0

package/dist/state/zones.svelte.js

@@ -0,0 +1,141 @@
+/*
+ * createStateZones — turns a declarative zone schema into live reactive
+ * per-zone objects backed by the right store for each zone.
+ *
+ * Usage (from a shard, or the shell itself):
+ *
+ *   const state = createStateZones('graphlive', {
+ *     ephemeral: { hoveredId: null as string | null },
+ *     session:   { lastFocus: null as string | null },
+ *     workspace: { collapsed: false, panelSizes: [0.3, 0.7] },
+ *     user:      { showIcons: true },
+ *   });
+ *
+ *   state.workspace.collapsed = true;   // persists to localStorage
+ *   state.ephemeral.hoveredId = 'foo';  // in-memory only
+ *
+ * Guarantees (phase 3 subset of docs/design/state-zones.md):
+ *   - Hydration before return: persistent zones are populated from the
+ *     backend before this function returns, so reads in the next line of
+ *     user code see persisted values.
+ *   - Debounced flush: writes within the same microtask coalesce to a
+ *     single backend write per (zone, shardId).
+ *   - Atomicity per write: each flush serializes a full zone snapshot.
+ *   - Isolation: zone data is keyed by shardId; shards cannot collide.
+ *
+ * Lifetime management (tracking teardown on shard deactivation) arrives in
+ * phase 4 when the shard contract exists. For phase 3, roots live until the
+ * page unloads, which is fine for a single-session shell.
+ *
+ * This file must be `.svelte.ts` so it can use the Svelte 5 runes
+ * `$state`, `$effect.root`, `$effect`, and `$state.snapshot` at module level.
+ */
+import { MemoryBackend, LocalStorageBackend } from './backends';
+import { PERSISTENT_ZONES } from './types';
+const backends = {
+    ephemeral: new MemoryBackend(),
+    session: new MemoryBackend(),
+    workspace: new LocalStorageBackend('sh3:workspace:'),
+    user: new LocalStorageBackend('sh3:user:'),
+};
+const pending = new Map();
+let flushScheduled = false;
+function scheduleFlush(zone, shardId, value) {
+    pending.set(`${zone}:${shardId}`, { zone, shardId, value });
+    if (flushScheduled)
+        return;
+    flushScheduled = true;
+    queueMicrotask(() => {
+        flushScheduled = false;
+        for (const { zone, shardId, value } of pending.values()) {
+            backends[zone].write(shardId, value);
+        }
+        pending.clear();
+    });
+}
+/**
+ * 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 function createStateZones(shardId, schema) {
+    const result = {};
+    for (const key of Object.keys(schema)) {
+        const defaults = schema[key];
+        const backend = backends[key];
+        // Hydrate: shallow-merge stored values over the schema defaults so new
+        // fields added to the schema in a later version get their defaults even
+        // for shards whose backend entries predate them.
+        const stored = backend.read(shardId);
+        const initial = Object.assign(Object.assign({}, defaults), (stored !== null && stored !== void 0 ? stored : {}));
+        // The reactive proxy. Deep reactivity via $state lets shards mutate
+        // nested fields (e.g. state.workspace.panelSizes[0] = 0.4) and still
+        // trigger the flush effect.
+        const proxy = $state(initial);
+        result[key] = proxy;
+        // Set up change tracking for persistent zones. Memory-only zones don't
+        // need it: nothing reads from them beyond the in-process proxy.
+        if (!PERSISTENT_ZONES.includes(key))
+            continue;
+        // $effect.root creates a standalone reactivity scope outside any
+        // component. The returned cleanup is intentionally not captured in
+        // phase 3 — see the "Lifetime management" note at the top of the file.
+        $effect.root(() => {
+            let first = true;
+            $effect(() => {
+                // $state.snapshot deeply reads every reactive field, which both
+                // establishes dependency tracking and produces a plain-object copy
+                // safe to hand to the backend.
+                const snap = $state.snapshot(proxy);
+                if (first) {
+                    first = false;
+                    return; // don't write back the just-hydrated value
+                }
+                scheduleFlush(key, shardId, snap);
+            });
+        });
+    }
+    return result;
+}
+// ---------- test hooks ----------------------------------------------------
+/**
+ * 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 function __setBackend(zone, backend) {
+    backends[zone] = backend;
+}
+/**
+ * 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 function peekZone(zone, shardId) {
+    return backends[zone].read(shardId);
+}
+/**
+ * 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 function clearZone(zone, shardId) {
+    backends[zone].delete(shardId);
+}

package/dist/store/InstalledView.svelte

@@ -0,0 +1,201 @@
+<script lang="ts">
+  /*
+   * InstalledView — lists installed packages with uninstall capability.
+   *
+   * Simpler than the browse view: a flat list of installed packages with
+   * metadata (type, version, contract version, source registry, install date)
+   * and an uninstall button per entry.
+   */
+
+  import { storeContext } from './storeShard.svelte';
+  import { uninstallPackage } from '../registry/installer';
+
+  const ctx = storeContext;
+
+  let uninstallingIds = $state<Set<string>>(new Set());
+
+  async function handleUninstall(id: string) {
+    if (uninstallingIds.has(id)) return;
+
+    uninstallingIds = new Set([...uninstallingIds, id]);
+    try {
+      await uninstallPackage(id);
+      await ctx.refreshInstalled();
+    } catch (err) {
+      console.warn('[sh3-store] Uninstall failed:', err instanceof Error ? err.message : err);
+    } finally {
+      const next = new Set(uninstallingIds);
+      next.delete(id);
+      uninstallingIds = next;
+    }
+  }
+
+  function handleRefresh() {
+    ctx.refreshInstalled();
+  }
+
+  function formatDate(iso: string): string {
+    try {
+      return new Date(iso).toLocaleDateString(undefined, {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+      });
+    } catch {
+      return iso;
+    }
+  }
+</script>
+
+<div class="installed-view">
+  <header class="installed-header">
+    <h2>Installed Packages</h2>
+    <button class="installed-refresh" onclick={handleRefresh}>Refresh</button>
+  </header>
+
+  {#if ctx.state.ephemeral.installed.length === 0}
+    <div class="installed-empty">No packages installed.</div>
+  {:else}
+    <ul class="installed-list">
+      {#each ctx.state.ephemeral.installed as pkg (pkg.id)}
+        {@const uninstalling = uninstallingIds.has(pkg.id)}
+        <li class="installed-item">
+          <div class="installed-item-main">
+            <span class="installed-item-id">{pkg.id}</span>
+            <span class="installed-item-badge" class:badge-shard={pkg.type === 'shard'} class:badge-app={pkg.type === 'app'}>
+              {pkg.type}
+            </span>
+            <span class="installed-item-version">{pkg.version}</span>
+          </div>
+          <div class="installed-item-meta">
+            <span>Contract: v{pkg.contractVersion}</span>
+            <span>Source: {pkg.sourceRegistry}</span>
+            <span>Installed: {formatDate(pkg.installedAt)}</span>
+          </div>
+          <div class="installed-item-actions">
+            <button
+              class="installed-uninstall-btn"
+              onclick={() => handleUninstall(pkg.id)}
+              disabled={uninstalling}
+            >
+              {uninstalling ? 'Removing...' : 'Uninstall'}
+            </button>
+          </div>
+        </li>
+      {/each}
+    </ul>
+  {/if}
+</div>
+
+<style>
+  .installed-view {
+    font-family: var(--shell-font, system-ui, sans-serif);
+    color: var(--shell-fg, #e0e0e0);
+    background: var(--shell-bg, #1e1e1e);
+    padding: 16px;
+    height: 100%;
+    overflow-y: auto;
+    box-sizing: border-box;
+  }
+  .installed-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 16px;
+  }
+  .installed-header h2 {
+    margin: 0;
+    font-size: 1.25rem;
+    font-weight: 600;
+  }
+  .installed-refresh {
+    padding: 6px 14px;
+    background: var(--shell-accent, #007acc);
+    color: #fff;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+    font-family: inherit;
+    font-size: 0.875rem;
+  }
+  .installed-empty {
+    text-align: center;
+    padding: 32px 16px;
+    color: var(--shell-fg-muted, #888);
+    font-size: 0.875rem;
+  }
+  .installed-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  .installed-item {
+    background: var(--shell-input-bg, #2a2a2a);
+    border: 1px solid var(--shell-border, #444);
+    border-radius: 6px;
+    padding: 12px 14px;
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+  }
+  .installed-item-main {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+  .installed-item-id {
+    font-weight: 600;
+    font-size: 0.9375rem;
+  }
+  .installed-item-badge {
+    font-size: 0.6875rem;
+    padding: 1px 6px;
+    border-radius: 3px;
+    text-transform: uppercase;
+    font-weight: 600;
+    letter-spacing: 0.04em;
+  }
+  .badge-shard {
+    background: color-mix(in srgb, var(--shell-accent, #007acc) 25%, transparent);
+    color: var(--shell-accent, #007acc);
+  }
+  .badge-app {
+    background: color-mix(in srgb, var(--shell-success, #4caf50) 25%, transparent);
+    color: var(--shell-success, #4caf50);
+  }
+  .installed-item-version {
+    font-size: 0.75rem;
+    color: var(--shell-fg-muted, #888);
+  }
+  .installed-item-meta {
+    display: flex;
+    gap: 16px;
+    flex-wrap: wrap;
+    font-size: 0.75rem;
+    color: var(--shell-fg-muted, #888);
+  }
+  .installed-item-actions {
+    display: flex;
+    justify-content: flex-end;
+  }
+  .installed-uninstall-btn {
+    padding: 4px 12px;
+    background: transparent;
+    color: var(--shell-error, #d32f2f);
+    border: 1px solid var(--shell-error, #d32f2f);
+    border-radius: 4px;
+    cursor: pointer;
+    font-family: inherit;
+    font-size: 0.8125rem;
+  }
+  .installed-uninstall-btn:hover:not(:disabled) {
+    background: color-mix(in srgb, var(--shell-error, #d32f2f) 15%, transparent);
+  }
+  .installed-uninstall-btn:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+  }
+</style>

package/dist/store/InstalledView.svelte.d.ts

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