@happyvertical/smrt-web 0.51.31 → 0.51.33

package/dist/ai.d.ts.map

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

package/dist/capability-classification.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The one capability classification rule this package applies, extracted so
+ * every declaration site in smrt-web shares a single implementation (#2587,
+ * #2588).
+ *
+ * Two sites consume it today: `webmcp.ts` (canonical definitions trusted
+ * through it directly, and its legacy CRUD switch's fail-closed default
+ * branch) and `intents.ts` (a declared view intent, which is never a CRUD
+ * verb and so resolves through the declaration rule alone). Keeping the rule
+ * here rather than private to `webmcp.ts` is what lets the intent path be a
+ * dependency-free module that never pulls the client-data engine.
+ *
+ * This module structurally mirrors `CapabilityEffect` / `CapabilityDeclaration`
+ * / `CapabilityClassification` in `@happyvertical/smrt-types` rather than
+ * importing them — this package's dependency-DAG guardrails keep it free of
+ * every `@happyvertical/*` dependency (see AGENTS.md "No inter-smrt
+ * dependencies"), the same reason `data-query.ts` mirrors that package's
+ * bounded query envelope structurally instead of importing it.
+ */
+/**
+ * Browser/agent-visible effect classification for a capability. `'read'`
+ * never mutates; `'write'` mutates within the application; `'destructive'`
+ * may remove or irreversibly change data.
+ */
+export type WebMcpToolEffect = 'read' | 'write' | 'destructive';
+/** Every valid {@link WebMcpToolEffect}, in exposure-breadth order. */
+export declare const WEBMCP_TOOL_EFFECTS: readonly WebMcpToolEffect[];
+/**
+ * An author-supplied, partial classification. Any omitted field resolves
+ * through the fail-closed rule on {@link resolveDeclaredCapability}, never
+ * through a CRUD- or name-based guess.
+ */
+export interface WebMcpCapabilityDeclaration {
+    effect?: WebMcpToolEffect;
+    idempotent?: boolean;
+    openWorld?: boolean;
+}
+/** A fully resolved classification. */
+export interface WebMcpCapabilityClassification {
+    effect: WebMcpToolEffect;
+    /**
+     * Derived, never declared: every non-read effect is annotated destructive
+     * to the browser, so a `write` capability cannot claim the MCP
+     * additive-only guarantee.
+     */
+    destructive: boolean;
+    idempotent: boolean;
+    openWorld: boolean;
+}
+/** The MCP-shaped annotation set a resolved classification emits. */
+export interface WebMcpCapabilityAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+    untrustedContentHint: boolean;
+}
+/**
+ * Resolve a declared capability with no CRUD/action-based guess — the shared
+ * fail-closed default documented on `CapabilityClassification` in
+ * `@happyvertical/smrt-types` (#2587): an omitted or invalid `effect`
+ * resolves to `'destructive'`, an omitted `idempotent` to `false`, an
+ * omitted `openWorld` to `true`. Each field defaults independently: a
+ * declared `effect: 'read'` does NOT imply `idempotent: true`.
+ */
+export declare function resolveDeclaredCapability(declared: WebMcpCapabilityDeclaration): WebMcpCapabilityClassification;
+/**
+ * The browser annotations a resolved classification is finally registered
+ * with. `destructiveHint` carries the DERIVED `destructive` flag, so a
+ * `write` capability is annotated destructive exactly like a generated
+ * custom model action declared `effect: 'write'`.
+ */
+export declare function capabilityAnnotations(classification: WebMcpCapabilityClassification): WebMcpCapabilityAnnotations;
+/**
+ * Encode a resolved classification as the INPUT hints
+ * `registerWebMcpBespokeTool` decodes (`bespokeDeclaredSemantics`), so a
+ * capability resolved here survives that registrar's own re-resolution
+ * unchanged.
+ *
+ * This is deliberately NOT {@link capabilityAnnotations}. That function emits
+ * the derived `destructive` flag, and `destructiveHint: true` is the first
+ * check the registrar makes — round-tripping it would silently upgrade every
+ * `write` capability to `destructive`. On the input side `destructiveHint`
+ * means "the author declared the destructive EFFECT", and `false` selects the
+ * `write` bucket; the registrar re-emits it as `true` on its way to the
+ * browser.
+ */
+export declare function capabilityDeclarationHints(classification: WebMcpCapabilityClassification): WebMcpCapabilityAnnotations;
+//# sourceMappingURL=capability-classification.d.ts.map

package/dist/capability-classification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-classification.d.ts","sourceRoot":"","sources":["../src/capability-classification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;AAEhE,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,EAAE,SAAS,gBAAgB,EAI1D,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,uCAAuC;AACvC,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,gBAAgB,CAAC;IACzB;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,qEAAqE;AACrE,MAAM,WAAW,2BAA2B;IAC1C,YAAY,EAAE,OAAO,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;IACvB,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,2BAA2B,GACpC,8BAA8B,CAYhC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,8BAA8B,GAC7C,2BAA2B,CAQ7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,8BAA8B,GAC7C,2BAA2B,CAQ7B"}

package/dist/capability.d.ts

@@ -0,0 +1,191 @@
+/**
+ * @happyvertical/smrt-web — capability extension seam (#1755).
+ *
+ * A capability is a small plug-in that hooks the {@link createSmrtCollection}
+ * lifecycle so a follow-on client slice — the offline outbox (#1762),
+ * persistence (#1764), or live SSE invalidation (#1763-client) — can live in
+ * its OWN module instead of contending on `index.ts`. The factory runs the six
+ * hooks below at fixed points; a collection with no capabilities is
+ * byte-for-byte the collection of today (the no-op guarantee).
+ *
+ * ## The engine boundary is sacred
+ *
+ * Every type here is expressed ENTIRELY in existing SMRT-owned terms
+ * (`SmrtWebCollectionDefinition`, `SmrtCrudFetchers`, `SmrtWebRow`, plain TS).
+ * No `@tanstack/*` type — no `QueryClient`, no engine `Collection` — appears on
+ * the capability surface, so the build's `.d.ts` boundary check stays green and
+ * the engine stays swappable. A capability that genuinely needs deeper engine
+ * access reaches it through the existing `getEngineCollection()` unknown-bridge
+ * from inside its own module — NEVER by widening these types.
+ *
+ * These types intentionally import nothing from `./index.ts` beyond the
+ * SMRT-owned contracts they name, so the seam is reviewable and unit-testable on
+ * its own (see {@link runWrapMutation}).
+ */
+import type { SmrtCrudFetchers, SmrtWebCollectionDefinition, SmrtWebRow, SmrtWebSubscription } from './index.js';
+/**
+ * The context every capability hook receives — a stable, engine-free view of
+ * the collection being built. All fields are the exact values the factory uses
+ * internally (the resolved cache key/id, the same fetchers), so a capability
+ * keys its own storage or subscriptions off the identical discriminators.
+ */
+export interface SmrtWebCapabilityContext<TData extends object = object> {
+    /** The generated definition this collection materializes. */
+    readonly definition: SmrtWebCollectionDefinition<TData>;
+    /** The CRUD fetchers the collection persists through. */
+    readonly fetchers: SmrtCrudFetchers;
+    /**
+     * The `queryKey` segments the collection's reads use — a LIVE view: from
+     * `onAttach`/`warmStart` onward it is the final key (including every
+     * capability-contributed segment); read during `contributeCacheKey` it omits
+     * that capability's own not-yet-applied segment. Treat as read-only.
+     */
+    readonly cacheKey: readonly string[];
+    /** The engine-collection id string (mirrors {@link cacheKey}). */
+    readonly cacheId: string;
+    /**
+     * Enter the SAME relationship-derived invalidation the factory runs after a
+     * settled mutation. A capability calls this to refetch this collection and its
+     * manifest-related collections in response to an EXTERNAL trigger (e.g. an SSE
+     * message) without reaching into the engine.
+     */
+    invalidate(): void;
+    /**
+     * A snapshot of the collection's current rows as plain public DTOs — the same
+     * projection as {@link SmrtWebCollection.toArray}, so the engine's virtual
+     * props never cross the boundary. The persistence slice (#1764) reads this in
+     * its write-back to serialize the current cache to disk. Populated by the real
+     * factory; a hand-built test context may omit it, so callers guard for its
+     * presence.
+     *
+     * SAFE ONLY FROM `onAttach` ONWARD. The factory's implementation closes over
+     * the engine collection, which is constructed AFTER `contributeCacheKey` and
+     * `warmStart` run — calling this from those earlier hooks would throw
+     * (temporal-dead-zone). Read rows from `onAttach`, `onSettled`, or an external
+     * trigger, never during construction.
+     */
+    snapshot?(): ReadonlyArray<SmrtWebRow<TData>>;
+    /**
+     * Subscribe to the collection's change notifications — the same stream as
+     * {@link SmrtWebCollection.subscribeChanges} (plain-DTO payloads). The
+     * persistence slice (#1764) wires its debounced write-back here in `onAttach`
+     * and detaches in `teardown`. Engine-free by construction: the payload is
+     * `unknown` (the capability only needs the change SIGNAL, then re-reads via
+     * {@link snapshot}), so no engine type crosses the seam. Populated by the real
+     * factory; a hand-built test context may omit it.
+     *
+     * SAFE ONLY FROM `onAttach` ONWARD (same reason as {@link snapshot}): it closes
+     * over the engine collection built after the pre-construction hooks.
+     */
+    subscribe?(callback: (changes: unknown) => void): SmrtWebSubscription;
+}
+/**
+ * A single mutation described in SMRT-owned terms — handed to
+ * {@link SmrtWebCapability.wrapMutation} and {@link SmrtWebCapability.onSettled}
+ * so a capability can inspect or intercept a write without touching the engine's
+ * transaction type.
+ */
+export interface SmrtWebMutationEnvelope {
+    /** Which mutation kind this describes. */
+    readonly kind: 'insert' | 'update' | 'delete';
+    /** The row key: the client-local id on insert, else the target row's id. */
+    readonly key: string;
+    /**
+     * The write payload: the full row on insert, the changed fields on update,
+     * and an empty object on delete (the key carries the target).
+     */
+    readonly data: Record<string, unknown>;
+    /**
+     * The server `updated_at` / `updatedAt` value the mutation is based on, when
+     * known. Update/delete handlers capture this from the original row so offline
+     * replay can preserve the sync/apply conflict guard even when the write
+     * payload only carries changed fields (or no fields for delete).
+     */
+    readonly baseUpdatedAt?: string;
+}
+/** The outcome handed to {@link SmrtWebCapability.wrapMutation}. */
+export type WrapMutationOutcome = {
+    handled: true;
+    result: unknown;
+} | {
+    handled: false;
+} | undefined;
+/** The settle outcome handed to {@link SmrtWebCapability.onSettled}. */
+export type MutationSettleOutcome = {
+    ok: true;
+    result: unknown;
+} | {
+    ok: false;
+    error: unknown;
+};
+/**
+ * A capability plugged into {@link createSmrtCollection}. Every hook is
+ * optional; a capability implements only the points its slice needs. Hooks fire
+ * in these fixed places, and capabilities run in ARRAY ORDER:
+ *
+ * - `contributeCacheKey` — ONCE, before the engine collection is constructed.
+ * - `warmStart` — ONCE, before the first read (seeds the cache).
+ * - `wrapMutation` — per mutation, BEFORE the fetcher, with a chance to handle
+ *   the write itself (offline).
+ * - `onSettled` — per mutation, AFTER it settles (success AND fetcher-throw).
+ * - `onAttach` — ONCE, right after the engine collection is constructed; the
+ *   ONLY place a capability registers an external (non-mutation) trigger such as
+ *   an SSE subscription.
+ * - `teardown` — in `cleanup()`, after the engine's own cleanup.
+ */
+export interface SmrtWebCapability<TData extends object = object> {
+    /** Diagnostic name (e.g. `'offline-outbox'`). */
+    readonly name: string;
+    /**
+     * Contribute extra cache-key segments so this capability can partition the
+     * collection's cache (e.g. an outbox variant). Runs ONCE, before construction;
+     * returned segments are appended to the collection's cache key/id. Return
+     * `undefined` (or omit) to contribute nothing.
+     */
+    contributeCacheKey?(ctx: SmrtWebCapabilityContext<TData>): string[] | undefined;
+    /**
+     * Provide rows to seed the cache before the first read — the persistence
+     * slice's rehydrate-from-disk path. Runs ONCE, before construction. NOTE:
+     * caller-supplied `initialData` (fresher same-request SSR truth) WINS over any
+     * capability `warmStart`. Return `undefined` to contribute no seed.
+     */
+    warmStart?(ctx: SmrtWebCapabilityContext<TData>): Promise<SmrtWebRow<TData>[] | undefined> | SmrtWebRow<TData>[] | undefined;
+    /**
+     * Intercept a mutation BEFORE its fetcher runs. Return `{ handled: true,
+     * result }` to take over the write (the fetcher is skipped and `result`
+     * reconciles the optimistic row — the offline path); return `{ handled: false
+     * }` or `undefined` to fall through to the real fetcher. With multiple
+     * capabilities the FIRST `{ handled: true }` wins and later capabilities'
+     * `wrapMutation` are skipped.
+     */
+    wrapMutation?(envelope: SmrtWebMutationEnvelope, ctx: SmrtWebCapabilityContext<TData>): Promise<WrapMutationOutcome> | WrapMutationOutcome;
+    /**
+     * Observe a mutation after it settles — on BOTH a successful persist and a
+     * fetcher throw (before the optimistic rollback propagates). Never swallows
+     * the error: a thrown fetcher error still rolls the transaction back.
+     */
+    onSettled?(envelope: SmrtWebMutationEnvelope, outcome: MutationSettleOutcome, ctx: SmrtWebCapabilityContext<TData>): void;
+    /**
+     * Run ONCE, right after the engine collection is constructed. The ONLY hook
+     * where a capability wires an external trigger (SSE subscription, focus
+     * listener) — `ctx.invalidate()` is callable here.
+     */
+    onAttach?(ctx: SmrtWebCapabilityContext<TData>): void;
+    /** Run inside `cleanup()`, AFTER the engine's own cleanup. Awaited if async. */
+    teardown?(ctx: SmrtWebCapabilityContext<TData>): void | Promise<void>;
+}
+/**
+ * Run the `wrapMutation` hook across `capabilities` in array order for one
+ * mutation, short-circuiting on the FIRST capability that returns `{ handled:
+ * true }` (later capabilities' `wrapMutation` are then skipped). A capability
+ * that returns `{ handled: false }`, `undefined`, or omits the hook declines,
+ * and the next is tried. When every capability declines, resolves `{ handled:
+ * false }` so the factory falls through to the real fetcher.
+ */
+export declare function runWrapMutation<TData extends object>(capabilities: readonly SmrtWebCapability<TData>[], envelope: SmrtWebMutationEnvelope, ctx: SmrtWebCapabilityContext<TData>): Promise<{
+    handled: true;
+    result: unknown;
+} | {
+    handled: false;
+}>;
+//# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

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

package/dist/data-query.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Browser transport for the canonical bounded data-query envelope (#2444).
+ *
+ * This is a textual structural mirror of `@happyvertical/smrt-types` rather
+ * than an import: smrt-web deliberately has no inter-SMRT dependencies. The
+ * authenticated server adapter owns allowlist, authorization, fingerprint,
+ * and byte-limit enforcement. This module gives browser callers a stable
+ * request/result shape and rejects malformed response envelopes before they
+ * reach a mounted surface.
+ */
+export type SmrtWebDataQueryScalar = string | number | boolean | null;
+export type SmrtWebDataQueryFilterOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'like';
+export type SmrtWebDataQueryFilter = {
+    kind: 'condition';
+    field: string;
+    operator: SmrtWebDataQueryFilterOperator;
+    value: SmrtWebDataQueryScalar | SmrtWebDataQueryScalar[];
+} | {
+    kind: 'all' | 'any';
+    filters: SmrtWebDataQueryFilter[];
+} | {
+    kind: 'not';
+    filter: SmrtWebDataQueryFilter;
+};
+export interface SmrtWebDataQueryRequest {
+    version: 1;
+    requestId: string;
+    mode: 'rows' | 'count' | 'facets';
+    projection?: string[];
+    filter?: SmrtWebDataQueryFilter;
+    sort?: Array<{
+        field: string;
+        direction: 'asc' | 'desc';
+    }>;
+    page?: {
+        kind: 'offset';
+        offset: number;
+        limit: number;
+    } | {
+        kind: 'cursor';
+        after?: string;
+        limit: number;
+    };
+    consistency?: {
+        mode: 'eventual' | 'snapshot';
+        asOf?: string;
+    };
+    facets?: Array<{
+        field: string;
+        limit: number;
+    }>;
+}
+export type SmrtWebDataQueryTotal = {
+    kind: 'exact' | 'estimated';
+    value: number;
+    asOf?: string;
+} | {
+    kind: 'unavailable';
+    reason?: string;
+};
+export interface SmrtWebDataQueryFacetResult {
+    field: string;
+    values: Array<{
+        value: SmrtWebDataQueryScalar;
+        count: number;
+    }>;
+    truncated: boolean;
+}
+export interface SmrtWebDataQueryResult {
+    version: 1;
+    requestId: string;
+    queryFingerprint: string;
+    identityField: string;
+    rows: Array<Record<string, unknown>>;
+    page?: {
+        kind: 'offset';
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    } | {
+        kind: 'cursor';
+        limit: number;
+        nextCursor?: string;
+        hasMore: boolean;
+    };
+    total: SmrtWebDataQueryTotal;
+    facets?: SmrtWebDataQueryFacetResult[];
+    freshness: {
+        state: 'fresh' | 'stale' | 'unknown';
+        asOf?: string;
+    };
+    warnings: string[];
+    truncated: boolean;
+}
+/** Browser transport seam; REST, WebMCP, and test transports share it. */
+export interface SmrtWebDataQueryTransport {
+    query(request: SmrtWebDataQueryRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+/** Mirrors core's hard output limits without adding an inter-SMRT dependency. */
+export declare const MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES = 10000000;
+export declare const MAX_SMRT_WEB_DATA_QUERY_ROWS = 1000;
+export declare const MAX_SMRT_WEB_DATA_QUERY_FACETS = 20;
+export declare const MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES = 1000;
+export declare const MAX_SMRT_WEB_DATA_QUERY_WARNINGS = 100;
+export declare const MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT = 1000;
+export declare const MAX_SMRT_WEB_DATA_QUERY_OFFSET = 1000000;
+export declare const MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS = 1000;
+export declare const MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH = 65536;
+/**
+ * Check the server-produced, normalized result envelope before a browser
+ * surface consumes it. This validates portable shape only; the server's core
+ * normalizer remains the authorization, projection, and query-policy boundary.
+ */
+export declare function normalizeSmrtWebDataQueryResult(value: unknown): SmrtWebDataQueryResult;
+/** Run a browser transport and return the defensive normalized envelope. */
+export declare function executeSmrtWebDataQuery(transport: SmrtWebDataQueryTransport, request: SmrtWebDataQueryRequest, options?: {
+    signal?: AbortSignal;
+}): Promise<SmrtWebDataQueryResult>;
+//# sourceMappingURL=data-query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"data-query.d.ts","sourceRoot":"","sources":["../src/data-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AACtE,MAAM,MAAM,8BAA8B,GACtC,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,OAAO,GACP,MAAM,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAC9B;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,8BAA8B,CAAC;IACzC,KAAK,EAAE,sBAAsB,GAAG,sBAAsB,EAAE,CAAC;CAC1D,GACD;IAAE,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;IAAC,OAAO,EAAE,sBAAsB,EAAE,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAA;CAAE,CAAC;AAEpD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D,IAAI,CAAC,EACD;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GACjD;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,OAAO,GAAG,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,sBAAsB,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrC,IAAI,CAAC,EACD;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GACnE;QACE,IAAI,EAAE,QAAQ,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;IACN,KAAK,EAAE,qBAAqB,CAAC;IAC7B,MAAM,CAAC,EAAE,2BAA2B,EAAE,CAAC;IACvC,SAAS,EAAE;QAAE,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,0EAA0E;AAC1E,MAAM,WAAW,yBAAyB;IACxC,KAAK,CACH,OAAO,EAAE,uBAAuB,EAChC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACjC,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAID,iFAAiF;AACjF,eAAO,MAAM,oCAAoC,WAAa,CAAC;AAC/D,eAAO,MAAM,4BAA4B,OAAQ,CAAC;AAClD,eAAO,MAAM,8BAA8B,KAAK,CAAC;AACjD,eAAO,MAAM,oCAAoC,OAAQ,CAAC;AAC1D,eAAO,MAAM,gCAAgC,MAAM,CAAC;AACpD,eAAO,MAAM,kCAAkC,OAAQ,CAAC;AACxD,eAAO,MAAM,8BAA8B,UAAY,CAAC;AACxD,eAAO,MAAM,uCAAuC,OAAQ,CAAC;AAC7D,eAAO,MAAM,qCAAqC,QAAS,CAAC;AAiN5D;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,OAAO,GACb,sBAAsB,CA2JxB;AAED,4EAA4E;AAC5E,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,yBAAyB,EACpC,OAAO,EAAE,uBAAuB,EAChC,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GACjC,OAAO,CAAC,sBAAsB,CAAC,CAUjC"}

package/dist/data-surface-actions.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Browser transport for bounded data-surface action envelopes.
+ *
+ * This structurally mirrors smrt-types without importing another SMRT package.
+ * The server remains responsible for authority, descriptor allowlists, and
+ * confirmation-token validation; this boundary only rejects malformed replies.
+ */
+import type { OutboxCommand, OutboxCommandResult, OutboxCommandTransport } from './offline/types.js';
+export type SmrtWebDataSurfaceJsonPrimitive = string | number | boolean | null;
+export type SmrtWebDataSurfaceJsonValue = SmrtWebDataSurfaceJsonPrimitive | SmrtWebDataSurfaceJsonValue[] | {
+    [key: string]: SmrtWebDataSurfaceJsonValue;
+};
+export interface SmrtWebDataSurfaceIdentity {
+    surfaceId: string;
+    kind: 'table' | 'list' | 'report' | 'custom';
+    subject?: {
+        type: string;
+        id: string;
+        label?: string;
+    };
+}
+export type SmrtWebDataSurfaceSelection = {
+    scope: 'current-page';
+} | {
+    scope: 'explicit-ids';
+    rowIds: Array<string | number>;
+} | {
+    scope: 'all-matching';
+    queryFingerprint: string;
+};
+export interface SmrtWebDataSurfaceActionRequest {
+    version: 1;
+    requestId: string;
+    identity: SmrtWebDataSurfaceIdentity;
+    actionId: string;
+    phase: 'preview' | 'apply';
+    expectedRevision: number;
+    /** Required by the server for apply; retries with the same key replay safely. */
+    idempotencyKey?: string;
+    selection: SmrtWebDataSurfaceSelection;
+    payload?: SmrtWebDataSurfaceJsonValue;
+    confirmationToken?: string;
+}
+export interface SmrtWebDataSurfaceActionResult {
+    version: 1;
+    requestId: string;
+    identity: SmrtWebDataSurfaceIdentity;
+    actionId: string;
+    phase: 'preview' | 'apply';
+    ok: boolean;
+    reason?: string;
+    confirmationToken?: string;
+    details?: {
+        [key: string]: SmrtWebDataSurfaceJsonValue;
+    };
+}
+export interface SmrtWebDataSurfaceActionTransport {
+    action(request: SmrtWebDataSurfaceActionRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+export declare const MAX_SMRT_WEB_DATA_SURFACE_ACTION_RESULT_BYTES = 1000000;
+export declare const MAX_SMRT_WEB_DATA_SURFACE_ACTION_IDENTIFIER_LENGTH = 256;
+export declare const MAX_SMRT_WEB_DATA_SURFACE_ACTION_JSON_DEPTH = 16;
+export declare const MAX_SMRT_WEB_DATA_SURFACE_ACTION_CONTAINER_ITEMS = 1000;
+/** Fail closed before an action result reaches browser state. */
+export declare function normalizeSmrtWebDataSurfaceActionResult(value: unknown): SmrtWebDataSurfaceActionResult;
+export declare function executeSmrtWebDataSurfaceAction(transport: SmrtWebDataSurfaceActionTransport, request: SmrtWebDataSurfaceActionRequest, options?: {
+    signal?: AbortSignal;
+}): Promise<SmrtWebDataSurfaceActionResult>;
+/**
+ * The replay-time request for {@link dataSurfaceActionCommandTransport}: every
+ * action-request field except those the adapter owns — `version`, `phase`,
+ * `requestId`, `idempotencyKey`, and `confirmationToken`.
+ */
+export type SmrtWebDataSurfaceActionCommandRequest = Omit<SmrtWebDataSurfaceActionRequest, 'version' | 'phase' | 'requestId' | 'idempotencyKey' | 'confirmationToken'>;
+export interface SmrtWebDataSurfaceActionCommandTransportOptions {
+    /** The same action transport the mounted surface uses online. */
+    transport: SmrtWebDataSurfaceActionTransport;
+    /**
+     * Build the action request for a queued write at its FIRST replay attempt,
+     * so it carries the surface's `expectedRevision` as of replay rather than
+     * capture. The built request is pinned durably to the write and reused on
+     * every later attempt (including after a reload): the server fingerprints
+     * the request per idempotency key, so a resend after a lost response must be
+     * identical to replay the recorded result instead of `idempotency_conflict`.
+     */
+    request: (command: OutboxCommand) => SmrtWebDataSurfaceActionCommandRequest | Promise<SmrtWebDataSurfaceActionCommandRequest>;
+    /**
+     * Run `preview` first and apply with its `confirmationToken` — for actions
+     * whose server adapter requires confirmation. Default false (apply only).
+     * The token is pinned before apply; a retry applies with it directly (the
+     * server replays a completed result) and previews again only when the token
+     * turns out unusable.
+     */
+    preview?: boolean;
+    /** Map a non-throwing result onto an outbox outcome. Default below. */
+    classify?: (result: SmrtWebDataSurfaceActionResult) => OutboxCommandResult;
+}
+/**
+ * Default outcome mapping for a data-surface action result. `ok` → applied; a
+ * transient server reason → retryable `write_failed`; an authentication reason
+ * → pause for re-auth; a stale revision/preview → `conflict` (a RESOLVED
+ * outcome the app rebases from); anything else — including `denied` — is a
+ * terminal rejection surfaced as `failed`.
+ */
+export declare function classifySmrtWebDataSurfaceActionResult(result: SmrtWebDataSurfaceActionResult): OutboxCommandResult;
+/**
+ * An {@link OutboxCommandTransport} that replays a queued write as a
+ * data-surface action `apply` (optionally preceded by `preview`) through the
+ * surface's own server adapter — its authority, allowlist, and principal
+ * scoping stay on the server path (#3021). The outbox's durable idempotency
+ * key becomes the action's `idempotencyKey`, so a resend after a lost response
+ * replays the server's recorded result instead of applying twice. Malformed or
+ * mismatched replies throw, which the outbox treats as retryable.
+ */
+export declare function dataSurfaceActionCommandTransport(options: SmrtWebDataSurfaceActionCommandTransportOptions): OutboxCommandTransport;
+//# sourceMappingURL=data-surface-actions.d.ts.map

package/dist/data-surface-actions.d.ts.map

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

package/dist/durable-store.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @happyvertical/smrt-web — shared durable-store foundation (#1755).
+ *
+ * The ONE SMRT-layer namespacing + wipe registry that the future offline
+ * outbox (#1762) and persistence (#1764) slices both build on. Pure bookkeeping
+ * — ZERO client-data-engine (`@tanstack/*`) imports — so it stays inside the
+ * engine-absorption boundary and ships now, before either consumer exists, so
+ * the two slices agree on it from day one.
+ *
+ * Why a SMRT-layer registry rather than one storage engine: TanStack DB
+ * persistence (SQLite-WASM / OPFS) and `@tanstack/offline-transactions`
+ * (IndexedDB) are SEPARATE storage engines. There is no single primitive that
+ * spans both, so the shared foundation lives one level up — a deterministic
+ * namespace both slices key their own storage under, plus a registry so
+ * {@link wipeDurableStore} can clear BOTH through one call without the outbox
+ * and persistence modules importing each other. A logout / tenant-switch wipes
+ * every durable artifact for a namespace in one place.
+ *
+ * Nothing in this package calls these yet — the seam ships ahead of its
+ * consumers by design (see PRD #1755).
+ */
+/**
+ * The identity a durable namespace is derived from. Combining the API base with
+ * the tenant + identity + manifest hash means a logout, a tenant switch, or a
+ * schema change each land on a DIFFERENT namespace, so durable artifacts are
+ * never reused across those boundaries.
+ *
+ * `manifestHash` is supplied by the caller (its source is #1764's call — a
+ * schema-shape digest); this module is source-agnostic and treats it as an
+ * opaque discriminator.
+ */
+export interface DurableStoreKey {
+    /** API base path the durable data was fetched against (e.g. `/api/v1`). */
+    apiBase: string;
+    /** Active tenant id, if any — absent means the single-tenant / global scope. */
+    tenantId?: string;
+    /** Authenticated identity id, if any — absent means anonymous. */
+    identityId?: string;
+    /** Opaque schema-shape digest; a change forces a fresh namespace. */
+    manifestHash: string;
+}
+/**
+ * Compute the deterministic storage namespace for a {@link DurableStoreKey}.
+ * The same key always yields the same string; **any differing segment yields a
+ * different one** (injective) — this is critical because the namespace IS the
+ * tenant/identity/api isolation + wipe boundary, so a collision would reuse or
+ * wipe durable data ACROSS those boundaries.
+ *
+ * Injectivity is guaranteed three ways: every segment is `encodeURIComponent`-
+ * encoded, so a raw `:` in a value becomes `%3A` and can never be mistaken for a
+ * separator; an ABSENT `tenantId` / `identityId` maps to the empty string while
+ * a PRESENT value is prefixed with `_` (so undefined→``, ``→`_`, `x`→`_x`) — so
+ * an explicitly-EMPTY id no longer collides with "no id", nor does a real id of
+ * `-`. Both future slices key their own storage primitive (IndexedDB store name,
+ * OPFS path, …) under this string.
+ */
+export declare function durableStoreNamespace(key: DurableStoreKey): string;
+/**
+ * A durable artifact registered under a namespace — the outbox queue (#1762) or
+ * a persisted collection store (#1764). Each owns its storage engine and
+ * exposes only a `clear()` so {@link wipeDurableStore} can tear it down without
+ * knowing which engine backs it.
+ */
+export interface DurableResource {
+    /** Which slice owns this artifact — for diagnostics and selective sweeps. */
+    readonly kind: 'outbox' | 'persisted-collection';
+    /** Drop this artifact's durable storage. Best-effort; may reject. */
+    clear(): Promise<void>;
+}
+/**
+ * Register a durable artifact under a namespace so {@link wipeDurableStore} can
+ * later clear it. Returns an unregister function that removes just this
+ * resource — call it when the artifact is disposed on its own (before any
+ * namespace-wide wipe) so it is not cleared twice.
+ */
+export declare function registerDurableResource(namespace: string, resource: DurableResource): () => void;
+/**
+ * Clear every durable artifact registered under `namespace`, then drop the
+ * namespace. This is the single teardown point a logout / tenant-switch calls:
+ * it fans out across BOTH the outbox and persistence slices via the registry,
+ * so neither module needs to import the other.
+ *
+ * Best-effort: a resource whose `clear()` rejects does not abort the sweep —
+ * every registered resource is still cleared (a wipe is a teardown, not a
+ * transaction). A safe no-op on an unknown or empty namespace.
+ */
+export declare function wipeDurableStore(namespace: string): Promise<void>;
+//# sourceMappingURL=durable-store.d.ts.map

package/dist/durable-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-store.d.ts","sourceRoot":"","sources":["../src/durable-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAOlE;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,sBAAsB,CAAC;IACjD,qEAAqE;IACrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AASD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,eAAe,GACxB,MAAM,IAAI,CAcZ;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYvE"}