@happyvertical/smrt-web 0.38.8 → 0.38.10

package/AGENTS.md

@@ -223,7 +223,9 @@ external trigger, `teardown` unregisters); it never touches the engine —
   `createSmrtWebClient`: construct once, pass to every collection; NOT
   auto-derived per collection — one EventSource / one poll loop feeds all).
   Config: `{ eventsUrl, changesUrl, fetchFn?, eventSourceFactory?,
-  pollIntervalMs?=5000, withCredentials?=true }`. Public surface:
+  pollIntervalMs?=5000, withCredentials?=true, manifestHash?, updateState? }`.
+  `manifestHash` + `updateState` enable live contract detection from the
+  server's connection-open `manifest` SSE frame (#1859). Public surface:
   `{ transport: 'sse'|'polling'|'idle', registerTable(table, invalidate) →
   unregister, invalidateAll(), close() }`.
 - `liveInvalidation({ subscriber, tableName })` — the thin per-collection
@@ -238,15 +240,17 @@ half in `packages/core/src/generators/`):
 - Push — the `_events` SSE route (`events-route.ts`): **NAMED** events
   `event: change` / `event: resync`, `data` is `{table, operation, rowId,
   tenantId}`, and the cursor `seq` is carried **only** in the SSE `id:` field
-  (the browser mirrors it to `MessageEvent.lastEventId`). `resync` uses that
-  `id:` as the fresh horizon for any later polling downgrade. Heartbeats are
-  `: heartbeat` comment lines EventSource ignores natively.
+  (the browser mirrors it to `MessageEvent.lastEventId`). `event: manifest`
+  carries `{ manifestHash }` at connection open so a reconnect can latch the
+  contract update signal. `resync` uses its `id:` as the fresh horizon for any
+  later polling downgrade. Heartbeats are `: heartbeat` comment lines
+  EventSource ignores natively.
 - Pull — the `_changes` route (`changes-route.ts`): `GET {changesUrl}?since=
   &tables=` → `{changes, cursor, resyncRequired?, resyncCursor?}`, the full
   fallback.
 
 **The NAMED-event gotcha.** The frames are named, so the subscriber wires
-`es.addEventListener('change', …)` / `('resync', …)` — **`onmessage` never
+`es.addEventListener('change', …)` / `('resync', …)` / `('manifest', …)` — **`onmessage` never
 fires** for a named event and would silently receive nothing. A `change` frame's
 `data` is JSON-parsed **defensively**: malformed input is logged + dropped, never
 thrown back into the EventSource message loop (a throw there breaks later
@@ -348,7 +352,8 @@ A tiny pub/sub (`update-state.ts`) with TWO INDEPENDENT signals; `updateAvailabl
   `manifestHash` (passed in by the consumer, imported from
   `@happyvertical/smrt-virt-web`) against a persisted "last-seen manifestHash" in
   durable storage; if they differ → fire `contract` + store the new value. First
-  run (no baseline) records without firing.
+  run (no baseline) records without firing. The live `_events` manifest frame
+  can also push the same sticky signal via `notifyContractUpdated()` (#1859).
 
 The last-seen hash lives in `update-state/meta-store.ts` (a tiny IDB key/value
 store) under the durable namespace, registered as a durable resource so
@@ -356,12 +361,11 @@ store) under the durable namespace, registered as a durable resource so
 AC). Degrades gracefully if IndexedDB is absent (bundle-only) or no running hash
 is supplied.
 
-> **Trade-off / documented follow-up:** contract detection under build-time
-> inject fires at most once **per load** (compare-on-init). LIVE-while-open
-> contract detection — learning mid-session that the server redeployed (an SSE
-> deploy signal / runtime version endpoint) — is an EXPLICIT follow-up, not this
-> slice; it would push a second `contract` signal into the same primitive, which
-> is shaped for it.
+> **Trade-off:** live contract detection is reconnect-based. The server hash is
+> advertised when the `_events` stream opens, so a deploy surfaces when the tab
+> reconnects (instant when the deploy drops old SSE connections, otherwise on
+> the next natural reconnect). Reconnect-independent fan-out remains a later
+> enhancement.
 
 The reactive Svelte binding (`useUpdateAvailable`) ships in
 `@happyvertical/smrt-svelte/web` — it wires SvelteKit's `updated` store into the

package/dist/index.d.ts

@@ -133,8 +133,9 @@ export declare function createSmrtWebEventSubscriber(config: SmrtWebEventSubscri
 /**
  * Create the framework-free `updateAvailable` primitive. Kicks off async
  * contract detection immediately (compare running vs. persisted manifest hash);
- * {@link UpdateState.notifyBundleUpdated} feeds the bundle signal. A change to
- * EITHER signal notifies subscribers.
+ * {@link UpdateState.notifyBundleUpdated} feeds the bundle signal, and
+ * {@link UpdateState.notifyContractUpdated} feeds the live contract signal. A
+ * change to EITHER signal notifies subscribers.
  */
 export declare function createUpdateState(config: UpdateStateConfig): UpdateState;
 
@@ -807,6 +808,17 @@ export declare interface SmrtWebEventSubscriberConfig {
     pollIntervalMs?: number;
     /** `withCredentials` for the EventSource (cookie auth). Default true. */
     withCredentials?: boolean;
+    /**
+     * The RUNNING build's web-collection shape digest. When paired with
+     * `updateState`, a differing server hash from the `_events` manifest frame
+     * latches the contract update signal (#1859).
+     */
+    manifestHash?: string;
+    /**
+     * Optional update-state primitive from `createUpdateState()`. Only its
+     * contract signal is used here; bundle polling remains the caller's job.
+     */
+    updateState?: Pick<UpdateState, 'notifyContractUpdated'>;
 }
 
 /**
@@ -963,6 +975,12 @@ export declare interface UpdateState {
      * (a bundle update does not un-happen).
      */
     notifyBundleUpdated(): void;
+    /**
+     * Push the API CONTRACT signal — call when a live transport observes a server
+     * `manifestHash` that differs from this running build (#1859). Idempotent:
+     * once set it stays set (a contract mismatch does not un-happen).
+     */
+    notifyContractUpdated(): void;
     /**
      * Resolves once the async contract detection has settled (compared the running
      * hash against the persisted last-seen value and fired the signal if needed).

package/dist/index.js

@@ -1108,7 +1108,7 @@ function defaultEventSourceFactory(url, init) {
 	return new EventSourceCtor(url, init);
 }
 function createSmrtWebEventSubscriber(config) {
-	const { eventsUrl, changesUrl, fetchFn = (...args) => globalThis.fetch(...args), eventSourceFactory = defaultEventSourceFactory, pollIntervalMs = 5e3, withCredentials = true } = config;
+	const { eventsUrl, changesUrl, fetchFn = (...args) => globalThis.fetch(...args), eventSourceFactory = defaultEventSourceFactory, pollIntervalMs = 5e3, withCredentials = true, manifestHash, updateState } = config;
 	const tableInvalidators = /* @__PURE__ */ new Map();
 	let lastSeq = null;
 	let transport = "idle";
@@ -1170,6 +1170,19 @@ function createSmrtWebEventSubscriber(config) {
 		advanceLastSeqFromEventId(ev.lastEventId);
 		invalidateAll();
 	};
+	const onManifest = (ev) => {
+		if (closed || manifestHash === void 0 || !updateState) return;
+		try {
+			const serverHash = JSON.parse(ev.data).manifestHash;
+			if (typeof serverHash !== "string" || serverHash.length === 0) {
+				warn("dropping manifest frame with no manifestHash", ev.data);
+				return;
+			}
+			if (serverHash !== manifestHash) updateState.notifyContractUpdated();
+		} catch (error) {
+			warn("dropping malformed manifest frame", error);
+		}
+	};
 	const poll = async () => {
 		if (closed) return;
 		const tables = registeredTables();
@@ -1207,6 +1220,7 @@ function createSmrtWebEventSubscriber(config) {
 		eventSource = source;
 		source.addEventListener("change", onChange);
 		source.addEventListener("resync", onResync);
+		source.addEventListener("manifest", onManifest);
 		source.onerror = () => {
 			if (closed) return;
 			if (source.readyState === EVENT_SOURCE_CLOSED) {
@@ -1392,6 +1406,7 @@ function createUpdateState(config) {
 			};
 		},
 		notifyBundleUpdated: setBundle,
+		notifyContractUpdated: setContract,
 		ready: (async () => {
 			const runningHash = config.manifestHash;
 			if (runningHash === void 0) return;