@bendyline/squisq 1.4.0 → 1.5.0

package/src/markdown/convert.ts

@@ -19,11 +19,20 @@ import type {
   MarkdownTableCell,
   MarkdownSourcePosition,
   HeadingTemplateAnnotation,
+  HeadingAttributes,
   MarkdownHeading,
   MarkdownInlineIcon,
 } from './types.js';
 import { parseHtmlToNodes } from './htmlParse.js';
 import { resolveIcon } from '../icons/resolve.js';
+import { coerceAnnotationValues } from './annotationCoercion.js';
+import {
+  matchTrailingTemplateAnnotation,
+  matchTrailingPandocAttr,
+  tokenizeAttrTokens,
+  splitKeyValueToken,
+  quoteAttrValue,
+} from './attrTokens.js';
 
 // ============================================
 // Generic mdast node shape
@@ -131,22 +140,16 @@ function extractText(node: MdastNode): string {
 // Template annotation helpers
 // ============================================
 
-/**
- * Regex matching a trailing `{[templateName key=value …]}` annotation.
- * Captures the content between `{[` and `]}`.
- *
- * The trailing `[\s\]\}]*` tolerates accidental doubled `]}` that users
- * sometimes type when learning the syntax (e.g. `{[foo]}]}`). It does
- * not allow trailing word characters, so a non-trailing annotation like
- * `## The {[chart]} section` still doesn't match.
- */
-const TEMPLATE_ANNOTATION_RE = /\s*\{\[([^\]]+)\]\}[\s\]}]*$/;
-
 /**
  * Extract a `{[templateName key=value …]}` annotation from a heading's
  * inline children. Mutates the children array in-place: strips the
  * annotation text from the last text node (or removes the node entirely).
  *
+ * Matching is delegated to {@link matchTrailingTemplateAnnotation}: a
+ * quote-aware grammar (values may contain `]` when quoted) with a legacy
+ * fallback, plus tolerance for an accidental doubled trailing `]}`. A
+ * non-trailing annotation like `## The {[chart]} section` doesn't match.
+ *
  * @returns The parsed annotation, or null if none found.
  */
 function extractTemplateAnnotation(
@@ -156,13 +159,13 @@ function extractTemplateAnnotation(
   for (let i = children.length - 1; i >= 0; i--) {
     const child = children[i];
     if (child.type === 'text') {
-      const match = child.value.match(TEMPLATE_ANNOTATION_RE);
+      const match = matchTrailingTemplateAnnotation(child.value);
       if (match) {
-        const inner = match[1].trim();
+        const inner = match.inner.trim();
         const annotation = parseAnnotationTokens(inner);
 
         // Strip the matched portion from the text
-        const stripped = child.value.slice(0, match.index!).replace(/\s+$/, '');
+        const stripped = child.value.slice(0, match.index).replace(/\s+$/, '');
         if (stripped) {
           (child as { value: string }).value = stripped;
         } else {
@@ -183,23 +186,27 @@ function extractTemplateAnnotation(
 /**
  * Parse the inner content of a `{[…]}` annotation into template + params.
  *
- * Input: `"chart colorScheme=blue size=large"`
- * Output: `{ template: 'chart', params: { colorScheme: 'blue', size: 'large' } }`
+ * Input: `"chart colorScheme=blue caption=\"Sales by region\""`
+ * Output: `{ template: 'chart', params: { colorScheme: 'blue', caption: 'Sales by region' } }`
+ *
+ * Tokenization is shared with the Pandoc attribute parser
+ * ({@link tokenizeAttrTokens}), so quoting and escaping behave
+ * identically in both annotation forms.
  */
 function parseAnnotationTokens(inner: string): HeadingTemplateAnnotation {
-  const tokens = inner.split(/\s+/);
+  const tokens = tokenizeAttrTokens(inner);
   const params: Record<string, string> = {};
 
   // If the first token contains '=', there's no template name —
   // the annotation is purely key-value (e.g., `{[audio=intro.mp3]}`).
-  const firstIsParam = tokens[0].indexOf('=') > 0;
-  const template = firstIsParam ? undefined : tokens[0];
+  const firstIsParam = tokens.length > 0 && tokens[0].indexOf('=') > 0;
+  const template = firstIsParam || tokens.length === 0 ? undefined : tokens[0];
   const startIdx = firstIsParam ? 0 : 1;
 
   for (let i = startIdx; i < tokens.length; i++) {
-    const eqIdx = tokens[i].indexOf('=');
-    if (eqIdx > 0) {
-      params[tokens[i].slice(0, eqIdx)] = tokens[i].slice(eqIdx + 1);
+    const kv = splitKeyValueToken(tokens[i]);
+    if (kv) {
+      params[kv.key] = kv.value;
     }
   }
 
@@ -213,8 +220,166 @@ function parseAnnotationTokens(inner: string): HeadingTemplateAnnotation {
   return result;
 }
 
+// ============================================
+// Pandoc-style heading attribute helpers
+// ============================================
+
+/**
+ * Extract a trailing Pandoc-style `{…}` attribute block from a heading's
+ * inline children. Matching is delegated to {@link matchTrailingPandocAttr}
+ * (quote-aware — values may contain `}` when quoted — with a legacy
+ * fallback; a `(?!\[)` lookahead keeps it from colliding with the
+ * squisq-native `{[…]}` template annotation).
+ *
+ * Unlike `extractTemplateAnnotation()`, this walks backward through both
+ * text nodes AND bare `textDirective` nodes. remark-directive may have
+ * fragmented a `{key=val:type,…}` attribute block at colon-prefixed
+ * segments like `:type` that look like text directives but are really
+ * attribute-value fragments. We virtually re-stitch the trailing run as a
+ * single string, match against it, and only physically modify the children
+ * array if a match is found — so a heading that legitimately contains a
+ * non-bare `:directive` is left alone.
+ *
+ * Returns the parsed `HeadingAttributes`, or null if no match.
+ */
+function extractPandocAttributes(children: MarkdownInlineNode[]): HeadingAttributes | null {
+  // Collect the trailing run of [text | bare textDirective] children.
+  const trail: { val: string; idx: number; len: number }[] = [];
+  for (let i = children.length - 1; i >= 0; i--) {
+    const c = children[i];
+    if (c.type === 'text') {
+      trail.unshift({ val: c.value, idx: i, len: c.value.length });
+    } else if (c.type === 'textDirective') {
+      const td = c as {
+        name?: string;
+        children?: unknown[];
+        attributes?: Record<string, string>;
+      };
+      const isBare =
+        (!td.children || td.children.length === 0) &&
+        (!td.attributes || Object.keys(td.attributes).length === 0);
+      if (!isBare) break;
+      const synthesized = ':' + (td.name ?? '');
+      trail.unshift({ val: synthesized, idx: i, len: synthesized.length });
+    } else {
+      break;
+    }
+  }
+  if (trail.length === 0) return null;
+
+  const joined = trail.map((t) => t.val).join('');
+  const match = matchTrailingPandocAttr(joined);
+  if (!match) return null;
+
+  const inner = match.inner.trim();
+  const attrs = parsePandocAttrTokens(inner);
+
+  // Strip the matched portion. `match.index` is an offset into `joined`.
+  // Walk forward through `trail` until we find the child that straddles
+  // the match boundary; trim that child (if text) or drop it (if directive),
+  // and remove everything after it from `children`.
+  const matchStart = match.index;
+  let scannedLen = 0;
+  for (let ti = 0; ti < trail.length; ti++) {
+    const t = trail[ti];
+    if (scannedLen + t.len <= matchStart) {
+      scannedLen += t.len;
+      continue;
+    }
+    const firstNode = children[t.idx];
+    const keepLen = matchStart - scannedLen;
+    if (firstNode.type === 'text') {
+      const trimmed = firstNode.value.slice(0, keepLen).replace(/\s+$/, '');
+      if (trimmed) {
+        (firstNode as { value: string }).value = trimmed;
+        children.splice(t.idx + 1);
+      } else {
+        children.splice(t.idx);
+      }
+    } else {
+      // Match boundary fell inside a textDirective's synthesized ":name"
+      // string — drop the directive and everything after.
+      children.splice(t.idx);
+    }
+    return attrs;
+  }
+  // Match consumes the entire trail.
+  children.splice(trail[0].idx);
+  return attrs;
+}
+
+/**
+ * Parse the inner content of a Pandoc-style `{…}` block. Tokens are
+ * whitespace-separated, with quoted runs (single or double) treated as
+ * single tokens — tokenization is shared with the `{[…]}` template
+ * annotation parser via {@link tokenizeAttrTokens}.
+ *
+ * - `#id` → `attributes.id`
+ * - `.class` → push onto `attributes.classes`
+ * - `key=value` or `key="quoted value"` → `attributes.params[key] = value`
+ *
+ * Empty `{}` yields `{}` (preserved as an annotation marker for round-tripping).
+ * Duplicate ids and keys: last wins, silent.
+ */
+export function parsePandocAttrTokens(inner: string): HeadingAttributes {
+  const tokens = tokenizeAttrTokens(inner);
+  const attrs: HeadingAttributes = {};
+  const params: Record<string, string> = {};
+  const classes: string[] = [];
+
+  for (const token of tokens) {
+    if (token.startsWith('#') && !token.includes('=')) {
+      attrs.id = token.slice(1);
+    } else if (token.startsWith('.') && !token.includes('=')) {
+      const cls = token.slice(1);
+      if (cls) classes.push(cls);
+    } else {
+      const kv = splitKeyValueToken(token);
+      if (kv) {
+        params[kv.key] = kv.value;
+      }
+    }
+  }
+
+  if (classes.length > 0) attrs.classes = classes;
+  if (Object.keys(params).length > 0) {
+    attrs.params = params;
+    const { blockMeta, metadata } = coerceAnnotationValues(params);
+    if (Object.keys(blockMeta).length > 0) attrs.blockMeta = blockMeta;
+    if (Object.keys(metadata).length > 0) attrs.metadata = metadata;
+  }
+  return attrs;
+}
+
+/**
+ * Serialize a HeadingAttributes object back to a Pandoc `{#id .class key=value}` string.
+ * Returns null when the attributes object is entirely empty (nothing to emit).
+ *
+ * Canonical key order: `#id`, then `.classes` (in original order), then
+ * params in their original insertion order. Values are quoted via the
+ * shared {@link quoteAttrValue} rule (same as `{[…]}` serialization).
+ */
+export function serializePandocAttributes(attrs: HeadingAttributes): string | null {
+  const parts: string[] = [];
+  if (attrs.id) parts.push(`#${attrs.id}`);
+  if (attrs.classes) {
+    for (const cls of attrs.classes) parts.push(`.${cls}`);
+  }
+  if (attrs.params) {
+    for (const [key, value] of Object.entries(attrs.params)) {
+      parts.push(`${key}=${quoteAttrValue(value)}`);
+    }
+  }
+  // Preserve an empty `{}` annotation marker if it was authored deliberately
+  // (e.g., reserved for downstream tooling). Caller decides whether to emit.
+  if (parts.length === 0) return '{}';
+  return `{${parts.join(' ')}}`;
+}
+
 /**
  * Serialize a HeadingTemplateAnnotation back to `{[templateName key=value …]}` text.
+ * Values are quoted via the shared {@link quoteAttrValue} rule (same as
+ * Pandoc attribute serialization).
  */
 function serializeTemplateAnnotation(annotation: HeadingTemplateAnnotation): string {
   const parts: string[] = [];
@@ -223,7 +388,7 @@ function serializeTemplateAnnotation(annotation: HeadingTemplateAnnotation): str
   }
   if (annotation.params) {
     for (const [key, value] of Object.entries(annotation.params)) {
-      parts.push(`${key}=${value}`);
+      parts.push(`${key}=${quoteAttrValue(value)}`);
     }
   }
   return `{[${parts.join(' ')}]}`;
@@ -447,8 +612,33 @@ function convertBlockNode(node: MdastNode, parseHtml: boolean): MarkdownBlockNod
       // a template annotation. Anything that's NOT the template still
       // needs to become an icon node, so we run `splitInlineIcons` on
       // what's left after the template extraction.
+      //
+      // Both annotation forms ({[…]} and Pandoc {#…}) may appear at the
+      // end of the heading in either order. Extract them in a loop so
+      // we catch the second-from-last one too. A small bounded retry
+      // (max 4) is plenty — authors don't stack more than two trailing
+      // brace-blocks in practice.
       const headingChildren = convertInlineChildren(node.children ?? [], parseHtml, false);
-      const annotation = extractTemplateAnnotation(headingChildren);
+      let annotation: HeadingTemplateAnnotation | null = null;
+      let attrs: HeadingAttributes | null = null;
+      for (let pass = 0; pass < 4; pass++) {
+        let matched = false;
+        if (!annotation) {
+          const t = extractTemplateAnnotation(headingChildren);
+          if (t) {
+            annotation = t;
+            matched = true;
+          }
+        }
+        if (!attrs) {
+          const a = extractPandocAttributes(headingChildren);
+          if (a) {
+            attrs = a;
+            matched = true;
+          }
+        }
+        if (!matched) break;
+      }
       const finalChildren = splitInlineIcons(headingChildren);
       const result: MarkdownHeading = {
         type: 'heading',
@@ -459,6 +649,9 @@ function convertBlockNode(node: MdastNode, parseHtml: boolean): MarkdownBlockNod
       if (annotation) {
         result.templateAnnotation = annotation;
       }
+      if (attrs) {
+        result.attributes = attrs;
+      }
       return result;
     }
 
@@ -778,9 +971,19 @@ function blockToMdast(node: MarkdownBlockNode): MdastNode {
   switch (node.type) {
     case 'heading': {
       const mdastChildren = inlineChildrenToMdast(node.children);
+      // Canonical trailing order: Pandoc attrs first, then template annotation.
+      // Author-supplied order is not preserved across round-trips by design —
+      // canonicalization gives stable diffs.
+      const suffixes: string[] = [];
+      if (node.attributes) {
+        const pandoc = serializePandocAttributes(node.attributes);
+        if (pandoc != null) suffixes.push(pandoc);
+      }
       if (node.templateAnnotation) {
-        const suffix = serializeTemplateAnnotation(node.templateAnnotation);
-        // Append to last text node, or create a new one
+        suffixes.push(serializeTemplateAnnotation(node.templateAnnotation));
+      }
+      if (suffixes.length > 0) {
+        const suffix = suffixes.join(' ');
         const lastChild = mdastChildren[mdastChildren.length - 1];
         if (lastChild && lastChild.type === 'text') {
           lastChild.value = (lastChild.value ?? '') + ' ' + suffix;

package/src/markdown/index.ts

@@ -32,6 +32,9 @@ export type {
   // Heading template annotation
   HeadingTemplateAnnotation,
 
+  // Pandoc-style heading attributes
+  HeadingAttributes,
+
   // HTML sub-DOM
   HtmlElement,
   HtmlText,
@@ -96,8 +99,40 @@ export { stringifyMarkdown } from './stringify.js';
 // Conversion layer (for advanced use: working with remark plugins directly)
 export { fromMdast, toMdast } from './convert.js';
 
+// Pandoc-style heading attribute helpers — exposed so editor-react can
+// mutate `data-block-attrs` strings without reimplementing the tokenizer.
+export { parsePandocAttrTokens, serializePandocAttributes } from './convert.js';
+
+// Shared key=value attribute machinery for both annotation forms
+// (`{[templateName key=value]}` and Pandoc `{#id .class key=value}`) —
+// exposed so editor-react's tiptap bridge tokenizes and matches headings
+// with the exact same grammar as the parser, by import rather than by copy.
+export {
+  tokenizeAttrTokens,
+  splitKeyValueToken,
+  unquoteAttrValue,
+  needsQuoting,
+  quoteAttrValue,
+  matchTrailingTemplateAnnotation,
+  matchTrailingPandocAttr,
+} from './attrTokens.js';
+export type { TrailingAnnotationMatch } from './attrTokens.js';
+
+// Known `{[name key=value]}` block-meta keys and their editor-facing
+// descriptors — exposed so the markdown editor's attribute autocomplete
+// suggests keys and (where closed) values from the same registry the parser
+// coerces against, rather than a hand-maintained copy.
+export {
+  KNOWN_BLOCK_META_KEYS,
+  BLOCK_META_KEY_DESCRIPTORS,
+  parseTimeSeconds,
+} from './annotationCoercion.js';
+export type { KnownBlockMetaKey, BlockMetaKeyDescriptor } from './annotationCoercion.js';
+
 // HTML sub-DOM utilities
 export { parseHtmlToNodes, stringifyHtmlNodes } from './htmlParse.js';
+export { sanitizeHtmlNodes, sanitizeUrl } from './sanitize.js';
+export type { HtmlPolicy, UrlKind } from './sanitize.js';
 
 // Tree utilities
 export {
@@ -111,4 +146,5 @@ export {
   setFrontmatterValues,
   inferDocumentTitle,
   readFrontmatterThemeId,
+  plainTextFromInlineHtml,
 } from './utils.js';

package/src/markdown/sanitize.ts

@@ -0,0 +1,298 @@
+import type { HtmlElement, HtmlNode } from './types.js';
+
+export type HtmlPolicy = 'strip' | 'sanitize' | 'trusted';
+
+export type UrlKind = 'link' | 'media';
+
+const SAFE_LINK_SCHEMES = new Set(['http', 'https', 'mailto', 'tel']);
+const SAFE_MEDIA_SCHEMES = new Set(['http', 'https', 'blob']);
+
+const SAFE_DATA_MEDIA_RE =
+  /^data:(?:image\/(?!svg\+xml)[a-z0-9.+-]+|audio\/[a-z0-9.+-]+|video\/[a-z0-9.+-]+);/i;
+
+const SAFE_TAGS = new Set([
+  'a',
+  'abbr',
+  'b',
+  'blockquote',
+  'br',
+  'caption',
+  'cite',
+  'code',
+  'col',
+  'colgroup',
+  'data',
+  'dd',
+  'del',
+  'details',
+  'dfn',
+  'div',
+  'dl',
+  'dt',
+  'em',
+  'figcaption',
+  'figure',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'hr',
+  'i',
+  'img',
+  'kbd',
+  'li',
+  'mark',
+  'ol',
+  'p',
+  'pre',
+  'q',
+  's',
+  'samp',
+  'small',
+  'source',
+  'span',
+  'strong',
+  'sub',
+  'summary',
+  'sup',
+  'table',
+  'tbody',
+  'td',
+  'tfoot',
+  'th',
+  'thead',
+  'time',
+  'tr',
+  'track',
+  'u',
+  'ul',
+  'var',
+  'video',
+  'audio',
+]);
+
+const DROP_WITH_CONTENT_TAGS = new Set([
+  'base',
+  'button',
+  'embed',
+  'form',
+  'iframe',
+  'input',
+  'link',
+  'meta',
+  'object',
+  'option',
+  'script',
+  'select',
+  'style',
+  'svg',
+  'template',
+  'textarea',
+]);
+
+const GLOBAL_ATTRS = new Set(['class', 'id', 'title', 'role']);
+
+const TAG_ATTRS: Record<string, Set<string>> = {
+  a: new Set(['href', 'target', 'rel']),
+  audio: new Set(['src', 'controls', 'preload', 'muted', 'loop']),
+  col: new Set(['span', 'width']),
+  colgroup: new Set(['span']),
+  data: new Set(['value']),
+  img: new Set(['src', 'alt', 'width', 'height', 'loading', 'decoding']),
+  li: new Set(['value']),
+  ol: new Set(['start', 'type']),
+  q: new Set(['cite']),
+  source: new Set(['src', 'type', 'media']),
+  td: new Set(['colspan', 'rowspan', 'align']),
+  th: new Set(['colspan', 'rowspan', 'align', 'scope']),
+  time: new Set(['datetime']),
+  track: new Set(['src', 'kind', 'label', 'srclang', 'default']),
+  video: new Set([
+    'src',
+    'poster',
+    'width',
+    'height',
+    'controls',
+    'preload',
+    'muted',
+    'loop',
+    'playsinline',
+  ]),
+};
+
+const SAFE_ATTR_NAME_RE = /^[a-z][a-z0-9:_.-]*$/;
+const SAFE_OL_TYPES = new Set(['1', 'a', 'A', 'i', 'I']);
+const SAFE_PRELOAD_VALUES = new Set(['none', 'metadata', 'auto']);
+const SAFE_TRACK_KINDS = new Set(['subtitles', 'captions', 'descriptions', 'chapters', 'metadata']);
+
+/**
+ * Sanitize a URL for a rendered link or media attribute.
+ *
+ * Relative URLs are allowed. Absolute URLs are restricted to schemes that
+ * cannot execute script in a document context. Media URLs additionally allow
+ * `blob:` and image/audio/video `data:` URLs because Squisq uses both for
+ * browser-local media previews and self-contained exports.
+ */
+export function sanitizeUrl(url: string | null | undefined, kind: UrlKind = 'link'): string | null {
+  if (typeof url !== 'string') return null;
+
+  const trimmed = url.trim();
+  if (!trimmed) return null;
+
+  const compact = stripUrlSchemeNoise(trimmed);
+  const colon = compact.indexOf(':');
+  const firstPathChar = firstIndexOfAny(compact, ['/', '?', '#']);
+  const hasScheme = colon >= 0 && (firstPathChar < 0 || colon < firstPathChar);
+
+  if (!hasScheme) return trimmed;
+
+  const scheme = compact.slice(0, colon).toLowerCase();
+  if (kind === 'media') {
+    if (scheme === 'data') return SAFE_DATA_MEDIA_RE.test(compact) ? trimmed : null;
+    return SAFE_MEDIA_SCHEMES.has(scheme) ? trimmed : null;
+  }
+
+  return SAFE_LINK_SCHEMES.has(scheme) ? trimmed : null;
+}
+
+/**
+ * Return a sanitized copy of an HtmlNode tree. The original parsed tree is left
+ * untouched so markdown stringify can still preserve source fidelity.
+ */
+export function sanitizeHtmlNodes(nodes: HtmlNode[]): HtmlNode[] {
+  const out: HtmlNode[] = [];
+  for (const node of nodes) {
+    out.push(...sanitizeHtmlNode(node));
+  }
+  return out;
+}
+
+function sanitizeHtmlNode(node: HtmlNode): HtmlNode[] {
+  switch (node.type) {
+    case 'htmlText':
+      return [node];
+    case 'htmlComment':
+      return [];
+    case 'htmlElement':
+      return sanitizeHtmlElement(node);
+  }
+}
+
+function sanitizeHtmlElement(node: HtmlElement): HtmlNode[] {
+  const tag = node.tagName.toLowerCase();
+
+  if (DROP_WITH_CONTENT_TAGS.has(tag)) return [];
+
+  const children = sanitizeHtmlNodes(node.children);
+  if (!SAFE_TAGS.has(tag)) return children;
+
+  return [
+    {
+      type: 'htmlElement',
+      tagName: tag,
+      attributes: sanitizeAttrs(tag, node.attributes),
+      children,
+      selfClosing: node.selfClosing,
+    },
+  ];
+}
+
+function sanitizeAttrs(tag: string, attrs: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [rawName, rawValue] of Object.entries(attrs)) {
+    const name = rawName.toLowerCase();
+    if (!isAllowedAttr(tag, name)) continue;
+
+    const value = String(rawValue);
+    const safeValue = sanitizeAttrValue(tag, name, value);
+    if (safeValue === null) continue;
+    out[name] = safeValue;
+  }
+  if (tag === 'a' && out.target === '_blank') {
+    out.rel = ensureRelTokens(out.rel, ['noopener', 'noreferrer']);
+  }
+  return out;
+}
+
+function isAllowedAttr(tag: string, name: string): boolean {
+  if (!SAFE_ATTR_NAME_RE.test(name)) return false;
+  if (name.startsWith('on')) return false;
+  if (name.startsWith('aria-') || name.startsWith('data-')) return true;
+  if (GLOBAL_ATTRS.has(name)) return true;
+  return TAG_ATTRS[tag]?.has(name) ?? false;
+}
+
+function sanitizeAttrValue(tag: string, name: string, value: string): string | null {
+  if (name === 'href') return sanitizeUrl(value, 'link');
+  if (name === 'src' || name === 'poster') return sanitizeUrl(value, 'media');
+  if (
+    (name === 'width' ||
+      name === 'height' ||
+      name === 'span' ||
+      name === 'colspan' ||
+      name === 'rowspan' ||
+      name === 'value') &&
+    !isNonNegativeInteger(value)
+  ) {
+    return null;
+  }
+  if (name === 'start' && !isInteger(value)) return null;
+  if (name === 'type' && tag === 'ol' && !SAFE_OL_TYPES.has(value)) return null;
+  if (name === 'preload' && !SAFE_PRELOAD_VALUES.has(value)) return null;
+  if (name === 'kind' && tag === 'track' && !SAFE_TRACK_KINDS.has(value)) return null;
+  if (name === 'align' && value !== 'left' && value !== 'right' && value !== 'center') return null;
+  if (name === 'target')
+    return value === '_blank' || value === '_self' || value === '_parent' || value === '_top'
+      ? value
+      : null;
+  if (name === 'rel') return sanitizeRel(value);
+  return value;
+}
+
+function sanitizeRel(value: string): string {
+  return relTokens(value).join(' ');
+}
+
+function ensureRelTokens(value: string | undefined, required: string[]): string {
+  const tokens = new Set(value ? relTokens(value) : []);
+  for (const token of required) tokens.add(token);
+  return Array.from(tokens).join(' ');
+}
+
+function relTokens(value: string): string[] {
+  const tokens = value
+    .split(/\s+/)
+    .map((token) => token.trim().toLowerCase())
+    .filter(Boolean)
+    .filter((token) => /^[a-z0-9_-]+$/.test(token));
+  return Array.from(new Set(tokens));
+}
+
+function isInteger(value: string): boolean {
+  return /^-?\d+$/.test(value.trim());
+}
+
+function isNonNegativeInteger(value: string): boolean {
+  return /^\d+$/.test(value.trim());
+}
+
+function firstIndexOfAny(value: string, needles: string[]): number {
+  let result = -1;
+  for (const needle of needles) {
+    const index = value.indexOf(needle);
+    if (index >= 0 && (result < 0 || index < result)) result = index;
+  }
+  return result;
+}
+
+function stripUrlSchemeNoise(value: string): string {
+  let out = '';
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (code <= 0x20 || code === 0x7f || char.trim() === '') continue;
+    out += char;
+  }
+  return out;
+}