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

package/dist/rich-text.js

@@ -0,0 +1,618 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { isPreviewSliceDirectInvocationCandidate, readPreviewSliceScopeAdapter, } from './preview-slice-scope.js';
+import { readContentOrigin, prepareContentSource, } from '@storystick/client/internal';
+/**
+ * RichText — renders ProseMirror JSON to React elements.
+ *
+ * A lightweight tree walker with no TipTap dependency.
+ * Uses one semantic `components` registry for blocks, marks and embeds.
+ *
+ *   <RichText content={post.fields.body} components={{ embeds: sliceComponents }} />
+ */
+import React from 'react';
+import { stripPreviewProvenanceTextMarkers } from '@storystick/types/preview-provenance';
+import { previewTextProps } from './preview-text-props.js';
+import { getReferencedDocumentsSidecar, richTextToPlainText, isSectionAnchorSlug, resolveLink as resolveLinkValue, } from '@storystick/types';
+import { hydrateSliceWithDiagnostics } from './hydrate-slice.js';
+import { projectHydratedSlice, renderSliceFallback, reportSliceFailure, validateSliceVariation, } from './slice-render-failure.js';
+import { stampPreviewScope } from './preview-scope.js';
+import { extractSliceFields, getPreviewDocumentId, isPublishedSnapshotContext, makeSliceRenderId, serializeSliceModel, } from '@storystick/preview/provenance/slice-model';
+import { buildDocumentProvenance, buildSliceProvenance, fieldSegment, previewPathKey, richTextTextNodeSegment, } from './preview-provenance.js';
+// ─────────────────────────────────────────────
+// Content parsing
+// ─────────────────────────────────────────────
+function parseContent(content) {
+    if (!content)
+        return null;
+    let doc = content;
+    if (typeof content === 'string') {
+        try {
+            doc = JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    const node = doc;
+    if (!node || typeof node !== 'object' || !node.type)
+        return null;
+    if (!node.content?.length)
+        return null;
+    return node;
+}
+// ─────────────────────────────────────────────
+// Default mark renderers
+// ─────────────────────────────────────────────
+function defaultMark(mark, children, key, link, title) {
+    switch (mark.type) {
+        case 'bold':
+            return _jsx("strong", { children: children }, key);
+        case 'italic':
+            return _jsx("em", { children: children }, key);
+        case 'underline':
+            return _jsx("u", { children: children }, key);
+        case 'strike':
+            return _jsx("s", { children: children }, key);
+        case 'code':
+            return _jsx("code", { children: children }, key);
+        case 'link': {
+            const status = link &&
+                link.status !== 'ok' &&
+                link.status !== 'external' &&
+                link.status !== 'asset'
+                ? link.status
+                : undefined;
+            return (_jsx("a", { ...link?.props, title: title, "data-ss-link-status": status, children: children }, key));
+        }
+        default:
+            // Custom mark — render as span with attrs
+            return _jsx("span", { children: children }, key);
+    }
+}
+// ─────────────────────────────────────────────
+// Tree walker
+// ─────────────────────────────────────────────
+const STANDARD_MARK_ORDER = [
+    'link',
+    'bold',
+    'italic',
+    'underline',
+    'strike',
+    'code',
+];
+function markOrder(left, right) {
+    const rank = (name) => {
+        const index = STANDARD_MARK_ORDER.indexOf(name);
+        return index < 0 ? STANDARD_MARK_ORDER.length : index;
+    };
+    return rank(left) - rank(right) || (left < right ? -1 : left > right ? 1 : 0);
+}
+const DEFAULT_WALK_POSITION = {
+    block: { type: 'paragraph' },
+    ancestors: [],
+};
+const BUILTIN_MARKS = new Set([
+    'bold',
+    'italic',
+    'underline',
+    'strike',
+    'code',
+    'link',
+]);
+function reportRichTextDiagnostic(ctx, diagnostic) {
+    ctx.onDiagnostic?.(diagnostic);
+    if (!ctx.onDiagnostic && process.env.NODE_ENV !== 'production') {
+        console.warn(`[Storystick RichText] ${diagnostic.message}`);
+    }
+}
+function renderContext(position) {
+    return {
+        block: position.block,
+        ancestors: [...position.ancestors],
+    };
+}
+function authoredLinkTitle(mark) {
+    const title = mark.attrs?.title;
+    if (typeof title !== 'string')
+        return undefined;
+    return stripPreviewProvenanceTextMarkers(title) || undefined;
+}
+function extractText(node, parts) {
+    if (node.text)
+        parts.push(stripPreviewProvenanceTextMarkers(node.text));
+    for (const child of node.content ?? [])
+        extractText(child, parts);
+}
+function visibleNodeText(node) {
+    const parts = [];
+    extractText(node, parts);
+    return parts.length > 0 ? parts.join('') : undefined;
+}
+function headingLevel(node) {
+    const level = node.attrs?.level;
+    return typeof level === 'number' &&
+        Number.isInteger(level) &&
+        level >= 1 &&
+        level <= 6
+        ? level
+        : 2;
+}
+function headingAnchorId(node) {
+    const anchor = node.attrs?._anchor;
+    if (anchor === null || typeof anchor !== 'object' || Array.isArray(anchor)) {
+        return undefined;
+    }
+    const slug = anchor.slug;
+    return typeof slug === 'string' && isSectionAnchorSlug(slug)
+        ? slug
+        : undefined;
+}
+function currentList(ancestors) {
+    for (let index = ancestors.length - 1; index >= 0; index -= 1) {
+        const ancestor = ancestors[index];
+        if (ancestor?.type === 'list') {
+            return { list: ancestor.list, depth: ancestor.depth };
+        }
+    }
+    return { list: 'bullet', depth: 1 };
+}
+function renderNode(node, index, ctx, position, path) {
+    const key = `rt-${index}`;
+    // Text node — apply marks
+    if (node.type === 'text') {
+        const textNodeIndex = ctx.nextTextNodeIndex++;
+        const textProps = previewTextProps(node.text ?? '');
+        let result = textProps.children;
+        if (node.marks?.length) {
+            // Canonical nesting does not depend on the order in which marks were applied.
+            const marks = [...node.marks].sort((a, b) => markOrder(a.type, b.type));
+            for (let i = marks.length - 1; i >= 0; i--) {
+                const mark = marks[i];
+                const markKey = `${key}-m${i}`;
+                // Resolved once, above the override branch: a custom link renderer and
+                // the default one see the same href, from the same resolution path.
+                const link = mark.type === 'link'
+                    ? resolveLinkValue(mark.attrs, {
+                        source: readContentOrigin(mark.attrs) ??
+                            ctx.linkSource ??
+                            ctx.referencedDocs,
+                    })
+                    : undefined;
+                const title = mark.type === 'link' ? authoredLinkTitle(mark) : undefined;
+                const context = renderContext(position);
+                const MarkOverride = ctx.components?.marks?.[mark.type];
+                if (mark.type === 'link' && MarkOverride && link) {
+                    result = (_jsx(MarkOverride, { link: link, title: title, context: context, children: result }, markKey));
+                }
+                else if (MarkOverride) {
+                    result = (_jsx(MarkOverride, { context: context, ...(mark.attrs?.value !== undefined
+                            ? { value: mark.attrs.value }
+                            : {}), children: result }, markKey));
+                }
+                else {
+                    if (!BUILTIN_MARKS.has(mark.type)) {
+                        reportRichTextDiagnostic(ctx, {
+                            reason: 'missing-mark-renderer',
+                            type: mark.type,
+                            path,
+                            message: `No RichText mark renderer is registered for "${mark.type}"; its children were preserved.`,
+                        });
+                    }
+                    result = defaultMark(mark, result, markKey, link, title);
+                }
+            }
+        }
+        const contextualAttrs = provenanceAttrsForTextNode(ctx, textNodeIndex);
+        const provenanceAttrs = Object.keys(contextualAttrs).length > 0
+            ? contextualAttrs
+            : textProps['data-ss-p'] ? { 'data-ss-p': textProps['data-ss-p'] } : {};
+        if (Object.keys(provenanceAttrs).length > 0) {
+            ctx.provenanceTextNodeCount += 1;
+            result = (_jsx("span", { suppressHydrationWarning: true, ...provenanceAttrs, ...(node.marks?.some(mark => mark.type === 'link')
+                    ? { 'data-ss-richtext-link': '' }
+                    : {}), children: result }, `${key}-p`));
+        }
+        return result;
+    }
+    // Slice embed — dispatch to component registry
+    if (node.type === 'sliceEmbed') {
+        const embedIndex = ctx.nextEmbedIndex++;
+        const embedType = node.attrs?._type;
+        if (typeof embedType !== 'string' || embedType.length === 0) {
+            const failure = {
+                reason: 'missing-type',
+                slice: isRecord(node.attrs) ? node.attrs : {},
+                index: embedIndex,
+            };
+            reportSliceFailure(failure, ctx.onRenderFailure);
+            return renderSliceFallback(ctx.sliceFallback, failure, `missing-embed-type-${embedIndex}`, ctx.previewing || process.env.NODE_ENV !== 'production');
+        }
+        const rawEmbedKey = node.attrs?._key;
+        const embedKey = typeof rawEmbedKey === 'string' && rawEmbedKey.length > 0
+            ? rawEmbedKey
+            : key;
+        const Component = ctx.components?.embeds?.[embedType];
+        if (!Component) {
+            const failure = {
+                reason: 'unregistered-type',
+                slice: { _type: embedType, _key: embedKey },
+                index: embedIndex,
+                registeredTypes: Object.keys(ctx.components?.embeds ?? {}).sort(),
+            };
+            reportSliceFailure(failure, ctx.onRenderFailure);
+            reportRichTextDiagnostic(ctx, {
+                reason: 'missing-embed-renderer',
+                type: embedType,
+                path,
+                message: `No RichText embed renderer is registered for "${embedType}".`,
+            });
+            return renderSliceFallback(ctx.sliceFallback, failure, embedKey, ctx.previewing || process.env.NODE_ENV !== 'production');
+        }
+        // Flatten attrs.data into a SliceData shape
+        const rawData = node.attrs?.data;
+        if (rawData !== undefined && !isRecord(rawData)) {
+            const failure = {
+                reason: 'invalid-slice',
+                value: rawData,
+                index: embedIndex,
+            };
+            reportSliceFailure(failure, ctx.onRenderFailure);
+            return renderSliceFallback(ctx.sliceFallback, failure, embedKey, ctx.previewing || process.env.NODE_ENV !== 'production');
+        }
+        const data = rawData ?? {};
+        const slice = {
+            ...data,
+            _type: embedType,
+            _key: embedKey,
+            ...(node.attrs &&
+                Object.prototype.hasOwnProperty.call(node.attrs, '_variation')
+                ? { _variation: node.attrs._variation }
+                : {}),
+        };
+        const variationFailure = validateSliceVariation(slice, ctx.contracts, embedIndex);
+        if (variationFailure) {
+            reportSliceFailure(variationFailure, ctx.onRenderFailure);
+            return renderSliceFallback(ctx.sliceFallback, variationFailure, embedKey, ctx.previewing || process.env.NODE_ENV !== 'production');
+        }
+        const sourceRefPath = ctx.sliceField === undefined
+            ? undefined
+            : `${ctx.parentPath ? `${ctx.parentPath}.` : ''}${ctx.sliceField}[${embedIndex}]._model`;
+        const contentOrigin = readContentOrigin(slice);
+        const hydration = contentOrigin
+            ? { slice, failures: contentOrigin.failures ?? [] }
+            : hydrateSliceWithDiagnostics(slice, ctx.source, { sourceRefPath });
+        if (hydration.failures.length > 0) {
+            const failures = hydration.failures.map((failure) => failure.reason === 'missing-model'
+                ? { ...failure, slice, index: embedIndex }
+                : { reason: 'invalid-bindings', slice, index: embedIndex });
+            failures.forEach((failure) => reportSliceFailure(failure, ctx.onRenderFailure));
+            return renderSliceFallback(ctx.sliceFallback, failures[0], embedKey, ctx.previewing || process.env.NODE_ENV !== 'production');
+        }
+        const hydrated = projectHydratedSlice(hydration.slice, ctx.contracts);
+        const hydratedFields = extractSliceFields(hydrated);
+        let propSlice = hydrated;
+        const componentContext = ctx.context;
+        if (ctx.previewing &&
+            ctx.previewDocId !== null &&
+            ctx.sliceField !== undefined &&
+            typeof slice._key === 'string' &&
+            slice._key.length > 0) {
+            const embedPathPrefix = ctx.parentPath
+                ? `${ctx.parentPath}.${ctx.sliceField}`
+                : ctx.sliceField;
+            const modelJson = serializeSliceModel({
+                v: 129,
+                renderId: ctx.embedRenderId,
+                doc: ctx.previewDocId,
+                i: contentOrigin?.index ?? embedIndex,
+                type: embedType,
+                fields: hydratedFields,
+                zoneField: ctx.sliceField,
+                zoneFieldSource: 'explicit',
+                parentAnchors: contentOrigin?.parentAnchors ?? ctx.parentAnchors,
+                ...(contentOrigin
+                    ? {
+                        source: {
+                            path: `${embedPathPrefix}[${contentOrigin.index ?? embedIndex}]`,
+                            anchors: [
+                                ...contentOrigin.parentAnchors,
+                                { pathPrefix: embedPathPrefix, key: slice._key },
+                            ],
+                        },
+                    }
+                    : {}),
+            });
+            if (modelJson !== null) {
+                propSlice = stampPreviewScope(hydrated, modelJson);
+            }
+        }
+        const bindings = buildSliceProvenance(contentOrigin ?? ctx.provenanceContext, slice);
+        const props = { slice: propSlice, context: componentContext, bindings };
+        const adapter = readPreviewSliceScopeAdapter();
+        const documentId = contentOrigin?.documentId ?? ctx.previewDocId;
+        if (adapter &&
+            documentId &&
+            isPreviewSliceDirectInvocationCandidate(Component)) {
+            const scoped = adapter({
+                component: Component,
+                props,
+                scope: {
+                    routeFrame: null,
+                    documentId,
+                    sliceField: ctx.sliceField ?? 'richtext',
+                    slicePath: contentOrigin?.path ??
+                        `${ctx.sliceField ?? 'richtext'}[${embedIndex}]`,
+                    sliceKey: embedKey,
+                    sliceType: embedType,
+                    sliceIndex: contentOrigin?.index ?? embedIndex,
+                },
+            });
+            return (_jsx(React.Fragment, { children: scoped }, embedKey));
+        }
+        return _jsx(Component, { ...props }, embedKey);
+    }
+    const renderChildren = (childPosition) => node.content?.map((child, childIndex) => renderNode(child, childIndex, ctx, childPosition, [...path, childIndex])) ?? null;
+    const renderTextBlockChildren = (childPosition) => {
+        const before = ctx.provenanceTextNodeCount;
+        const children = renderChildren(childPosition);
+        // Explicit opt-in geometry survives custom block renderers without reading
+        // arbitrary customer DOM. Keep each leaf's provenance for precise arrivals.
+        return ctx.provenanceTextNodeCount > before
+            ? _jsx("span", { "data-ss-richtext-block": "", suppressHydrationWarning: true, children: children })
+            : children;
+    };
+    switch (node.type) {
+        case 'paragraph': {
+            const block = position.block.type === 'listItem'
+                ? position.block
+                : { type: 'paragraph' };
+            const childPosition = { ...position, block };
+            const children = renderTextBlockChildren(childPosition);
+            const Component = ctx.components?.block?.paragraph;
+            return Component ? (_jsx(Component, { text: visibleNodeText(node), context: renderContext(childPosition), children: children }, key)) : (_jsx("p", { children: children }, key));
+        }
+        case 'heading': {
+            const level = headingLevel(node);
+            const id = headingAnchorId(node);
+            const childPosition = {
+                ...position,
+                block: { type: 'heading', level },
+            };
+            const children = renderTextBlockChildren(childPosition);
+            const Component = ctx.components?.block?.[`h${level}`];
+            if (Component) {
+                return (_jsx(Component, { id: id, text: visibleNodeText(node), context: renderContext(childPosition), children: children }, key));
+            }
+            const Tag = `h${level}`;
+            return (_jsx(Tag, { id: id, children: children }, key));
+        }
+        case 'blockquote': {
+            const block = { type: 'blockquote' };
+            const childPosition = {
+                block,
+                ancestors: [...position.ancestors, { type: 'blockquote' }],
+            };
+            const children = renderChildren(childPosition);
+            const Component = ctx.components?.block?.blockquote;
+            return Component ? (_jsx(Component, { text: visibleNodeText(node), context: { block, ancestors: [...position.ancestors] }, children: children }, key)) : (_jsx("blockquote", { children: children }, key));
+        }
+        case 'codeBlock': {
+            const childPosition = {
+                ...position,
+                block: { type: 'code' },
+            };
+            const children = renderTextBlockChildren(childPosition);
+            const language = typeof node.attrs?.language === 'string'
+                ? node.attrs.language
+                : undefined;
+            const Component = ctx.components?.block?.code;
+            return Component ? (_jsx(Component, { text: visibleNodeText(node), language: language, context: renderContext(childPosition), children: children }, key)) : (_jsx("pre", { "data-language": language, children: _jsx("code", { children: children }) }, key));
+        }
+        case 'horizontalRule': {
+            const Component = ctx.components?.block?.divider;
+            return Component ? _jsx(Component, {}, key) : _jsx("hr", {}, key);
+        }
+        case 'hardBreak': {
+            const Component = ctx.components?.hardBreak;
+            return Component ? _jsx(Component, {}, key) : _jsx("br", {}, key);
+        }
+        case 'bulletList':
+        case 'orderedList': {
+            const list = node.type === 'bulletList' ? 'bullet' : 'ordered';
+            const depth = currentList(position.ancestors).depth +
+                (position.ancestors.some((ancestor) => ancestor.type === 'list')
+                    ? 1
+                    : 0);
+            const childPosition = {
+                ...position,
+                ancestors: [...position.ancestors, { type: 'list', list, depth }],
+            };
+            const children = renderChildren(childPosition);
+            if (list === 'ordered') {
+                const start = typeof node.attrs?.start === 'number' ? node.attrs.start : undefined;
+                const Component = ctx.components?.list?.ordered;
+                return Component ? (_jsx(Component, { start: start, children: children }, key)) : (_jsx("ol", { start: start, children: children }, key));
+            }
+            const Component = ctx.components?.list?.bullet;
+            return Component ? (_jsx(Component, { children: children }, key)) : (_jsx("ul", { children: children }, key));
+        }
+        case 'listItem': {
+            const list = currentList(position.ancestors);
+            const block = {
+                type: 'listItem',
+                list: list.list,
+                depth: list.depth,
+            };
+            const childPosition = {
+                block,
+                ancestors: [
+                    ...position.ancestors,
+                    { type: 'listItem', list: list.list, depth: list.depth },
+                ],
+            };
+            const children = renderChildren(childPosition);
+            const Component = ctx.components?.listItem?.[list.list];
+            return Component ? (_jsx(Component, { children: children }, key)) : (_jsx("li", { children: children }, key));
+        }
+        default: {
+            reportRichTextDiagnostic(ctx, {
+                reason: 'unknown-block',
+                type: node.type,
+                path,
+                message: `Unknown RichText block "${node.type}"; its children were preserved.`,
+            });
+            const children = renderChildren(position);
+            return children ? _jsx("div", { children: children }, key) : null;
+        }
+    }
+}
+// ─────────────────────────────────────────────
+// Component
+// ─────────────────────────────────────────────
+function renderRichText(props, inline) {
+    const { content: inputContent, source, components, sliceFallback, contracts, onRenderFailure, onDiagnostic, context, bindings, provenancePath, sliceField, parentAnchors, parentPath, className, fallback, } = props;
+    const content = prepareContentSource(inputContent, source);
+    const origin = readContentOrigin(content);
+    const doc = parseContent(content);
+    if (!doc) {
+        return (fallback ?? null);
+    }
+    const technicalSource = origin ?? source?.document;
+    // Preparing a raw rich-text field gives the parsed value a compact
+    // ContentOrigin. That origin deliberately carries reference/address data,
+    // but not the complete document provenance map. Keep resolution on the
+    // origin while reading direct-field provenance from the explicit document.
+    const provenanceSource = source?.document ?? origin;
+    const referencedDocs = getReferencedDocumentsSidecar(technicalSource);
+    const linkSource = technicalSource;
+    const previewDocId = origin?.documentId ?? getPreviewDocumentId(source?.document);
+    const effectiveSliceField = origin?.path.split('.').at(-1) ?? sliceField ?? source?.path;
+    const effectiveParentAnchors = origin?.parentAnchors ?? parentAnchors ?? [];
+    const effectiveParentPath = origin?.path.includes('.')
+        ? origin.path.slice(0, origin.path.lastIndexOf('.'))
+        : parentPath;
+    const inferredDocumentProvenance = !bindings && previewDocId !== null
+        ? buildDocumentProvenance(provenanceSource, {
+            documentId: previewDocId,
+        })
+        : undefined;
+    const effectiveProvenance = bindings ?? inferredDocumentProvenance;
+    const effectiveProvenancePath = provenancePath ?? inferTopLevelProvenancePath(origin?.path ?? source?.path);
+    const provenanceContext = technicalSource;
+    const previewing = origin
+        ? origin.preview === true
+        : previewDocId !== null && !isPublishedSnapshotContext(source?.document);
+    const embedRenderId = previewing && previewDocId !== null
+        ? makeSliceRenderId({
+            scopeDocId: previewDocId,
+            slices: collectEmbedIdentities(doc),
+            scopeKey: `${effectiveParentPath ?? 'root'}:${effectiveSliceField}`,
+        })
+        : '';
+    const ctx = {
+        components: components,
+        sliceFallback,
+        contracts,
+        onRenderFailure,
+        onDiagnostic,
+        context,
+        source: technicalSource,
+        referencedDocs,
+        linkSource,
+        provenance: effectiveProvenance,
+        provenancePath: effectiveProvenancePath,
+        provenanceContext,
+        sliceField: effectiveSliceField,
+        parentPath: effectiveParentPath,
+        parentAnchors: effectiveParentAnchors,
+        previewDocId,
+        previewing,
+        embedRenderId,
+        nextTextNodeIndex: 0,
+        provenanceTextNodeCount: 0,
+        nextEmbedIndex: 0,
+    };
+    let renderNodes = doc.content;
+    if (inline) {
+        const validInlineShape = renderNodes.length === 1 && renderNodes[0]?.type === 'paragraph';
+        if (!validInlineShape) {
+            reportRichTextDiagnostic(ctx, {
+                reason: 'inline-shape',
+                path: [],
+                message: 'RichText.Inline expected exactly one paragraph; block wrappers were omitted while preserving renderable children.',
+            });
+        }
+        renderNodes = renderNodes.flatMap((node) => node.type === 'text' ||
+            node.type === 'hardBreak' ||
+            node.type === 'sliceEmbed'
+            ? [node]
+            : (node.content ?? []));
+    }
+    const renderedNodes = renderNodes.map((node, index) => renderNode(node, index, ctx, DEFAULT_WALK_POSITION, [index]));
+    const rendered = inline && ctx.provenanceTextNodeCount > 0
+        ? _jsx("span", { "data-ss-richtext-block": "", suppressHydrationWarning: true, children: renderedNodes })
+        : renderedNodes;
+    if (className) {
+        return _jsx("div", { className: className, children: rendered });
+    }
+    return _jsx(_Fragment, { children: rendered });
+}
+/**
+ * A raw primitive cannot carry ContentOrigin metadata. For the common direct
+ * document-field case, the explicit ContentSource still gives RichText enough
+ * information to recover its document provenance without app-owned plumbing.
+ * Indexed paths keep requiring an explicit provenancePath because their stable
+ * array-item keys cannot be inferred from a numeric string alone.
+ */
+function inferTopLevelProvenancePath(path) {
+    if (!path || path.includes('['))
+        return undefined;
+    const segments = path.split('.').filter(Boolean);
+    return segments.length > 0 ? segments.map(fieldSegment) : undefined;
+}
+function RichTextRoot(props) {
+    return renderRichText(props, false);
+}
+function RichTextInline(props) {
+    return renderRichText(props, true);
+}
+export const RichText = Object.assign(RichTextRoot, {
+    Inline: RichTextInline,
+});
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function collectEmbedIdentities(root) {
+    const out = [];
+    const visit = (node, index) => {
+        if (node.type === 'sliceEmbed') {
+            const embedType = node.attrs?._type;
+            const key = node.attrs?._key;
+            if (typeof embedType === 'string' && embedType.length > 0) {
+                out.push({
+                    _type: embedType,
+                    _key: typeof key === 'string' ? key : `rt-${index}`,
+                });
+            }
+        }
+        node.content?.forEach((child, childIndex) => visit(child, childIndex));
+    };
+    visit(root, 0);
+    return out;
+}
+function provenanceAttrsForTextNode(ctx, textNodeIndex) {
+    if (!ctx.provenance || !ctx.provenancePath)
+        return {};
+    const path = [...ctx.provenancePath, richTextTextNodeSegment(textNodeIndex)];
+    return ctx.provenance.paths[previewPathKey(path)] ?? {};
+}
+// ─────────────────────────────────────────────
+// toText utility
+// ─────────────────────────────────────────────
+/**
+ * Extract plain text from richtext content.
+ * Handles both JSON string and parsed ProseMirror document.
+ */
+export function toText(content, separator = ' ') {
+    return richTextToPlainText(content, separator);
+}

package/dist/slice-render-failure.d.ts

@@ -0,0 +1,8 @@
+import type { ReactElement, ReactNode } from 'react';
+export { validateSliceVariation, projectHydratedSlice } from '@storystick/types';
+export type { SliceRenderFailure, SliceContract, SliceContractRegistry } from '@storystick/types';
+import type { SliceRenderFailure } from '@storystick/types';
+export type SliceFallback = ReactNode | ((failure: SliceRenderFailure) => ReactNode);
+export type SliceRenderFailureHandler = (failure: SliceRenderFailure) => void;
+export declare function reportSliceFailure(failure: SliceRenderFailure, onRenderFailure: SliceRenderFailureHandler | undefined): void;
+export declare function renderSliceFallback(fallback: SliceFallback | undefined, failure: SliceRenderFailure, key: string, visiblyFail: boolean): ReactElement | null;

package/dist/slice-render-failure.js

@@ -0,0 +1,46 @@
+import React from 'react';
+export { validateSliceVariation, projectHydratedSlice } from '@storystick/types';
+export function reportSliceFailure(failure, onRenderFailure) {
+    onRenderFailure?.(failure);
+    if (process.env.NODE_ENV === 'production')
+        return;
+    switch (failure.reason) {
+        case 'invalid-slice':
+            console.warn(`StorystickError: Slice at index ${failure.index} is not an object.`);
+            return;
+        case 'missing-type':
+            console.warn(`StorystickError: Slice at index ${failure.index} has no "_type" field.\n` +
+                'Each slice must have: { _type: string, _key: string, ...fields }');
+            return;
+        case 'unregistered-type':
+            console.warn(`StorystickError: No component registered for slice type "${failure.slice._type}".\n` +
+                `Registered types: ${failure.registeredTypes.join(', ') || '(none)'}\n` +
+                `Fix: add "${failure.slice._type}" to the slice component registry.`);
+            return;
+        case 'invalid-variation':
+            console.warn(`StorystickError: Unknown variation ${JSON.stringify(failure.variation)} for slice "${failure.slice._type}".\n` +
+                `Registered variations: ${failure.registeredVariations.join(', ') || '(base only)'}\n` +
+                'Fix: omit _variation for the base slice or use a declared named variation.');
+            return;
+        case 'missing-model':
+            console.warn(`StorystickError: Model "${failure.modelId}" for slice "${failure.slice._type}" is missing from the response sidecar.`);
+            return;
+        case 'invalid-bindings':
+            console.warn(`StorystickError: Field bindings for slice "${failure.slice._type}" are malformed.`);
+    }
+}
+export function renderSliceFallback(fallback, failure, key, visiblyFail) {
+    const rendered = fallback === undefined
+        ? visiblyFail
+            ? React.createElement('div', {
+                role: 'alert',
+                'data-storystick-slice-failure': failure.reason,
+            }, `Slice could not render (${failure.reason}).`)
+            : null
+        : typeof fallback === 'function'
+            ? fallback(failure)
+            : fallback;
+    if (rendered === null || rendered === undefined || rendered === false)
+        return null;
+    return React.createElement(React.Fragment, { key }, rendered);
+}