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

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

@@ -0,0 +1,212 @@
+import { type PreviewReadContext } from '@storystick/types/preview-query-targeting';
+export type PreviewJsonPrimitive = string | number | boolean | null;
+export type PreviewJsonValue = PreviewJsonPrimitive | readonly PreviewJsonValue[] | {
+    readonly [key: string]: PreviewJsonValue;
+};
+export type PreviewDependencyReason = 'rendered-document' | 'route-document' | 'scope-document' | 'context-document' | 'referenced-document' | 'model-document' | 'manual';
+export type PreviewFrameDependency = {
+    readonly kind: 'document';
+    readonly documentId: string;
+    readonly storyType?: string;
+    readonly reason?: PreviewDependencyReason;
+} | {
+    readonly kind: 'asset';
+    readonly assetId: string;
+} | {
+    readonly kind: 'route-lookup';
+    readonly pathname: string;
+    readonly storyTypes?: readonly string[];
+} | {
+    readonly kind: 'list';
+    readonly storyType: string;
+    readonly where?: PreviewJsonValue;
+    readonly orderBy?: {
+        readonly field: string;
+        readonly direction: 'asc' | 'desc';
+    };
+    readonly limit?: number;
+} | {
+    readonly kind: 'get-by-slug';
+    readonly storyType: string;
+    readonly slug: string;
+} | {
+    readonly kind: 'get-by-pathname';
+    readonly storyType: string;
+    readonly pathname: string;
+} | {
+    readonly kind: 'batch-get';
+    readonly documentIds: readonly string[];
+} | {
+    readonly kind: 'template';
+    readonly templateId: string;
+} | {
+    readonly kind: 'custom-read';
+    readonly key: string;
+};
+export interface PreviewFrameDependencySet {
+    readonly type: 'storystick.preview.frame-dependency-set';
+    readonly version: 1;
+    readonly sessionId?: string;
+    readonly readContext?: PreviewReadContext;
+    readonly receiptIds?: readonly string[];
+    readonly routeHash: string;
+    readonly codeVersion: string;
+    readonly variantId?: string;
+    readonly frameId: string;
+    readonly renderId: string;
+    readonly generation: number;
+    /**
+     * F3 render-read identity. Optional only for frames produced by an older
+     * codeVersion; current writers always carry both fields.
+     */
+    readonly observationId?: string;
+    readonly renderWatermark?: number;
+    readonly dependencies: readonly PreviewFrameDependency[];
+}
+export declare const PREVIEW_CONTENT_CHANGE_OPERATIONS: readonly ["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"];
+export type PreviewContentChangeOperation = (typeof PREVIEW_CONTENT_CHANGE_OPERATIONS)[number];
+export declare const PREVIEW_CONTENT_PLANE_OUTBOX_KIND_TO_OPERATION: {
+    readonly 'document.create': "create";
+    readonly 'document.update': "update";
+    readonly 'document.delete': "delete";
+    readonly 'document.publish': "publish";
+    readonly 'document.unpublish': "unpublish";
+    readonly 'document.rollback': "rollback";
+    readonly 'document.restoreDraft': "restore-draft";
+    readonly 'document.archive': "archive";
+    readonly 'document.unarchive': "unarchive";
+    readonly 'document.shapeMigration': "shape-migration";
+    readonly 'snapshot.shapeMigration': "snapshot-shape-migration";
+    readonly 'asset.create': "update";
+    readonly 'asset.update': "update";
+    readonly 'asset.archive': "archive";
+    readonly 'template.create': "template-create";
+    readonly 'template.update': "template-update";
+    readonly 'template.archive': "template-archive";
+    readonly 'template.delete': "template-delete";
+    readonly 'template.default.update': "template-update";
+    readonly 'release.create': "unknown";
+    readonly 'release.update': "unknown";
+    readonly 'release.schedule': "unknown";
+    readonly 'release.unschedule': "unknown";
+    readonly 'release.archive': "unknown";
+    readonly 'locale.settings.update': "unknown";
+    readonly 'variant.create': "variant-create";
+    readonly 'variant.update': "variant-update";
+    readonly 'variant.discard': "variant-discard";
+    readonly 'variant.promote': "variant-promote";
+    readonly 'project.wipe': "unknown";
+    readonly 'refs.backfill': "unknown";
+    readonly 'richtextEmbeds.migrate': "unknown";
+    readonly 'contentShape.epoch': "unknown";
+    readonly 'schema.push': "unknown";
+    readonly 'schema.generation.project': "unknown";
+};
+export type PreviewContentPlaneOutboxKind = keyof typeof PREVIEW_CONTENT_PLANE_OUTBOX_KIND_TO_OPERATION;
+export declare const PREVIEW_CONTENT_PLANE_OUTBOX_UNKNOWN_REASONS: {
+    readonly 'release.create': "release mutations are not preview-rendered document/template writes";
+    readonly 'release.update': "release mutations are not preview-rendered document/template writes";
+    readonly 'release.schedule': "release scheduling has no route-specific preview dependency identity";
+    readonly 'release.unschedule': "release scheduling has no route-specific preview dependency identity";
+    readonly 'release.archive': "release mutations are not preview-rendered document/template writes";
+    readonly 'locale.settings.update': "locale settings can change fallback/read semantics project-wide";
+    readonly 'project.wipe': "project wipe is destructive and must refresh fail-open if observed";
+    readonly 'refs.backfill': "backfills do not carry a user mutation target identity";
+    readonly 'richtextEmbeds.migrate': "embed extraction can change every rendered content family project-wide";
+    readonly 'contentShape.epoch': "an epoch switch changes project-wide content composition semantics";
+    readonly 'schema.push': "schema pushes can change renderer shape outside document identity";
+    readonly 'schema.generation.project': "schema-generation projection can change renderer shape project-wide";
+};
+export declare function mapContentPlaneOutboxKindToPreviewContentChangeOperation(kind: string): {
+    readonly operation: PreviewContentChangeOperation;
+    readonly unknownReason?: string;
+};
+export type PreviewContentChangeSource = {
+    readonly kind: 'document';
+    readonly documentId: string;
+    readonly storyType?: string;
+    readonly operation: PreviewContentChangeOperation;
+} | {
+    readonly kind: 'asset';
+    readonly assetId: string;
+    readonly operation: PreviewContentChangeOperation;
+} | {
+    readonly kind: 'template';
+    readonly templateId: string;
+    readonly operation: PreviewContentChangeOperation;
+} | {
+    readonly kind: 'storyType';
+    readonly storyType: string;
+    readonly operation: PreviewContentChangeOperation;
+} | {
+    readonly kind: 'session';
+    readonly operation: PreviewContentChangeOperation;
+} | {
+    readonly kind: 'project';
+    readonly operation: PreviewContentChangeOperation;
+} | {
+    readonly kind: 'unknown';
+    readonly operation: PreviewContentChangeOperation;
+};
+export interface PreviewContentChangeIdentity {
+    readonly type: 'storystick.preview.content-change';
+    readonly version: 1;
+    readonly source: PreviewContentChangeSource;
+}
+export interface PreviewContentRefreshDecision {
+    readonly type: 'storystick.preview.content-refresh-decision';
+    readonly version: 1;
+    readonly refresh: boolean;
+    readonly affectedFrameIds: readonly string[];
+    readonly reason: 'dependency-match' | 'unrelated-change' | 'no-dependency-set' | 'unknown-change' | 'legacy-refresh';
+}
+export declare function createPreviewFrameDependencySet(input: {
+    readonly sessionId?: string;
+    readonly readContext?: PreviewReadContext;
+    readonly receiptIds?: readonly string[];
+    readonly routeHash: string;
+    readonly codeVersion: string;
+    readonly variantId?: string | null;
+    readonly frameId: string;
+    readonly renderId: string;
+    readonly generation: number;
+    readonly observationId?: string;
+    readonly renderWatermark?: number;
+    readonly dependencies: readonly PreviewFrameDependency[];
+}): PreviewFrameDependencySet;
+export declare function attachPreviewFrameDependencies<T>(target: T, dependencies: readonly PreviewFrameDependency[]): T;
+export declare function getPreviewFrameDependencies(value: unknown): readonly PreviewFrameDependency[];
+export declare function collectPreviewFrameDependencies(...roots: readonly unknown[]): readonly PreviewFrameDependency[];
+export declare function createDocumentPreviewContentChange(input: {
+    readonly documentId: string;
+    readonly storyType?: string;
+    readonly operation?: PreviewContentChangeOperation;
+}): PreviewContentChangeIdentity;
+export declare function createTemplatePreviewContentChange(input: {
+    readonly templateId: string;
+    readonly operation?: PreviewContentChangeOperation;
+}): PreviewContentChangeIdentity;
+export declare function createAssetPreviewContentChange(input: {
+    readonly assetId: string;
+    readonly operation?: PreviewContentChangeOperation;
+}): PreviewContentChangeIdentity;
+export declare function createStoryTypePreviewContentChange(input: {
+    readonly storyType: string;
+    readonly operation?: PreviewContentChangeOperation;
+}): PreviewContentChangeIdentity;
+export declare function createVariantSwitchPreviewContentChange(): PreviewContentChangeIdentity;
+export declare function createProjectPreviewContentChange(operation?: PreviewContentChangeOperation): PreviewContentChangeIdentity;
+export declare function createUnknownPreviewContentChange(operation?: PreviewContentChangeOperation): PreviewContentChangeIdentity;
+export declare function createPreviewContentRefreshDecision(input: {
+    readonly refresh: boolean;
+    readonly affectedFrameIds?: readonly string[];
+    readonly reason: PreviewContentRefreshDecision['reason'];
+}): PreviewContentRefreshDecision;
+export declare function dedupePreviewFrameDependencies(dependencies: readonly PreviewFrameDependency[]): readonly PreviewFrameDependency[];
+export declare function doesPreviewContentChangeAffectFrame(dependencySet: PreviewFrameDependencySet | null | undefined, change: PreviewContentChangeIdentity | null | undefined): boolean;
+export declare function getAffectedPreviewFrameIds(dependencySets: readonly PreviewFrameDependencySet[], change: PreviewContentChangeIdentity | null | undefined): readonly string[];
+export declare function doesPreviewContentChangeAffectDependency(dependency: PreviewFrameDependency, change: PreviewContentChangeIdentity): boolean;
+export declare function normalizePreviewFrameDependency(dependency: PreviewFrameDependency): PreviewFrameDependency | null;
+export declare function isPreviewFrameDependencySet(value: unknown): value is PreviewFrameDependencySet;
+export declare function isPreviewContentChangeIdentity(value: unknown): value is PreviewContentChangeIdentity;
+export declare function isPreviewContentRefreshDecision(value: unknown): value is PreviewContentRefreshDecision;