@miliastry/quasar 1.0.6 → 1.2.0

package/src/Visitors/HTMLRenderer.ts

@@ -9,17 +9,42 @@
  */
 
 import { RedNode } from '../Syntax/RedNode'
+import {
+  nodeAttrValue,
+  parseImgAttr,
+  sanitizeColor,
+  sanitizeFontFamily,
+  sanitizeFontSize,
+} from '../Syntax/nodeAttr'
 import { Visitor } from './Visitor'
 import type { TagRegistry } from '../Model/TagRegistry'
 import { RenderTree } from '../RenderPipeline/RenderTree'
 
 import type { BBCodeDialect } from '../BBCode/BBCodeToGreenNode'
+import { evaluateEffect, type EffectKind, type EffectParams } from '../Utils/EffectMath'
+import {
+  toTokenResolver,
+  resolveTokenValue,
+  type TokenResolverFn,
+  type TokenSource,
+} from '../Tokens'
 
 export interface HTMLRendererOptions {
-  /** 
-   * Replicate osu! forum BBCode spacing quirks. 
-   * Defaults to true for full compatibility with Miliastry. 
-   * Set to false for a more logical, predictable rendering engine.
+  /**
+   * Replicate osu! forum BBCode spacing quirks.
+   *
+   * NO LO LEE NADIE desde que el motor implementa las reglas reales de
+   * consumo de saltos (ver {@link HTMLRenderer.NEWLINE_RULES}). Sólo gobernaba
+   * dos heurísticas sobre `[code]` que resultaron ser falsas — osu no se come
+   * ningún salto ANTES de un bloque, y el resto de las reglas nunca estuvo
+   * condicionado. El espaciado ya no es opcional: Miliastry es "osu con
+   * esteroides" y rompe líneas igual, así que apagarlo no tendría a qué
+   * volver.
+   *
+   * Se conserva porque es API pública del renderer y quitarlo rompería a quien
+   * lo pase. Es candidato a borrarse en la próxima ruptura de versión.
+   *
+   * @deprecated Sin efecto. El espaciado de osu es ahora incondicional.
    */
   osuBehaviour?: boolean
   /** Registry for resolving custom tags */
@@ -44,19 +69,30 @@ export interface HTMLRendererOptions {
    * timestamp as plain text. Used by map hosts that deep-link into an editor.
    */
   timestampResolver?: (ms: number, label: string) => { href: string; external?: boolean } | null
+  /** Design tokens or resolver function */
+  tokens?: TokenSource
 }
 
+/** Saltos de línea a convertir en `<br>` al pintar un efecto. */
+const NEWLINE_RE = /\n/g
+
+/** Referencia a un token de diseño dentro de un texto: `$nombre`. */
+const TOKEN_REF_RE = /\$([a-zA-Z_][a-zA-Z0-9_-]*)/g
+
 export class HTMLRenderer extends Visitor<string> {
-  private options: Required<Omit<HTMLRendererOptions, 'registry' | 'mediaProxy' | 'entityLinkResolver' | 'mentionResolver' | 'timestampResolver'>> & {
+  private tokenResolver?: TokenResolverFn
+  private options: Required<Omit<HTMLRendererOptions, 'registry' | 'mediaProxy' | 'entityLinkResolver' | 'mentionResolver' | 'timestampResolver' | 'tokens'>> & {
     registry?: TagRegistry
     mediaProxy?: (url: string) => string
     entityLinkResolver?: (kind: string, value: string) => { href: string; external?: boolean } | null
     mentionResolver?: (name: string) => { href: string; external?: boolean } | null
     timestampResolver?: (ms: number, label: string) => { href: string; external?: boolean } | null
+    tokens?: TokenSource
   }
 
   constructor(options: HTMLRendererOptions = {}) {
     super()
+    this.tokenResolver = toTokenResolver(options.tokens)
     this.options = {
       osuBehaviour: options.osuBehaviour ?? true,
       registry: options.registry,
@@ -66,9 +102,19 @@ export class HTMLRenderer extends Visitor<string> {
       entityLinkResolver: options.entityLinkResolver,
       mentionResolver: options.mentionResolver,
       timestampResolver: options.timestampResolver,
+      tokens: options.tokens,
     }
   }
 
+  setTokens(tokens?: TokenSource): void {
+    this.tokenResolver = toTokenResolver(tokens)
+    this.options.tokens = tokens
+  }
+
+  getTokenResolver(): TokenResolverFn | undefined {
+    return this.tokenResolver
+  }
+
   // ─── Tag → HTML Element Map ─────────────────────────────
 
   private readonly BLOCK_TAGS = new Set([
@@ -184,6 +230,25 @@ export class HTMLRenderer extends Visitor<string> {
    */
   private tableDepth = 0
 
+  /**
+   * ¿Estamos emitiendo el vocabulario de clases de osu!?
+   *
+   * osu estiliza box, spoilerbox, notice, imagemap, youtube, los alineados y
+   * los perfiles POR NOMBRE DE CLASE, no por estilo inline. Sobre una userpage
+   * real el HTML de Quasar salía sin estilo porque emitía su propio
+   * vocabulario (`<details>`, `.notice`, `.imagemap-container`…). Bajo
+   * `dialect: 'osu'` se emiten las clases y la estructura de osu; el resto de
+   * dialectos conserva la suya, que es la que sus hojas de estilo esperan.
+   */
+  private isOsu(): boolean {
+    return this.options.dialect === 'osu'
+  }
+
+  /** osu recorta los saltos pegados a la apertura y al cierre de box/notice. */
+  private static trimOsuEdges(html: string): string {
+    return html.replace(/^[\t ]*\r?\n/, '').replace(/\r?\n[\t ]*$/, '')
+  }
+
   private idAttr(node: RedNode): string {
     if (HTMLRenderer.idMode === 'none') return ''
     if (HTMLRenderer.idMode === 'all') return ` data-node-id="${node.id}"`
@@ -203,6 +268,7 @@ export class HTMLRenderer extends Visitor<string> {
     'notice', 'wnotice', 'spoilerbox', 'box', 'boxw', 'list', 'list_item', 'quote', 'code', 'svg',
     'heading', 'center', 'right', 'left', 'align', 'imagemap', 'image', 'video', 'audio',
     'tables', 'table_row', 'gallery', 'columns', 'separator', 'scroll', 'container',
+    'spacing', 'empty_line',
   ])
 
   // ─── Main Entry ─────────────────────────────────────────
@@ -211,7 +277,22 @@ export class HTMLRenderer extends Visitor<string> {
     return this.renderNode(node)
   }
 
+  /**
+   * Ancho de cada tabla abierta, apilado igual que `tableDepth`.
+   *
+   * `getTableContext` corre una vez POR CELDA y recorría todas las filas de
+   * la tabla en cada llamada, con un `.filter()` —y su array— por fila: una
+   * tabla de 20×20 hacía 8.000 arrays intermedios por renderizado para
+   * llegar 400 veces al mismo número. Ahora se calcula una vez al entrar en
+   * la tabla. Va en una pila y no en un caché por nodo porque los hijos de un
+   * `RedNode` SON mutables (`appendChild`/`removeChild`), así que la
+   * identidad del nodo no garantiza que su estructura siga siendo la misma
+   * entre renderizados.
+   */
+  private maxColsStack: number[] = []
+
   render(root: RedNode): string {
+    this.maxColsStack.length = 0
     return this.renderNode(root)
   }
 
@@ -243,14 +324,26 @@ export class HTMLRenderer extends Visitor<string> {
   private renderNode(node: RedNode): string {
     // Leaf nodes
     if (node.children.length === 0 && node.kind === 'text') {
+      let rawText = node.text
+      // El `indexOf` va delante: casi ningún texto lleva un `$`, y así ni se
+      // arranca el motor de expresiones regulares. El patrón es de módulo
+      // porque este es el nodo más frecuente del documento y un literal aquí
+      // dentro construía un `RegExp` por hoja, en cada renderizado.
+      if (this.tokenResolver !== undefined && rawText.indexOf('$') !== -1) {
+        const resolve = this.tokenResolver
+        rawText = rawText.replace(TOKEN_REF_RE, (match, name: string) => {
+          const resolved = resolve(name) ?? resolve(match)
+          return resolved !== undefined ? resolved : match
+        })
+      }
       let out = this.mentionResolver || this.options.timestampResolver
-        ? this.linkifyText(node.text)
-        : this.escapeHtml(node.text)
+        ? this.linkifyText(rawText)
+        : this.escapeHtml(rawText)
       const style = node.metadata?.style as Record<string, string> | undefined
       if (style) {
         const inlineStyles = []
-        const color = style.color && this.sanitizeColor(style.color)
-        const fontSize = style.fontSize && this.sanitizeFontSize(style.fontSize)
+        const color = style.color && sanitizeColor(style.color, this.tokenResolver)
+        const fontSize = style.fontSize && sanitizeFontSize(style.fontSize, this.tokenResolver)
         if (color) inlineStyles.push(`color: ${color}`)
         if (fontSize) inlineStyles.push(`font-size: ${fontSize}%`)
         if (this.isCssKeyword(style.fontWeight)) inlineStyles.push(`font-weight: ${style.fontWeight}`)
@@ -277,7 +370,7 @@ export class HTMLRenderer extends Visitor<string> {
       case 'strikethrough': return this.wrapInline('s', node)
       case 'inline_code': return this.wrapInline('code', node, 'class="inline"')
       case 'spoiler': return this.wrapInline('span', node, 'class="spoiler"')
-      case 'color': return this.wrapInline('span', node, this.colorStyle(node))
+      case 'color': return this.renderColor(node)
       case 'font_size': return this.wrapInline('span', node, this.fontSizeStyle(node))
       case 'font': return this.wrapInline('span', node, this.fontStyle(node))
       case 'url': return this.renderLink(node, 'url')
@@ -286,10 +379,18 @@ export class HTMLRenderer extends Visitor<string> {
       case 'image': return this.renderImage(node)
       case 'video': return this.renderVideo(node)
       case 'audio': return this.renderAudio(node)
-      case 'center': return this.wrapBlock('div', node, 'style="text-align:center;"')
-      case 'right': return this.wrapBlock('div', node, 'style="text-align:right;"')
-      case 'left': return this.wrapBlock('div', node, 'style="text-align:left;"')
-      case 'heading': return this.wrapBlock('h2', node)
+      case 'center': return this.renderAlignAs(node, 'center')
+      case 'right': return this.renderAlignAs(node, 'right')
+      case 'left': return this.renderAlignAs(node, 'left')
+      // Sigue siendo siempre `h2`, como antes: el nivel de BBCode no mapea al
+      // de HTML y un `[heading=9]` daría un `<h9>` inválido. `data-bare-level`
+      // sólo anota que el 2 lo puso el renderer, para que el camino de vuelta
+      // no escriba `[heading=2]` donde el autor había puesto `[heading]`.
+      case 'heading': return this.wrapBlock(
+        'h2',
+        node,
+        node.metadata?.level === undefined ? 'data-bare-level="1"' : '',
+      )
       case 'notice': return this.renderNotice(node, false)
       case 'wnotice': return this.renderNotice(node, true)
       case 'quote': return this.renderQuote(node)
@@ -363,14 +464,18 @@ export class HTMLRenderer extends Visitor<string> {
       case 'bubble': return this.wrapInline('span', node, 'class="bubble"')
       case 'flower': return this.wrapInline('span', node, 'class="flower"')
       case 'gradient': return this.renderGradient(node)
+      // These three had no case at all, so `[rainbow]Hi[/rainbow]` previewed
+      // as bare text while its export was a full colour sweep.
+      case 'rainbow': return this.renderEffectSegments(node, 'rainbow')
+      case 'grow': return this.renderEffectSegments(node, 'grow')
+      case 'sinewave': return this.renderEffectSegments(node, 'sinewave')
+      case 'paint': return this.renderEffectSegments(node, 'paint')
       case 'spacing':
-        if (this.options.osuBehaviour && this.isNextCodeBlock(node)) return '\n'
-        if (this.isTrailingBlockBoundary(node)) return '\n'
-        return this.isPrevBlockBoundary(node) ? '\n' : '<br>'
+        if (this.isNewlineSwallowed(node)) return '\n'
+        return `<br${this.idAttr(node)}>`
       case 'empty_line':
-        if (this.options.osuBehaviour && this.isImmediateEmptyLineBeforeCode(node)) return '\n'
-        if (this.isTrailingBlockBoundary(node)) return '\n'
-        return '<br>'
+        if (this.isNewlineSwallowed(node)) return '\n'
+        return `<div class="bb-empty-line"${this.idAttr(node)}><br></div>`
       case 'group': return this.wrapInline('span', node, 'class="group"')
       // Un párrafo no tiene etiqueta propia en BBCode, pero sí necesita un
       // elemento: sin él, la prosa suelta entre bloques no es clicable —
@@ -378,6 +483,9 @@ export class HTMLRenderer extends Visitor<string> {
       // Un `span` es inline, así que no altera el flujo del texto.
       case 'paragraph': return this.wrapInline('span', node, 'class="bb-paragraph"')
       case 'error': return this.renderError(node)
+      // osu! no muestra un cierre que no cerró nada; el nodo existe solo para
+      // que su rango siga perteneciendo a alguien.
+      case 'discarded_tag': return ''
       case 'text':
         return this.textWrap(node, this.escapeHtml(node.text || ''))
       default:
@@ -401,65 +509,224 @@ export class HTMLRenderer extends Visitor<string> {
     }
   }
 
-  // ─── Render Helpers ─────────────────────────────────────
+  // ─── Newline swallowing ─────────────────────────────────
+  //
+  // osu! turns newlines into `<br />` with one flat rule at the very end of
+  // `BBCodeFromDB::toHTML` — `str_replace("\n", '<br />')`. Every subtlety
+  // lives BEFORE that line: each block pass is a regex that eats the newlines
+  // touching its own tags, so those newlines are simply gone by the time the
+  // flat rule runs. The amount eaten differs per tag, and the asymmetries are
+  // not decorative:
+  //
+  //   parseBox      `\[box=…\]\n*`   `\n*\[/box\]\n?`
+  //   parseCode     `\[code\]\n*`    `\n*\[/code\]\n?`
+  //   parseNotice   `\[notice\]\n*`  `\n*\[/notice\]\n?`
+  //   parseList     `\s*\[\*\]`      `\s*\[/list\]\n?\n?`
+  //   parseQuote    `\[quote…\]\s*`  `\s*\[/quote\]\n?\n?`
+  //   parseHeading  —                `\[/heading\]\n?`
+  //   parseImagemap —                `\[/imagemap\]\n?`
+  //   parseAlignment  strtr of `[centre]\n` and `[/centre]\n` — exactly one
+  //
+  // Quasar used to approximate all of that with two neighbourhood heuristics
+  // (`isPrevBlockBoundary` / `isTrailingBlockBoundary`) that treated every
+  // block alike, so they over-ate at `[centre]`/`[/imagemap]` and under-ate at
+  // `[/list]`/`[/quote]`. This models the real rules instead.
+  //
+  // Deliberately NOT gated on the dialect: Miliastry is "osu with steroids"
+  // and has to break lines the same way. Blocks that only exist in Miliastry
+  // (tables, gallery, columns, scroll, …) have no osu counterpart to copy, so
+  // they keep the legacy behaviour via {@link HTMLRenderer.LEGACY_BLOCK_RULE}.
+
+  /** How many newlines a construct swallows around its own tags. */
+  private static readonly NEWLINE_RULES: Record<string, {
+    /** Newlines eaten right after the opening tag. */
+    afterOpen: 'all' | 'whitespace' | 'one' | 'none'
+    /** Newlines eaten right before the closing tag. */
+    beforeClose: 'all' | 'whitespace' | 'none'
+    /** Whitespace eaten right before the OPENING tag (`\s*\[\*\]`). */
+    beforeOpen: 'whitespace' | 'none'
+    /** Newlines eaten right after the closing tag. */
+    afterClose: number
+  }> = {
+    // `\n*` inside both edges, one newline after the close.
+    box:        { afterOpen: 'all', beforeClose: 'all', beforeOpen: 'none', afterClose: 1 },
+    boxw:       { afterOpen: 'all', beforeClose: 'all', beforeOpen: 'none', afterClose: 1 },
+    spoilerbox: { afterOpen: 'all', beforeClose: 'all', beforeOpen: 'none', afterClose: 1 },
+    notice:     { afterOpen: 'all', beforeClose: 'all', beforeOpen: 'none', afterClose: 1 },
+    wnotice:    { afterOpen: 'all', beforeClose: 'all', beforeOpen: 'none', afterClose: 1 },
+    code:       { afterOpen: 'all', beforeClose: 'all', beforeOpen: 'none', afterClose: 1 },
+    // `\s*` — not just newlines — and TWO newlines after the close.
+    quote:      { afterOpen: 'whitespace', beforeClose: 'whitespace', beforeOpen: 'none', afterClose: 2 },
+    // `[list]` itself eats nothing after its opening tag: the pass that eats
+    // is `\s*\[\*\]`, which needs an item to follow. `[list]\n\nloose text`
+    // keeps both newlines; `[list]\n[*]a` loses one to the item, not the list.
+    list:       { afterOpen: 'none', beforeClose: 'whitespace', beforeOpen: 'none', afterClose: 2 },
+    // `\s*\[\*\]`. The matching `[/*]` of the table exists only in legacy
+    // phpBB rows — `BBCodeForDB` never emits one — so the item's close is
+    // width-less here and its two-newline budget is unreachable by design;
+    // `[*]a\n\n[*]b` loses both newlines to the NEXT item's `\s*`, which is
+    // the same output by a different route.
+    list_item:  { afterOpen: 'none', beforeClose: 'none', beforeOpen: 'whitespace', afterClose: 0 },
+    // strtr with `[centre]\n` / `[/centre]\n`: exactly one on each outer edge,
+    // and nothing before the close — `x\n[/centre]` really does keep its `<br>`.
+    center:     { afterOpen: 'one', beforeClose: 'none', beforeOpen: 'none', afterClose: 1 },
+    left:       { afterOpen: 'one', beforeClose: 'none', beforeOpen: 'none', afterClose: 1 },
+    right:      { afterOpen: 'one', beforeClose: 'none', beforeOpen: 'none', afterClose: 1 },
+    align:      { afterOpen: 'one', beforeClose: 'none', beforeOpen: 'none', afterClose: 1 },
+    heading:    { afterOpen: 'none', beforeClose: 'none', beforeOpen: 'none', afterClose: 1 },
+    imagemap:   { afterOpen: 'none', beforeClose: 'none', beforeOpen: 'none', afterClose: 1 },
+    // `[img]` is inline in osu and swallows nothing at all.
+    image:      { afterOpen: 'none', beforeClose: 'none', beforeOpen: 'none', afterClose: 0 },
+    document:   { afterOpen: 'none', beforeClose: 'none', beforeOpen: 'none', afterClose: 0 },
+  }
 
-  /** osu! quirk: newlines immediately preceding a [code] block are completely ignored */
-  private isNextCodeBlock(node: RedNode): boolean {
-    let next = node.nextSibling
-    while (next && (next.kind === 'spacing' || next.kind === 'empty_line')) {
-      next = next.nextSibling
-    }
-    return next?.kind === 'code'
+  /**
+   * What a Miliastry-only block does. This is what the old
+   * `isPrevBlockBoundary` / `isTrailingBlockBoundary` pair did for every block:
+   * eat the first newline after the open, every newline before the close, and
+   * the first newline after the close.
+   */
+  private static readonly LEGACY_BLOCK_RULE = {
+    afterOpen: 'one', beforeClose: 'all', beforeOpen: 'none', afterClose: 1,
+  } as const
+
+  /**
+   * Containers whose opening tag occupies no source text, so a backwards scan
+   * has to walk straight through them.
+   */
+  private static readonly WIDTHLESS_OPEN = new Set(['paragraph', 'group'])
+
+  /**
+   * Same for the closing side. `list_item` is here because `[/*]` is never
+   * written: an item ends where the next `[*]` or the `[/list]` begins, so
+   * `\s*\[/list\]` sees the newline that Quasar stores inside the item.
+   */
+  private static readonly WIDTHLESS_CLOSE = new Set(['paragraph', 'group', 'list_item'])
+
+  private newlineRule(kind: string) {
+    const rule = HTMLRenderer.NEWLINE_RULES[kind]
+    if (rule) return rule
+    return this.BLOCK_TAGS.has(kind) ? HTMLRenderer.LEGACY_BLOCK_RULE : null
   }
 
-  /** Checks if this is the LAST empty_line right before a code block (skipping only spacing) */
-  private isImmediateEmptyLineBeforeCode(node: RedNode): boolean {
-    let next = node.nextSibling
-    while (next && next.kind === 'spacing') {
-      next = next.nextSibling
-    }
-    return next?.kind === 'code'
+  private static isNewlineNode(node: RedNode): boolean {
+    return node.kind === 'spacing' || node.kind === 'empty_line'
   }
 
-  private isPrevBlockBoundary(node: RedNode): boolean {
-    let prev = node.previousSibling
-    while (prev) {
-      if (prev.kind === 'spacing' || prev.kind === 'empty_line') {
-        prev = prev.previousSibling
-        continue
+  private static isBlankText(node: RedNode): boolean {
+    return node.kind === 'text' && node.children.length === 0 && node.text.trim() === ''
+  }
+
+  /**
+   * Whether this `spacing` / `empty_line` leaf is eaten by a neighbouring tag
+   * and therefore renders nothing.
+   *
+   * Each leaf is exactly ONE source newline (the parser splits a run into one
+   * node per `\n`), so the four scans below can be read straight off the
+   * regexes they mirror. A newline eaten by any of them is eaten: osu's passes
+   * run in a fixed order, but since a consumed newline is consumed whichever
+   * pass claimed it, the union is enough — the per-pass order only matters for
+   * a budget that could be spent elsewhere, and budgets here are counted from
+   * the tag outwards, exactly as `\n?\n?` counts.
+   */
+  private isNewlineSwallowed(node: RedNode): boolean {
+    return this.eatenByOpeningTag(node)
+      || this.eatenByClosingTag(node)
+      || this.eatenAfterClosingTag(node)
+      || this.eatenBeforeOpeningTag(node)
+  }
+
+  /** `\[box\]\n*`, `\[quote\]\s*`, `[centre]\n`. */
+  private eatenByOpeningTag(node: RedNode): boolean {
+    let cur: RedNode = node
+    let newlinesBetween = 0
+    let blankBetween = false
+    for (;;) {
+      const prev = cur.previousSibling
+      if (prev) {
+        if (HTMLRenderer.isNewlineNode(prev)) { newlinesBetween++; cur = prev; continue }
+        if (HTMLRenderer.isBlankText(prev)) { blankBetween = true; cur = prev; continue }
+        return false
       }
-      if (prev.kind === 'text' && prev.text.trim() === '') {
-        prev = prev.previousSibling
-        continue
+      const parent = cur.parent
+      if (!parent) return false
+      if (HTMLRenderer.WIDTHLESS_OPEN.has(parent.kind)) { cur = parent; continue }
+      const rule = this.newlineRule(parent.kind)
+      if (!rule) return false
+      switch (rule.afterOpen) {
+        case 'whitespace': return true
+        // `\n*` matches newlines only: a stray space breaks the run.
+        case 'all': return !blankBetween
+        case 'one': return !blankBetween && newlinesBetween === 0
+        default: return false
       }
-      break
     }
-    
-    if (prev && this.BLOCK_TAGS.has(prev.kind) && prev.kind !== 'image' && prev.kind !== 'imagemap') return true
-    if (!prev && node.parent && this.BLOCK_TAGS.has(node.parent.kind) && node.parent.kind !== 'image' && node.parent.kind !== 'imagemap') return true
+  }
 
-    return false
+  /** `\n*\[/box\]`, `\s*\[/quote\]`, `\s*\[/list\]`. */
+  private eatenByClosingTag(node: RedNode): boolean {
+    let cur: RedNode = node
+    let blankBetween = false
+    for (;;) {
+      const next = cur.nextSibling
+      if (next) {
+        if (HTMLRenderer.isNewlineNode(next)) { cur = next; continue }
+        if (HTMLRenderer.isBlankText(next)) { blankBetween = true; cur = next; continue }
+        return false
+      }
+      const parent = cur.parent
+      if (!parent) return false
+      if (HTMLRenderer.WIDTHLESS_CLOSE.has(parent.kind)) { cur = parent; continue }
+      const rule = this.newlineRule(parent.kind)
+      if (!rule) return false
+      switch (rule.beforeClose) {
+        case 'whitespace': return true
+        case 'all': return !blankBetween
+        default: return false
+      }
+    }
   }
 
-  private isTrailingBlockBoundary(node: RedNode): boolean {
-    let next = node.nextSibling
-    while (next) {
-      if (next.kind === 'spacing' || next.kind === 'empty_line') {
-        next = next.nextSibling
-        continue
+  /** `\[/box\]\n?`, `\[/list\]\n?\n?`. */
+  private eatenAfterClosingTag(node: RedNode): boolean {
+    let cur: RedNode = node
+    let newlinesBetween = 0
+    for (;;) {
+      const prev = cur.previousSibling
+      if (!prev) {
+        const parent = cur.parent
+        if (parent && HTMLRenderer.WIDTHLESS_OPEN.has(parent.kind)) { cur = parent; continue }
+        return false
       }
-      if (next.kind === 'text' && next.text.trim() === '') {
-        next = next.nextSibling
-        continue
+      if (HTMLRenderer.isNewlineNode(prev)) { newlinesBetween++; cur = prev; continue }
+      // Descend to whatever real closing tag sits immediately to our left.
+      let closer: RedNode = prev
+      while (HTMLRenderer.WIDTHLESS_CLOSE.has(closer.kind) && closer.children.length > 0) {
+        closer = closer.children[closer.children.length - 1]
       }
-      break
+      const rule = this.newlineRule(closer.kind)
+      return rule !== null && newlinesBetween < rule.afterClose
     }
-    if (!next && node.parent && this.BLOCK_TAGS.has(node.parent.kind) && node.parent.kind !== 'document') {
-      return true
+  }
+
+  /** `\s*\[\*\]` — the only pass that eats whitespace BEFORE an opening tag. */
+  private eatenBeforeOpeningTag(node: RedNode): boolean {
+    let cur: RedNode = node
+    for (;;) {
+      const next = cur.nextSibling
+      if (next) {
+        if (HTMLRenderer.isNewlineNode(next) || HTMLRenderer.isBlankText(next)) { cur = next; continue }
+        return this.newlineRule(next.kind)?.beforeOpen === 'whitespace'
+      }
+      const parent = cur.parent
+      if (!parent) return false
+      if (HTMLRenderer.WIDTHLESS_CLOSE.has(parent.kind)) { cur = parent; continue }
+      return false
     }
-    return false
   }
 
+  // ─── Render Helpers ─────────────────────────────────────
+
   private renderError(node: RedNode): string {
     const errorMsg = this.escapeHtml((node.metadata?.message as string) || node.text || 'Syntax Error')
     // The content is the raw offending tag, mapped as child text.
@@ -489,21 +756,9 @@ export class HTMLRenderer extends Visitor<string> {
   // half-escaped value still emits broken CSS, so we validate the shape and
   // drop anything that isn't a value we intended to support.
 
-  /** #rgb / #rgba / #rrggbb / #rrggbbaa, a bare CSS color keyword, or rgb()/hsl(). */
-  private static readonly CSS_COLOR_RE =
-    /^(?:#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})|[a-z]{3,20}|(?:rgb|hsl)a?\([0-9a-z.,%\s/+-]{1,64}\))$/i
-
-  /** Bare number — interpolated as a percentage. */
-  private static readonly CSS_SIZE_RE = /^\d{1,4}(?:\.\d{1,2})?$/
-
-  /** Font family list. Quotes are rejected outright; unquoted names are valid CSS. */
-  private static readonly CSS_FONT_RE = /^[A-Za-z0-9 ,_-]{1,120}$/
-
   /** Characters `escapeHtml` has to rewrite. Non-global on purpose: `test` must not carry `lastIndex`. */
   private static readonly HTML_ESCAPE_RE = /[&<>"']/
 
-  private static readonly BARE_HEX_RE = /^[0-9a-f]{3,8}$/i
-
   private static readonly NAMED_COLORS: Record<string, string> = {
     black: '#000000',
     white: '#FFFFFF',
@@ -525,88 +780,84 @@ export class HTMLRenderer extends Visitor<string> {
     gold: '#FFD700',
   }
 
-  private sanitizeColor(raw: string): string | null {
-    let v = raw.trim()
-    if (!v) return null
-    if (HTMLRenderer.BARE_HEX_RE.test(v) && (v.length === 3 || v.length === 4 || v.length === 6 || v.length === 8)) {
-      v = '#' + v
-    }
-    return HTMLRenderer.CSS_COLOR_RE.test(v) ? v : null
-  }
-
-  private sanitizeFontSize(raw: string): string | null {
-    const v = raw.trim()
-    return HTMLRenderer.CSS_SIZE_RE.test(v) ? v : null
-  }
-
-  private sanitizeFontFamily(raw: string): string | null {
-    const v = raw.trim()
-    return HTMLRenderer.CSS_FONT_RE.test(v) ? v : null
-  }
-
   /** Keyword-or-number CSS values (font-weight, font-style, text-decoration). */
   private isCssKeyword(raw: string | undefined): boolean {
     return !!raw && /^[a-z]{2,20}(?: [a-z]{2,20})?$|^[1-9]00$/i.test(raw.trim())
   }
 
   /** Read a metadata field, falling back to the raw tag attribute. */
-  private metaOrAttr(node: RedNode, key: string): string {
-    const meta = node.metadata?.[key]
-    return (typeof meta === 'string' && meta) || this.extractValue(node)
+
+  /**
+   * Lo único que osu! acepta en `[color=…]`.
+   *
+   * Su `BBCodeForDB::parseColour` sella el tag con un uid sólo si el valor
+   * matchea `#[[:xdigit:]]{6}` o `[[:alpha:]]+` — nada más. No valida que el
+   * nombre sea un color CSS de verdad (`banana` pasa), pero `#fff`, `#ffffffff`,
+   * `rgb(...)`, `$token` o un hex sin `#` no pasan. Sin uid, la segunda pasada
+   * no ve el tag y el opener *y* el closer quedan como texto en la página.
+   */
+  private static readonly OSU_COLOR_RE = /^(?:#[0-9a-fA-F]{6}|[a-zA-Z]+)$/
+
+  /**
+   * `[color]` con el vocabulario de cada dialecto.
+   *
+   * Miliastry (y Lyne) aceptan a propósito más que osu: `#RGB`, `#RGBA`, un
+   * `$token` de diseño, nombres propios. Bajo `dialect: 'osu'` eso es una
+   * mentira: el editor pintaría color donde la página publicada muestra el
+   * BBCode crudo. Así que replicamos lo que hace osu — literal el opener,
+   * literal el closer, y los hijos renderizados normalmente en el medio.
+   *
+   * El chequeo mira el texto crudo del atributo, no el valor saneado: osu
+   * matchea sobre la fuente, así que `[color="#ffffff"]` (con comillas) también
+   * se le escapa.
+   */
+  private renderColor(node: RedNode): string {
+    if (this.options.dialect === 'osu') {
+      const text = node.text || ''
+      const eq = text.indexOf('=')
+      // Sin `=` en el texto el nodo no vino del parser de BBCode (import de
+      // HTML, por ejemplo): ahí el único valor disponible es el de metadata.
+      const raw = eq >= 0 ? text.slice(eq + 1) : (text ? '' : nodeAttrValue(node, 'color'))
+      if (!HTMLRenderer.OSU_COLOR_RE.test(raw)) {
+        const opener = eq >= 0 ? `[color${text}]` : `[${text || 'color'}]`
+        return this.escapeHtml(opener) + this.renderChildren(node) + this.escapeHtml('[/color]')
+      }
+    }
+    return this.wrapInline('span', node, this.colorStyle(node))
   }
 
   private colorStyle(node: RedNode): string {
-    const color = this.sanitizeColor(this.metaOrAttr(node, 'color'))
+    const color = sanitizeColor(nodeAttrValue(node, 'color'), this.tokenResolver)
     return color ? `style="color:${color};"` : ''
   }
 
   private fontSizeStyle(node: RedNode): string {
-    const size = this.sanitizeFontSize(this.metaOrAttr(node, 'size'))
+    const size = sanitizeFontSize(nodeAttrValue(node, 'size'), this.tokenResolver)
     return size ? `style="font-size:${size}%;"` : ''
   }
 
   private fontStyle(node: RedNode): string {
-    const font = this.sanitizeFontFamily(this.metaOrAttr(node, 'font'))
+    const font = sanitizeFontFamily(nodeAttrValue(node, 'font'), this.tokenResolver)
     return font ? `style="font-family:${font};"` : ''
   }
 
-  /**
-   * Extract the attribute value from a BBCode tag node.
-   *
-   * BBCode attributes come in the format `=VALUE` (e.g. `=#61afef`, `="Author"`,
-   * `=https://osu.ppy.sh`). This strips the leading `=` and any surrounding quotes.
-   *
-   * For tags without attrs (like text nodes, img content), returns the node text as-is.
-   */
-  private extractValue(node: RedNode): string {
-    const text = node.text || ''
-    if (!text) return ''
-
-    const eqIdx = text.indexOf('=')
-    if (eqIdx >= 0) {
-      // Strip `=` prefix and surrounding quotes
-      let value = text.slice(eqIdx + 1)
-      // Remove surrounding quotes: "value" or 'value'
-      if ((value.startsWith('"') && value.endsWith('"')) ||
-          (value.startsWith("'") && value.endsWith("'"))) {
-        value = value.slice(1, -1)
-      }
-      return value
-    }
-
-    // No `=` prefix — return as-is (used for media content like img URLs)
-    return text
-  }
-
   private renderLink(node: RedNode, kind: string): string {
-    let href = String(node.metadata?.href ?? '') || this.extractValue(node)
+    let href = String(node.metadata?.href ?? '') || nodeAttrValue(node)
+    // Un `[email]a@b.com[/email]` llega con href exactamente `mailto:` y la
+    // dirección en el hijo de texto. Sin completarlo aquí el href quedaba
+    // vacío y el round-trip devolvía `[url=mailto:]a@b.com[/url]`.
+    if (kind === 'email' && href === 'mailto:') {
+      href += node.children.map(c => c.text || '').join('')
+    }
     // Ensure the URL has a protocol for external links
     if (href && !href.startsWith('http://') && !href.startsWith('https://') && !href.startsWith('mailto:')) {
       href = 'https://' + href
     }
     const content = this.renderChildren(node) || href
     const h = href ? ` href="${this.escapeHtml(href)}"` : ''    
-    return `<a${this.idAttr(node)}${h} target="_blank" rel="noopener">${content}</a>`
+    const hasMediaChild = node.children.some(c => c.kind === 'image' || c.kind === 'svg' || c.kind === 'video')
+    const imgCls = hasMediaChild ? ' class="bb-link-img"' : ''
+    return `<a${this.idAttr(node)}${imgCls}${h} target="_blank" rel="noopener">${content}</a>`
   }
 
   private renderProfile(node: RedNode): string {
@@ -615,48 +866,64 @@ export class HTMLRenderer extends Visitor<string> {
 
   private renderEntity(node: RedNode, type: 'profile' | 'guild' | 'map'): string {
     const key = type === 'profile' ? 'username' : type === 'guild' ? 'tag' : 'id'
-    const val = String(node.metadata?.[key] ?? '') || this.extractValue(node)
+    const val = String(node.metadata?.[key] ?? '') || nodeAttrValue(node)
     const content = this.renderChildren(node) || val
+    // El converter HTML→BBCode ve `<strong><a>`, no la etiqueta original. Sin
+    // esta marca `[profile]peppy[/profile]` volvía como `[b][url=...]…[/url][/b]`,
+    // y sin el valor `[profile=5458323]` perdía el id y volvía como `[profile]`.
+    const entity = ` data-entity="${type}"` +
+      (val ? ` data-entity-value="${this.escapeHtml(val)}"` : '')
     if (this.options.entityLinkResolver) {
       const link = this.options.entityLinkResolver(type, val || content)
       if (link) {
         const ext = link.external ? ' target="_blank" rel="noopener noreferrer"' : ''
-        return `<strong><a${this.idAttr(node)} href="${this.escapeHtml(link.href)}"${ext}>${content}</a></strong>`
+        return `<strong${entity}><a${this.idAttr(node)} href="${this.escapeHtml(link.href)}"${ext}>${content}</a></strong>`
       }
     }
+    if (type === 'profile' && this.isOsu()) {
+      // Sacado de los fixtures `basic_profile*` de osu-web, no adivinado: el
+      // enlace es un `<a>` pelado (nada de `<strong>`), y `data-user-id` lleva
+      // el id numérico cuando `[profile=N]` lo trae y `@` + el texto crudo
+      // cuando no. El href es ese mismo valor, URL-encoded.
+      const key = val || `@${this.collectNodeText(node)}`
+      const href = `https://osu.ppy.sh/users/${encodeURIComponent(key)}`
+      return `<a${this.idAttr(node)}${entity} class="user-name js-usercard" data-user-id="${this.escapeHtml(key)}" href="${href}">${content}</a>`
+    }
     if (type === 'profile') {
       const url = this.options.theme === 'lyne' || this.options.dialect === 'lyne'
         ? `/u/${encodeURIComponent(val || content)}`
         : `https://osu.ppy.sh/users/${this.escapeHtml(val || content)}`
-      return `<strong><a${this.idAttr(node)} href="${url}" target="_blank" rel="noopener">${content}</a></strong>`
+      return `<strong${entity}><a${this.idAttr(node)} href="${url}" target="_blank" rel="noopener">${content}</a></strong>`
     }
     if (type === 'guild') {
-      return `<strong><a${this.idAttr(node)} href="/guilds/${encodeURIComponent(val || content)}">${content}</a></strong>`
+      return `<strong${entity}><a${this.idAttr(node)} href="/guilds/${encodeURIComponent(val || content)}">${content}</a></strong>`
     }
     if (type === 'map') {
-      return `<strong><a${this.idAttr(node)} href="/maps/${encodeURIComponent(val || content)}">${content}</a></strong>`
+      return `<strong${entity}><a${this.idAttr(node)} href="/maps/${encodeURIComponent(val || content)}">${content}</a></strong>`
     }
-    return `<strong><a${this.idAttr(node)} href="#">${content}</a></strong>`
+    return `<strong${entity}><a${this.idAttr(node)} href="#">${content}</a></strong>`
   }
 
-  private parseImgAttr(v: string | null): { w?: number; h?: number; round?: boolean; shadow?: boolean; float?: boolean } {
-    if (!v) return {}
-    const t = v.trim().toLowerCase()
-    if (t === 'round') return { round: true }
-    if (t === 'shadow') return { shadow: true }
-    if (t === 'float') return { float: true }
-    const m = /^(\d{1,4})x(\d{1,4})$/i.exec(t)
-    if (m) return { w: Math.min(2000, parseInt(m[1], 10)), h: Math.min(2000, parseInt(m[2], 10)) }
-    return {}
+  /**
+   * El aviso que ocupa el sitio de un medio que no se puede pintar.
+   *
+   * Lleva `data-bb-empty` con la etiqueta de origen porque el camino
+   * HTML→BBCode lee de vuelta lo que hay en el lienzo: sin la marca, el texto
+   * del aviso entraba al documento como contenido y se comía la etiqueta. En
+   * `docs/ai/hxovc.bbcode`, con cinco `[img][/img]` vacíos, cada edición del
+   * bloque convertía otro en la frase «[img] missing source URL».
+   */
+  private mediaError(tag: string, message: string): string {
+    return `<div class="media-error" data-bb-empty="${tag}">${message}</div>`
   }
 
   private renderImage(node: RedNode): string {
-    let src = String(node.metadata?.src ?? '') || this.extractValue(node) || ''
-    if (!src) return '<div class="media-error">[img] missing source URL</div>'
+    let src = String(node.metadata?.src ?? '') || nodeAttrValue(node) || ''
+    if (!src) return this.mediaError('img', '[img] missing source URL')
     if (this.options.mediaProxy) {
       src = this.options.mediaProxy(src)
     }
-    const imgAttr = this.parseImgAttr(this.extractValue(node))
+    const imgAttr = parseImgAttr(nodeAttrValue(node))
     const styles: string[] = []
     if (imgAttr.w) styles.push(`width:${imgAttr.w}px`)
     if (imgAttr.h) styles.push(`height:${imgAttr.h}px`)
@@ -671,15 +938,25 @@ export class HTMLRenderer extends Visitor<string> {
       styles.push('max-width:100%', 'height:auto', 'display:inline-block')
     }
     const cls = imgAttr.round ? '' : ' class="bb-img"'
-    return `<img${this.idAttr(node)}${cls} src="${this.escapeHtml(src)}" alt="" style="${styles.join(';')};">`
+    // El modificador no se puede reconstruir desde el `style` resultante
+    // (`round` y `120x120` producen el mismo CSS), así que viaja literal.
+    const rawAttr = nodeAttrValue(node)
+    const attr = rawAttr ? ` data-img-attr="${this.escapeHtml(rawAttr)}"` : ''
+    return `<img${this.idAttr(node)}${cls}${attr} src="${this.escapeHtml(src)}" alt="" style="${styles.join(';')};">`
   }
 
   private renderVideo(node: RedNode): string {
-    let id = String(node.metadata?.videoId ?? '') || this.extractValue(node) || ''
-    if (!id) return '<div class="media-error">[youtube] missing video ID</div>'
+    let id = String(node.metadata?.videoId ?? '') || nodeAttrValue(node) || ''
+    if (!id) return this.mediaError('youtube', '[youtube] missing video ID')
     const ytMatch = /(?:youtu\.be\/|v=|\/embed\/|\/shorts\/)([\w-]{11})/.exec(id)
     if (ytMatch) id = ytMatch[1]
-    return `<iframe${this.idAttr(node)} src="https://www.youtube.com/embed/${this.escapeHtml(id)}" frameborder="0" allowfullscreen></iframe>`
+    // `data-youtube` es lo que deja al converter HTML→BBCode reconocer este
+    // iframe. Sin él el vídeo volvía como un `group` vacío: se perdía entero.
+    // Las clases de osu van en el iframe mismo, no en un div contenedor: son
+    // las que le dan la caja 16:9. Y su `src` lleva siempre `?rel=0`.
+    const cls = this.isOsu() ? 'u-embed-wide u-embed-wide--bbcode' : 'bb-youtube'
+    const rel = this.isOsu() ? '?rel=0' : ''
+    return `<iframe${this.idAttr(node)} class="${cls}" data-youtube="${this.escapeHtml(id)}" src="https://www.youtube.com/embed/${this.escapeHtml(id)}${rel}" frameborder="0" allowfullscreen></iframe>`
   }
 
   private renderAudio(node: RedNode): string {
@@ -687,6 +964,31 @@ export class HTMLRenderer extends Visitor<string> {
     if (this.options.mediaProxy && src) {
       src = this.options.mediaProxy(src)
     }
+    const isLyne = this.options.theme === 'lyne' || this.options.dialect === 'lyne'
+    if (isLyne) {
+      const rawName = src.split('?')[0].split('#')[0].split('/').filter(Boolean).pop() || 'audio_track.mp3'
+      let fileName = rawName
+      try {
+        fileName = decodeURIComponent(rawName)
+      } catch {}
+      return `<div${this.idAttr(node)} class="lx-audio bb-audio" data-src="${this.escapeHtml(src)}">`
+        + `<audio preload="metadata" src="${this.escapeHtml(src)}"></audio>`
+        + `<div class="lx-track" role="progressbar" aria-label="Audio progress"><div class="fill"></div></div>`
+        + `<div class="lx-row">`
+        + `<button type="button" class="lx-btn" aria-label="Play"><svg viewBox="0 0 16 16"><path d="M3 1.5 14 8 3 14.5z"/></svg></button>`
+        + `<div class="lx-title">`
+        + `<div class="name">${this.escapeHtml(fileName)}</div>`
+        + `<div class="label"><span class="dot"></span> <span class="status-text">audio</span></div>`
+        + `</div>`
+        + `<div class="lx-vol">`
+        + `<button type="button" class="lx-vol-btn" aria-label="Mute"><svg viewBox="0 0 16 16"><path d="M10.707 11.182A4.5 4.5 0 0 0 12.025 8a4.5 4.5 0 0 0-1.318-3.182L10 5.525A3.5 3.5 0 0 1 11.025 8 3.5 3.5 0 0 1 10 10.475zM6.717 3.55A.5.5 0 0 1 7 4v8a.5.5 0 0 1-.812.39L3.825 10.5H1.5A.5.5 0 0 1 1 10V6a.5.5 0 0 1 .5-.5h2.325l2.363-1.89a.5.5 0 0 1 .529-.06"/></svg></button>`
+        + `<input type="range" class="lx-vol-slider" min="0" max="1" step="0.01" value="0.2" aria-label="Volume" style="background:linear-gradient(to right, var(--color-accent, #2EE6E2) 20%, var(--color-inset-well, #080D20) 20%);" />`
+        + `</div>`
+        + `<button type="button" class="lx-speed" aria-label="Playback speed">1.0×</button>`
+        + `<div class="lx-time"><span class="cur">0:00</span> / <span class="total">–:––</span></div>`
+        + `</div>`
+        + `</div>`
+    }
     return `<audio${this.idAttr(node)} controls src="${this.escapeHtml(src)}" class="bb-audio"></audio>`
   }
 
@@ -707,7 +1009,7 @@ export class HTMLRenderer extends Visitor<string> {
   private renderNotice(node: RedNode, warning: boolean): string {
     const isLyne = this.options.theme === 'lyne' || this.options.dialect === 'lyne' || warning
     if (isLyne) {
-      const color = this.sanitizeColor(this.metaOrAttr(node, 'color'))
+      const color = sanitizeColor(nodeAttrValue(node, 'color'), this.tokenResolver)
       const styleAttr = color
         ? ` style="background:${this.hexToRgba(color, 0.08)};border-color:${this.hexToRgba(color, 0.4)};border-left-color:${color};color:${this.hexToRgba(color, 0.85)};"`
         : ''
@@ -717,11 +1019,18 @@ export class HTMLRenderer extends Visitor<string> {
       return `<div${this.idAttr(node)} class="notice bb-cut-panel bb-notice${warning ? ' bb-wnotice' : ''}" role="note"${styleAttr}>${warningIcon}<div class="bb-notice-body">${content}</div></div>`
     }
 
+    // osu pinta el aviso con `.well` a secas — no hay ninguna clase `notice`
+    // en su hoja de estilos, que es por lo que el bloque salía desnudo.
+    if (this.isOsu()) {
+      const content = HTMLRenderer.trimOsuEdges(this.renderChildren(node))
+      return `<div${this.idAttr(node)} class="well">${content}</div>`
+    }
+
     return this.wrapBlock('div', node, 'class="notice"')
   }
 
   private renderTables(node: RedNode): string {
-    const variant = (String(node.metadata?.variant ?? '') || this.extractValue(node) || '').trim().toLowerCase()
+    const variant = (String(node.metadata?.variant ?? '') || nodeAttrValue(node) || '').trim().toLowerCase()
     const variants = new Set(variant.split(/[\s,]+/).filter(Boolean))
     const tableClasses = [
       'bb-table',
@@ -729,7 +1038,9 @@ export class HTMLRenderer extends Visitor<string> {
       variants.has('borders') ? 'bb-table-borders' : '',
     ].filter(Boolean).join(' ')
     this.tableDepth++
+    this.maxColsStack.push(HTMLRenderer.widestRow(node))
     const content = this.renderChildren(node)
+    this.maxColsStack.pop()
     this.tableDepth--
     // `[tables=striped:#hex]`: de `--table-accent` se deriva toda la paleta
     // de la tabla (gradiente del frame, hover de filas, encabezado, bordes).
@@ -737,22 +1048,52 @@ export class HTMLRenderer extends Visitor<string> {
     return `<div${this.idAttr(node)} class="bb-table-frame"${accent}><table class="${tableClasses}"><tbody>${content}</tbody></table></div>`
   }
 
+  /** Celdas directas de una fila, sin materializar un array intermedio. */
+  private static countCells(node: RedNode): number {
+    let count = 0
+    const children = node.children
+    for (let i = 0; i < children.length; i++) {
+      const kind = children[i].kind
+      if (kind === 'table_th' || kind === 'table_col') count++
+    }
+    return count
+  }
+
+  /**
+   * Columnas de la tabla más ancha bajo `tableNode`, memoizado por tabla.
+   *
+   * `getTableContext` se llama una vez POR CELDA, y recorría todas las filas
+   * de la tabla en cada llamada, con un `.filter()` —y su array— por fila.
+   * Una tabla de 20×20 hacía 8.000 arrays intermedios en cada renderizado
+   * para llegar 400 veces al mismo número. El caché se vacía al empezar cada
+   * render, así que no retiene nodos entre documentos.
+   */
+  private static widestRow(tableNode: RedNode): number {
+    let maxCols = 1
+    const rows = tableNode.children
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i]
+      if (row.kind !== 'table_row') continue
+      const count = HTMLRenderer.countCells(row)
+      if (count > maxCols) maxCols = count
+    }
+    return maxCols
+  }
+
   private getTableContext(node: RedNode): { cellCount: number; maxCols: number; isDirect: boolean } {
     const parent = node.parent
     const isDirect = parent?.kind === 'tables'
     const tableNode = isDirect ? parent : (parent?.parent?.kind === 'tables' ? parent.parent : undefined)
-    const cellCount = parent?.children
-      ? parent.children.filter(c => c.kind === 'table_th' || c.kind === 'table_col').length
-      : 1
+    const cellCount = parent ? HTMLRenderer.countCells(parent) : 1
 
     let maxCols = cellCount
     if (tableNode) {
-      for (const row of tableNode.children) {
-        if (row.kind === 'table_row') {
-          const count = row.children.filter(c => c.kind === 'table_th' || c.kind === 'table_col').length
-          if (count > maxCols) maxCols = count
-        }
-      }
+      // La tabla en curso está en lo alto de la pila; solo se recorre si esta
+      // celda llegó por un camino que no pasó por `renderTables`.
+      const widest = this.maxColsStack.length > 0
+        ? this.maxColsStack[this.maxColsStack.length - 1]
+        : HTMLRenderer.widestRow(tableNode)
+      if (widest > maxCols) maxCols = widest
     }
     return { cellCount, maxCols, isDirect }
   }
@@ -763,7 +1104,7 @@ export class HTMLRenderer extends Visitor<string> {
   }
 
   private renderColumns(node: RedNode): string {
-    const cols = parseInt(String(node.metadata?.columns ?? '') || this.extractValue(node) || '2', 10)
+    const cols = parseInt(String(node.metadata?.columns ?? '') || nodeAttrValue(node) || '2', 10)
     const numCols = Math.max(2, Math.min(4, isNaN(cols) ? 2 : cols))
     const content = this.renderChildren(node)
     // `[columns=2:#hex]`: con color se añade la superficie (borde + fondo
@@ -775,27 +1116,27 @@ export class HTMLRenderer extends Visitor<string> {
   }
 
   private renderSeparator(node: RedNode): string {
-    const variant = (String(node.metadata?.variant ?? '') || this.extractValue(node) || 'line').trim().toLowerCase()
+    const variant = (String(node.metadata?.variant ?? '') || nodeAttrValue(node) || 'line').trim().toLowerCase()
     if (variant === 'dots') return `<div${this.idAttr(node)} class="bb-separator">· · ·</div>`
     if (variant === 'stars') return `<div${this.idAttr(node)} class="bb-separator">✦ ✦ ✦</div>`
     return `<hr${this.idAttr(node)} class="bb-separator" />`
   }
 
   private renderScroll(node: RedNode): string {
-    const h = parseInt(String(node.metadata?.height ?? '') || this.extractValue(node) || '200', 10)
+    const h = parseInt(String(node.metadata?.height ?? '') || nodeAttrValue(node) || '200', 10)
     const maxH = Math.max(50, Math.min(2000, isNaN(h) ? 200 : h))
     const content = this.renderChildren(node)
     return `<div${this.idAttr(node)} class="bb-scroll" style="max-height:${maxH}px;">${content}</div>`
   }
 
   private renderAbbr(node: RedNode): string {
-    const title = String(node.metadata?.title ?? '') || this.extractValue(node)
+    const title = String(node.metadata?.title ?? '') || nodeAttrValue(node)
     const attr = title ? ` title="${this.escapeHtml(title)}"` : ''
     return this.wrapInline('abbr', node, attr)
   }
 
   private renderTooltip(node: RedNode): string {
-    const tip = String(node.metadata?.tip ?? '') || this.extractValue(node)
+    const tip = String(node.metadata?.tip ?? '') || nodeAttrValue(node)
     const attr = tip ? ` title="${this.escapeHtml(tip)}"` : ''
     return this.wrapInline('span', node, `class="bb-tooltip"${attr}`)
   }
@@ -810,16 +1151,31 @@ export class HTMLRenderer extends Visitor<string> {
   }
 
   private renderAlign(node: RedNode): string {
-    const alignVal = (String(node.metadata?.align ?? '') || this.extractValue(node) || 'center').trim().toLowerCase()
+    const alignVal = (String(node.metadata?.align ?? '') || nodeAttrValue(node) || 'center').trim().toLowerCase()
     const validAlign = alignVal === 'left' || alignVal === 'right' ? alignVal : 'center'
-    return this.wrapBlock('div', node, `style="text-align:${validAlign};"`)
+    return this.renderAlignAs(node, validAlign)
+  }
+
+  /**
+   * `[centre]` / `[left]` / `[right]` (y `[align=…]`).
+   *
+   * osu! no usa `text-align` inline: estiliza el bloque por nombre de clase,
+   * con la grafía británica `centre`. Fuera del dialecto osu el estilo inline
+   * se mantiene, porque ni Miliastry ni Lyne traen esas reglas.
+   */
+  private renderAlignAs(node: RedNode, align: 'center' | 'left' | 'right'): string {
+    if (this.isOsu()) {
+      const name = align === 'center' ? 'centre' : align
+      return this.wrapBlock('div', node, `class="bbcode__align-${name}"`)
+    }
+    return this.wrapBlock('div', node, `style="text-align:${align};"`)
   }
 
   private renderEffect(node: RedNode): string {
-    const raw = (String(node.metadata?.effectType ?? '') || this.extractValue(node) || 'glow').toLowerCase().trim()
+    const raw = (String(node.metadata?.effectType ?? '') || nodeAttrValue(node) || 'glow').toLowerCase().trim()
     const effectType = raw.includes(':') ? raw.split(':')[0] : (raw.startsWith('#') ? 'glow' : raw)
-    const rawColor = String(node.metadata?.color ?? '') || (raw.includes(':') ? raw.split(':')[1] : (raw.startsWith('#') ? raw : this.extractValue(node)))
-    const color = this.sanitizeColor(rawColor)
+    const rawColor = String(node.metadata?.color ?? '') || (raw.includes(':') ? raw.split(':')[1] : (raw.startsWith('#') ? raw : nodeAttrValue(node)))
+    const color = sanitizeColor(rawColor, this.tokenResolver)
     const content = this.renderChildren(node)
     const idAttr = this.idAttr(node)
 
@@ -852,7 +1208,7 @@ export class HTMLRenderer extends Visitor<string> {
   }
 
   private renderAnim(node: RedNode): string {
-    const raw = (String(node.metadata?.animType ?? '') || this.extractValue(node) || 'pulse').toLowerCase().trim()
+    const raw = (String(node.metadata?.animType ?? '') || nodeAttrValue(node) || 'pulse').toLowerCase().trim()
     const animType = raw.includes(':') ? raw.split(':')[0] : raw
     const content = this.renderChildren(node)
     const idAttr = this.idAttr(node)
@@ -880,7 +1236,7 @@ export class HTMLRenderer extends Visitor<string> {
   }
 
   private renderContainer(node: RedNode): string {
-    const raw = (String(node.metadata?.containerType ?? '') || this.extractValue(node) || 'stack').trim()
+    const raw = (String(node.metadata?.containerType ?? '') || nodeAttrValue(node) || 'stack').trim()
     const [type, ...params] = raw.split(':')
     const containerType = type.toLowerCase()
     const param = params.join(':')
@@ -904,7 +1260,7 @@ export class HTMLRenderer extends Visitor<string> {
         return `<div${idAttr} class="bb-middle">${content}</div>`
       case 'square':
       case 'circle': {
-        const accent = this.sanitizeColor(param)
+        const accent = sanitizeColor(param, this.tokenResolver)
         const border = accent ? this.hexToRgba(accent, 0.35) : ''
         const bg = accent ? this.hexToRgba(accent, 0.08) : ''
         const style = accent ? ` style="--square-accent:${accent};--square-border:${border};--square-bg:${bg};"` : ''
@@ -917,14 +1273,14 @@ export class HTMLRenderer extends Visitor<string> {
         // del que el CSS deriva borde, tinte de fondo y —vía la clase
         // `bb-accented`— la paleta del contenido sin color propio. Sin color,
         // defaults y sin clase.
-        const accent = this.sanitizeColor(param)
+        const accent = sanitizeColor(param, this.tokenResolver)
         const cls = accent ? ' bb-accented' : ''
         const style = accent ? ` style="--${containerType}-accent:${accent};"` : ''
         return `<div${idAttr} class="bb-cut-panel bb-${containerType}${cls}"${style}>${content}</div>`
       }
       case 'neon-box':
       case 'neonbox': {
-        const c = this.sanitizeColor(param || this.extractValue(node)) || 'var(--color-accent, #2EE6E2)'
+        const c = sanitizeColor(param || nodeAttrValue(node), this.tokenResolver) || 'var(--color-accent, #2EE6E2)'
         return `<div${idAttr} class="bb-cut-panel bb-neon-box" style="--neon-color:${c};border-color:${c};">${content}</div>`
       }
       default:
@@ -943,7 +1299,7 @@ export class HTMLRenderer extends Visitor<string> {
   ])
 
   private renderStyleTag(node: RedNode): string {
-    const raw = (String(node.metadata?.style ?? '') || this.extractValue(node) || '').trim()
+    const raw = (String(node.metadata?.style ?? '') || nodeAttrValue(node) || '').trim()
     const content = this.renderChildren(node)
     const idAttr = this.idAttr(node)
     if (!raw) return `<span${idAttr}>${content}</span>`
@@ -961,7 +1317,10 @@ export class HTMLRenderer extends Visitor<string> {
       // color-mix()…) — antes se eliminaban y rompían esos valores. Lo que sí
       // se bloquea son las funciones/fuentes peligrosas (url(), expression(),
       // javascript:), que no tienen uso legítimo en el whitelist de props.
-      const safeVal = val.replace(/["'{}<>]/g, '').slice(0, 100)
+      let safeVal = val.replace(/["'{}<>]/g, '').slice(0, 100)
+      if (safeVal.startsWith('$') && this.tokenResolver) {
+        safeVal = resolveTokenValue(safeVal, this.tokenResolver)
+      }
       if (/url\s*\(|expression\s*\(|javascript\s*:/i.test(safeVal)) continue
       safeStyles.push(`${prop}:${safeVal}`)
     }
@@ -971,7 +1330,7 @@ export class HTMLRenderer extends Visitor<string> {
   }
 
   private renderQuote(node: RedNode): string {
-    const source = node.metadata?.source || this.extractValue(node)
+    const source = node.metadata?.source || nodeAttrValue(node)
     const content = this.renderChildren(node)
     if (source) {
       return `<blockquote${this.idAttr(node)}><div style="margin-bottom:8px"><strong>${this.escapeHtml(String(source))} wrote:</strong></div>${content}</blockquote>`
@@ -979,8 +1338,34 @@ export class HTMLRenderer extends Visitor<string> {
     return `<blockquote${this.idAttr(node)}>${content}</blockquote>`
   }
 
+  /**
+   * La estructura exacta que `bbcode-spoilerbox` de osu-web espera.
+   *
+   * El toggle de osu es JS: `js-spoilerbox__link` es el gancho del click y
+   * `js-spoilerbox__body` el panel que abre. Si falta cualquiera de las dos
+   * clases el box queda mudo, así que la estructura no es decorativa.
+   */
+  private renderOsuSpoilerbox(node: RedNode, title: string, extra: string): string {
+    const content = HTMLRenderer.trimOsuEdges(this.renderChildren(node))
+    return `<div${this.idAttr(node)} class="js-spoilerbox bbcode-spoilerbox"${extra}>` +
+      `<a class="js-spoilerbox__link bbcode-spoilerbox__link" href="#">` +
+      `<span class="bbcode-spoilerbox__link-icon"></span>` +
+      `<span class="bbcode-spoilerbox__link-text">${title}</span></a>` +
+      `<div class="js-spoilerbox__body bbcode-spoilerbox__body">${content}</div></div>`
+  }
+
+  /** El rótulo de un box bajo osu: el del autor, o `SPOILER` en mayúsculas. */
+  private osuBoxTitle(node: RedNode): string {
+    return this.hasOwnTitle(node) ? this.renderTitle(node, 'SPOILER') : 'SPOILER'
+  }
+
   private renderSpoilerbox(node: RedNode): string {
+    if (this.isOsu()) {
+      // Un [spoilerbox] sin título propio se rotula SPOILER, en mayúsculas.
+      return this.renderOsuSpoilerbox(node, this.osuBoxTitle(node), this.bareTitleAttr(node))
+    }
     const title = this.renderTitle(node, 'Spoiler')
+    const bare = this.bareTitleAttr(node)
     const content = this.renderChildren(node)
     const isLyne = this.options.theme === 'lyne' || this.options.dialect === 'lyne'
     const bodyCls = isLyne ? 'bb-box-body' : 'bbcode-box-body'
@@ -990,11 +1375,17 @@ export class HTMLRenderer extends Visitor<string> {
     // `--box-accent` colorea el acento del box (título + chevron, y el borde
     // en boxw) cuando el autor puso `[box=Title:#hex]`.
     const accent = this.boxAccentStyle(node)
-    return `<details${this.idAttr(node)}${accent}><summary><span class="bb-box-heading">${title}</span></summary><div class="${bodyCls}">${content}</div></details>`
+    return `<details${this.idAttr(node)}${bare}${accent}><summary><span class="bb-box-heading">${title}</span></summary><div class="${bodyCls}">${content}</div></details>`
   }
 
   private renderBox(node: RedNode): string {
+    if (this.isOsu()) {
+      // osu no distingue box de spoilerbox: es la misma construcción, y sin
+      // título propio rotula SPOILER igual que `[spoilerbox]`.
+      return this.renderOsuSpoilerbox(node, this.osuBoxTitle(node), this.bareTitleAttr(node))
+    }
     const title = this.renderTitle(node, 'Box')
+    const bare = this.bareTitleAttr(node)
     const content = this.renderChildren(node)
     const isLyne = this.options.theme === 'lyne' || this.options.dialect === 'lyne'
     const bodyCls = isLyne ? 'bb-box-body' : 'bbcode-box-body'
@@ -1006,7 +1397,30 @@ export class HTMLRenderer extends Visitor<string> {
     // (no `bb-box-title`) evita la regla legacy `.bbcode-preview .bb-box-title`
     // de la app, que pinta un fondo sobre el título.
     const accent = this.boxAccentStyle(node)
-    return `<details${this.idAttr(node)} class="${cls}"${accent}><summary><span class="bb-box-heading">${title}</span></summary><div class="${bodyCls}">${content}</div></details>`
+    return `<details${this.idAttr(node)} class="${cls}"${bare}${accent}><summary><span class="bb-box-heading">${title}</span></summary><div class="${bodyCls}">${content}</div></details>`
+  }
+
+  /**
+   * Marca un `[box]`/`[spoilerbox]` sin título propio.
+   *
+   * El `<summary>` siempre lleva texto ("Box", "Spoiler"), así que sin esta
+   * marca el camino HTML→BBCode leía ese relleno como si el autor lo hubiera
+   * escrito y devolvía `[box=Box]`.
+   */
+  private bareTitleAttr(node: RedNode): string {
+    return this.hasOwnTitle(node) ? '' : ' data-bare-title="1"'
+  }
+
+  /**
+   * ¿El título del box lo escribió el autor, o es el relleno del parser?
+   *
+   * `BBCodeToGreenNode` ya deja `metadata.title = 'Box'`/`'Spoiler'` para un
+   * tag pelado, así que el `fallback` de `renderTitle` nunca llega a usarse:
+   * quien quiera otro rótulo por defecto tiene que preguntar por aquí.
+   */
+  private hasOwnTitle(node: RedNode): boolean {
+    const raw = node.metadata?.rawTitle
+    return raw !== undefined ? String(raw) !== '' : node.metadata?.title !== undefined
   }
 
   private renderTitle(node: RedNode, fallback: string): string {
@@ -1014,8 +1428,14 @@ export class HTMLRenderer extends Visitor<string> {
     if (titleNodes && titleNodes.length > 0) {
       return titleNodes.map(c => this.renderNode(c)).join('')
     }
-    const title = node.metadata?.title ?? this.extractValue(node) ?? fallback
-    return this.escapeHtml(String(title))
+    let title = String(node.metadata?.title ?? nodeAttrValue(node) ?? fallback)
+    if (this.tokenResolver) {
+      title = title.replace(/\$([a-zA-Z_][a-zA-Z0-9_-]*)/g, (match, name) => {
+        const resolved = this.tokenResolver!(name) ?? this.tokenResolver!(match)
+        return resolved !== undefined ? resolved : match
+      })
+    }
+    return this.escapeHtml(title)
   }
 
   /**
@@ -1025,7 +1445,7 @@ export class HTMLRenderer extends Visitor<string> {
    * borde + fondo en columns). Devuelve '' si no hay color válido.
    */
   private boxAccentStyle(node: RedNode, suffix: 'box' | 'table' | 'columns' = 'box'): string {
-    const color = this.sanitizeColor(String(node.metadata?.color ?? ''))
+    const color = sanitizeColor(String(node.metadata?.color ?? ''), this.tokenResolver)
     if (!color) return ''
     const border = this.hexToRgba(color, 0.35)
     const bg = this.hexToRgba(color, 0.08)
@@ -1034,7 +1454,7 @@ export class HTMLRenderer extends Visitor<string> {
 
   private renderList(node: RedNode): string {
     // Check for ordered list: [list=1], [list=a], or metadata
-    const attrs = this.extractValue(node)
+    const attrs = nodeAttrValue(node)
     const isOrdered = node.metadata?.ordered === true || attrs === '1' || attrs === 'a'
     const tag = isOrdered ? 'ol' : 'ul'
     const content = node.children.map(c => this.renderNode(c)).join('\n')
@@ -1055,7 +1475,12 @@ export class HTMLRenderer extends Visitor<string> {
     const trailingMatch = content.match(/(?:[\r\n][\t ]*)+$/)
     if (trailingMatch) content = content.slice(0, -trailingMatch[0].length)
 
-    return `<pre${this.idAttr(node)}><code>${this.escapeHtml(content)}</code></pre>`
+    // Los saltos recortados arriba son de presentación: si no se anotan, el
+    // camino HTML→BBCode los da por inexistentes y reescribe el bloque del
+    // autor como `[code]…[/code]` en una sola línea.
+    const pad = `${leadingMatch ? leadingMatch[0] : ''}\u0000${trailingMatch ? trailingMatch[0] : ''}`
+    const padAttr = pad === '\u0000' ? '' : ` data-code-pad="${this.escapeHtml(JSON.stringify(pad))}"`
+    return `<pre${this.idAttr(node)}${padAttr}><code>${this.escapeHtml(content)}</code></pre>`
   }
 
   private renderSVG(node: RedNode): string {
@@ -1091,12 +1516,12 @@ export class HTMLRenderer extends Visitor<string> {
       .filter(Boolean)
 
     if (textLines.length === 0) {
-      return '<div class="media-error">[imagemap] missing image URL</div>'
+      return this.mediaError('imagemap', '[imagemap] missing image URL')
     }
 
     const imageUrl = textLines[0]
     if (!imageUrl.startsWith('http://') && !imageUrl.startsWith('https://')) {
-      return `<div class="media-error">[imagemap] invalid image URL: ${this.escapeHtml(imageUrl)}</div>`
+      return this.mediaError('imagemap', `[imagemap] invalid image URL: ${this.escapeHtml(imageUrl)}`)
     }
 
     let areas = ''
@@ -1119,9 +1544,26 @@ export class HTMLRenderer extends Visitor<string> {
         areaUrl = 'https://' + areaUrl
       }
 
+      if (this.isOsu()) {
+        // osu posiciona por CSS (`.imagemap__link` ya es absolute), así que el
+        // style inline lleva sólo las cuatro coordenadas. Un destino `#` no es
+        // un enlace: emite un `span` con la misma clase, para que la zona siga
+        // mostrando su `title` sin navegar a ninguna parte.
+        const pos = `left:${x}%;top:${y}%;width:${w}%;height:${h}%;`
+        const title = ` title="${this.escapeHtml(label)}"`
+        areas += url === '#'
+          ? `<span class="imagemap__link" style="${pos}"${title}></span>`
+          : `<a class="imagemap__link" href="${this.escapeHtml(areaUrl)}" style="${pos}"${title}></a>`
+        continue
+      }
       areas += `<a${this.idAttr(node)} href="${this.escapeHtml(areaUrl)}" target="_blank" rel="noopener" class="imagemap-area bbcode-imap-area" style="position:absolute;left:${x}%;top:${y}%;width:${w}%;height:${h}%;" title="${this.escapeHtml(label || 'Link')}"></a>`
     }
 
+    if (this.isOsu()) {
+      return `<div${this.idAttr(node)} class="imagemap">` +
+        `<img class="imagemap__image" loading="lazy" src="${this.escapeHtml(imageUrl)}" alt="">${areas}</div>`
+    }
+
     return `<div${this.idAttr(node)} class="imagemap-container bbcode-imagemap" style="position:relative;display:inline-block;"><img src="${this.escapeHtml(imageUrl)}" alt="imagemap" style="max-width:100%;height:auto;display:block;">${areas}</div>`
   }
 
@@ -1133,26 +1575,127 @@ export class HTMLRenderer extends Visitor<string> {
     return node.text || ''
   }
 
+  /**
+   * Effect parameters off a node, with every colour re-validated.
+   *
+   * `startsWith('#')` was NOT a filter: `#a" onmouseover="alert(1)` passes
+   * it. Every stop has to survive the full colour allowlist or be dropped,
+   * because these values end up inside a `style` attribute.
+   */
+  private effectParams(node: RedNode): EffectParams {
+    const meta = (node.metadata ?? {}) as Record<string, unknown>
+    const params: EffectParams = {}
+    for (const [key, value] of Object.entries(meta)) {
+      if (key === 'globalOffset' || key === 'documentLength') continue
+      ;(params as Record<string, unknown>)[key] = value
+    }
+
+    if (Array.isArray(params.colors)) {
+      params.colors = params.colors
+        .map(c => (typeof c === 'string' ? sanitizeColor(c, this.tokenResolver) : null))
+        .filter((c): c is string => c !== null)
+      if (params.colors.length === 0) delete params.colors
+    }
+    if (Array.isArray(params.stops)) {
+      params.stops = params.stops
+        .filter(st => st && typeof st.color === 'string' && sanitizeColor(st.color, this.tokenResolver) !== null)
+      if (params.stops.length === 0) delete params.stops
+    }
+    return params
+  }
+
+  /** Text inside an effect node, ignoring layout-only children. */
+  /**
+   * The plain text an effect modulates, line breaks included.
+   *
+   * A break is a childless `spacing` leaf carrying no text, so collecting
+   * it naively contributes nothing and the effect sees one long line.
+   * Every two-dimensional axis then collapses: `line` reports zero for
+   * the whole block, `column` stretches one row across the paragraph, and
+   * `radial` measures a rectangle one line tall. The break was being
+   * dropped from the OUTPUT as well, so a multi-line effect previewed as
+   * a single run-on line.
+   *
+   * The document's own plain text spells a break `\n` — that is what
+   * `stripColorWrappers` and the studio's sampler both count — so this
+   * agrees with them rather than inventing a third answer.
+   */
+  private effectText(node: RedNode): string {
+    return node.children.map(c => this.effectChildText(c)).join('')
+  }
+
+  private effectChildText(node: RedNode): string {
+    if (node.kind === 'spacing' || node.kind === 'empty_line') return '\n'
+    if (node.kind === 'text') return node.text ?? ''
+    if (node.children.length === 0) return this.collectNodeText(node)
+    return node.children.map(c => this.effectChildText(c)).join('')
+  }
+
+  /**
+   * Paint an effect's computed segments as spans.
+   *
+   * Shared by rainbow, grow and any modulated gradient, so the preview
+   * shows exactly the colours and sizes the BBCode export will contain
+   * rather than an approximation of them.
+   */
+  private renderEffectSegments(node: RedNode, kind: EffectKind): string {
+    const text = this.effectText(node)
+    if (!text) return this.renderChildren(node)
+
+    const meta = (node.metadata ?? {}) as Record<string, unknown>
+    const segments = evaluateEffect(text, kind, this.effectParams(node), {
+      globalOffset: meta.globalOffset as number | undefined,
+      documentLength: meta.documentLength as number | undefined,
+    })
+
+    let out = ''
+    for (const seg of segments) {
+      // The break is markup, not text: escaping it would print a newline
+      // that HTML collapses to a space, which is how a painted block of
+      // ASCII art would arrive as one unreadable line.
+      // El `indexOf` delante: un degradado sin fusionar emite un segmento POR
+      // CARÁCTER, y `/\n/g` es un literal —en ES2015+ eso asigna un objeto
+      // nuevo cada vez que se evalúa— para recorrer una cadena de un carácter
+      // que casi nunca es un salto de línea.
+      const html = this.escapeHtml(seg.text)
+      const escaped = html.indexOf('\n') === -1 ? html : html.replace(NEWLINE_RE, '<br>')
+      if (seg.color) {
+        const safe = sanitizeColor(seg.color, this.tokenResolver)
+        out += safe ? `<span style="color:${safe}">${escaped}</span>` : escaped
+      } else if (seg.size !== undefined) {
+        out += `<span style="font-size:${Math.max(10, Math.min(400, seg.size))}%">${escaped}</span>`
+      } else {
+        out += escaped
+      }
+    }
+    return `<span${this.idAttr(node)} class="bb-effect bb-${kind}">${out}</span>`
+  }
+
+  /**
+   * A gradient previews as a real CSS gradient when it is a plain
+   * left-to-right ramp, and as computed per-character spans otherwise.
+   *
+   * The CSS path is genuinely smoother — it interpolates per pixel rather
+   * than per glyph — but it can only express a linear sweep. A gradient
+   * with a waveform, a non-index axis or quantisation steps looked
+   * nothing like its own export while this was the only path.
+   */
   private renderGradient(node: RedNode): string {
-    // `startsWith('#')` was NOT a filter: `#a" onmouseover="alert(1)` passes it.
-    // Every stop must survive the full color allowlist or it is dropped.
-    const raw = (node.metadata?.colors as string[]) || []
-    const valid = raw
-      .map(c => (typeof c === 'string' ? this.sanitizeColor(c) : null))
-      .filter((c): c is string => c !== null)
-    const colors =
-      valid.length === 0 ? ['#FF0000', '#00FF00']
-      : valid.length === 1 ? [valid[0], valid[0]]
-      : valid
-    // Skip spacing/empty_line children so source formatting (newlines inside the tag)
-    // doesn't produce extra <br> in the preview. Both:
-    //   [gradient]Hello[/gradient]  and  [gradient]\nHello\n[/gradient]
-    // render identically.
+    const params = this.effectParams(node)
     const content = node.children
       .filter(c => c.kind !== 'spacing' && c.kind !== 'empty_line')
       .map(c => this.renderNode(c)).join('')
-    const gradientCss = `linear-gradient(to right, ${colors.join(', ')})`
-    return `<span${this.idAttr(node)} style="background: ${gradientCss}; -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text;">${content}</span>`
+
+    if (isPlainGradient(params)) {
+      const stops = params.stops && params.stops.length > 0
+        ? params.stops.map(st => `${st.color} ${(st.position * 100).toFixed(1)}%`)
+        : (params.colors ?? ['#FF0000', '#00FF00'])
+      const list = stops.length === 1 ? [stops[0], stops[0]] : stops
+      const gradientCss = `linear-gradient(to right, ${list.join(', ')})`
+      return `<span${this.idAttr(node)} style="background: ${gradientCss}; -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text;">${content}</span>`
+    }
+
+    return this.renderEffectSegments(node, 'gradient')
   }
 
   /**
@@ -1281,3 +1824,26 @@ export class HTMLRenderer extends Visitor<string> {
     return out + text.slice(last)
   }
 }
+
+/**
+ * Whether a gradient is a plain left-to-right ramp.
+ *
+ * Only then can CSS express it. Anything with a waveform, a non-index
+ * axis, quantisation, inversion or per-word stepping has to be painted
+ * per character instead, or the preview and the export disagree.
+ */
+function isPlainGradient(params: EffectParams): boolean {
+  // A tag carrying a span is one fragment of a longer ramp. Painting it
+  // as a full-width CSS gradient restarts the sweep inside every
+  // fragment, which is exactly the discontinuity the span exists to fix.
+  if (params.documentLength !== undefined && params.documentLength > 1) return false
+  return (params.wave === undefined || params.wave === 'none')
+    && (params.axis === undefined || params.axis === 'index')
+    && (params.easing === undefined || params.easing === 'linear')
+    && (params.steps === undefined || params.steps < 2)
+    && !params.invert
+    && (params.unit === undefined || params.unit === 'character')
+    && (params.cycles === undefined || params.cycles === 1)
+    && (params.phase === undefined || params.phase === 0)
+    && (params.expression === undefined || params.expression === '')
+}