@bettercms-ai/richtext 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.2.0",
+  "version": "0.4.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/accept.ts

@@ -1,5 +1,6 @@
 import { RICH_TEXT_CAPABILITY_MANIFEST, type RichTextFeature } from './features'
 import type { AllowEntry } from './features'
+import { STYLED_TAGS } from './styled'
 
 /**
  * The Accept model — which HTML elements a rich-text field is allowed to contain.
@@ -123,7 +124,11 @@ export const DEFAULT_RICHTEXT_CONFIG: RichTextConfig = {
 
 /** The tag allowlist the sanitiser enforces for a given Accept set. */
 export function allowedTags(accept: AcceptElement[]): string[] {
-  const tags = new Set<string>(['span']) // spans carry marks; never the reason content is stripped
+  // `span` carries marks and is never the reason content is stripped; the rest of `STYLED_TAGS`
+  // is the site's OWN inline markup, admitted on the same terms and for the same reason the
+  // `styled` annotation is granted to every field — see `styled.ts`. Gating them on an Accept
+  // element would let the sanitiser undo the round trip the annotation exists to make lossless.
+  const tags = new Set<string>(['span', ...STYLED_TAGS])
   for (const el of accept) for (const t of ELEMENT_TAGS[el] ?? []) tags.add(t)
   return [...tags]
 }

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

@@ -2,6 +2,7 @@ import { toHTML, type PortableTextHtmlComponents } from "@portabletext/to-html";
 import { PT_TYPES, type PortableText, type PortableTextTable } from "./types";
 import { builtInTableToTable } from "./table";
 import { safeHref } from "./href";
+import { isStyledTag, styledAttrEntries } from "./styled";
 
 /**
  * Portable Text → HTML.
@@ -149,11 +150,40 @@ 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 href="${esc(href)}"${target}${relAttr}>${children}</a>`;
+    },
+    /**
+     * The site's own inline markup, written back out as itself.
+     *
+     * Every value here came from content, so every value here is escaped and the tag is
+     * re-checked against `STYLED_TAGS` — a markDef can arrive from an import, the Management
+     * API or an AI write, and `<${value.tag}>` with no check is how a stored string becomes a
+     * `<script>`. An unrecognised tag renders its CHILDREN rather than nothing: the words are
+     * the author's, the wrapper is only the design.
+     */
+    [PT_TYPES.styled]: ({ value, children }) => {
+      const v = (value ?? {}) as { tag?: unknown; className?: unknown; attrs?: unknown };
+      const tag = typeof v.tag === "string" ? v.tag.toLowerCase() : "";
+      if (!isStyledTag(tag)) return children;
+      const cls = typeof v.className === "string" && v.className ? ` class="${esc(v.className)}"` : "";
+      const attrs = styledAttrEntries(v.attrs)
+        .map(([name, val]) => ` ${name}="${esc(val)}"`)
+        .join("");
+      return `<${tag}${cls}${attrs}>${children}</${tag}>`;
     },
     highlight: ({ children }) => `<mark>${children}</mark>`,
     "strike-through": ({ children }) => `<s>${children}</s>`,

package/src/index.ts

@@ -5,6 +5,7 @@ export * from "./key";
 export * from "./from-lexical";
 export * from "./plain";
 export * from "./table";
+export * from "./styled";
 export * from "./read";
 export * from "./accept";
 export * from "./features";

package/src/ingest.ts

@@ -3,6 +3,7 @@ import { compileSchema } from "@portabletext/schema";
 import { 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";
 import type { PtSchema } from "./schema";
 
 /**
@@ -180,6 +181,58 @@ function tableRule(key: KeyGenerator, ingestCell: (html: string) => PortableText
   };
 }
 
+/**
+ * An inline element Portable Text does not model → the `styled` annotation.
+ *
+ * 🔴 THE REASON THIS EXISTS is measured, not theoretical: 13–28% of the visible text on an
+ * imported site sits inside a `<span class>` in a heading or a paragraph, and none of it could
+ * be made editable while this round trip was lossy — the span came back as bare words and the
+ * design died on the author's first save. `derive-schema` refused those elements ON PURPOSE
+ * for exactly that reason.
+ *
+ * A `<span>` with nothing on it is NOT annotated: it carries no design, so recording it would
+ * mint a markDef per stray wrapper and bloat every value for nothing. The other tags are
+ * annotated bare, because there the TAG is the design (`<small>`, `<sup>`, `<kbd>`).
+ *
+ * Decorator tags (`b/strong`, `i/em`, `u`, `s`, `mark`, `code`) are deliberately absent: they
+ * have real decorators and the standard rules run right after this one.
+ *
+ * `__annotation` is the deserialiser's own internal placeholder — the same one its built-in
+ * link rule returns — so nesting composes for free: `<strong><span class>` comes back as one
+ * span carrying both marks, in that order, and renders back out nested the same way.
+ */
+function styledRule(key: KeyGenerator): DeserializerRule {
+  return {
+    deserialize(el: Node, next) {
+      if (!isElement(el)) return undefined;
+      const tag = el.nodeName.toLowerCase();
+      if (!isStyledTag(tag)) return undefined;
+      const className = el.getAttribute("class")?.trim() || undefined;
+      const attrs = styledAttrsOf(el);
+      if (tag === "span" && !className && !attrs) return undefined;
+      const markDef: StyledMarkDef = {
+        _type: PT_TYPES.styled,
+        _key: key(),
+        tag,
+        ...(className ? { className } : {}),
+        ...(attrs ? { attrs } : {}),
+      };
+      return { _type: "__annotation", markDef, children: next(el.childNodes) } as never;
+    },
+  };
+}
+
+/**
+ * Does this field's schema carry the `styled` annotation?
+ *
+ * Gated for the same reason the table rule is: a custom rule runs BEFORE the compiled schema
+ * and its output is taken as given, so an unconditional rule would be a way past the Accept
+ * config. `ptSchemaFor` grants `styled` to every field, because it is the site's design rather
+ * than an authoring capability — but a caller passing a hand-built schema still decides.
+ */
+const allowsStyled = (schema: PtSchema | undefined): boolean =>
+  !schema || schema.annotations.some((a) => a.name === PT_TYPES.styled);
+
 /** Does this field's schema carry the table block object? Asked by name, not by capability. */
 const allowsTables = (schema: PtSchema | undefined): boolean =>
   !schema || schema.blockObjects.some((o) => o.name === PT_TYPES.table);
@@ -208,7 +261,10 @@ export function htmlToPortableText(html: string, opts: IngestOptions = {}): Port
      * for an image or an embed alike, so gating on it would let a `<table>` into a field that
      * accepts only images.
      */
-    ...(allowsTables(opts.schema) ? { rules: [tableRule(key, (cell) => htmlToPortableText(cell, opts))] } : {}),
+    rules: [
+      ...(allowsTables(opts.schema) ? [tableRule(key, (cell) => htmlToPortableText(cell, opts))] : []),
+      ...(allowsStyled(opts.schema) ? [styledRule(key)] : []),
+    ],
     keyGenerator: key,
   });
   return normalise(converted, key);

package/src/schema.ts

@@ -81,7 +81,27 @@ export function ptSchemaFor(accept: readonly AcceptElement[]): PtSchema {
     if (d && has(el)) decorators.push(d);
   }
 
-  const annotations: PtAnnotation[] = [];
+  /**
+   * `styled` is granted to EVERY field, and that is not a leak in the Accept model.
+   *
+   * It is not a capability an author can reach — no toolbar button offers it, and no ingest
+   * mints one from author input. It records the SITE'S OWN inline markup (`<span class>`,
+   * `<time datetime>`) so that a heading an importer bound as a field survives being saved.
+   * Gating it on an Accept element would mean a field that happens not to accept `b` silently
+   * strips the design out of the copy it is holding — the loss this annotation exists to stop,
+   * moved one layer down.
+   */
+  const annotations: PtAnnotation[] = [
+    {
+      name: PT_TYPES.styled,
+      title: "Styled",
+      fields: [
+        { name: "tag", type: "string" },
+        { name: "className", type: "string" },
+        { name: "attrs", type: "object" },
+      ],
+    },
+  ];
   if (has("link") || has("internalLink")) {
     annotations.push({
       name: PT_TYPES.link,

package/src/styled.ts

@@ -0,0 +1,138 @@
+/**
+ * The `styled` annotation — a site's own inline markup, carried through Portable Text.
+ *
+ * WHY IT EXISTS. An imported site writes `<h1>Notes from a <span class="serif italic">web
+ * studio</span></h1>`. Portable Text models `strong`/`em`/`underline`/`strike`/`code`/
+ * `highlight` and `link`, and NOTHING ELSE inline — so that span had no node to become,
+ * `unknownMark` rendered its children, and the class was gone the first time an author saved.
+ * That loss is why `derive-schema` deliberately refused to bind any heading containing a
+ * `<span class>`: a field that destroys the design on save is worse than no field at all.
+ *
+ * So this is NOT an authoring mark. There is no toolbar button and no editing UI: it is the
+ * site's design, recorded so the round trip is lossless, and it rides along with whatever the
+ * author actually types inside it.
+ *
+ * ── The attribute allowlist IS the threat model ──────────────────────────────────────────
+ * A markDef is data, and data reaches this platform from an import, the Management API, MCP
+ * and AI writes. Rendering an arbitrary attribute bag would be an XSS primitive wearing a
+ * design system's clothes, so exactly four names plus `data-*` are admitted, and the render
+ * escapes every value. `id` is refused because it is an addressing surface (a duplicate id
+ * breaks anchors and label association), `data-bcms-*` because those attributes ARE the Visual
+ * Editor's binding addresses and content must not be able to mint one. `style` is admitted but
+ * NOT passed through — its value is a language of its own, bounded by `safeStyle` below.
+ */
+
+/** Inline tags a `styled` annotation may wear. Nothing outside this list is ever rendered. */
+export const STYLED_TAGS = ["span", "small", "sup", "sub", "kbd", "abbr", "time"] as const;
+
+export type StyledTag = (typeof STYLED_TAGS)[number];
+
+const TAG_SET: ReadonlySet<string> = new Set<string>(STYLED_TAGS);
+
+export const isStyledTag = (tag: unknown): tag is StyledTag =>
+  typeof tag === "string" && TAG_SET.has(tag);
+
+/**
+ * Attribute names a `styled` annotation may carry.
+ *
+ * Presentational or descriptive only. Never `href`/`src` (a navigation or fetch surface),
+ * never `id` (an addressing surface), never `on*` (script), and never `data-bcms-*` — those
+ * are binding addresses the editor reads, and content that could write one could point an
+ * author's edit at somebody else's field.
+ */
+const ATTR_NAMES: ReadonlySet<string> = new Set(["title", "datetime", "style", "aria-label"]);
+
+const DATA_ATTR = /^data-[a-z][a-z0-9-]*$/;
+
+export const isStyledAttr = (name: string): boolean =>
+  ATTR_NAMES.has(name) || (DATA_ATTR.test(name) && !name.startsWith("data-bcms-"));
+
+/**
+ * CSS an inline run may carry: how the words LOOK inside their own box, and nothing else.
+ *
+ * `style` is the one admitted attribute whose value is itself a language, so the tag allowlist
+ * buys nothing here — a bare passthrough lets any markDef write
+ * `position:fixed;inset:0;z-index:9999`, which is a full-viewport overlay over the published
+ * page (clickjacking, defacement) minted by anyone who can write content, and
+ * `background:url(https://…)` which fetches a third-party URL on every page view. Neither is a
+ * design an import needs, so neither is on the list. Properties that only paint glyphs are.
+ *
+ * Values are checked as well as names, because `url()`, a CSS escape (`\75 rl(`), a comment and
+ * `expression()` are all ways to smuggle a fetch past a name check.
+ */
+const STYLE_PROPS: ReadonlySet<string> = new Set([
+  "color", "background-color", "opacity",
+  "font", "font-family", "font-size", "font-style", "font-weight", "font-variant",
+  "font-feature-settings", "font-variation-settings",
+  "letter-spacing", "line-height", "word-spacing", "white-space", "word-break",
+  "text-align", "text-decoration", "text-decoration-color", "text-decoration-line",
+  "text-decoration-style", "text-transform", "text-underline-offset", "vertical-align",
+]);
+
+const STYLE_VALUE_BAN = /url\(|expression\(|@import|\\|\/\*|[<>]/i;
+
+/**
+ * The declarations of a `style` attribute that survive, rejoined — or undefined when none do.
+ * Custom properties (`--brand`) are kept: they paint nothing on their own, and a site's own CSS
+ * is what decides whether they mean anything.
+ */
+export function safeStyle(css: string): string | undefined {
+  const kept: string[] = [];
+  for (const declaration of css.split(";")) {
+    const at = declaration.indexOf(":");
+    if (at < 0) continue;
+    const name = declaration.slice(0, at).trim().toLowerCase();
+    const value = declaration.slice(at + 1).trim();
+    if (!name || !value) continue;
+    if (!name.startsWith("--") && !STYLE_PROPS.has(name)) continue;
+    if (STYLE_VALUE_BAN.test(value)) continue;
+    kept.push(`${name}:${value}`);
+  }
+  return kept.length ? kept.join(";") : undefined;
+}
+
+/** The annotation's payload, as stored. `tag` is validated again at render time. */
+export interface StyledMarkDef {
+  _type: "styled";
+  _key: string;
+  tag: StyledTag;
+  className?: string;
+  attrs?: Record<string, string>;
+}
+
+/**
+ * The admitted attributes of an element, in source order, or undefined when there are none.
+ *
+ * `class` is deliberately absent — it lives on the markDef as `className`, because it is the
+ * one attribute every consumer of this annotation needs to reach without parsing a bag.
+ */
+export function styledAttrsOf(el: Element): Record<string, string> | undefined {
+  const out: Record<string, string> = {};
+  for (const attr of Array.from(el.attributes)) {
+    const name = attr.name.toLowerCase();
+    if (name === "class" || !isStyledAttr(name)) continue;
+    const value = name === "style" ? safeStyle(attr.value) : attr.value;
+    if (value === undefined) continue;
+    out[name] = value;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+/**
+ * The same filter applied to a STORED bag, which may have arrived from anywhere.
+ *
+ * Both ends, and this is the end that matters: a markDef reaches storage from an import, the
+ * Management API, MCP and AI writes, so the ingest filter is a courtesy and this one is the
+ * control. Every renderer of the annotation goes through here.
+ */
+export function styledAttrEntries(attrs: unknown): [string, string][] {
+  if (!attrs || typeof attrs !== "object" || Array.isArray(attrs)) return [];
+  const out: [string, string][] = [];
+  for (const [name, raw] of Object.entries(attrs as Record<string, unknown>)) {
+    if (!isStyledAttr(name) || typeof raw !== "string") continue;
+    const value = name === "style" ? safeStyle(raw) : raw;
+    if (value === undefined) continue;
+    out.push([name, value]);
+  }
+  return out;
+}

package/src/types.ts

@@ -176,6 +176,12 @@ export const PT_TYPES = {
   table: "table",
   /** The annotation carrying a hyperlink's `href`. Spelled `link` because that is the spec's convention. */
   link: "link",
+  /**
+   * The annotation carrying a site's OWN inline markup — `<span class>`, `<small>`, `<time
+   * datetime>`. Unprefixed, like `table`, because it describes HTML rather than a BetterCMS
+   * concept. See `styled.ts` for what it may hold and why the list is that short.
+   */
+  styled: "styled",
 } as const;
 
 /**