@happyvertical/smrt-svelte 0.38.1 → 0.38.3

package/dist/web/activity-feed.svelte.js

@@ -0,0 +1,302 @@
+/**
+ * AdminShell activity feed adapter — bridge a `@happyvertical/smrt-web` live
+ * collection into the AdminShell activity registry (#1779, part of the WASD
+ * AdminShell epic #1766).
+ *
+ * This is a thin, OPT-IN CONSUMER of already-shipped infrastructure, not a new
+ * generated surface. It sits at the intersection of two existing contracts:
+ *
+ *  - the runes-reactive {@link liveCollection} view over a `SmrtWebCollection`
+ *    (`@happyvertical/smrt-svelte/web`, slice A of #1761), and
+ *  - the `ShellState` activity registry (`upsertActivity` / `updateActivity` /
+ *    `removeActivity`, from `components/workspace/admin-shell`).
+ *
+ * The app supplies (a) the `@smrt()` DOMAIN collection (a `SmrtWebCollection`)
+ * and (b) an editorial {@link ActivityFeedMap} that turns each row into the
+ * shell-facing activity fields (`kind`, `scope`, `label`, `progress`, …). The
+ * adapter reconciles the mapped rows against the shell as rows appear, change,
+ * and vanish, and returns a disposer that removes the activities it created.
+ *
+ * ── Why it lives behind the `/web` opt-in entry ─────────────────────────────
+ * `liveCollection` pulls the client-data engine (`@tanstack/db` +
+ * `@tanstack/svelte-db`). Keeping this adapter in the `/web` subpath keeps that
+ * engine OUT of the AdminShell core: nothing under `components/workspace/` may
+ * import this module, so `@happyvertical/smrt-svelte/workspace` stays
+ * transport-agnostic and TanStack-free (a hard constraint of #1766). The app
+ * wires the adapter at the edge, next to where it already opts into `/web`.
+ *
+ * ── Engine-absorption boundary ──────────────────────────────────────────────
+ * No `@tanstack/*` type appears here. The adapter reconciles against the plain
+ * DTO rows exposed by {@link liveCollection} (which already strips the engine's
+ * `$`-prefixed virtual props), so the engine stays swappable behind the same
+ * boundary the rest of `/web` respects.
+ *
+ * ── Reconciliation, not change-diffing ──────────────────────────────────────
+ * Rather than decode the engine's change payload, the adapter re-derives the
+ * activity set from the current live rows on every reactive tick (via an
+ * internal `$effect` over `view.rows`) and diffs it against what it last pushed
+ * to the shell. This is robust to the change-notification shape (which is
+ * engine-internal) and mirrors how the runtime's own consumers treat a change
+ * as a "something moved, re-read" signal.
+ */
+import { liveCollection } from './live-collection.svelte.js';
+/**
+ * Compute the change-detection fingerprint for a resolved activity input. The
+ * signature is a JSON projection of the shell-relevant fields in a FIXED key
+ * order (so key ordering in the mapper output never registers as a change); the
+ * non-serializable `cancel` is carried alongside for identity comparison.
+ */
+function fingerprintOf(input) {
+    const signature = JSON.stringify([
+        input.id,
+        input.label,
+        input.kind,
+        input.scope,
+        input.status,
+        input.progress ?? null,
+        input.message ?? null,
+        input.detailHref ?? null,
+        input.edge ?? null,
+        input.subject
+            ? [input.subject.type, input.subject.id, input.subject.label ?? null]
+            : null,
+    ]);
+    return { signature, cancel: input.cancel };
+}
+/** Two fingerprints are equal when their signatures AND `cancel` identity match. */
+function fingerprintsEqual(a, b) {
+    return a.signature === b.signature && a.cancel === b.cancel;
+}
+/**
+ * Resolve a mapped input to a fully-keyed activity input, defaulting the
+ * activity `id` to the row `id`. Returns `null` when the row has neither a
+ * mapped `id` nor a usable row `id` (it cannot be tracked, so it is dropped
+ * rather than pushed to the shell under an unstable key).
+ */
+function resolveInput(row, mapped) {
+    const id = mapped.id ?? row.id;
+    if (typeof id !== 'string' || id.length === 0)
+        return null;
+    return { ...mapped, id };
+}
+/**
+ * Build the update patch for a re-mapped activity so it REPLACES the mapped
+ * field set rather than merging over it.
+ *
+ * `ShellState.updateActivity(id, patch)` merges `{ ...current, ...patch }`, so a
+ * key the new mapping OMITS would otherwise retain its stale prior value. To
+ * keep the shell activity an exact mirror of the current mapping, every field a
+ * map controls is listed EXPLICITLY here — an omitted optional field is carried
+ * as `undefined`, which overwrites the stale value on merge. Two consequences:
+ *
+ *  - Dropped optionals (`message`, `detailHref`, `subject`, `progress`, `cancel`)
+ *    are cleared, not kept (codex P2).
+ *  - `edge` is passed through as the mapping left it — `undefined` when the map
+ *    did not pin an edge — so when a row's `scope` changes without an explicit
+ *    `edge`, the merged activity carries `edge: undefined` and `upsertActivity`
+ *    RE-DERIVES the edge from the new scope (`edge ?? homeEdgeForScope(scope)`),
+ *    re-homing it instead of pinning it to the previous scope's edge (copilot).
+ *
+ * `id` is deliberately excluded (it is the update key, not a patched field).
+ */
+function toUpdatePatch(input) {
+    return {
+        label: input.label,
+        kind: input.kind,
+        scope: input.scope,
+        status: input.status,
+        subject: input.subject,
+        edge: input.edge,
+        progress: input.progress,
+        detailHref: input.detailHref,
+        message: input.message,
+        cancel: input.cancel,
+    };
+}
+/**
+ * The pure reconciliation core of {@link activityFeed}: it owns the diff between
+ * a set of live rows and the shell's activity registry, with NO Svelte reactive
+ * or client-data-engine dependency. {@link activityFeed} wraps one of these in a
+ * `$effect` over a {@link liveCollection} view; this split keeps the mapping /
+ * create-update-remove / ownership logic testable against a real `ShellState`
+ * with plain row arrays (mock only externals — see the `__tests__`).
+ *
+ * @internal Not part of the public surface — use {@link activityFeed}.
+ * @typeParam TData - the row DTO shape being reconciled.
+ */
+export class ActivityFeedReconciler {
+    shell;
+    map;
+    /**
+     * Activities this feed currently owns, keyed by activity id, each with the
+     * last resolved input + fingerprint so a reconcile can tell created / changed
+     * / unchanged apart and remove exactly its own set on teardown.
+     */
+    owned = new Map();
+    disposed = false;
+    constructor(shell, map) {
+        this.shell = shell;
+        this.map = map;
+    }
+    /** True once {@link dispose} has run. */
+    get isDisposed() {
+        return this.disposed;
+    }
+    /**
+     * Reconcile `rows` against the owned activity set: upsert newly-appearing
+     * activities, update changed ones, remove vanished ones. A pure diff — an
+     * unchanged tick (same rows, same mappings) performs ZERO shell mutations.
+     * No-op once disposed.
+     */
+    reconcile(rows) {
+        if (this.disposed)
+            return;
+        // Resolve this tick's activities from the rows. A row mapping to `null`, or
+        // resolving to no usable id, is simply absent from `next` — which makes the
+        // removal pass below retract it if the feed owned it last tick.
+        const next = new Map();
+        for (const row of rows) {
+            const mapped = this.map(row);
+            if (mapped === null)
+                continue;
+            const input = resolveInput(row, mapped);
+            if (input === null)
+                continue;
+            // Last write wins if two rows resolve to the same activity id — matches
+            // the shell's own upsert-by-id semantics.
+            next.set(input.id, { input, fingerprint: fingerprintOf(input) });
+        }
+        // Removals: ids the feed owned last tick but that are gone now.
+        for (const id of this.owned.keys()) {
+            if (!next.has(id)) {
+                this.shell.removeActivity(id);
+                this.owned.delete(id);
+            }
+        }
+        // Creates + updates.
+        for (const [id, entry] of next) {
+            const prior = this.owned.get(id);
+            if (!prior) {
+                // First appearance: create it (stamps createdAt/updatedAt in the shell).
+                this.shell.upsertActivity({ ...entry.input });
+                this.owned.set(id, entry);
+                continue;
+            }
+            if (!fingerprintsEqual(prior.fingerprint, entry.fingerprint)) {
+                // Changed: patch it, preserving createdAt and letting the shell emit a
+                // `transition` when the status changed. The patch lists every mappable
+                // field explicitly (see `toUpdatePatch`) so it REPLACES the mapped set
+                // rather than merging over it — dropped optionals are cleared and a
+                // changed `scope` re-derives the `edge` instead of pinning the old one.
+                this.shell.updateActivity(id, toUpdatePatch(entry.input));
+                this.owned.set(id, entry);
+            }
+            // Unchanged: no shell mutation.
+        }
+    }
+    /**
+     * Retract exactly this feed's activities from the shell and stop reconciling.
+     * Idempotent. Activities owned by other sources are left untouched.
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const id of this.owned.keys())
+            this.shell.removeActivity(id);
+        this.owned.clear();
+    }
+}
+/**
+ * Bridge a `@happyvertical/smrt-web` live collection into an AdminShell's
+ * activity registry: each mapped row becomes a {@link ShellActivity} that
+ * appears, updates, and disappears in the shell as the collection changes.
+ *
+ * MUST be called during Svelte component initialization — it delegates to
+ * {@link liveCollection} (which installs a `$effect`) and installs its own
+ * reconciliation `$effect`. Both bind to the calling component's lifecycle, so
+ * the live subscription and reconciliation tear down automatically on unmount.
+ * Unmount ALSO auto-retracts the feed's activities from the shell (via an
+ * `$effect` teardown), so they never linger after the host component is gone —
+ * no manual cleanup required. The returned {@link ActivityFeedHandle.dispose}
+ * retracts them SOONER (without unmounting) and is idempotent, so calling it and
+ * then unmounting is safe.
+ *
+ * Lifecycle per row:
+ *  - a row that newly maps to an activity → `shell.upsertActivity(...)` (creates
+ *    it, stamping `createdAt`);
+ *  - an owned row whose mapping changes → `shell.updateActivity(id, patch)`
+ *    (preserves `createdAt`, bumps `updatedAt`, and the shell emits a
+ *    `transition` event when `status` changed — driving toasts);
+ *  - a row that vanishes, or whose mapping flips to `null` →
+ *    `shell.removeActivity(id)`.
+ *
+ * Only activities this feed created are ever touched: activities pushed to the
+ * shell by other sources (or a second feed) are left untouched, and `dispose`
+ * removes exactly this feed's set.
+ *
+ * @typeParam TData - the row DTO shape carried by {@link ActivityFeedOptions.collection}.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { activityFeed } from '@happyvertical/smrt-svelte/web';
+ *   import { useAdminShell } from '@happyvertical/smrt-svelte/workspace';
+ *   import { createSmrtCollection } from '@happyvertical/smrt-web';
+ *   import { getCollectionDefinition } from '@happyvertical/smrt-virt-web';
+ *
+ *   const shell = useAdminShell();
+ *   const encodes = createSmrtCollection(getCollectionDefinition('encodes'), {});
+ *
+ *   // Reconciles `encodes` rows into the shell's Focus scope; disposes on unmount.
+ *   activityFeed({
+ *     collection: encodes,
+ *     shell,
+ *     map: (row) => ({
+ *       kind: 'video-encode',
+ *       scope: 'focus',
+ *       label: row.title,
+ *       status: row.state,          // 'running' | 'completed' | …
+ *       progress: row.progress,
+ *     }),
+ *   });
+ * </script>
+ * ```
+ */
+export function activityFeed(options) {
+    const { collection, map, shell, preload = true } = options;
+    // Build the runes-reactive live view over the domain collection. This is the
+    // sole place the client-data engine is reached (through the `/web` binding),
+    // and it MUST run during component init — as must `activityFeed` itself.
+    const view = liveCollection(collection, { preload });
+    // The pure diff core: holds ownership + create/update/remove logic, with no
+    // reactive or engine dependency (unit-tested directly). This function just
+    // feeds it the live rows on every reactive tick.
+    const reconciler = new ActivityFeedReconciler(shell, map);
+    // Reconcile whenever the live rows change. `view.rows` is a `$derived`-backed
+    // reactive array; reading it inside `$effect` subscribes this effect to it, so
+    // every insert/update/delete/rollback surfaced by the live view re-reconciles.
+    // The effect binds to the hosting component and tears down on unmount.
+    $effect(() => {
+        reconciler.reconcile(view.rows);
+    });
+    // Auto-cleanup on unmount: retract this feed's activities from the shell when
+    // the hosting component is destroyed, so they never linger after the UI that
+    // created them is gone. This effect reads NO reactive state, so it never
+    // re-runs — its teardown fires only when the effect is destroyed (component
+    // unmount / `$effect.root` teardown), exactly the unmount hook we want. The
+    // returned `dispose()` stays available for callers that want to retract the
+    // feed's activities sooner (without unmounting); `dispose` is idempotent, so
+    // an explicit call followed by the unmount teardown is safe.
+    $effect(() => {
+        return () => reconciler.dispose();
+    });
+    return {
+        dispose() {
+            reconciler.dispose();
+        },
+        get isDisposed() {
+            return reconciler.isDisposed;
+        },
+    };
+}

package/dist/web/index.d.ts

@@ -7,7 +7,13 @@
  * stays an implementation detail of the runtime + this binding; nothing here
  * re-exports an `@tanstack/*` type.
  *
+ * The {@link activityFeed} adapter (#1779) is layered on {@link liveCollection}
+ * to bridge a live collection into the AdminShell activity registry. It lives
+ * behind this opt-in `/web` entry — NOT under `components/workspace/` — so the
+ * AdminShell core stays transport-agnostic and TanStack-free (epic #1766).
+ *
  * @packageDocumentation
  */
+export { type ActivityFeedHandle, type ActivityFeedMap, type ActivityFeedOptions, activityFeed, type ShellActivityInput, } from './activity-feed.svelte.js';
 export { type LiveCollection, type LiveCollectionMutation, type LiveCollectionOptions, type LiveCollectionStatus, liveCollection, } from './live-collection.svelte.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/web/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,cAAc,GACf,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,YAAY,EACZ,KAAK,kBAAkB,GACxB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,cAAc,GACf,MAAM,6BAA6B,CAAC"}

package/dist/web/index.js

@@ -7,6 +7,12 @@
  * stays an implementation detail of the runtime + this binding; nothing here
  * re-exports an `@tanstack/*` type.
  *
+ * The {@link activityFeed} adapter (#1779) is layered on {@link liveCollection}
+ * to bridge a live collection into the AdminShell activity registry. It lives
+ * behind this opt-in `/web` entry — NOT under `components/workspace/` — so the
+ * AdminShell core stays transport-agnostic and TanStack-free (epic #1766).
+ *
  * @packageDocumentation
  */
+export { activityFeed, } from './activity-feed.svelte.js';
 export { liveCollection, } from './live-collection.svelte.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-svelte",
-  "version": "0.38.1",
+  "version": "0.38.3",
   "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",
@@ -82,14 +88,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@happyvertical/logger": "^0.74.11",
+    "@happyvertical/logger": "^0.76.2",
     "@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-languages": "0.38.3",
+    "@happyvertical/smrt-types": "0.38.3",
+    "@happyvertical/smrt-ui": "0.38.3",
+    "@happyvertical/smrt-web": "0.38.3"
   },
   "peerDependencies": {
     "@huggingface/transformers": ">=3.8.1",
@@ -127,7 +133,7 @@
     "svelte": "^5.56.4",
     "svelte-check": "^4.7.1",
     "typescript": "^5.9.3",
-    "vite": "^8.1.2",
+    "vite": "^8.1.3",
     "vitest": "^4.1.9"
   },
   "scripts": {