@miliastry/quasar 1.0.6 → 1.1.0

package/src/Visitors/BBCodeExporter.ts

@@ -12,6 +12,12 @@ import { RedNode } from '../Syntax/RedNode'
 import { Visitor } from './Visitor'
 import type { VisitorContext } from './Visitor'
 import { TagRegistry, type TagDefinition } from '../Model/TagRegistry'
+import {
+  toTokenResolver,
+  resolveTokenValue,
+  type TokenResolverFn,
+  type TokenSource,
+} from '../Tokens'
 
 /**
  * Export target for BBCodeExporter.
@@ -21,8 +27,42 @@ import { TagRegistry, type TagDefinition } from '../Model/TagRegistry'
  */
 export type ExportTarget = 'osu' | 'miliastry' | 'lyne'
 
+export interface BBCodeExporterOptions {
+  registry?: TagRegistry
+  target?: ExportTarget
+  tokens?: TokenSource
+  resolveTokens?: boolean
+}
+
+export type BBCodeExportOptions = {
+  target?: ExportTarget
+  tokens?: TokenSource
+  resolveTokens?: boolean
+}
+
+/**
+ * Referencia a un token de diseño dentro de un texto: `$nombre`.
+ *
+ * A nivel de módulo porque el sitio caliente es la rama de nodo TEXTO, la
+ * clase de nodo más frecuente de cualquier documento: un literal de expresión
+ * regular ahí dentro construye un `RegExp` por nodo. Había además tres copias
+ * idénticas del mismo patrón repartidas por el fichero.
+ */
+const TOKEN_REF_RE = /\$([a-zA-Z_][a-zA-Z0-9_-]*)/g
+
+/** Sustituye cada `$token` por su valor; deja intacto el que no resuelva. */
+function expandTokenRefs(text: string, resolve: TokenResolverFn): string {
+  // `indexOf` antes que `replace`: la inmensa mayoría de los textos no lleva
+  // ningún `$`, y así no se pone en marcha el motor de expresiones regulares.
+  if (text.indexOf('$') === -1) return text
+  return text.replace(TOKEN_REF_RE, (match, name: string) => {
+    const resolved = resolve(name) ?? resolve(match)
+    return resolved !== undefined ? resolved : match
+  })
+}
+
 /** Miliastry-native effect tags that osu! doesn't support natively */
-const MILIASTRY_INTERNAL_TAGS = new Set(['gradient', 'grow', 'sinewave', 'rainbow'])
+const MILIASTRY_INTERNAL_TAGS = new Set(['gradient', 'grow', 'sinewave', 'rainbow', 'paint'])
 
 /**
  * Tags que existen SOLO en Miliastry (registrados en el TagRegistry) y que
@@ -39,6 +79,9 @@ export const LYNE_ONLY_TAGS = new Set([
   'boxw', 'wnotice', 'tables', 'table_row', 'table_col', 'table_th', 'gallery', 'columns',
   'separator', 'scroll', 'sup', 'sub', 'abbr', 'mark', 'kbd', 'tooltip', 'flip',
   'raw', 'plain', 'guild', 'map', 'align', 'effect', 'anim', 'container', 'style_tag',
+  'neon', 'shimmer', 'glitch', 'typewriter', 'wave', 'fire', 'ice', 'ghost', 'glow',
+  'outline', 'emboss', 'engrave', 'pulse', 'bounce', 'shake', 'levitate', 'fade-in', 'fade-out',
+  'card', 'glass', 'neon-box', 'square', 'row', 'col', 'th',
 ])
 
 /**
@@ -89,11 +132,17 @@ const KIND_TO_TAG_NAME: Record<string, string> = {
   flower: 'flower',
   gradient: 'gradient',
   grow: 'grow',
+  rainbow: 'rainbow',
+  sinewave: 'sinewave',
+  paint: 'paint',
   align: 'align',
   tables: 'tables',
   table_row: 'row',
   table_col: 'col',
   table_th: 'th',
+  row: 'row',
+  col: 'col',
+  th: 'th',
   gallery: 'gallery',
   columns: 'columns',
   separator: 'separator',
@@ -111,18 +160,101 @@ const KIND_TO_TAG_NAME: Record<string, string> = {
   anim: 'anim',
   container: 'container',
   style_tag: 'style',
+  neon: 'neon',
+  shimmer: 'shimmer',
+  glitch: 'glitch',
+  typewriter: 'typewriter',
+  wave: 'wave',
+  fire: 'fire',
+  ice: 'ice',
+  ghost: 'ghost',
+  glow: 'glow',
+  outline: 'outline',
+  emboss: 'emboss',
+  engrave: 'engrave',
+  pulse: 'pulse',
+  bounce: 'bounce',
+  shake: 'shake',
+  levitate: 'levitate',
+  'fade-in': 'fade-in',
+  'fade-out': 'fade-out',
+  card: 'card',
+  glass: 'glass',
+  'neon-box': 'neon-box',
+  square: 'square',
+}
+
+
+/**
+ * Whether a parsed attribute actually carries a value worth re-emitting.
+ *
+ * The parser stores an empty string for the attribute of a bare tag, so a
+ * plain `[box]` arrives here with `rawTitle: ''` rather than `undefined`.
+ * The guards below used to test `!== undefined`, which an empty string
+ * passes — exporting `[box]` as `[box=]` and `[quote]` as `[quote=""]`.
+ * Both are corruption, not normalization: bare boxes and quotes are
+ * ordinary BBCode and must round-trip untouched.
+ */
+function hasAttrValue(value: unknown): boolean {
+  return value !== undefined && value !== null && String(value) !== ''
 }
 
+function normalizeColorToHex(color: string): string {
+  if (!color) return color
+  const trimmed = color.trim()
+  // Un hex ya es canónico: bajarlo a minúsculas reescribía `[color=#FF0000]`
+  // del autor en cada exportación, y `Analysis/RoundTrip` fija lo contrario.
+  if (trimmed.startsWith('#')) return trimmed
+
+  const rgbMatch = trimmed.match(/^rgba?\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:\s*,\s*([\d.]+))?\s*\)$/i)
+  if (rgbMatch) {
+    const r = parseInt(rgbMatch[1], 10).toString(16).padStart(2, '0')
+    const g = parseInt(rgbMatch[2], 10).toString(16).padStart(2, '0')
+    const b = parseInt(rgbMatch[3], 10).toString(16).padStart(2, '0')
+    return `#${r}${g}${b}`.toLowerCase()
+  }
+
+  return trimmed
+}
 
 export class BBCodeExporter extends Visitor<string> {
   private registry: TagRegistry
   private depth: number = 0
   private target: ExportTarget
+  private tokens?: TokenSource
+  private tokenResolver?: TokenResolverFn
+  private explicitResolveTokens?: boolean
+  /**
+   * El resolvedor a aplicar en ESTE recorrido, o `null` si no hay expansión.
+   *
+   * Se decide una vez en `visit`, no por nodo: `shouldResolveTokens()` da la
+   * misma respuesta para todo el documento, y se estaba llamando en la rama
+   * de nodo texto, la más frecuente que hay.
+   */
+  private expandTokens: TokenResolverFn | null = null
 
-  constructor(registry: TagRegistry = new TagRegistry(), target: ExportTarget = 'osu') {
+  constructor(
+    registryOrOptions?: TagRegistry | BBCodeExporterOptions,
+    target: ExportTarget = 'osu',
+    options?: BBCodeExporterOptions | { tokens?: TokenSource; resolveTokens?: boolean },
+  ) {
     super()
-    this.registry = registry
-    this.target = target
+    if (registryOrOptions && !(registryOrOptions instanceof TagRegistry) && !('get' in registryOrOptions)) {
+      const opts = registryOrOptions as BBCodeExporterOptions
+      this.registry = opts.registry ?? new TagRegistry()
+      this.target = opts.target ?? 'osu'
+      this.tokens = opts.tokens
+      this.tokenResolver = toTokenResolver(opts.tokens)
+      this.explicitResolveTokens = opts.resolveTokens
+    } else {
+      this.registry = (registryOrOptions as TagRegistry) ?? new TagRegistry()
+      this.target = target
+      if (options) {
+        this.tokens = options.tokens
+        this.tokenResolver = toTokenResolver(options.tokens)
+        this.explicitResolveTokens = options.resolveTokens
+      }
+    }
   }
 
   /**
@@ -132,30 +264,95 @@ export class BBCodeExporter extends Visitor<string> {
     this.target = target
   }
 
+  setTokens(tokens?: TokenSource): void {
+    this.tokens = tokens
+    this.tokenResolver = toTokenResolver(tokens)
+  }
+
+  getTokens(): TokenSource | undefined {
+    return this.tokens
+  }
+
+  getTokenResolver(): TokenResolverFn | undefined {
+    return this.tokenResolver
+  }
+
+  private shouldResolveTokens(): boolean {
+    if (this.explicitResolveTokens !== undefined) {
+      return this.explicitResolveTokens
+    }
+    return this.target === 'osu'
+  }
+
   /**
    * Export a RedNode tree to BBCode.
    */
   visit(node: RedNode, context?: VisitorContext): string {
     if (context) this.context = context
     this.depth = 0
+    this.expandTokens =
+      this.tokenResolver !== undefined && this.shouldResolveTokens() ? this.tokenResolver : null
     return this.exportNode(node)
   }
 
   /**
    * Export the entire document to BBCode.
-   * Optionally override the export target for this specific call.
+   * Optionally override the export target or options for this specific call.
    */
-  export(root: RedNode, target?: ExportTarget): string {
-    if (target !== undefined) this.target = target
+  export(
+    root: RedNode,
+    targetOrOptions?: ExportTarget | BBCodeExportOptions,
+    options?: BBCodeExportOptions,
+  ): string {
+    if (typeof targetOrOptions === 'string') {
+      this.target = targetOrOptions
+      if (options?.tokens !== undefined) {
+        this.setTokens(options.tokens)
+      }
+      if (options?.resolveTokens !== undefined) {
+        this.explicitResolveTokens = options.resolveTokens
+      }
+    } else if (targetOrOptions && typeof targetOrOptions === 'object') {
+      if (targetOrOptions.target !== undefined) {
+        this.target = targetOrOptions.target
+      }
+      if (targetOrOptions.tokens !== undefined) {
+        this.setTokens(targetOrOptions.tokens)
+      }
+      if (targetOrOptions.resolveTokens !== undefined) {
+        this.explicitResolveTokens = targetOrOptions.resolveTokens
+      }
+    }
     return this.visit(root)
   }
 
+  /**
+   * Exporta los hijos directos y los concatena.
+   *
+   * Reemplaza el `children.map(...).join('')`, que asignaba un cierre y un
+   * array intermedio de N cadenas en cada nivel del árbol. `HTMLRenderer`
+   * hizo este mismo cambio y dejó la nota; el exportador se quedó atrás, y es
+   * el camino que corre bajo un límite de 60.000 caracteres.
+   */
+  private exportChildren(node: RedNode): string {
+    const children = node.children
+    let out = ''
+    for (let i = 0; i < children.length; i++) out += this.exportNode(children[i])
+    return out
+  }
+
   private exportNode(node: RedNode): string {
+    // Un cierre que no cerró nada no vuelve al source. Escribirlo hacía que el
+    // siguiente parseo lo leyera otra vez como etiqueta viva, y el documento no
+    // convergía al reexportarlo.
+    if (node.kind === 'discarded_tag') return ''
+
     const tagDef = this.registry.getByKind(node.kind)
 
     // Text nodes
     if (node.kind === 'text') {
       let out = node.text
+      if (this.expandTokens !== null) out = expandTokenRefs(out, this.expandTokens)
       const style = node.metadata?.style as Record<string, string> | undefined
       if (style) {
         // Envolvemos desde adentro hacia afuera (o al revés, no importa mucho para osu)
@@ -163,8 +360,20 @@ export class BBCodeExporter extends Visitor<string> {
         if (style.fontStyle === 'italic') out = `[i]${out}[/i]`
         if (style.textDecoration === 'underline') out = `[u]${out}[/u]`
         if (style.textDecoration === 'line-through') out = `[s]${out}[/s]`
-        if (style.color) out = `[color=${style.color}]${out}[/color]`
-        if (style.fontSize) out = `[size=${style.fontSize}]${out}[/size]`
+        if (style.color) {
+          let col = style.color
+          if (this.shouldResolveTokens() && col.startsWith('$')) {
+            col = resolveTokenValue(col, this.tokenResolver)
+          }
+          out = `[color=${normalizeColorToHex(col)}]${out}[/color]`
+        }
+        if (style.fontSize) {
+          let size = style.fontSize
+          if (this.shouldResolveTokens() && size.startsWith('$')) {
+            size = resolveTokenValue(size, this.tokenResolver)
+          }
+          out = `[size=${size}]${out}[/size]`
+        }
         // Se pueden seguir sumando estilos dinámicos
       }
       return out
@@ -172,7 +381,7 @@ export class BBCodeExporter extends Visitor<string> {
 
     // Document root
     if (node.kind === 'document') {
-      return node.children.map(c => this.exportNode(c)).join('')
+      return this.exportChildren(node)
     }
 
     // Custom tag handlers from registry
@@ -196,7 +405,7 @@ export class BBCodeExporter extends Visitor<string> {
     // Default BBCode serialization
     let tagName = this.kindToTagName(node.kind)
     const attrs = this.getTagAttributes(node)
-    const content = node.children.map(c => this.exportNode(c)).join('')
+    const content = this.exportChildren(node)
 
     if (!tagName) {
       if (node.kind === 'spacing') return '\n'
@@ -246,38 +455,78 @@ export class BBCodeExporter extends Visitor<string> {
         if (tag?.properties) {
           const parts: string[] = []
           for (const prop of tag.properties) {
-            const val = node.metadata[prop.name]
+            let val = node.metadata[prop.name]
             if (val !== undefined && val !== null) {
+              if (this.shouldResolveTokens() && typeof val === 'string' && val.startsWith('$')) {
+                val = resolveTokenValue(val, this.tokenResolver)
+              }
               parts.push(`${prop.name}=${val}`)
             }
           }
           if (parts.length > 0) return `=${parts[0]}`
         }
-      } else if (node.kind === 'font_size' && node.metadata.size !== undefined) {
-        return `=${node.metadata.size}`
-      } else if (node.kind === 'color' && node.metadata.color !== undefined) {
-        return `=${node.metadata.color}`
-      } else if (node.kind === 'font' && node.metadata.font !== undefined) {
-        return `=${node.metadata.font}`
+      } else if (node.kind === 'font_size' && hasAttrValue(node.metadata.size)) {
+        let size = String(node.metadata.size)
+        if (this.shouldResolveTokens() && size.startsWith('$')) {
+          size = resolveTokenValue(size, this.tokenResolver)
+        }
+        return `=${size}`
+      } else if (node.kind === 'color' && hasAttrValue(node.metadata.color)) {
+        let color = String(node.metadata.color)
+        if (this.shouldResolveTokens() && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
+        return `=${normalizeColorToHex(color)}`
+      } else if (node.kind === 'font' && hasAttrValue(node.metadata.font)) {
+        let font = String(node.metadata.font)
+        if (this.shouldResolveTokens() && font.startsWith('$')) {
+          font = resolveTokenValue(font, this.tokenResolver)
+        }
+        return `=${font}`
       } else if (node.kind === 'url' && node.metadata.href !== undefined) {
         return `=${node.metadata.href}`
-      } else if (node.kind === 'email' && node.metadata.href !== undefined) {
-        return `=${(node.metadata.href as string).replace('mailto:', '')}`
-      } else if (node.kind === 'quote' && node.metadata.source !== undefined) {
-        return `="${node.metadata.source}"`
-      } else if ((node.kind === 'box' || node.kind === 'boxw' || node.kind === 'spoilerbox') && (node.metadata.rawTitle !== undefined || node.metadata.title !== undefined)) {
-        const titleVal = node.metadata.rawTitle !== undefined ? node.metadata.rawTitle : node.metadata.title
+      } else if (node.kind === 'email' && hasAttrValue(node.metadata.href)) {
+        // The parser prefixes the address with `mailto:`, so a bare `[email]`
+        // arrives as exactly that prefix and nothing else — test the address.
+        const address = (node.metadata.href as string).replace('mailto:', '')
+        return address === '' ? '' : `=${address}`
+      } else if (node.kind === 'quote' && hasAttrValue(node.metadata.source)) {
+        let src = String(node.metadata.source)
+        if (this.expandTokens !== null) src = expandTokenRefs(src, this.expandTokens)
+        return `="${src}"`
+      } else if (node.kind === 'box' || node.kind === 'boxw' || node.kind === 'spoilerbox') {
+        // `rawTitle` is the source spelling; `title` is the parsed one, which
+        // falls back to a synthetic "Box"/"Spoiler" when the tag is bare. Only
+        // the raw form can be trusted to reproduce the input, so it wins.
+        const raw = node.metadata.rawTitle
+        let titleVal = String((raw !== undefined ? raw : node.metadata.title) ?? '')
+        if (this.expandTokens !== null) titleVal = expandTokenRefs(titleVal, this.expandTokens)
         // `[box=Title:#hex]`: el color se guardó aparte en metadata; se vuelve
         // a añadir aquí para que el round-trip no pierda el sufijo.
-        const color = node.metadata.color as string | undefined
+        let color = node.metadata.color as string | undefined
+        if (this.shouldResolveTokens() && color && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
+        // A bare `[box]` has neither, and must stay bare.
+        if (titleVal === '' && !color) return ''
         return `=${titleVal}${color ? `:${color}` : ''}`
       } else if ((node.kind === 'notice' || node.kind === 'wnotice') && node.metadata.color !== undefined) {
-        return `=${node.metadata.color}`
+        let color = String(node.metadata.color)
+        if (this.shouldResolveTokens() && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
+        return `=${color}`
       } else if (node.kind === 'tables' && node.metadata.variant !== undefined) {
-        const color = node.metadata.color as string | undefined
+        let color = node.metadata.color as string | undefined
+        if (this.shouldResolveTokens() && color && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
         return `=${node.metadata.variant}${color ? `:${color}` : ''}`
       } else if (node.kind === 'columns' && node.metadata.columns !== undefined) {
-        const color = node.metadata.color as string | undefined
+        let color = node.metadata.color as string | undefined
+        if (this.shouldResolveTokens() && color && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
         return `=${node.metadata.columns}${color ? `:${color}` : ''}`
       } else if (node.kind === 'separator' && node.metadata.variant !== undefined) {
         return `=${node.metadata.variant}`
@@ -294,22 +543,60 @@ export class BBCodeExporter extends Visitor<string> {
       } else if (node.kind === 'align' && node.metadata.align !== undefined) {
         return `=${node.metadata.align}`
       } else if (node.kind === 'effect' && node.metadata.effectType !== undefined) {
-        return `=${node.metadata.effectType}`
+        let color = node.metadata.color as string | undefined
+        if (this.shouldResolveTokens() && color && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
+        return `=${node.metadata.effectType}${color ? `:${color}` : ''}`
       } else if (node.kind === 'image' && node.metadata.imgAttr !== undefined) {
         return `=${node.metadata.imgAttr}`
       } else if (node.kind === 'anim' && node.metadata.animType !== undefined) {
         return `=${node.metadata.animType}`
       } else if (node.kind === 'container' && node.metadata.containerType !== undefined) {
-        return `=${node.metadata.containerType}`
+        let color = node.metadata.color as string | undefined
+        if (this.shouldResolveTokens() && color && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
+        return `=${node.metadata.containerType}${color ? `:${color}` : ''}`
       } else if (node.kind === 'style_tag' && node.metadata.style !== undefined) {
-        return `=${node.metadata.style}`
+        let style = String(node.metadata.style)
+        if (this.shouldResolveTokens()) {
+          style = style.replace(/\$([a-zA-Z0-9_.-]+)/g, (match) => {
+            return resolveTokenValue(match, this.tokenResolver)
+          })
+        }
+        return `=${style}`
+      } else if (hasAttrValue(node.metadata.value)) {
+        let val = String(node.metadata.value)
+        if (this.shouldResolveTokens() && val.startsWith('$')) {
+          val = resolveTokenValue(val, this.tokenResolver)
+        }
+        return `=${val}`
+      } else if (hasAttrValue(node.metadata.raw)) {
+        let raw = String(node.metadata.raw)
+        if (this.shouldResolveTokens() && raw.startsWith('$')) {
+          raw = resolveTokenValue(raw, this.tokenResolver)
+        }
+        return `=${raw}`
       }
     }
 
     // Fallback: check node text for attribute info
     const text = node.text || ''
     if (text.startsWith('=') || text.startsWith(' ')) {
-      // The text is exactly the attributes string (e.g. "=50" or " min=50 max=200")
+      if (node.kind === 'color' && text.startsWith('=')) {
+        let col = text.slice(1)
+        if (this.shouldResolveTokens() && col.startsWith('$')) {
+          col = resolveTokenValue(col, this.tokenResolver)
+        }
+        return `=${normalizeColorToHex(col)}`
+      }
+      if (this.shouldResolveTokens() && text.startsWith('=')) {
+        let val = text.slice(1)
+        if (val.startsWith('$')) {
+          return `=${resolveTokenValue(val, this.tokenResolver)}`
+        }
+      }
       return text
     }
 

package/src/Visitors/BlockPatcher.ts

@@ -67,6 +67,8 @@ export interface PatchBlocksOptions {
    * path on small documents.
    */
   minWindowedBlocks?: number
+  /** If true, forces a full rebuild of the container instead of incremental patching. */
+  forceRebuild?: boolean
 }
 
 export interface PatchBlocksStats {
@@ -143,6 +145,53 @@ interface PatchCache {
 
 const caches = new WeakMap<HTMLElement, PatchCache>()
 
+/**
+ * ¿Está encendido el volcado verboso? (`globalThis.__BP_DEBUG__ = true`)
+ *
+ * Imprime por consola el detalle de la reconciliación por ventana. Es caro:
+ * sirve para leer un caso a mano, NO para medir con él encendido.
+ */
+function BP_DEBUG(): boolean {
+  return (globalThis as { __BP_DEBUG__?: boolean }).__BP_DEBUG__ === true
+}
+
+/**
+ * Deja constancia de POR QUÉ `patchBlocksInto` tomó el camino que tomó, en
+ * `globalThis.__BP_LAST__` (`globalThis.__BP_TRACE__ = true` para encenderlo).
+ *
+ * Va aparte del volcado verboso a propósito: esta traza es UNA asignación por
+ * parcheo, así que se puede dejar encendida MIENTRAS SE MIDE sin falsear la
+ * medida, que es justo cuando hace falta.
+ *
+ * Existe porque "¿por qué esto no usó el camino incremental?" es cara de
+ * contestar desde fuera: el bundle está minificado, `patchBlocksInto` devuelve
+ * `mode` pero no el motivo, y quien lo llama (el preview) tira las
+ * estadísticas. Diagnosticar la caída a `fullRebuild` por tecla en el
+ * documento de 547 KB costó desminificar a mano una función dentro de una
+ * línea de 75.000 caracteres; con esto se lee `__BP_LAST__` y ya está.
+ *
+ * Coste apagada: una comparación de identidad por parcheo.
+ */
+function bpTrace(reason: Record<string, unknown>): void {
+  if ((globalThis as { __BP_TRACE__?: boolean }).__BP_TRACE__ === true) {
+    ;(globalThis as { __BP_LAST__?: unknown }).__BP_LAST__ = reason
+  }
+}
+
+/**
+ * Evict `container` from the patch cache so the next patch rebuilds afresh.
+ */
+export function clearPatchCache(container: HTMLElement): void {
+  // Contador de invalidaciones bajo la misma traza barata: "cuántas veces se
+  // tira la caché por pulsación" es la pregunta que destapó el fullRebuild por
+  // tecla, y no se puede contestar desde fuera del módulo.
+  if ((globalThis as { __BP_TRACE__?: boolean }).__BP_TRACE__ === true) {
+    const g = globalThis as { __BP_CLEARS__?: number }
+    g.__BP_CLEARS__ = (g.__BP_CLEARS__ ?? 0) + 1
+  }
+  caches.delete(container)
+}
+
 const defaultRenderer = new HTMLRenderer()
 
 function getCache(container: HTMLElement): PatchCache {
@@ -607,10 +656,15 @@ function reconcileWindowed(
 
   const oldRuns = cache.lastRuns
 
-  const DBG = (globalThis as { __BP_DEBUG__?: boolean }).__BP_DEBUG__ === true
+  const DBG = BP_DEBUG()
   const dbg = (...a: unknown[]): void => {
     if (DBG) console.log('[BP]', ...a)
   }
+  // OJO: `dbg(...)` evalúa sus argumentos ANTES de entrar, así que las
+  // llamadas que construyen algo —`.map()`, plantillas, `slice`— van dentro
+  // de un `if (DBG)`. Este es el camino de cada pulsación: los cuatro
+  // volcados de abajo recorrían la ventana entera y construían una cadena por
+  // ejecución, con la depuración apagada, para tirarlo todo.
 
 
   // ── Old window (OLD coordinates). ──────────────────────────────────────
@@ -749,14 +803,22 @@ function reconcileWindowed(
   const oldWinRunsFinal = oldRuns.slice(oldWinFrom2, oldWinTo)
   const newWinRunsFinal = newWinRuns
 
-  dbg('change', { start: change.start, end: change.end, endOld: change.endOld })
-  dbg('oldWin', oldWinFrom2, oldWinTo, 'keys', oldWinRunsFinal.map((r) => `${r.key}:${r.node.kind}`).slice(0, 40))
-  dbg('newWin', fromNew, toNew, 'keys', newWinRunsFinal.map((r) => `${r.key}:${r.node.kind}`).slice(0, 40))
-  dbg('newWinKeySet', [...newWinRunsFinal.map((r) => r.key).slice(0, 40)])
+  if (DBG) {
+    dbg('change', { start: change.start, end: change.end, endOld: change.endOld })
+    dbg('oldWin', oldWinFrom2, oldWinTo, 'keys', oldWinRunsFinal.map((r) => `${r.key}:${r.node.kind}`).slice(0, 40))
+    dbg('newWin', fromNew, toNew, 'keys', newWinRunsFinal.map((r) => `${r.key}:${r.node.kind}`).slice(0, 40))
+    dbg('newWinKeySet', [...newWinRunsFinal.map((r) => r.key).slice(0, 40)])
+  }
 
   // DOM anchor at the window start, and the window's old nodes.
-  let anchorNode: Node | null = container.firstChild
-  for (let k = 0; k < oldWinFrom2; k++) anchorNode = anchorNode?.nextSibling ?? null
+  // Indexed, not walked. `childNodes` is a live NodeList with indexed access,
+  // so asking for the window's first node is one lookup; stepping to it one
+  // `nextSibling` at a time was O(blocks before the edit) and, on a document
+  // of 30.000 top-level blocks, the single largest term left in this
+  // function's bookkeeping — 11 ms per keystroke, more than the reconcile it
+  // was preparing for. The two are exactly equivalent: the k-th child is the
+  // k-th child.
+  const anchorNode: Node | null = container.childNodes[oldWinFrom2] ?? null
   const oldWinNodes: Node[] = []
   let node: Node | null = anchorNode
   for (let i = oldWinFrom2; i < oldWinTo; i++) {
@@ -800,7 +862,7 @@ function reconcileWindowed(
       const k = oldWinRunsFinal[i].key
       if (newKeySet.has(k) || newByNode.has(oldWinRunsFinal[i].node)) continue
       const el = oldWinNodes[i]
-      dbg('orphan?', k, oldWinRunsFinal[i].node.kind, 'el=', el ? (el.nodeType === 1 ? (el as Element).tagName : `text:'${String((el as Text).data ?? '').slice(0, 20)}'`) : 'null')
+      if (DBG) dbg('orphan?', k, oldWinRunsFinal[i].node.kind, 'el=', el ? (el.nodeType === 1 ? (el as Element).tagName : `text:'${String((el as Text).data ?? '').slice(0, 20)}'`) : 'null')
       if (el && !removed.has(el)) {
         removed.add(el)
         container.removeChild(el)
@@ -828,7 +890,7 @@ function reconcileWindowed(
       const prev = oldRunByKey.get(run.key) ?? oldRunByNode.get(run.node)
       const element = oldByKey.get(run.key) ?? oldByNode.get(run.node)
 
-      dbg('WALK', run.key, run.node.kind, 'element=', element ? (element.nodeType === 1 ? (element as Element).tagName : 'text') : 'NEW', 'cursor=', cursor ? (cursor.nodeType === 1 ? (cursor as Element).tagName : 'text') : 'null')
+      if (DBG) dbg('WALK', run.key, run.node.kind, 'element=', element ? (element.nodeType === 1 ? (element as Element).tagName : 'text') : 'NEW', 'cursor=', cursor ? (cursor.nodeType === 1 ? (cursor as Element).tagName : 'text') : 'null')
 
       if (!element) {
         container.insertBefore(nodeFromHtml(run.html), cursor)
@@ -858,7 +920,7 @@ function reconcileWindowed(
     // the first suffix node. Leftovers of runs that rendered to a different
     // node count sit between the walk's end and the suffix — drop them.
     let tail = cursor
-    dbg('tail-safety: cursor=', cursor ? (cursor.nodeType === 1 ? (cursor as Element).tagName : `text:'${String((cursor as Text).data ?? '').slice(0, 15)}'`) : 'null', 'afterWindow=', afterWindow ? (afterWindow.nodeType === 1 ? (afterWindow as Element).tagName : `text:'${String((afterWindow as Text).data ?? '').slice(0, 15)}'`) : 'null')
+    if (DBG) dbg('tail-safety: cursor=', cursor ? (cursor.nodeType === 1 ? (cursor as Element).tagName : `text:'${String((cursor as Text).data ?? '').slice(0, 15)}'`) : 'null', 'afterWindow=', afterWindow ? (afterWindow.nodeType === 1 ? (afterWindow as Element).tagName : `text:'${String((afterWindow as Text).data ?? '').slice(0, 15)}'`) : 'null')
     let tailCount = 0
     while (tail !== afterWindow) {
       if (!tail) break
@@ -923,9 +985,15 @@ export function patchBlocksInto(
     return { mode: 'full', total: 0, patched: 0 }
   }
 
+  if (options.forceRebuild) {
+    bpTrace({ why: 'forceRebuild' })
+    return fullRebuild(container, rootNode, renderer, cache)
+  }
+
   // DOM out of sync with the cache (a host replaced the innerHTML behind our
   // back, or a run rendered to a different node count than last time).
   if (container.childNodes.length !== cache.lastRuns.length) {
+    bpTrace({ why: 'desync', kids: container.childNodes.length, runs: cache.lastRuns.length })
     return fullRebuild(container, rootNode, renderer, cache)
   }
 
@@ -938,7 +1006,13 @@ export function patchBlocksInto(
     undefined
   if (change) {
     const windowed = reconcileWindowed(container, rootNode, change, renderer, cache, options)
-    if (windowed) return windowed
+    if (windowed) {
+      bpTrace({ why: 'windowed' })
+      return windowed
+    }
+    bpTrace({ why: 'windowed-declinado' })
+  } else {
+    bpTrace({ why: 'sin-changeRange' })
   }
 
   const blocks = rootNode.children
@@ -956,8 +1030,10 @@ export function patchBlocksInto(
     oldSet.add(k)
   }
   if (added >= cache.lastKeys.length) {
+    bpTrace({ why: 'added>=lastKeys', added, lastKeys: cache.lastKeys.length })
     return fullRebuild(container, rootNode, renderer, cache)
   }
 
+  bpTrace({ why: 'keyed' })
   return reconcileKeyed(container, rootNode, keys, renderer, cache, options)
 }