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

package/dist/runtime/render-mode-state.js

@@ -0,0 +1,76 @@
+/**
+ * Module-level mutable state for the current render mode inside the
+ * developer's iframe. Read by framework SDKs to decide whether to
+ * debounce Convex subscriptions (Navigation mode = 100ms debounce
+ * per ADR-059 §Technical commitments + spec/preview-system.md
+ * §"Convex subscription debounced 100ms in Navigation mode").
+ *
+ * The snapshot reporter writes here when a `render-mode` postMessage
+ * arrives. Framework SDKs read here in their query hook. Subscribers
+ * can register a callback to be notified on changes — useful for
+ * triggering re-renders without polling.
+ *
+ * This intentionally lives at module scope (not React Context) for
+ * three reasons:
+ *
+ *   1. The state is iframe-global (one site rendered in one iframe).
+ *      Two providers in the same iframe with different render modes
+ *      would be a bug, not a feature.
+ *
+ *   2. The state is set by the postMessage runtime (vanilla JS,
+ *      no React tree). A Context API requires a Provider mounted
+ *      above every consumer; module state is observed regardless.
+ *
+ *   3. Tests can reset it deterministically via `_resetForTests()`.
+ *      Cross-test pollution is the only real risk and it's explicit.
+ */
+let current = 'device';
+const subscribers = new Set();
+export function getRenderMode() {
+    return current;
+}
+export function setRenderMode(mode) {
+    if (mode === current)
+        return;
+    current = mode;
+    subscribers.forEach((sub) => {
+        try {
+            sub(mode);
+        }
+        catch {
+            // Subscriber errors must not break the dispatch chain.
+        }
+    });
+}
+/**
+ * Subscribe to render-mode changes. Returns an unsubscribe function.
+ * Subscribers are called synchronously after `setRenderMode`. They
+ * MUST not call `setRenderMode` from within their handler — that
+ * would re-enter the dispatch.
+ */
+export function subscribeRenderMode(callback) {
+    subscribers.add(callback);
+    return () => {
+        subscribers.delete(callback);
+    };
+}
+/**
+ * Returns the debounce window (ms) appropriate for the current
+ * render mode. Navigation mode = 100ms; Device mode = 0 (no debounce).
+ *
+ * Per ADR-059 §Technical commitments: "the editor reads structure
+ * (section order, slice type, slice count), not typography. Typo-
+ * graphic updates do not need to propagate to the Navigation
+ * miniature within one frame."
+ */
+export function debounceForRenderMode(mode = current) {
+    return mode === 'navigation' ? 100 : 0;
+}
+/**
+ * Test-only reset. Not exported from index.ts to keep the public
+ * API small.
+ */
+export function _resetForTests() {
+    current = 'device';
+    subscribers.clear();
+}

package/dist/runtime/request-id.d.ts

@@ -0,0 +1,4 @@
+/** Opaque 128-bit correlation id for Preview commands, handoffs and envelopes.
+ * getRandomValues also works on HTTP customer origins, unlike randomUUID.
+ */
+export declare function createPreviewRequestId(source?: Pick<Crypto, 'getRandomValues'>): string;

package/dist/runtime/request-id.js

@@ -0,0 +1,8 @@
+/** Opaque 128-bit correlation id for Preview commands, handoffs and envelopes.
+ * getRandomValues also works on HTTP customer origins, unlike randomUUID.
+ */
+export function createPreviewRequestId(source = globalThis.crypto) {
+    const bytes = new Uint8Array(16);
+    source.getRandomValues(bytes);
+    return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+}

package/dist/runtime/resolve-schema-field.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Conserved deliberately despite having zero importers today: this walker
+ * is the source of the coverage denominator (schema fields that should be
+ * annotated). Do not remove it as dead resolver machinery.
+ *
+ * ADR-131 §D6.1 — walk a serialised schema row to a leaf field shape
+ * the resolver uses.
+ *
+ * The schema returned by `/api/q/schemas/current` has the shape
+ * documented in `@storystick/types` `SerializedSchema` :
+ *   - `stories: Record<storyId, SerializedStory>`
+ *   - Each `SerializedStory` has `fields: Record<fieldName, SerializedField>`
+ *
+ * The resolver's `fieldId` argument is a dotted/indexed path emitted
+ * by the snapshot-assembly traversal (e.g. `"headline"`,
+ * `"cards[0].title"`, `"sections[1].cta.label"`). This helper walks
+ * the path against the right story (resolved from `storyTypeId`),
+ * descending into sub-stories on each hop.
+ *
+ * Returns `null` when :
+ *   - the schema row is missing/malformed ;
+ *   - the storyTypeId doesn't exist ;
+ *   - any path segment doesn't resolve (renamed field, missing array
+ *     hop, etc.).
+ */
+import type { RawSchemaRow } from '@storystick/client/adapter';
+export interface ResolvedSchemaField {
+    /** Final leaf field shape (subset of `SerializedField`). */
+    type: string;
+    /** Whether the field is an array (repeater). */
+    isArray: boolean;
+    /** Optional enum values — useful for downstream value→DOM matchers. */
+    enumValues?: readonly string[];
+}
+export interface SchemaFieldDeclaration {
+    /** Stable inside one serialized schema. Inherited fields point to their source declaration. */
+    readonly id: string;
+    readonly storyTypeId: string;
+    readonly field: string;
+    readonly type: string;
+    readonly isArray: boolean;
+}
+export interface SchemaCoverageDocument {
+    readonly documentId: string;
+    readonly storyType: string;
+    readonly fields: Readonly<Record<string, unknown>>;
+}
+export interface SchemaStoriesInput {
+    readonly stories: unknown;
+}
+export interface SchemaCoverageOccurrence extends SchemaFieldDeclaration {
+    /** Concrete identity used only inside Studio; never crosses the iframe boundary. */
+    readonly documentId: string;
+    readonly path: string;
+}
+/**
+ * Walk the schema for `storyTypeId` against the dotted/indexed
+ * `fieldPath`. Returns the leaf field shape or null on any failure.
+ *
+ * Path grammar :
+ *   - dotted segments descend into sub-stories : `foo.bar`
+ *   - bracketed indices descend into array items : `cards[0]` (the
+ *     index is structurally meaningful in the path, not a value —
+ *     `cards[0]` and `cards[3]` share the same leaf schema).
+ */
+export declare function resolveSchemaField(schema: RawSchemaRow, storyTypeId: string, fieldPath: string): ResolvedSchemaField | null;
+/**
+ * Enumerate the declaration catalog carried by a serialized schema.
+ *
+ * `variations` and `computed` are deliberately absent because this function
+ * reads only each story's materialized `fields`. Fragment/extends fields are
+ * materialized into every consumer by the serializer, so their `origin` is
+ * used as the declaration owner to avoid multiplying one source declaration.
+ */
+export declare function enumerateSchemaFieldDeclarations(schema: SchemaStoriesInput): SchemaFieldDeclaration[];
+/**
+ * Enumerate schema-classified values that are actually present in the
+ * authoritative documents for one route. Missing optional fields are not a
+ * demand; falsy values and empty arrays are. Nested custom field stories and
+ * concrete `_type` slice instances are walked without expanding SDK primitive
+ * objects such as image/link/richtext.
+ */
+export declare function enumerateSchemaCoverageOccurrences(schema: SchemaStoriesInput, documents: readonly SchemaCoverageDocument[]): SchemaCoverageOccurrence[];
+type PathSegment = {
+    kind: 'name';
+    name: string;
+} | {
+    kind: 'index';
+    idx: number;
+};
+/**
+ * Split `cards[0].cta.label` into
+ * `[{name:'cards'},{index:0},{name:'cta'},{name:'label'}]`.
+ *
+ * Returns null on malformed input (e.g. `cards[]`, `cards[abc]`,
+ * stray `[`).
+ */
+export declare function splitFieldPath(path: string): PathSegment[] | null;
+export {};

package/dist/runtime/resolve-schema-field.js

@@ -0,0 +1,356 @@
+/**
+ * Conserved deliberately despite having zero importers today: this walker
+ * is the source of the coverage denominator (schema fields that should be
+ * annotated). Do not remove it as dead resolver machinery.
+ *
+ * ADR-131 §D6.1 — walk a serialised schema row to a leaf field shape
+ * the resolver uses.
+ *
+ * The schema returned by `/api/q/schemas/current` has the shape
+ * documented in `@storystick/types` `SerializedSchema` :
+ *   - `stories: Record<storyId, SerializedStory>`
+ *   - Each `SerializedStory` has `fields: Record<fieldName, SerializedField>`
+ *
+ * The resolver's `fieldId` argument is a dotted/indexed path emitted
+ * by the snapshot-assembly traversal (e.g. `"headline"`,
+ * `"cards[0].title"`, `"sections[1].cta.label"`). This helper walks
+ * the path against the right story (resolved from `storyTypeId`),
+ * descending into sub-stories on each hop.
+ *
+ * Returns `null` when :
+ *   - the schema row is missing/malformed ;
+ *   - the storyTypeId doesn't exist ;
+ *   - any path segment doesn't resolve (renamed field, missing array
+ *     hop, etc.).
+ */
+import { effectiveSchemaFieldType } from '@storystick/types';
+const BUILTIN_SCHEMA_FIELD_TYPES = new Set([
+    'boolean',
+    'color',
+    'date',
+    'datetime',
+    'enum',
+    'file',
+    'geopoint',
+    'image',
+    'link',
+    'markdown',
+    'number',
+    'pathname',
+    'portableText',
+    'reference',
+    'relation',
+    'richtext',
+    'sliceZone',
+    'slug',
+    'text',
+    'video',
+]);
+/**
+ * Walk the schema for `storyTypeId` against the dotted/indexed
+ * `fieldPath`. Returns the leaf field shape or null on any failure.
+ *
+ * Path grammar :
+ *   - dotted segments descend into sub-stories : `foo.bar`
+ *   - bracketed indices descend into array items : `cards[0]` (the
+ *     index is structurally meaningful in the path, not a value —
+ *     `cards[0]` and `cards[3]` share the same leaf schema).
+ */
+export function resolveSchemaField(schema, storyTypeId, fieldPath) {
+    const stories = readStories(schema);
+    if (stories === null)
+        return null;
+    const story = stories[storyTypeId];
+    if (story === undefined || story.fields === undefined)
+        return null;
+    const segments = splitFieldPath(fieldPath);
+    if (segments === null || segments.length === 0)
+        return null;
+    let currentFields = story.fields;
+    let currentField = null;
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        if (segment.kind === 'index') {
+            // Array index — current field must be an array. Descend into
+            // the resolved type's fields.
+            if (currentField === null || currentField.array !== true)
+                return null;
+            const typeId = currentField.resolvedTypeId;
+            if (typeof typeId !== 'string')
+                return null;
+            const subStory = stories[typeId];
+            if (subStory === undefined || subStory.fields === undefined)
+                return null;
+            currentFields = subStory.fields;
+            currentField = null;
+            continue;
+        }
+        // Named segment — look up the field on the current story.
+        const field = currentFields[segment.name];
+        if (field === undefined)
+            return null;
+        currentField = field;
+        // If there's another segment after this one (dotted descent), we
+        // need to walk into the sub-story. Skip when the next segment is
+        // an array index — that path is handled by the index case above.
+        const next = segments[i + 1];
+        if (next !== undefined && next.kind === 'name') {
+            // Dotted descent into a sub-object/sub-story.
+            if (field.primitiveBase !== undefined)
+                return null;
+            const typeId = field.resolvedTypeId;
+            if (typeof typeId !== 'string')
+                return null;
+            const subStory = stories[typeId];
+            if (subStory === undefined || subStory.fields === undefined)
+                return null;
+            currentFields = subStory.fields;
+            currentField = null;
+        }
+    }
+    if (currentField === null)
+        return null;
+    return {
+        type: effectiveSchemaFieldType(currentField) ??
+            pickFieldType(currentField.type),
+        isArray: currentField.array === true,
+        enumValues: currentField.enumValues,
+    };
+}
+/**
+ * Enumerate the declaration catalog carried by a serialized schema.
+ *
+ * `variations` and `computed` are deliberately absent because this function
+ * reads only each story's materialized `fields`. Fragment/extends fields are
+ * materialized into every consumer by the serializer, so their `origin` is
+ * used as the declaration owner to avoid multiplying one source declaration.
+ */
+export function enumerateSchemaFieldDeclarations(schema) {
+    const stories = readStories(schema);
+    if (stories === null)
+        return [];
+    const byId = new Map();
+    for (const [storyTypeId, story] of Object.entries(stories)) {
+        for (const [field, shape] of Object.entries(story.fields ?? {})) {
+            const declaration = schemaFieldDeclaration(storyTypeId, field, shape);
+            if (declaration.type.length === 0 || byId.has(declaration.id))
+                continue;
+            byId.set(declaration.id, declaration);
+        }
+    }
+    return [...byId.values()].sort((left, right) => left.id.localeCompare(right.id));
+}
+/**
+ * Enumerate schema-classified values that are actually present in the
+ * authoritative documents for one route. Missing optional fields are not a
+ * demand; falsy values and empty arrays are. Nested custom field stories and
+ * concrete `_type` slice instances are walked without expanding SDK primitive
+ * objects such as image/link/richtext.
+ */
+export function enumerateSchemaCoverageOccurrences(schema, documents) {
+    const stories = readStories(schema);
+    if (stories === null)
+        return [];
+    const occurrences = [];
+    for (const document of documents) {
+        if (document.documentId.trim().length === 0 ||
+            document.storyType.trim().length === 0 ||
+            !isRecord(document.fields)) {
+            continue;
+        }
+        visitSchemaStoryValue({
+            stories,
+            storyTypeId: document.storyType,
+            value: document.fields,
+            documentId: document.documentId,
+            pathPrefix: '',
+            occurrences,
+            depth: 0,
+        });
+    }
+    return occurrences.sort((left, right) => `${left.documentId}:${left.path}:${left.id}`.localeCompare(`${right.documentId}:${right.path}:${right.id}`));
+}
+function visitSchemaStoryValue(input) {
+    // JSON-shaped content cannot be cyclic, but a depth cap keeps malformed
+    // inputs fail-closed instead of turning coverage into unbounded work.
+    if (input.depth > 64)
+        return;
+    const story = input.stories[input.storyTypeId];
+    if (story?.fields === undefined)
+        return;
+    for (const [field, shape] of Object.entries(story.fields)) {
+        if (!Object.prototype.hasOwnProperty.call(input.value, field))
+            continue;
+        const fieldValue = input.value[field];
+        const fieldPath = joinCoveragePath(input.pathPrefix, field);
+        const declaration = schemaFieldDeclaration(input.storyTypeId, field, shape);
+        if (declaration.type.length === 0)
+            continue;
+        if (shape.array === true && Array.isArray(fieldValue)) {
+            if (fieldValue.length === 0) {
+                input.occurrences.push({
+                    ...declaration,
+                    documentId: input.documentId,
+                    path: fieldPath,
+                });
+                continue;
+            }
+            for (let index = 0; index < fieldValue.length; index++) {
+                const item = fieldValue[index];
+                const itemPath = `${fieldPath}[${index}]`;
+                input.occurrences.push({
+                    ...declaration,
+                    documentId: input.documentId,
+                    path: itemPath,
+                });
+                visitNestedSchemaValue({
+                    ...input,
+                    fieldShape: shape,
+                    value: item,
+                    pathPrefix: itemPath,
+                    depth: input.depth + 1,
+                });
+            }
+            continue;
+        }
+        input.occurrences.push({
+            ...declaration,
+            documentId: input.documentId,
+            path: fieldPath,
+        });
+        visitNestedSchemaValue({
+            ...input,
+            fieldShape: shape,
+            value: fieldValue,
+            pathPrefix: fieldPath,
+            depth: input.depth + 1,
+        });
+    }
+}
+function visitNestedSchemaValue(input) {
+    if (!isRecord(input.value))
+        return;
+    const nestedStoryTypeId = nestedStoryTypeForValue(input.stories, input.fieldShape, input.value);
+    if (nestedStoryTypeId === null)
+        return;
+    visitSchemaStoryValue({
+        stories: input.stories,
+        storyTypeId: nestedStoryTypeId,
+        value: input.value,
+        documentId: input.documentId,
+        pathPrefix: input.pathPrefix,
+        occurrences: input.occurrences,
+        depth: input.depth,
+    });
+}
+function nestedStoryTypeForValue(stories, field, value) {
+    const fieldType = effectiveSchemaFieldType(field) ?? pickFieldType(field.type);
+    if (fieldType === 'sliceZone') {
+        const concrete = typeof value._type === 'string' ? value._type : null;
+        if (concrete === null || stories[concrete] === undefined)
+            return null;
+        if (!Array.isArray(field.allowed))
+            return null;
+        return field.allowed.some((entry) => entry.slice === concrete) ? concrete : null;
+    }
+    if (BUILTIN_SCHEMA_FIELD_TYPES.has(fieldType))
+        return null;
+    const candidates = [
+        ...(typeof field.resolvedTypeId === 'string' ? [field.resolvedTypeId] : []),
+        ...(field.resolvedTypeIds ?? []),
+        ...(stories[fieldType] !== undefined ? [fieldType] : []),
+    ].filter((candidate, index, all) => all.indexOf(candidate) === index);
+    if (candidates.length === 1)
+        return candidates[0];
+    const concrete = typeof value._type === 'string' ? value._type : null;
+    if (concrete !== null && candidates.includes(concrete))
+        return concrete;
+    return null;
+}
+function schemaFieldDeclaration(storyTypeId, field, shape) {
+    const type = effectiveSchemaFieldType(shape) ?? pickFieldType(shape.type);
+    const declarationStoryTypeId = declarationOwnerStoryType(storyTypeId, shape.origin);
+    return {
+        id: `${declarationStoryTypeId}:${field}:${type}:${shape.array === true ? 'array' : 'one'}`,
+        storyTypeId: declarationStoryTypeId,
+        field,
+        type,
+        isArray: shape.array === true,
+    };
+}
+function declarationOwnerStoryType(storyTypeId, origin) {
+    if (origin?.startsWith('fragment:') || origin?.startsWith('inherited:')) {
+        const owner = origin.slice(origin.indexOf(':') + 1).trim();
+        if (owner.length > 0)
+            return owner;
+    }
+    return storyTypeId;
+}
+function joinCoveragePath(prefix, field) {
+    return prefix.length === 0 ? field : `${prefix}.${field}`;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+// ─────────────────────────────────────────────
+// Internals
+// ─────────────────────────────────────────────
+function readStories(schema) {
+    const raw = schema.stories;
+    if (raw === null || raw === undefined || typeof raw !== 'object')
+        return null;
+    return raw;
+}
+/**
+ * Split `cards[0].cta.label` into
+ * `[{name:'cards'},{index:0},{name:'cta'},{name:'label'}]`.
+ *
+ * Returns null on malformed input (e.g. `cards[]`, `cards[abc]`,
+ * stray `[`).
+ */
+export function splitFieldPath(path) {
+    if (path.length === 0)
+        return [];
+    const out = [];
+    const len = path.length;
+    let i = 0;
+    while (i < len) {
+        if (path[i] === '.') {
+            i++;
+            continue;
+        }
+        if (path[i] === '[') {
+            // Index segment.
+            const close = path.indexOf(']', i + 1);
+            if (close === -1)
+                return null;
+            const inner = path.slice(i + 1, close);
+            if (inner.length === 0)
+                return null;
+            const idx = Number(inner);
+            if (!Number.isInteger(idx) || idx < 0)
+                return null;
+            out.push({ kind: 'index', idx });
+            i = close + 1;
+            continue;
+        }
+        // Name segment — read until `.` or `[`.
+        let j = i;
+        while (j < len && path[j] !== '.' && path[j] !== '[')
+            j++;
+        const name = path.slice(i, j);
+        if (name.length === 0)
+            return null;
+        out.push({ kind: 'name', name });
+        i = j;
+    }
+    return out;
+}
+function pickFieldType(type) {
+    if (typeof type === 'string')
+        return type;
+    if (Array.isArray(type) && type.length > 0 && typeof type[0] === 'string') {
+        return type[0];
+    }
+    return '';
+}

package/dist/runtime/runtime-error-dispatch.d.ts

@@ -0,0 +1,23 @@
+import { type RuntimeErrorPayload } from '@storystick/transport-allowlist';
+export interface RuntimeErrorDispatchOptions {
+    readonly code: string;
+    readonly message: string;
+    readonly severity: RuntimeErrorPayload['severity'];
+    readonly retryable: boolean;
+    readonly retryNotBefore?: number;
+    readonly persistence: RuntimeErrorPayload['persistence'];
+}
+export interface RuntimeErrorDispatchContext {
+    readonly parentOrigin: string | null;
+    readonly sessionId: string | null;
+    readonly projectId: string | null;
+}
+/**
+ * Dispatch a runtime diagnostic from an already-resolved preview identity.
+ *
+ * Keeping the context explicit lets the runtime store report a recoverable
+ * subscription failure without importing the public emitter back through the
+ * store singleton (which would create a module cycle).
+ */
+export declare function dispatchRuntimeError(options: RuntimeErrorDispatchOptions, context: RuntimeErrorDispatchContext): void;
+export declare function dispatchRuntimeRecovered(code: string, context: RuntimeErrorDispatchContext): void;

package/dist/runtime/runtime-error-dispatch.js

@@ -0,0 +1,75 @@
+import { PREVIEW_NAMESPACE, PREVIEW_PROTOCOL_VERSION, RUNTIME_ERROR_CODE_PREFIX, } from '@storystick/transport-allowlist';
+import { createPreviewRequestId } from './request-id.js';
+/**
+ * Dispatch a runtime diagnostic from an already-resolved preview identity.
+ *
+ * Keeping the context explicit lets the runtime store report a recoverable
+ * subscription failure without importing the public emitter back through the
+ * store singleton (which would create a module cycle).
+ */
+export function dispatchRuntimeError(options, context) {
+    if (!options.code.startsWith(RUNTIME_ERROR_CODE_PREFIX)) {
+        throw new Error(`emitRuntimeError: code must start with '${RUNTIME_ERROR_CODE_PREFIX}' — got '${options.code}'`);
+    }
+    if (context.parentOrigin === null ||
+        context.sessionId === null ||
+        context.projectId === null) {
+        return;
+    }
+    if (typeof window === 'undefined' || window.parent === window) {
+        return;
+    }
+    try {
+        const envelope = {
+            namespace: PREVIEW_NAMESPACE,
+            version: PREVIEW_PROTOCOL_VERSION,
+            type: 'storystick.preview.runtime-error',
+            sessionId: context.sessionId,
+            projectId: context.projectId,
+            requestId: createPreviewRequestId(),
+            nonce: createPreviewRequestId(),
+            sentAt: Date.now(),
+            payload: {
+                code: options.code,
+                message: options.message,
+                severity: options.severity,
+                retryable: options.retryable,
+                ...(options.retryNotBefore !== undefined ? { retryNotBefore: options.retryNotBefore } : {}),
+                persistence: options.persistence,
+            },
+        };
+        window.parent.postMessage(envelope, context.parentOrigin);
+    }
+    catch {
+        // Best-effort diagnostics must never compound the runtime failure.
+    }
+}
+export function dispatchRuntimeRecovered(code, context) {
+    if (!code.startsWith(RUNTIME_ERROR_CODE_PREFIX)) {
+        throw new Error(`emitRuntimeRecovered: code must start with '${RUNTIME_ERROR_CODE_PREFIX}' — got '${code}'`);
+    }
+    if (context.parentOrigin === null ||
+        context.sessionId === null ||
+        context.projectId === null) {
+        return;
+    }
+    if (typeof window === 'undefined' || window.parent === window)
+        return;
+    try {
+        const envelope = {
+            namespace: PREVIEW_NAMESPACE,
+            version: PREVIEW_PROTOCOL_VERSION,
+            type: 'storystick.preview.runtime-recovered',
+            sessionId: context.sessionId,
+            projectId: context.projectId,
+            requestId: createPreviewRequestId(),
+            nonce: createPreviewRequestId(),
+            sentAt: Date.now(),
+            payload: { code },
+        };
+        window.parent.postMessage(envelope, context.parentOrigin);
+    }
+    catch {
+        // Best-effort diagnostics must never compound runtime recovery.
+    }
+}