@happyvertical/smrt-svelte 0.38.1 → 0.38.2

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`.

package/dist/components/workspace/live/system-feed.svelte.d.ts

@@ -0,0 +1,129 @@
+/**
+ * `systemFeed` — a transport-light polling helper for the AdminShell system
+ * scope (issue #1774, epic #1766).
+ *
+ * The System edge presents jobs / schedules / dispatch — data that lives in the
+ * `_smrt_*` SYSTEM tables. Those tables are intentionally **excluded** from the
+ * core change-feed (`packages/core/src/change-feed.ts`) and are **not** surfaced
+ * as `smrt-web` collections, so the live-collection path used by tenant/app
+ * data does not apply here. Instead, an app exposes its own status endpoint
+ * (a `+server.ts` that reads `_smrt_*` through the `smrt-jobs` query API) and
+ * this helper polls it on an interval, mapping the response into the
+ * presentation contracts the shell already renders:
+ * `ShellSystemPanel[]` (for `SystemScopePanel`) and `ShellStatusChip[]`
+ * (for `SystemStatusChips`).
+ *
+ * This module is deliberately kept OUT of the `./workspace` presentation barrel
+ * and the `./web` (smrt-web / TanStack) entry: it is opt-in via the
+ * `@happyvertical/smrt-svelte/workspace/live` subpath and pulls no runtime
+ * dependency beyond Svelte's reactivity. It only imports the shell's *types*.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { systemFeed } from '@happyvertical/smrt-svelte/workspace/live';
+ *   import { SystemScopePanel, SystemStatusChips } from
+ *     '@happyvertical/smrt-svelte/workspace';
+ *   import { onDestroy } from 'svelte';
+ *
+ *   const feed = systemFeed({
+ *     fetch: () => fetch('/admin/system/status').then((r) => r.json()),
+ *     intervalMs: 5000,
+ *     map: (status) => ({ panels: toPanels(status), chips: toChips(status) }),
+ *   });
+ *   onDestroy(feed.dispose);
+ * </script>
+ *
+ * <SystemStatusChips chips={feed.chips} />
+ * <SystemScopePanel panels={feed.panels} />
+ * ```
+ */
+import type { ShellStatusChip, ShellSystemPanel } from '../admin-shell/types.js';
+/** Lifecycle phase of a {@link SystemFeedController}. */
+export type SystemFeedStatus = 'idle' | 'loading' | 'success' | 'error' | 'stopped';
+/**
+ * The shell-facing shape produced by {@link SystemFeedOptions.map}. Either half
+ * is optional so a feed can drive only the panels, only the chips, or both.
+ */
+export interface SystemFeedView {
+    panels?: ShellSystemPanel[];
+    chips?: ShellStatusChip[];
+}
+/** Options for {@link systemFeed}. */
+export interface SystemFeedOptions<T> {
+    /**
+     * App-supplied async loader. Called on each tick (and once immediately unless
+     * `immediate` is `false`). Typically wraps `fetch('/…/status')`. Its resolved
+     * value is handed to {@link SystemFeedOptions.map}. Rejections are caught and
+     * surfaced via `error` / `onError` without stopping the poll loop.
+     */
+    fetch: (signal: AbortSignal) => T | Promise<T>;
+    /**
+     * Maps a raw `fetch` result into the shell presentation contracts. Runs
+     * inside the same try/catch as `fetch`, so a throwing mapper is treated as a
+     * failed tick (tolerated, loop continues).
+     */
+    map: (data: T) => SystemFeedView;
+    /**
+     * Poll interval in milliseconds. Values `<= 0` disable the timer (single
+     * fetch only, useful for tests / manual `refresh()`). Default `5000`.
+     */
+    intervalMs?: number;
+    /**
+     * Fetch once as soon as the feed is created. Default `true`. When `false`,
+     * nothing is fetched until the first timer tick or an explicit `refresh()`.
+     */
+    immediate?: boolean;
+    /**
+     * Skip ticks while `document.hidden` is true and refresh once on the next
+     * `visibilitychange` back to visible. Avoids polling a backgrounded tab.
+     * Default `true`. Ignored (treated as `false`) when there is no `document`
+     * (SSR / non-DOM environments).
+     */
+    pauseWhenHidden?: boolean;
+    /** Notified on every caught fetch/map error. Never throws into the loop. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Reactive controller returned by {@link systemFeed}. `panels` / `chips` are
+ * `$state`-backed getters safe to bind straight to `SystemScopePanel` /
+ * `SystemStatusChips`. Call {@link SystemFeedController.dispose} (e.g. from
+ * `onDestroy`) to stop the timer and detach listeners — this is the disposer.
+ */
+export interface SystemFeedController {
+    /** Latest mapped panels; `[]` until the first successful tick. */
+    readonly panels: ShellSystemPanel[];
+    /** Latest mapped chips; `[]` until the first successful tick. */
+    readonly chips: ShellStatusChip[];
+    /** Lifecycle phase of the most recent tick. */
+    readonly status: SystemFeedStatus;
+    /** The most recent caught error, or `null` after any success. */
+    readonly error: unknown;
+    /**
+     * Whether the poll timer is currently armed. Stays `false` for single-shot
+     * feeds (`intervalMs <= 0`), under SSR (no `document`), and after `stop()` /
+     * `dispose()`.
+     */
+    readonly running: boolean;
+    /** Fetch + map once, off-schedule. Resolves after state is updated. */
+    refresh(): Promise<void>;
+    /**
+     * (Re)arm the poll timer. Idempotent. No-op when already running, after
+     * {@link dispose}, when `intervalMs <= 0`, or under SSR (no `document`).
+     */
+    start(): void;
+    /** Disarm the poll timer without tearing down listeners. Idempotent. */
+    stop(): void;
+    /** Stop the timer, detach listeners, abort any in-flight fetch. Terminal. */
+    dispose(): void;
+}
+/**
+ * Create a polling feed that maps an app status endpoint into the AdminShell
+ * system-scope presentation contracts.
+ *
+ * The returned {@link SystemFeedController} exposes reactive `panels` / `chips`
+ * and a `dispose()` disposer. Bind the getters to the shell components and call
+ * `dispose()` on teardown.
+ */
+export declare function systemFeed<T>(options: SystemFeedOptions<T>): SystemFeedController;
+//# sourceMappingURL=system-feed.svelte.d.ts.map

package/dist/components/workspace/live/system-feed.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-feed.svelte.d.ts","sourceRoot":"","sources":["../../../../src/components/workspace/live/system-feed.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AAEjC,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,SAAS,GACT,SAAS,GACT,OAAO,GACP,SAAS,CAAC;AAEd;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC;;;;;OAKG;IACH,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/C;;;;OAIG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,cAAc,CAAC;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACpC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,eAAe,EAAE,CAAC;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;IACd,wEAAwE;IACxE,IAAI,IAAI,IAAI,CAAC;IACb,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;CACjB;AAID;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,oBAAoB,CA6ItB"}

package/dist/components/workspace/live/system-feed.svelte.js

@@ -0,0 +1,201 @@
+/**
+ * `systemFeed` — a transport-light polling helper for the AdminShell system
+ * scope (issue #1774, epic #1766).
+ *
+ * The System edge presents jobs / schedules / dispatch — data that lives in the
+ * `_smrt_*` SYSTEM tables. Those tables are intentionally **excluded** from the
+ * core change-feed (`packages/core/src/change-feed.ts`) and are **not** surfaced
+ * as `smrt-web` collections, so the live-collection path used by tenant/app
+ * data does not apply here. Instead, an app exposes its own status endpoint
+ * (a `+server.ts` that reads `_smrt_*` through the `smrt-jobs` query API) and
+ * this helper polls it on an interval, mapping the response into the
+ * presentation contracts the shell already renders:
+ * `ShellSystemPanel[]` (for `SystemScopePanel`) and `ShellStatusChip[]`
+ * (for `SystemStatusChips`).
+ *
+ * This module is deliberately kept OUT of the `./workspace` presentation barrel
+ * and the `./web` (smrt-web / TanStack) entry: it is opt-in via the
+ * `@happyvertical/smrt-svelte/workspace/live` subpath and pulls no runtime
+ * dependency beyond Svelte's reactivity. It only imports the shell's *types*.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { systemFeed } from '@happyvertical/smrt-svelte/workspace/live';
+ *   import { SystemScopePanel, SystemStatusChips } from
+ *     '@happyvertical/smrt-svelte/workspace';
+ *   import { onDestroy } from 'svelte';
+ *
+ *   const feed = systemFeed({
+ *     fetch: () => fetch('/admin/system/status').then((r) => r.json()),
+ *     intervalMs: 5000,
+ *     map: (status) => ({ panels: toPanels(status), chips: toChips(status) }),
+ *   });
+ *   onDestroy(feed.dispose);
+ * </script>
+ *
+ * <SystemStatusChips chips={feed.chips} />
+ * <SystemScopePanel panels={feed.panels} />
+ * ```
+ */
+const DEFAULT_INTERVAL_MS = 5000;
+/**
+ * Create a polling feed that maps an app status endpoint into the AdminShell
+ * system-scope presentation contracts.
+ *
+ * The returned {@link SystemFeedController} exposes reactive `panels` / `chips`
+ * and a `dispose()` disposer. Bind the getters to the shell components and call
+ * `dispose()` on teardown.
+ */
+export function systemFeed(options) {
+    const { fetch: fetcher, map, intervalMs = DEFAULT_INTERVAL_MS, immediate = true, pauseWhenHidden = true, onError, } = options;
+    let panels = $state([]);
+    let chips = $state([]);
+    let status = $state('idle');
+    let error = $state(null);
+    let running = $state(false);
+    // Non-reactive machinery.
+    let timer = null;
+    let inFlight = null;
+    let disposed = false;
+    // Guards against a slow tick resolving after a newer one (or after dispose)
+    // and clobbering fresher state.
+    let generation = 0;
+    const hasDocument = typeof document !== 'undefined';
+    const usesVisibility = pauseWhenHidden && hasDocument;
+    async function tick() {
+        if (disposed)
+            return;
+        // When hidden, skip the network entirely; the visibility listener will
+        // refresh on the way back to visible.
+        if (usesVisibility && document.hidden)
+            return;
+        const myGeneration = ++generation;
+        // Supersede any still-running fetch so its result can't land late.
+        inFlight?.abort();
+        const controller = new AbortController();
+        inFlight = controller;
+        status = 'loading';
+        try {
+            const raw = await fetcher(controller.signal);
+            if (disposed || myGeneration !== generation)
+                return;
+            const view = map(raw);
+            if (disposed || myGeneration !== generation)
+                return;
+            if (view.panels)
+                panels = view.panels;
+            if (view.chips)
+                chips = view.chips;
+            error = null;
+            status = 'success';
+        }
+        catch (caught) {
+            if (disposed || myGeneration !== generation)
+                return;
+            // An abort is an intentional supersede/teardown, not a feed failure.
+            if (isAbortError(caught))
+                return;
+            error = caught;
+            status = 'error';
+            // Contain a throwing consumer callback: it must not reject the tick and
+            // surface as an unhandled rejection from the interval / visibility path.
+            try {
+                onError?.(caught);
+            }
+            catch {
+                // Swallow — the feed's own error handling already recorded `caught`.
+            }
+        }
+        finally {
+            if (inFlight === controller)
+                inFlight = null;
+        }
+    }
+    function start() {
+        if (disposed || running)
+            return;
+        // Arm a timer only in a DOM environment (never spin a server-side interval
+        // during SSR) and only when an interval is requested. `running` reflects an
+        // actually-armed timer, so it stays false for single-shot feeds
+        // (`intervalMs <= 0`) and under SSR.
+        if (!hasDocument || intervalMs <= 0)
+            return;
+        running = true;
+        timer = setInterval(() => void tick(), intervalMs);
+    }
+    function stop() {
+        running = false;
+        if (timer !== null) {
+            clearInterval(timer);
+            timer = null;
+        }
+    }
+    function handleVisibility() {
+        // Only catch up on becoming visible while actively polling — a stopped
+        // (or disposed) feed must stay quiet.
+        if (disposed || !running)
+            return;
+        if (!document.hidden)
+            void tick();
+    }
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        stop();
+        // Invalidate any in-flight tick and abort its fetch.
+        generation++;
+        inFlight?.abort();
+        inFlight = null;
+        if (usesVisibility) {
+            document.removeEventListener('visibilitychange', handleVisibility);
+        }
+        status = 'stopped';
+    }
+    // Everything below activates the feed. Under SSR (no `document`) the feed is
+    // created inert — no listener, no immediate fetch, no timer — so a consumer
+    // can safely construct it in a component script; the client re-runs this and
+    // brings it to life. Callers can also drive an inert feed manually via
+    // `refresh()` / `start()`.
+    if (hasDocument) {
+        if (usesVisibility) {
+            document.addEventListener('visibilitychange', handleVisibility);
+        }
+        if (immediate)
+            void tick();
+        start();
+    }
+    return {
+        get panels() {
+            return panels;
+        },
+        get chips() {
+            return chips;
+        },
+        get status() {
+            return status;
+        },
+        get error() {
+            return error;
+        },
+        get running() {
+            return running;
+        },
+        refresh: tick,
+        start,
+        stop,
+        dispose,
+    };
+}
+function isAbortError(error) {
+    // Guard `DOMException` — it is undefined in some non-DOM runtimes, so a bare
+    // `instanceof` would throw a ReferenceError and defeat the SSR-safe contract.
+    if (typeof DOMException !== 'undefined' && error instanceof DOMException) {
+        return error.name === 'AbortError';
+    }
+    return (typeof error === 'object' &&
+        error !== null &&
+        'name' in error &&
+        error.name === 'AbortError');
+}

package/dist/i18n/strings.workspace.d.ts

@@ -56,5 +56,21 @@ export declare const M: {
     readonly 'ui.system_scope_panel.no_running_work': "ui.system_scope_panel.no_running_work";
     readonly 'ui.system_status_chips.system_status': "ui.system_status_chips.system_status";
     readonly 'ui.tenant_nav.tenant_navigation': "ui.tenant_nav.tenant_navigation";
+    readonly 'ui.system_feed.title': "ui.system_feed.title";
+    readonly 'ui.system_feed.description': "ui.system_feed.description";
+    readonly 'ui.system_feed.pause': "ui.system_feed.pause";
+    readonly 'ui.system_feed.resume': "ui.system_feed.resume";
+    readonly 'ui.system_feed.refresh': "ui.system_feed.refresh";
+    readonly 'ui.system_feed.fail_next': "ui.system_feed.fail_next";
+    readonly 'ui.system_feed.status_label': "ui.system_feed.status_label";
+    readonly 'ui.system_feed.tick_label': "ui.system_feed.tick_label";
+    readonly 'ui.system_feed.error_label': "ui.system_feed.error_label";
+    readonly 'ui.system_feed.jobs_panel': "ui.system_feed.jobs_panel";
+    readonly 'ui.system_feed.schedules_panel': "ui.system_feed.schedules_panel";
+    readonly 'ui.system_feed.dispatch_panel': "ui.system_feed.dispatch_panel";
+    readonly 'ui.system_feed.chip_workers': "ui.system_feed.chip_workers";
+    readonly 'ui.system_feed.chip_running': "ui.system_feed.chip_running";
+    readonly 'ui.system_feed.chip_queued': "ui.system_feed.chip_queued";
+    readonly 'ui.system_feed.chip_failed': "ui.system_feed.chip_failed";
 };
 //# sourceMappingURL=strings.workspace.d.ts.map

package/dist/i18n/strings.workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strings.workspace.d.ts","sourceRoot":"","sources":["../../src/i18n/strings.workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,eAAO,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwDZ,CAAC"}
+{"version":3,"file":"strings.workspace.d.ts","sourceRoot":"","sources":["../../src/i18n/strings.workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,eAAO,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2EZ,CAAC"}

package/dist/i18n/strings.workspace.js

@@ -61,4 +61,21 @@ export const M = defineMessages({
     'ui.system_scope_panel.no_running_work': 'No running work',
     'ui.system_status_chips.system_status': 'System status',
     'ui.tenant_nav.tenant_navigation': 'Tenant navigation',
+    // components/workspace/live/* (systemFeed demo — issue #1774)
+    'ui.system_feed.title': 'System feed',
+    'ui.system_feed.description': 'Polls an app-provided status endpoint and maps it into the system-scope panels and status chips.',
+    'ui.system_feed.pause': 'Pause polling',
+    'ui.system_feed.resume': 'Resume polling',
+    'ui.system_feed.refresh': 'Refresh now',
+    'ui.system_feed.fail_next': 'Fail next fetch',
+    'ui.system_feed.status_label': 'Feed status',
+    'ui.system_feed.tick_label': 'Ticks',
+    'ui.system_feed.error_label': 'Last error',
+    'ui.system_feed.jobs_panel': 'Jobs',
+    'ui.system_feed.schedules_panel': 'Schedules',
+    'ui.system_feed.dispatch_panel': 'Dispatch',
+    'ui.system_feed.chip_workers': 'Workers',
+    'ui.system_feed.chip_running': 'Running',
+    'ui.system_feed.chip_queued': 'Queued',
+    'ui.system_feed.chip_failed': 'Failed',
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-svelte",
-  "version": "0.38.1",
+  "version": "0.38.2",
   "description": "Svelte 5 components for SMRT user management - auth, users, tenants, roles, permissions, groups",
   "type": "module",
   "smrtRawPrimitives": "strict",
@@ -36,6 +36,12 @@
       "import": "./dist/components/workspace/server/index.js",
       "default": "./dist/components/workspace/server/index.js"
     },
+    "./workspace/live": {
+      "types": "./dist/components/workspace/live/index.d.ts",
+      "svelte": "./dist/components/workspace/live/index.js",
+      "import": "./dist/components/workspace/live/index.js",
+      "default": "./dist/components/workspace/live/index.js"
+    },
     "./browser-ai": {
       "types": "./dist/browser-ai/index.d.ts",
       "import": "./dist/browser-ai/index.js",
@@ -86,10 +92,10 @@
     "@tanstack/db": "^0.6.14",
     "@tanstack/svelte-db": "^0.1.91",
     "esm-env": "^1.2.2",
-    "@happyvertical/smrt-languages": "0.38.1",
-    "@happyvertical/smrt-types": "0.38.1",
-    "@happyvertical/smrt-ui": "0.38.1",
-    "@happyvertical/smrt-web": "0.38.1"
+    "@happyvertical/smrt-types": "0.38.2",
+    "@happyvertical/smrt-ui": "0.38.2",
+    "@happyvertical/smrt-web": "0.38.2",
+    "@happyvertical/smrt-languages": "0.38.2"
   },
   "peerDependencies": {
     "@huggingface/transformers": ">=3.8.1",