@glw907/cairn-cms 0.5.0 → 0.6.0-rc.0

package/src/lib/nav/site-config.ts

@@ -0,0 +1,124 @@
+// The navigation tree and its YAML site-config. A menu lives in the site's git-committed config
+// under `menus.<name>`, read at build time by the public layout and edited from /admin/nav, which
+// commits the file back through the GitHub-App pipeline. This module is pure: parse, validate, and
+// rewrite only. The engine returns data; each site renders the tree with its own markup.
+import { parse as parseYaml, parseDocument } from 'yaml';
+
+/** One navigation node. An omitted or empty `url` is a label-only grouping header; no `children` is a leaf. */
+export interface NavNode {
+  label: string;
+  url?: string;
+  children?: NavNode[];
+}
+
+/** Total node cap across the whole tree, a guard against a runaway payload. */
+export const MAX_NAV_NODES = 200;
+
+/** Maximum character length for a node label. */
+export const MAX_LABEL_LENGTH = 500;
+
+/** Maximum character length for a node URL. */
+export const MAX_URL_LENGTH = 2048;
+
+/** Allowlist for safe URL schemes: site-relative, in-page anchors, http(s), mailto, and tel. */
+const SAFE_URL = /^(\/|#|https?:\/\/|mailto:|tel:)/i;
+
+export class NavValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NavValidationError';
+  }
+}
+
+/**
+ * Validate and normalize an untrusted value into a NavNode[]: arrays only, non-empty labels, depth
+ * within `maxDepth` (1 is flat), a bounded node count, and only the three known keys kept. Throws
+ * NavValidationError on any violation. Used by navSave before writing.
+ */
+export function validateNavTree(value: unknown, maxDepth: number): NavNode[] {
+  let count = 0;
+
+  function walk(nodes: unknown, depth: number): NavNode[] {
+    if (!Array.isArray(nodes)) throw new NavValidationError('Navigation must be a list of items');
+    if (depth > maxDepth) throw new NavValidationError(`Navigation is nested deeper than ${maxDepth} levels`);
+    return nodes.map((raw) => {
+      if (typeof raw !== 'object' || raw === null) throw new NavValidationError('Each item must be an object');
+      const item = raw as Record<string, unknown>;
+      const label = typeof item.label === 'string' ? item.label.trim() : '';
+      if (!label) throw new NavValidationError('Each item needs a label');
+      if (label.length > MAX_LABEL_LENGTH) throw new NavValidationError('Label is too long (max 500 characters)');
+      if (++count > MAX_NAV_NODES) throw new NavValidationError('Too many navigation items');
+      const node: NavNode = { label };
+      if (typeof item.url === 'string' && item.url.trim()) {
+        const url = item.url.trim();
+        if (url.length > MAX_URL_LENGTH) throw new NavValidationError('URL is too long (max 2048 characters)');
+        if (!SAFE_URL.test(url)) throw new NavValidationError('URL must start with /, #, http(s)://, mailto:, or tel:');
+        node.url = url;
+      }
+      if (item.children !== undefined) {
+        const children = walk(item.children, depth + 1);
+        if (children.length) node.children = children;
+      }
+      return node;
+    });
+  }
+
+  return walk(value, 1);
+}
+
+/**
+ * Shape of the YAML site-config file. Unknown keys are ignored so the file can grow without an
+ * engine change. Read at build time by the public site.
+ */
+export interface SiteConfig {
+  siteName: string;
+  description?: string;
+  author?: string;
+  url?: string;
+  locale?: string;
+  /** Named navigation menus, each a NavNode[] (normalized by extractMenu). */
+  menus?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export class SiteConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SiteConfigError';
+  }
+}
+
+/** Parse the YAML site-config text into a typed object. Throws SiteConfigError on a malformed root. */
+export function parseSiteConfig(raw: string): SiteConfig {
+  const parsed = parseYaml(raw) as unknown;
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new SiteConfigError('Site config must be a YAML mapping');
+  }
+  const { siteName } = parsed as SiteConfig;
+  if (typeof siteName !== 'string' || !siteName.trim()) {
+    throw new SiteConfigError('Site config needs a siteName');
+  }
+  return parsed as SiteConfig;
+}
+
+/** Extract one named menu from a parsed config and validate it. Returns [] when the menu is absent. */
+export function extractMenu(config: SiteConfig, name: string, maxDepth: number): NavNode[] {
+  const menu = config.menus?.[name];
+  if (menu === undefined) return [];
+  return validateNavTree(menu, maxDepth);
+}
+
+/**
+ * Replace one named menu in the YAML site-config text and reserialize, preserving every other
+ * top-level key (siteName, other menus, settings). Parses into a Document so the rest of the file
+ * round-trips. YAML comments are not preserved (an accepted trade); data keys are. A leaf node
+ * serializes without `url`/`children` keys.
+ */
+export function setMenu(raw: string, name: string, tree: NavNode[]): string {
+  const doc = parseDocument(raw);
+  if (doc.get('siteName') === undefined) {
+    throw new SiteConfigError('Site config must be a mapping with a siteName');
+  }
+  doc.setIn(['menus', name], tree);
+  return doc.toString();
+}

package/src/lib/render/glyph.ts

@@ -1,14 +1,14 @@
 import { s } from 'hastscript';
 import type { Element } from 'hast';
 
-/** A glyph name → SVG path-data map (the site owns the icon set). */
+/** A glyph name to SVG path-data map (the site owns the icon set). */
 export type IconSet = Record<string, string>;
 
 /** Inline SVG glyph as a real hast node: class ec-glyph, 256 viewBox, currentColor fill. */
 export function glyph(name: string, icons: IconSet): Element {
-	return s(
-		'svg',
-		{ className: ['ec-glyph'], viewBox: '0 0 256 256', fill: 'currentColor', ariaHidden: 'true' },
-		[s('path', { d: icons[name] })],
-	);
+  return s(
+    'svg',
+    { className: ['ec-glyph'], viewBox: '0 0 256 256', fill: 'currentColor', ariaHidden: 'true' },
+    [s('path', { d: icons[name] })],
+  );
 }

package/src/lib/render/index.ts

@@ -1,8 +1,8 @@
-// cairn-cms render engine: a directive-driven markdown → HTML pipeline whose
+// cairn-cms render engine: a directive-driven markdown to HTML pipeline whose
 // component vocabulary is supplied by a site's component registry. The site owns the
 // component builders, class names, icon set, and CSS; the engine owns the machinery.
-export * from './registry';
-export * from './glyph';
-export * from './remark-directives';
-export * from './rehype-dispatch';
-export * from './pipeline';
+export * from './registry.js';
+export * from './glyph.js';
+export * from './remark-directives.js';
+export * from './rehype-dispatch.js';
+export * from './pipeline.js';

package/src/lib/render/pipeline.ts

@@ -6,32 +6,32 @@ import remarkRehype from 'remark-rehype';
 import rehypeRaw from 'rehype-raw';
 import rehypeSlug from 'rehype-slug';
 import rehypeStringify from 'rehype-stringify';
-import { remarkDirectiveStamp } from './remark-directives';
-import { rehypeDispatch } from './rehype-dispatch';
-import type { ComponentRegistry } from './registry';
+import { remarkDirectiveStamp } from './remark-directives.js';
+import { rehypeDispatch } from './rehype-dispatch.js';
+import type { ComponentRegistry } from './registry.js';
 
 export interface RendererOptions {
-	/** A site's per-index motion formula for the top-level rise stagger
-	 *  (e.g. ecnordic's `(i) => '--rise:' + …`). Omit for no stagger. */
-	rise?: (idx: number) => string;
+  /** A site's per-index motion formula for the top-level rise stagger
+   *  (e.g. ecnordic's `(i) => '--rise:' + …`). Omit for no stagger. */
+  rise?: (idx: number) => string;
 }
 
-/** Compose a site's render pipeline from its component registry: directive syntax →
- *  stamped markers → registry-built hast. Returns `renderMarkdown` plus the remark/
+/** Compose a site's render pipeline from its component registry: directive syntax to
+ *  stamped markers to registry-built hast. Returns `renderMarkdown` plus the remark/
  *  rehype plugin arrays (so the Carta editor preview can reuse the exact same set). */
 export function createRenderer(registry: ComponentRegistry, options: RendererOptions = {}) {
-	const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry]];
-	const rehypePlugins: PluggableList = [rehypeRaw, [rehypeDispatch, registry, options.rise], rehypeSlug];
-	const processor = unified()
-		.use(remarkParse)
-		.use(remarkGfm)
-		.use(remarkPlugins)
-		.use(remarkRehype, { allowDangerousHtml: true })
-		.use(rehypePlugins)
-		.use(rehypeStringify);
-	return {
-		remarkPlugins,
-		rehypePlugins,
-		renderMarkdown: async (content: string): Promise<string> => String(await processor.process(content)),
-	};
+  const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry]];
+  const rehypePlugins: PluggableList = [rehypeRaw, [rehypeDispatch, registry, options.rise], rehypeSlug];
+  const processor = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkPlugins)
+    .use(remarkRehype, { allowDangerousHtml: true })
+    .use(rehypePlugins)
+    .use(rehypeStringify);
+  return {
+    remarkPlugins,
+    rehypePlugins,
+    renderMarkdown: async (content: string): Promise<string> => String(await processor.process(content)),
+  };
 }

package/src/lib/render/registry.ts

@@ -1,36 +1,43 @@
+// cairn-cms: the directive component registry (seam 3). One declaration per component,
+// carrying how it inserts in the editor and how it renders in rehype. The render pipeline
+// (Plan 04) and the future component palette both derive from this single source, so the
+// parser, the render dispatch, and the editor never drift apart. The adapter references
+// `ComponentRegistry` from here.
 import type { Element } from 'hast';
 
 /** A site component: how it inserts (editor) and how it renders (rehype). */
 export interface ComponentDef {
-	/** Directive name, e.g. 'card' (matches `:::card`). */
-	name: string;
-	/** Palette label. */
-	label: string;
-	/** Palette description. */
-	description: string;
-	/** Markdown scaffold inserted at the cursor by the editor palette. */
-	insertTemplate: string;
-	/** Build the final hast element from the stamped directive element. */
-	build: (node: Element, rise?: string) => Element;
-	/** Optional role→default-icon (e.g. `{ caution: 'warning' }`). */
-	defaultIconByRole?: Record<string, string>;
+  /** Directive name, e.g. 'card' (matches `:::card`). */
+  name: string;
+  /** Palette label. */
+  label: string;
+  /** Palette description. */
+  description: string;
+  /** Markdown scaffold inserted at the cursor by the editor palette. */
+  insertTemplate: string;
+  /** Build the final hast element from the stamped directive element. */
+  build: (node: Element, rise?: string) => Element;
+  /** Optional role-to-default-icon, e.g. `{ caution: 'warning' }`. */
+  defaultIconByRole?: Record<string, string>;
 }
 
 export interface ComponentRegistry {
-	defs: ComponentDef[];
-	names: string[];
-	get(name: string): ComponentDef | undefined;
-	defaultIcon(name: string, role?: string): string | undefined;
+  defs: ComponentDef[];
+  names: string[];
+  get(name: string): ComponentDef | undefined;
+  defaultIcon(name: string, role?: string): string | undefined;
 }
 
-/** Build a registry from a site's component definitions. The single source the
- *  render pipeline (directive stamp + rehype dispatch) and the editor palette read. */
-export function defineRegistry(input: { components: ComponentDef[] }): ComponentRegistry {
-	const byName = new Map(input.components.map((c) => [c.name, c]));
-	return {
-		defs: input.components,
-		names: input.components.map((c) => c.name),
-		get: (name) => byName.get(name),
-		defaultIcon: (name, role) => (role ? byName.get(name)?.defaultIconByRole?.[role] : undefined),
-	};
+/**
+ * Build a registry from a site's component definitions. The single source the render
+ * pipeline (directive stamp plus rehype dispatch) and the editor palette both read.
+ */
+export function defineRegistry({ components }: { components: ComponentDef[] }): ComponentRegistry {
+  const byName = new Map(components.map((c) => [c.name, c]));
+  return {
+    defs: components,
+    names: components.map((c) => c.name),
+    get: (name) => byName.get(name),
+    defaultIcon: (name, role) => (role ? byName.get(name)?.defaultIconByRole?.[role] : undefined),
+  };
 }

package/src/lib/render/rehype-dispatch.ts

@@ -1,23 +1,23 @@
 import type { Root, Element, ElementContent, Properties } from 'hast';
 import { h } from 'hastscript';
-import type { ComponentRegistry } from './registry';
+import type { ComponentRegistry } from './registry.js';
 
 export function isElement(node: ElementContent | undefined): node is Element {
-	return !!node && node.type === 'element';
+  return !!node && node.type === 'element';
 }
 
 // hast Properties values are PropertyValue (string | number | boolean | array | null).
 // Directive markers (dataIcon/dataRole/dataPrimitive) are always stamped as strings;
 // this reads them back with that guarantee instead of casting at each call site.
 export function strProp(node: Element, name: string): string | undefined {
-	const value = node.properties?.[name];
-	return typeof value === 'string' ? value : undefined;
+  const value = node.properties?.[name];
+  return typeof value === 'string' ? value : undefined;
 }
 
 /** Wrap a pre-built glyph in an ec-icon span; secondary role adds the modifier. */
 export function iconSpan(glyphEl: Element, role?: string): Element {
-	const className = role === 'secondary' ? ['ec-icon', 'ec-icon-secondary'] : ['ec-icon'];
-	return h('span', { className }, [glyphEl]);
+  const className = role === 'secondary' ? ['ec-icon', 'ec-icon-secondary'] : ['ec-icon'];
+  return h('span', { className }, [glyphEl]);
 }
 
 /** A site's icon factory: turn a stamped icon name + role into a hast element. */
@@ -28,55 +28,55 @@ export type MakeIcon = (name: string, role?: string) => Element;
 // `makeIcon` (site-supplied) turns the stamped data-icon into an element; omit it
 // for a head with no icon.
 export function splitHead(node: Element, makeIcon?: MakeIcon): { head: Element; rest: ElementContent[] } {
-	const children = node.children as ElementContent[];
-	const i = children.findIndex((c) => isElement(c) && c.tagName === 'h2');
-	const h2 = children[i] as Element;
-	h2.properties = { ...h2.properties, className: ['card-title'] };
-	const rest = children.filter((_, j) => j !== i);
-	const icon = strProp(node, 'dataIcon');
-	const role = strProp(node, 'dataRole');
-	const headKids: ElementContent[] = [];
-	if (makeIcon && icon) headKids.push(makeIcon(icon, role));
-	headKids.push(h2);
-	return { head: h('div', { className: ['ec-head'] }, headKids), rest };
+  const children = node.children as ElementContent[];
+  const i = children.findIndex((c) => isElement(c) && c.tagName === 'h2');
+  const h2 = children[i] as Element;
+  h2.properties = { ...h2.properties, className: ['card-title'] };
+  const rest = children.filter((_, j) => j !== i);
+  const icon = strProp(node, 'dataIcon');
+  const role = strProp(node, 'dataRole');
+  const headKids: ElementContent[] = [];
+  if (makeIcon && icon) headKids.push(makeIcon(icon, role));
+  headKids.push(h2);
+  return { head: h('div', { className: ['ec-head'] }, headKids), rest };
 }
 
 /** Section wrapper: `<section class=…><div class="card-body">…</div></section>`,
  *  with an optional inline rise style. */
 export function cardShell(classes: string[], rise: string | undefined, body: ElementContent[]): Element {
-	const properties: Properties = { className: classes };
-	if (rise) properties.style = rise;
-	return h('section', properties, [h('div', { className: ['card-body'] }, body)]);
+  const properties: Properties = { className: classes };
+  if (rise) properties.style = rise;
+  return h('section', properties, [h('div', { className: ['card-body'] }, body)]);
 }
 
 /** Tag the first <ul> among children with `ec-grid` and strip its whitespace-only
  *  text nodes so the bare list serializes without newlines. Returns that <ul>. */
 export function markFirstList(children: ElementContent[]): Element | undefined {
-	const ul = children.find((c) => isElement(c) && c.tagName === 'ul') as Element | undefined;
-	if (ul) {
-		ul.properties = { ...ul.properties, className: ['ec-grid'] };
-		ul.children = (ul.children as ElementContent[]).filter(
-			(c) => !(c.type === 'text' && /^\s*$/.test(c.value)),
-		);
-	}
-	return ul;
+  const ul = children.find((c) => isElement(c) && c.tagName === 'ul') as Element | undefined;
+  if (ul) {
+    ul.properties = { ...ul.properties, className: ['ec-grid'] };
+    ul.children = (ul.children as ElementContent[]).filter(
+      (c) => !(c.type === 'text' && /^\s*$/.test(c.value)),
+    );
+  }
+  return ul;
 }
 
 // Recurse into a node's children, transforming any nested primitive sections
 // (a grid inside a card, panels inside a split) WITHOUT a rise stagger.
 function transformChildren(children: ElementContent[], registry: ComponentRegistry): ElementContent[] {
-	return children.map((c) => {
-		if (isElement(c) && c.properties?.dataPrimitive) return transformNode(c, registry);
-		if (isElement(c)) c.children = transformChildren(c.children as ElementContent[], registry);
-		return c;
-	});
+  return children.map((c) => {
+    if (isElement(c) && c.properties?.dataPrimitive) return transformNode(c, registry);
+    if (isElement(c)) c.children = transformChildren(c.children as ElementContent[], registry);
+    return c;
+  });
 }
 
 function transformNode(node: Element, registry: ComponentRegistry, rise?: string): Element {
-	node.children = transformChildren(node.children as ElementContent[], registry);
-	const name = strProp(node, 'dataPrimitive');
-	const def = name ? registry.get(name) : undefined;
-	return def ? def.build(node, rise) : node;
+  node.children = transformChildren(node.children as ElementContent[], registry);
+  const name = strProp(node, 'dataPrimitive');
+  const def = name ? registry.get(name) : undefined;
+  return def ? def.build(node, rise) : node;
 }
 
 /** Rehype transformer: dispatch each stamped element through its registry `build`
@@ -84,14 +84,14 @@ function transformNode(node: Element, registry: ComponentRegistry, rise?: string
  *  supplied (a site's per-index motion formula); nested ones don't. Non-primitive
  *  content (lede, intro paragraphs, the page-toc nav) passes through untouched. */
 export function rehypeDispatch(registry: ComponentRegistry, rise?: (idx: number) => string) {
-	return (tree: Root) => {
-		let idx = 0;
-		tree.children = (tree.children as ElementContent[]).map((child) => {
-			if (isElement(child) && child.properties?.dataPrimitive) {
-				return transformNode(child, registry, rise ? rise(idx++) : undefined);
-			}
-			if (isElement(child)) child.children = transformChildren(child.children as ElementContent[], registry);
-			return child;
-		});
-	};
+  return (tree: Root) => {
+    let idx = 0;
+    tree.children = (tree.children as ElementContent[]).map((child) => {
+      if (isElement(child) && child.properties?.dataPrimitive) {
+        return transformNode(child, registry, rise ? rise(idx++) : undefined);
+      }
+      if (isElement(child)) child.children = transformChildren(child.children as ElementContent[], registry);
+      return child;
+    });
+  };
 }

package/src/lib/render/remark-directives.ts

@@ -1,20 +1,20 @@
 import type { Paragraph, PhrasingContent, Root, Text } from 'mdast';
 import type { ContainerDirective, LeafDirective, TextDirective } from 'mdast-util-directive';
 import { visit } from 'unist-util-visit';
-import type { ComponentRegistry } from './registry';
+import type { ComponentRegistry } from './registry.js';
 
 // Reconstruct a directive's authored attribute block (`{#id .class key="value"}`).
 // Accidental prose directives carry none, so this is almost always empty.
 function serializeAttributes(attributes?: Record<string, string | null | undefined> | null): string {
-	if (!attributes) return '';
-	const tokens: string[] = [];
-	for (const [key, value] of Object.entries(attributes)) {
-		if (value == null) tokens.push(key);
-		else if (key === 'id') tokens.push(`#${value}`);
-		else if (key === 'class') for (const c of value.split(/\s+/).filter(Boolean)) tokens.push(`.${c}`);
-		else tokens.push(`${key}="${value}"`);
-	}
-	return tokens.length ? `{${tokens.join(' ')}}` : '';
+  if (!attributes) return '';
+  const tokens: string[] = [];
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value == null) tokens.push(key);
+    else if (key === 'id') tokens.push(`#${value}`);
+    else if (key === 'class') for (const c of value.split(/\s+/).filter(Boolean)) tokens.push(`.${c}`);
+    else tokens.push(`${key}="${value}"`);
+  }
+  return tokens.length ? `{${tokens.join(' ')}}` : '';
 }
 
 // The vocabulary is container-only (`:::name`). A text directive (`:name`) or
@@ -22,14 +22,14 @@ function serializeAttributes(attributes?: Record<string, string | null | undefin
 // ("4:00", "9:30", "ratio 16:9") that micromark tokenized as a directive.
 // Restore it to its literal source text so prose renders verbatim.
 function restoreLiteral(node: TextDirective | LeafDirective): PhrasingContent[] {
-	const marker = node.type === 'leafDirective' ? '::' : ':';
-	const attrs = serializeAttributes(node.attributes);
-	if (node.children.length === 0) {
-		return [{ type: 'text', value: marker + node.name + attrs }];
-	}
-	const open: Text = { type: 'text', value: `${marker}${node.name}[` };
-	const close: Text = { type: 'text', value: `]${attrs}` };
-	return [open, ...(node.children as PhrasingContent[]), close];
+  const marker = node.type === 'leafDirective' ? '::' : ':';
+  const attrs = serializeAttributes(node.attributes);
+  if (node.children.length === 0) {
+    return [{ type: 'text', value: marker + node.name + attrs }];
+  }
+  const open: Text = { type: 'text', value: `${marker}${node.name}[` };
+  const close: Text = { type: 'text', value: `]${attrs}` };
+  return [open, ...(node.children as PhrasingContent[]), close];
 }
 
 // Stamp each registered container directive with data-* markers carrying its
@@ -37,35 +37,35 @@ function restoreLiteral(node: TextDirective | LeafDirective): PhrasingContent[]
 // dispatcher rewrites the marked elements once their children are hast.
 // Text and leaf directives are restored to literal text (accidental prose colons).
 export function remarkDirectiveStamp(registry: ComponentRegistry) {
-	const known = new Set(registry.names);
-	return (tree: Root) => {
-		visit(tree, 'containerDirective', (node: ContainerDirective) => {
-			if (!known.has(node.name)) return;
-			const attrs = node.attributes ?? {};
-			const role = attrs.role || undefined;
-			let icon = attrs.icon || undefined;
-			if (!icon && role) icon = registry.defaultIcon(node.name, role);
+  const known = new Set(registry.names);
+  return (tree: Root) => {
+    visit(tree, 'containerDirective', (node: ContainerDirective) => {
+      if (!known.has(node.name)) return;
+      const attrs = node.attributes ?? {};
+      const role = attrs.role || undefined;
+      let icon = attrs.icon || undefined;
+      if (!icon && role) icon = registry.defaultIcon(node.name, role);
 
-			const properties: Record<string, string> = { dataPrimitive: node.name };
-			if (icon) properties.dataIcon = icon;
-			if (role) properties.dataRole = role;
+      const properties: Record<string, string> = { dataPrimitive: node.name };
+      if (icon) properties.dataIcon = icon;
+      if (role) properties.dataRole = role;
 
-			const data = node.data ?? (node.data = {});
-			data.hName = 'div';
-			data.hProperties = properties;
-		});
+      const data = node.data ?? (node.data = {});
+      data.hName = 'div';
+      data.hProperties = properties;
+    });
 
-		visit(tree, ['textDirective', 'leafDirective'], (node, index, parent) => {
-			if (!parent || index == null) return;
-			const literal = restoreLiteral(node as TextDirective | LeafDirective);
-			if (node.type === 'leafDirective') {
-				// Leaf directives sit at block level; wrap the restored text in a paragraph.
-				const paragraph: Paragraph = { type: 'paragraph', children: literal };
-				parent.children.splice(index, 1, paragraph);
-			} else {
-				parent.children.splice(index, 1, ...literal);
-			}
-			return index;
-		});
-	};
+    visit(tree, ['textDirective', 'leafDirective'], (node, index, parent) => {
+      if (!parent || index == null) return;
+      const literal = restoreLiteral(node as TextDirective | LeafDirective);
+      if (node.type === 'leafDirective') {
+        // Leaf directives sit at block level; wrap the restored text in a paragraph.
+        const paragraph: Paragraph = { type: 'paragraph', children: literal };
+        parent.children.splice(index, 1, paragraph);
+      } else {
+        parent.children.splice(index, 1, ...literal);
+      }
+      return index;
+    });
+  };
 }

package/src/lib/render/sanitize.ts

@@ -0,0 +1,27 @@
+// The live preview's sanitize floor. Carta runs with `sanitizer: false` behind the MarkdownEditor
+// seam, so the admin preview pane is the one barrier between editor-authored markdown and the DOM.
+// DOMPurify needs a DOM, and the preview renders only in the browser after mount, so DOMPurify
+// loads through a dynamic import: the module never evaluates a DOM library on the Worker, and a
+// server import of this file pulls in nothing.
+let purify: { sanitize(html: string, config?: Record<string, unknown>): string; addHook(event: string, cb: (node: Element) => void): void } | null = null;
+
+/**
+ * Sanitize rendered preview HTML before it reaches `{@html}`. Strips scripts, inline event
+ * handlers, and dangerous URL schemes (`javascript:`, `data:`) while keeping ordinary formatting.
+ * Also forces `rel="noopener noreferrer"` on any anchor with `target="_blank"` to prevent
+ * reverse-tabnabbing. Browser-only; resolves the same string DOMPurify would return.
+ */
+export async function sanitizePreviewHtml(html: string): Promise<string> {
+  if (!purify) {
+    const mod = await import('dompurify');
+    purify = mod.default;
+    purify.addHook('afterSanitizeAttributes', (node) => {
+      if (node.tagName === 'A' && node.getAttribute('target') === '_blank') {
+        node.setAttribute('rel', 'noopener noreferrer');
+      }
+    });
+  }
+  // ADD_ATTR: ['target'] allows target="_blank" through so the afterSanitizeAttributes hook
+  // can enforce rel="noopener noreferrer" on those anchors before they reach the DOM.
+  return purify.sanitize(html, { ADD_ATTR: ['target'] });
+}