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

package/dist/provenance/frame-dependencies.js

@@ -0,0 +1,550 @@
+import { getPreviewReadDependencies, setPreviewReadDependencies } from '@storystick/types';
+import { isPreviewReadContext } from '@storystick/types/preview-query-targeting';
+export const PREVIEW_CONTENT_CHANGE_OPERATIONS = [
+    'create',
+    'update',
+    'delete',
+    'publish',
+    'unpublish',
+    'rollback',
+    'restore-draft',
+    'archive',
+    'unarchive',
+    'shape-migration',
+    'snapshot-shape-migration',
+    'template-create',
+    'template-update',
+    'template-archive',
+    'template-delete',
+    'variant-create',
+    'variant-update',
+    'variant-discard',
+    'variant-promote',
+    'variant-switch',
+    'unknown',
+];
+const PREVIEW_CONTENT_CHANGE_OPERATION_SET = new Set(PREVIEW_CONTENT_CHANGE_OPERATIONS);
+export const PREVIEW_CONTENT_PLANE_OUTBOX_KIND_TO_OPERATION = {
+    'document.create': 'create',
+    'document.update': 'update',
+    'document.delete': 'delete',
+    'document.publish': 'publish',
+    'document.unpublish': 'unpublish',
+    'document.rollback': 'rollback',
+    'document.restoreDraft': 'restore-draft',
+    'document.archive': 'archive',
+    'document.unarchive': 'unarchive',
+    'document.shapeMigration': 'shape-migration',
+    'snapshot.shapeMigration': 'snapshot-shape-migration',
+    'asset.create': 'update',
+    'asset.update': 'update',
+    'asset.archive': 'archive',
+    'template.create': 'template-create',
+    'template.update': 'template-update',
+    'template.archive': 'template-archive',
+    'template.delete': 'template-delete',
+    'template.default.update': 'template-update',
+    'release.create': 'unknown',
+    'release.update': 'unknown',
+    'release.schedule': 'unknown',
+    'release.unschedule': 'unknown',
+    'release.archive': 'unknown',
+    'locale.settings.update': 'unknown',
+    'variant.create': 'variant-create',
+    'variant.update': 'variant-update',
+    'variant.discard': 'variant-discard',
+    'variant.promote': 'variant-promote',
+    'project.wipe': 'unknown',
+    'refs.backfill': 'unknown',
+    'richtextEmbeds.migrate': 'unknown',
+    'contentShape.epoch': 'unknown',
+    'schema.push': 'unknown',
+    'schema.generation.project': 'unknown',
+};
+export const PREVIEW_CONTENT_PLANE_OUTBOX_UNKNOWN_REASONS = {
+    'release.create': 'release mutations are not preview-rendered document/template writes',
+    'release.update': 'release mutations are not preview-rendered document/template writes',
+    'release.schedule': 'release scheduling has no route-specific preview dependency identity',
+    'release.unschedule': 'release scheduling has no route-specific preview dependency identity',
+    'release.archive': 'release mutations are not preview-rendered document/template writes',
+    'locale.settings.update': 'locale settings can change fallback/read semantics project-wide',
+    'project.wipe': 'project wipe is destructive and must refresh fail-open if observed',
+    'refs.backfill': 'backfills do not carry a user mutation target identity',
+    'richtextEmbeds.migrate': 'embed extraction can change every rendered content family project-wide',
+    'contentShape.epoch': 'an epoch switch changes project-wide content composition semantics',
+    'schema.push': 'schema pushes can change renderer shape outside document identity',
+    'schema.generation.project': 'schema-generation projection can change renderer shape project-wide',
+};
+export function mapContentPlaneOutboxKindToPreviewContentChangeOperation(kind) {
+    const operation = PREVIEW_CONTENT_PLANE_OUTBOX_KIND_TO_OPERATION[kind] ?? 'unknown';
+    const unknownReason = operation === 'unknown'
+        ? (PREVIEW_CONTENT_PLANE_OUTBOX_UNKNOWN_REASONS[kind] ?? 'unrecognized Content Plane outbox kind')
+        : undefined;
+    return unknownReason ? { operation, unknownReason } : { operation };
+}
+export function createPreviewFrameDependencySet(input) {
+    return {
+        type: 'storystick.preview.frame-dependency-set',
+        version: 1,
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        ...(input.readContext ? { readContext: input.readContext } : {}),
+        ...(input.receiptIds ? { receiptIds: [...new Set(input.receiptIds)] } : {}),
+        routeHash: input.routeHash,
+        codeVersion: input.codeVersion,
+        ...(input.variantId ? { variantId: input.variantId } : {}),
+        frameId: input.frameId,
+        renderId: input.renderId,
+        generation: input.generation,
+        ...(normalizeOptionalString(input.observationId)
+            ? { observationId: normalizeOptionalString(input.observationId) }
+            : {}),
+        ...(typeof input.renderWatermark === 'number' &&
+            Number.isFinite(input.renderWatermark)
+            ? { renderWatermark: input.renderWatermark }
+            : {}),
+        dependencies: dedupePreviewFrameDependencies(input.dependencies),
+    };
+}
+export function attachPreviewFrameDependencies(target, dependencies) {
+    if (!isRecord(target) && !Array.isArray(target))
+        return target;
+    const existing = getPreviewFrameDependencies(target);
+    const next = dedupePreviewFrameDependencies([
+        ...existing,
+        ...dependencies,
+    ]);
+    setPreviewReadDependencies(target, next);
+    return target;
+}
+export function getPreviewFrameDependencies(value) {
+    if (!isRecord(value) && !Array.isArray(value))
+        return [];
+    const dependencies = getPreviewReadDependencies(value);
+    return dedupePreviewFrameDependencies(dependencies.filter(isPreviewFrameDependency));
+}
+export function collectPreviewFrameDependencies(...roots) {
+    const dependencies = [];
+    const seen = new WeakSet();
+    const visit = (value) => {
+        if (!isRecord(value) && !Array.isArray(value))
+            return;
+        if (seen.has(value))
+            return;
+        seen.add(value);
+        dependencies.push(...getPreviewFrameDependencies(value));
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        for (const child of Object.values(value))
+            visit(child);
+    };
+    for (const root of roots)
+        visit(root);
+    return dedupePreviewFrameDependencies(dependencies);
+}
+export function createDocumentPreviewContentChange(input) {
+    return {
+        type: 'storystick.preview.content-change',
+        version: 1,
+        source: {
+            kind: 'document',
+            documentId: input.documentId,
+            operation: input.operation ?? 'update',
+            ...(normalizeOptionalString(input.storyType)
+                ? { storyType: normalizeOptionalString(input.storyType) }
+                : {}),
+        },
+    };
+}
+export function createTemplatePreviewContentChange(input) {
+    return {
+        type: 'storystick.preview.content-change',
+        version: 1,
+        source: {
+            kind: 'template',
+            templateId: input.templateId,
+            operation: input.operation ?? 'template-update',
+        },
+    };
+}
+export function createAssetPreviewContentChange(input) {
+    return {
+        type: 'storystick.preview.content-change',
+        version: 1,
+        source: {
+            kind: 'asset',
+            assetId: input.assetId,
+            operation: input.operation ?? 'update',
+        },
+    };
+}
+export function createStoryTypePreviewContentChange(input) {
+    return {
+        type: 'storystick.preview.content-change',
+        version: 1,
+        source: {
+            kind: 'storyType',
+            storyType: input.storyType,
+            operation: input.operation ?? 'update',
+        },
+    };
+}
+export function createVariantSwitchPreviewContentChange() {
+    return {
+        type: 'storystick.preview.content-change',
+        version: 1,
+        source: {
+            kind: 'session',
+            operation: 'variant-switch',
+        },
+    };
+}
+export function createProjectPreviewContentChange(operation = 'update') {
+    return {
+        type: 'storystick.preview.content-change',
+        version: 1,
+        source: {
+            kind: 'project',
+            operation,
+        },
+    };
+}
+export function createUnknownPreviewContentChange(operation = 'unknown') {
+    return {
+        type: 'storystick.preview.content-change',
+        version: 1,
+        source: {
+            kind: 'unknown',
+            operation,
+        },
+    };
+}
+export function createPreviewContentRefreshDecision(input) {
+    return {
+        type: 'storystick.preview.content-refresh-decision',
+        version: 1,
+        refresh: input.refresh,
+        affectedFrameIds: dedupeStrings(input.affectedFrameIds ?? []),
+        reason: input.reason,
+    };
+}
+export function dedupePreviewFrameDependencies(dependencies) {
+    const seen = new Set();
+    const normalized = [];
+    for (const dependency of dependencies) {
+        const next = normalizePreviewFrameDependency(dependency);
+        if (!next)
+            continue;
+        const key = previewFrameDependencyKey(next);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        normalized.push(next);
+    }
+    return normalized;
+}
+export function doesPreviewContentChangeAffectFrame(dependencySet, change) {
+    if (!dependencySet || dependencySet.dependencies.length === 0)
+        return true;
+    if (!change)
+        return true;
+    if (change.source.kind === 'unknown')
+        return true;
+    if (change.source.kind === 'session')
+        return true;
+    if (change.source.kind === 'project')
+        return true;
+    return dependencySet.dependencies.some((dependency) => doesPreviewContentChangeAffectDependency(dependency, change));
+}
+export function getAffectedPreviewFrameIds(dependencySets, change) {
+    return dedupeStrings(dependencySets
+        .filter((dependencySet) => doesPreviewContentChangeAffectFrame(dependencySet, change))
+        .map((dependencySet) => dependencySet.frameId));
+}
+export function doesPreviewContentChangeAffectDependency(dependency, change) {
+    if (change.source.kind === 'unknown')
+        return true;
+    if (change.source.kind === 'session')
+        return true;
+    if (change.source.kind === 'project')
+        return true;
+    if (change.source.kind === 'template') {
+        return dependency.kind === 'template'
+            ? dependency.templateId === change.source.templateId
+            : false;
+    }
+    if (change.source.kind === 'asset') {
+        return dependency.kind === 'asset'
+            ? dependency.assetId === change.source.assetId
+            : false;
+    }
+    if (change.source.kind === 'storyType') {
+        return dependency.kind === 'list' ||
+            dependency.kind === 'get-by-slug' ||
+            dependency.kind === 'get-by-pathname'
+            ? dependency.storyType === change.source.storyType
+            : dependency.kind === 'route-lookup'
+                ? (dependency.storyTypes ?? []).includes(change.source.storyType)
+                : dependency.kind === 'document'
+                    ? dependency.storyType === change.source.storyType
+                    : false;
+    }
+    const source = change.source;
+    switch (dependency.kind) {
+        case 'document':
+            return dependency.documentId === source.documentId;
+        case 'batch-get':
+            return dependency.documentIds.includes(source.documentId);
+        case 'list':
+            return storyTypesMayOverlap(dependency.storyType, source.storyType);
+        case 'get-by-slug':
+        case 'get-by-pathname':
+            return storyTypesMayOverlap(dependency.storyType, source.storyType);
+        case 'route-lookup':
+            return storyTypeListMayOverlap(dependency.storyTypes, source.storyType);
+        case 'asset':
+        case 'template':
+        case 'custom-read':
+            return false;
+    }
+}
+export function normalizePreviewFrameDependency(dependency) {
+    switch (dependency.kind) {
+        case 'document': {
+            const documentId = normalizeRequiredString(dependency.documentId);
+            if (!documentId)
+                return null;
+            const storyType = normalizeOptionalString(dependency.storyType);
+            const reason = normalizeOptionalString(dependency.reason);
+            return {
+                kind: 'document',
+                documentId,
+                ...(storyType ? { storyType } : {}),
+                ...(reason ? { reason: reason } : {}),
+            };
+        }
+        case 'asset': {
+            const assetId = normalizeRequiredString(dependency.assetId);
+            return assetId ? { kind: 'asset', assetId } : null;
+        }
+        case 'route-lookup': {
+            const pathname = normalizeRequiredString(dependency.pathname);
+            if (!pathname)
+                return null;
+            const storyTypes = dedupeStrings(dependency.storyTypes ?? []);
+            return {
+                kind: 'route-lookup',
+                pathname,
+                ...(storyTypes.length > 0 ? { storyTypes } : {}),
+            };
+        }
+        case 'list': {
+            const storyType = normalizeRequiredString(dependency.storyType);
+            if (!storyType)
+                return null;
+            return {
+                kind: 'list',
+                storyType,
+                ...(dependency.where !== undefined ? { where: dependency.where } : {}),
+                ...(dependency.orderBy ? { orderBy: dependency.orderBy } : {}),
+                ...(typeof dependency.limit === 'number'
+                    ? { limit: dependency.limit }
+                    : {}),
+            };
+        }
+        case 'get-by-slug': {
+            const storyType = normalizeRequiredString(dependency.storyType);
+            const slug = normalizeRequiredString(dependency.slug);
+            if (!storyType || !slug)
+                return null;
+            return { kind: 'get-by-slug', storyType, slug };
+        }
+        case 'get-by-pathname': {
+            const storyType = normalizeRequiredString(dependency.storyType);
+            const pathname = normalizeRequiredString(dependency.pathname);
+            if (!storyType || !pathname)
+                return null;
+            return { kind: 'get-by-pathname', storyType, pathname };
+        }
+        case 'batch-get': {
+            const documentIds = dedupeStrings(dependency.documentIds);
+            if (documentIds.length === 0)
+                return null;
+            return { kind: 'batch-get', documentIds };
+        }
+        case 'template': {
+            const templateId = normalizeRequiredString(dependency.templateId);
+            if (!templateId)
+                return null;
+            return { kind: 'template', templateId };
+        }
+        case 'custom-read': {
+            const key = normalizeRequiredString(dependency.key);
+            if (!key)
+                return null;
+            return { kind: 'custom-read', key };
+        }
+    }
+}
+export function isPreviewFrameDependencySet(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.type !== 'storystick.preview.frame-dependency-set')
+        return false;
+    if (value.version !== 1)
+        return false;
+    if (value.sessionId !== undefined && typeof value.sessionId !== 'string')
+        return false;
+    if (value.readContext !== undefined && !isPreviewReadContext(value.readContext))
+        return false;
+    if (!value.sessionId && !value.readContext)
+        return false;
+    if (value.receiptIds !== undefined && (!Array.isArray(value.receiptIds) ||
+        value.receiptIds.length > 64 || !value.receiptIds.every((id) => typeof id === 'string' && /^pqr_[a-f0-9]{64}$/.test(id))))
+        return false;
+    if (typeof value.routeHash !== 'string')
+        return false;
+    if (typeof value.codeVersion !== 'string')
+        return false;
+    if (typeof value.frameId !== 'string')
+        return false;
+    if (typeof value.renderId !== 'string')
+        return false;
+    if (typeof value.generation !== 'number')
+        return false;
+    if (value.observationId !== undefined &&
+        typeof value.observationId !== 'string')
+        return false;
+    if (value.renderWatermark !== undefined &&
+        (typeof value.renderWatermark !== 'number' ||
+            !Number.isFinite(value.renderWatermark)))
+        return false;
+    if (!Array.isArray(value.dependencies))
+        return false;
+    return value.dependencies.every(isPreviewFrameDependency);
+}
+export function isPreviewContentChangeIdentity(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.type !== 'storystick.preview.content-change')
+        return false;
+    if (value.version !== 1)
+        return false;
+    if (!isRecord(value.source))
+        return false;
+    switch (value.source.kind) {
+        case 'document':
+            return (typeof value.source.documentId === 'string' &&
+                isPreviewContentChangeOperation(value.source.operation));
+        case 'storyType':
+            return (typeof value.source.storyType === 'string' &&
+                isPreviewContentChangeOperation(value.source.operation));
+        case 'asset':
+            return (typeof value.source.assetId === 'string' &&
+                isPreviewContentChangeOperation(value.source.operation));
+        case 'template':
+            return (typeof value.source.templateId === 'string' &&
+                isPreviewContentChangeOperation(value.source.operation));
+        case 'session':
+            return isPreviewContentChangeOperation(value.source.operation);
+        case 'project':
+            return isPreviewContentChangeOperation(value.source.operation);
+        case 'unknown':
+            return isPreviewContentChangeOperation(value.source.operation);
+        default:
+            return false;
+    }
+}
+export function isPreviewContentRefreshDecision(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.type !== 'storystick.preview.content-refresh-decision')
+        return false;
+    if (value.version !== 1)
+        return false;
+    if (typeof value.refresh !== 'boolean')
+        return false;
+    if (!Array.isArray(value.affectedFrameIds))
+        return false;
+    if (!value.affectedFrameIds.every((id) => typeof id === 'string'))
+        return false;
+    if (typeof value.reason !== 'string')
+        return false;
+    return true;
+}
+function isPreviewFrameDependency(value) {
+    if (!isRecord(value) || typeof value.kind !== 'string')
+        return false;
+    switch (value.kind) {
+        case 'document':
+            return typeof value.documentId === 'string';
+        case 'asset':
+            return typeof value.assetId === 'string';
+        case 'route-lookup':
+            return typeof value.pathname === 'string';
+        case 'list':
+            return typeof value.storyType === 'string';
+        case 'get-by-slug':
+            return (typeof value.storyType === 'string' && typeof value.slug === 'string');
+        case 'get-by-pathname':
+            return (typeof value.storyType === 'string' && typeof value.pathname === 'string');
+        case 'batch-get':
+            return (Array.isArray(value.documentIds) &&
+                value.documentIds.every((id) => typeof id === 'string'));
+        case 'template':
+            return typeof value.templateId === 'string';
+        case 'custom-read':
+            return typeof value.key === 'string';
+        default:
+            return false;
+    }
+}
+function previewFrameDependencyKey(dependency) {
+    return stableStringify(dependency);
+}
+function storyTypesMayOverlap(dependencyStoryType, changeStoryType) {
+    return !changeStoryType || dependencyStoryType === changeStoryType;
+}
+function storyTypeListMayOverlap(dependencyStoryTypes, changeStoryType) {
+    if (!dependencyStoryTypes || dependencyStoryTypes.length === 0)
+        return true;
+    if (!changeStoryType)
+        return true;
+    return dependencyStoryTypes.includes(changeStoryType);
+}
+function isPreviewContentChangeOperation(value) {
+    return (typeof value === 'string' &&
+        PREVIEW_CONTENT_CHANGE_OPERATION_SET.has(value));
+}
+function dedupeStrings(values) {
+    return Array.from(new Set(values
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0))).sort();
+}
+function normalizeRequiredString(value) {
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : null;
+}
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+    }
+    if (isRecord(value)) {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/provenance/index.d.ts

@@ -0,0 +1,26 @@
+export * from './anchor-map.js';
+export * from './carrier-plan.js';
+export * from './coded-text.js';
+export * from './read-carrier.js';
+export * from './direct-edit-locator.js';
+export * from './editable-leaf.js';
+export * from './frame-dependencies.js';
+export * from './local-events.js';
+export * from './markers.js';
+export * from './multi-frame-anchor-map.js';
+export * from './normalize.js';
+export * from './overlay-projection.js';
+export * from './owner-map.js';
+export * from './recorder.js';
+export * from './runtime-script.js';
+export * from './richtext-slice-embed-address.js';
+export * from './sidecar.js';
+export * from './sidecar-store.js';
+export * from './source-map-materializer.js';
+export * from './source-identity.js';
+export * from './transformed-output-gate.js';
+export * from './types.js';
+export { enumerateSchemaCoverageOccurrences, enumerateSchemaFieldDeclarations, resolveSchemaField, splitFieldPath, type ResolvedSchemaField, type SchemaCoverageDocument, type SchemaCoverageOccurrence, type SchemaFieldDeclaration, type SchemaStoriesInput, } from '../runtime/resolve-schema-field.js';
+export * from './editor-target.js';
+export * from './reveal-contract.js';
+export * from './overlay-focus-echo.js';

package/dist/provenance/index.js

@@ -0,0 +1,26 @@
+export * from './anchor-map.js';
+export * from './carrier-plan.js';
+export * from './coded-text.js';
+export * from './read-carrier.js';
+export * from './direct-edit-locator.js';
+export * from './editable-leaf.js';
+export * from './frame-dependencies.js';
+export * from './local-events.js';
+export * from './markers.js';
+export * from './multi-frame-anchor-map.js';
+export * from './normalize.js';
+export * from './overlay-projection.js';
+export * from './owner-map.js';
+export * from './recorder.js';
+export * from './runtime-script.js';
+export * from './richtext-slice-embed-address.js';
+export * from './sidecar.js';
+export * from './sidecar-store.js';
+export * from './source-map-materializer.js';
+export * from './source-identity.js';
+export * from './transformed-output-gate.js';
+export * from './types.js';
+export { enumerateSchemaCoverageOccurrences, enumerateSchemaFieldDeclarations, resolveSchemaField, splitFieldPath, } from '../runtime/resolve-schema-field.js';
+export * from './editor-target.js';
+export * from './reveal-contract.js';
+export * from './overlay-focus-echo.js';

package/dist/provenance/local-events.d.ts

@@ -0,0 +1 @@
+export declare const PREVIEW_PROVENANCE_ANCHOR_MAP_EVENT = "storystick.preview.provenance-anchor-map-local";

package/dist/provenance/local-events.js

@@ -0,0 +1 @@
+export const PREVIEW_PROVENANCE_ANCHOR_MAP_EVENT = 'storystick.preview.provenance-anchor-map-local';

package/dist/provenance/markers.d.ts

@@ -0,0 +1,21 @@
+import type { PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import type { AuthoritativeSet, ProvenanceFrame } from './types.js';
+export interface MarkerInput {
+    readonly sessionId?: string;
+    readonly readContext?: PreviewReadContext;
+    readonly routeHash: string;
+    readonly codeVersion: string;
+    readonly variantId?: string | null;
+    readonly renderId: string;
+    readonly sourceSetId: string;
+}
+export interface FrameValidationOk {
+    readonly ok: true;
+}
+export interface FrameValidationError {
+    readonly ok: false;
+    readonly reason: 'route-mismatch' | 'code-version-mismatch' | 'variant-mismatch' | 'marker-source-missing' | 'source-not-authoritative' | 'source-variant-mismatch' | 'source-path-missing' | 'composite-no-primary';
+}
+export type FrameValidationResult = FrameValidationOk | FrameValidationError;
+export declare function createDirectEditMarkerId(input: MarkerInput): Promise<string>;
+export declare function validateProvenanceFrame(frame: ProvenanceFrame, authoritativeSet: AuthoritativeSet): FrameValidationResult;