@miliastry/quasar 1.0.0

package/src/Tests/Chars500kBenchmark.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Benchmark — 500k-character engine test on REAL osu! BBCode.
+ *
+ * Uses the real user-profile document at `packages/quasar/500KCharsTest`
+ * (~547 KB, thousands of color-gradient inlines, boxes, notices, imagemaps).
+ * Run with `PROFILE=1` for the diagnostic numbers (the default run is a
+ * correctness smoke test).
+ *
+ * The flow mirrors production exactly: ONE model, `applyTextUpdate` per edit,
+ * `patchBlocksInto(container, model.redRoot)` per patch. Each DOM path gets
+ * its own container (own patch cache), primed on the previous state so every
+ * measurement honestly consumes the fresh change.
+ */
+
+import { describe, it, expect } 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 PROFILE = process.env.PROFILE === '1'
+
+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')
+}
+
+function bench(fn: () => void): number {
+  const t0 = performance.now()
+  fn()
+  return performance.now() - t0
+}
+
+describe('Quasar @ 500k chars (real fixture)', () => {
+  it('engine correctness + (PROFILE=1) diagnostics on the 547KB fixture', () => {
+    const src = loadFixture()
+    const n = src.length
+    if (PROFILE) console.log(`[500k] fixture chars=${n} lines=${src.split('\n').length}`)
+    expect(n).toBeGreaterThan(500_000)
+
+    const renderer = new HTMLRenderer()
+    let renders = 0
+    const counting = new Proxy(renderer, {
+      get(target, prop, receiver) {
+        const v = Reflect.get(target, prop, receiver)
+        if (prop === 'render' && typeof v === 'function') {
+          return (node: unknown) => {
+            renders++
+            return v.call(target, node)
+          }
+        }
+        return v
+      },
+    })
+
+    let model!: BBCodeDocumentModel
+    const tNew = bench(() => {
+      model = new BBCodeDocumentModel({ source: src })
+    })
+    if (PROFILE) console.log(`[500k] bootstrap(new model+parse): ${tNew.toFixed(1)}ms`)
+
+    const blocks = model.redRoot?.children.length ?? 0
+    if (PROFILE) console.log(`[500k] top-level blocks=${blocks}`)
+
+    if (PROFILE) {
+      const sizes = model.redRoot!.children.map((b) => b.range.end - b.range.start).sort((a, b) => b - a)
+      console.log(
+        `[500k] block-size profile: max=${sizes[0]} median=${sizes[Math.floor(sizes.length / 2)]} ` +
+          `mean=${Math.round(sizes.reduce((a, b) => a + b, 0) / sizes.length)}`,
+      )
+    }
+
+    const mid = Math.floor(src.length * 0.6)
+    const edits: Array<[string, string]> = [
+      ['start-insert', '[heading]TOP[/heading]\n\n' + src],
+      ['mid-insert', src.slice(0, mid) + '[heading]MID[/heading]\n\n' + src.slice(mid)],
+      ['end-append', src + '\n\n[box]fin[/box]'],
+      ['inline-char', src.replace('hxovc', 'hxovcX')],
+    ]
+
+    for (const [name, next] of edits) {
+      // Prime both containers on the previous state.
+      const elWin = document.createElement('div')
+      const elFull = document.createElement('div')
+      patchBlocksInto(elWin, model.redRoot!, { renderer })
+      patchBlocksInto(elFull, model.redRoot!, { renderer })
+
+      // Apply the edit once; the root below is the ONE the model now holds.
+      const tParse = bench(() => model.applyTextUpdate(next))
+      const root = model.redRoot!
+      if (PROFILE && model.lastReparseTimings) {
+        const t = model.lastReparseTimings
+        console.log(
+          `[500k]   reparse path=${model.lastReparsePath} fallback=${model.lastReparseFallbackReason} ` +
+            `findAffected=${t.findAffected.toFixed(1)}ms safe=${t.safeBoundary.toFixed(1)}ms ` +
+            `parse=${t.parse.toFixed(1)}ms buildRed=${t.buildRed.toFixed(1)}ms mutate=${t.mutate.toFixed(1)}ms`,
+        )
+      }
+
+      renders = 0
+      let statsWin: ReturnType<typeof patchBlocksInto>
+      const tWin = bench(() => {
+        statsWin = patchBlocksInto(elWin, root, { renderer: counting, minWindowedBlocks: 0 })
+      })
+      const winRenders = renders
+
+      renders = 0
+      let statsFull: ReturnType<typeof patchBlocksInto>
+      const tFull = bench(() => {
+        statsFull = patchBlocksInto(elFull, root, { renderer: counting, change: undefined as never })
+      })
+      const fullRenders = renders
+
+      // Default production path: no forced option — the patcher picks the
+      // windowed vs full decision on its own (MIN_WINDOWED_BLOCKS applies).
+      const elDef = document.createElement('div')
+      model.applyTextUpdate(src)
+      patchBlocksInto(elDef, model.redRoot!, { renderer })
+      model.applyTextUpdate(next)
+      const tDefault = bench(() => {
+        patchBlocksInto(elDef, root, { renderer: counting })
+      })
+      const defaultMs = tDefault
+
+      if (PROFILE) {
+        console.log(
+          `[500k] ${name}: parse=${tParse.toFixed(1)}ms ` +
+            `windowed=${tWin.toFixed(2)}ms renders=${winRenders} ` +
+            `(${statsWin!.mode}/${statsWin!.windowed ? 'win' : 'full'}, ${statsWin!.patched}/${statsWin!.total}) ` +
+            `defaultPath=${defaultMs.toFixed(2)}ms ` +
+            `full=${tFull.toFixed(2)}ms renders=${fullRenders} (${statsFull!.patched}/${statsFull!.total})`,
+        )
+      }
+
+      expect(stripIds(elWin.innerHTML)).toBe(stripIds(elFull.innerHTML))
+
+      model.applyTextUpdate(src)
+    }
+  }, 120_000)
+})
+
+function stripIds(html: string): string {
+  return html.replace(/ data-node-id="[^"]*"/g, '')
+}

package/src/Tests/Chars500kEdits.test.ts

@@ -0,0 +1,321 @@
+/**
+ * Edits battery — every kind of edit on the REAL 547KB osu! fixture.
+ *
+ * Loads `packages/quasar/500KCharsTest` (~547 KB: 60 imagemaps, hundreds of
+ * `[centre]`/`[colour]` gradient inlines, links) and drives it through 24
+ * edit phases covering every edit class:
+ *
+ *   - inline typing (1 char at start/giant block/paragraph, backspace,
+ *     char delete, word replace, tag-boundary edit)
+ *   - blank-run growth/shrink
+ *   - special blocks (imagemap content, url text)
+ *   - structural block edits (prepend heading, insert box/quote/code,
+ *     delete first/last/middle block, convert paragraph→heading, append)
+ *   - big edits (8KB paste, 20KB delete, replace imagemap, nuke-most)
+ *
+ * The invariant is the engine's core contract: after EVERY edit the
+ * windowed-patched DOM must equal the full re-render (`morphHTML` of
+ * `renderer.render(root)`). That is the differential that proves the
+ * incremental paths never leave the DOM diverging — no matter where the
+ * edit lands or what it does. `stats.windowed` is recorded per phase so a
+ * regression that silently downgrades to the full walk is visible.
+ *
+ * A separate phase simulates holding a key down: 60 consecutive 1-char
+ * appends, each applied and patched separately, with a MutationObserver
+ * proving the DOM churn stays O(1)-per-keystroke (not O(blocks)).
+ *
+ * Run with `PROFILE=1` for the per-phase timings; the default run is pure
+ * correctness.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { BBCodeDocumentModel } from '../BBCode/BBCodeDocumentModel'
+import { HTMLRenderer } from '../Visitors/HTMLRenderer'
+import { morphHTML } from '../Visitors/DOMMorpher'
+import { patchBlocksInto } from '../Visitors/BlockPatcher'
+
+const PROFILE = process.env.PROFILE === '1'
+
+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')
+}
+
+/** Strip data-node-id so the differential is structural, not identity-based. */
+function stripIds(html: string): string {
+  return html.replace(/ data-node-id="[^"]*"/g, '')
+}
+
+/** Ground truth: a fresh element morphed with the full render of the root. */
+function morphDOM(model: BBCodeDocumentModel, renderer: HTMLRenderer): HTMLDivElement {
+  const el = document.createElement('div')
+  if (model.redRoot) morphHTML(el, renderer.render(model.redRoot))
+  return el
+}
+
+const insertAt = (s: string, pos: number, text: string): string =>
+  s.slice(0, pos) + text + s.slice(pos)
+const del = (s: string, start: number, end: number): string => s.slice(0, start) + s.slice(end)
+
+/** Position right after the next blank line (realistic Enter + paste spot). */
+function afterBlank(s: string, pos: number): number {
+  const i = s.indexOf('\n\n', pos)
+  return i === -1 ? s.length : i + 2
+}
+
+interface Phase {
+  name: string
+  edit: (src: string) => string
+  /** True: the windowed path MUST fire (small local edit). False: bail is fine. */
+  expectWindowed: boolean
+}
+
+describe('Quasar @ 500k — every edit kind on the real fixture', () => {
+  it('batería de 24 ediciones con diferencial contra el morph completo', () => {
+    const src0 = loadFixture()
+    const renderer = new HTMLRenderer()
+    const winOpts = { renderer, minWindowedBlocks: 0 }
+
+    let current = src0
+    let model = new BBCodeDocumentModel({ source: current })
+    const el = document.createElement('div')
+    patchBlocksInto(el, model.redRoot!, winOpts) // prime the patch cache
+
+    const phases: Phase[] = [
+      { name: 'type-1char-at-start', expectWindowed: true, edit: (s) => insertAt(s, 0, 'X') },
+      {
+        name: 'type-1char-in-giant-gradient',
+        expectWindowed: true,
+        edit: (s) => insertAt(s, s.indexOf('◆') + 1, 'X'),
+      },
+      {
+        name: 'type-1char-in-paragraph',
+        expectWindowed: true,
+        edit: (s) => {
+          const p = s.indexOf('hxovc | Feel comfortable checking!')
+          return p === -1 ? s : insertAt(s, p, 'X')
+        },
+      },
+      { name: 'delete-1char-middle', expectWindowed: true, edit: (s) => del(s, s.indexOf('hxovc'), s.indexOf('hxovc') + 1) },
+      { name: 'backspace-at-end', expectWindowed: true, edit: (s) => s.slice(0, -1) },
+      { name: 'replace-word', expectWindowed: true, edit: (s) => s.replace('Twitch', 'TwitchTV') },
+      {
+        name: 'edit-at-tag-boundary',
+        expectWindowed: true,
+        edit: (s) => insertAt(s, s.indexOf('[/color]') + 8, 'Y'),
+      },
+      { name: 'grow-blank-run', expectWindowed: true, edit: (s) => s.replace('\n\n', '\n\n\n\n\n') },
+      {
+        name: 'shrink-blank-run',
+        expectWindowed: true,
+        edit: (s) => {
+          const i = s.indexOf('\n\n\n\n')
+          return i === -1 ? s.replace('\n\n', '\n') : s.slice(0, i) + '\n\n' + s.slice(i + 4)
+        },
+      },
+      {
+        name: 'edit-inside-imagemap',
+        expectWindowed: true,
+        edit: (s) => s.replace('hxovc.s-ul.eu/84A4eZfV', 'hxovc.s-ul.eu/84A4eZfV2'),
+      },
+      { name: 'edit-url-link-text', expectWindowed: true, edit: (s) => s.replace('Chess', 'ChessTV') },
+      { name: 'prepend-heading-block', expectWindowed: true, edit: (s) => '[heading]TOP[/heading]\n\n' + s },
+      {
+        name: 'insert-box-block-mid',
+        expectWindowed: true,
+        edit: (s) => insertAt(s, afterBlank(s, Math.floor(s.length * 0.5)), '[box]caja nueva[/box]\n\n'),
+      },
+      {
+        name: 'insert-quote-block-mid',
+        expectWindowed: true,
+        edit: (s) => insertAt(s, afterBlank(s, Math.floor(s.length * 0.6)), '[quote]cita nueva[/quote]\n\n'),
+      },
+      {
+        name: 'insert-code-block-mid',
+        expectWindowed: true,
+        edit: (s) => insertAt(s, afterBlank(s, Math.floor(s.length * 0.4)), '[code]codigo nuevo[/code]\n\n'),
+      },
+      {
+        name: 'convert-paragraph-to-heading',
+        expectWindowed: true,
+        edit: (s) => s.replace('hxovc | Feel comfortable checking!', '[heading]WELCOME[/heading]'),
+      },
+      {
+        name: 'delete-middle-imagemap',
+        expectWindowed: true,
+        edit: (s) => {
+          const a = s.indexOf('[imagemap]')
+          if (a === -1) return s
+          const b = s.indexOf('[/imagemap]', a)
+          const end = b === -1 ? s.length : b + '[/imagemap]'.length
+          const after = s.indexOf('\n\n', end)
+          return del(s, a, after === -1 ? end : after + 2)
+        },
+      },
+      { name: 'append-block-at-end', expectWindowed: true, edit: (s) => s + '\n\n[box]fin[/box]' },
+      { name: 'delete-last-block', expectWindowed: true, edit: (s) => s.slice(0, s.lastIndexOf('\n\n')) },
+      {
+        name: 'delete-first-block',
+        expectWindowed: true,
+        edit: (s) => {
+          const i = s.indexOf('\n\n')
+          return i === -1 ? s : s.slice(i + 2)
+        },
+      },
+      {
+        name: 'paste-8kb-mid',
+        expectWindowed: false, // 300 bloques nuevos: el churn cubre casi la mitad del doc → baila a full (correcto)
+        edit: (s) => {
+          const chunk = Array.from({ length: 300 }, () => '[centre][size=100][color=#ABCDEF]▬[/color][/size]').join('\n\n')
+          return insertAt(s, afterBlank(s, Math.floor(s.length * 0.3)), chunk + '\n\n')
+        },
+      },
+      {
+        name: 'delete-20k-mid',
+        // Regresión del 2026-08-10: borrar 20k en el medio tras un paste de
+        // 8KB re-keyea 24 runs sobrevivientes a ~24 posiciones de la banda de
+        // identidad del patcher — la ventana vieja los perdía, el walk insertaba
+        // duplicados y el DOM divergía (452 vs 428 childNodes). El fix extiende
+        // la banda mientras el run viejo sea twin (reference-identical) de la
+        // ventana nueva, así que este caso ahora es windowed Y correcto.
+        expectWindowed: true,
+        edit: (s) => del(s, Math.floor(s.length * 0.5), Math.floor(s.length * 0.5) + 20_000),
+      },
+      {
+        name: 'replace-imagemap-content',
+        expectWindowed: true,
+        edit: (s) => s.replace('Sarichus', 'Sarichus2'),
+      },
+      {
+        name: 'nuke-most-of-doc',
+        expectWindowed: false, // window > half → must bail to full and still be exact
+        edit: (s) => s.slice(0, 800) + s.slice(s.length - 800),
+      },
+    ]
+
+    const results: Array<{
+      name: string
+      parseMs: number
+      patchMs: number
+      windowed: boolean
+      patched: number
+      total: number
+    }> = []
+
+    for (const phase of phases) {
+      const next = phase.edit(current)
+      if (next === current) {
+        if (PROFILE) console.log(`[500k-edits] ${phase.name}: SKIP (edit sin cambio)`)
+        continue
+      }
+
+      const t0 = performance.now()
+      model.applyTextUpdate(next)
+      model.ensureAnalyzed()
+      const parseMs = performance.now() - t0
+      const root = model.redRoot!
+
+      const t1 = performance.now()
+      const stats = patchBlocksInto(el, root, winOpts)
+      const patchMs = performance.now() - t1
+
+      const expected = morphDOM(model, renderer)
+      expect(stripIds(el.innerHTML), `divergencia tras "${phase.name}"`).toBe(stripIds(expected.innerHTML))
+
+      if (phase.expectWindowed) {
+        expect(
+          stats.windowed,
+          `"${phase.name}" debió ir por la ventana pero fue ${stats.mode}/${stats.windowed ? 'win' : 'full'}`,
+        ).toBe(true)
+      }
+
+      if (PROFILE && model.lastReparsePath) {
+        console.log(
+          `[500k-edits]   └ reparse=${model.lastReparsePath}${model.lastReparseFallbackReason ? ` (${model.lastReparseFallbackReason})` : ''}`,
+        )
+      }
+
+      results.push({
+        name: phase.name,
+        parseMs,
+        patchMs,
+        windowed: !!stats.windowed,
+        patched: stats.patched,
+        total: stats.total,
+      })
+      current = next
+    }
+
+    if (PROFILE) {
+      console.log('\n[500k-edits] ---- batería (windowed forzado) ----')
+      for (const r of results) {
+        console.log(
+          `[500k-edits] ${r.name.padEnd(28)} parse=${r.parseMs.toFixed(1).padStart(7)}ms ` +
+            `patch=${r.patchMs.toFixed(2).padStart(7)}ms ` +
+            `${r.windowed ? 'WIN ' : 'FULL'} patched=${r.patched}/${r.total}`,
+        )
+      }
+      const win = results.filter((r) => r.windowed).length
+      const worst = results.reduce((m, r) => Math.max(m, r.patchMs), 0)
+      console.log(`[500k-edits] windowed=${win}/${results.length} worst-patch=${worst.toFixed(2)}ms`)
+    }
+  }, 300_000)
+
+  it('ráfaga de teclas (60x append de 1 char) — DOM churn O(1) por tecla', () => {
+    let s = loadFixture()
+    const renderer = new HTMLRenderer()
+    const winOpts = { renderer, minWindowedBlocks: 0 }
+
+    let model = new BBCodeDocumentModel({ source: s })
+    const el = document.createElement('div')
+    patchBlocksInto(el, model.redRoot!, winOpts)
+
+    const mo = new MutationObserver(() => {})
+    mo.observe(el, { childList: true })
+
+    const patchTimes: number[] = []
+    let winCount = 0
+    let maxMutations = 0
+    let worstPatch = 0
+
+    for (let k = 0; k < 60; k++) {
+      s += 'a'
+      model.applyTextUpdate(s)
+      model.ensureAnalyzed()
+      const t0 = performance.now()
+      const stats = patchBlocksInto(el, model.redRoot!, winOpts)
+      const dt = performance.now() - t0
+      patchTimes.push(dt)
+      worstPatch = Math.max(worstPatch, dt)
+      if (stats.windowed) winCount++
+      maxMutations = Math.max(maxMutations, mo.takeRecords().length)
+    }
+    mo.disconnect()
+
+    // Correctness after the burst: the DOM must equal the full re-render.
+    const expected = morphDOM(model, renderer)
+    expect(stripIds(el.innerHTML)).toBe(stripIds(expected.innerHTML))
+
+    const sorted = [...patchTimes].sort((a, b) => a - b)
+    const p50 = sorted[Math.floor(sorted.length / 2)]
+    const p95 = sorted[Math.floor(sorted.length * 0.95)]
+    if (PROFILE) {
+      console.log(
+        `[500k-edits] ráfaga: win=${winCount}/60 maxMutations/tecla=${maxMutations} ` +
+          `patch p50=${p50.toFixed(2)}ms p95=${p95.toFixed(2)}ms worst=${worstPatch.toFixed(2)}ms`,
+      )
+    }
+
+    // O(1) per keystroke: never an O(blocks) rebuild storm in the burst.
+    expect(maxMutations).toBeLessThanOrEqual(12)
+    expect(winCount).toBeGreaterThanOrEqual(55)
+  }, 300_000)
+})

package/src/Tests/CollabPositions.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from 'vitest'
+import { transformOffset, transformRange } from '../Collab/positions'
+import { BBCodeDocumentModel } from '../BBCode/BBCodeDocumentModel'
+import type { TextChange } from '../Incremental/ChangeTracker'
+
+/**
+ * Position transforms are collaboration's ground floor: a caret or remote
+ * cursor must keep pointing at the same CONTENT while text shifts under it.
+ *
+ * The central property, fuzz-checked below: for any position outside an
+ * edit's replaced span, the character it pointed at before is the character
+ * it points at after. Positions inside deleted text have no content left to
+ * point at, so they collapse to the edit boundary — asserted separately.
+ */
+
+function apply(source: string, c: TextChange): string {
+  return source.slice(0, c.start) + c.text + source.slice(c.end)
+}
+
+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('transformOffset', () => {
+  const insert: TextChange = { start: 5, end: 5, text: 'XY' }
+  const del: TextChange = { start: 3, end: 7, text: '' }
+  const replace: TextChange = { start: 3, end: 7, text: 'Z' }
+
+  it('before the edit: unchanged', () => {
+    expect(transformOffset(2, insert)).toBe(2)
+    expect(transformOffset(2, del)).toBe(2)
+  })
+
+  it('after the edit: shifted by the length delta', () => {
+    expect(transformOffset(9, insert)).toBe(11)
+    expect(transformOffset(9, del)).toBe(5)
+    expect(transformOffset(9, replace)).toBe(6)
+  })
+
+  it('exactly at an insertion point: bias decides the side', () => {
+    expect(transformOffset(5, insert, 'right')).toBe(7)
+    expect(transformOffset(5, insert, 'left')).toBe(5)
+  })
+
+  it('inside deleted text: collapses to the edit boundary', () => {
+    expect(transformOffset(5, del, 'left')).toBe(3)
+    expect(transformOffset(5, del, 'right')).toBe(3)
+    expect(transformOffset(5, replace, 'left')).toBe(3)
+    expect(transformOffset(5, replace, 'right')).toBe(4)
+  })
+
+  it('composes over a sequence of changes', () => {
+    const changes: TextChange[] = [
+      { start: 0, end: 0, text: 'aa' }, // caret at 5 → 7
+      { start: 9, end: 9, text: 'bb' }, // after 7: unchanged
+      { start: 1, end: 3, text: '' },   // before: 7 → 5
+    ]
+    expect(transformOffset(5, changes)).toBe(5)
+  })
+
+  it('property: positions outside the edit keep pointing at the same character', () => {
+    const rand = mulberry32(2026)
+    const alphabet = 'abcdefghij[]/ \n'
+    for (let round = 0; round < 2000; round++) {
+      let src = ''
+      const len = 10 + Math.floor(rand() * 60)
+      for (let i = 0; i < len; i++) src += alphabet[Math.floor(rand() * alphabet.length)]
+
+      const start = Math.floor(rand() * src.length)
+      const end = start + Math.floor(rand() * (src.length - start + 1))
+      let text = ''
+      const insertLen = Math.floor(rand() * 5)
+      for (let i = 0; i < insertLen; i++) text += alphabet[Math.floor(rand() * alphabet.length)]
+      const change: TextChange = { start, end, text }
+      const after = apply(src, change)
+
+      for (let offset = 0; offset < src.length; offset++) {
+        const isInsertionPoint = start === end && offset === start
+        if (offset >= start && offset <= end && !(offset === end && !isInsertionPoint)) {
+          // Inside the replaced span (or at the insertion point): only assert
+          // the result lands within the replacement's bounds.
+          const mapped = transformOffset(offset, change)
+          expect(mapped).toBeGreaterThanOrEqual(start)
+          expect(mapped).toBeLessThanOrEqual(start + text.length)
+          continue
+        }
+        const mapped = transformOffset(offset, change)
+        expect(after[mapped]).toBe(src[offset])
+      }
+    }
+  })
+})
+
+describe('transformRange', () => {
+  it('keeps covering exactly the content it covered', () => {
+    // "hola mundo cruel" — range over "mundo" = [5, 10)
+    const range = { start: 5, end: 10 }
+
+    // Insertion exactly at the start lands OUTSIDE the range.
+    expect(transformRange(range, { start: 5, end: 5, text: 'XX' })).toEqual({ start: 7, end: 12 })
+    // Insertion exactly at the end lands OUTSIDE too.
+    expect(transformRange(range, { start: 10, end: 10, text: 'XX' })).toEqual({ start: 5, end: 10 })
+    // Insertion strictly inside grows it.
+    expect(transformRange(range, { start: 7, end: 7, text: 'XX' })).toEqual({ start: 5, end: 12 })
+    // Deletion strictly before shifts it whole.
+    expect(transformRange(range, { start: 0, end: 2, text: '' })).toEqual({ start: 3, end: 8 })
+  })
+
+  it('never inverts: a range inside deleted text collapses to a point', () => {
+    const out = transformRange({ start: 4, end: 8 }, { start: 2, end: 10, text: '' })
+    expect(out.start).toBe(out.end)
+  })
+})
+
+describe('origin on model events', () => {
+  it('travels from applyTextUpdate to the document_changed event', () => {
+    const model = new BBCodeDocumentModel({ source: 'hola mundo' })
+    const origins: Array<string | undefined> = []
+    model.events.on('document_changed', e => origins.push(e.origin as string | undefined))
+
+    model.applyTextUpdate('hola mundo!')
+    model.applyTextUpdate('hola mundo!!', 'remote')
+
+    expect(origins).toEqual(['local', 'remote'])
+  })
+
+  it('a sync layer can ignore its own echo', () => {
+    const model = new BBCodeDocumentModel({ source: 'hola' })
+    let userEdits = 0
+    model.events.on('document_changed', e => {
+      if (e.origin === 'local') userEdits++
+    })
+
+    model.applyTextUpdate('hola!', 'sync')
+    model.applyTextUpdate('hola! y algo', 'local')
+    model.applyTextUpdate('hola! y algo mas')
+
+    expect(userEdits).toBe(2)
+  })
+})