@lemonadecms/client 0.1.1 → 0.2.1

package/bin/schema-extensions.mjs

@@ -0,0 +1,6 @@
+// Negotiation affects schema tooling only; ordinary delivery/SDK reads retain
+// their existing response contract and zero runtime dependency boundary.
+export const schemaExtensionKeys = Object.freeze([
+  'relationships', 'rich_text', 'unique_identifiers',
+]);
+export const schemaExtensions = 'relationships.v1,rich-text.v2,unique-identifiers.v1';

package/bin/unique-identifiers.mjs

@@ -0,0 +1,50 @@
+import {schemaExtensionKeys} from './schema-extensions.mjs';
+
+const identifier = /^[a-z][a-z0-9_]{0,47}$/;
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const exact = (value, keys) => record(value) && Object.keys(value).length === keys.length &&
+  keys.every(key => Object.hasOwn(value, key));
+const invalid = () => { throw new Error('Invalid unique-identifier schema extension.'); };
+
+export function uniqueIdentifierDefinitions(schema) {
+  // Inline declarations belong to management definitions, never portable
+  // delivery exports. Requiring the extension prevents silently lost metadata.
+  let nodes = 0;
+  function fields(values, depth = 0) {
+    if (!Array.isArray(values) || values.length > 24 || depth > 3) invalid();
+    for (const field of values) {
+      if (++nodes > 150000 || !record(field) || Object.hasOwn(field, 'unique')) invalid();
+      const components = field.components || [];
+      if (!Array.isArray(components) || components.length > 12) invalid();
+      for (const component of components) {
+        if (!record(component)) invalid();
+        fields(component.fields, depth + 1);
+      }
+    }
+  }
+  for (const model of schema.models) fields(model.fields);
+  if (!Object.hasOwn(schema, 'extensions')) return [];
+  if (!record(schema.extensions) || Object.keys(schema.extensions).length === 0 ||
+      Object.keys(schema.extensions).some(key => !schemaExtensionKeys.includes(key))) invalid();
+  if (!Object.hasOwn(schema.extensions, 'unique_identifiers')) return [];
+  const extension = schema.extensions.unique_identifiers;
+  if (!exact(extension, ['version', 'definitions']) || extension.version !== 1 ||
+      !Array.isArray(extension.definitions) || extension.definitions.length > 6144) invalid();
+  const models = new Map(schema.models.map(model => [model.key, model]));
+  const seen = new Set();
+  for (const definition of extension.definitions) {
+    if (!exact(definition, ['model', 'field']) ||
+        !['model', 'field'].every(key => typeof definition[key] === 'string' && identifier.test(definition[key]))) invalid();
+    const field = models.get(definition.model)?.fields.find(field => field.key === definition.field);
+    const identity = `${definition.model}.${definition.field}`;
+    if (!field || field.type !== 'text' || field.localized === true || seen.has(identity)) invalid();
+    seen.add(identity);
+  }
+  return extension.definitions;
+}
+
+export function modelsWithUniqueIdentifiers(schema) {
+  const definitions = new Set(uniqueIdentifierDefinitions(schema).map(value => `${value.model}.${value.field}`));
+  return schema.models.map(model => ({...model, fields: model.fields.map(field =>
+    definitions.has(`${model.key}.${field.key}`) ? {...field, unique: true} : field)}));
+}

package/dist/composer.d.ts

@@ -0,0 +1,27 @@
+/** Optional browser-only Composer bridge. Website code owns rendering.
+ * Enable only on an authenticated preview. No credentials or framework imports.
+ */
+export interface ComposerUpdate {
+    channel: string;
+    entry: string;
+    locale: string;
+    root: string;
+    fields: Record<string, unknown>;
+    model_version: number;
+    entry_version: number;
+    renderer_revision: string;
+}
+export interface VisualComposerOptions {
+    studioOrigin: string;
+    channel: string;
+    entry: string;
+    locale: string;
+    roots: readonly string[];
+    components: readonly string[];
+    rendererRevision: string;
+    root?: HTMLElement;
+    /** Return a synchronous commit function; the bridge calls it only for the
+     * latest successful render. Honor signal and keep DOM changes in commit. */
+    render: (update: ComposerUpdate, signal: AbortSignal) => Promise<() => void>;
+}
+export declare function enableVisualComposer(options: VisualComposerOptions): () => void;

package/dist/composer.js

@@ -0,0 +1,240 @@
+export function enableVisualComposer(options) {
+    const keyPattern = /^[a-z][a-z0-9_]{0,47}$/;
+    const idPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    const { studioOrigin, channel, entry, locale, roots, components, rendererRevision } = options;
+    let origin;
+    try {
+        origin = new URL(studioOrigin);
+    }
+    catch {
+        return () => { };
+    }
+    if (origin.origin !== studioOrigin || !['http:', 'https:'].includes(origin.protocol) ||
+        window.parent === window || !idPattern.test(channel) || !idPattern.test(entry) ||
+        !/^[a-zA-Z0-9-]{2,20}$/.test(locale) || !/^[a-f0-9]{64}$/.test(rendererRevision) ||
+        roots.length < 1 || roots.length > 24 || components.length < 1 || components.length > 128 ||
+        ![...roots, ...components].every(key => keyPattern.test(key)) || typeof options.render !== 'function') {
+        return () => { };
+    }
+    const root = options.root ?? document.body;
+    let active = true;
+    let enabled = false;
+    let selectedRoot = '';
+    let generation = '';
+    let latest = 0;
+    let busy = false;
+    let pending;
+    let controller;
+    const originals = new Map();
+    const send = (type, extra = {}) => window.parent.postMessage({ type, version: 1, channel, entry, locale, root: selectedRoot, ...extra }, studioOrigin);
+    const announce = (request) => send('lemonade:composer-ready', {
+        roots: [...roots], components: [...components], renderer_revision: rendererRevision,
+        ...(request ? { request } : {}),
+    });
+    const restore = () => {
+        for (const [element, attrs] of originals)
+            for (const [name, value] of attrs) {
+                if (value === null)
+                    element.removeAttribute(name);
+                else
+                    element.setAttribute(name, value);
+            }
+        originals.clear();
+    };
+    const enhance = () => {
+        restore();
+        if (!enabled)
+            return;
+        for (const element of Array.from(root.querySelectorAll('[data-lemonade-block]')).slice(0, 100)) {
+            const id = element.dataset.lemonadeBlock ?? '';
+            if (!idPattern.test(id))
+                continue;
+            const attrs = new Map();
+            for (const name of ['tabindex', 'role', 'aria-label', 'draggable', 'style'])
+                attrs.set(name, element.getAttribute(name));
+            originals.set(element, attrs);
+            if (!element.matches('a[href],button,input,textarea,select'))
+                element.setAttribute('role', 'button');
+            element.tabIndex = 0;
+            element.setAttribute('aria-label', `Edit ${element.dataset.lemonadeName ?? 'section'} in Studio`);
+            element.draggable = true;
+            element.style.outline = '1px dashed currentColor';
+            element.style.outlineOffset = '3px';
+        }
+    };
+    const run = async () => {
+        if (!active || !enabled || busy || !pending)
+            return;
+        const work = pending;
+        pending = undefined;
+        busy = true;
+        const abort = new AbortController();
+        controller = abort;
+        let timeout;
+        try {
+            const commit = await Promise.race([
+                options.render(work.update, abort.signal),
+                new Promise((_, reject) => { timeout = setTimeout(() => { abort.abort(); reject(new Error('Composer render timed out')); }, 10000); }),
+            ]);
+            if (active && enabled && !abort.signal.aborted && work.sequence === latest && work.generation === generation) {
+                if (typeof commit !== 'function')
+                    throw new Error('Composer renderer must return a commit function');
+                commit();
+                enhance();
+                send('lemonade:composer-rendered', { sequence: work.sequence, generation });
+            }
+        }
+        catch {
+            if (active && enabled && work.sequence === latest && work.generation === generation) {
+                send('lemonade:composer-error', { sequence: work.sequence, generation });
+            }
+        }
+        finally {
+            clearTimeout(timeout);
+            if (controller === abort)
+                controller = undefined;
+            busy = false;
+            void run();
+        }
+    };
+    const disable = () => {
+        enabled = false;
+        pending = undefined;
+        controller?.abort();
+        restore();
+    };
+    const receive = (event) => {
+        if (!active || event.source !== window.parent || event.origin !== studioOrigin || event.data?.channel !== channel)
+            return;
+        const data = event.data;
+        if (data.type === 'lemonade:preview-connect') {
+            if (typeof data.request === 'string' && data.request.length <= 64)
+                announce(data.request);
+            return;
+        }
+        if (data.version !== 1 || data.entry !== entry || data.locale !== locale)
+            return;
+        if (data.type === 'lemonade:composer-disable') {
+            disable();
+            return;
+        }
+        if (data.type === 'lemonade:composer-enable') {
+            if (!roots.includes(data.root) || typeof data.generation !== 'string' || data.generation.length > 64)
+                return;
+            if (generation !== data.generation) {
+                controller?.abort();
+                pending = undefined;
+                latest = 0;
+            }
+            enabled = true;
+            generation = data.generation;
+            selectedRoot = data.root;
+            enhance();
+            return;
+        }
+        if (!enabled || data.generation !== generation || data.root !== selectedRoot)
+            return;
+        if (data.type === 'lemonade:composer-highlight' && idPattern.test(data.id)) {
+            for (const element of originals.keys()) {
+                element.style.outlineWidth = element.dataset.lemonadeBlock === data.id ? '3px' : '1px';
+            }
+            return;
+        }
+        if (data.type === 'lemonade:composer-drop') {
+            if (!Number.isFinite(data.x) || !Number.isFinite(data.y) || data.x < 0 || data.y < 0 ||
+                data.x >= window.innerWidth || data.y >= window.innerHeight)
+                return;
+            const element = document.elementFromPoint(data.x, data.y);
+            if (element)
+                emitDrop(element, data.payload);
+            return;
+        }
+        if (data.type !== 'lemonade:composer-update' || !Number.isSafeInteger(data.sequence) || data.sequence <= latest ||
+            !data.fields || typeof data.fields !== 'object' || Array.isArray(data.fields) ||
+            data.renderer_revision !== rendererRevision || !Number.isSafeInteger(data.model_version) || !Number.isSafeInteger(data.entry_version))
+            return;
+        try {
+            if (new TextEncoder().encode(JSON.stringify(data.fields)).length > 65536)
+                return;
+        }
+        catch {
+            return;
+        }
+        latest = data.sequence;
+        pending = { update: { channel, entry, locale, root: selectedRoot, fields: data.fields,
+                model_version: data.model_version, entry_version: data.entry_version, renderer_revision: rendererRevision }, sequence: latest, generation };
+        controller?.abort();
+        void run();
+    };
+    const select = (event) => {
+        if (!enabled || !(event.target instanceof Element))
+            return;
+        if (event instanceof KeyboardEvent && !['Enter', ' '].includes(event.key))
+            return;
+        if (event instanceof MouseEvent && (event.button !== 0 || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey))
+            return;
+        const element = event.target.closest('[data-lemonade-block]');
+        if (!element || !originals.has(element))
+            return;
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        send('lemonade:composer-select', { id: element.dataset.lemonadeBlock, root: selectedRoot, generation });
+    };
+    const dragstart = (event) => {
+        if (!enabled || !(event.target instanceof Element))
+            return;
+        const element = event.target.closest('[data-lemonade-block]');
+        if (!element || !originals.has(element))
+            return;
+        event.dataTransfer?.setData('application/x-lemonade-composer', JSON.stringify({ id: element.dataset.lemonadeBlock, channel, root: selectedRoot }));
+    };
+    const dragover = (event) => {
+        if (enabled && event.target instanceof Element && event.target.closest('[data-lemonade-slot]'))
+            event.preventDefault();
+    };
+    const emitDrop = (element, data) => {
+        const slot = element.closest('[data-lemonade-slot]');
+        const path = slot?.dataset.lemonadeSlot;
+        if (!slot || !path || path.length > 512 || !root.contains(slot) || !data ||
+            !(idPattern.test(data.id ?? '') || keyPattern.test(data.component ?? '')))
+            return;
+        if (path !== selectedRoot && !path.startsWith(selectedRoot + '.'))
+            return;
+        const block = element.closest('[data-lemonade-block]');
+        send('lemonade:composer-action', { action: data.id ? 'move' : 'add', id: data.id, component: data.component,
+            target: path, before: block?.dataset.lemonadeBlock, root: selectedRoot, generation });
+    };
+    const drop = (event) => {
+        if (!enabled || !(event.target instanceof Element))
+            return;
+        try {
+            const raw = event.dataTransfer?.getData('application/x-lemonade-composer') ?? '';
+            if (raw.length > 1024)
+                return;
+            const data = JSON.parse(raw);
+            if (data.channel !== channel || data.root !== selectedRoot)
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            emitDrop(event.target, data);
+        }
+        catch { /* Foreign drag payloads are not composition commands. */ }
+    };
+    window.addEventListener('message', receive);
+    root.addEventListener('click', select, true);
+    root.addEventListener('keydown', select, true);
+    root.addEventListener('dragstart', dragstart);
+    root.addEventListener('dragover', dragover);
+    root.addEventListener('drop', drop);
+    announce();
+    return () => {
+        active = false;
+        disable();
+        window.removeEventListener('message', receive);
+        root.removeEventListener('click', select, true);
+        root.removeEventListener('keydown', select, true);
+        root.removeEventListener('dragstart', dragstart);
+        root.removeEventListener('dragover', dragover);
+        root.removeEventListener('drop', drop);
+    };
+}

package/dist/index.d.ts

@@ -1,10 +1,11 @@
-import type { CMSClient, CMSClientOptions, ModelMap, UntypedModels } from "./types.js";
+import type { CMSClient, CMSClientOptions, ModelMap, RelationshipMap, UntypedModels } from "./types.js";
 export * from "./errors.js";
 export type { RemoteValue } from "./types.js";
-export type { CountOptions, GetManyOptions, ContentSearch, SearchOptions, TextField } from "./types.js";
+export type { CMSQueryDefaults, RelationshipMap, CountOptions, GetManyOptions, ContentSearch, SearchOptions, TextField } from "./types.js";
 export type { CMSClient, CMSClientOptions, ContentCollection, ContentEntry, ContentPage, ContentTypeIdentity, ContentEnvironment, ListOptions, FindOneOptions, PaginationOptions, ContentFilter, ContentSort } from "./types.js";
 /** Published content only. Framework environment variables must be passed explicitly. */
-export declare function createCMSClient<Models extends ModelMap<Models> = UntypedModels>(options: CMSClientOptions): CMSClient<Models>;
+export declare function createCMSClient<Models extends ModelMap<Models> = UntypedModels, Relationships extends RelationshipMap<Models> = {}>(options: CMSClientOptions<Models>): CMSClient<Models, Relationships>;
 export { imageSrcSet } from "./images.js";
 export type { ContentRendition } from "./images.js";
-export { richTextToHtml, richTextToPlainText } from "./rich-text.js";
+export { richTextToHtml, richTextToPlainText, externalMediaDescriptor } from "./rich-text.js";
+export type { ExternalMediaDescriptor, ExternalMediaProvider } from "./rich-text.js";

package/dist/index.js

@@ -14,4 +14,4 @@ export function createCMSClient(options) {
     return createTransport(options, options?.publicKey, "content");
 }
 export { imageSrcSet } from "./images.js";
-export { richTextToHtml, richTextToPlainText } from "./rich-text.js";
+export { richTextToHtml, richTextToPlainText, externalMediaDescriptor } from "./rich-text.js";

package/dist/rich-text-v2.d.ts

@@ -0,0 +1,20 @@
+export type ExternalMediaProvider = 'youtube' | 'vimeo' | 'spotify' | 'soundcloud';
+export interface ExternalMediaDescriptor {
+    provider: ExternalMediaProvider;
+    url: string;
+    embedUrl: string;
+    title: string;
+    caption: string;
+    transcript: string;
+    poster: {
+        id: string;
+        url: string;
+        alt: string;
+    } | null;
+}
+/** The only relative URL accepted by first-party renderers is the private website asset proxy. */
+export declare function safeRichTextURL(value: unknown, image: boolean): string | null;
+/** Pure player metadata. This performs no fetches, creates no iframe and grants no playback consent. */
+export declare function externalMediaDescriptor(value: unknown): ExternalMediaDescriptor;
+/** Strict v2 validation protects renderers from silently dropping unknown future nodes. */
+export declare function assertRichTextV2(value: unknown): void;

package/dist/rich-text-v2.js

@@ -0,0 +1,242 @@
+import { CMSResponseError } from './errors.js';
+const encoder = new TextEncoder();
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+const identifier = /^[a-z][a-z0-9_]{0,47}$/;
+const imageTypes = ['image/jpeg', 'image/png', 'image/webp', 'image/gif'];
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const own = (value, keys) => Object.keys(value).every(key => keys.includes(key));
+function invalid() {
+    throw new CMSResponseError('Invalid or unsupported rich-text v2 document.');
+}
+const validString = (value, max, min = 0) => typeof value === 'string' && !/[\u0000\ud800-\udfff]/u.test(value) &&
+    encoder.encode(value).byteLength >= min && encoder.encode(value).byteLength <= max;
+/** The only relative URL accepted by first-party renderers is the private website asset proxy. */
+export function safeRichTextURL(value, image) {
+    if (typeof value !== 'string' || value.length > (image ? 4096 : 2048) ||
+        /[\s\\\u0000-\u0020\u007f-\u009f]/u.test(value))
+        return null;
+    if (image && /^\/lemonade\/preview\/assets\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}(?:\?[^#]+)?$/i.test(value)) {
+        const params = new URL(value, 'https://preview.invalid').searchParams;
+        const keys = [];
+        params.forEach((_value, key) => keys.push(key));
+        const recipes = ['hero-640', 'hero-1280', 'card-320', 'card-640', 'social-1200'];
+        if (keys.length > 4 || new Set(keys).size !== keys.length ||
+            keys.some(key => !['rendition', 'v', 'impact', 'composition'].includes(key)) ||
+            (params.has('rendition') && !recipes.includes(params.get('rendition'))) ||
+            (params.has('v') && !/^[A-Za-z0-9_-]{43}$/.test(params.get('v'))) ||
+            (params.has('impact') && !['before', 'after'].includes(params.get('impact'))) ||
+            (params.has('composition') && (params.get('composition').length > 2048 ||
+                !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(params.get('composition')))))
+            return null;
+        return value;
+    }
+    if (!/^https?:\/\//i.test(value) && (image || !/^mailto:/i.test(value)))
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.username || url.password)
+            return null;
+        if ((url.protocol === 'https:' || url.protocol === 'http:') && url.hostname)
+            return value;
+        return !image && url.protocol === 'mailto:' && url.pathname ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function external(attrs) {
+    if (!record(attrs) || !own(attrs, ['provider', 'url', 'title', 'caption', 'transcript', 'poster']) ||
+        !validString(attrs.title, 500, 1) || !/[^\p{White_Space}]/u.test(attrs.title) ||
+        !validString(attrs.caption, 2000) || !validString(attrs.transcript, 20_000) ||
+        !validString(attrs.url, 2048, 1) ||
+        (attrs.poster !== undefined && (typeof attrs.poster !== 'string' || !uuid.test(attrs.poster))))
+        invalid();
+    const { provider, url, title, caption, transcript } = attrs;
+    let embedUrl;
+    let match;
+    if (provider === 'youtube' && (match = url.match(/^https:\/\/www\.youtube\.com\/watch\?v=([A-Za-z0-9_-]{11})$/))) {
+        embedUrl = `https://www.youtube-nocookie.com/embed/${match[1]}`;
+    }
+    else if (provider === 'vimeo' && (match = url.match(/^https:\/\/vimeo\.com\/([1-9][0-9]{0,11})$/))) {
+        embedUrl = `https://player.vimeo.com/video/${match[1]}?dnt=1`;
+    }
+    else if (provider === 'spotify' && (match = url.match(/^https:\/\/open\.spotify\.com\/episode\/([A-Za-z0-9]{22})$/))) {
+        embedUrl = `https://open.spotify.com/embed/episode/${match[1]}`;
+    }
+    else if (provider === 'soundcloud' && (match = url.match(/^https:\/\/soundcloud\.com\/([A-Za-z0-9][A-Za-z0-9_-]{0,199})\/([A-Za-z0-9][A-Za-z0-9_-]{0,199})$/)) &&
+        !['sets', 'playlists', 'discover', 'charts', 'search', 'you'].includes(match[1].toLowerCase()) &&
+        !['sets', 'tracks', 'albums', 'reposts', 'likes', 'popular-tracks'].includes(match[2].toLowerCase())) {
+        embedUrl = `https://w.soundcloud.com/player/?url=${encodeURIComponent(url)}&auto_play=false`;
+    }
+    else
+        invalid();
+    return { provider: provider, url, embedUrl, title, caption, transcript };
+}
+/** Pure player metadata. This performs no fetches, creates no iframe and grants no playback consent. */
+export function externalMediaDescriptor(value) {
+    if (!record(value) || value.type !== 'externalMedia' || !own(value, ['type', 'attrs', 'resource']))
+        invalid();
+    const descriptor = external(value.attrs);
+    const attrs = value.attrs;
+    const resource = value.resource;
+    let poster = null;
+    if (typeof attrs.poster === 'string' && record(resource) && typeof resource.id === 'string' &&
+        attrs.poster.toLowerCase() === resource.id.toLowerCase() && typeof resource.content_type === 'string' && imageTypes.includes(resource.content_type)) {
+        const url = safeRichTextURL(resource.url, true);
+        const metadata = record(resource.metadata) ? resource.metadata : {};
+        if (url)
+            poster = { id: attrs.poster, url, alt: validString(metadata.alt, 2000) ? metadata.alt : '' };
+    }
+    return { ...descriptor, poster };
+}
+/** Strict v2 validation protects renderers from silently dropping unknown future nodes. */
+export function assertRichTextV2(value) {
+    if (!record(value) || value.version !== 2 || !own(value, ['version', 'document']))
+        invalid();
+    let remaining = 500, embeds = 20, bytes = 65_536;
+    const string = (value, max, min = 0) => {
+        if (!validString(value, max, min))
+            invalid();
+        bytes -= encoder.encode(value).byteLength;
+        if (bytes < 0)
+            invalid();
+        return value;
+    };
+    function node(value, context, depth) {
+        if (!record(value) || depth > 8 || --remaining < 0 || typeof value.type !== 'string')
+            invalid();
+        const children = (next, min = 0) => {
+            const list = value.content ?? [];
+            if (!Array.isArray(list) || list.length < min || list.length > 200)
+                invalid();
+            for (const child of list)
+                node(child, next, depth + 1);
+            return list;
+        };
+        if (context === 'inline' || context === 'code') {
+            if (context === 'inline' && value.type === 'hardBreak' && own(value, ['type']))
+                return;
+            if (value.type !== 'text' || !own(value, context === 'code' ? ['type', 'text'] : ['type', 'text', 'marks']))
+                invalid();
+            string(value.text, 20_000, 1);
+            if (context === 'code')
+                return;
+            const marks = value.marks ?? [];
+            if (!Array.isArray(marks) || marks.length > 6)
+                invalid();
+            const seen = new Set();
+            for (const mark of marks) {
+                if (!record(mark) || typeof mark.type !== 'string' || seen.has(mark.type))
+                    invalid();
+                seen.add(mark.type);
+                if (mark.type === 'link') {
+                    if (!own(mark, ['type', 'attrs']) || !record(mark.attrs) || !own(mark.attrs, ['href']) ||
+                        !safeRichTextURL(string(mark.attrs.href, 2048, 1), false))
+                        invalid();
+                }
+                else if (!['bold', 'italic', 'underline', 'strike', 'code'].includes(mark.type) || !own(mark, ['type']))
+                    invalid();
+            }
+            return;
+        }
+        if (context === 'root') {
+            if (value.type !== 'doc' || !own(value, ['type', 'content']))
+                invalid();
+            children('block');
+            return;
+        }
+        if (context === 'list') {
+            if (value.type !== 'listItem' || !own(value, ['type', 'content']) || !Array.isArray(value.content) ||
+                !record(value.content[0]) || value.content[0].type !== 'paragraph')
+                invalid();
+            children('item', 1);
+            return;
+        }
+        if (context === 'row' || context === 'headerRow') {
+            if (value.type !== (context === 'headerRow' ? 'tableHeader' : 'tableCell') ||
+                !own(value, ['type', 'content']) || !Array.isArray(value.content) || value.content.length !== 1)
+                invalid();
+            children('cell', 1);
+            return;
+        }
+        if (value.type === 'paragraph' && ['block', 'item', 'quote', 'cell'].includes(context)) {
+            if (!own(value, ['type', 'content']))
+                invalid();
+            children('inline');
+            return;
+        }
+        if (['bulletList', 'orderedList'].includes(value.type) && ['block', 'item'].includes(context)) {
+            if (!own(value, ['type', 'content', 'attrs']) ||
+                (value.attrs !== undefined && (!record(value.attrs) || !own(value.attrs, ['start']) ||
+                    Object.keys(value.attrs).length > 0 && (value.type !== 'orderedList' || value.attrs.start !== 1))))
+                invalid();
+            children('list', 1);
+            return;
+        }
+        if (context !== 'block')
+            invalid();
+        if (value.type === 'heading') {
+            if (!own(value, ['type', 'attrs', 'content']) || !record(value.attrs) ||
+                !own(value.attrs, ['level']) || typeof value.attrs.level !== 'number' || ![2, 3, 4].includes(value.attrs.level))
+                invalid();
+            children('inline');
+            return;
+        }
+        if (value.type === 'blockquote') {
+            if (!own(value, ['type', 'content']))
+                invalid();
+            children('quote', 1);
+            return;
+        }
+        if (value.type === 'codeBlock') {
+            if (!own(value, ['type', 'attrs', 'content']) || !record(value.attrs) || !own(value.attrs, ['language']))
+                invalid();
+            const language = string(value.attrs.language, 32);
+            if (language !== '' && !/^[A-Za-z][A-Za-z0-9_+.#-]{0,31}$/.test(language))
+                invalid();
+            children('code');
+            return;
+        }
+        if (value.type === 'table') {
+            if (!own(value, ['type', 'attrs', 'content']) || !record(value.attrs) ||
+                !own(value.attrs, ['caption', 'header']) || typeof value.attrs.header !== 'boolean' ||
+                !Array.isArray(value.content) || value.content.length < 1 || value.content.length > 20)
+                invalid();
+            string(value.attrs.caption, 500);
+            let columns = 0;
+            for (let index = 0; index < value.content.length; index++) {
+                const row = value.content[index];
+                if (!record(row) || --remaining < 0 || depth + 1 > 8 || row.type !== 'tableRow' ||
+                    !own(row, ['type', 'content']) || !Array.isArray(row.content) || row.content.length < 1 || row.content.length > 6)
+                    invalid();
+                columns ||= row.content.length;
+                if (row.content.length !== columns)
+                    invalid();
+                for (const cell of row.content)
+                    node(cell, index === 0 && value.attrs.header ? 'headerRow' : 'row', depth + 2);
+            }
+            return;
+        }
+        if (!['image', 'entry', 'externalMedia'].includes(value.type) || --embeds < 0)
+            invalid();
+        if (value.type === 'externalMedia') {
+            if (!own(value, ['type', 'attrs', 'resource']))
+                invalid();
+            external(value.attrs);
+            const attrs = value.attrs;
+            string(attrs.title, 500, 1);
+            string(attrs.caption, 2000);
+            string(attrs.transcript, 20_000);
+            return;
+        }
+        if (!own(value, ['type', 'attrs', 'resource']) || !record(value.attrs) ||
+            !own(value.attrs, value.type === 'image' ? ['id', 'alt'] : ['id', 'target']) ||
+            typeof value.attrs.id !== 'string' || !uuid.test(value.attrs.id))
+            invalid();
+        if (value.type === 'image')
+            string(value.attrs.alt, 2000);
+        else if (typeof value.attrs.target !== 'string' || !identifier.test(value.attrs.target))
+            invalid();
+    }
+    node(value.document, 'root', 0);
+}

package/dist/rich-text.d.ts

@@ -1,4 +1,6 @@
-/** Escaped HTML for rich-text v1, including safe expanded images/entry captions. */
+export { externalMediaDescriptor } from './rich-text-v2.js';
+export type { ExternalMediaDescriptor, ExternalMediaProvider } from './rich-text-v2.js';
+/** Escaped HTML; v2 rejects malformed/unknown nodes. External media remains a static card. */
 export declare function richTextToHtml(value: unknown): string;
 /** Authored text with block/hard-break newlines; excludes embeds and link URLs. */
 export declare function richTextToPlainText(value: unknown): string;