@storystick/preview 0.0.0-stage → 0.2.0-rc.0

package/dist/provenance/source-map-materializer.d.ts

@@ -0,0 +1,76 @@
+import { type PreviewReadScopeEcho } from '@storystick/client/internal';
+import { type PreviewProvenanceEditableLeaf, type PreviewProvenanceEditableTextLeafContext, type PreviewProvenanceEditableTextPathManifest, type PreviewProvenancePathPart } from './editable-leaf.js';
+import type { PathAnchor, ProvenanceId, SourceSet } from './types.js';
+export interface PreviewProvenanceQueryResultLike {
+    readonly documentId: string;
+    readonly storyType?: string;
+    readonly fields?: unknown;
+    readonly _previewScope?: PreviewReadScopeEcho;
+    readonly _locale?: {
+        readonly variantId?: string | null;
+    };
+    readonly _variant?: {
+        readonly variantId?: string | null;
+    };
+}
+export interface PreviewProvenanceSourceMapEntry {
+    readonly resultPath: readonly PreviewProvenancePathPart[];
+    readonly documentId: string;
+    readonly variantId?: string;
+    readonly readScope?: PreviewReadScopeEcho;
+    readonly storyType: string;
+    readonly canonicalPath: string;
+    readonly pathAnchors: readonly PathAnchor[];
+    readonly sourceKind: PreviewProvenanceEditableTextLeafContext['sourceKind'];
+    readonly outputKind?: PreviewProvenanceEditableTextLeafContext['outputKind'];
+    readonly renderedText?: string;
+    readonly derivation?: SourceSet['derivation'];
+    readonly textNodeIndex?: number;
+}
+export interface PreviewProvenanceQueryResultSourceMap {
+    readonly documentId: string;
+    readonly storyType: string;
+    readonly entries: readonly PreviewProvenanceSourceMapEntry[];
+}
+export interface MaterializePreviewProvenanceSourceMapInput {
+    readonly queryResult: PreviewProvenanceQueryResultLike;
+    readonly manifest: PreviewProvenanceEditableTextPathManifest;
+    readonly keyPrefix: string;
+    readonly sourceSetPrefix: string;
+    readonly keyForEntry?: (entry: PreviewProvenanceSourceMapEntry, defaultKey: string) => string;
+    readonly presence?: PreviewProvenanceEditableLeaf['presence'];
+    readonly anchorMultiplicity?: PreviewProvenanceEditableLeaf['anchorMultiplicity'];
+}
+export interface MaterializedPreviewProvenanceSourceMap {
+    readonly sourceMapEntries: number;
+    readonly leaves: readonly PreviewProvenanceEditableLeaf[];
+    readonly skipped: PreviewProvenanceSourceMapSkipSummary;
+}
+export interface PreviewProvenanceSourceMapSkipSummary {
+    readonly manifestIneligible: number;
+    readonly nonIdentityDerivation: number;
+}
+export declare function attachPreviewProvenanceSourceMap<T extends object>(value: T, sourceMap: PreviewProvenanceQueryResultSourceMap): T;
+export declare function getPreviewProvenanceSourceMap(value: unknown): PreviewProvenanceQueryResultSourceMap | null;
+export declare function ensurePreviewProvenanceSourceMap<T extends PreviewProvenanceQueryResultLike>(queryResult: T): PreviewProvenanceQueryResultSourceMap;
+export declare function createPreviewProvenanceQueryResultSourceMap(queryResult: PreviewProvenanceQueryResultLike): PreviewProvenanceQueryResultSourceMap;
+export declare function collectPreviewProvenanceSourceMappedQueryResults(root: unknown): readonly PreviewProvenanceQueryResultLike[];
+export declare function materializePreviewProvenanceSourceMap(input: MaterializePreviewProvenanceSourceMapInput): MaterializedPreviewProvenanceSourceMap;
+/** Identity of an editorial source supplied by this read, including bindings. */
+export declare function previewProvenanceSourceIdentityFromQueryResult(queryResult: PreviewProvenanceQueryResultLike): Pick<ProvenanceId, 'documentId' | 'variantId' | 'readScope'>;
+/**
+ * Read the gateway's explicit applied-scope echo.
+ *
+ * `undefined` means the payload predates the echo and callers may use their
+ * legacy identity fallback. `null` is authoritative: the gateway explicitly
+ * says living content was applied, so an expected variant must not mask it.
+ */
+export declare function appliedPreviewVariantIdFromQueryResult(queryResult: PreviewProvenanceQueryResultLike): string | null | undefined;
+/**
+ * Read the requested scope echo even when the concrete document is outside
+ * that scope. A host frame can retain the session lifecycle identity while
+ * only an applicable target payload is allowed to prove a mismatch.
+ */
+export declare function requestedPreviewVariantIdFromQueryResult(queryResult: PreviewProvenanceQueryResultLike): string | null | undefined;
+/** Return the complete gateway-owned scope echo for runtime reporting. */
+export declare function previewReadScopeEchoFromQueryResult(queryResult: PreviewProvenanceQueryResultLike): PreviewReadScopeEcho | undefined;

package/dist/provenance/source-map-materializer.js

@@ -0,0 +1,286 @@
+import { getPreviewReadSourceMap, setPreviewReadSourceMap } from '@storystick/types';
+import { createPreviewProvenanceEditableLeaf, formatPreviewProvenanceCanonicalPath, matchingPreviewProvenanceEditablePathPattern, } from './editable-leaf.js';
+import { walkPreviewProvenanceFieldLeaves } from './field-leaf-walker.js';
+import { normalizePreviewVariantId } from '../identity/preview-identity.js';
+export function attachPreviewProvenanceSourceMap(value, sourceMap) {
+    setPreviewReadSourceMap(value, sourceMap);
+    return value;
+}
+export function getPreviewProvenanceSourceMap(value) {
+    if (!isObject(value))
+        return null;
+    const sourceMap = getPreviewReadSourceMap(value);
+    return isPreviewProvenanceSourceMap(sourceMap) ? sourceMap : null;
+}
+export function ensurePreviewProvenanceSourceMap(queryResult) {
+    const existing = getPreviewProvenanceSourceMap(queryResult);
+    if (existing !== null)
+        return existing;
+    const sourceMap = createPreviewProvenanceQueryResultSourceMap(queryResult);
+    attachPreviewProvenanceSourceMap(queryResult, sourceMap);
+    return sourceMap;
+}
+export function createPreviewProvenanceQueryResultSourceMap(queryResult) {
+    const storyType = typeof queryResult.storyType === 'string' && queryResult.storyType.length > 0
+        ? queryResult.storyType
+        : 'unknown';
+    const entries = [];
+    const sourceIdentity = previewProvenanceSourceIdentityFromQueryResult(queryResult);
+    walkPreviewProvenanceFieldLeaves({
+        root: queryResult.fields,
+        onLeaf: (walked) => {
+            entries.push({
+                resultPath: walked.path,
+                ...sourceIdentity,
+                storyType,
+                canonicalPath: formatPreviewProvenanceCanonicalPath(walked.path),
+                pathAnchors: walked.pathAnchors,
+                sourceKind: walked.sourceKind,
+                outputKind: walked.outputKind,
+                renderedText: walked.renderedText,
+                derivation: 'identity',
+                ...(walked.textNodeIndex === undefined
+                    ? {}
+                    : { textNodeIndex: walked.textNodeIndex }),
+            });
+        },
+    });
+    return {
+        documentId: queryResult.documentId,
+        storyType,
+        entries,
+    };
+}
+export function collectPreviewProvenanceSourceMappedQueryResults(root) {
+    const out = new Map();
+    const seen = new WeakSet();
+    const visit = (value) => {
+        if (!isObject(value))
+            return;
+        if (seen.has(value))
+            return;
+        seen.add(value);
+        if (isQueryResultLike(value)) {
+            // The first occurrence is the canonical render carrier. Delivery
+            // documents expose referenced QueryResult-like entries twice (`byId`
+            // and `byRef`); letting the later alias replace the first would encode a
+            // different clone from the one SDK readers return.
+            if (!out.has(value.documentId))
+                out.set(value.documentId, value);
+            visit(value.resolved);
+            const referenced = value._referencedDocs;
+            if (isObject(referenced)) {
+                // JSON object order is not a contract. Readers use `byId` as their
+                // canonical convenience carrier, so always visit it before aliases.
+                visit(referenced.byId);
+                visit(referenced.byRef);
+            }
+            else {
+                visit(referenced);
+            }
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        for (const [key, child] of Object.entries(value)) {
+            if (key === '__ssPreviewProvenance')
+                continue;
+            visit(child);
+        }
+    };
+    visit(root);
+    return [...out.values()];
+}
+export function materializePreviewProvenanceSourceMap(input) {
+    const sourceMap = ensurePreviewProvenanceSourceMap(input.queryResult);
+    const leaves = [];
+    let manifestIneligible = 0;
+    let nonIdentityDerivation = 0;
+    for (const entry of sourceMap.entries) {
+        const outputKind = entry.outputKind ?? 'text';
+        const value = outputKind === 'element'
+            ? valueAtPath(input.queryResult.fields, entry.resultPath)
+            : entry.renderedText;
+        const context = {
+            path: entry.resultPath,
+            fieldName: leafFieldName(entry.resultPath),
+            value,
+            sourceKind: entry.sourceKind,
+            outputKind,
+            textNodeIndex: entry.textNodeIndex,
+        };
+        const pattern = matchingPreviewProvenanceSourceMapEntryPattern(context, sourceMap.storyType, input.manifest);
+        if (pattern === null) {
+            manifestIneligible++;
+            continue;
+        }
+        const hasNonIdentityDerivation = entry.derivation !== undefined && entry.derivation !== 'identity';
+        if (hasNonIdentityDerivation)
+            nonIdentityDerivation++;
+        const slug = pathSlug(entry.resultPath, entry.pathAnchors);
+        const documentSlug = safeSlugPart(entry.documentId);
+        const defaultKey = `${input.keyPrefix}:${slug}${entry.textNodeIndex === undefined ? '' : `:richtext:${entry.textNodeIndex}`}`;
+        const source = sourceForSourceMapEntry(entry);
+        leaves.push(createPreviewProvenanceEditableLeaf({
+            key: input.keyForEntry?.(entry, defaultKey) ?? defaultKey,
+            documentId: entry.documentId,
+            variantId: entry.variantId,
+            readScope: entry.readScope,
+            leafPath: entry.resultPath,
+            pathAnchors: entry.pathAnchors,
+            sourceKind: entry.sourceKind,
+            sourceSetId: `${input.sourceSetPrefix}_${documentSlug}_${slug}${entry.textNodeIndex === undefined ? '' : `_richtext_${entry.textNodeIndex}`}`,
+            outputKind,
+            modality: pattern.modality ?? 'text',
+            anchorKind: pattern.anchorKind ?? 'element',
+            renderedText: entry.renderedText,
+            ...(hasNonIdentityDerivation
+                ? {
+                    sourceSet: {
+                        kind: 'derived',
+                        sources: [source],
+                        primary: source,
+                        derivation: entry.derivation,
+                        editable: 'not-editable',
+                    },
+                }
+                : {}),
+            codedText: outputKind === 'text' &&
+                !hasNonIdentityDerivation &&
+                entry.sourceKind === 'stored'
+                ? true
+                : undefined,
+            codedRichTextTextNodeIndex: outputKind === 'text' &&
+                !hasNonIdentityDerivation &&
+                entry.sourceKind === 'richtext'
+                ? entry.textNodeIndex
+                : undefined,
+            // Image attribute carriers retain their established repeatable contract.
+            // C3 re-arms text-field duplication diagnostics without changing the
+            // SDK image surface or its anchoring grammar.
+            anchorMultiplicity: input.anchorMultiplicity ??
+                (pattern.modality === 'attr:src' && pattern.anchorKind === 'attribute'
+                    ? 'multi'
+                    : undefined),
+            // Element carriers follow the caller's declared presence, like text.
+            presence: input.presence,
+        }));
+    }
+    return {
+        sourceMapEntries: sourceMap.entries.length,
+        leaves,
+        skipped: {
+            manifestIneligible,
+            nonIdentityDerivation,
+        },
+    };
+}
+function sourceForSourceMapEntry(entry) {
+    return {
+        documentId: entry.documentId,
+        ...(entry.variantId !== undefined ? { variantId: entry.variantId } : {}),
+        ...(entry.readScope !== undefined ? { readScope: entry.readScope } : {}),
+        canonicalPath: entry.canonicalPath,
+        pathAnchors: entry.pathAnchors,
+        sourceKind: entry.sourceKind,
+        ...(entry.textNodeIndex !== undefined
+            ? { textNodeIndex: entry.textNodeIndex }
+            : {}),
+    };
+}
+function valueAtPath(root, path) {
+    let current = root;
+    for (const part of path) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function matchingPreviewProvenanceSourceMapEntryPattern(context, storyType, manifest) {
+    return matchingPreviewProvenanceEditablePathPattern(context, manifest[storyType] ?? []);
+}
+/** Identity of an editorial source supplied by this read, including bindings. */
+export function previewProvenanceSourceIdentityFromQueryResult(queryResult) {
+    const variantId = queryResultVariantId(queryResult);
+    const readScope = previewReadScopeEchoFromQueryResult(queryResult);
+    return {
+        documentId: queryResult.documentId,
+        ...(variantId !== null ? { variantId } : {}),
+        ...(readScope !== undefined ? { readScope } : {}),
+    };
+}
+function queryResultVariantId(queryResult) {
+    const echoedAppliedVariantId = appliedPreviewVariantIdFromQueryResult(queryResult);
+    if (echoedAppliedVariantId !== undefined)
+        return echoedAppliedVariantId;
+    return (normalizePreviewVariantId(queryResult._locale?.variantId) ??
+        normalizePreviewVariantId(queryResult._variant?.variantId));
+}
+/**
+ * Read the gateway's explicit applied-scope echo.
+ *
+ * `undefined` means the payload predates the echo and callers may use their
+ * legacy identity fallback. `null` is authoritative: the gateway explicitly
+ * says living content was applied, so an expected variant must not mask it.
+ */
+export function appliedPreviewVariantIdFromQueryResult(queryResult) {
+    const scope = queryResult._previewScope;
+    if (scope === undefined ||
+        scope.appliesToDocument === false ||
+        !Object.prototype.hasOwnProperty.call(scope, 'appliedVariantId')) {
+        return undefined;
+    }
+    return normalizePreviewVariantId(scope.appliedVariantId);
+}
+/**
+ * Read the requested scope echo even when the concrete document is outside
+ * that scope. A host frame can retain the session lifecycle identity while
+ * only an applicable target payload is allowed to prove a mismatch.
+ */
+export function requestedPreviewVariantIdFromQueryResult(queryResult) {
+    const scope = queryResult._previewScope;
+    if (scope === undefined ||
+        !Object.prototype.hasOwnProperty.call(scope, 'requestedVariantId')) {
+        return undefined;
+    }
+    return normalizePreviewVariantId(scope.requestedVariantId);
+}
+/** Return the complete gateway-owned scope echo for runtime reporting. */
+export function previewReadScopeEchoFromQueryResult(queryResult) {
+    return queryResult._previewScope;
+}
+function isPreviewProvenanceSourceMap(value) {
+    return (isObject(value) &&
+        typeof value.documentId === 'string' &&
+        typeof value.storyType === 'string' &&
+        Array.isArray(value.entries));
+}
+function isQueryResultLike(value) {
+    return (isObject(value) &&
+        typeof value.documentId === 'string' &&
+        isObject(value.fields));
+}
+function leafFieldName(path) {
+    const leaf = path[path.length - 1];
+    return typeof leaf === 'string' ? leaf : null;
+}
+function pathSlug(path, pathAnchors) {
+    const keyByArrayPath = new Map(pathAnchors.map((anchor) => [anchor.path, anchor.key]));
+    return path.map((part, index) => {
+        if (typeof part === 'number') {
+            const arrayPath = formatPreviewProvenanceCanonicalPath(path.slice(0, index));
+            return safeSlugPart(keyByArrayPath.get(arrayPath) ?? String(part));
+        }
+        return safeSlugPart(part);
+    }).join('_');
+}
+function safeSlugPart(value) {
+    return value.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'field';
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/provenance/source-registry.d.ts

@@ -0,0 +1,103 @@
+import { type MultiFrameAnchorMaps } from "./multi-frame-anchor-map.js";
+import { type PreviewPaintRenderIdentity } from "./anchor-map.js";
+import type { ProvenanceOwnerMap, ResolvedProvenanceOwner } from "./owner-map.js";
+import { type PreviewOverlayClickTarget } from "./overlay-projection.js";
+import type { PreviewOverlayClickPayload, PreviewV2RevealResultStatus, PreviewV2RevealSourcePayload, PreviewV2RevealTargetToken } from "@storystick/transport-allowlist";
+import type { PreviewV2RevealSliceRequest, PreviewV2SourceIdentity, PreviewV2SourceIdentityRequest } from "./reveal-contract.js";
+export interface PreviewPresentationFrameIdentity {
+    documentId: string | null;
+    pathname: string;
+    sessionId?: string | null;
+    routeHash?: string | null;
+    renderId?: string | null;
+    codeVersion?: string | null;
+}
+export interface ActivePreviewOverlayClickTargets {
+    generation: number;
+    /** Authority used to revalidate a paint before interaction routing. */
+    interactionAuthority: "live-direct-locator" | "legacy-snapshot";
+    presentationFrameIdentity: PreviewPresentationFrameIdentity;
+    renderIdentity: PreviewPaintRenderIdentity;
+    targets: ReadonlyMap<string, PreviewOverlayClickTarget>;
+}
+export interface PreviewV2SourceRegistryInput {
+    sessionId: string | null;
+    anchorMap: MultiFrameAnchorMaps | null;
+    ownerMap: ProvenanceOwnerMap | null;
+    sourceMapBytes: number | null;
+    activeOverlayTargets?: ActivePreviewOverlayClickTargets | null;
+    sourceIdentitySnapshot?: PreviewV2SourceIdentitySnapshot | null;
+    /** Read transient iframe scroll state without rebuilding the registry. */
+    currentViewport?: () => MultiFrameAnchorMaps["viewport"];
+    activePaintFor?: (documentId: string, sourceSetId: string) => PreviewV2ActivePaint | null;
+}
+export interface PreviewV2ActivePaint {
+    readonly sourceSetId: string;
+    readonly markerId: string;
+    readonly paintId: string;
+    readonly renderIdentity: PreviewPaintRenderIdentity;
+}
+export type PreviewV2RevealTargetSelection = {
+    readonly kind: "active-paint";
+    readonly paintId: string;
+} | {
+    readonly kind: "nearest-viewport-fallback";
+    readonly paintId: string;
+} | {
+    readonly kind: "first-document-fallback";
+    readonly paintId: string;
+};
+export type PreviewV2RevealPayloadResolution = {
+    ok: true;
+    payload: PreviewV2RevealSourcePayload;
+    expectedStatus: PreviewV2RevealResultStatus;
+    selection: PreviewV2RevealTargetSelection;
+} | {
+    ok: false;
+    sourceKey: string | null;
+    status: Extract<PreviewV2RevealResultStatus, "unknownSource" | "notMounted" | "routeMissing">;
+};
+export interface PreviewV2RevealBehavior {
+    scroll: boolean;
+    flash: boolean;
+    durationMs: number;
+}
+interface CachedPreviewV2SourceIdentity {
+    sourceKey: string;
+    sourceKind: ResolvedProvenanceOwner["sourceKind"];
+    frameId: string;
+    routeHash: string;
+    variantId: string | null;
+    codeVersion: string;
+    renderId: string;
+    sourceMapBytes: number | null;
+}
+export interface PreviewV2SourceIdentitySnapshot {
+    renderIdentity: PreviewPaintRenderIdentity;
+    entries: ReadonlyMap<string, CachedPreviewV2SourceIdentity>;
+    markerIdsBySourceKey: ReadonlyMap<string, readonly string[]>;
+}
+export declare function createPreviewV2SourceIdentitySnapshot(input: {
+    sessionId: string | null;
+    anchorMap: MultiFrameAnchorMaps | null;
+    ownerMap: ProvenanceOwnerMap | null;
+    sourceMapBytes: number | null;
+}): PreviewV2SourceIdentitySnapshot | null;
+export declare function createPreviewV2SourceRegistry(input: PreviewV2SourceRegistryInput): {
+    resolveSourceIdentity: (request: PreviewV2SourceIdentityRequest) => Omit<PreviewV2SourceIdentity, "sourceMapLookupMs"> | null;
+    resolveActiveRenderTargets: (sourceKey: string) => PreviewV2RevealTargetToken[];
+    resolveRevealPayloadForStudioTarget: (args: {
+        request: PreviewV2SourceIdentityRequest;
+        requestId: string;
+        behavior: PreviewV2RevealBehavior;
+    }) => PreviewV2RevealPayloadResolution;
+    resolveRevealPayloadForStudioSlice: (args: {
+        request: PreviewV2RevealSliceRequest;
+        requestId: string;
+        behavior: PreviewV2RevealBehavior;
+    }) => PreviewV2RevealPayloadResolution;
+    resolveEditableTargetFromOverlayClick: (payload: PreviewOverlayClickPayload, options?: {
+        expectedPresentationDocumentId?: string | null;
+    }) => PreviewOverlayClickTarget | null;
+};
+export {};