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

package/dist/provenance/render-context.js

@@ -0,0 +1,338 @@
+import { isPreviewReadContext } from '@storystick/types/preview-query-targeting';
+import { previewProvenanceDocumentPathKey, readPreviewProvenanceDocumentPathKey, } from '@storystick/types/internal/preview-provenance';
+export function serializePreviewProvenanceSidecar(sidecar) {
+    return JSON.stringify(sidecar).replace(/</g, '\\u003c');
+}
+export function withPreviewProvenanceContext(context, attrsByKey) {
+    if (!attrsByKey)
+        return context;
+    const base = isRecord(context) ? context : {};
+    return {
+        ...base,
+        __ssPreviewProvenance: { attrsByKey },
+    };
+}
+export function withPreviewProvenanceRouteFrame(value, frame) {
+    if (!frame)
+        return value;
+    const base = isRecord(value) ? value : {};
+    return {
+        ...base,
+        __ssPreviewRouteFrame: frame,
+    };
+}
+export function readPreviewProvenanceRouteFrame(value) {
+    if (!isRecord(value))
+        return null;
+    const frame = value
+        .__ssPreviewRouteFrame;
+    if (!isRecord(frame))
+        return null;
+    if (frame.type !== 'storystick.preview.route-frame')
+        return null;
+    if (frame.version !== 1)
+        return null;
+    if (typeof frame.frameId !== 'string' || frame.frameId.length === 0) {
+        return null;
+    }
+    if (typeof frame.routeHash !== 'string' || frame.routeHash.length === 0) {
+        return null;
+    }
+    const publicSidecar = isRecord(frame.publicSidecar) &&
+        frame.publicSidecar.type === 'storystick.preview.public-sidecar'
+        ? frame.publicSidecar
+        : null;
+    if ((!frame.sessionId || typeof frame.sessionId !== 'string') &&
+        !isPreviewReadContext(publicSidecar?.dependencySet?.readContext))
+        return null;
+    return {
+        type: 'storystick.preview.route-frame',
+        version: 1,
+        frameId: frame.frameId,
+        ...(typeof frame.sessionId === 'string' ? { sessionId: frame.sessionId } : {}),
+        routeHash: frame.routeHash,
+        publicSidecar,
+    };
+}
+export function withPreviewProvenanceRouteRender(value, render) {
+    if (!render)
+        return value;
+    const base = isRecord(value) ? value : {};
+    return {
+        ...base,
+        __ssPreviewRouteRender: render,
+    };
+}
+export function readPreviewProvenanceRouteRender(value) {
+    if (!isRecord(value))
+        return null;
+    const render = value
+        .__ssPreviewRouteRender;
+    if (!isRecord(render))
+        return null;
+    if (render.type !== 'storystick.preview.route-render')
+        return null;
+    if (render.version !== 1)
+        return null;
+    const frame = readPreviewProvenanceRouteFrame({
+        __ssPreviewRouteFrame: render.frame,
+    });
+    if (frame === null)
+        return null;
+    if (!isRecord(render.document))
+        return null;
+    return {
+        type: 'storystick.preview.route-render',
+        version: 1,
+        frame,
+        document: render.document,
+    };
+}
+export function previewProvenanceAttrs(context, key) {
+    if (!isRecord(context))
+        return {};
+    const holder = context;
+    return withPreviewCarrierHydrationSuppression(holder.__ssPreviewProvenance?.attrsByKey[key]);
+}
+export function buildSliceProvenance(context, slice) {
+    if (!isRecord(context))
+        return undefined;
+    if (typeof slice._key !== 'string' || slice._key.length === 0)
+        return undefined;
+    const attrsByKey = context.__ssPreviewProvenance
+        ?.attrsByKey;
+    if (!attrsByKey)
+        return undefined;
+    const fields = {};
+    const arrays = {};
+    const paths = {};
+    let found = false;
+    for (const [key, attrs] of Object.entries(attrsByKey)) {
+        const parsed = parseSlicePathKey(key);
+        if (!parsed || parsed.sliceKey !== slice._key)
+            continue;
+        const hydratedAttrs = withPreviewCarrierHydrationSuppression(attrs);
+        paths[previewPathKey(parsed.path)] = hydratedAttrs;
+        copyStructuredPathToConvenienceViews(parsed.path, hydratedAttrs, fields, arrays);
+        found = true;
+    }
+    return found ? { fields, arrays, paths } : undefined;
+}
+export function buildDocumentProvenance(context, document) {
+    if (!isRecord(context))
+        return undefined;
+    if (typeof document.documentId !== 'string' ||
+        document.documentId.length === 0) {
+        return undefined;
+    }
+    const attrsByKey = context.__ssPreviewProvenance
+        ?.attrsByKey;
+    if (!attrsByKey)
+        return undefined;
+    const fields = {};
+    const paths = {};
+    let found = false;
+    for (const [key, attrs] of Object.entries(attrsByKey)) {
+        const parsed = parseDocumentPathKey(key);
+        if (!parsed || parsed.documentId !== document.documentId)
+            continue;
+        const hydratedAttrs = withPreviewCarrierHydrationSuppression(attrs);
+        paths[previewPathKey(parsed.path)] = hydratedAttrs;
+        copyDocumentPathToConvenienceViews(parsed.path, hydratedAttrs, fields);
+        found = true;
+    }
+    return found ? { fields, paths } : undefined;
+}
+function withPreviewCarrierHydrationSuppression(attrs) {
+    if (!attrs || typeof attrs['data-ss-p'] !== 'string')
+        return attrs ?? {};
+    return {
+        ...attrs,
+        suppressHydrationWarning: true,
+    };
+}
+export function fieldSegment(name) {
+    return { type: 'field', name };
+}
+export function arrayItemSegment(field, key) {
+    return { type: 'arrayItem', field, key };
+}
+export function richTextTextNodeSegment(index) {
+    return { type: 'richTextTextNode', index };
+}
+export function previewPathKey(path) {
+    return encodePathPayload(normalizePath(path));
+}
+export function slicePathKey(slice, path) {
+    const payload = {
+        v: 2,
+        sliceKey: slice._key,
+        path: normalizePath(path),
+    };
+    return `route:slice:v2:${encodePathPayload(payload)}`;
+}
+export function sliceFieldKey(slice, field) {
+    return slicePathKey(slice, [fieldSegment(field)]);
+}
+export function sliceArrayFieldKey(slice, arrayName, itemKey, field) {
+    return slicePathKey(slice, [
+        arrayItemSegment(arrayName, itemKey),
+        fieldSegment(field),
+    ]);
+}
+export function documentPathKey(document, path) {
+    return previewProvenanceDocumentPathKey(document.documentId, normalizePath(path));
+}
+export function documentFieldKey(document, field) {
+    return documentPathKey(document, [fieldSegment(field)]);
+}
+function parseSlicePathKey(key) {
+    const prefix = 'route:slice:v2:';
+    if (!key.startsWith(prefix))
+        return parseLegacyFlatSlicePathKey(key);
+    const payload = decodePathPayload(key.slice(prefix.length));
+    if (!isRecord(payload))
+        return null;
+    if (payload.v !== 2 || typeof payload.sliceKey !== 'string')
+        return null;
+    const path = normalizePath(payload.path);
+    if (path.length === 0)
+        return null;
+    return { sliceKey: payload.sliceKey, path };
+}
+function parseLegacyFlatSlicePathKey(key) {
+    const prefix = 'route:slice:';
+    if (!key.startsWith(prefix))
+        return null;
+    const rest = key.slice(prefix.length);
+    const separator = rest.indexOf(':');
+    if (separator <= 0)
+        return null;
+    const sliceKey = rest.slice(0, separator);
+    const slug = rest.slice(separator + 1);
+    if (sliceKey.length === 0 || slug.length === 0)
+        return null;
+    const parts = slug.split('_').filter((part) => part.length > 0);
+    if (parts.length === 0)
+        return null;
+    if (parts.length === 1) {
+        return { sliceKey, path: [fieldSegment(parts[0])] };
+    }
+    if (parts.length >= 3) {
+        return {
+            sliceKey,
+            path: [
+                arrayItemSegment(parts[0], parts.slice(1, -1).join('_')),
+                fieldSegment(parts[parts.length - 1]),
+            ],
+        };
+    }
+    return { sliceKey, path: [fieldSegment(slug)] };
+}
+function parseDocumentPathKey(key) {
+    const payload = readPreviewProvenanceDocumentPathKey(key);
+    if (!payload)
+        return null;
+    const path = normalizePath(payload.path);
+    if (path.length === 0)
+        return null;
+    return { documentId: payload.documentId, path };
+}
+function copyStructuredPathToConvenienceViews(path, attrs, fields, arrays) {
+    if (path.length === 1) {
+        const [field] = path;
+        if (field?.type === 'field' && isSafeRecordKey(field.name)) {
+            fields[field.name] = attrs;
+        }
+        return;
+    }
+    if (path.length !== 2)
+        return;
+    const [arrayItem, field] = path;
+    if (arrayItem?.type !== 'arrayItem' ||
+        field?.type !== 'field' ||
+        !isSafeRecordKey(arrayItem.field) ||
+        !isSafeRecordKey(arrayItem.key) ||
+        !isSafeRecordKey(field.name)) {
+        return;
+    }
+    let arrayItems = hasOwn(arrays, arrayItem.field)
+        ? arrays[arrayItem.field]
+        : undefined;
+    if (!arrayItems) {
+        arrayItems = {};
+        arrays[arrayItem.field] = arrayItems;
+    }
+    let itemFields = hasOwn(arrayItems, arrayItem.key)
+        ? arrayItems[arrayItem.key]
+        : undefined;
+    if (!itemFields) {
+        itemFields = {};
+        arrayItems[arrayItem.key] = itemFields;
+    }
+    itemFields[field.name] = attrs;
+}
+function copyDocumentPathToConvenienceViews(path, attrs, fields) {
+    if (path.length !== 1)
+        return;
+    const [field] = path;
+    if (field?.type === 'field' && isSafeRecordKey(field.name)) {
+        fields[field.name] = attrs;
+    }
+}
+function normalizePath(value) {
+    if (!Array.isArray(value))
+        return [];
+    const path = [];
+    for (const segment of value) {
+        if (!isRecord(segment))
+            return [];
+        if (segment.type === 'field' &&
+            typeof segment.name === 'string' &&
+            segment.name.length > 0) {
+            path.push({ type: 'field', name: segment.name });
+            continue;
+        }
+        if (segment.type === 'arrayItem' &&
+            typeof segment.field === 'string' &&
+            segment.field.length > 0 &&
+            typeof segment.key === 'string' &&
+            segment.key.length > 0) {
+            path.push({ type: 'arrayItem', field: segment.field, key: segment.key });
+            continue;
+        }
+        if (segment.type === 'richTextTextNode' &&
+            typeof segment.index === 'number' &&
+            Number.isInteger(segment.index) &&
+            segment.index >= 0) {
+            path.push({ type: 'richTextTextNode', index: segment.index });
+            continue;
+        }
+        return [];
+    }
+    return path;
+}
+function encodePathPayload(value) {
+    return encodeURIComponent(JSON.stringify(value));
+}
+function decodePathPayload(value) {
+    try {
+        return JSON.parse(decodeURIComponent(value));
+    }
+    catch {
+        return null;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasOwn(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key);
+}
+function isSafeRecordKey(key) {
+    return (typeof key === 'string' &&
+        key.length > 0 &&
+        key !== '__proto__' &&
+        key !== 'constructor' &&
+        key !== 'prototype');
+}

package/dist/provenance/reveal-contract.d.ts

@@ -0,0 +1,44 @@
+import type { ProvenanceId } from './types.js';
+export interface PreviewV2SourceIdentityRequest {
+    documentId: string;
+    anchoredPath: string;
+    sliceKey?: string;
+    expectedSourceKey?: string;
+    expectedSourceKind?: ProvenanceId['sourceKind'];
+    richTextTextNodeIndex?: number;
+    richTextSliceEmbedIndex?: number;
+    richTextSliceEmbedKey?: string;
+}
+export interface PreviewV2SourceIdentity {
+    sourceKey: string;
+    sourceKind: ProvenanceId['sourceKind'];
+    frameId: string;
+    routeHash: string;
+    variantId: string | null;
+    codeVersion: string;
+    renderId: string;
+    markerIds: readonly string[];
+    sourceMapBytes: number | null;
+    sourceMapLookupMs: number | null;
+}
+export interface PreviewV2RevealSourceRequest extends PreviewV2SourceIdentityRequest {
+    behavior?: {
+        scroll?: boolean;
+        flash?: boolean;
+        durationMs?: number;
+    };
+}
+export interface PreviewV2RevealSliceRequest {
+    documentId: string;
+    sliceKey: string;
+    behavior?: {
+        scroll?: boolean;
+        flash?: boolean;
+        durationMs?: number;
+    };
+}
+export interface PreviewRevealCommands {
+    resolvePreviewV2SourceIdentity: (request: PreviewV2SourceIdentityRequest) => PreviewV2SourceIdentity | null;
+    revealPreviewV2Source: (request: PreviewV2RevealSourceRequest) => boolean;
+    revealPreviewV2Slice: (request: PreviewV2RevealSliceRequest) => boolean;
+}

package/dist/provenance/reveal-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/provenance/richtext-slice-embed-address.d.ts

@@ -0,0 +1,20 @@
+export interface PreviewRichTextSliceEmbedAddress {
+    readonly rootPath: string;
+    readonly index: number;
+    readonly navigationPath: string;
+}
+/**
+ * Rich-text slice embeds are addressed as editorial slice instances:
+ * `<richtextField>[embedOrdinal]`, e.g. `body[0]` or `meta.body[2]`.
+ *
+ * The ordinal counts only `sliceEmbed` atoms, not ProseMirror `content[]`
+ * nodes. This deliberately avoids leaking `attrs.data` or paragraph nodes
+ * into the Studio/provenance contract.
+ */
+export declare function parsePreviewRichTextSliceEmbedAddress(path: string, expectedIndex?: number): PreviewRichTextSliceEmbedAddress | null;
+export declare function formatPreviewRichTextSliceEmbedPath(rootPath: string, index: number): string | null;
+export declare const richTextSliceEmbedAddressFromPath: typeof parsePreviewRichTextSliceEmbedAddress;
+export declare function richTextSliceEmbedKeyFromAnchors(anchors: ReadonlyArray<{
+    pathPrefix: string;
+    key: string;
+}> | undefined, rootPath: string): string | undefined;

package/dist/provenance/richtext-slice-embed-address.js

@@ -0,0 +1,35 @@
+/**
+ * Rich-text slice embeds are addressed as editorial slice instances:
+ * `<richtextField>[embedOrdinal]`, e.g. `body[0]` or `meta.body[2]`.
+ *
+ * The ordinal counts only `sliceEmbed` atoms, not ProseMirror `content[]`
+ * nodes. This deliberately avoids leaking `attrs.data` or paragraph nodes
+ * into the Studio/provenance contract.
+ */
+export function parsePreviewRichTextSliceEmbedAddress(path, expectedIndex) {
+    const match = /^(body|.*\.body)\[(\d+)\](?:\.|$)/.exec(path);
+    if (match === null)
+        return null;
+    const index = Number.parseInt(match[2], 10);
+    if (!Number.isInteger(index) || index < 0)
+        return null;
+    if (expectedIndex !== undefined && index !== expectedIndex)
+        return null;
+    const rootPath = match[1];
+    return {
+        rootPath,
+        index,
+        navigationPath: `${rootPath}[${index}]`,
+    };
+}
+export function formatPreviewRichTextSliceEmbedPath(rootPath, index) {
+    if (rootPath.length === 0)
+        return null;
+    if (!Number.isInteger(index) || index < 0)
+        return null;
+    return `${rootPath}[${index}]`;
+}
+export const richTextSliceEmbedAddressFromPath = parsePreviewRichTextSliceEmbedAddress;
+export function richTextSliceEmbedKeyFromAnchors(anchors, rootPath) {
+    return anchors?.find(anchor => anchor.pathPrefix === rootPath)?.key;
+}

package/dist/provenance/runtime-script.d.ts

@@ -0,0 +1 @@
+export declare const previewProvenanceRuntimeScript: string;