@storystick/client 0.0.0-stage → 0.2.0-rc.1

package/dist/infra-resolver.js

@@ -0,0 +1,130 @@
+/**
+ * Infrastructure URL resolution — ADR-131 C9.
+ *
+ * Centralizes derivation of the three Convex-flavoured URLs the customer-
+ * bundled SDK packages need at runtime :
+ *
+ *   - `endpoint`   — gateway HTTP root, `.convex.site` form. Hosts the
+ *                    custom HTTP routes (JWKS, Pattern-D queries).
+ *   - `convexUrl`  — standard Convex RPC + WebSocket sync URL, `.convex.cloud`
+ *                    form. Used by `ConvexReactClient` (WS) and the server-
+ *                    side `ConvexHttpClient` (preview session lookup,
+ *                    observation tap mutation).
+ *   - `jwksUrl`    — `${endpoint}/api/jwks.json` by default.
+ *
+ * Cascade (per URL, independent) :
+ *
+ *   1. Explicit `options.*Url` — call-site override (props, env vars read
+ *      by the adapter and forwarded as options, factory args).
+ *   2. Auto-derive from `resolveProject(projectId).endpoint`.
+ *   3. Fail-loud — `resolveProject` throws a typed `StorystickError` if
+ *      the gateway returns 404/503/network error.
+ *
+ * The single `resolveProject` round-trip is shared across the three URLs ;
+ * subsequent calls hit the per-process cache (server) or sessionStorage
+ * cache (browser).
+ *
+ * **Env vars are NOT read here.** The bundler-replace behaviour of
+ * `process.env.NEXT_PUBLIC_*` requires literal property access in the
+ * adapter package (Next/React) so the static replacement at build time
+ * resolves the value into the browser bundle. Adapters call this helper
+ * after reading their respective env vars and forwarding them as options.
+ *
+ * Direction produit (owner 2026-05-26 PM) :
+ *
+ *   > "Convex doit rester transparent au dev. Hors de question qu'une env
+ *   > var mentionnant convex.cloud / .site / etc apparaisse côté customer."
+ *
+ * The 5-var customer allowlist is `STORYSTICK_PROJECT_ID`, `STORYSTICK_API_KEY`,
+ * `NEXT_PUBLIC_STORYSTICK_PROJECT_ID`, `NEXT_PUBLIC_STORYSTICK_PUBLISHABLE_KEY`,
+ * `NEXT_PUBLIC_STORYSTICK_STUDIO_ORIGIN`. All Convex-flavoured URLs are
+ * derived from `projectId` via this module.
+ * Resource-storage bucket credentials belong exclusively to the server-side
+ * storage resolver; they are never customer env vars or resolver options.
+ */
+import { resolveProject } from './resolve.js';
+const JWKS_PATH = '/api/jwks.json';
+/**
+ * Swap `.convex.site` → `.convex.cloud` on a Convex deployment URL. Returns
+ * the input unchanged for non-Convex-Cloud deployments (self-host) — the
+ * customer sets `convexUrl` explicitly in that case.
+ *
+ * **CSO trade-off (codex R2 P1, accepted per ADR-131 C9 brief direction
+ * produit) :** the default `convexUrl` resolves to a raw `.convex.cloud`
+ * deployment URL, bypassing the sub-gateway Worker (`services/sub-gateway/`).
+ * Pre-C9, the default was `http://localhost:8787` (dev Worker URL) and
+ * customers in prod were expected to set
+ * `NEXT_PUBLIC_STORYSTICK_GATEWAY_SYNC_URL` explicitly — usually to the
+ * Worker public URL (e.g. `https://gateway.storystick.app`). The Worker
+ * is not deployed yet (5 Path B manual steps in
+ * `services/sub-gateway/wrangler.toml`), so the spike-Vercel Fix 2 already
+ * documents `.convex.cloud` direct as the only working posture today.
+ *
+ * Once the Worker is deployed, replace this default with the Worker
+ * public URL constant ; the rest of the cascade is unchanged. The
+ * explicit `options.convexUrl` override remains the escape hatch for
+ * customers needing to bypass the constant (self-host, internal Vercel
+ * deploys, etc.).
+ *
+ * See `storystick-hq/notes/adr-131-chantier/c9-hidden-vars-audit.md` §9
+ * for the deferred-follow-up list.
+ */
+function gatewayToConvex(endpoint) {
+    if (endpoint.includes('.convex.site')) {
+        return endpoint.replace('.convex.site', '.convex.cloud');
+    }
+    return endpoint;
+}
+function stripTrailingSlash(url) {
+    return url.replace(/\/$/, '');
+}
+/**
+ * Synchronously derive `ResolvedInfra` when `endpoint` is already known
+ * (explicit prop or env override). Used by adapters that need an
+ * initial value during render — e.g. `<StorystickQueryProvider>`
+ * synchronously seeds its `infra` state when all required values are
+ * explicit, so generated clients can execute on the first render
+ * inside an immediately-available `ConvexProvider` (codex R2 P2 fix).
+ *
+ * Returns `null` when `endpoint` is missing (gateway round-trip needed).
+ */
+export function resolveInfraSync(options = {}) {
+    if (options.endpoint === undefined)
+        return null;
+    const endpoint = stripTrailingSlash(options.endpoint);
+    const convexUrl = stripTrailingSlash(options.convexUrl ?? gatewayToConvex(endpoint));
+    const jwksUrl = options.jwksUrl !== undefined ? options.jwksUrl : `${endpoint}${JWKS_PATH}`;
+    return { endpoint, convexUrl, jwksUrl };
+}
+/**
+ * Resolve the three infrastructure URLs for `projectId`.
+ *
+ * Idempotent + cache-aware — repeated calls with the same `projectId` reuse
+ * the `resolveProject` cache (per-process Map server-side, sessionStorage
+ * browser-side). Safe to call eagerly at module init.
+ *
+ * The `resolveProject` round-trip happens only when no explicit endpoint
+ * override is supplied — `convexUrl` + `jwksUrl` are pure transforms on
+ * `endpoint`. If `endpoint` is provided (prop or env escape hatch), the
+ * helper completes without any network call ; gateway failures cannot
+ * stall the boot path in that case.
+ *
+ * Throws (propagates) the `StorystickError` from `resolveProject` when the
+ * gateway returns 404/503/network error AND no explicit `endpoint` is set.
+ */
+export async function resolveInfra(projectId, options = {}) {
+    // The gateway round-trip is needed only when we don't already know the
+    // endpoint — convexUrl + jwksUrl are pure transforms on it. Explicit
+    // endpoint prop alone is enough to skip the round-trip.
+    let endpointSource = options.endpoint;
+    if (endpointSource === undefined) {
+        const config = await resolveProject(projectId, options.gatewayUrl);
+        endpointSource = config.endpoint;
+    }
+    const endpoint = stripTrailingSlash(endpointSource);
+    const convexUrl = stripTrailingSlash(options.convexUrl ?? gatewayToConvex(endpoint));
+    const jwksUrl = options.jwksUrl !== undefined
+        ? options.jwksUrl
+        : `${endpoint}${JWKS_PATH}`;
+    return { endpoint, convexUrl, jwksUrl };
+}

package/dist/internal.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Internal entry point — Storystick surfaces only (ADR-045 §11.2).
+ *
+ * Consumers outside `apps/studio`, `apps/ops`, `apps/hub` should NOT
+ * import from here. This file exposes the user-session fetcher (which
+ * the public SDK doesn't need) and direct access to the state machine.
+ */
+export { wireConvexAuth } from './_wireAuth.js';
+export { assertExactQueryResult } from './errors.js';
+export type { ConvexClientWithSetAuth, WireAuthOptions, WireAuthResult, } from './_wireAuth.js';
+export { userSessionFetcher, apiKeyFetcher } from './_fetchers.js';
+export type { UserSessionFetcherOptions, ApiKeyFetcherOptions, } from './_fetchers.js';
+export { createTokenStateMachine, isHardAuthError, isRefreshableError, } from './_stateMachine.js';
+export type { SdkError, StateMachineErrorCode, TokenFetcher, TokenFetchResult, TokenStateMachine, } from './_stateMachine.js';
+export { getExecutableQueryDescriptor } from './query-builder.js';
+export type { InternalExecutableQueryDescriptor } from './query-builder.js';
+export { createInternalClient, bindClientSchemaToAuthority, clientMatchesPreviewAuthority, getInternalClientRuntime, } from './query-client.js';
+export type { InternalClientOptions, InternalClientRuntime, InternalPreviewAuthorityScope, } from './query-client.js';
+/** Internal Studio wire knob. Public SDK reads always use backend `explicit`. */
+export interface InternalLocaleWireOptions {
+    locale?: string;
+    fallbackPolicy?: 'none' | 'explicit';
+}
+export { attachPreviewReadObservation, collectPreviewReadObservations, conservativePreviewRenderWatermark, getPreviewReadObservation, } from './preview-read-observation.js';
+export type { PreviewReadObservation } from './preview-read-observation.js';
+export { getPreviewQueryReceiptId } from './preview-query-receipt.js';
+export { resolvePreviewTarget } from './preview-target.js';
+export type { PreviewTarget } from './preview-target.js';
+export { previewAssetDependenciesFromValue } from './preview-frame-dependencies.js';
+export * from './hydrate-slice.js';
+export * from './content-values.js';
+export { attachPreviewQueryReceipt } from './preview-query-receipt.js';
+export type { RequestContext, PreviewReadScopeEcho, PreviewProvenanceReadLifecycle, PreviewProvenanceReadLifecycleInput, Transport, TransportRequest, } from './types.js';

package/dist/internal.js

@@ -0,0 +1,20 @@
+/**
+ * Internal entry point — Storystick surfaces only (ADR-045 §11.2).
+ *
+ * Consumers outside `apps/studio`, `apps/ops`, `apps/hub` should NOT
+ * import from here. This file exposes the user-session fetcher (which
+ * the public SDK doesn't need) and direct access to the state machine.
+ */
+export { wireConvexAuth } from './_wireAuth.js';
+export { assertExactQueryResult } from './errors.js';
+export { userSessionFetcher, apiKeyFetcher } from './_fetchers.js';
+export { createTokenStateMachine, isHardAuthError, isRefreshableError, } from './_stateMachine.js';
+export { getExecutableQueryDescriptor } from './query-builder.js';
+export { createInternalClient, bindClientSchemaToAuthority, clientMatchesPreviewAuthority, getInternalClientRuntime, } from './query-client.js';
+export { attachPreviewReadObservation, collectPreviewReadObservations, conservativePreviewRenderWatermark, getPreviewReadObservation, } from './preview-read-observation.js';
+export { getPreviewQueryReceiptId } from './preview-query-receipt.js';
+export { resolvePreviewTarget } from './preview-target.js';
+export { previewAssetDependenciesFromValue } from './preview-frame-dependencies.js';
+export * from './hydrate-slice.js';
+export * from './content-values.js';
+export { attachPreviewQueryReceipt } from './preview-query-receipt.js';

package/dist/locale-routing.d.ts

@@ -0,0 +1,5 @@
+export { publicHrefForPublication, publicHrefForLocale, publishedLocaleHrefs, normalizePublicLocaleOrigins, prefixHref, publicPathnameForLocale, resolveLocalePathname, readDocumentLocaleRouting } from '@storystick/types/internal/locale-routing';
+export type { PublicLocaleOrigins, LocalePathnameResolution, LocaleRouting, LocaleRoutingSettings, RoutingLocale, DocumentLocaleRouting } from '@storystick/types/internal/locale-routing';
+import type { LocaleRoutingSettings } from '@storystick/types/internal/locale-routing';
+/** @internal Attach only after validating the wire response. No credentials or view identity. */
+export declare function attachDocumentLocaleRouting<T>(value: T, settings: LocaleRoutingSettings): T;

package/dist/locale-routing.js

@@ -0,0 +1,33 @@
+export { publicHrefForPublication, publicHrefForLocale, publishedLocaleHrefs, normalizePublicLocaleOrigins, prefixHref, publicPathnameForLocale, resolveLocalePathname, readDocumentLocaleRouting } from '@storystick/types/internal/locale-routing';
+/** @internal Attach only after validating the wire response. No credentials or view identity. */
+export function attachDocumentLocaleRouting(value, settings) {
+    const seen = new WeakSet();
+    const visit = (item) => {
+        if (typeof item !== 'object' || item === null || seen.has(item))
+            return;
+        seen.add(item);
+        if (Array.isArray(item)) {
+            item.forEach(visit);
+            return;
+        }
+        const record = item;
+        if (typeof record.documentId === 'string' && typeof record.storyType === 'string' &&
+            isRecord(record.fields) && isRecord(record._locale) && typeof record._locale.code === 'string') {
+            record._localeRouting = {
+                locale: record._locale.code,
+                defaultLocale: settings.defaultLocale,
+                locales: settings.locales.map(({ code, enabled }) => ({ code, enabled })),
+                localeRouting: { ...settings.localeRouting },
+                ...(settings.publicOrigins ? { publicOrigins: { ...settings.publicOrigins } } : {}),
+                ...(settings.synthetic === undefined ? {} : { synthetic: settings.synthetic }),
+            };
+        }
+        for (const [key, child] of Object.entries(record)) {
+            if (key !== '_localeRouting')
+                visit(child);
+        }
+    };
+    visit(value);
+    return value;
+}
+function isRecord(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }

package/dist/normalize-pathname.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Pathname normalization helpers (ADR-090 §3).
+ *
+ * The public SDK accepts all developer-natural forms for a pathname:
+ *
+ *   - `undefined` (catch-all root in Next.js: `params.segments` for `/`)
+ *   - `""`, `"/"` (empty / root)
+ *   - `"accueil"`, `"/accueil"` (single segment, optional leading slash)
+ *   - `["blog", "post"]` (array of segments, e.g. Next.js `params.segments`)
+ *   - `[]` (empty array — homepage)
+ *
+ * All forms normalize to a canonical internal form: a single string of
+ * slug-like segments joined by `"/"`, with no leading or trailing slash.
+ * The empty string `""` represents the homepage.
+ *
+ * | Input              | Canonical form |
+ * |--------------------|----------------|
+ * | `undefined`        | `""`           |
+ * | `""` / `"/"`       | `""`           |
+ * | `"accueil"`        | `"accueil"`    |
+ * | `"/accueil"`       | `"accueil"`    |
+ * | `"/blog/post"`     | `"blog/post"`  |
+ * | `["blog", "post"]` | `"blog/post"`  |
+ * | `[]`               | `""`           |
+ *
+ * The canonical form is what a compiled Query V2 pathname address stores when
+ * `.by({ pathname })` is called, and what backend `getByPathname` will
+ * eventually accept on the wire (currently routed via list + filter
+ * fallback on the `resolvedPathname` allowlist column from ADR-088).
+ *
+ * These helpers are framework-agnostic and shared by all framework
+ * adapters so that normalization behavior is identical across Next.js,
+ * Astro, SvelteKit, and any future SDK.
+ */
+/**
+ * Normalize a developer-supplied pathname input to its canonical form.
+ *
+ *   normalizePathname(undefined)          // ""
+ *   normalizePathname("/")                // ""
+ *   normalizePathname("/accueil")         // "accueil"
+ *   normalizePathname(["blog", "post"])   // "blog/post"
+ *   normalizePathname([])                 // ""
+ */
+export declare function normalizePathname(input: string | string[] | undefined): string;
+/**
+ * Convert a canonical pathname into segment array form.
+ * Inverse of {@link segmentsToPathname}.
+ *
+ *   pathnameToSegments("")             // []
+ *   pathnameToSegments("accueil")      // ["accueil"]
+ *   pathnameToSegments("blog/post")    // ["blog", "post"]
+ */
+export declare function pathnameToSegments(pathname: string): string[];
+/**
+ * Convert a segment array into canonical pathname string form.
+ * Inverse of {@link pathnameToSegments}.
+ *
+ *   segmentsToPathname([])                  // ""
+ *   segmentsToPathname(["accueil"])         // "accueil"
+ *   segmentsToPathname(["blog", "post"])    // "blog/post"
+ */
+export declare function segmentsToPathname(segments: string[]): string;
+/**
+ * Convert a canonical pathname (`'blog/post-1'` or `''` for homepage) to a
+ * browser-displayable path with leading slash. Inverse of {@link normalizePathname}.
+ *
+ *   pathnameToHref('')              → '/'
+ *   pathnameToHref('accueil')       → '/accueil'
+ *   pathnameToHref('blog/post-1')   → '/blog/post-1'
+ *
+ * Trusts canonical-form input (no leading slash, `''` for homepage). Producers
+ * are expected to call `normalizePathname` first if they hold non-canonical
+ * input. This keeps the helper minimal and the canonicalization rule single-sourced.
+ *
+ * Use cases: ADR-094 catch-all routing (companion utility consumed by customer
+ * renderers + the Studio iframe routing in ADR-095), future sitemap generation,
+ * AI Builder doc→URL pass, "share my draft" link generators.
+ */
+export declare function pathnameToHref(canonical: string): string;

package/dist/normalize-pathname.js

@@ -0,0 +1,103 @@
+import { normalizeQueryPathname } from '@storystick/types/pathname-query';
+/**
+ * Pathname normalization helpers (ADR-090 §3).
+ *
+ * The public SDK accepts all developer-natural forms for a pathname:
+ *
+ *   - `undefined` (catch-all root in Next.js: `params.segments` for `/`)
+ *   - `""`, `"/"` (empty / root)
+ *   - `"accueil"`, `"/accueil"` (single segment, optional leading slash)
+ *   - `["blog", "post"]` (array of segments, e.g. Next.js `params.segments`)
+ *   - `[]` (empty array — homepage)
+ *
+ * All forms normalize to a canonical internal form: a single string of
+ * slug-like segments joined by `"/"`, with no leading or trailing slash.
+ * The empty string `""` represents the homepage.
+ *
+ * | Input              | Canonical form |
+ * |--------------------|----------------|
+ * | `undefined`        | `""`           |
+ * | `""` / `"/"`       | `""`           |
+ * | `"accueil"`        | `"accueil"`    |
+ * | `"/accueil"`       | `"accueil"`    |
+ * | `"/blog/post"`     | `"blog/post"`  |
+ * | `["blog", "post"]` | `"blog/post"`  |
+ * | `[]`               | `""`           |
+ *
+ * The canonical form is what a compiled Query V2 pathname address stores when
+ * `.by({ pathname })` is called, and what backend `getByPathname` will
+ * eventually accept on the wire (currently routed via list + filter
+ * fallback on the `resolvedPathname` allowlist column from ADR-088).
+ *
+ * These helpers are framework-agnostic and shared by all framework
+ * adapters so that normalization behavior is identical across Next.js,
+ * Astro, SvelteKit, and any future SDK.
+ */
+/**
+ * Normalize a developer-supplied pathname input to its canonical form.
+ *
+ *   normalizePathname(undefined)          // ""
+ *   normalizePathname("/")                // ""
+ *   normalizePathname("/accueil")         // "accueil"
+ *   normalizePathname(["blog", "post"])   // "blog/post"
+ *   normalizePathname([])                 // ""
+ */
+export function normalizePathname(input) {
+    if (input === undefined)
+        return '';
+    if (Array.isArray(input)) {
+        // Filter out empty / falsy segments so `["", "blog"]` doesn't produce
+        // a leading-slash canonical form. This also makes `normalizePathname([""])`
+        // correctly produce `""` (homepage).
+        const filtered = input.filter((s) => typeof s === 'string' && s.length > 0);
+        return filtered.join('/');
+    }
+    // String input: strip leading and trailing slashes.
+    // "/" → "" (after strip), "/accueil" → "accueil", "/blog/post/" → "blog/post"
+    return normalizeQueryPathname(input);
+}
+/**
+ * Convert a canonical pathname into segment array form.
+ * Inverse of {@link segmentsToPathname}.
+ *
+ *   pathnameToSegments("")             // []
+ *   pathnameToSegments("accueil")      // ["accueil"]
+ *   pathnameToSegments("blog/post")    // ["blog", "post"]
+ */
+export function pathnameToSegments(pathname) {
+    if (pathname === '')
+        return [];
+    return pathname.split('/');
+}
+/**
+ * Convert a segment array into canonical pathname string form.
+ * Inverse of {@link pathnameToSegments}.
+ *
+ *   segmentsToPathname([])                  // ""
+ *   segmentsToPathname(["accueil"])         // "accueil"
+ *   segmentsToPathname(["blog", "post"])    // "blog/post"
+ */
+export function segmentsToPathname(segments) {
+    return segments.join('/');
+}
+/**
+ * Convert a canonical pathname (`'blog/post-1'` or `''` for homepage) to a
+ * browser-displayable path with leading slash. Inverse of {@link normalizePathname}.
+ *
+ *   pathnameToHref('')              → '/'
+ *   pathnameToHref('accueil')       → '/accueil'
+ *   pathnameToHref('blog/post-1')   → '/blog/post-1'
+ *
+ * Trusts canonical-form input (no leading slash, `''` for homepage). Producers
+ * are expected to call `normalizePathname` first if they hold non-canonical
+ * input. This keeps the helper minimal and the canonicalization rule single-sourced.
+ *
+ * Use cases: ADR-094 catch-all routing (companion utility consumed by customer
+ * renderers + the Studio iframe routing in ADR-095), future sitemap generation,
+ * AI Builder doc→URL pass, "share my draft" link generators.
+ */
+export function pathnameToHref(canonical) {
+    if (canonical === '')
+        return '/';
+    return `/${canonical}`;
+}

package/dist/preview-frame-dependencies.d.ts

@@ -0,0 +1,39 @@
+export type PreviewFrameDependencyLike = {
+    readonly kind: 'document';
+    readonly documentId: string;
+    readonly storyType?: string;
+    readonly reason?: string;
+} | {
+    readonly kind: 'asset';
+    readonly assetId: string;
+} | {
+    readonly kind: 'list';
+    readonly storyType: string;
+    readonly where?: unknown;
+    readonly orderBy?: {
+        readonly field: string;
+        readonly direction: 'asc' | 'desc';
+    };
+    readonly limit?: number;
+} | {
+    readonly kind: 'route-lookup';
+    readonly pathname: string;
+    readonly storyTypes?: readonly string[];
+} | {
+    readonly kind: 'get-by-slug';
+    readonly storyType: string;
+    readonly slug: string;
+} | {
+    readonly kind: 'get-by-pathname';
+    readonly storyType: string;
+    readonly pathname: string;
+} | {
+    readonly kind: 'batch-get';
+    readonly documentIds: readonly string[];
+};
+export declare function attachPreviewFrameDependencies<T>(target: T, dependencies: readonly PreviewFrameDependencyLike[]): T;
+export declare function getAttachedPreviewFrameDependencies(value: unknown): readonly PreviewFrameDependencyLike[];
+/** Build precise Preview dependencies from public `_assets` sidecars. */
+export declare function previewAssetDependenciesFromValue(value: unknown): readonly Extract<PreviewFrameDependencyLike, {
+    readonly kind: 'asset';
+}>[];

package/dist/preview-frame-dependencies.js

@@ -0,0 +1,84 @@
+import { getPreviewReadDependencies, setPreviewReadDependencies } from '@storystick/types';
+export function attachPreviewFrameDependencies(target, dependencies) {
+    if (!isObjectLike(target) || dependencies.length === 0)
+        return target;
+    const next = dedupePreviewFrameDependencies([
+        ...getAttachedPreviewFrameDependencies(target),
+        ...dependencies,
+    ]);
+    setPreviewReadDependencies(target, next);
+    return target;
+}
+export function getAttachedPreviewFrameDependencies(value) {
+    if (!isObjectLike(value))
+        return [];
+    return getPreviewReadDependencies(value).filter(isPreviewDependencyLike);
+}
+/** Build precise Preview dependencies from public `_assets` sidecars. */
+export function previewAssetDependenciesFromValue(value) {
+    const assetIds = new Set();
+    const seen = new WeakSet();
+    const visit = (current) => {
+        if (!isObjectLike(current) || seen.has(current))
+            return;
+        seen.add(current);
+        if (Array.isArray(current)) {
+            for (const item of current)
+                visit(item);
+            return;
+        }
+        const record = current;
+        const sidecar = isPlainRecord(record._assets) ? record._assets : undefined;
+        for (const key of ['byId', 'unresolved']) {
+            const entries = sidecar && isPlainRecord(sidecar[key])
+                ? sidecar[key]
+                : undefined;
+            if (entries) {
+                for (const assetId of Object.keys(entries)) {
+                    if (assetId.length > 0)
+                        assetIds.add(assetId);
+                }
+            }
+        }
+        for (const child of Object.values(record))
+            visit(child);
+    };
+    visit(value);
+    return [...assetIds]
+        .sort()
+        .map((assetId) => ({ kind: 'asset', assetId }));
+}
+function dedupePreviewFrameDependencies(dependencies) {
+    const seen = new Set();
+    const out = [];
+    for (const dependency of dependencies) {
+        const key = stableStringify(dependency);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(dependency);
+    }
+    return out;
+}
+function isPreviewDependencyLike(value) {
+    return isPlainRecord(value) && typeof value.kind === 'string';
+}
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+    }
+    if (isPlainRecord(value)) {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function isObjectLike(value) {
+    return (typeof value === 'object' || typeof value === 'function') &&
+        value !== null;
+}
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/preview-query-receipt.d.ts

@@ -0,0 +1,3 @@
+import type { PreviewQueryReceiptId } from '@storystick/types/preview-query-targeting';
+export declare function attachPreviewQueryReceipt<T>(result: T, receiptId: string | undefined): T;
+export declare function getPreviewQueryReceiptId(result: unknown): PreviewQueryReceiptId | null;

package/dist/preview-query-receipt.js

@@ -0,0 +1,16 @@
+const receiptByResult = new WeakMap();
+export function attachPreviewQueryReceipt(result, receiptId) {
+    if (result !== null &&
+        (typeof result === 'object' || typeof result === 'function') &&
+        typeof receiptId === 'string' &&
+        /^pqr_[a-f0-9]{64}$/.test(receiptId)) {
+        receiptByResult.set(result, receiptId);
+    }
+    return result;
+}
+export function getPreviewQueryReceiptId(result) {
+    if (result === null ||
+        (typeof result !== 'object' && typeof result !== 'function'))
+        return null;
+    return receiptByResult.get(result) ?? null;
+}

package/dist/preview-read-lifecycle.d.ts

@@ -0,0 +1,10 @@
+import type { PreviewProvenanceReadLifecycleInput, RequestContext } from './types.js';
+/** @internal */
+export declare function runPreviewProvenanceReadLifecycle<T>(requestContext: RequestContext | undefined, input: PreviewProvenanceReadLifecycleInput<T>): Promise<T>;
+/**
+ * Stable, non-secret JSON key used only by request-local adapter caches.
+ * Functions, undefined values, and AbortSignals are intentionally omitted.
+ *
+ * @internal
+ */
+export declare function createPreviewProvenanceReadCacheKey(kind: PreviewProvenanceReadLifecycleInput<unknown>['kind'], value: unknown): string;

package/dist/preview-read-lifecycle.js

@@ -0,0 +1,40 @@
+import { prepareContentValues } from './content-values.js';
+/** @internal */
+export function runPreviewProvenanceReadLifecycle(requestContext, input) {
+    const lifecycle = requestContext?.unstable_previewProvenanceReadLifecycle;
+    return (lifecycle ? lifecycle(input) : input.executeRaw()).then(value => prepareContentValues(value, true, Boolean(requestContext?.previewToken)));
+}
+/**
+ * Stable, non-secret JSON key used only by request-local adapter caches.
+ * Functions, undefined values, and AbortSignals are intentionally omitted.
+ *
+ * @internal
+ */
+export function createPreviewProvenanceReadCacheKey(kind, value) {
+    return JSON.stringify({ contentVersion: 1, kind, value: canonicalize(value) });
+}
+function canonicalize(value) {
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (typeof value !== 'object')
+        return undefined;
+    if (isAbortSignal(value))
+        return undefined;
+    const result = {};
+    for (const key of Object.keys(value).sort()) {
+        const next = canonicalize(value[key]);
+        if (next !== undefined)
+            result[key] = next;
+    }
+    return result;
+}
+function isAbortSignal(value) {
+    return (typeof value.aborted === 'boolean' &&
+        typeof value.addEventListener === 'function');
+}

package/dist/preview-read-observation.d.ts

@@ -0,0 +1,18 @@
+import type { PreviewReadContext } from '@storystick/types/preview-query-targeting';
+export interface PreviewReadObservation {
+    readonly readContext?: PreviewReadContext;
+    readonly receiptId?: string;
+    readonly documentIds: readonly string[];
+    readonly storyTypes: readonly string[];
+    readonly codeVersion: string;
+    readonly observationId: string;
+    /**
+     * Clock sampled before the gateway content read. Multiple reads in one RSC
+     * render compose with MIN, never max: equal clocks are conservatively stale.
+     */
+    readonly renderWatermark: number;
+}
+export declare function attachPreviewReadObservation<T>(root: T, observation: PreviewReadObservation): T;
+export declare function getPreviewReadObservation(value: unknown): PreviewReadObservation | null;
+export declare function collectPreviewReadObservations(...roots: readonly unknown[]): readonly PreviewReadObservation[];
+export declare function conservativePreviewRenderWatermark(observations: readonly Pick<PreviewReadObservation, 'renderWatermark'>[]): number | undefined;