@miliastry/quasar 1.0.0

package/src/Tests/PluginTags.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect } from 'vitest'
+import { BBCodeDocumentModel } from '../BBCode/BBCodeDocumentModel'
+import { PluginAPI } from '../Plugins/PluginAPI'
+import { HTMLRenderer } from '../Visitors/HTMLRenderer'
+import { BBCodeExporter } from '../Visitors/BBCodeExporter'
+import type { RedNode } from '../Syntax/RedNode'
+import type { NodeKind } from '../Types/core'
+import type { TagDefinition } from '../Model/TagRegistry'
+
+/**
+ * A plugin tag must live the FULL life of a tag: lex → parse → tree → render
+ * → export → re-parse. Before `ParseOptions.extraTags`, a registered tag
+ * could render and export but never parse — the parser turned it into
+ * literal text, so the rest of the pipeline had nothing to work with. The
+ * platform's plugin promise starts at the parser or it doesn't start.
+ */
+
+function findKind(root: RedNode, kind: string): RedNode | null {
+  let found: RedNode | null = null
+  root.walk(n => {
+    if (!found && n.kind === kind) found = n
+  })
+  return found
+}
+
+const blurTag: TagDefinition = {
+  name: 'blur',
+  kind: 'blur' as NodeKind,
+  label: 'Blur',
+  category: 'text',
+  isInline: true,
+  isSelfClosing: false,
+  canHaveChildren: true,
+  toRenderNode: (ctx) => ({
+    kind: 'blur',
+    text: '',
+    children: [{ kind: 'text', text: `⟦blur⟧${ctx.visitChildren(ctx.node)}⟦/blur⟧`, children: [], props: {} }],
+    props: {},
+  }),
+}
+
+const wiggleTag: TagDefinition = {
+  name: 'wiggle',
+  kind: 'wiggle' as NodeKind,
+  label: 'Wiggle',
+  isInline: true,
+  isSelfClosing: false,
+  canHaveChildren: true,
+}
+
+describe('plugin tags — full pipeline', () => {
+  it('parses a registered tag as a real container, with attrs and nesting', () => {
+    const model = new BBCodeDocumentModel({ source: '' })
+    model.tagRegistry.register(blurTag)
+    model.tagRegistry.register(wiggleTag)
+
+    model.rebuild('hola [blur]mundo [b]fuerte[/b][/blur] y [wiggle=3]algo[/wiggle]')
+
+    const blur = findKind(model.redRoot!, 'blur')!
+    expect(blur).toBeTruthy()
+    expect(findKind(blur, 'bold')).toBeTruthy() // nesting inside the plugin tag
+    const wiggle = findKind(model.redRoot!, 'wiggle')!
+    expect(wiggle.text).toBe('=3') // attrs preserved like any builtin
+
+    // The tree still partitions the source: the plugin tag owns its delimiters.
+    expect(blur.range.end - blur.range.start).toBe('[blur]mundo [b]fuerte[/b][/blur]'.length)
+  })
+
+  it('unregistered tags still fall to literal text — prose stays visible', () => {
+    const model = new BBCodeDocumentModel({ source: 'combo de [90 misses] con [Gateron Yellow]' })
+    expect(findKind(model.redRoot!, 'custom')).toBeNull()
+    const html = new HTMLRenderer().render(model.redRoot!)
+    expect(html).toContain('[90 misses]')
+    expect(html).toContain('[Gateron Yellow]')
+  })
+
+  it('renders through the registry handler, and safely without it', () => {
+    const model = new BBCodeDocumentModel({ source: '' })
+    model.tagRegistry.register(blurTag)
+    model.rebuild('[blur]contenido[/blur]')
+
+    const withRegistry = new HTMLRenderer({ registry: model.tagRegistry }).render(model.redRoot!)
+    expect(withRegistry).toContain('⟦blur⟧')
+    expect(withRegistry).toContain('contenido')
+
+    // Without the registry the wrapper is unknown, but content must survive.
+    const bare = new HTMLRenderer().render(model.redRoot!)
+    expect(bare).toContain('contenido')
+  })
+
+  it('exports under its registered name and round-trips', () => {
+    const model = new BBCodeDocumentModel({ source: '' })
+    model.tagRegistry.register(blurTag)
+    model.tagRegistry.register(wiggleTag)
+    const source = 'hola [blur]mundo[/blur] y [wiggle=3]algo[/wiggle]'
+    model.rebuild(source)
+
+    const exporter = new BBCodeExporter(model.tagRegistry)
+    const exported = exporter.export(model.redRoot!)
+    expect(exported).toBe(source)
+
+    // Fixpoint: parsing the export reproduces the same export.
+    model.rebuild(exported)
+    expect(exporter.export(model.redRoot!)).toBe(exported)
+  })
+
+  it('works through PluginAPI, and unregistering returns the tag to prose', () => {
+    const model = new BBCodeDocumentModel({ source: '' })
+    const api = new PluginAPI(model)
+    api.registerPlugin(
+      { name: 'blur-plugin', version: '1.0.0' },
+      { tags: [blurTag] },
+    )
+
+    model.rebuild('[blur]x[/blur]')
+    expect(findKind(model.redRoot!, 'blur')).toBeTruthy()
+
+    api.unregisterPlugin('blur-plugin')
+    model.rebuild('[blur]x[/blur]')
+    expect(findKind(model.redRoot!, 'blur')).toBeNull()
+    // Back to what unknown tags always were: visible text.
+    expect(new HTMLRenderer().render(model.redRoot!)).toContain('[blur]')
+  })
+
+  it('incremental editing with plugin tags matches a full rebuild', () => {
+    let src = ''
+    for (let i = 0; i < 60; i++) src += `parrafo ${i} con [blur]nucleo ${i}[/blur] normal\n\n`
+
+    const reuse = new BBCodeDocumentModel({ source: '' })
+    const control = new BBCodeDocumentModel({ source: '', incremental: false })
+    reuse.tagRegistry.register(blurTag)
+    control.tagRegistry.register(blurTag)
+    reuse.rebuild(src)
+    control.rebuild(src)
+
+    const renderer = new HTMLRenderer()
+    for (let edit = 0; edit < 30; edit++) {
+      const at = (edit * 137) % (reuse.source.length - 10)
+      const next = reuse.source.slice(0, at) + 'x' + reuse.source.slice(at)
+      reuse.applyTextUpdate(next)
+      control.applyTextUpdate(next)
+
+      // Sin los ids: son identidades por modelo, y aquí hay dos modelos
+      // independientes. Lo que debe coincidir es la estructura.
+      const sinIds = (html: string) => html.replace(/ data-node-id="[^"]*"/g, '')
+      expect(sinIds(renderer.render(reuse.redRoot!))).toBe(sinIds(renderer.render(control.redRoot!)))
+      expect(reuse.redRoot!.green).toBe(reuse.greenRoot)
+    }
+  })
+})

package/src/Tests/ProblematicSection.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest'
+import { TagRegistry } from '../Model/TagRegistry'
+import { BBCodeExporter } from '../Visitors/BBCodeExporter'
+import { processStudioAST } from '@miliastry/quasar-studio'
+import { REFERENCE_DOCUMENT, REFERENCE_GRADIENT_LAYER } from './referenceDocument'
+
+/**
+ * Round-tripping a document through the Studio must not invent or drop layout.
+ *
+ * The name of this suite always promised that, but the body only rendered the
+ * document and `console.log`ged the result — `expect` was imported and never
+ * called, so it could not fail. It also read an untracked `.milia` fixture,
+ * which is what finally broke it. Both are fixed here: the invariant its name
+ * describes is now actually asserted, against `referenceDocument.ts`.
+ *
+ * Braille blanks (`⠀`, U+2800) are load-bearing in these posts — authors use
+ * them as padding because osu! collapses ordinary whitespace. Gaining or losing
+ * one silently reflows somebody's profile.
+ */
+describe('Problematic Section Export', () => {
+  const exportWithLayers = (source: string, layers: unknown[]) => {
+    const registry = new TagRegistry()
+    const { redRoot } = processStudioAST(source, layers as never, {})
+    return new BBCodeExporter(registry).export(redRoot)
+  }
+
+  const brailleCount = (s: string) => (s.match(/⠀/g) || []).length
+
+  it('preserves every braille blank through a plain round trip', () => {
+    const exported = exportWithLayers(REFERENCE_DOCUMENT, [])
+    expect(brailleCount(exported)).toBe(brailleCount(REFERENCE_DOCUMENT))
+  })
+
+  it('preserves every braille blank through a gradient layer', () => {
+    // A gradient splits text into one node per character; the padding must come
+    // out the far side with the same count it went in with.
+    const exported = exportWithLayers(REFERENCE_DOCUMENT, [REFERENCE_GRADIENT_LAYER])
+    expect(brailleCount(exported)).toBe(brailleCount(REFERENCE_DOCUMENT))
+  })
+
+  it('does not add a trailing blank line', () => {
+    const exported = exportWithLayers(REFERENCE_DOCUMENT, [])
+    const trailing = (s: string) => s.length - s.replace(/\n+$/, '').length
+    expect(trailing(exported)).toBe(trailing(REFERENCE_DOCUMENT))
+  })
+})

package/src/Tests/ProblematicSectionHTML.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest'
+import { TagRegistry } from '../Model/TagRegistry'
+import { HTMLRenderer } from '../Visitors/HTMLRenderer'
+import { processStudioAST } from '@miliastry/quasar-studio'
+import { REFERENCE_DOCUMENT, REFERENCE_GRADIENT_LAYER } from './referenceDocument'
+
+/**
+ * A substantial document rendered with and without a Studio gradient layer.
+ *
+ * This used to assert nothing at all: it rendered both variants and wrote
+ * them to `orig.html` and `grad.html` in the repo root — tracked files, so
+ * every test run dirtied the working tree, and no failure was possible. What
+ * it should have been checking is below.
+ */
+describe('Problematic Section HTML Output', () => {
+  // Was an untracked `.milia` read from disk; see `referenceDocument.ts`.
+  const text = REFERENCE_DOCUMENT
+  const layers = [REFERENCE_GRADIENT_LAYER]
+
+  const render = (studioLayers: unknown[]) => {
+    const registry = new TagRegistry()
+    const renderer = new HTMLRenderer({ registry })
+    const { redRoot } = processStudioAST(text, studioLayers as never, {})
+    return renderer.render(redRoot)
+  }
+
+  it('renders the document without a gradient layer', () => {
+    const html = render([])
+
+    expect(html.length).toBeGreaterThan(1000)
+    // Structure of the source survives to the output.
+    expect(html).toContain('data-node-id')
+    // No per-character colouring without a gradient layer.
+    expect(html).not.toMatch(/color:\s*#e8b04b/i)
+  })
+
+  it('a gradient layer colours the text, and only the text', () => {
+    const plain = render([])
+    const gradient = render(layers)
+
+    expect(gradient).not.toBe(plain)
+    // The layer's own stops reach the output as inline colours.
+    expect(gradient).toMatch(/color:\s*#e8b04b/i)
+    // Colorear no puede cambiar el TEXTO, que es la invariante de verdad
+    // (contar `data-node-id` no servía: el degradado parte el texto en un
+    // nodo por carácter, así que el número cambia legítimamente).
+    const texto = (s: string) => s.replace(/<[^>]*>/g, '').replace(/\s+/g, ' ').trim()
+    expect(texto(gradient)).toBe(texto(plain))
+  })
+
+  it('rendering is deterministic', () => {
+    // Node ids come from a monotonic per-process counter, so two parses of
+    // the same text legitimately number their nodes differently. Identity is
+    // not content: strip it and the output must be identical.
+    const withoutIds = (html: string) => html.replace(/ data-node-id="[^"]*"/g, '')
+    expect(withoutIds(render(layers))).toBe(withoutIds(render(layers)))
+  })
+})

package/src/Tests/RedReuse.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect } from 'vitest'
+import { BBCodeDocumentModel } from '../BBCode/BBCodeDocumentModel'
+import { HTMLRenderer } from '../Visitors/HTMLRenderer'
+import type { RedNode } from '../Syntax/RedNode'
+
+/**
+ * Red-subtree reuse: on the incremental path, subtrees whose green is shared
+ * by reference must be ADOPTED (same RedNode objects) instead of rebuilt —
+ * building red was the largest phase of a keystroke.
+ *
+ * The property demanded is the engine's usual one: the resulting tree must be
+ * IDENTICAL — kind, text, range, structure, metadata — to what a full rebuild
+ * of the same final text produces. Ids are exempt (reuse is what makes them
+ * stable; a fresh rebuild has no history), and object identity is the point.
+ */
+
+function bigDoc(): string {
+  // Comfortably above MIN_SOURCE_LENGTH (2500) so the incremental path engages.
+  let src = ''
+  for (let i = 0; i < 40; i++) {
+    src += `parrafo numero ${i} con [b]negrita[/b] y [color=#ff66ab]color[/color]\n\n`
+  }
+  src += '[notice]interior del notice con [i]cursiva[/i] y texto largo para editar[/notice]\n\n'
+  for (let i = 0; i < 20; i++) {
+    src += `cola numero ${i} despues del notice\n\n`
+  }
+  return src
+}
+
+/** Walk both trees asserting deep equality of everything but ids. */
+function expectSameTree(a: RedNode, b: RedNode, path = 'root'): void {
+  expect(a.kind, `${path}: kind`).toBe(b.kind)
+  expect(a.text, `${path}: text`).toBe(b.text)
+  expect(a.range.start, `${path}: range.start`).toBe(b.range.start)
+  expect(a.range.end, `${path}: range.end`).toBe(b.range.end)
+  expect(JSON.stringify(a.metadata), `${path}: metadata`).toBe(JSON.stringify(b.metadata))
+  expect(a.children.length, `${path}: childCount`).toBe(b.children.length)
+  for (let i = 0; i < a.children.length; i++) {
+    expectSameTree(a.children[i], b.children[i], `${path}.${a.children[i].kind}[${i}]`)
+  }
+}
+
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0
+  return () => {
+    a |= 0; a = (a + 0x6D2B79F5) | 0
+    let t = Math.imul(a ^ (a >>> 15), 1 | a)
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+describe('red-subtree reuse', () => {
+  it('adopts untouched subtrees as the same objects, with correct shifted ranges', () => {
+    const model = new BBCodeDocumentModel({ source: bigDoc() })
+    const root = model.redRoot!
+    const noticeIdx = root.children.findIndex(c => c.kind === 'notice')
+    expect(noticeIdx).toBeGreaterThan(0)
+
+    const beforeBlock = root.children[noticeIdx - 2] // a paragraph before the notice
+    const afterBlock = root.children[root.children.length - 2]
+    const afterStart = afterBlock.range.start
+
+    // Type one char inside the notice.
+    const src = model.source
+    const at = src.indexOf('texto largo') + 5
+    model.applyTextUpdate(src.slice(0, at) + 'X' + src.slice(at))
+
+    const newRoot = model.redRoot!
+    expect(newRoot).not.toBe(root)
+
+    // Prefix subtree: same object, same position.
+    expect(newRoot.children[noticeIdx - 2]).toBe(beforeBlock)
+    // Suffix subtree: same object, range shifted by the inserted char.
+    const afterNow = newRoot.children[newRoot.children.length - 2]
+    expect(afterNow).toBe(afterBlock)
+    expect(afterNow.range.start).toBe(afterStart + 1)
+    // Adopted nodes are correctly parented into the new tree.
+    expect(afterNow.parent).toBe(newRoot)
+    expect(afterNow.index).toBe(newRoot.children.length - 2)
+  })
+
+  it('reuseRed: false keeps the old behavior (no shared objects)', () => {
+    const model = new BBCodeDocumentModel({ source: bigDoc(), reuseRed: false })
+    const root = model.redRoot!
+    const firstBlock = root.children[0]
+
+    const src = model.source
+    const at = src.indexOf('texto largo') + 5
+    model.applyTextUpdate(src.slice(0, at) + 'X' + src.slice(at))
+
+    expect(model.redRoot!.children[0]).not.toBe(firstBlock)
+  })
+
+  it('differential: reuse tree is identical to a full rebuild, over seeded edits', () => {
+    const renderer = new HTMLRenderer()
+    const rand = mulberry32(777)
+    const insertables = ['a', 'X', ' ', '\n', '[', ']', '[b]', '[/b]', '[i]', '[*]', '[notice]', '[/notice]']
+
+    const reuse = new BBCodeDocumentModel({ source: bigDoc() })
+    const control = new BBCodeDocumentModel({ source: bigDoc(), incremental: false })
+
+    for (let edit = 0; edit < 120; edit++) {
+      const src = reuse.source
+      const pos = Math.floor(rand() * (src.length + 1))
+      const next = rand() < 0.7
+        ? src.slice(0, pos) + insertables[Math.floor(rand() * insertables.length)] + src.slice(pos)
+        : src.slice(0, pos) + src.slice(Math.min(pos + 1 + Math.floor(rand() * 3), src.length))
+
+      reuse.applyTextUpdate(next)
+      control.applyTextUpdate(next)
+
+      expectSameTree(reuse.redRoot!, control.redRoot!)
+      expect(renderer.render(reuse.redRoot!).replace(/ data-node-id="[^"]*"/g, ''))
+        .toBe(renderer.render(control.redRoot!).replace(/ data-node-id="[^"]*"/g, ''))
+      expect(reuse.redRoot!.green).toBe(reuse.greenRoot)
+    }
+  })
+
+  it('ids stay unique after adoption plus fresh nodes', () => {
+    const model = new BBCodeDocumentModel({ source: bigDoc() })
+    const rand = mulberry32(4242)
+
+    for (let edit = 0; edit < 40; edit++) {
+      const src = model.source
+      const pos = Math.floor(rand() * (src.length + 1))
+      model.applyTextUpdate(src.slice(0, pos) + 'y' + src.slice(pos))
+
+      const ids: string[] = []
+      model.redRoot!.walk(n => { ids.push(String(n.id)) })
+      expect(new Set(ids).size).toBe(ids.length)
+    }
+  })
+})

package/src/Tests/ReproDelete20k.test.ts

@@ -0,0 +1,62 @@
+/**
+ * Debug — dump the windowed reconcile decisions for the minimal delete-20k
+ * divergence: change range, old/new window keys, orphan decisions, walk.
+ */
+
+import { describe, it } from 'vitest'
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { BBCodeDocumentModel } from '../BBCode/BBCodeDocumentModel'
+import { HTMLRenderer } from '../Visitors/HTMLRenderer'
+import { patchBlocksInto } from '../Visitors/BlockPatcher'
+
+const renderer = new HTMLRenderer()
+
+function loadFixture(): string {
+  const candidates = [
+    join(process.cwd(), 'packages', 'quasar', '500KCharsTest'),
+    join(process.cwd(), '500KCharsTest'),
+    join(__dirname, '..', '..', '500KCharsTest'),
+  ]
+  const p = candidates.find(c => existsSync(c))
+  if (!p) throw new Error(`Fixture not found in: ${candidates.join(', ')}`)
+  return readFileSync(p, 'utf-8')
+}
+
+const insertAt = (s: string, pos: number, text: string): string => s.slice(0, pos) + text + s.slice(pos)
+function afterBlank(s: string, pos: number): number {
+  const i = s.indexOf('\n\n', pos)
+  return i === -1 ? s.length : i + 2
+}
+
+describe('windowed debug: minimal delete-20k', () => {
+  it('dumps orphan + walk decisions', () => {
+    ;(globalThis as { __BP_DEBUG__?: boolean }).__BP_DEBUG__ = true
+    let src = loadFixture()
+    let model = new BBCodeDocumentModel({ source: src })
+    const el = document.createElement('div')
+    patchBlocksInto(el, model.redRoot!, { renderer, minWindowedBlocks: 0 })
+
+    // Step 1: insert box at 50%
+    src = insertAt(src, afterBlank(src, Math.floor(src.length * 0.5)), '[box]caja nueva[/box]\n\n')
+    model.applyTextUpdate(src)
+    model.ensureAnalyzed()
+    patchBlocksInto(el, model.redRoot!, { renderer, minWindowedBlocks: 0 })
+
+    // Step 2: insert quote at 60%
+    src = insertAt(src, afterBlank(src, Math.floor(src.length * 0.6)), '[quote]cita nueva[/quote]\n\n')
+    model.applyTextUpdate(src)
+    model.ensureAnalyzed()
+    patchBlocksInto(el, model.redRoot!, { renderer, minWindowedBlocks: 0 })
+
+    // Step 3: delete 20k at 50% — the diverging edit
+    console.log('[dbg] --- STEP 3: delete 20k at 50% ---')
+    const pos = Math.floor(src.length * 0.5)
+    const next = src.slice(0, pos) + src.slice(pos + 20_000)
+    model.applyTextUpdate(next)
+    model.ensureAnalyzed()
+    console.log('[dbg] change source pos', pos)
+    patchBlocksInto(el, model.redRoot!, { renderer, minWindowedBlocks: 0 })
+    ;(globalThis as { __BP_DEBUG__?: boolean }).__BP_DEBUG__ = false
+  }, 300_000)
+})

package/src/Tests/SemanticValidators.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest'
+import { REFERENCE_DOCUMENT_WITH_GRADIENT } from './referenceDocument'
+import { BBCodeDocumentModel } from '../BBCode/BBCodeDocumentModel'
+
+/**
+ * Regression: the built-in validators must actually fire.
+ *
+ * Three of the four were unreachable, so `analyze()` returned zero diagnostics
+ * on *any* document and `ErrorCheckerWindow` — a whole window whose job is
+ * listing problems — was permanently empty. None of them set `range` either, so
+ * even a firing diagnostic could not be clicked through to its position.
+ *
+ *   unknown-tag       required kind 'custom', but the parser turns unknown tags
+ *                     into `text` nodes before the analyzer sees them
+ *   deprecated-tag    looked up `deprecated[node.text]`, but `text` holds the
+ *                     tag's attributes, not its name
+ *   nested-structure  required non-text children of [code], but the parser
+ *                     keeps code content as raw text, so there never are any
+ *
+ * `unknown-tag` is still unreachable by design — see the note at the bottom.
+ */
+function diagnose(source: string) {
+  const model = new BBCodeDocumentModel({ source })
+  const result = model.analyze()
+  return result.diagnostics.items
+}
+
+function codes(source: string): string[] {
+  return diagnose(source).map(d => d.code)
+}
+
+describe('SemanticAnalyzer — built-in validators', () => {
+  it('flags a deprecated tag exactly once, with its range', () => {
+    const source = '[strike]x[/strike]'
+    const found = diagnose(source)
+
+    expect(found.map(d => d.code)).toEqual(['deprecated-tag'])
+    // Several nodes share offset 0 here (document, paragraph, the tag itself),
+    // so an offset-only check reported this three times.
+    expect(found[0].range).toEqual({ start: 0, end: source.length })
+    expect(found[0].message).toContain('[s]')
+  })
+
+  it('does not flag the modern spelling', () => {
+    expect(codes('[s]x[/s]')).toEqual([])
+  })
+
+  it('flags BBCode tags inside a code block', () => {
+    expect(codes('[code][b]x[/b][/code]')).toEqual(['nested-tags-in-code', 'nested-tags-in-code'])
+  })
+
+  it('does not flag a code block without tags', () => {
+    expect(codes('[code]const a = 1[/code]')).toEqual([])
+  })
+
+  it('flags an empty tag', () => {
+    const found = diagnose('[b][/b]')
+    expect(found.map(d => d.code)).toEqual(['empty-tag'])
+    expect(found[0].range).not.toBeNull()
+  })
+
+  it('every diagnostic carries a usable range', () => {
+    // ErrorCheckerWindow guards on `if (err.range)` to jump to the problem, so
+    // a diagnostic without one is invisible in practice.
+    for (const source of ['[strike]x[/strike]', '[code][b]x[/b][/code]', '[b][/b]']) {
+      for (const d of diagnose(source)) {
+        expect(d.range).not.toBeNull()
+        expect(d.range!.start).toBeGreaterThanOrEqual(0)
+        expect(d.range!.end).toBeGreaterThan(d.range!.start)
+        expect(d.range!.end).toBeLessThanOrEqual(source.length)
+      }
+    }
+  })
+
+  describe('unclosed tags', () => {
+    // The one BBCode mistake people actually make. The legacy parser closes
+    // these silently by design, so without this nothing tells the author.
+    it('flags a tag never closed', () => {
+      expect(codes('[b]hola')).toEqual(['unclosed-tag'])
+    })
+
+    it('flags each unclosed tag separately', () => {
+      expect(codes('[b][i]hola')).toEqual(['unclosed-tag', 'unclosed-tag'])
+    })
+
+    it('flags a tag auto-closed by a mismatched close', () => {
+      // [i] is never closed; the legacy rules close it when [/b] arrives.
+      expect(codes('[b][i]x[/b]')).toEqual(['unclosed-tag'])
+    })
+
+    it('says nothing about properly closed tags', () => {
+      expect(codes('[b]hola[/b]')).toEqual([])
+      expect(codes('[b][i]x[/i][/b]')).toEqual([])
+      expect(codes('[color=red]x[/color]')).toEqual([])
+      expect(codes('[url=https://osu.ppy.sh]x[/url]')).toEqual([])
+    })
+
+    it('is case-insensitive about the closing tag', () => {
+      expect(codes('[B]x[/B]')).toEqual([])
+    })
+
+    it('does not flag [*], which has no closing form', () => {
+      expect(codes('[list]\n[*]uno\n[*]dos\n[/list]')).toEqual([])
+    })
+
+    it('does not flag brackets in ordinary prose', () => {
+      expect(codes('Combo de [90 misses] con teclado [Gateron]')).toEqual([])
+      expect(codes('hola[/b]')).toEqual([])
+    })
+  })
+
+  it('stays quiet on well-formed documents', () => {
+    // False positives are worse than silence: a checker that cries wolf on
+    // ordinary text gets ignored.
+    expect(codes('[b]hola[/b] [i]mundo[/i]')).toEqual([])
+    expect(codes('texto sin ninguna etiqueta')).toEqual([])
+    expect(codes('[url=https://osu.ppy.sh]enlace[/url]')).toEqual([])
+  })
+
+  it('produces no noise on the real reference document', () => {
+    const found = diagnose(REFERENCE_DOCUMENT_WITH_GRADIENT)
+    // This is a real, valid document: anything reported here is a false
+    // positive that would bury genuine problems in the checker window.
+    expect(found.filter(d => d.severity === 'error')).toEqual([])
+    expect(found.filter(d => d.severity === 'warning')).toEqual([])
+  })
+
+  // NOTE: `unknown-tag` is deliberately still dormant. The parser renders
+  // unrecognised tags as literal text on purpose — `[Gateron]`, `[90 misses]`
+  // are ordinary prose, not typos — so warning on them would be pure noise.
+  // Reviving it is a product decision, tracked as roadmap point 15.
+  it('does not warn about unknown tags (parser renders them as text)', () => {
+    expect(codes('[unknowntag]hola[/unknowntag]')).toEqual([])
+    expect(codes('Combo de [90 misses] con teclado [Gateron]')).toEqual([])
+  })
+})