@miliastry/quasar 1.0.5 → 1.1.0

package/src/Visitors/HTMLRenderer.ts

@@ -9,11 +9,25 @@
  */
 
 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 {
   /** 
@@ -44,19 +58,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 +91,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([
@@ -203,6 +238,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 +247,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 +294,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}`)
@@ -289,7 +352,15 @@ export class HTMLRenderer extends Visitor<string> {
       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)
+      // 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)
@@ -304,12 +375,39 @@ export class HTMLRenderer extends Visitor<string> {
       case 'align': return this.renderAlign(node)
       case 'tables': return this.renderTables(node)
       case 'table_row': return this.tableDepth > 0 ? this.wrapBlock('tr', node) : this.wrapInline('span', node)
-      case 'table_col': return this.tableDepth > 0 ? this.wrapInline('td', node) : this.wrapInline('span', node)
+      case 'table_col': {
+        if (this.tableDepth <= 0) return this.wrapInline('span', node)
+        const { cellCount, maxCols, isDirect } = this.getTableContext(node)
+        let colspanAttr = ''
+        if (node.metadata?.colspan) {
+          colspanAttr = ` colspan="${node.metadata.colspan}"`
+        } else if (cellCount === 1 && maxCols > 1) {
+          colspanAttr = ` colspan="${maxCols}"`
+        } else if (cellCount < maxCols && maxCols % cellCount === 0) {
+          colspanAttr = ` colspan="${maxCols / cellCount}"`
+        }
+        const align = node.metadata?.align ? ` style="text-align:${node.metadata.align};"` : ''
+        const td = `<td${this.idAttr(node)}${colspanAttr}${align}>${this.renderChildren(node)}</td>`
+        return isDirect ? `<tr>${td}</tr>` : td
+      }
       case 'table_th': {
         const content = this.renderChildren(node)
-        return this.tableDepth > 0
-          ? `<th${this.idAttr(node)} class="bb-th"><span class="bb-table-badge">${content}</span></th>`
-          : this.wrapInline('span', node)
+        if (this.tableDepth <= 0) return this.wrapInline('span', node)
+        const { cellCount, maxCols, isDirect } = this.getTableContext(node)
+        let colspanAttr = ''
+        let fullCls = ''
+        if (node.metadata?.colspan) {
+          colspanAttr = ` colspan="${node.metadata.colspan}"`
+        } else if (cellCount === 1) {
+          colspanAttr = maxCols > 1 ? ` colspan="${maxCols}"` : ' colspan="100"'
+          fullCls = ' bb-th-full'
+        } else if (cellCount < maxCols && maxCols % cellCount === 0) {
+          colspanAttr = ` colspan="${maxCols / cellCount}"`
+        }
+        const alignCls = node.metadata?.align ? ` bb-th-${node.metadata.align}` : ''
+        const alignStyle = node.metadata?.align ? ` style="text-align:${node.metadata.align};"` : ''
+        const th = `<th${this.idAttr(node)}${colspanAttr} class="bb-th${fullCls}${alignCls}"${alignStyle}><span class="bb-table-badge">${content}</span></th>`
+        return isDirect ? `<tr>${th}</tr>` : th
       }
       case 'gallery': return this.renderGallery(node)
       case 'columns': return this.renderColumns(node)
@@ -336,14 +434,20 @@ 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>'
+        return this.isPrevBlockBoundary(node) ? '\n' : `<br${this.idAttr(node)}>`
       case 'empty_line':
         if (this.options.osuBehaviour && this.isImmediateEmptyLineBeforeCode(node)) return '\n'
         if (this.isTrailingBlockBoundary(node)) return '\n'
-        return '<br>'
+        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 —
@@ -351,6 +455,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:
@@ -462,32 +569,28 @@ 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 sanitizeColor(raw: string): string | null {
-    const v = raw.trim()
-    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
+  private static readonly NAMED_COLORS: Record<string, string> = {
+    black: '#000000',
+    white: '#FFFFFF',
+    red: '#FF4C4C',
+    green: '#2ECC71',
+    blue: '#3498DB',
+    yellow: '#F1C40F',
+    cyan: '#2EE6E2',
+    magenta: '#E056FD',
+    pink: '#FF94C4',
+    purple: '#A972FF',
+    orange: '#FF9F43',
+    amber: '#FFC34D',
+    gray: '#8395A7',
+    grey: '#8395A7',
+    lime: '#10AC84',
+    teal: '#01CBC6',
+    violet: '#5F27CD',
+    gold: '#FFD700',
   }
 
   /** Keyword-or-number CSS values (font-weight, font-style, text-decoration). */
@@ -496,63 +599,39 @@ export class HTMLRenderer extends Visitor<string> {
   }
 
   /** 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)
-  }
 
   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 {
@@ -561,48 +640,55 @@ 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') {
       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`)
@@ -617,15 +703,21 @@ 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.
+    return `<iframe${this.idAttr(node)} class="bb-youtube" data-youtube="${this.escapeHtml(id)}" src="https://www.youtube.com/embed/${this.escapeHtml(id)}" frameborder="0" allowfullscreen></iframe>`
   }
 
   private renderAudio(node: RedNode): string {
@@ -637,8 +729,12 @@ export class HTMLRenderer extends Visitor<string> {
   }
 
   private hexToRgba(hex: string, alpha: number): string {
-    if (!hex.startsWith('#')) return hex
-    const t = hex.replace('#', '')
+    let clean = hex.trim().toLowerCase()
+    if (HTMLRenderer.NAMED_COLORS[clean]) {
+      clean = HTMLRenderer.NAMED_COLORS[clean]
+    }
+    if (!clean.startsWith('#')) return clean
+    const t = clean.replace('#', '')
     const full = t.length <= 4 ? t.split('').map(c => c + c).join('') : t
     const r = parseInt(full.slice(0, 2), 16) || 0
     const g = parseInt(full.slice(2, 4), 16) || 0
@@ -649,7 +745,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)};"`
         : ''
@@ -663,7 +759,7 @@ export class HTMLRenderer extends Visitor<string> {
   }
 
   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',
@@ -671,7 +767,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).
@@ -679,13 +777,63 @@ 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 ? HTMLRenderer.countCells(parent) : 1
+
+    let maxCols = cellCount
+    if (tableNode) {
+      // 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 }
+  }
+
   private renderGallery(node: RedNode): string {
     const content = this.renderChildren(node)
     return `<div${this.idAttr(node)} class="bb-gallery">${content}</div>`
   }
 
   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
@@ -697,27 +845,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}`)
   }
@@ -732,16 +880,16 @@ 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};"`)
   }
 
   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)
 
@@ -774,7 +922,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)
@@ -802,7 +950,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(':')
@@ -824,8 +972,14 @@ export class HTMLRenderer extends Visitor<string> {
       }
       case 'middle':
         return `<div${idAttr} class="bb-middle">${content}</div>`
-      case 'circle':
-        return `<div${idAttr} class="bb-circle">${content}</div>`
+      case 'square':
+      case 'circle': {
+        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};"` : ''
+        return `<div${idAttr} class="bb-square bb-cut-panel"${style}>${content}</div>`
+      }
       case 'card':
       case 'glass': {
         // `[card=#hex]` / `[container=glass:#hex]`: el color se pasa como
@@ -833,14 +987,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:
@@ -859,7 +1013,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>`
@@ -877,7 +1031,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}`)
     }
@@ -887,7 +1044,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>`
@@ -897,6 +1054,7 @@ export class HTMLRenderer extends Visitor<string> {
 
   private renderSpoilerbox(node: RedNode): string {
     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'
@@ -906,11 +1064,12 @@ 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 {
     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'
@@ -922,7 +1081,20 @@ 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 {
+    const raw = node.metadata?.rawTitle
+    const hasOwnTitle = raw !== undefined ? String(raw) !== '' : node.metadata?.title !== undefined
+    return hasOwnTitle ? '' : ' data-bare-title="1"'
   }
 
   private renderTitle(node: RedNode, fallback: string): string {
@@ -930,8 +1102,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)
   }
 
   /**
@@ -941,13 +1119,16 @@ 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 ?? ''))
-    return color ? ` style="--${suffix}-accent:${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)
+    return ` style="--${suffix}-accent:${color};--${suffix}-border:${border};--${suffix}-bg:${bg};"`
   }
 
   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')
@@ -968,7 +1149,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 {
@@ -1004,12 +1190,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 = ''
@@ -1046,26 +1232,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')
   }
 
   /**
@@ -1194,3 +1481,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 === '')
+}