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

package/dist/content-values.js

@@ -0,0 +1,401 @@
+import { CONTENT_RENDER_MAX_DEPTH, ContentRenderDepthError } from '@storystick/types';
+import { carryPublicReadIdentity } from './public-delivery.js';
+import { attachPreviewQueryReceipt, getPreviewQueryReceiptId, } from './preview-query-receipt.js';
+import { isContentRenderPlan, mergeContentFields, getPreviewReadDependencies, setPreviewReadDependencies, getPreviewReadSourceMap, setPreviewReadSourceMap, } from '@storystick/types';
+import { hydrateSliceWithDiagnostics, } from './hydrate-slice.js';
+import { attachPreviewReadObservation, getPreviewReadObservation, } from './preview-read-observation.js';
+import { readPreviewProvenanceDocumentPathKey } from '@storystick/types/internal/preview-provenance';
+export { readContentOrigin } from '@storystick/types/internal/content-origin';
+import { readContentOrigin } from '@storystick/types/internal/content-origin';
+const rawReads = new WeakMap();
+/** Internal: live projections apply to authored reads before effective hydration. */
+export function rawContentValues(value) {
+    return value !== null && typeof value === 'object'
+        ? (rawReads.get(value) ?? value)
+        : value;
+}
+/** Prepare once per consumer, after the raw read cache and Preview coding. */
+export function prepareContentValues(value, requirePlan = false, preview = false) {
+    const visit = (v) => {
+        if (Array.isArray(v)) {
+            const children = v.map(visit);
+            const result = children.every((child, index) => child === v[index])
+                ? v
+                : children;
+            rawReads.set(result, rawContentValues(v));
+            carryPublicReadIdentity(v, result);
+            setPreviewReadDependencies(result, getPreviewReadDependencies(v));
+            setPreviewReadSourceMap(result, getPreviewReadSourceMap(v));
+            const observation = getPreviewReadObservation(v);
+            if (observation)
+                attachPreviewReadObservation(result, observation);
+            attachPreviewQueryReceipt(result, getPreviewQueryReceiptId(v) ?? undefined);
+            return result;
+        }
+        if (!record(v))
+            return v;
+        if (readContentOrigin(v))
+            return v;
+        // Diagnostic results are not usable reads; preserve their original error and partial material.
+        if (v.exactness === 'blocked' || v.exactness === 'degraded')
+            return v;
+        let result;
+        if (typeof v.documentId === 'string' &&
+            typeof v.storyType === 'string' &&
+            record(v.fields)) {
+            if (v._render === undefined) {
+                if (requirePlan)
+                    throw new TypeError('storystick/CONTENT_PROTOCOL: Delivery render plan is missing. Update the backend and reconcile the Content Plane before using this SDK.');
+                return v;
+            }
+            if (!isContentRenderPlan(v._render))
+                throw new TypeError('storystick/CONTENT_PROTOCOL: Unsupported delivery render plan.');
+            const prepare = documentPreparer(v, v._render, preview);
+            const authoredFields = v.fields;
+            const fields = prepare.fields(authoredFields, v._render.fields, '', []);
+            result = Object.keys(fields).every((key) => fields[key] === authoredFields[key])
+                ? v
+                : { ...v, fields };
+        }
+        else {
+            const children = Object.fromEntries(Object.entries(v).map(([key, child]) => [key, visit(child)]));
+            result = Object.keys(children).every((key) => children[key] === v[key])
+                ? v
+                : children;
+        }
+        rawReads.set(result, rawContentValues(v));
+        setPreviewReadDependencies(result, getPreviewReadDependencies(v));
+        setPreviewReadSourceMap(result, getPreviewReadSourceMap(v));
+        const observation = getPreviewReadObservation(v);
+        if (observation)
+            attachPreviewReadObservation(result, observation);
+        attachPreviewQueryReceipt(result, getPreviewQueryReceiptId(v) ?? undefined);
+        carryPublicReadIdentity(v, result);
+        return result;
+    };
+    return visit(value);
+}
+/** Explicit raw-content escape hatch. Never performs I/O or reads app context. */
+export function prepareContentSource(value, source) {
+    if (!source)
+        return value;
+    const doc = source.document;
+    if (!record(doc))
+        throw new TypeError('storystick/CONTENT_PROTOCOL: source.document needs a delivery render plan.');
+    const check = (v) => {
+        const origin = readContentOrigin(v);
+        if (origin &&
+            (origin.documentId !== doc.documentId ||
+                !(origin.path === source.path ||
+                    origin.path.startsWith(source.path + '[')))) {
+            throw new TypeError('storystick/CONTENT_SOURCE_MISMATCH: Content and source have different origins.');
+        }
+    };
+    if (Array.isArray(value))
+        value.forEach(check);
+    else
+        check(value);
+    if (doc._render === undefined)
+        return value;
+    if (!isContentRenderPlan(doc._render))
+        throw new TypeError('storystick/CONTENT_PROTOCOL: Unsupported delivery render plan.');
+    const tokens = source.path.match(/[^.[\]]+|\[\d+\]/g) ?? [];
+    let defs = doc._render.fields;
+    let current = mergeContentFields(recordOrEmpty(doc._render.dependencies), recordOrEmpty(doc.fields));
+    let def;
+    let prefix = '';
+    const anchors = [];
+    for (const token of tokens) {
+        if (token.startsWith('[')) {
+            current = Array.isArray(current)
+                ? current[Number(token.slice(1, -1))]
+                : undefined;
+            if (record(current) && typeof current._key === 'string')
+                anchors.push({ pathPrefix: prefix, key: current._key });
+            prefix += token;
+            if (def?.array)
+                def = { ...def, array: false };
+        }
+        else {
+            def = defs[token];
+            current = record(current) ? current[token] : undefined;
+            prefix += `${prefix ? '.' : ''}${token}`;
+        }
+        const type = record(current) && typeof current._type === 'string'
+            ? current._type
+            : def?.types?.[0];
+        const story = type ? doc._render.stories[type] : undefined;
+        defs =
+            record(current) && typeof current._variation === 'string'
+                ? (story?.variations?.[current._variation] ?? {})
+                : (story?.fields ?? {});
+    }
+    if (!def || prefix !== source.path)
+        throw new TypeError('storystick/CONTENT_PROTOCOL: Unknown source field path.');
+    return documentPreparer(doc, doc._render).field(def, value, source.path, anchors);
+}
+function documentPreparer(doc, plan, preview = false) {
+    const host = {
+        ...doc,
+        fields: mergeContentFields(recordOrEmpty(plan.dependencies), recordOrEmpty(doc.fields)),
+    };
+    const activeZones = new Set();
+    let compositionDepth = 0;
+    const origin = (kind, path, anchors, value) => {
+        const ids = new Set();
+        const collect = (v) => {
+            if (typeof v === 'string')
+                ids.add(v);
+            else if (Array.isArray(v))
+                v.forEach(collect);
+            else if (record(v))
+                for (const [key, child] of Object.entries(v))
+                    if (!key.startsWith('__ss'))
+                        collect(child);
+        };
+        collect(value);
+        const subset = (sidecar, byPath) => {
+            if (!record(sidecar))
+                return undefined;
+            const selected = {};
+            for (const [mapName, entries] of Object.entries(sidecar)) {
+                if (!record(entries))
+                    continue;
+                selected[mapName] = Object.fromEntries(Object.entries(entries).filter(([key]) => mapName === 'byRef' || (byPath && mapName === 'unresolved')
+                    ? key === path ||
+                        key.startsWith(path + '.') ||
+                        key.startsWith(path + '[')
+                    : ids.has(key)));
+            }
+            return Object.values(selected).some((map) => Object.keys(map).length)
+                ? selected
+                : undefined;
+        };
+        const assets = subset(doc._assets, false);
+        const refs = subset(doc._referencedDocs, true);
+        const previewProvenance = kind === 'richtext'
+            ? documentFieldPreviewProvenance(doc, path)
+            : undefined;
+        // Resolve this occurrence before the compatibility by-ID index. The same
+        // document may be linked both live and at a pinned snapshot on one page.
+        if (refs && record(refs.byRef) && record(refs.byId)) {
+            for (const [refPath, entry] of Object.entries(refs.byRef)) {
+                if ((refPath === path || refPath === `${path}.document`) &&
+                    record(entry) &&
+                    typeof entry.documentId === 'string')
+                    refs.byId[entry.documentId] = entry;
+            }
+            for (const [refPath, failure] of Object.entries(recordOrEmpty(refs.unresolved))) {
+                if ((refPath === path || refPath === `${path}.document`) &&
+                    record(failure) &&
+                    typeof failure.documentId === 'string')
+                    delete refs.byId[failure.documentId];
+            }
+        }
+        return {
+            version: 1,
+            documentId: String(doc.documentId),
+            path,
+            kind,
+            parentAnchors: anchors,
+            ...(preview || doc.__ssPreviewProvenance || doc.__ssPreviewRouteRender
+                ? { preview: true }
+                : {}),
+            ...(doc._localeRouting ? { _localeRouting: doc._localeRouting } : {}),
+            ...(assets
+                ? { _assets: assets }
+                : {}),
+            ...(refs
+                ? {
+                    _referencedDocs: refs,
+                }
+                : {}),
+            ...(previewProvenance
+                ? { __ssPreviewProvenance: previewProvenance }
+                : {}),
+        };
+    };
+    const fields = (values, defs, prefix, anchors) => Object.fromEntries(Object.entries(values).map(([name, value]) => [
+        name,
+        defs[name]
+            ? field(defs[name], value, prefix ? `${prefix}.${name}` : name, anchors)
+            : value,
+    ]));
+    const slice = (raw, path, anchors, zoneField, index, anchorPrefix = path.replace(/\[\d+\]$/, '')) => {
+        if (!record(raw) ||
+            typeof raw._type !== 'string' ||
+            typeof raw._key !== 'string')
+            return raw;
+        if (readContentOrigin(raw))
+            return raw;
+        if (++compositionDepth > CONTENT_RENDER_MAX_DEPTH)
+            throw new ContentRenderDepthError();
+        try {
+            const result = hydrateSliceWithDiagnostics(raw, host, {
+                sourceRefPath: `${path}._model`,
+            });
+            const story = plan.stories[raw._type];
+            const defs = typeof raw._variation === 'string'
+                ? story?.variations?.[raw._variation]
+                : story?.fields;
+            const currentAnchors = [
+                ...anchors,
+                { pathPrefix: anchorPrefix, key: raw._key },
+            ];
+            const hydrated = result.slice;
+            const effective = Object.fromEntries(Object.entries(hydrated).filter(([key]) => key.startsWith('_') || !defs || key in defs));
+            const prepared = fields(effective, defs ?? {}, path, currentAnchors);
+            const meta = origin('slice', path, anchors, effective);
+            const attrs = recordOrEmpty(recordOrEmpty(doc.__ssPreviewProvenance).attrsByKey);
+            const localAttrs = Object.fromEntries(Object.entries(attrs).filter(([key]) => sliceAttributeOwner(key) === raw._key));
+            if (Object.keys(localAttrs).length)
+                meta.__ssPreviewProvenance = { attrsByKey: localAttrs };
+            meta.index = index;
+            meta.anchorPrefix = anchorPrefix;
+            meta.zoneField = zoneField;
+            if (result.failures.length)
+                meta.failures = result.failures;
+            const mappings = recordOrEmpty(recordOrEmpty(doc._zoneMappings)[raw._type]);
+            const zones = {};
+            for (const [name, mapped] of Object.entries(mappings)) {
+                if (typeof mapped !== 'string')
+                    continue;
+                if (activeZones.has(mapped))
+                    throw new TypeError('storystick/CONTENT_PROTOCOL: Circular container zone mapping.');
+                activeZones.add(mapped);
+                const rootDef = plan.fields[mapped];
+                zones[name] = {
+                    path: mapped,
+                    value: rootDef
+                        ? field(rootDef, host.fields[mapped], mapped, [])
+                        : null,
+                };
+                activeZones.delete(mapped);
+            }
+            if (Object.keys(zones).length)
+                meta.zones = zones;
+            return { ...prepared, __ssContent: meta };
+        }
+        finally {
+            compositionDepth--;
+        }
+    };
+    const field = (def, value, path, anchors) => {
+        if (value == null)
+            return value;
+        if (record(value) &&
+            typeof value.documentId === 'string' &&
+            typeof value.storyType === 'string' &&
+            record(value.fields))
+            return prepareContentValues(value, false, preview);
+        if (readContentOrigin(value))
+            return value;
+        if (def.array && Array.isArray(value))
+            return value.map((v, i) => field({ ...def, array: false }, v, `${path}[${i}]`, record(v) && typeof v._key === 'string'
+                ? [...anchors, { pathPrefix: path, key: v._key }]
+                : anchors));
+        const kinds = Array.isArray(def.type) ? def.type : [def.type];
+        if (kinds.includes('sliceZone'))
+            return Array.isArray(value)
+                ? value.map((v, i) => slice(v, `${path}[${i}]`, anchors, path.split('.').at(-1), i))
+                : value;
+        if (kinds.includes('richtext')) {
+            let node = value;
+            if (typeof node === 'string') {
+                try {
+                    node = JSON.parse(node);
+                }
+                catch {
+                    return null;
+                }
+            }
+            if (!record(node) || node.type !== 'doc')
+                return null;
+            let embedIndex = 0;
+            const walk = (n, nodePath) => {
+                if (!record(n))
+                    return n;
+                if (n.type === 'sliceEmbed' && record(n.attrs)) {
+                    const attrs = n.attrs;
+                    const prepared = slice({
+                        ...recordOrEmpty(attrs.data),
+                        _key: attrs._key,
+                        _type: attrs._type,
+                        ...(attrs._variation === undefined
+                            ? {}
+                            : { _variation: attrs._variation }),
+                    }, `${nodePath}.data`, anchors, path.split('.').at(-1), embedIndex++, path);
+                    return { ...n, attrs: { ...attrs, data: prepared } };
+                }
+                return {
+                    ...n,
+                    ...(Array.isArray(n.marks)
+                        ? {
+                            marks: n.marks.map((mark, i) => record(mark) && mark.type === 'link' && record(mark.attrs)
+                                ? {
+                                    ...mark,
+                                    attrs: {
+                                        ...mark.attrs,
+                                        __ssContent: origin('link', `${nodePath}.marks[${i}]`, anchors, mark.attrs),
+                                    },
+                                }
+                                : mark),
+                        }
+                        : {}),
+                    ...(Array.isArray(n.content)
+                        ? {
+                            content: n.content.map((child, i) => walk(child, `${nodePath}.content[${i}]`)),
+                        }
+                        : {}),
+                };
+            };
+            return {
+                ...walk(node, path),
+                __ssContent: origin('richtext', path, anchors, node),
+            };
+        }
+        if (!record(value))
+            return value;
+        const type = typeof value._type === 'string' ? value._type : def.types?.[0];
+        const prepared = type && plan.stories[type]
+            ? fields(value, plan.stories[type].fields, path, anchors)
+            : { ...value };
+        return { ...prepared, __ssContent: origin(kinds[0], path, anchors, value) };
+    };
+    return { fields, field };
+}
+function record(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function recordOrEmpty(v) {
+    return record(v) ? v : {};
+}
+function sliceAttributeOwner(key) {
+    if (!key.startsWith('route:slice:v2:'))
+        return undefined;
+    try {
+        const payload = JSON.parse(decodeURIComponent(key.slice('route:slice:v2:'.length)));
+        return payload.v === 2 && typeof payload.sliceKey === 'string'
+            ? payload.sliceKey
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function documentFieldPreviewProvenance(document, path) {
+    // Container zones resolve document-owned root fields. Keep autonomous values
+    // compact by carrying only that field's markers, never the owner-wide map.
+    if (!/^[^.[\]]+$/.test(path))
+        return undefined;
+    const attrs = recordOrEmpty(recordOrEmpty(document.__ssPreviewProvenance).attrsByKey);
+    const documentId = String(document.documentId);
+    const selected = Object.fromEntries(Object.entries(attrs).filter(([key]) => {
+        const parsed = readPreviewProvenanceDocumentPathKey(key);
+        const root = parsed?.path[0];
+        return (parsed?.documentId === documentId &&
+            root?.type === 'field' &&
+            root.name === path);
+    }));
+    return Object.keys(selected).length > 0 ? { attrsByKey: selected } : undefined;
+}

package/dist/errors.d.ts

@@ -0,0 +1,65 @@
+import type { QueryResult, QueryPageInfo, QueryMeta, QueryReason } from '@storystick/types/query-contract';
+/**
+ * StorystickError — single source of truth for SDK errors (ADR-091
+ * §Consequences > @storystick/client).
+ *
+ * Lifted from `packages/next/src/server.ts` per the ADR-091 mandate that
+ * `@storystick/client` owns the class. Lane C re-exports it from
+ * `@storystick/next` for source-compat with existing user imports.
+ *
+ * Field parity is load-bearing — the consolidated transport throws
+ * `StorystickError` for every non-OK gateway response and consumers
+ * (`error.tsx` boundaries, devtools, support tickets) read every field.
+ * The CRITICAL `StorystickError field parity` test in
+ * `tests/transport.test.ts` pins the contract.
+ */
+export type StorystickErrorCategory = 'validation' | 'conflict' | 'auth' | 'system' | 'cancel';
+export interface StorystickErrorOptions {
+    /**
+     * Gateway-issued ref ID (`err_XXXXXXXX`) — populated when the gateway
+     * responded with a `{ error: { ref } }` body. Present on every non-2xx
+     * response from up-to-date deployments; absent for local validation
+     * errors that never hit the gateway.
+     */
+    ref?: string;
+    /** Boundary error code (post ADR-079 batch 5 namespaced `storystick/<NAME>`). */
+    code?: string;
+    /** Canonical category from the gateway envelope (post ADR-079 batch 4). */
+    category?: StorystickErrorCategory;
+    /** True if the user can fix the cause and retry. */
+    recoverable?: boolean;
+    /** True if the SDK / CLI can auto-retry without user input. */
+    retryable?: boolean;
+    /** Per-code structured payload from the gateway envelope. */
+    payload?: unknown;
+    /** HTTP status when a gateway response was received. */
+    status?: number;
+    /** Server retry delay; callers own retry/deadline/abort policy. */
+    retryAfterMs?: number;
+}
+export declare class StorystickError extends Error {
+    readonly ref: string | undefined;
+    readonly code: string | undefined;
+    readonly category: StorystickErrorCategory | undefined;
+    readonly recoverable: boolean | undefined;
+    readonly retryable: boolean | undefined;
+    readonly status: number | undefined;
+    readonly retryAfterMs: number | undefined;
+    readonly payload: unknown | undefined;
+    constructor(message: string, refOrOpts?: string | StorystickErrorOptions);
+}
+/** A strict content read could not return an exact Query V2 result. */
+export declare class QueryExecutionError extends StorystickError {
+    readonly result: {
+        exactness: 'blocked' | 'degraded';
+        data: unknown;
+        pageInfo: QueryPageInfo | null;
+        reason: QueryReason;
+        meta: QueryMeta;
+    };
+    constructor(result: QueryExecutionError['result']);
+}
+/** Shared strict-read policy for SDK adapters that also need pagination metadata. */
+export declare function assertExactQueryResult<TData, TPageInfo extends QueryPageInfo | null>(result: QueryResult<TData, TPageInfo>): asserts result is Extract<QueryResult<TData, TPageInfo>, {
+    exactness: 'exact';
+}>;

package/dist/errors.js

@@ -0,0 +1,45 @@
+export class StorystickError extends Error {
+    ref;
+    code;
+    category;
+    recoverable;
+    retryable;
+    status;
+    retryAfterMs;
+    payload;
+    constructor(message, refOrOpts) {
+        const opts = typeof refOrOpts === 'string' ? { ref: refOrOpts } : (refOrOpts ?? {});
+        const ref = opts.ref;
+        const refLine = ref
+            ? `\n\nReference ID: ${ref}\nShare this with support when reporting this issue.`
+            : '';
+        super(`${message}${refLine}`);
+        this.name = 'StorystickError';
+        this.ref = ref;
+        this.code = opts.code;
+        this.category = opts.category;
+        this.recoverable = opts.recoverable;
+        this.retryable = opts.retryable;
+        this.payload = opts.payload;
+        this.status = opts.status;
+        this.retryAfterMs = opts.retryAfterMs;
+    }
+}
+/** A strict content read could not return an exact Query V2 result. */
+export class QueryExecutionError extends StorystickError {
+    constructor(result) {
+        super('The content query did not produce an exact result.', {
+            code: 'storystick/QUERY_NOT_EXACT',
+            category: 'system',
+            retryable: result.reason.retryable,
+        });
+        this.name = 'QueryExecutionError';
+        // Keep the complete diagnostic server-side, out of ordinary serialization.
+        Object.defineProperty(this, 'result', { value: result, enumerable: false });
+    }
+}
+/** Shared strict-read policy for SDK adapters that also need pagination metadata. */
+export function assertExactQueryResult(result) {
+    if (result.exactness !== 'exact')
+        throw new QueryExecutionError(result);
+}

package/dist/hydrate-slice.d.ts

@@ -0,0 +1,2 @@
+export { hydrateSlice, hydrateSliceWithDiagnostics, getFieldBindings, resolveBinding, getByPath } from '@storystick/types/internal/hydrate-slice';
+export type { FieldBindingsSidecar, HydrateSliceOptions, HydratedSliceResult, SliceHydrationFailure } from '@storystick/types/internal/hydrate-slice';

package/dist/hydrate-slice.js

@@ -0,0 +1 @@
+export { hydrateSlice, hydrateSliceWithDiagnostics, getFieldBindings, resolveBinding, getByPath } from '@storystick/types/internal/hydrate-slice';

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { stripPreviewProvenance } from '@storystick/types/preview-provenance';
+/** @storystick/client — generated, typed Query V2 client. */
+export type { StorystickAsset, StorystickAssetAltDefault, StorystickAssetDeliveryStatus, StorystickAssetMetadata, StorystickAssetSidecar, StorystickAssetType, StorystickImageField, } from '@storystick/media';
+export type { QueryResult, ResolvedRoute, RequestLocaleContext, PublicationSeo, RequestOptions, DefaultRequestOptions, ClientAuth, ReferencedDocumentFailureReason, ReferencedDocumentPolicy, ReferencedDocumentSidecarEntry, ReferencedDocumentSidecarFailure, ReferencedDocumentsSidecar, ResolveRouteInput, PublicTransport as Transport, PublicTransportRequest as TransportRequest, TransportResponse, } from './types.js';
+export { resolveLink, resolveSafeHref, safeHref, } from '@storystick/types';
+export type { LinkOptions, LinkProps, LinkStatus, LinkValue, PathnameLiteralSegment, PathnameReferenceSegment, PathnameSegment, PathnameValue, ResolvedLink, SafeHrefResolution, SafeHrefStatus, } from '@storystick/types';
+export { createClient } from './query-client.js';
+export { createPublicRenderReceipt, serializePublicRenderReceipt, createPublicSiteManifest } from './public-delivery.js';
+export { PUBLIC_RENDER_RECEIPT_ID, PUBLIC_SITE_MANIFEST_PATH } from '@storystick/types/public-delivery';
+export type { PublicRenderReceiptV1, PublicSiteManifestV1 } from '@storystick/types/public-delivery';
+export type { Client, ClientOptions } from './query-client.js';
+export type { AddressedQuery, CollectionQuery, FieldAccessor, PagedQuery, QueryExecuteOptions, QueryFieldAccessors, QueryForSchema, QuerySelectionInput, QuerySortAccessors, QuerySortClause, QuerySortTuple, SelectedDocument, SelectedFields, SingletonQuery, UnselectedQuery, } from './query-builder.js';
+export type { QueryDslOperator, QueryFieldMap, QueryFieldType, QuerySchemaDefinition, QueryStoryMap, QueryStoryType, QueryStoriesOf, } from './query-schema.js';
+export { StorystickError, QueryExecutionError } from './errors.js';
+export type { StorystickErrorCategory, StorystickErrorOptions } from './errors.js';
+export { normalizePathname, pathnameToHref, pathnameToSegments, segmentsToPathname, } from './normalize-pathname.js';
+export { publicHrefForLocale, publishedLocaleHrefs, normalizePublicLocaleOrigins, prefixHref, publicPathnameForLocale, resolveLocalePathname } from './locale-routing.js';
+export type { LocalePathnameResolution, LocaleRouting, LocaleRoutingSettings, RoutingLocale, } from './locale-routing.js';
+export { resolveReference, resolveReferences } from './reference-resolver.js';
+export type { ReferenceDocument, ResolveReferenceOptions, ResolvedReference, } from './reference-resolver.js';
+export type { QueryRouteAccessors, QueryRoutePathAccessor } from './query-builder.js';
+export type { PublicLocaleOrigins } from './locale-routing.js';
+export type { SchemaStoryName, RoutableSchemaStoryName, RequestedStoryName, TypedRouteDocument, TypedDocumentRoute, ResolvedRouteForSchema } from './typed-route.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export { stripPreviewProvenance } from '@storystick/types/preview-provenance';
+export { resolveLink, resolveSafeHref, safeHref, } from '@storystick/types';
+export { createClient } from './query-client.js';
+export { createPublicRenderReceipt, serializePublicRenderReceipt, createPublicSiteManifest } from './public-delivery.js';
+export { PUBLIC_RENDER_RECEIPT_ID, PUBLIC_SITE_MANIFEST_PATH } from '@storystick/types/public-delivery';
+export { StorystickError, QueryExecutionError } from './errors.js';
+export { normalizePathname, pathnameToHref, pathnameToSegments, segmentsToPathname, } from './normalize-pathname.js';
+export { publicHrefForLocale, publishedLocaleHrefs, normalizePublicLocaleOrigins, prefixHref, publicPathnameForLocale, resolveLocalePathname } from './locale-routing.js';
+export { resolveReference, resolveReferences } from './reference-resolver.js';

package/dist/infra-resolver.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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.
+ */
+export interface ResolveInfraOptions {
+    /** Explicit endpoint override (gateway HTTP root, `.convex.site`). */
+    endpoint?: string;
+    /** Explicit Convex RPC URL override (`.convex.cloud`). */
+    convexUrl?: string;
+    /** Explicit JWKS URL override. */
+    jwksUrl?: string;
+    /**
+     * Optional gateway URL passed through to `resolveProject()` for self-host
+     * overrides. Unused by default ; resolution falls back to
+     * `DEFAULT_GATEWAY_URL` inside `resolve.ts`.
+     */
+    gatewayUrl?: string;
+}
+export interface ResolvedInfra {
+    /** Gateway HTTP root (`.convex.site` form). HTTP custom routes + JWKS. */
+    endpoint: string;
+    /** Convex RPC / WS URL (`.convex.cloud` form). */
+    convexUrl: string;
+    /** JWKS endpoint (default `${endpoint}/api/jwks.json`). */
+    jwksUrl: string;
+}
+/**
+ * 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 declare function resolveInfraSync(options?: ResolveInfraOptions): ResolvedInfra | null;
+/**
+ * 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 declare function resolveInfra(projectId: string, options?: ResolveInfraOptions): Promise<ResolvedInfra>;