@bettercms-ai/richtext 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.3.0",
+  "version": "0.5.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.",
@@ -15,6 +15,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./html": "./src/html.ts",
+    "./heading": "./src/heading.ts",
     "./ingest": "./src/ingest.ts"
   },
   "scripts": {

package/src/from-lexical.ts

@@ -49,6 +49,7 @@ interface LexNode {
   checked?: boolean;
   url?: string;
   target?: string | null;
+  rel?: string | null;
   mentionId?: string;
   children?: unknown[];
   blockAttrs?: Record<string, unknown>;
@@ -102,6 +103,8 @@ function spansFrom(
     if (href) {
       const def: PortableTextMarkDef = { _type: PT_TYPES.link, _key: ctx.key(), href };
       if (typeof node.target === "string" && node.target) def.target = node.target;
+      // `rel` rides next to `target` — the importer keeps `prev`/`next` on pagination links.
+      if (typeof node.rel === "string" && node.rel) (def as PortableTextMarkDef & { rel?: string }).rel = node.rel;
       markDefs.push(def);
       marks = [...inherited, def._key];
     }

package/src/heading.ts

@@ -0,0 +1,132 @@
+/**
+ * A `richtext` block rendered AS a heading — `props.level` (1–6).
+ *
+ * Closes the gap between the two blocks that each held half of a title: `heading` has a level
+ * but a PLAIN `text` (the renderer escapes it, so `Equip Your Projects with <span
+ * class="text-yellow-500">ScrewFast</span>` loses its brand span), and `richtext` keeps the
+ * markup but had no level. With `level` set, the renderer emits `<hN>` around the rich copy
+ * instead of `<div class="bcms-text">`, so the marks survive AND the element is a real heading —
+ * the one site CSS sizes (`.bcms-page h1{font-size:…}` keys on the tag, not a class).
+ *
+ * WHY A LEVEL ON `richtext` RATHER THAN MARKS ON `heading.text`: `props.html` is already the one
+ * MARKUP slot every writer, override and coercion rule knows about (`MARKUP_PATH` in
+ * prop-value.ts, block-pass.ts and @bettercms-ai/ui/resolve). Making `heading.props.text` a
+ * Portable Text value would add a second markup slot, and every reader that does
+ * `String(p.text)` would print `[object Object]`. A number beside `html` touches nothing that
+ * reads `html`.
+ *
+ * ── The one rule both the validator and the renderer apply ──────────────────────────────────
+ * A heading holds PHRASING content only. `<h1><p>…</p><p>…</p></h1>` is not a heading, it is
+ * two paragraphs in a heading-shaped box, and it is what a naïve wrapper would emit for every
+ * editor that stores a lone line as `<p>…</p>`. So the value must reduce to ONE line of inline
+ * copy: a lone Portable Text text block, or html with at most a bare `<p>`/`<hN>` wrapper around
+ * inline markup. The write schema refuses anything else with a message naming the fix; the
+ * renderer, which also sees values no block schema checked (component overrides), falls back to
+ * the ordinary `<div class="bcms-text">` rather than emit invalid markup or drop copy.
+ */
+import { isPortableTextBlock, type PortableTextBlock } from "./types";
+import { readStructuredContent } from "./read";
+import { portableTextToHtml } from "./html";
+
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+/**
+ * The level a `richtext` block renders at, or null for "not a heading" — which is every block
+ * stored before this existed. No clamping: `heading` clamps because its level is always a
+ * heading, but here an absent/invalid level must mean the ordinary paragraph render, so a
+ * stray `0`, `null` or `""` cannot quietly turn body copy into an `<h1>`.
+ */
+export function richtextHeadingLevel(value: unknown): HeadingLevel | null {
+  if (value === null || value === undefined || value === "" || typeof value === "boolean") return null;
+  const n = Number(value);
+  return Number.isInteger(n) && n >= 1 && n <= 6 ? (n as HeadingLevel) : null;
+}
+
+/** Flow-content tags a heading may not contain. Phrasing tags (`span`, `a`, `strong`, `br`) pass. */
+const BLOCK_TAG =
+  /<\/?(?:address|article|aside|blockquote|details|dialog|div|dl|dd|dt|fieldset|figcaption|figure|footer|form|h[1-6]|header|hr|li|main|nav|ol|p|pre|section|summary|table|tbody|td|tfoot|th|thead|tr|ul)\b/i;
+
+/**
+ * An ATTRIBUTE-LESS lone `<p>` or `<hN>`. With attributes it is not unwrapped: dropping a
+ * `<p class="lead">` would silently change the design, so that value is refused instead.
+ */
+const LONE_WRAPPER = /^<(p|h[1-6])>([\s\S]*)<\/\1>$/i;
+
+/** `html` as the inner content of a heading, or null when it is not one line of inline copy. */
+export function inlineHeadingHtml(html: string): string | null {
+  const m = LONE_WRAPPER.exec(html.trim());
+  const inner = m ? m[2]! : html;
+  return BLOCK_TAG.test(inner) ? null : inner;
+}
+
+/**
+ * The ONE Portable Text block a heading can be made of, or null. A list item, a quote, a table
+ * or a second block is not a heading; `normal` and an existing `h1`–`h6` style are (the level
+ * on the block, not the style in the value, decides the tag).
+ */
+export function loneHeadingBlock(content: unknown[]): PortableTextBlock | null {
+  if (content.length !== 1) return null;
+  const node = content[0];
+  if (!isPortableTextBlock(node) || node.listItem !== undefined) return null;
+  const style = node.style ?? "normal";
+  return style === "normal" || /^h[1-6]$/.test(style) ? node : null;
+}
+
+/** True when these richtext props can render as a heading. What the write schema enforces. */
+export function canRenderAsHeading(props: Record<string, unknown>): boolean {
+  const structured = readStructuredContent(props);
+  if (structured) return loneHeadingBlock(structured) !== null;
+  return inlineHeadingHtml(typeof props.html === "string" ? props.html : "") !== null;
+}
+
+/**
+ * The level the VALUE spells for itself — a lone `<h3>` wrapper, or a lone `h3`-styled Portable
+ * Text block — or null when it names none (a `<p>`, bare inline copy, `normal`).
+ *
+ * `props.level` decides the tag, so a value that names a DIFFERENT one is a contradiction the
+ * write schema refuses rather than silently overriding: `{ html: "<h3>T</h3>", level: 1 }` would
+ * store as an h3 and render as an h1, and the editor's block-style control reads the VALUE.
+ * Same class of defect as `headingLevelMismatch` in publish-static.ts, one layer up.
+ */
+export function valueHeadingLevel(props: Record<string, unknown>): HeadingLevel | null {
+  const structured = readStructuredContent(props);
+  const tag = structured
+    ? loneHeadingBlock(structured)?.style
+    : LONE_WRAPPER.exec(String(props.html ?? "").trim())?.[1];
+  return tag && /^h[1-6]$/i.test(tag) ? (Number(tag[1]) as HeadingLevel) : null;
+}
+
+/**
+ * The inner markup + binding ADDRESS of a levelled richtext value, or null when the value is
+ * not one line of inline copy (the caller then renders it as ordinary rich text).
+ *
+ * Shared by all three renderers — render-page.ts, @bettercms-ai/next and @bettercms-ai/astro —
+ * because a heading assembled once per lane is exactly the divergence `parity.test.ts` exists to
+ * catch: three green suites and one lane shipping a `<div>` where the others ship an `<hN>`.
+ * The lanes differ only in how they SPELL attributes (a string, a React prop, an Astro spread),
+ * so the address comes back raw and each lane formats it the way it already does.
+ *
+ * The binding is the one each lane already emits, moved from the wrapper onto the heading so no
+ * `<div>` lands inside an `<hN>`: the html lane binds the whole field (`<blockId>__html`); the
+ * Portable Text lane binds the lone block by its `_key` (`<base>#<_key>`), exactly as
+ * `portableTextToHtml({ bindingBase })` addresses it — so the editor's writer is unchanged.
+ */
+export function headingParts(
+  /** Any block's props — `{ html?, content? }`, as loose as the three lanes' own types are. */
+  props: { html?: unknown },
+  base: string | null,
+): { inner: string; address: string | null } | null {
+  const structured = readStructuredContent(props);
+  if (structured) {
+    const node = loneHeadingBlock(structured);
+    if (!node) return null;
+    // Style normalised to `normal` so the serialiser emits a lone <p> that `inline` unwraps; the
+    // block's LEVEL, not any h1–h6 style inside the value, decides the tag.
+    return {
+      inner: portableTextToHtml([{ ...node, style: "normal" }], { inline: true }),
+      address: base && node._key ? `${base}#${node._key}` : null,
+    };
+  }
+  const inner = inlineHeadingHtml(String(props.html ?? ""));
+  return inner === null ? null : { inner, address: base };
+}

package/src/href.ts

@@ -11,6 +11,12 @@ const SAFE_HREF_SCHEMES = ["http:", "https:", "mailto:", "tel:"];
 /** The href if it is safe to emit, otherwise null. Callers render the label as plain text. */
 export function safeHref(raw: string): string | null {
   const trimmed = raw.trim();
+  // An in-page FRAGMENT (`#where-it-comes-from`) can only move within the page, so it is as safe
+  // as a site-relative path. Refusing it cost every imported Contents list its links: the
+  // importer's Lexical anchors were dropped on conversion, on ingest and on render alike
+  // (astro-sumi, 2026-09-14). No whitespace or markup characters, so it cannot break out of the
+  // attribute it is written into.
+  if (trimmed.startsWith("#")) return /^#[^\s<>"'`]*$/.test(trimmed) ? trimmed : null;
   // A site-relative path has no scheme to check and cannot navigate off-origin.
   if (trimmed.startsWith("/") && !trimmed.startsWith("//")) return trimmed;
   try {

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
@@ -102,7 +234,29 @@ export interface RenderOptions {
   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;
+};
+
+const buildComponents = (classes: HtmlClasses = {}): Partial<PortableTextHtmlComponents> => ({
+  block: tagOverrides(classes, STYLE_TAGS),
+  list: tagOverrides(classes, { bullet: "ul", number: "ol", check: "ul" }),
+  listItem: tagOverrides(classes, { bullet: "li", number: "li", check: "li" }),
   types: {
     [PT_TYPES.divider]: () => "<hr>",
     [PT_TYPES.table]: ({ value }) => tableHtml(value as PortableTextTable),
@@ -113,14 +267,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.
@@ -150,11 +312,21 @@ const components: Partial<PortableTextHtmlComponents> = {
      * renders the LABEL rather than deleting it — a blocked link must not lose the words.
      */
     [PT_TYPES.link]: ({ value, children }) => {
-      const v = (value ?? {}) as { href?: unknown; target?: unknown };
+      const v = (value ?? {}) as { href?: unknown; target?: unknown; rel?: unknown };
       const href = typeof v.href === "string" ? safeHref(v.href) : null;
       if (!href) return children;
-      const target = v.target === "_blank" ? ' target="_blank" rel="noopener noreferrer"' : "";
-      return `<a href="${esc(href)}"${target}>${children}</a>`;
+      // `rel` is author data too (the importer keeps `prev`/`next` on pagination links), so only
+      // plain link-type tokens pass; a new tab always adds noopener + noreferrer.
+      const rel = new Set(
+        typeof v.rel === "string" ? v.rel.toLowerCase().split(/\s+/).filter((t) => /^[a-z][a-z-]*$/.test(t)) : [],
+      );
+      const target = v.target === "_blank" ? ' target="_blank"' : "";
+      if (target) {
+        rel.add("noopener");
+        rel.add("noreferrer");
+      }
+      const relAttr = rel.size ? ` rel="${esc([...rel].join(" "))}"` : "";
+      return `<a${cls(classes, "a")} href="${esc(href)}"${target}${relAttr}>${children}</a>`;
     },
     /**
      * The site's own inline markup, written back out as itself.
@@ -185,13 +357,17 @@ 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();
 
 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);

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;
+}