@bettercms-ai/richtext 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/richtext",
-  "version": "0.2.0",
+  "version": "0.3.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/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/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.
@@ -155,6 +156,25 @@ const components: Partial<PortableTextHtmlComponents> = {
       const target = v.target === "_blank" ? ' target="_blank" rel="noopener noreferrer"' : "";
       return `<a href="${esc(href)}"${target}>${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;
 
 /**