@bettercms-ai/richtext 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "sideEffects": false,
   "description": "The one Portable Text contract for BetterCMS: schema, converters, and rendering. Shared by the backend, the dashboard and every delivery SDK.",

package/src/html.ts

@@ -1,5 +1,12 @@
 import { toHTML, type PortableTextHtmlComponents } from "@portabletext/to-html";
-import { PT_TYPES, type PortableText, type PortableTextTable } from "./types";
+import {
+  BUILTIN_EMBED_KEY,
+  BUILTIN_IMAGE_KEY,
+  PT_TYPES,
+  type PortableText,
+  type PortableTextTable,
+} from "./types";
+import { resolveVideoSource } from "./video";
 import { builtInTableToTable } from "./table";
 import { safeHref } from "./href";
 import { isStyledTag, styledAttrEntries } from "./styled";
@@ -84,12 +91,137 @@ function tableHtml(table: PortableTextTable): string {
   }</table>`;
 }
 
+/**
+ * The tags a caller may dress with the SITE'S OWN classes.
+ *
+ * Every tag this serialiser emits that a stylesheet is likely to target, and no attribute but
+ * `class`: an imported page's prose is `<p class="mt-4 text-slate-600">`, and a value that comes
+ * back as a bare `<p>` is the design deleted on the author's first save. The list is closed
+ * because each entry has to be a tag this file actually writes.
+ */
+export type ClassTag =
+  | "p" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6"
+  | "ul" | "ol" | "li" | "a" | "img" | "figure" | "blockquote";
+
+export type HtmlClasses = Partial<Record<ClassTag, string>>;
+
+/** ` class="…"`, or nothing. Values come from a derived page, so they are escaped like content. */
+const cls = (classes: HtmlClasses, tag: ClassTag): string => {
+  const value = classes[tag];
+  return value ? ` class="${esc(value)}"` : "";
+};
+
+/** Portable Text style → the tag it is written as. `normal` is a paragraph. */
+const STYLE_TAGS: Record<string, ClassTag> = {
+  normal: "p", blockquote: "blockquote",
+  h1: "h1", h2: "h2", h3: "h3", h4: "h4", h5: "h5", h6: "h6",
+};
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+/**
+ * A MEDIA url: `safeHref`, plus a plain relative path.
+ *
+ * An imported page is full of `images/hero.png` and `../media/clip.mp4`, and `safeHref` refuses
+ * a path with no leading slash — so every one of those images would render as nothing, which is
+ * the loss this whole pass exists to stop. Widened only for `<img>`, `<video>` and a poster:
+ * they load a picture, while an `<iframe>` frames a whole page and keeps the strict check.
+ * A colon or whitespace is refused, so no scheme (`javascript:`) can ride this path, and a
+ * PROTOCOL-RELATIVE `//host/clip.mp4` is refused with it — it is off-origin, not relative, and
+ * `safeHref` rejects the same shape for the same reason (href.ts:20).
+ */
+const mediaSrc = (raw: string): string | null =>
+  safeHref(raw) ?? (raw !== "" && !raw.startsWith("//") && !/[:\s]/.test(raw) ? raw : null);
+
+const fieldsOf = (value: unknown): Record<string, unknown> => {
+  const f = isRecord(value) ? value.fields : undefined;
+  return isRecord(f) ? f : {};
+};
+
+/**
+ * An image, as the markup a page was imported FROM.
+ *
+ * It used to render as `<div class="bcms-block">` — an empty marker — so an article's
+ * illustrations vanished from every delivered rendition while the stored value still held them.
+ * The payload is a URL and an alt string, which is everything an `<img>` needs; the marker was
+ * only ever right for the blocks that carry an unresolvable REFERENCE.
+ */
+function imageHtml(value: unknown, classes: HtmlClasses): string {
+  const f = fieldsOf(value);
+  const src = mediaSrc(str(f.src));
+  if (!src) return "";
+  const caption = str(f.caption);
+  const img = `<img${cls(classes, "img")} src="${esc(src)}" alt="${esc(str(f.alt))}">`;
+  return `<figure${cls(classes, "figure")}>${img}${
+    caption ? `<figcaption>${esc(caption)}</figcaption>` : ""
+  }</figure>`;
+}
+
+/** The attributes a framed embed needs to be safe: no scripts of ours, no payment APIs. */
+const IFRAME_ATTRS = ' loading="lazy" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen';
+
+/**
+ * An embed — a provider player, a map, a form. `<iframe>` and nothing else.
+ *
+ * `safeHref` is the whole gate: it admits http(s) and site-relative URLs only, so a
+ * `javascript:` src cannot reach the attribute. An embed whose URL it refuses renders nothing
+ * rather than a broken frame.
+ */
+function embedHtml(value: unknown, _classes: HtmlClasses): string {
+  const f = fieldsOf(value);
+  const src = safeHref(str(f.url) || str(f.src));
+  if (!src) return "";
+  const title = str(f.title);
+  return `<iframe src="${esc(src)}"${title ? ` title="${esc(title)}"` : ""}${IFRAME_ATTRS}></iframe>`;
+}
+
+/**
+ * A video: the file itself where the URL is one, the provider's player where it is a provider's.
+ *
+ * `resolveVideoSource` is the single answer to "what is this URL", shared with the editor that
+ * drew the same block — see video.ts. A URL it does not recognise still plays as a `<video>`:
+ * an uploaded asset is served from a PATH, which is not parseable as a URL at all, and refusing
+ * it would make every uploaded video render as nothing.
+ */
+function videoHtml(value: unknown, _classes: HtmlClasses): string {
+  const v = isRecord(value) ? value : {};
+  const raw = str(v.src);
+  const src = mediaSrc(raw);
+  if (!src) return "";
+  const title = str(v.title);
+  const titleAttr = title ? ` title="${esc(title)}"` : "";
+  const resolved = resolveVideoSource(raw);
+  if (resolved?.kind === "iframe") {
+    return `<iframe src="${esc(resolved.src)}"${titleAttr}${IFRAME_ATTRS}></iframe>`;
+  }
+  const poster = mediaSrc(str(v.poster));
+  return `<video controls src="${esc(src)}"${poster ? ` poster="${esc(poster)}"` : ""}${titleAttr}></video>`;
+}
+
+/** A downloadable document. The NAME is the link text — a file with no name has nothing to click. */
+function fileHtml(value: unknown, classes: HtmlClasses): string {
+  const v = isRecord(value) ? value : {};
+  const src = safeHref(str(v.src));
+  if (!src) return "";
+  const name = str(v.name) || src.split("/").pop() || "Download";
+  return `<a${cls(classes, "a")} href="${esc(src)}" download>${esc(name)}</a>`;
+}
+
 export interface RenderOptions {
   /**
    * Render a single value with no wrapping `<p>`, for a field whose consumer supplies its own
    * heading or button. Mirrors `allowMultipleParagraphs: false` and the old `toInlineHtml`.
    */
   inline?: boolean;
+  /**
+   * The site's own class per tag, for a value derived FROM that site.
+   *
+   * A derived `document` field records what the imported page's prose wore
+   * (`config.htmlClasses`), and every rendition of that value — the envelope's html mirror, the
+   * published page, the canvas — has to put it back on or the page restyles itself the first
+   * time anyone saves.
+   */
+  classes?: HtmlClasses;
   /**
    * `<blockId>__<prop>`. Present ⇒ wrap each top-level node in an element carrying
    * `data-bcms-field="<base>#<_key>"`, which is what makes ONE PARAGRAPH inside a rich-text
@@ -98,11 +230,53 @@ export interface RenderOptions {
    * Wrapping at the top level rather than inside the block components is deliberate: a block
    * component only ever sees TEXT blocks, so a divider or an embedded image would get no
    * address — and those are exactly the nodes an editor most wants to click.
+   *
+   * List items are the one exception: a run of them renders as ONE `<ul>`/`<ol>` and the address
+   * sits on each `<li>`, because a wrapper per item would split the list into one-item lists.
    */
   bindingBase?: string;
 }
 
-const components: Partial<PortableTextHtmlComponents> = {
+/**
+ * A tag override per style/list, for the tags the caller gave a class — and NOTHING else.
+ *
+ * Only the dressed tags are overridden, so a call with no classes renders through the library's
+ * own components byte for byte. That is what keeps every already-published rendition stable:
+ * the html on an envelope is compared against stored markup by the parity gate.
+ */
+const tagOverrides = <T extends string>(
+  classes: HtmlClasses,
+  tags: Record<T, ClassTag>,
+): Record<string, (p: { children?: string }) => string> => {
+  const out: Record<string, (p: { children?: string }) => string> = {};
+  for (const [name, tag] of Object.entries(tags) as [string, ClassTag][]) {
+    if (!classes[tag]) continue;
+    out[name] = ({ children }) => `<${tag}${cls(classes, tag)}>${children ?? ""}</${tag}>`;
+  }
+  return out;
+};
+
+/** The per-node address `portableTextToHtml({ bindingBase })` stamps. "" for a node with no key. */
+const bindingAttrs = (base: string, key: unknown): string =>
+  typeof key === "string" && key
+    ? ` data-bcms-field="${esc(base)}#${esc(key)}" data-bcms-kind="richtext"`
+    : "";
+
+/**
+ * `keys` is the set of `_key`s the value actually carries: to-html invents one (`li-0-1`) for an
+ * item that has none, and an invented key is an address that resolves to nothing.
+ */
+const buildComponents = (
+  classes: HtmlClasses = {},
+  binding?: { base: string; keys: ReadonlySet<unknown> },
+): Partial<PortableTextHtmlComponents> => ({
+  block: tagOverrides(classes, STYLE_TAGS),
+  list: tagOverrides(classes, { bullet: "ul", number: "ol", check: "ul" }),
+  // With a base, every item carries its own address ON the `<li>` — see `bindingBase`.
+  listItem: binding
+    ? ({ value, children }: { value: { _key?: unknown }; children?: string }) =>
+        `<li${cls(classes, "li")}${binding.keys.has(value._key) ? bindingAttrs(binding.base, value._key) : ""}>${children ?? ""}</li>`
+    : tagOverrides(classes, { bullet: "li", number: "li", check: "li" }),
   types: {
     [PT_TYPES.divider]: () => "<hr>",
     [PT_TYPES.table]: ({ value }) => tableHtml(value as PortableTextTable),
@@ -113,14 +287,22 @@ const components: Partial<PortableTextHtmlComponents> = {
       const cls = lang ? ` class="language-${lang}"` : "";
       return `<pre><code${cls}>${esc(code)}</code></pre>`;
     },
+    [PT_TYPES.video]: ({ value }) => videoHtml(value, classes),
+    [PT_TYPES.file]: ({ value }) => fileHtml(value, classes),
     /**
-     * A generic embedded block. It renders as a marker rather than as content, because the
-     * payload it carries (a component reference, a media id) has to be RESOLVED against the
-     * project before it means anything, and this serialiser has no project. Emitting the
-     * marker keeps the node addressable and visible instead of silently rendering nothing.
+     * A generic embedded block. A block whose payload this serialiser can READ renders as
+     * content; one carrying a reference it would have to resolve against a project renders as a
+     * marker, which keeps the node addressable and visible instead of drawing nothing.
+     *
+     * 🔴 AN IMAGE AND AN EMBED ARE READABLE, and rendering them as markers was silent loss: an
+     * imported article's illustrations and its YouTube embed disappeared from every delivered
+     * rendition while the stored value still held them. Their payload is a URL — there is
+     * nothing to resolve.
      */
     [PT_TYPES.block]: ({ value }) => {
       const v = value as { schemaKey?: unknown };
+      if (v.schemaKey === BUILTIN_IMAGE_KEY) return imageHtml(value, classes);
+      if (v.schemaKey === BUILTIN_EMBED_KEY) return embedHtml(value, classes);
       /**
        * A pre-P1c TABLE is the exception to the marker, and it has to be: it resolves against
        * nothing. Its rows are text, held right here, so a marker would DELETE visible content.
@@ -164,7 +346,7 @@ const components: Partial<PortableTextHtmlComponents> = {
         rel.add("noreferrer");
       }
       const relAttr = rel.size ? ` rel="${esc([...rel].join(" "))}"` : "";
-      return `<a href="${esc(href)}"${target}${relAttr}>${children}</a>`;
+      return `<a${cls(classes, "a")} href="${esc(href)}"${target}${relAttr}>${children}</a>`;
     },
     /**
      * The site's own inline markup, written back out as itself.
@@ -195,25 +377,44 @@ const components: Partial<PortableTextHtmlComponents> = {
    */
   unknownMark: ({ children }) => children,
   unknownType: ({ children }) => children ?? "",
-};
+});
+
+/** The undressed components, built once: the overwhelming majority of calls pass no classes. */
+const defaultComponents = buildComponents();
+
+const isListItem = (node: unknown): boolean =>
+  isRecord(node) && node._type === "block" && typeof node.listItem === "string" && !!node.listItem;
 
 export function portableTextToHtml(
   value: PortableText | null | undefined,
   opts: RenderOptions = {},
 ): string {
   if (!Array.isArray(value) || value.length === 0) return "";
+  const components = opts.classes ? buildComponents(opts.classes) : defaultComponents;
 
   if (opts.bindingBase) {
-    const base = esc(opts.bindingBase);
-    return value
-      .map((node) => {
-        const inner = toHTML([node] as never, { components });
-        // A node with no key cannot be addressed. Render it rather than dropping it — an
-        // unaddressable paragraph is a small loss, a missing one is content disappearing.
-        if (!node._key) return inner;
-        return `<div data-bcms-field="${base}#${esc(node._key)}" data-bcms-kind="richtext">${inner}</div>`;
-      })
-      .join("");
+    const base = opts.bindingBase;
+    const bound = buildComponents(opts.classes, { base, keys: new Set(value.map((n) => n._key)) });
+    const out: string[] = [];
+    for (let i = 0; i < value.length; ) {
+      const node = value[i];
+      // A RUN of list items renders as ONE list, each `<li>` carrying its own address. Wrapping
+      // items one by one gave every item its own `<ol>`, so numbering restarted at 1 on every line
+      // and bullets sat a list-margin apart — the canvas no longer looked like the site.
+      if (isListItem(node)) {
+        let end = i + 1;
+        while (end < value.length && isListItem(value[end])) end++;
+        out.push(toHTML(value.slice(i, end) as never, { components: bound }));
+        i = end;
+        continue;
+      }
+      const inner = toHTML([node] as never, { components });
+      // A node with no key cannot be addressed. Render it rather than dropping it — an
+      // unaddressable paragraph is a small loss, a missing one is content disappearing.
+      out.push(node._key ? `<div${bindingAttrs(base, node._key)}>${inner}</div>` : inner);
+      i++;
+    }
+    return out.join("");
   }
 
   const html = toHTML(value as never, { components });

package/src/index.ts

@@ -9,3 +9,4 @@ export * from "./styled";
 export * from "./read";
 export * from "./accept";
 export * from "./features";
+export * from "./video";

package/src/ingest.ts

@@ -1,6 +1,12 @@
 import { htmlToPortableText as ptHtmlToPortableText, type DeserializerRule } from "@portabletext/html";
 import { compileSchema } from "@portabletext/schema";
-import { PT_TYPES, type PortableText, type PortableTextBlock } from "./types";
+import {
+  BUILTIN_EMBED_KEY,
+  BUILTIN_IMAGE_KEY,
+  PT_TYPES,
+  type PortableText,
+  type PortableTextBlock,
+} from "./types";
 import { randomKey, isValidKey, type KeyGenerator } from "./key";
 import { safeHref } from "./href";
 import { isStyledTag, styledAttrsOf, type StyledMarkDef } from "./styled";
@@ -222,6 +228,118 @@ function styledRule(key: KeyGenerator): DeserializerRule {
   };
 }
 
+/**
+ * ── MEDIA, WHICH USED TO PRODUCE NO NODE AT ALL ──────────────────────────────────────────
+ *
+ * `<img>`, `<video>`, `<iframe>` and a PDF link have no place in the compiled schema, so a
+ * prose container ingested as one document lost every one of them: the deserialiser emits
+ * nothing for a tag it cannot map, and an article came back as its paragraphs only. These four
+ * rules are what make importing a page's body lossless.
+ *
+ * Gated the same way the table rule is, and for the same reason — a custom rule runs BEFORE the
+ * compiled schema and its output is taken as given, so an ungated rule is a way past a field's
+ * Accept config.
+ */
+
+/** The `<img>`, `<video>` or `<iframe>` a `<figure>` is wrapped around — the figure's subject. */
+const mediaIn = (el: Element): Element | null =>
+  el.querySelector("img,video,iframe");
+
+const captionOf = (el: Element): string =>
+  el.nodeName.toLowerCase() === "figure"
+    ? (el.querySelector("figcaption")?.textContent ?? "").trim()
+    : "";
+
+/** `<video src>` or `<video><source src></video>` — both spellings are ordinary markup. */
+const videoSrc = (el: Element): string =>
+  (el.getAttribute("src") ?? el.querySelector("source")?.getAttribute("src") ?? "").trim();
+
+/**
+ * An `<a>` that IS its line — nothing else visible beside it in its parent.
+ *
+ * A PDF link in the middle of a sentence is a link, and turning it into a block would tear the
+ * sentence in half. A link on a line of its own is a download button, which is what the `file`
+ * block draws.
+ */
+const wholeLine = (el: Element): boolean => {
+  const parent = el.parentElement;
+  if (!parent) return false;
+  return [...parent.childNodes].every(
+    (n) => n === el || (n.nodeType === 3 && (n as Text).data.trim() === ""),
+  );
+};
+
+const PDF_HREF = /\.pdf(?:[?#]|$)/i;
+
+/**
+ * `<figure>`/`<img>`/`<video>`/`<iframe>`/`<a href=*.pdf>` → the block object each one is.
+ *
+ * ONE rule rather than four, because a `<figure>` has to decide which of them it is wrapping
+ * and four rules would each have to ask that question. `undefined` hands the node back to the
+ * deserialiser untouched, which is what keeps a mid-sentence PDF link a link.
+ */
+function mediaRule(key: KeyGenerator, schema: PtSchema | undefined): DeserializerRule {
+  const allows = (name: string): boolean =>
+    !schema || schema.blockObjects.some((o) => o.name === name);
+  return {
+    deserialize(node: Node, _next, createBlock) {
+      if (!isElement(node)) return undefined;
+      const tag = node.nodeName.toLowerCase();
+      if (tag === "a") {
+        if (!allows(PT_TYPES.file)) return undefined;
+        const href = (node.getAttribute("href") ?? "").trim();
+        if (!PDF_HREF.test(href) || !safeHref(href) || !wholeLine(node)) return undefined;
+        const name = (node.textContent ?? "").trim() || href.split("/").pop() || "Download";
+        return createBlock({ _type: PT_TYPES.file, _key: key(), src: href, name });
+      }
+      const el = tag === "figure" ? mediaIn(node) : node;
+      if (!el) return undefined;
+      const subject = el.nodeName.toLowerCase();
+      if (subject !== "img" && subject !== "video" && subject !== "iframe") return undefined;
+      const caption = captionOf(node);
+
+      if (subject === "video") {
+        if (!allows(PT_TYPES.video)) return undefined;
+        const src = videoSrc(el);
+        if (!src) return undefined;
+        const poster = (el.getAttribute("poster") ?? "").trim();
+        return createBlock({
+          _type: PT_TYPES.video,
+          _key: key(),
+          src,
+          ...(poster ? { poster } : {}),
+          ...(caption ? { title: caption } : {}),
+        });
+      }
+      // Image and embed keep the GENERIC block object under their existing `builtin:` keys —
+      // thousands of stored values already spell them that way, and nothing is gained by a
+      // migration when the renderer reads both shapes from the same fields.
+      if (!allows(PT_TYPES.block)) return undefined;
+      const src = (el.getAttribute("src") ?? "").trim();
+      if (!src) return undefined;
+      if (subject === "iframe") {
+        const title = (el.getAttribute("title") ?? "").trim() || caption;
+        return createBlock({
+          _type: PT_TYPES.block,
+          _key: key(),
+          schemaKey: BUILTIN_EMBED_KEY,
+          fields: { url: src, ...(title ? { title } : {}) },
+        });
+      }
+      return createBlock({
+        _type: PT_TYPES.block,
+        _key: key(),
+        schemaKey: BUILTIN_IMAGE_KEY,
+        fields: {
+          src,
+          alt: (el.getAttribute("alt") ?? "").trim(),
+          ...(caption ? { caption } : {}),
+        },
+      });
+    },
+  };
+}
+
 /**
  * Does this field's schema carry the `styled` annotation?
  *
@@ -263,6 +381,7 @@ export function htmlToPortableText(html: string, opts: IngestOptions = {}): Port
      */
     rules: [
       ...(allowsTables(opts.schema) ? [tableRule(key, (cell) => htmlToPortableText(cell, opts))] : []),
+      mediaRule(key, opts.schema),
       ...(allowsStyled(opts.schema) ? [styledRule(key)] : []),
     ],
     keyGenerator: key,

package/src/schema.ts

@@ -146,6 +146,39 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
       ],
     });
   }
+  /**
+   * Video and file, the two media kinds with a type of their own.
+   *
+   * They ride the Accept elements that already gate the same capability — `embed` is "Video
+   * embed" and a downloadable document is a link — so no stored field config has to change for
+   * an author to get them. Image, embed and columns keep the generic block above: their
+   * rendition is a straight read of their own fields, while a video's depends on what its URL
+   * turns out to be, and a file's is a link the author must be able to name.
+   */
+  if (has("embed")) {
+    blockObjects.push({
+      name: PT_TYPES.video,
+      title: "Video",
+      fields: [
+        { name: "src", type: "string" },
+        { name: "poster", type: "string" },
+        { name: "provider", type: "string" },
+        { name: "title", type: "string" },
+      ],
+    });
+  }
+  if (has("link")) {
+    blockObjects.push({
+      name: PT_TYPES.file,
+      title: "File",
+      fields: [
+        { name: "src", type: "string" },
+        { name: "name", type: "string" },
+        { name: "size", type: "number" },
+        { name: "mime", type: "string" },
+      ],
+    });
+  }
   /**
    * The table, and it is a REAL block object now rather than the capability marker it used to be.
    *

package/src/types.ts

@@ -131,6 +131,32 @@ export interface PortableTextTable extends PortableTextObject {
   legacy?: boolean;
 }
 
+/**
+ * A video block. `src` is an uploaded asset's path or a provider URL; `provider` and `poster`
+ * are what an author set, never something this package infers — the renderer asks
+ * `resolveVideoSource` about `src` and draws what it answers.
+ *
+ * 🔴 THE SHAPE IS A CONTRACT WITH THE EDITOR. The dashboard writes these fields (`ptNodes.tsx`,
+ * `formNodes.tsx`) and this package renders them; spelling it once here is what stops the two
+ * sides disagreeing about a key and rendering an empty box.
+ */
+export interface PortableTextVideo extends PortableTextObject {
+  _type: "video";
+  src: string;
+  poster?: string;
+  provider?: string;
+  title?: string;
+}
+
+/** A downloadable file. `name` is the link's text — a file with no name has nothing to click. */
+export interface PortableTextFile extends PortableTextObject {
+  _type: "file";
+  src: string;
+  name: string;
+  size?: number;
+  mime?: string;
+}
+
 export const isPortableTextBlock = (n: unknown): n is PortableTextBlock =>
   !!n && typeof n === "object" && (n as PortableTextNode)._type === "block";
 
@@ -168,6 +194,16 @@ export const PT_TYPES = {
   mention: "bcmsMention",
   divider: "bcmsDivider",
   code: "bcmsCode",
+  /**
+   * A video — an uploaded file or a provider URL. DEDICATED rather than another `schemaKey` on
+   * the generic block, because a video is the one media node whose rendition depends on its own
+   * payload: the same field is a `<video>` for an mp4 and a provider `<iframe>` for a YouTube
+   * link (@see resolveVideoSource). The generic block carries a reference this package cannot
+   * resolve; a video carries a URL it can.
+   */
+  video: "video",
+  /** A downloadable document — a PDF, a spec sheet. `<a href download>`, nothing more. */
+  file: "file",
   /**
    * A table. Spelled `table`, unprefixed, because that is what every other Portable Text
    * producer calls one — the Sanity-shaped `{_type:"table", rows}` this platform used to refuse
@@ -221,8 +257,25 @@ export const STORABLE_BLOCK_TYPES: ReadonlySet<string> = new Set<string>([
   PT_TYPES.code,
   PT_TYPES.divider,
   PT_TYPES.mention,
+  PT_TYPES.video,
+  PT_TYPES.file,
 ]);
 
+/**
+ * The `schemaKey`s the GENERIC block object carries for the two media kinds that keep it.
+ *
+ * Image and embed stay on `bcmsBlock` because thousands of stored values already spell them
+ * that way and a migration buys nothing: unlike a video, their rendition is a straight read of
+ * their own fields. Named here because this package now RENDERS them — it used to emit a marker
+ * — and a renderer keyed on a string literal typed at the call site is the drift this file
+ * exists to prevent.
+ *
+ * The embed's key is historically `builtin:video`: it is the "Video embed" block, and it
+ * predates the dedicated `video` type by two years of content.
+ */
+export const BUILTIN_IMAGE_KEY = "builtin:image" as const;
+export const BUILTIN_EMBED_KEY = "builtin:video" as const;
+
 /**
  * Top-level nodes whose `_type` this platform cannot store or render, in document order.
  *

package/src/video.ts

@@ -0,0 +1,74 @@
+/**
+ * What a video URL actually IS — a provider embed, a playable file, or nothing we will render.
+ *
+ * Moved here from the dashboard (`src/lib/richtext/builtInBlocks.ts`) because the same question
+ * is asked on both sides of one value: the server serialises a `video` block into the published
+ * page, and the editor draws the same block in the canvas. Two implementations disagreeing about
+ * whether a link is a YouTube embed means the author sees one thing and the visitor another.
+ *
+ * 🔴 ALLOWLIST, NOT A GUESS. An unknown URL returns null rather than becoming an `<iframe src>`:
+ * this value reaches a published page, and a frame pointing at arbitrary author input on the
+ * tenant's own origin is the one thing a renderer must not mint by accident.
+ */
+export type ResolvedVideoSource = {
+  kind: "iframe" | "video";
+  src: string;
+  provider: "YouTube" | "Vimeo" | "Video file";
+};
+
+const videoId = (value: string | null | undefined): string | null =>
+  value && /^[a-zA-Z0-9_-]{6,32}$/.test(value) ? value : null;
+
+/** Only known embed providers or direct video files become executable media elements. */
+export function resolveVideoSource(value: unknown): ResolvedVideoSource | null {
+  if (typeof value !== "string" || !value.trim()) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(value.trim());
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+
+  const host = parsed.hostname.toLowerCase().replace(/^www\./, "");
+  let id: string | null = null;
+  if (host === "youtu.be") id = videoId(parsed.pathname.split("/").filter(Boolean)[0]);
+  if (host === "youtube.com" || host === "m.youtube.com" || host === "youtube-nocookie.com") {
+    id = videoId(
+      parsed.searchParams.get("v")
+      ?? parsed.pathname.match(/^\/(?:embed|shorts)\/([^/?#]+)/)?.[1],
+    );
+  }
+  if (id) {
+    return {
+      kind: "iframe",
+      src: `https://www.youtube-nocookie.com/embed/${id}`,
+      provider: "YouTube",
+    };
+  }
+
+  if (host === "vimeo.com" || host === "player.vimeo.com") {
+    // Hand-rolled reverse scan, not `findLast`: this package's consumers compile against
+    // libs older than ES2023, where `Array.prototype.findLast` is not declared.
+    const segments: string[] = parsed.pathname.split("/").filter(Boolean);
+    let vimeoId: string | null = null;
+    for (let i = segments.length - 1; i >= 0; i -= 1) {
+      if (/^\d+$/.test(segments[i]!)) {
+        vimeoId = segments[i]!;
+        break;
+      }
+    }
+    if (vimeoId) {
+      return {
+        kind: "iframe",
+        src: `https://player.vimeo.com/video/${vimeoId}`,
+        provider: "Vimeo",
+      };
+    }
+  }
+
+  if (/\.(?:m4v|mp4|og[gv]|webm)$/i.test(parsed.pathname)) {
+    return { kind: "video", src: parsed.toString(), provider: "Video file" };
+  }
+  return null;
+}