@happyvertical/smrt-svelte 0.38.6 → 0.38.7

package/AGENTS.md

@@ -280,6 +280,29 @@ 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`.
 
+### `updateAvailable` binding (`./web`, #1764)
+
+`useUpdateAvailable({ state, updated? })` (from `@happyvertical/smrt-svelte/web`)
+is the Svelte 5 reactive wrapper over smrt-web's framework-free `UpdateState`
+(from `createUpdateState()`). It surfaces `updateAvailable` / `bundle` /
+`contract` reactively (`$state`/`$derived`) for a toast or reload prompt, and
+wires SvelteKit's native `updated` store as the **bundle** signal. The
+**contract** signal (a manifest-hash change across loads, detected inside the
+smrt-web primitive under the build-time-inject decision) is surfaced as-is.
+
+`updated` is passed IN as a reactive accessor (`() => updated.current` on modern
+`$app/state`, or a `$derived` over the legacy `$updated` store) rather than
+imported here — `$app/*` only resolves inside a SvelteKit app, so a library that
+imported it could not build/test standalone; the other `./web` adapters take
+runtime input the same way. Must be called during component init (installs
+`$effect`s that subscribe to the primitive and watch `updated`); both tear down
+on unmount. Construct ONE `createUpdateState()` per app (it owns the durable
+last-seen-hash bookkeeping) and pass its `manifestHash` from
+`@happyvertical/smrt-virt-web`. Browser-safe, engine-free (no `@tanstack/*`
+type). NOTE: `.svelte.ts` runes tests may not run under the local Darwin/vite8
+toolchain (CI is the gate) — the binding is covered by typecheck + svelte-check +
+a light unit test.
+
 ### Dock availability gates (server-side)
 
 `ToolDef.gates?: string[]` declares the gates a tool must pass to be visible.

package/dist/web/__tests__/update-available-harness.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+/**
+ * Test harness — invokes useUpdateAvailable() inside a component init scope so
+ * its `$effect`s (the state subscription + the `updated` watcher) wire up
+ * correctly, then hands the reactive view back to the test via `onReady`.
+ *
+ * The bundle-signal source (`updated`) is a genuinely REACTIVE `$state` owned by
+ * this harness, mutated by the test through the `setUpdated` control handed back
+ * via `onReady`. This mirrors production, where the caller passes
+ * `() => updated.current` over SvelteKit's reactive `updated` store — a plain
+ * closure variable would not be tracked by the rune's `$effect`.
+ */
+import type { UpdateState } from '@happyvertical/smrt-web';
+import {
+  type UpdateAvailableView,
+  useUpdateAvailable,
+} from '../update-available.svelte.js';
+
+interface Props {
+  state: UpdateState;
+  initialUpdated?: boolean;
+  onReady: (view: UpdateAvailableView, setUpdated: (v: boolean) => void) => void;
+}
+
+const props: Props = $props();
+
+// A reactive bundle-updated source the test drives via setUpdated. Seeds from
+// the prop once at init (intentional snapshot).
+// svelte-ignore state_referenced_locally
+let updated = $state(props.initialUpdated ?? false);
+
+// The harness intentionally snapshots the props during setup.
+// svelte-ignore state_referenced_locally
+const view = useUpdateAvailable({
+  state: props.state,
+  updated: () => updated,
+});
+
+// svelte-ignore state_referenced_locally
+props.onReady(view, (v: boolean) => {
+  updated = v;
+});
+</script>

package/dist/web/__tests__/update-available-harness.svelte.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Test harness — invokes useUpdateAvailable() inside a component init scope so
+ * its `$effect`s (the state subscription + the `updated` watcher) wire up
+ * correctly, then hands the reactive view back to the test via `onReady`.
+ *
+ * The bundle-signal source (`updated`) is a genuinely REACTIVE `$state` owned by
+ * this harness, mutated by the test through the `setUpdated` control handed back
+ * via `onReady`. This mirrors production, where the caller passes
+ * `() => updated.current` over SvelteKit's reactive `updated` store — a plain
+ * closure variable would not be tracked by the rune's `$effect`.
+ */
+import type { UpdateState } from '@happyvertical/smrt-web';
+import { type UpdateAvailableView } from '../update-available.svelte.js';
+interface Props {
+    state: UpdateState;
+    initialUpdated?: boolean;
+    onReady: (view: UpdateAvailableView, setUpdated: (v: boolean) => void) => void;
+}
+declare const UpdateAvailableHarness: import("svelte").Component<Props, {}, "">;
+type UpdateAvailableHarness = ReturnType<typeof UpdateAvailableHarness>;
+export default UpdateAvailableHarness;
+//# sourceMappingURL=update-available-harness.svelte.d.ts.map

package/dist/web/__tests__/update-available-harness.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-available-harness.svelte.d.ts","sourceRoot":"","sources":["../../../src/web/__tests__/update-available-harness.svelte.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,+BAA+B,CAAC;AAGvC,UAAU,KAAK;IACb,KAAK,EAAE,WAAW,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE,CAAC,IAAI,EAAE,mBAAmB,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,KAAK,IAAI,CAAC;CAChF;AA6BD,QAAA,MAAM,sBAAsB,2CAAwC,CAAC;AACrE,KAAK,sBAAsB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACxE,eAAe,sBAAsB,CAAC"}

package/dist/web/__tests__/update-available.svelte.test.js

@@ -0,0 +1,131 @@
+/**
+ * Behavior tests for the Svelte 5 `useUpdateAvailable` binding (#1764).
+ *
+ * The binding wires SvelteKit's `updated` boolean (the bundle signal) into
+ * smrt-web's framework-free `UpdateState`, and surfaces both signals reactively.
+ * Here the `UpdateState` is a small in-memory stub (a real one would open
+ * IndexedDB; the RUNE's reactivity — subscription sync + `updated` watcher — is
+ * what these tests pin), and the binding runs inside a host component so its
+ * `$effect`s have a genuine component-init scope, matching this package's other
+ * runes-composable tests.
+ *
+ * NOTE: Svelte-package tests may not run under the local Darwin/vite8 toolchain
+ * (CI is the gate). The binding is additionally covered by typecheck.
+ */
+import { flushSync, mount, unmount } from 'svelte';
+import { afterEach, describe, expect, it } from 'vitest';
+import Harness from './update-available-harness.svelte';
+/**
+ * A minimal in-memory UpdateState: drives `bundle`/`contract` and fans out to
+ * subscribers, exactly like the real primitive but with no IndexedDB. Lets a
+ * test flip the contract signal and push the bundle signal deterministically.
+ */
+function makeStubState() {
+    let bundle = false;
+    let contract = false;
+    const subs = new Set();
+    const snapshot = () => ({
+        bundle,
+        contract,
+        updateAvailable: bundle || contract,
+    });
+    const notify = () => {
+        for (const cb of [...subs])
+            cb(snapshot());
+    };
+    return {
+        get: snapshot,
+        subscribe(cb) {
+            subs.add(cb);
+            cb(snapshot());
+            return () => {
+                subs.delete(cb);
+            };
+        },
+        notifyBundleUpdated() {
+            if (bundle)
+                return;
+            bundle = true;
+            notify();
+        },
+        ready: Promise.resolve(),
+        dispose() {
+            subs.clear();
+        },
+        fireContract() {
+            if (contract)
+                return;
+            contract = true;
+            notify();
+        },
+    };
+}
+const mounted = [];
+function render(state, initialUpdated = false) {
+    let view;
+    let setUpdated;
+    const target = document.createElement('div');
+    const component = mount(Harness, {
+        target,
+        props: {
+            state,
+            initialUpdated,
+            onReady: (v, set) => {
+                view = v;
+                setUpdated = set;
+            },
+        },
+    });
+    mounted.push(component);
+    flushSync();
+    return { view, setUpdated };
+}
+afterEach(() => {
+    for (const c of mounted) {
+        void unmount(c);
+    }
+    mounted.length = 0;
+});
+describe('useUpdateAvailable (#1764)', () => {
+    it('starts with no update available and reflects the initial state', () => {
+        const state = makeStubState();
+        const { view } = render(state);
+        expect(view.bundle).toBe(false);
+        expect(view.contract).toBe(false);
+        expect(view.updateAvailable).toBe(false);
+    });
+    it('reacts to the CONTRACT signal fired by the primitive', () => {
+        const state = makeStubState();
+        const { view } = render(state);
+        state.fireContract();
+        flushSync();
+        expect(view.contract).toBe(true);
+        expect(view.updateAvailable).toBe(true);
+        expect(view.bundle).toBe(false);
+    });
+    it('pushes the BUNDLE signal when SvelteKit `updated` flips true', () => {
+        const state = makeStubState();
+        // `setUpdated` mutates a REACTIVE $state in the harness (mirrors SvelteKit's
+        // reactive `updated` store) — a plain closure variable would not be tracked
+        // by the rune's $effect, so the bundle signal would never fire.
+        const { view, setUpdated } = render(state);
+        expect(view.updateAvailable).toBe(false);
+        // Simulate SvelteKit detecting a new deployment.
+        setUpdated(true);
+        flushSync();
+        expect(view.bundle).toBe(true);
+        expect(view.updateAvailable).toBe(true);
+    });
+    it('updateAvailable is the union: either signal alone makes it true', () => {
+        const stateA = makeStubState();
+        const a = render(stateA);
+        stateA.fireContract();
+        flushSync();
+        expect(a.view.updateAvailable).toBe(true);
+        const stateB = makeStubState();
+        const b = render(stateB);
+        b.setUpdated(true);
+        flushSync();
+        expect(b.view.updateAvailable).toBe(true);
+    });
+});

package/dist/web/index.d.ts

@@ -16,4 +16,5 @@
  */
 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';
+export { type UpdateAvailableView, type UseUpdateAvailableOptions, useUpdateAvailable, } from './update-available.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;;;;;;;;;;;;;;;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"}
+{"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;AACrC,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,kBAAkB,GACnB,MAAM,8BAA8B,CAAC"}

package/dist/web/index.js

@@ -16,3 +16,4 @@
  */
 export { activityFeed, } from './activity-feed.svelte.js';
 export { liveCollection, } from './live-collection.svelte.js';
+export { useUpdateAvailable, } from './update-available.svelte.js';

package/dist/web/update-available.svelte.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Svelte 5 reactive binding for smrt-web's `updateAvailable` primitive (#1764).
+ *
+ * Turns the framework-free {@link UpdateState} from `@happyvertical/smrt-web`
+ * into runes-reactive state a component can read directly to drive a toast /
+ * reload prompt, and wires SvelteKit's native `updated` store (the BUNDLE
+ * signal) into it. The contract signal (a manifest-hash change across loads) is
+ * detected inside the smrt-web primitive under the build-time-inject decision;
+ * this binding just surfaces both, plus the derived `updateAvailable = bundle ||
+ * contract`.
+ *
+ * ## Why the caller passes `updated` in
+ *
+ * SvelteKit's `updated` store lives in `$app/state` / `$app/stores`, which only
+ * resolve inside a SvelteKit app — a library that imported it could not build or
+ * test standalone. So the consumer passes the CURRENT bundle-updated boolean via
+ * {@link UseUpdateAvailableOptions.updated} (e.g. `() => updated.current` on
+ * modern SvelteKit, or a `$derived` over the legacy `$updated` store). This
+ * keeps the binding browser-safe and SvelteKit-version-agnostic, matching how
+ * this package's other `/web` adapters take runtime input as parameters rather
+ * than importing app-only modules.
+ *
+ * MUST be called during Svelte component initialization (it installs a
+ * `$effect`), like this package's other `use*` composables. The subscription to
+ * the primitive and the `updated` watcher are torn down automatically when the
+ * component unmounts.
+ *
+ * Engine-free / TanStack-free: this binding names no `@tanstack/*` type — it
+ * only touches the SMRT-owned `UpdateState` surface.
+ */
+import type { UpdateState } from '@happyvertical/smrt-web';
+/**
+ * A runes-reactive view of the two update signals. Read the fields directly in
+ * markup — they update as either signal fires. Do NOT destructure (Svelte 5
+ * reactivity is lost on destructure); read through the object, e.g.
+ * `update.updateAvailable`.
+ */
+export interface UpdateAvailableView {
+    /** True once the client bundle changed on the server (SvelteKit `updated`). */
+    readonly bundle: boolean;
+    /** True once the API contract (manifest hash) changed across this load. */
+    readonly contract: boolean;
+    /** `bundle || contract` — either means an update is available. */
+    readonly updateAvailable: boolean;
+}
+/** Options for {@link useUpdateAvailable}. */
+export interface UseUpdateAvailableOptions {
+    /**
+     * The smrt-web primitive holding the two signals, from `createUpdateState()`.
+     * Construct ONE per app (it owns the durable last-seen-hash bookkeeping) and
+     * pass it here.
+     */
+    state: UpdateState;
+    /**
+     * A reactive accessor for SvelteKit's bundle-updated boolean — call it inside
+     * this function so the returned `$effect` tracks it. Typically `() =>
+     * updated.current` (modern `$app/state`) or a `$derived` over the legacy
+     * `$updated` store. When it flips `true`, the BUNDLE signal is pushed into the
+     * primitive. Omit to wire no bundle source (contract-only).
+     */
+    updated?: () => boolean;
+}
+/**
+ * Create a runes-reactive {@link UpdateAvailableView} over a smrt-web
+ * {@link UpdateState}, wiring SvelteKit's `updated` store as the bundle signal.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { updated } from '$app/state';
+ *   import { createUpdateState } from '@happyvertical/smrt-web';
+ *   import { useUpdateAvailable } from '@happyvertical/smrt-svelte/web';
+ *   import { manifestHash } from '@happyvertical/smrt-virt-web';
+ *
+ *   // One primitive per app — owns the durable last-seen-hash compare.
+ *   const state = createUpdateState({
+ *     manifestHash,
+ *     namespace: { apiBase: '/api/v1', manifestHash: 'apiv1' },
+ *   });
+ *   const update = useUpdateAvailable({ state, updated: () => updated.current });
+ * </script>
+ *
+ * {#if update.updateAvailable}
+ *   <div role="alert">
+ *     A new version is available.
+ *     <button onclick={() => location.reload()}>Reload</button>
+ *   </div>
+ * {/if}
+ * ```
+ */
+export declare function useUpdateAvailable(options: UseUpdateAvailableOptions): UpdateAvailableView;
+//# sourceMappingURL=update-available.svelte.d.ts.map

package/dist/web/update-available.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-available.svelte.d.ts","sourceRoot":"","sources":["../../src/web/update-available.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAED,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,KAAK,EAAE,WAAW,CAAC;IACnB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,mBAAmB,CAuCrB"}

package/dist/web/update-available.svelte.js

@@ -0,0 +1,94 @@
+/**
+ * Svelte 5 reactive binding for smrt-web's `updateAvailable` primitive (#1764).
+ *
+ * Turns the framework-free {@link UpdateState} from `@happyvertical/smrt-web`
+ * into runes-reactive state a component can read directly to drive a toast /
+ * reload prompt, and wires SvelteKit's native `updated` store (the BUNDLE
+ * signal) into it. The contract signal (a manifest-hash change across loads) is
+ * detected inside the smrt-web primitive under the build-time-inject decision;
+ * this binding just surfaces both, plus the derived `updateAvailable = bundle ||
+ * contract`.
+ *
+ * ## Why the caller passes `updated` in
+ *
+ * SvelteKit's `updated` store lives in `$app/state` / `$app/stores`, which only
+ * resolve inside a SvelteKit app — a library that imported it could not build or
+ * test standalone. So the consumer passes the CURRENT bundle-updated boolean via
+ * {@link UseUpdateAvailableOptions.updated} (e.g. `() => updated.current` on
+ * modern SvelteKit, or a `$derived` over the legacy `$updated` store). This
+ * keeps the binding browser-safe and SvelteKit-version-agnostic, matching how
+ * this package's other `/web` adapters take runtime input as parameters rather
+ * than importing app-only modules.
+ *
+ * MUST be called during Svelte component initialization (it installs a
+ * `$effect`), like this package's other `use*` composables. The subscription to
+ * the primitive and the `updated` watcher are torn down automatically when the
+ * component unmounts.
+ *
+ * Engine-free / TanStack-free: this binding names no `@tanstack/*` type — it
+ * only touches the SMRT-owned `UpdateState` surface.
+ */
+/**
+ * Create a runes-reactive {@link UpdateAvailableView} over a smrt-web
+ * {@link UpdateState}, wiring SvelteKit's `updated` store as the bundle signal.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { updated } from '$app/state';
+ *   import { createUpdateState } from '@happyvertical/smrt-web';
+ *   import { useUpdateAvailable } from '@happyvertical/smrt-svelte/web';
+ *   import { manifestHash } from '@happyvertical/smrt-virt-web';
+ *
+ *   // One primitive per app — owns the durable last-seen-hash compare.
+ *   const state = createUpdateState({
+ *     manifestHash,
+ *     namespace: { apiBase: '/api/v1', manifestHash: 'apiv1' },
+ *   });
+ *   const update = useUpdateAvailable({ state, updated: () => updated.current });
+ * </script>
+ *
+ * {#if update.updateAvailable}
+ *   <div role="alert">
+ *     A new version is available.
+ *     <button onclick={() => location.reload()}>Reload</button>
+ *   </div>
+ * {/if}
+ * ```
+ */
+export function useUpdateAvailable(options) {
+    const { state, updated } = options;
+    // Seed from the primitive's current state, then keep it in sync via its
+    // subscription (fires immediately + on every transition).
+    let bundle = $state(state.get().bundle);
+    let contract = $state(state.get().contract);
+    $effect(() => {
+        const unsubscribe = state.subscribe((s) => {
+            bundle = s.bundle;
+            contract = s.contract;
+        });
+        return unsubscribe;
+    });
+    // Push the bundle signal when SvelteKit reports a new deployment. Reading
+    // `updated()` inside the effect makes it a reactive dependency, so a flip to
+    // true re-runs and forwards it. The primitive's bundle signal is idempotent,
+    // so re-forwarding is harmless.
+    if (updated) {
+        $effect(() => {
+            if (updated())
+                state.notifyBundleUpdated();
+        });
+    }
+    const updateAvailable = $derived(bundle || contract);
+    return {
+        get bundle() {
+            return bundle;
+        },
+        get contract() {
+            return contract;
+        },
+        get updateAvailable() {
+            return updateAvailable;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-svelte",
-  "version": "0.38.6",
+  "version": "0.38.7",
   "description": "Svelte 5 components for SMRT user management - auth, users, tenants, roles, permissions, groups",
   "type": "module",
   "smrtRawPrimitives": "strict",
@@ -92,10 +92,10 @@
     "@tanstack/db": "^0.6.14",
     "@tanstack/svelte-db": "^0.1.91",
     "esm-env": "^1.2.2",
-    "@happyvertical/smrt-types": "0.38.6",
-    "@happyvertical/smrt-languages": "0.38.6",
-    "@happyvertical/smrt-ui": "0.38.6",
-    "@happyvertical/smrt-web": "0.38.6"
+    "@happyvertical/smrt-languages": "0.38.7",
+    "@happyvertical/smrt-types": "0.38.7",
+    "@happyvertical/smrt-ui": "0.38.7",
+    "@happyvertical/smrt-web": "0.38.7"
   },
   "peerDependencies": {
     "@huggingface/transformers": ">=3.8.1",