@happyvertical/smrt-svelte 0.38.1 → 0.38.3

package/AGENTS.md

@@ -263,6 +263,23 @@ compatibility.
 
 See `src/components/workspace/MIGRATION.md` for the old-to-new concept map.
 
+### Live activity feed adapter (`./web`, #1779)
+
+`activityFeed({ collection, map, shell })` (from `@happyvertical/smrt-svelte/web`)
+bridges a `@happyvertical/smrt-web` live collection into a `ShellState` activity
+registry: it subscribes the collection through `liveCollection`, reactively maps
+each row → `ShellActivity` via the app-supplied editorial `map`, and drives
+`upsertActivity` / `updateActivity` / `removeActivity` as rows appear, change,
+and vanish (a row mapping to `null` is excluded / retracted). Returns a disposer
+that removes exactly the activities it created. Must be called during component
+init (installs a `$effect`); the subscription tears down on unmount.
+
+It lives behind the opt-in `./web` entry — which pulls the TanStack client-data
+engine — and is **never** imported under `components/workspace/`, so the
+AdminShell core (`./workspace`) stays transport-agnostic and TanStack-free (epic
+#1766). The pure diff core is `ActivityFeedReconciler` (engine-free, unit-tested
+against a real `ShellState`). Demo: `playground/.../admin-shell-activity-feed`.
+
 ### Dock availability gates (server-side)
 
 `ToolDef.gates?: string[]` declares the gates a tool must pass to be visible.

package/dist/components/workspace/NavTree.svelte

@@ -76,7 +76,7 @@ function checkExpanded(item: NavItem): boolean {
  */
 function checkEffectiveActive(item: NavItem): boolean {
   if (checkActive(item)) return true;
-  if (collapsed && !!item.children?.length && checkParentActive(item))
+  if (collapsed && item.children?.length && checkParentActive(item))
     return true;
   return false;
 }

package/dist/components/workspace/__tests__/system-feed.test.js

@@ -0,0 +1,327 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { systemFeed } from '../live/system-feed.svelte.js';
+/**
+ * Lifecycle tests for the `systemFeed` polling helper (#1774). Real Svelte
+ * `$state` reactivity + vitest fake timers; only the external `fetch` is
+ * mocked. Each `dispose()`s its feed in `afterEach` to avoid leaked intervals.
+ */
+const disposers = [];
+function track(controller) {
+    disposers.push(() => controller.dispose());
+    return controller;
+}
+/** Flush the interval + the async tick's microtasks. */
+async function advance(ms) {
+    await vi.advanceTimersByTimeAsync(ms);
+}
+function panel(id, itemCount) {
+    return {
+        id,
+        label: id,
+        items: Array.from({ length: itemCount }, (_, index) => ({
+            id: `${id}-${index}`,
+            label: `${id} ${index}`,
+            status: 'running',
+        })),
+    };
+}
+beforeEach(() => {
+    vi.useFakeTimers();
+});
+afterEach(() => {
+    while (disposers.length > 0)
+        disposers.pop()?.();
+    vi.useRealTimers();
+    // Restore any spies (e.g. document.hidden / addEventListener) so they cannot
+    // leak into later tests or files.
+    vi.restoreAllMocks();
+});
+describe('systemFeed', () => {
+    it('fetches immediately and maps the response into panels and chips', async () => {
+        const fetch = vi.fn().mockResolvedValue({ jobs: 2 });
+        const feed = track(systemFeed({
+            fetch,
+            intervalMs: 1000,
+            pauseWhenHidden: false,
+            map: (data) => ({
+                panels: [panel('jobs', data.jobs)],
+                chips: [{ id: 'jobs', label: 'Jobs', value: data.jobs }],
+            }),
+        }));
+        // Immediate tick is queued synchronously; flush its microtasks.
+        await advance(0);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        expect(feed.status).toBe('success');
+        expect(feed.panels).toHaveLength(1);
+        expect(feed.panels[0]?.items).toHaveLength(2);
+        expect(feed.chips[0]?.value).toBe(2);
+        expect(feed.running).toBe(true);
+    });
+    it('polls again on each interval tick', async () => {
+        const fetch = vi.fn().mockResolvedValue({ ok: true });
+        track(systemFeed({
+            fetch,
+            intervalMs: 1000,
+            pauseWhenHidden: false,
+            map: () => ({}),
+        }));
+        await advance(0); // immediate
+        expect(fetch).toHaveBeenCalledTimes(1);
+        await advance(1000);
+        expect(fetch).toHaveBeenCalledTimes(2);
+        await advance(3000);
+        expect(fetch).toHaveBeenCalledTimes(5);
+    });
+    it('stops polling after the disposer runs', async () => {
+        const fetch = vi.fn().mockResolvedValue({ ok: true });
+        const feed = systemFeed({
+            fetch,
+            intervalMs: 1000,
+            pauseWhenHidden: false,
+            map: () => ({}),
+        });
+        await advance(0);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        feed.dispose();
+        expect(feed.running).toBe(false);
+        expect(feed.status).toBe('stopped');
+        await advance(5000);
+        // No further ticks after disposal.
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
+    it('stop() halts the timer while start() re-arms it', async () => {
+        const fetch = vi.fn().mockResolvedValue({ ok: true });
+        const feed = track(systemFeed({
+            fetch,
+            intervalMs: 1000,
+            pauseWhenHidden: false,
+            map: () => ({}),
+        }));
+        await advance(0);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        feed.stop();
+        expect(feed.running).toBe(false);
+        await advance(3000);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        feed.start();
+        expect(feed.running).toBe(true);
+        await advance(1000);
+        expect(fetch).toHaveBeenCalledTimes(2);
+    });
+    it('tolerates a rejected fetch without stopping the loop and keeps prior data', async () => {
+        const onError = vi.fn();
+        const fetch = vi
+            .fn()
+            .mockResolvedValueOnce({ n: 1 })
+            .mockRejectedValueOnce(new Error('boom'))
+            .mockResolvedValue({ n: 3 });
+        const feed = track(systemFeed({
+            fetch,
+            intervalMs: 1000,
+            pauseWhenHidden: false,
+            onError,
+            map: (data) => ({
+                chips: [{ id: 'n', label: 'N', value: data.n }],
+            }),
+        }));
+        await advance(0);
+        expect(feed.chips[0]?.value).toBe(1);
+        expect(feed.status).toBe('success');
+        // Second tick rejects.
+        await advance(1000);
+        expect(onError).toHaveBeenCalledTimes(1);
+        expect(feed.status).toBe('error');
+        expect(feed.error).toBeInstanceOf(Error);
+        // Last good data stays on screen.
+        expect(feed.chips[0]?.value).toBe(1);
+        // Third tick recovers.
+        await advance(1000);
+        expect(feed.status).toBe('success');
+        expect(feed.error).toBeNull();
+        expect(feed.chips[0]?.value).toBe(3);
+    });
+    it('tolerates a throwing mapper as a failed tick', async () => {
+        const fetch = vi.fn().mockResolvedValue({ bad: true });
+        const feed = track(systemFeed({
+            fetch,
+            intervalMs: 1000,
+            pauseWhenHidden: false,
+            map: () => {
+                throw new Error('map failed');
+            },
+        }));
+        await advance(0);
+        expect(feed.status).toBe('error');
+        expect(feed.error).toBeInstanceOf(Error);
+        // Loop survives.
+        await advance(1000);
+        expect(fetch).toHaveBeenCalledTimes(2);
+    });
+    it('does not fetch on creation when immediate is false', async () => {
+        const fetch = vi.fn().mockResolvedValue({ ok: true });
+        const feed = track(systemFeed({
+            fetch,
+            intervalMs: 1000,
+            immediate: false,
+            pauseWhenHidden: false,
+            map: () => ({}),
+        }));
+        await advance(0);
+        expect(fetch).not.toHaveBeenCalled();
+        expect(feed.status).toBe('idle');
+        // First real load is the timer tick.
+        await advance(1000);
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
+    it('runs a single fetch with no timer when intervalMs <= 0', async () => {
+        const fetch = vi.fn().mockResolvedValue({ ok: true });
+        const feed = track(systemFeed({
+            fetch,
+            intervalMs: 0,
+            pauseWhenHidden: false,
+            map: () => ({}),
+        }));
+        await advance(0);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        // No timer is armed, so `running` stays false (it tracks an armed timer).
+        expect(feed.running).toBe(false);
+        await advance(10_000);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        // Manual refresh still works.
+        await feed.refresh();
+        expect(fetch).toHaveBeenCalledTimes(2);
+    });
+    it('refresh() fetches once off-schedule', async () => {
+        const fetch = vi.fn().mockResolvedValue({ ok: true });
+        const feed = track(systemFeed({
+            fetch,
+            intervalMs: 0,
+            immediate: false,
+            pauseWhenHidden: false,
+            map: () => ({}),
+        }));
+        await advance(0);
+        expect(fetch).not.toHaveBeenCalled();
+        await feed.refresh();
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
+    it('skips ticks while the document is hidden and refreshes on becoming visible', async () => {
+        let hidden = false;
+        const listeners = [];
+        vi.spyOn(document, 'hidden', 'get').mockImplementation(() => hidden);
+        const addSpy = vi
+            .spyOn(document, 'addEventListener')
+            .mockImplementation((type, cb) => {
+            if (type === 'visibilitychange')
+                listeners.push(cb);
+        });
+        const removeSpy = vi
+            .spyOn(document, 'removeEventListener')
+            .mockImplementation(() => { });
+        const fetch = vi.fn().mockResolvedValue({ ok: true });
+        const feed = track(systemFeed({
+            fetch,
+            intervalMs: 1000,
+            // pauseWhenHidden defaults to true.
+            map: () => ({}),
+        }));
+        // Immediate tick while visible.
+        await advance(0);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        // Go hidden — timer ticks are skipped.
+        hidden = true;
+        await advance(3000);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        // Back to visible — the visibilitychange listener refreshes once.
+        hidden = false;
+        for (const cb of listeners)
+            cb();
+        await advance(0);
+        expect(fetch).toHaveBeenCalledTimes(2);
+        feed.dispose();
+        expect(removeSpy).toHaveBeenCalledWith('visibilitychange', expect.any(Function));
+        addSpy.mockRestore();
+        removeSpy.mockRestore();
+    });
+    it('supersedes an in-flight fetch so a stale response cannot clobber newer data', async () => {
+        let resolveFirst;
+        const fetch = vi
+            .fn()
+            .mockImplementationOnce(() => new Promise((resolve) => {
+            resolveFirst = resolve;
+        }))
+            .mockResolvedValue({ n: 2 });
+        const feed = track(systemFeed({
+            fetch,
+            intervalMs: 0,
+            immediate: false,
+            pauseWhenHidden: false,
+            map: (data) => ({
+                chips: [{ id: 'n', label: 'N', value: data.n }],
+            }),
+        }));
+        // Start a slow first fetch (never resolved yet).
+        const first = feed.refresh();
+        // Start a second fetch that resolves immediately; it supersedes the first.
+        await feed.refresh();
+        expect(feed.chips[0]?.value).toBe(2);
+        // Now let the stale first fetch resolve — it must be ignored.
+        resolveFirst?.({ n: 1 });
+        await first;
+        expect(feed.chips[0]?.value).toBe(2);
+    });
+    it('contains a throwing onError callback (no unhandled rejection)', async () => {
+        const unhandled = vi.fn();
+        process.on('unhandledRejection', unhandled);
+        const onError = vi.fn(() => {
+            throw new Error('consumer onError blew up');
+        });
+        const fetch = vi.fn().mockRejectedValue(new Error('fetch failed'));
+        const feed = track(systemFeed({
+            fetch,
+            intervalMs: 0,
+            immediate: false,
+            pauseWhenHidden: false,
+            onError,
+            map: () => ({}),
+        }));
+        // The failing fetch invokes the throwing onError; the tick must still
+        // resolve rather than reject.
+        await expect(feed.refresh()).resolves.toBeUndefined();
+        expect(onError).toHaveBeenCalled();
+        expect(feed.status).toBe('error');
+        // Give any stray rejection a chance to surface, then assert none did.
+        await advance(0);
+        process.off('unhandledRejection', unhandled);
+        expect(unhandled).not.toHaveBeenCalled();
+    });
+    it('does not refresh on becoming visible after stop()', async () => {
+        let hidden = false;
+        const listeners = [];
+        vi.spyOn(document, 'hidden', 'get').mockImplementation(() => hidden);
+        vi.spyOn(document, 'addEventListener').mockImplementation((type, cb) => {
+            if (type === 'visibilitychange')
+                listeners.push(cb);
+        });
+        vi.spyOn(document, 'removeEventListener').mockImplementation(() => { });
+        const fetch = vi.fn().mockResolvedValue({ ok: true });
+        const feed = track(systemFeed({
+            fetch,
+            intervalMs: 1000,
+            map: () => ({}),
+        }));
+        await advance(0);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        // Pause polling (but the visibility listener is still attached — only
+        // dispose() detaches it).
+        feed.stop();
+        expect(feed.running).toBe(false);
+        // A hidden -> visible transition must NOT resurrect polling while stopped.
+        hidden = true;
+        hidden = false;
+        for (const cb of listeners)
+            cb();
+        await advance(0);
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/components/workspace/live/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@happyvertical/smrt-svelte/workspace/live`
+ *
+ * Opt-in, transport-light live-data helpers for the AdminShell system scope.
+ *
+ * This subpath is intentionally separate from the `./workspace` presentation
+ * barrel and the `./web` (smrt-web / TanStack) entry. The system scope shows
+ * jobs / schedules / dispatch, which live in `_smrt_*` system tables that the
+ * core change-feed skips and smrt-web does not expose as collections — so this
+ * layer polls an app-provided status endpoint rather than a live collection,
+ * and carries no smrt-web dependency.
+ *
+ * See `src/components/workspace/live/system-feed.recipe.md` for wiring an app
+ * jobs-status endpoint (server reads `_smrt_*` via `@happyvertical/smrt-jobs`).
+ */
+export { type SystemFeedController, type SystemFeedOptions, type SystemFeedStatus, type SystemFeedView, systemFeed, } from './system-feed.svelte.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/workspace/live/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/components/workspace/live/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,UAAU,GACX,MAAM,yBAAyB,CAAC"}

package/dist/components/workspace/live/index.js

@@ -0,0 +1,16 @@
+/**
+ * `@happyvertical/smrt-svelte/workspace/live`
+ *
+ * Opt-in, transport-light live-data helpers for the AdminShell system scope.
+ *
+ * This subpath is intentionally separate from the `./workspace` presentation
+ * barrel and the `./web` (smrt-web / TanStack) entry. The system scope shows
+ * jobs / schedules / dispatch, which live in `_smrt_*` system tables that the
+ * core change-feed skips and smrt-web does not expose as collections — so this
+ * layer polls an app-provided status endpoint rather than a live collection,
+ * and carries no smrt-web dependency.
+ *
+ * See `src/components/workspace/live/system-feed.recipe.md` for wiring an app
+ * jobs-status endpoint (server reads `_smrt_*` via `@happyvertical/smrt-jobs`).
+ */
+export { systemFeed, } from './system-feed.svelte.js';

package/dist/components/workspace/live/system-feed.recipe.md

@@ -0,0 +1,169 @@
+# Recipe: live system-scope data with `systemFeed`
+
+The AdminShell **system scope** (the bottom edge) shows operational data — jobs,
+schedules, dispatch, worker liveness. That data lives in the `_smrt_*` **system
+tables**, which are intentionally outside the reactive path used for tenant/app
+data:
+
+- The core change-feed **skips** every `_smrt_*` table
+  (`packages/core/src/change-feed.ts`).
+- `smrt-web` does **not** expose these as collections.
+
+So the system scope is not fed by `liveCollection()`. Instead the **app owns a
+status endpoint** that reads `_smrt_*` on the server, and the browser **polls**
+it with `systemFeed` from `@happyvertical/smrt-svelte/workspace/live`. This
+subpath is transport-light — it pulls no `smrt-web` / TanStack dependency.
+
+## 1. Server: expose a jobs-status endpoint
+
+Read the system tables through the `@happyvertical/smrt-jobs` query API
+(`SmrtJobCollection`, `SmrtWorkerCollection`, …) — never hand-write SQL against
+`_smrt_*`. A SvelteKit `+server.ts` is shown; any framework's request handler
+works the same way.
+
+```ts
+// src/routes/admin/system/status/+server.ts
+import { json } from '@sveltejs/kit';
+import { getDatabase } from '@happyvertical/sql';
+import { SmrtJobCollection, SmrtWorkerCollection } from '@happyvertical/smrt-jobs';
+
+export async function GET() {
+  const db = await getDatabase(/* your app's connection options */);
+  const jobs = await SmrtJobCollection.create({ db });
+  const workers = await SmrtWorkerCollection.create({ db });
+
+  // Collections read the `_smrt_*` system tables for you.
+  const recent = await jobs.list({ orderBy: 'created_at DESC', limit: 20 });
+  const live = await workers.list({ limit: 50 });
+
+  const counts = { queued: 0, running: 0, failed: 0 };
+  for (const job of recent) {
+    if (job.status === 'pending') counts.queued += 1;
+    else if (job.status === 'running') counts.running += 1;
+    else if (job.status === 'failed') counts.failed += 1;
+  }
+
+  return json({
+    generatedAt: new Date().toISOString(),
+    counts,
+    workers: live.length,
+    // SmrtJob is a method-dispatch row: `queue` / `objectType` / `method` /
+    // `status` / `lastError` — there is no free-text "name" column, so build a
+    // label from the fields that exist.
+    jobs: recent.map((job) => ({
+      id: job.id,
+      label: `${job.objectType}.${job.method}`,
+      queue: job.queue,
+      status: job.status,
+      detail: job.lastError ?? undefined,
+      updatedAt: job.updatedAt,
+    })),
+  });
+}
+```
+
+Guard the route with your own auth/permissions (e.g. the `smrt-users`
+`PermissionResolver`) — it exposes operational internals.
+
+## 2. Client: poll it and map into the shell contracts
+
+`systemFeed({ fetch, intervalMs, map })` calls your `fetch` on an interval and
+maps the response into `ShellSystemPanel[]` (for `SystemScopePanel`) and
+`ShellStatusChip[]` (for `SystemStatusChips`). It returns a controller whose
+`panels` / `chips` are `$state`-reactive; bind them straight to the components
+and call `dispose()` on teardown.
+
+```svelte
+<script lang="ts">
+  import { onDestroy } from 'svelte';
+  import { systemFeed } from '@happyvertical/smrt-svelte/workspace/live';
+  import {
+    SystemScopePanel,
+    SystemStatusChips,
+    type ShellStatusChip,
+    type ShellSystemPanel,
+  } from '@happyvertical/smrt-svelte/workspace';
+
+  interface SystemStatus {
+    counts: { queued: number; running: number; failed: number };
+    workers: number;
+    jobs: Array<{
+      id: string;
+      label: string;
+      queue: string;
+      status: string;
+      detail?: string;
+      updatedAt?: string;
+    }>;
+  }
+
+  const feed = systemFeed<SystemStatus>({
+    // App-owned transport — the helper only calls it.
+    fetch: (signal) =>
+      fetch('/admin/system/status', { signal }).then((r) => r.json()),
+    intervalMs: 5000,
+    map: (status) => ({
+      chips: [
+        { id: 'workers', label: 'Workers', value: status.workers, tone: 'info' },
+        {
+          id: 'running',
+          label: 'Running',
+          value: status.counts.running,
+          tone: 'success',
+        },
+        {
+          id: 'failed',
+          label: 'Failed',
+          value: status.counts.failed,
+          tone: status.counts.failed > 0 ? 'error' : 'neutral',
+        },
+      ] satisfies ShellStatusChip[],
+      panels: [
+        {
+          id: 'jobs',
+          label: 'Jobs',
+          items: status.jobs.map((job) => ({
+            id: job.id,
+            label: job.label,
+            status: job.status,
+            detail: job.detail,
+            updatedAt: job.updatedAt,
+          })),
+        },
+      ] satisfies ShellSystemPanel[],
+    }),
+  });
+
+  onDestroy(feed.dispose);
+</script>
+
+<SystemStatusChips chips={feed.chips} />
+<SystemScopePanel panels={feed.panels} />
+```
+
+Wire those two snippets into the shell's `systemBar` / `systemPanel` slots as
+usual (see `SystemScopePanel` / `SystemStatusChips`).
+
+## Behavior notes
+
+- **Immediate first load** — fetches once on creation (disable with
+  `immediate: false`), then every `intervalMs`. `intervalMs <= 0` disables the
+  timer (single fetch; drive further loads with `refresh()`).
+- **Errors are tolerated** — a rejected `fetch` or a throwing `map` sets
+  `status: 'error'` and `error`, calls `onError`, and keeps polling. The last
+  good `panels` / `chips` stay on screen.
+- **Backgrounded tabs** — with the default `pauseWhenHidden: true`, ticks are
+  skipped while `document.hidden` and one refresh fires when the tab becomes
+  visible again. In SSR / non-DOM environments this is a no-op.
+- **No overlap / no late writes** — each tick supersedes any in-flight fetch
+  (via `AbortSignal`), and a stale response can never clobber a newer one.
+- **SSR-safe construction** — constructed under SSR (no `document`), the feed is
+  inert: no listener, no immediate fetch, no server-side timer. It comes to life
+  when the client re-runs the component script, so you can call `systemFeed`
+  directly in `<script>` (as above) without an `onMount` guard; the first fetch
+  and the poll timer start on the client. `running` is `false` until a timer is
+  actually armed (so it is also `false` for single-shot `intervalMs <= 0`).
+- **`onError` is contained** — a throwing `onError` callback is caught and
+  swallowed; it never rejects the tick or surfaces as an unhandled rejection.
+- **Teardown** — `dispose()` stops the timer, detaches the visibility listener,
+  and aborts any in-flight fetch. Always call it from `onDestroy`.