@canvas-digital/blog-sdk 2.0.0

package/dist/lib/hero-post.js

@@ -0,0 +1,95 @@
+import { resolveFormatVideoSrc } from './format-media';
+import { videoEmbedSrc } from './post-format';
+import { mediaUrl } from './seo';
+import { primaryCategoryName } from './post-categories';
+const featuredAlt = (post) => {
+    const m = post.featuredImage;
+    if (typeof m === 'object' && m && 'alt' in m)
+        return String(m.alt ?? '');
+    return post.title;
+};
+const posterFor = (post) => mediaUrl(post.featuredImage, 'hero');
+const resolveVideoHero = (post, poster, ambient) => {
+    const src = resolveFormatVideoSrc(post);
+    if (!src)
+        return null;
+    const embed = videoEmbedSrc(src);
+    if (!embed)
+        return null;
+    if (embed.includes('youtube.com/embed')) {
+        if (!ambient)
+            return { kind: 'video-embed', src: embed, poster };
+        const id = embed.split('/').pop()?.split('?')[0];
+        if (!id)
+            return null;
+        const params = new URLSearchParams({
+            autoplay: '1',
+            mute: '1',
+            loop: '1',
+            playlist: id,
+            controls: '0',
+            rel: '0',
+            modestbranding: '1',
+            playsinline: '1',
+            disablekb: '1',
+            iv_load_policy: '3',
+        });
+        return { kind: 'video-embed', src: `${embed}?${params}`, poster };
+    }
+    if (embed.includes('player.vimeo.com')) {
+        if (!ambient)
+            return { kind: 'video-embed', src: embed, poster };
+        const params = new URLSearchParams({
+            autoplay: '1',
+            muted: '1',
+            loop: '1',
+            background: '1',
+            autopause: '0',
+        });
+        return { kind: 'video-embed', src: `${embed}?${params}`, poster };
+    }
+    if (/\.(mp4|webm|ogg)(\?|$)/i.test(embed) || src.startsWith('/') || /^https?:\/\//i.test(src)) {
+        return { kind: 'video-file', src: embed || src, poster };
+    }
+    return null;
+};
+/** Resolve background media for a post hero (image, file video, or embed). */
+export const resolveHeroMedia = (post) => {
+    const poster = posterFor(post);
+    if (post.postFormat === 'video') {
+        const video = resolveVideoHero(post, poster, true);
+        if (video)
+            return video;
+    }
+    const img = mediaUrl(post.featuredImage, 'hero');
+    if (img)
+        return { kind: 'image', src: img, alt: featuredAlt(post) };
+    return null;
+};
+/** First published post on the page that has a usable hero image or video. */
+export const findHeroPost = (posts) => {
+    for (const post of posts) {
+        if (resolveHeroMedia(post))
+            return post;
+    }
+    return null;
+};
+/** Every post on the current page that can drive the media hero slider. */
+export const findHeroPosts = (posts) => posts.filter((post) => Boolean(resolveHeroMedia(post)));
+export const postCategoryName = (post) => primaryCategoryName(post);
+/** Article detail hero — full-width media at social/OG 1200×630 without ambient autoplay. */
+export const resolveArticleHeroMedia = (post) => {
+    const poster = mediaUrl(post.featuredImage, 'og') || mediaUrl(post.featuredImage, 'hero');
+    if (post.postFormat === 'video') {
+        const video = resolveVideoHero(post, poster, false);
+        if (video)
+            return video;
+    }
+    const format = post.postFormat || 'standard';
+    if (format !== 'standard' && format !== 'image' && format !== 'video')
+        return null;
+    const img = mediaUrl(post.featuredImage, 'og') || mediaUrl(post.featuredImage, 'hero');
+    if (img)
+        return { kind: 'image', src: img, alt: featuredAlt(post) };
+    return null;
+};

package/dist/lib/lexical-build.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Builders for Lexical editor state.
+ *
+ * Used by the seed and by the WordPress importer. Content is written as a node
+ * tree from the start — there is no HTML-to-anything step anywhere in the
+ * pipeline, which is what keeps the "no markup" guarantee true end to end.
+ */
+type Node = Record<string, unknown>;
+export declare const p: (text: string) => Node;
+export declare const h: (level: 2 | 3, text: string) => Node;
+export declare const quote: (text: string) => Node;
+export declare const ul: (items: string[]) => Node;
+/**
+ * An internal link. Note it stores the target's *id*, not its URL — the path is
+ * resolved at render time, so this link keeps working after the target's slug
+ * changes.
+ */
+export declare const paragraphWithInternalLink: (before: string, linkText: string, targetId: string | number, after: string) => Node;
+export declare const doc: (children: Node[]) => {
+    root: {
+        type: string;
+        format: string;
+        indent: number;
+        version: number;
+        direction: string;
+        children: Node[];
+    };
+};
+export {};
+//# sourceMappingURL=lexical-build.d.ts.map

package/dist/lib/lexical-build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical-build.d.ts","sourceRoot":"","sources":["../../app/lib/lexical-build.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAsBnC,eAAO,MAAM,CAAC,GAAI,MAAM,MAAM,KAAG,IAAmE,CAAA;AAEpG,eAAO,MAAM,CAAC,GAAI,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,KAAG,IACe,CAAA;AAE9D,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,KAAG,IAA4C,CAAA;AAEjF,eAAO,MAAM,EAAE,GAAI,OAAO,MAAM,EAAE,KAAG,IAOlC,CAAA;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GACpC,QAAQ,MAAM,EACd,UAAU,MAAM,EAChB,UAAU,MAAM,GAAG,MAAM,EACzB,OAAO,MAAM,KACZ,IAqBA,CAAA;AAEH,eAAO,MAAM,GAAG,GAAI,UAAU,IAAI,EAAE;;;;;;;;;CASlC,CAAA"}

package/dist/lib/lexical-build.js

@@ -0,0 +1,57 @@
+/**
+ * Builders for Lexical editor state.
+ *
+ * Used by the seed and by the WordPress importer. Content is written as a node
+ * tree from the start — there is no HTML-to-anything step anywhere in the
+ * pipeline, which is what keeps the "no markup" guarantee true end to end.
+ */
+const textNode = (text, format = 0) => ({
+    type: 'text',
+    detail: 0,
+    format,
+    mode: 'normal',
+    style: '',
+    text,
+    version: 1,
+});
+const container = (type, children, extra = {}) => ({
+    type,
+    format: '',
+    indent: 0,
+    version: 1,
+    direction: 'ltr',
+    children,
+    ...extra,
+});
+export const p = (text) => container('paragraph', [textNode(text)], { textFormat: 0 });
+export const h = (level, text) => container('heading', [textNode(text)], { tag: `h${level}` });
+export const quote = (text) => container('quote', [textNode(text)]);
+export const ul = (items) => container('list', items.map((item, i) => container('listitem', [textNode(item)], { value: i + 1, checked: undefined })), { listType: 'bullet', start: 1, tag: 'ul' });
+/**
+ * An internal link. Note it stores the target's *id*, not its URL — the path is
+ * resolved at render time, so this link keeps working after the target's slug
+ * changes.
+ */
+export const paragraphWithInternalLink = (before, linkText, targetId, after) => container('paragraph', [
+    textNode(before),
+    container('link', [textNode(linkText)], {
+        fields: {
+            linkType: 'internal',
+            doc: { relationTo: 'posts', value: targetId },
+            newTab: false,
+            rel: null,
+        },
+        id: `link-${targetId}`,
+    }),
+    textNode(after),
+], { textFormat: 0 });
+export const doc = (children) => ({
+    root: {
+        type: 'root',
+        format: '',
+        indent: 0,
+        version: 1,
+        direction: 'ltr',
+        children,
+    },
+});

package/dist/lib/lexical-doc.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The contract between the dashboard editor and the stored document.
+ *
+ * The editor is a contenteditable surface, so what it hands back is a DOM tree.
+ * That tree becomes a Lexical node tree in the browser (see lexical-dom.ts) and
+ * is then re-validated *here*, on the server, against a closed allowlist before
+ * it is written. Nothing a client sends reaches the database unexamined: an
+ * unknown node type is dropped, an unknown property is dropped, and a text node
+ * is reduced to a string plus an integer format mask.
+ *
+ * That is what keeps the "content is structured JSON, never markup" guarantee
+ * true now that a browser is producing the content. `lexicalToEditorHtml` does
+ * emit HTML, but only in one direction and only for the editing surface — it is
+ * generated from already-sanitised JSON, with every text run escaped, and it is
+ * never stored and never served to a reader.
+ */
+export type LexNode = {
+    type: string;
+    [key: string]: unknown;
+};
+export type LexDoc = {
+    root: {
+        type: 'root';
+        children: LexNode[];
+        direction: 'ltr' | null;
+        format: '';
+        indent: 0;
+        version: 1;
+    };
+};
+/** Lexical's text format bitmask. These values are fixed by the format itself. */
+export declare const FMT: {
+    readonly bold: 1;
+    readonly italic: 2;
+    readonly strikethrough: 4;
+    readonly underline: 8;
+    readonly code: 16;
+};
+/** Headings an editor may produce (classic WP editor parity includes H1). */
+export declare const HEADING_TAGS: readonly ["h1", "h2", "h3", "h4"];
+export type HeadingTag = (typeof HEADING_TAGS)[number];
+/** Collections an internal link may point at — mirrors LinkFeature in payload.config.ts. */
+declare const LINKABLE: readonly ["posts", "categories"];
+export declare const emptyDoc: () => LexDoc;
+export declare const text: (value: string, format?: number) => LexNode;
+export declare const paragraph: (children: LexNode[]) => LexNode;
+export declare const heading: (tag: HeadingTag, children: LexNode[]) => LexNode;
+export declare const quote: (children: LexNode[]) => LexNode;
+export declare const listItem: (children: LexNode[], value: number) => LexNode;
+export declare const list: (tag: "ul" | "ol", items: LexNode[]) => LexNode;
+export declare const horizontalRule: () => LexNode;
+export declare const lineBreak: () => LexNode;
+export declare const uploadNode: (mediaId: string, nodeId?: string) => LexNode;
+export type LinkTarget = {
+    linkType: 'custom';
+    url: string;
+    newTab: boolean;
+    rel: string[] | null;
+} | {
+    linkType: 'internal';
+    relationTo: (typeof LINKABLE)[number];
+    value: string;
+    newTab: boolean;
+    rel: string[] | null;
+};
+export declare const linkNode: (target: LinkTarget, children: LexNode[], id?: string) => LexNode;
+/**
+ * External URLs are restricted to schemes that cannot execute. `javascript:` and
+ * `data:` in an href are the classic stored-XSS payload, and this is the point at
+ * which they are refused — before storage, not before rendering.
+ */
+export declare const safeHref: (raw: string) => string | null;
+/**
+ * Validate an editor payload into something safe to persist.
+ *
+ * Returns `emptyDoc()` rather than throwing for unusable input: a save must not
+ * fail because of a stray node, and an empty body is a legitimate draft state.
+ */
+export declare const sanitizeLexical: (input: unknown) => LexDoc;
+/** True when the document holds no words and no media — used for publish checks. */
+export declare const isEmptyDoc: (doc: unknown) => boolean;
+/**
+ * Render a stored document as the HTML the contenteditable surface starts from.
+ * Pass content read at depth >= 1 so upload nodes carry their populated media.
+ */
+export declare const lexicalToEditorHtml: (doc: unknown) => string;
+export {};
+//# sourceMappingURL=lexical-doc.d.ts.map

package/dist/lib/lexical-doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical-doc.d.ts","sourceRoot":"","sources":["../../app/lib/lexical-doc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAA;AAE9D,MAAM,MAAM,MAAM,GAAG;IACnB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAA;QACZ,QAAQ,EAAE,OAAO,EAAE,CAAA;QACnB,SAAS,EAAE,KAAK,GAAG,IAAI,CAAA;QACvB,MAAM,EAAE,EAAE,CAAA;QACV,MAAM,EAAE,CAAC,CAAA;QACT,OAAO,EAAE,CAAC,CAAA;KACX,CAAA;CACF,CAAA;AAED,kFAAkF;AAClF,eAAO,MAAM,GAAG;;;;;;CAMN,CAAA;AAIV,6EAA6E;AAC7E,eAAO,MAAM,YAAY,mCAAoC,CAAA;AAC7D,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAA;AAEtD,4FAA4F;AAC5F,QAAA,MAAM,QAAQ,kCAAmC,CAAA;AAIjD,eAAO,MAAM,QAAQ,QAAO,MAS1B,CAAA;AAgBF,eAAO,MAAM,IAAI,GAAI,OAAO,MAAM,EAAE,eAAU,KAAG,OAQ/C,CAAA;AAEF,eAAO,MAAM,SAAS,GAAI,UAAU,OAAO,EAAE,KAAG,OACgB,CAAA;AAEhE,eAAO,MAAM,OAAO,GAAI,KAAK,UAAU,EAAE,UAAU,OAAO,EAAE,KAAG,OAC1B,CAAA;AAErC,eAAO,MAAM,KAAK,GAAI,UAAU,OAAO,EAAE,KAAG,OAAmC,CAAA;AAE/E,eAAO,MAAM,QAAQ,GAAI,UAAU,OAAO,EAAE,EAAE,OAAO,MAAM,KAAG,OACF,CAAA;AAE5D,eAAO,MAAM,IAAI,GAAI,KAAK,IAAI,GAAG,IAAI,EAAE,OAAO,OAAO,EAAE,KAAG,OAKtD,CAAA;AAEJ,eAAO,MAAM,cAAc,QAAO,OAAmD,CAAA;AAErF,eAAO,MAAM,SAAS,QAAO,OAA8C,CAAA;AAE3E,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,SAAS,MAAM,KAAG,OAQ5D,CAAA;AAEF,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CAAE,GAC1E;IACE,QAAQ,EAAE,UAAU,CAAA;IACpB,UAAU,EAAE,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAA;IACrC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,OAAO,CAAA;IACf,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CACrB,CAAA;AAEL,eAAO,MAAM,QAAQ,GAAI,QAAQ,UAAU,EAAE,UAAU,OAAO,EAAE,EAAE,KAAK,MAAM,KAAG,OAsB9E,CAAA;AAiBF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAS/C,CAAA;AA8GD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,MAmBhD,CAAA;AAED,oFAAoF;AACpF,eAAO,MAAM,UAAU,GAAI,KAAK,OAAO,KAAG,OAWzC,CAAA;AAmHD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,OAAO,KAAG,MAIlD,CAAA"}

package/dist/lib/lexical-doc.js

@@ -0,0 +1,385 @@
+/**
+ * The contract between the dashboard editor and the stored document.
+ *
+ * The editor is a contenteditable surface, so what it hands back is a DOM tree.
+ * That tree becomes a Lexical node tree in the browser (see lexical-dom.ts) and
+ * is then re-validated *here*, on the server, against a closed allowlist before
+ * it is written. Nothing a client sends reaches the database unexamined: an
+ * unknown node type is dropped, an unknown property is dropped, and a text node
+ * is reduced to a string plus an integer format mask.
+ *
+ * That is what keeps the "content is structured JSON, never markup" guarantee
+ * true now that a browser is producing the content. `lexicalToEditorHtml` does
+ * emit HTML, but only in one direction and only for the editing surface — it is
+ * generated from already-sanitised JSON, with every text run escaped, and it is
+ * never stored and never served to a reader.
+ */
+/** Lexical's text format bitmask. These values are fixed by the format itself. */
+export const FMT = {
+    bold: 1,
+    italic: 2,
+    strikethrough: 4,
+    underline: 8,
+    code: 16,
+};
+const ALL_FORMATS = FMT.bold | FMT.italic | FMT.strikethrough | FMT.underline | FMT.code;
+/** Headings an editor may produce (classic WP editor parity includes H1). */
+export const HEADING_TAGS = ['h1', 'h2', 'h3', 'h4'];
+/** Collections an internal link may point at — mirrors LinkFeature in payload.config.ts. */
+const LINKABLE = ['posts', 'categories'];
+const REL_VALUES = ['noopener', 'noreferrer', 'nofollow', 'sponsored'];
+export const emptyDoc = () => ({
+    root: {
+        type: 'root',
+        children: [paragraph([])],
+        direction: 'ltr',
+        format: '',
+        indent: 0,
+        version: 1,
+    },
+});
+/* ------------------------------------------------------------------ */
+/* builders — one place that knows each node's exact serialized shape   */
+/* ------------------------------------------------------------------ */
+const block = (type, children, extra = {}) => ({
+    type,
+    children,
+    direction: 'ltr',
+    format: '',
+    indent: 0,
+    version: 1,
+    ...extra,
+});
+export const text = (value, format = 0) => ({
+    type: 'text',
+    detail: 0,
+    format,
+    mode: 'normal',
+    style: '',
+    text: value,
+    version: 1,
+});
+export const paragraph = (children) => block('paragraph', children, { textFormat: 0, textStyle: '' });
+export const heading = (tag, children) => block('heading', children, { tag });
+export const quote = (children) => block('quote', children);
+export const listItem = (children, value) => block('listitem', children, { value, checked: undefined });
+export const list = (tag, items) => block('list', items, {
+    listType: tag === 'ol' ? 'number' : 'bullet',
+    start: 1,
+    tag,
+});
+export const horizontalRule = () => ({ type: 'horizontalrule', version: 1 });
+export const lineBreak = () => ({ type: 'linebreak', version: 1 });
+export const uploadNode = (mediaId, nodeId) => ({
+    type: 'upload',
+    relationTo: 'media',
+    value: mediaId,
+    fields: null,
+    format: '',
+    version: 3,
+    id: nodeId || `u-${mediaId}-${Math.random().toString(36).slice(2, 8)}`,
+});
+export const linkNode = (target, children, id) => ({
+    type: 'link',
+    children,
+    direction: 'ltr',
+    format: '',
+    indent: 0,
+    version: 3,
+    id: id || `l-${Math.random().toString(36).slice(2, 9)}`,
+    fields: target.linkType === 'internal'
+        ? {
+            linkType: 'internal',
+            doc: { relationTo: target.relationTo, value: target.value },
+            newTab: target.newTab,
+            rel: target.rel,
+        }
+        : {
+            linkType: 'custom',
+            url: target.url,
+            newTab: target.newTab,
+            rel: target.rel,
+        },
+});
+/* ------------------------------------------------------------------ */
+/* sanitiser — the only door content comes through                     */
+/* ------------------------------------------------------------------ */
+const str = (v) => (typeof v === 'string' ? v : '');
+const idOf = (v) => {
+    if (typeof v === 'string' || typeof v === 'number')
+        return String(v);
+    if (v && typeof v === 'object' && 'id' in v) {
+        const id = v.id;
+        if (typeof id === 'string' || typeof id === 'number')
+            return String(id);
+    }
+    return '';
+};
+/**
+ * External URLs are restricted to schemes that cannot execute. `javascript:` and
+ * `data:` in an href are the classic stored-XSS payload, and this is the point at
+ * which they are refused — before storage, not before rendering.
+ */
+export const safeHref = (raw) => {
+    const url = raw.trim();
+    if (!url)
+        return null;
+    if (/^(https?:\/\/|mailto:|tel:)/i.test(url))
+        return url;
+    if (url.startsWith('/') && !url.startsWith('//'))
+        return url;
+    if (url.startsWith('#'))
+        return url;
+    // Bare domains typed by a human ("example.com/x") are the common case.
+    if (/^[\w-]+(\.[\w-]+)+(\/|$)/.test(url))
+        return `https://${url}`;
+    return null;
+};
+const cleanRel = (v) => {
+    if (!Array.isArray(v))
+        return null;
+    const rels = v.filter((r) => typeof r === 'string' && REL_VALUES.includes(r));
+    return rels.length ? [...new Set(rels)] : null;
+};
+const sanitizeChildren = (v, inline) => {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const child of v) {
+        const node = sanitizeNode(child, inline);
+        if (node)
+            out.push(node);
+    }
+    return out;
+};
+const sanitizeNode = (input, inline) => {
+    if (!input || typeof input !== 'object')
+        return null;
+    const n = input;
+    switch (n.type) {
+        case 'text': {
+            const value = str(n.text);
+            if (!value)
+                return null;
+            const format = typeof n.format === 'number' ? n.format & ALL_FORMATS : 0;
+            return text(value, format);
+        }
+        case 'linebreak':
+            return lineBreak();
+        case 'link':
+        case 'autolink': {
+            const children = sanitizeChildren(n.children, true);
+            if (!children.length)
+                return null;
+            const fields = (n.fields ?? {});
+            const newTab = Boolean(fields.newTab);
+            const rel = cleanRel(fields.rel);
+            if (fields.linkType === 'internal') {
+                const doc = (fields.doc ?? {});
+                const relationTo = LINKABLE.includes(doc.relationTo)
+                    ? doc.relationTo
+                    : null;
+                const value = idOf(doc.value);
+                if (!relationTo || !value)
+                    return null;
+                return linkNode({ linkType: 'internal', relationTo, value, newTab, rel }, children, str(n.id));
+            }
+            const url = safeHref(str(fields.url));
+            if (!url) {
+                // A refused URL must not silently drop the words it was wrapped around.
+                return children.length === 1 ? children[0] : paragraph(children);
+            }
+            return linkNode({ linkType: 'custom', url, newTab, rel }, children, str(n.id));
+        }
+        default:
+            break;
+    }
+    // Anything below here is block level and cannot appear inside a paragraph.
+    if (inline)
+        return null;
+    switch (n.type) {
+        case 'paragraph':
+            return paragraph(sanitizeChildren(n.children, true));
+        case 'heading': {
+            const tag = HEADING_TAGS.includes(n.tag) ? n.tag : 'h2';
+            const children = sanitizeChildren(n.children, true);
+            return children.length ? heading(tag, children) : null;
+        }
+        case 'quote': {
+            const children = sanitizeChildren(n.children, true);
+            return children.length ? quote(children) : null;
+        }
+        case 'list': {
+            const tag = n.tag === 'ol' || n.listType === 'number' ? 'ol' : 'ul';
+            const items = [];
+            if (Array.isArray(n.children)) {
+                for (const raw of n.children) {
+                    if (!raw || typeof raw !== 'object')
+                        continue;
+                    const item = raw;
+                    if (item.type !== 'listitem')
+                        continue;
+                    const children = sanitizeChildren(item.children, true);
+                    if (children.length)
+                        items.push(listItem(children, items.length + 1));
+                }
+            }
+            return items.length ? list(tag, items) : null;
+        }
+        case 'horizontalrule':
+            return horizontalRule();
+        case 'upload': {
+            const mediaId = idOf(n.value);
+            if (!mediaId || n.relationTo !== 'media')
+                return null;
+            return uploadNode(mediaId, str(n.id));
+        }
+        default:
+            return null;
+    }
+};
+/**
+ * Validate an editor payload into something safe to persist.
+ *
+ * Returns `emptyDoc()` rather than throwing for unusable input: a save must not
+ * fail because of a stray node, and an empty body is a legitimate draft state.
+ */
+export const sanitizeLexical = (input) => {
+    const root = input && typeof input === 'object' && 'root' in input
+        ? input.root
+        : null;
+    const children = sanitizeChildren(root?.children, false);
+    if (!children.length)
+        return emptyDoc();
+    return {
+        root: {
+            type: 'root',
+            children,
+            direction: 'ltr',
+            format: '',
+            indent: 0,
+            version: 1,
+        },
+    };
+};
+/** True when the document holds no words and no media — used for publish checks. */
+export const isEmptyDoc = (doc) => {
+    let found = false;
+    const walk = (node) => {
+        if (found || !node || typeof node !== 'object')
+            return;
+        const n = node;
+        if (n.type === 'upload' || n.type === 'horizontalrule')
+            found = true;
+        if (typeof n.text === 'string' && n.text.trim())
+            found = true;
+        if (Array.isArray(n.children))
+            n.children.forEach(walk);
+    };
+    walk(doc?.root);
+    return !found;
+};
+/* ------------------------------------------------------------------ */
+/* JSON -> editor HTML (one direction, editing surface only)           */
+/* ------------------------------------------------------------------ */
+const escapeHtml = (value) => value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+const FORMAT_TAGS = [
+    [FMT.code, 'code'],
+    [FMT.strikethrough, 's'],
+    [FMT.underline, 'u'],
+    [FMT.italic, 'em'],
+    [FMT.bold, 'strong'],
+];
+const textToHtml = (node) => {
+    const format = typeof node.format === 'number' ? node.format : 0;
+    let html = escapeHtml(str(node.text)).replace(/\n/g, '<br>');
+    for (const [bit, tag] of FORMAT_TAGS) {
+        if (format & bit)
+            html = `<${tag}>${html}</${tag}>`;
+    }
+    return html;
+};
+const mediaFromNode = (value) => {
+    const id = idOf(value);
+    if (!id)
+        return null;
+    const doc = value && typeof value === 'object' ? value : {};
+    const sizes = (doc.sizes ?? {});
+    const url = str(sizes.card?.url) || str(doc.url);
+    return { id, url, alt: str(doc.alt) };
+};
+const childrenToHtml = (node) => Array.isArray(node.children) ? node.children.map(nodeToHtml).join('') : '';
+const nodeToHtml = (node) => {
+    switch (node.type) {
+        case 'text':
+            return textToHtml(node);
+        case 'linebreak':
+            return '<br>';
+        case 'link':
+        case 'autolink': {
+            const fields = (node.fields ?? {});
+            const inner = childrenToHtml(node);
+            const newTab = fields.newTab ? ' data-new-tab="1"' : '';
+            if (fields.linkType === 'internal') {
+                const doc = (fields.doc ?? {});
+                const target = doc.value;
+                const slug = target && typeof target === 'object' ? escapeHtml(str(target.slug)) : '';
+                const collection = escapeHtml(str(doc.relationTo) || 'posts');
+                const label = collection === 'categories' ? 'category' : 'post';
+                return `<a href="#" data-link-type="internal" data-doc-collection="${collection}" data-doc-id="${escapeHtml(idOf(doc.value))}" data-doc-label="${label}: ${slug}"${newTab}>${inner}</a>`;
+            }
+            const href = safeHref(str(fields.url));
+            if (!href)
+                return inner;
+            return `<a href="${escapeHtml(href)}" data-link-type="custom"${newTab}>${inner}</a>`;
+        }
+        case 'paragraph': {
+            const inner = childrenToHtml(node);
+            return `<p>${inner || '<br>'}</p>`;
+        }
+        case 'heading': {
+            const tag = HEADING_TAGS.includes(node.tag) ? node.tag : 'h2';
+            return `<${tag}>${childrenToHtml(node)}</${tag}>`;
+        }
+        case 'quote':
+            return `<blockquote>${childrenToHtml(node)}</blockquote>`;
+        case 'list': {
+            const tag = node.tag === 'ol' || node.listType === 'number' ? 'ol' : 'ul';
+            const items = Array.isArray(node.children)
+                ? node.children
+                    .map((item) => `<li>${childrenToHtml(item)}</li>`)
+                    .join('')
+                : '';
+            return `<${tag}>${items}</${tag}>`;
+        }
+        case 'horizontalrule':
+            return '<hr>';
+        case 'upload': {
+            const media = mediaFromNode(node.value);
+            if (!media)
+                return '';
+            return (`<figure class="ed-figure" contenteditable="false" data-media-id="${escapeHtml(media.id)}"` +
+                ` data-node-id="${escapeHtml(str(node.id))}">` +
+                `<img src="${escapeHtml(media.url)}" alt="${escapeHtml(media.alt)}">` +
+                `<figcaption>${escapeHtml(media.alt || 'Image')}</figcaption>` +
+                `</figure>`);
+        }
+        default:
+            return '';
+    }
+};
+/**
+ * Render a stored document as the HTML the contenteditable surface starts from.
+ * Pass content read at depth >= 1 so upload nodes carry their populated media.
+ */
+export const lexicalToEditorHtml = (doc) => {
+    const root = doc?.root;
+    if (!root || !Array.isArray(root.children))
+        return '';
+    return root.children.map(nodeToHtml).join('');
+};

package/dist/lib/lexical-dom.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Browser side of the editor contract: the contenteditable DOM read back as a
+ * Lexical node tree.
+ *
+ * We walk the live DOM rather than serialising to an HTML string and parsing it
+ * again — there is no intermediate markup to get wrong, and anything the browser
+ * invented while the user typed (a stray <span style>, a pasted <font>) simply
+ * has no case here and disappears. The server re-validates the result anyway
+ * (see sanitizeLexical), so this file is a translator, not a security boundary.
+ */
+import { type LexDoc } from './lexical-doc';
+/**
+ * Read the editing surface as a document.
+ *
+ * Loose text typed straight into the root (which browsers do on the first
+ * keystroke of an empty editor) is gathered into a paragraph rather than lost.
+ */
+export declare const domToLexical: (root: HTMLElement) => LexDoc;
+//# sourceMappingURL=lexical-dom.d.ts.map