@happyvertical/smrt-web 0.51.32 → 0.51.34

package/dist/persistence.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @happyvertical/smrt-web — the durable persistence capability (#1764).
+ *
+ * The read-side twin of the offline outbox (#1762): an opted-in collection
+ * WARM-STARTS from a durable browser snapshot on load — rendering stale rows
+ * instantly — then the engine revalidates in the background via its normal SWR.
+ * A reload therefore paints last-known data with zero network round-trip before
+ * the fresh fetch lands. This is the read-cache rehydrate the outbox explicitly
+ * left to #1764 (see offline.ts "Known gap").
+ *
+ * This is a {@link SmrtWebCapability} plug-in, so it lives in its OWN module and
+ * an app opts a collection in by passing `persistCollection(config)` in that
+ * collection's `capabilities` array. A collection WITHOUT it is byte-for-byte
+ * the collection of today (the seam's no-op guarantee) — nothing persists
+ * implicitly, which is exactly the "persistence is opt-in per model" acceptance
+ * criterion. Sensitive models simply omit the capability and never touch disk.
+ *
+ * ## How it plugs into the seam
+ *
+ * - `warmStart(ctx)` — reads the persisted snapshot for
+ *   `(durableStoreNamespace(namespace), collection)` and returns its rows to
+ *   seed the cache (the factory's rehydrate path; `preload()` awaits the async
+ *   return so it suppresses the first `list()`). If the namespace's
+ *   `manifestHash` changed, the key differs → NO snapshot is found → an empty
+ *   return → a fresh fetch with NO stale-schema hydration. So "a manifest-hash
+ *   change drops persisted caches" is AUTOMATIC via the namespace including the
+ *   hash — no explicit invalidation.
+ * - `onAttach(ctx)` — subscribes to the collection's changes (via the seam's
+ *   engine-free `ctx.subscribe`) and persists the current row snapshot
+ *   (`ctx.snapshot`) DEBOUNCED (trailing) to avoid thrashing IndexedDB on a
+ *   burst of writes. Also registers the shared store as a durable resource so a
+ *   logout `wipeDurableStore` clears it.
+ * - `teardown(ctx)` — unsubscribes, unregisters the durable resource BEFORE
+ *   closing IndexedDB (the #1762 discipline: a later `wipeDurableStore` is then a
+ *   no-op, never a double-clear), and the LAST detach closes the shared db. The
+ *   durable SNAPSHOT survives for the next load.
+ *
+ * ## Namespace segregation + logout wipe (shared with the outbox)
+ *
+ * The durable namespace folds api base / tenant / identity / manifest hash, so
+ * switching users on one device lands on a DIFFERENT IndexedDB database — one
+ * user can never read another's persisted rows. The SAME namespace is shared
+ * with the outbox (#1762), so registering this store under it means a single
+ * {@link wipeDurableStore} on logout clears BOTH the persisted collections AND
+ * the outbox queue in one call (the "logout wipe clears persisted data AND
+ * outbox state" AC).
+ *
+ * ## Degrade, don't crash
+ *
+ * If IndexedDB is unavailable (a probe `open()` throws — private mode, sandboxed
+ * iframe), the capability `console.warn`s ONCE and behaves as non-persistent:
+ * `warmStart` returns nothing (normal fetch), write-back is a no-op. It never
+ * throws — matching the outbox's `probeIndexedDb()` posture.
+ *
+ * Engine-free public surface: no `@tanstack/*` type appears — inside the
+ * engine-absorption boundary (#1761), verified by
+ * scripts/check-smrt-web-engine-boundary.mjs.
+ */
+import type { SmrtWebCapability } from './capability.js';
+import type { SmrtWebDataSurfaceIdentity } from './data-surface-actions.js';
+import { type DurableStoreKey } from './durable-store.js';
+/** Default trailing-debounce window (ms) for the write-back. */
+export declare const DEFAULT_PERSIST_DEBOUNCE_MS = 250;
+/**
+ * Configuration for {@link persistCollection}. Generic in the collection's row
+ * type `TData` so the capability matches the collection it plugs into.
+ */
+export interface PersistCollectionConfig<TData extends object = object> {
+    /**
+     * The REST collection name this snapshot is keyed by — MUST be the SAME
+     * `definition.name` passed to {@link createSmrtCollection} (it is the store
+     * key under the namespace). Provided explicitly (not read off the ctx) so the
+     * config is self-describing and testable.
+     */
+    collection: string;
+    /**
+     * The durable-store identity this snapshot is namespaced under — folds api
+     * base / tenant / identity / manifest hash, so a logout, tenant switch, or a
+     * contract-changing deploy lands on a different IndexedDB database (never
+     * cross-identity reuse, and a shape change drops old snapshots). Shared with
+     * the outbox (#1762) via the same {@link durableStoreNamespace}, so one
+     * {@link wipeDurableStore} clears both.
+     *
+     * The canonical `manifestHash` source is the build-time inject — the
+     * `manifestHash` constant the generated `@happyvertical/smrt-virt-web` module
+     * exports (#1764). Thread it here at the call site.
+     */
+    namespace: DurableStoreKey;
+    /**
+     * Trailing-debounce window (ms) for the write-back snapshot. A burst of
+     * mutations within the window collapses to ONE IndexedDB write of the final
+     * row set. Default {@link DEFAULT_PERSIST_DEBOUNCE_MS}. Set 0 to write on
+     * every change (tests).
+     */
+    debounceMs?: number;
+}
+/**
+ * Build a durable persistence capability for a collection. Add the returned
+ * capability to the collection's `capabilities` array; a collection without it
+ * is unaffected (the seam's no-op guarantee — the "opt-in per model" AC).
+ *
+ * The same `namespace` across multiple collections shares ONE snapshot database
+ * (one open, one durable resource, one wipe), and each collection is keyed by
+ * its own `collection` name within it.
+ */
+export declare function persistCollection<TData extends object = object>(config: PersistCollectionConfig<TData>): SmrtWebCapability<TData>;
+/** Configuration for {@link persistDataSurface}. */
+export interface PersistDataSurfaceConfig {
+    /**
+     * The durable-store identity — the SAME key the app's collections and
+     * outbox use. It folds the principal (`identityId`) and tenant, so a surface
+     * whose rows the server scopes per principal lands on a per-principal
+     * database: another user on the device never reads them, and one
+     * `wipeDurableStore(namespace)` on logout clears them with everything else.
+     */
+    namespace: DurableStoreKey;
+    /** The mounted surface's identity (`descriptor.identity`) — the store key. */
+    identity: SmrtWebDataSurfaceIdentity;
+    /** Trailing-debounce window for `save` (ms). Default {@link DEFAULT_PERSIST_DEBOUNCE_MS}. */
+    debounceMs?: number;
+}
+/** A durable row snapshot for one mounted data surface (#3021). */
+export interface PersistedDataSurface<TRow extends object = object> {
+    /**
+     * The rows last saved for this surface under this namespace, or `undefined`
+     * when none exist (first load, a different principal/tenant/manifest, a
+     * wipe, or no IndexedDB). Render them as stale, then revalidate. After a
+     * `wipeDurableStore` of its namespace a handle is inert (`load` finds
+     * nothing, `save` is ignored); create a new one for the next scope.
+     */
+    load(): Promise<TRow[] | undefined>;
+    /**
+     * Replace the persisted rows (debounced, trailing; last call wins). Pass the
+     * surface's CURRENT rows whenever the page refreshes them. Rows must be
+     * structured-clone-safe plain objects.
+     */
+    save(rows: readonly TRow[]): void;
+    /** Write any pending `save` now. */
+    flush(): Promise<void>;
+    /** Flush a pending `save`, then release the shared store. */
+    dispose(): Promise<void>;
+}
+/**
+ * Persist and rehydrate a mounted data surface's rows (#3021) — the
+ * `persistCollection` twin for a surface (e.g. one registered with
+ * `mountListDataSurface`) whose rows come from a server-scoped data-surface
+ * query rather than a generated `list` route. The page owns its rows, so it
+ * owns the calls: `load()` before the first fetch to paint stale rows, then
+ * `save(rows)` whenever it refreshes them.
+ *
+ * Shares the namespace's snapshot database, durable-resource registration,
+ * and IndexedDB-unavailable degrade with {@link persistCollection}: a
+ * manifest-hash, tenant, or identity change lands on a different database, and
+ * `wipeDurableStore(namespace)` clears the surface's rows with the rest.
+ */
+export declare function persistDataSurface<TRow extends object = object>(config: PersistDataSurfaceConfig): PersistedDataSurface<TRow>;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAC5E,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,oBAAoB,CAAC;AAO5B,gEAAgE;AAChE,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,uBAAuB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IACpE;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,eAAe,CAAC;IAC3B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAqID;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7D,MAAM,EAAE,uBAAuB,CAAC,KAAK,CAAC,GACrC,iBAAiB,CAAC,KAAK,CAAC,CAqJ1B;AAED,oDAAoD;AACpD,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,SAAS,EAAE,eAAe,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,EAAE,0BAA0B,CAAC;IACrC,6FAA6F;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,mEAAmE;AACnE,MAAM,WAAW,oBAAoB,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IAChE;;;;;;OAMG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,EAAE,GAAG,SAAS,CAAC,CAAC;IACpC;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,SAAS,IAAI,EAAE,GAAG,IAAI,CAAC;IAClC,oCAAoC;IACpC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,6DAA6D;IAC7D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAsBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAC7D,MAAM,EAAE,wBAAwB,GAC/B,oBAAoB,CAAC,IAAI,CAAC,CAiF5B"}

package/dist/remote-query.d.ts

@@ -0,0 +1,61 @@
+import { type SmrtWebDataQueryRequest, type SmrtWebDataQueryResult, type SmrtWebDataQueryTransport } from './data-query.js';
+import type { SmrtWebCollection } from './index.js';
+/** How a query run is allowed to affect the visible query state. */
+export type SmrtWebQueryMode = 'visible' | 'background' | 'prefetch' | 'silent';
+export interface SmrtWebQueryRunOptions {
+    mode?: SmrtWebQueryMode;
+    signal?: AbortSignal;
+    /** Cancel this run after the given number of milliseconds. */
+    deadlineMs?: number;
+    /** Bypass the keyed cache and execute a fresh request (used by refresh). */
+    force?: boolean;
+}
+export interface SmrtWebQueryPage {
+    kind: 'offset' | 'cursor';
+    limit: number;
+    offset?: number;
+    nextCursor?: string;
+    hasMore: boolean;
+}
+export interface SmrtWebQueryState<TData extends object = object> {
+    readonly rows: ReadonlyArray<TData>;
+    readonly page: SmrtWebQueryPage | undefined;
+    readonly total: SmrtWebDataQueryResult['total'] | undefined;
+    readonly loading: boolean;
+    readonly refreshing: boolean;
+    readonly stale: boolean;
+    readonly error: unknown;
+    readonly lastUpdated: number | undefined;
+    readonly result: SmrtWebDataQueryResult | undefined;
+}
+export interface SmrtWebQueryLiveSubscription {
+    unsubscribe(): void;
+    reconnect(): void;
+}
+export interface SmrtWebQueryTransport extends SmrtWebDataQueryTransport {
+    /** Subscribe to changes for this exact query, not the entire collection. */
+    subscribe?(request: SmrtWebDataQueryRequest, onResult: (result: unknown) => void, options?: {
+        signal?: AbortSignal;
+    }): SmrtWebQueryLiveSubscription | {
+        unsubscribe(): void;
+    };
+}
+export interface SmrtWebQuery<TData extends object = object> {
+    readonly state: SmrtWebQueryState<TData>;
+    readonly request: SmrtWebDataQueryRequest | undefined;
+    execute(request: SmrtWebDataQueryRequest, options?: SmrtWebQueryRunOptions): Promise<SmrtWebDataQueryResult>;
+    refresh(options?: Omit<SmrtWebQueryRunOptions, 'mode' | 'force'>): Promise<SmrtWebDataQueryResult | undefined>;
+    retry(): Promise<SmrtWebDataQueryResult | undefined>;
+    subscribe(listener: (state: SmrtWebQueryState<TData>) => void): () => void;
+    subscribeLive(): SmrtWebQueryLiveSubscription | undefined;
+    invalidate(): void;
+    dispose(): void;
+}
+/**
+ * Create a query controller over one SMRT collection. Query rows stay in a
+ * separate keyed cache; the collection's full list is never loaded.
+ */
+export declare function createSmrtWebQuery<TData extends object>(_collection: SmrtWebCollection<TData>, transport: SmrtWebQueryTransport, options?: {
+    staleTimeMs?: number;
+}): SmrtWebQuery<TData>;
+//# sourceMappingURL=remote-query.d.ts.map

package/dist/remote-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-query.d.ts","sourceRoot":"","sources":["../src/remote-query.ts"],"names":[],"mappings":"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"}

package/dist/sse-client.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @happyvertical/smrt-web — live-updates subscriber (#1763, CLIENT half).
+ *
+ * The browser half of live cache invalidation: ONE app-wide subscriber that
+ * turns the server's coarse change signals into collection refetches, so a
+ * dashboard reflects another session's writes without a manual refresh or
+ * aggressive polling. It speaks the two channels the #1763 server half
+ * generated:
+ *
+ * - the push channel — the generated `_events` Server-Sent-Events route
+ *   (`packages/core/src/generators/events-route.ts`): NAMED events
+ *   `event: change` / `event: resync` whose `data` is `{table, operation,
+ *   rowId, tenantId}`, with the cursor `seq` carried ONLY in the SSE `id:`
+ *   field (mirrored by the browser to `MessageEvent.lastEventId`), plus
+ *   `event: manifest` for live contract detection. Heartbeats are
+ *   `: heartbeat` comment lines EventSource ignores natively.
+ * - the pull channel — the generated `_changes` route
+ *   (`packages/core/src/generators/changes-route.ts`): `GET {changesUrl}
+ *   ?since=&tables=&limit=` →
+ *   `{changes, cursor, resyncRequired?, resyncCursor?}`, the full fallback
+ *   where SSE is unavailable.
+ *
+ * ## No row payload, no tenant logic, no authorization here
+ *
+ * The wire carries only a signal (table + row id + operation), never a row.
+ * A signal makes the subscriber INVALIDATE — the refetch re-reads through the
+ * authorized collection routes, so authorization and tenant-scoping stay
+ * ENTIRELY on the read path, exactly as the server enforces (the `_events`
+ * stream is auth-guarded and tenant-scoped at connection open; `_changes` is
+ * tenant-scoped per request). This module therefore does NO tenant filtering
+ * and needs no identity — it just maps `table → invalidate`.
+ *
+ * ## One app-wide instance (mirrors createSmrtWebClient)
+ *
+ * A consumer constructs ONE subscriber and passes it to every
+ * {@link liveInvalidation} capability — the same "one shared handle" convention
+ * as {@link createSmrtWebClient}. It is NOT auto-derived per collection: one
+ * EventSource / one poll loop feeds every registered collection.
+ *
+ * ## Idempotent invalidation → no client-side dedup
+ *
+ * Re-invalidating on a replayed change (a reconnect replays the tail from the
+ * cursor) is safe: invalidation only schedules a background refetch, and the
+ * factory's relationship-derived invalidation is itself idempotent
+ * (over-invalidation merely refetches). So the subscriber deliberately does NO
+ * seq dedup — a replayed signal STILL fires, which is exactly what guarantees a
+ * gap misses no invalidation. `lastSeq` is a resume cursor for the poll
+ * fallback, not a dedup filter.
+ *
+ * Engine boundary: no `@happyvertical/smrt-*` import and no `@tanstack/*`
+ * import — URLs and `fetch` arrive as config, and the refetch primitive arrives
+ * as the `invalidate` callback each capability wires from `ctx.invalidate()`.
+ * smrt-web has no logger dependency, so faults are surfaced via `console.warn`
+ * (matching `warnCapability` / core's `deliverLocally` style).
+ *
+ * The server may also emit a named `manifest` event at connection open (#1859):
+ * `{ manifestHash }`. When this differs from the running build hash configured
+ * here, the subscriber latches `updateState.contract`.
+ */
+import type { SmrtWebCapability } from './capability.js';
+import type { UpdateState } from './update-state.js';
+/**
+ * The minimal `EventSource` surface the subscriber uses — declared here so a
+ * test injects a fake without a real DOM, and so this module compiles without
+ * DOM `lib` beyond the ambient global. A real `EventSource` satisfies it
+ * structurally.
+ */
+export interface SmrtWebEventSource {
+    /** Native reconnect fires this after (re)connect. */
+    onopen: ((this: unknown, ev: unknown) => unknown) | null;
+    /**
+     * Fires on a stream error. A transient drop leaves `readyState` at OPEN
+     * (0→…) and the browser auto-reconnects with `Last-Event-ID`; a fatal error
+     * (server 401 / route disabled) leaves it CLOSED.
+     */
+    onerror: ((this: unknown, ev: unknown) => unknown) | null;
+    /**
+     * Fires only for UNNAMED (`message`) events. The `_events` frames are NAMED
+     * (`change` / `resync`), so this never fires for them — the subscriber uses
+     * {@link addEventListener} instead. Present only to satisfy the structural
+     * type of a real EventSource.
+     */
+    onmessage: ((this: unknown, ev: unknown) => unknown) | null;
+    /** Register a listener for a NAMED event (`change`, `resync`). */
+    addEventListener(type: string, listener: (ev: {
+        data: string;
+        lastEventId: string;
+    }) => void): void;
+    /** Close the stream (stops reconnection). */
+    close(): void;
+    /** `CONNECTING` (0), `OPEN` (1), or `CLOSED` (2). */
+    readonly readyState: number;
+}
+/** Factory that constructs an {@link SmrtWebEventSource} for a URL. */
+export type SmrtWebEventSourceFactory = (url: string, init: {
+    withCredentials: boolean;
+}) => SmrtWebEventSource | null | undefined;
+/** Configuration for {@link createSmrtWebEventSubscriber}. */
+export interface SmrtWebEventSubscriberConfig {
+    /** Absolute or same-origin URL of the generated `_events` SSE route. */
+    eventsUrl: string;
+    /** Absolute or same-origin URL of the generated `_changes` route (fallback). */
+    changesUrl: string;
+    /** `fetch` implementation for the polling fallback. Defaults to global fetch. */
+    fetchFn?: typeof fetch;
+    /**
+     * Factory for the EventSource. Defaults to `new globalThis.EventSource(url,
+     * { withCredentials })`, guarded by a `typeof` check — when EventSource is
+     * absent (or the factory yields nothing) the subscriber starts on the polling
+     * fallback instead.
+     */
+    eventSourceFactory?: SmrtWebEventSourceFactory;
+    /** Poll interval for the `_changes` fallback (ms). Default 5000. */
+    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'>;
+}
+/** Which transport a subscriber is currently using. */
+export type SmrtWebSubscriberTransport = 'sse' | 'polling' | 'idle';
+/**
+ * The ONE app-wide live-updates subscriber. Construct once (see
+ * {@link createSmrtWebEventSubscriber}) and pass it to every
+ * {@link liveInvalidation} capability.
+ */
+export interface SmrtWebEventSubscriber {
+    /**
+     * The live transport: `'sse'` while the EventSource is the source of truth,
+     * `'polling'` when running (or downgraded to) the `_changes` fallback,
+     * `'idle'` before any transport starts.
+     */
+    readonly transport: SmrtWebSubscriberTransport;
+    /**
+     * Register an invalidator for a physical table. Returns an unregister
+     * function. Multiple invalidators may share a table (two live collections);
+     * a `change` for that table fires them all.
+     */
+    registerTable(table: string, invalidate: () => void): () => void;
+    /** Invalidate every registered table (a `resync` / `resyncRequired`). */
+    invalidateAll(): void;
+    /** Tear down the live transport and drop all registrations. */
+    close(): void;
+}
+/**
+ * Create the app-wide live-updates subscriber. Feature-detects ONCE at
+ * construction: an available EventSource connects the SSE stream; otherwise it
+ * starts the `_changes` poll loop. A fatal SSE error later downgrades to
+ * polling for the rest of the subscriber's life (no flap-back).
+ */
+export declare function createSmrtWebEventSubscriber(config: SmrtWebEventSubscriberConfig): SmrtWebEventSubscriber;
+/** Configuration for the {@link liveInvalidation} capability. */
+export interface LiveInvalidationConfig {
+    /** The one app-wide subscriber from {@link createSmrtWebEventSubscriber}. */
+    subscriber: Pick<SmrtWebEventSubscriber, 'registerTable' | 'invalidateAll' | 'transport'>;
+    /**
+     * The PHYSICAL table name this collection reads. EXPLICIT because a
+     * `SmrtWebCollectionDefinition` has no physical-table field and STI children
+     * share one base table — the subscriber keys signals by physical table, so a
+     * guess would mis-route invalidations.
+     */
+    tableName: string;
+}
+/**
+ * A thin per-collection capability that subscribes THIS collection to live
+ * signals for its `tableName`. On attach it registers `ctx.invalidate` (the
+ * factory's relationship-derived refetch primitive) with the shared subscriber;
+ * on teardown it unregisters. All transport, reconnection, and fan-out live in
+ * the {@link createSmrtWebEventSubscriber}; this capability is just the wire
+ * between one collection and that one subscriber.
+ */
+export declare function liveInvalidation<TData extends object = object>(config: LiveInvalidationConfig): SmrtWebCapability<TData>;
+//# sourceMappingURL=sse-client.d.ts.map

package/dist/sse-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-client.d.ts","sourceRoot":"","sources":["../src/sse-client.ts"],"names":[],"mappings":"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"}

package/dist/update-state/meta-store.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @happyvertical/smrt-web — the durable version-meta store (#1764).
+ *
+ * A tiny raw IndexedDB key/value store for version-awareness bookkeeping —
+ * currently the single "last-seen manifestHash" per durable-store namespace,
+ * which contract-change detection ({@link ../update-state}) compares the running
+ * build against across loads. One database per namespace
+ * ({@link durableStoreNamespace}), one object store (`meta`) keyed by a string
+ * key, each record `{ key, value }`.
+ *
+ * Separate from the collection snapshot store (persistence/snapshot-store.ts):
+ * that one holds per-collection row blobs; this holds scalar version state, and
+ * update-awareness must work even for an app that persists no collection. Both
+ * register under the SAME namespace so one {@link wipeDurableStore} clears
+ * everything on logout.
+ *
+ * Raw IndexedDB, ZERO new runtime dependency — inside the engine-absorption
+ * boundary (#1761), mirroring offline/durable-queue.ts.
+ */
+/** IndexedDB object-store name inside every version-meta database. */
+export declare const META_STORE = "meta";
+/** IndexedDB schema version. Bump only on a store/index migration. */
+export declare const META_DB_VERSION = 1;
+/**
+ * Suffix appended to the durable-store namespace to form this store's OWN
+ * IndexedDB database name — DISTINCT from both the merged outbox's bare-namespace
+ * DB and the snapshot store's `::snapshots` DB. Required so persistence + outbox
+ * + version-meta under one shared namespace never collide on a single-store v1
+ * database (a second opener would find the existing v1 DB, skip
+ * `onupgradeneeded`, and throw `NotFoundError` on `objectStore('meta')`).
+ * `wipeDurableStore` still clears all three via each registered `clear()`.
+ */
+export declare const META_DB_SUFFIX = "::meta";
+/** The reserved key under which the last-seen manifest hash is stored. */
+export declare const LAST_SEEN_MANIFEST_HASH_KEY = "lastSeenManifestHash";
+/**
+ * The durable version-meta store over one IndexedDB database. Constructed via
+ * {@link openVersionMetaStore}; used through the async methods below.
+ */
+export declare class VersionMetaStore {
+    private readonly db;
+    /** The IndexedDB database name (== the durable-store namespace). */
+    readonly dbName: string;
+    constructor(db: IDBDatabase, dbName: string);
+    /** Read the value for `key`, or `undefined` if unset / malformed. */
+    get(key: string): Promise<string | undefined>;
+    /** Write (replacing) the value for `key`; resolves once durably committed. */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Drop EVERY meta record — the durable-store `clear()` for
+     * {@link wipeDurableStore}, so a logout also clears the last-seen manifest
+     * hash (the AC "wipe clears the last-seen-hash record").
+     */
+    clear(): Promise<void>;
+    /** Close the underlying database handle. */
+    close(): void;
+}
+/**
+ * Open (creating/upgrading as needed) the version-meta database for `namespace`
+ * and wrap it in a {@link VersionMetaStore}. `namespace` MUST be a
+ * {@link durableStoreNamespace} string. The actual IndexedDB database name is
+ * `${namespace}${META_DB_SUFFIX}` — a DISTINCT database from the outbox's and
+ * the snapshot store's, so the three never collide (see {@link META_DB_SUFFIX}).
+ */
+export declare function openVersionMetaStore(namespace: string): Promise<VersionMetaStore>;
+//# sourceMappingURL=meta-store.d.ts.map

package/dist/update-state/meta-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-store.d.ts","sourceRoot":"","sources":["../../src/update-state/meta-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,sEAAsE;AACtE,eAAO,MAAM,UAAU,SAAS,CAAC;AACjC,sEAAsE;AACtE,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,WAAW,CAAC;AACvC,0EAA0E;AAC1E,eAAO,MAAM,2BAA2B,yBAAyB,CAAC;AA4BlE;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAc;IACjC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM;IAK3C,qEAAqE;IAC/D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAWnD,8EAA8E;IACxE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpD;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,4CAA4C;IAC5C,KAAK,IAAI,IAAI;CAGd;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,gBAAgB,CAAC,CA4B3B"}

package/dist/update-state.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @happyvertical/smrt-web — the framework-free `updateAvailable` primitive (#1764).
+ *
+ * A tiny pub/sub carrying an app's "an update is available" state, driven by TWO
+ * INDEPENDENT signals so the presentation (a toast / reload prompt, shipped as a
+ * Svelte binding in smrt-svelte) can react to either:
+ *
+ *  - **bundle** — the client BUNDLE changed on the server (a new deploy of the
+ *    front-end assets). SvelteKit already detects this via its native `updated`
+ *    store (version.json polling); the consumer/smrt-svelte binding pushes it in
+ *    here through {@link UpdateState.notifyBundleUpdated}. This module owns no
+ *    polling — it just holds the state and fans out.
+ *  - **contract** — the API CONTRACT changed: the manifest hash, which only SMRT
+ *    knows. Detected here under the BUILD-TIME-INJECT decision (#1764): on init
+ *    we compare the RUNNING build's `manifestHash` (passed in by the consumer,
+ *    imported from `@happyvertical/smrt-virt-web`) against a persisted
+ *    "last-seen manifestHash" in durable storage. If they differ, the contract
+ *    changed across this load → the `contract` signal fires and the new value is
+ *    stored. So a returning user whose app was rebuilt against a new schema is
+ *    told to reload.
+ *
+ * `updateAvailable` is simply `bundle || contract` — either signal means "an
+ * update is available".
+ *
+ * ## Scope: load-time contract detection only (documented follow-up)
+ *
+ * Contract detection here fires at MOST once per load (the compare-on-init).
+ * LIVE-while-open contract detection — learning mid-session that the server
+ * redeployed a new contract, via the `_events` SSE manifest frame — pushes the
+ * same sticky `contract` signal through {@link UpdateState.notifyContractUpdated}.
+ *
+ * ## Durable last-seen storage + logout wipe
+ *
+ * The last-seen hash lives in the version-meta store
+ * (update-state/meta-store.ts) under the durable-store namespace, registered as
+ * a durable resource so a logout {@link wipeDurableStore} clears it too (the AC
+ * "wipe clears the last-seen-hash record"). If IndexedDB is unavailable the
+ * primitive still works for the bundle signal; contract detection degrades to a
+ * no-op (no durable baseline to compare against) rather than throwing.
+ *
+ * Engine-free (no `@tanstack/*` import) and framework-free (no Svelte/DOM) — the
+ * reactive binding is a separate smrt-svelte adapter (#1764 PART E).
+ */
+import { type DurableStoreKey } from './durable-store.js';
+/** The two independent update signals plus their derived union. */
+export interface UpdateAvailableState {
+    /** The client bundle changed on the server (SvelteKit `updated`). */
+    readonly bundle: boolean;
+    /** The API contract (manifest hash) changed across this load. */
+    readonly contract: boolean;
+    /** `bundle || contract` — either means an update is available. */
+    readonly updateAvailable: boolean;
+}
+/** Configuration for {@link createUpdateState}. */
+export interface UpdateStateConfig {
+    /**
+     * The RUNNING build's web-collection shape digest — the `manifestHash`
+     * constant the generated `@happyvertical/smrt-virt-web` module exports
+     * (#1764). Compared against the persisted last-seen value to detect a contract
+     * change across loads. Omit to disable contract detection (bundle-only).
+     */
+    manifestHash?: string;
+    /**
+     * The durable-store identity the last-seen manifest hash is namespaced under —
+     * folds api base / tenant / identity (and, yes, the manifest hash itself, but
+     * see below). Shared with persistence/outbox so one {@link wipeDurableStore}
+     * clears the last-seen record too.
+     *
+     * NOTE the namespace's OWN `manifestHash` segment should be a STABLE value
+     * (e.g. the app's api-version or a constant), NOT the running build hash —
+     * otherwise a contract change would move the namespace and the compare would
+     * never find the prior value (always "first run"). Contract change is detected
+     * by the STORED VALUE under a stable namespace, not by the namespace moving.
+     */
+    namespace: DurableStoreKey;
+}
+/** The framework-free update-available primitive. */
+export interface UpdateState {
+    /** The current signal state (a fresh immutable snapshot). */
+    get(): UpdateAvailableState;
+    /**
+     * Subscribe to state changes; the callback fires immediately with the current
+     * state and again on every transition. Returns an unsubscribe function.
+     */
+    subscribe(callback: (state: UpdateAvailableState) => void): () => void;
+    /**
+     * Push the BUNDLE signal — call from the consumer/smrt-svelte binding when
+     * SvelteKit's `updated` store flips true. Idempotent: once set it stays set
+     * (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).
+     * Primarily for tests/SSR; UI code just subscribes.
+     */
+    readonly ready: Promise<void>;
+    /** Detach the durable resource (does NOT wipe — that's wipeDurableStore). */
+    dispose(): void;
+}
+/**
+ * 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, and
+ * {@link UpdateState.notifyContractUpdated} feeds the live contract signal. A
+ * change to EITHER signal notifies subscribers.
+ */
+export declare function createUpdateState(config: UpdateStateConfig): UpdateState;
+//# sourceMappingURL=update-state.d.ts.map

package/dist/update-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-state.d.ts","sourceRoot":"","sources":["../src/update-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,oBAAoB,CAAC;AAO5B,mEAAmE;AACnE,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAED,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,eAAe,CAAC;CAC5B;AAED,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,6DAA6D;IAC7D,GAAG,IAAI,oBAAoB,CAAC;IAC5B;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACvE;;;;OAIG;IACH,mBAAmB,IAAI,IAAI,CAAC;IAC5B;;;;OAIG;IACH,qBAAqB,IAAI,IAAI,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAoHxE"}