@miliastry/quasar 1.0.0

package/src/Analysis/Passes/Analysis/RainbowAnalyzer.ts

@@ -0,0 +1,233 @@
+/**
+ * Quasar Analysis Framework — Rainbow Analyzer
+ *
+ * Detects sequences of [color=#HEX] tags where the HSL hue rotates
+ * continuously while saturation and lightness remain approximately
+ * constant — the classic "rainbow" pattern.
+ *
+ * ## Confidence features
+ *
+ *   - hueRotation (+0.35) — hue changes monotonically (increasing or decreasing)
+ *   - stableSaturation (+0.20) — saturation stays within a narrow band
+ *   - stableLightness (+0.20) — lightness stays within a narrow band
+ *   - contiguousWrappers (+0.15) — no gaps in the colour sequence
+ *   - noFormattingBreaks (+0.10) — no formatting tags between colours
+ *
+ * @see SemanticContribution
+ */
+
+import type { AnalyzerPass } from '../../Contracts/Pass'
+import type { PipelineContext } from '../../Contracts/PipelineContext'
+import type { Contribution } from '../../Contracts/Contribution'
+import { ContributionKind } from '../../Contracts/Contribution'
+import type { GreenNode } from '../../../Syntax/GreenNode'
+import { childOffsets } from '../../../Syntax/GreenNode'
+import { hexToHsl } from '../../../Utils/ColorMath'
+import { extractHex, sigmoid, extractSequences, checkFormattingBreaks } from '../../Utils/color-utils'
+
+// ── Constants ─────────────────────────────────────────────────────
+
+const MIN_SEQUENCE_LENGTH = 4
+const SIGMOID_STEEPNESS = 6
+
+const WEIGHTS = {
+  hueRotation: 0.50,
+  stableSaturation: 0.25,
+  stableLightness: 0.20,
+  noFormattingBreaks: 0.05,
+} as const
+
+// ── Types ─────────────────────────────────────────────────────────
+
+export interface RainbowModel {
+  readonly colors: string[]
+  readonly hueStart: number
+  readonly hueEnd: number
+  readonly avgSaturation: number
+  readonly avgLightness: number
+  readonly rangeStart: number
+  readonly rangeEnd: number
+  readonly charCount: number
+  readonly diagnostics: RainbowDiagnostics
+}
+
+export interface RainbowDiagnostics {
+  readonly hueDelta: number
+  readonly saturationDeviation: number
+  readonly lightnessDeviation: number
+  readonly isContinuous: boolean
+  readonly featureScores: Readonly<Record<string, number>>
+}
+
+// ── Main Analyzer ─────────────────────────────────────────────────
+
+export class RainbowAnalyzer implements AnalyzerPass {
+  readonly id = 'rainbow-analyzer'
+
+  run(tree: GreenNode, _context: PipelineContext): Contribution[] {
+    const contributions: Contribution[] = []
+    this.findRainbows(tree, contributions)
+    return contributions
+  }
+
+  private findRainbows(node: GreenNode, sink: Contribution[], nodeStart: number = 0): void {
+    // Green nodes carry widths, not positions, so a walk that reports source
+    // ranges accumulates them on the way down.
+    const offsets = childOffsets(node, nodeStart)
+    if (node.children.length > 0) {
+      const children = node.children as GreenNode[]
+      const sequences = extractSequences(children, 'color', extractHex)
+
+      for (const seq of sequences) {
+        const colors = seq.values as string[]
+        if (colors.length < MIN_SEQUENCE_LENGTH) continue
+
+        let textLen = 0
+        for (let i = seq.startIdx; i < seq.endIdx; i++) {
+          for (const child of children[i].children as GreenNode[]) {
+            if (child.kind === 'text') textLen += child.text.length
+          }
+        }
+
+        const hasBreaks = checkFormattingBreaks(children, seq, 'color')
+        const diag = this.analyzeRainbow(colors)
+        const { score, featureScores } = this.calculateRawScore(diag, hasBreaks)
+        const confidence = sigmoid(score, SIGMOID_STEEPNESS)
+
+        sink.push({
+          kind: ContributionKind.Semantic,
+          label: 'Rainbow',
+          confidence,
+          range: {
+            start: offsets[seq.startIdx],
+            end: offsets[seq.endIdx],
+          },
+          metadata: {
+            model: {
+              colors,
+              hueStart: diag.hueDelta >= 0 ? colors[0] : colors[colors.length - 1],
+              hueEnd: diag.hueDelta >= 0 ? colors[colors.length - 1] : colors[0],
+              avgSaturation: this.extractHSL(colors).avgS,
+              avgLightness: this.extractHSL(colors).avgL,
+              charCount: textLen,
+            },
+            diagnostics: { ...diag, featureScores },
+          },
+        })
+      }
+    }
+
+    const kids = node.children as GreenNode[]
+    for (let i = 0; i < kids.length; i++) {
+      this.findRainbows(kids[i], sink, offsets[i])
+    }
+  }
+
+  // ── HSL Analysis ────────────────────────────────────────────────
+
+  private extractHSL(colors: string[]): { hues: number[]; sats: number[]; lights: number[]; avgS: number; avgL: number } {
+    const hues: number[] = []
+    const sats: number[] = []
+    const lights: number[] = []
+
+    for (const c of colors) {
+      const [h, s, l] = hexToHsl(c)
+      hues.push(h)
+      sats.push(s)
+      lights.push(l)
+    }
+
+    const avgS = sats.reduce((a, b) => a + b, 0) / sats.length
+    const avgL = lights.reduce((a, b) => a + b, 0) / lights.length
+
+    return { hues, sats, lights, avgS, avgL }
+  }
+
+  private analyzeRainbow(colors: string[]): Omit<RainbowDiagnostics, 'featureScores'> {
+    const { hues, sats, lights, avgS, avgL } = this.extractHSL(colors)
+    const n = colors.length
+
+    // 1. Hue rotation: compute signed delta, unwrapping at 360→0
+    let totalHueDelta = 0
+    let unwrapped = hues[0]
+    for (let i = 1; i < n; i++) {
+      let delta = hues[i] - hues[i - 1]
+      if (delta > 180) delta -= 360
+      else if (delta < -180) delta += 360
+      totalHueDelta += delta
+      unwrapped += delta
+    }
+
+    // Reset to compute direction from unwrapped
+    const hueDirection = Math.sign(totalHueDelta)
+
+    // Check hue monotonicity (after unwrapping)
+    let hueViolations = 0
+    unwrapped = hues[0]
+    for (let i = 1; i < n; i++) {
+      let delta = hues[i] - hues[i - 1]
+      if (delta > 180) delta -= 360
+      else if (delta < -180) delta += 360
+      unwrapped += delta
+
+      const prevUnwrapped = unwrapped - delta
+      if (Math.sign(delta) !== hueDirection && Math.abs(delta) > 15) {
+        hueViolations++
+      }
+    }
+    const isContinuous = hueViolations < n * 0.25
+
+    // 2. Saturation stability (standard deviation)
+    const satDev = Math.sqrt(sats.reduce((sum, s) => sum + (s - avgS) ** 2, 0) / n)
+
+    // 3. Lightness stability (standard deviation)
+    const litDev = Math.sqrt(lights.reduce((sum, l) => sum + (l - avgL) ** 2, 0) / n)
+
+    return {
+      hueDelta: totalHueDelta,
+      saturationDeviation: satDev,
+      lightnessDeviation: litDev,
+      isContinuous,
+    }
+  }
+
+  // ── Confidence Scoring ──────────────────────────────────────────
+
+  private calculateRawScore(
+    diag: Omit<RainbowDiagnostics, 'featureScores'>,
+    hasBreaks: boolean,
+  ): { score: number; featureScores: Record<string, number> } {
+    let score = 0
+
+    // Hue rotation: need significant hue change + continuity
+    const absHueDelta = Math.abs(diag.hueDelta)
+    if (diag.isContinuous && absHueDelta > 60) score += WEIGHTS.hueRotation
+    else if (absHueDelta > 30) score += WEIGHTS.hueRotation * 0.5
+    else score -= WEIGHTS.hueRotation * 0.5
+
+    // Stable saturation (low deviation)
+    if (diag.saturationDeviation < 15) score += WEIGHTS.stableSaturation
+    else if (diag.saturationDeviation < 30) score += WEIGHTS.stableSaturation * 0.5
+    else score -= WEIGHTS.stableSaturation * 0.5
+
+    // Stable lightness (low deviation)
+    if (diag.lightnessDeviation < 15) score += WEIGHTS.stableLightness
+    else if (diag.lightnessDeviation < 30) score += WEIGHTS.stableLightness * 0.5
+    else score -= WEIGHTS.stableLightness * 0.5
+
+    // No formatting breaks
+    if (!hasBreaks) score += WEIGHTS.noFormattingBreaks
+
+    const featureScores = {
+      hueRotation: (diag.isContinuous && absHueDelta > 60) ? WEIGHTS.hueRotation :
+                    absHueDelta > 30 ? WEIGHTS.hueRotation * 0.5 : -WEIGHTS.hueRotation * 0.5,
+      stableSaturation: diag.saturationDeviation < 15 ? WEIGHTS.stableSaturation :
+                        diag.saturationDeviation < 30 ? WEIGHTS.stableSaturation * 0.5 : -WEIGHTS.stableSaturation * 0.5,
+      stableLightness: diag.lightnessDeviation < 15 ? WEIGHTS.stableLightness :
+                       diag.lightnessDeviation < 30 ? WEIGHTS.stableLightness * 0.5 : -WEIGHTS.stableLightness * 0.5,
+      noFormattingBreaks: hasBreaks ? -WEIGHTS.noFormattingBreaks : WEIGHTS.noFormattingBreaks,
+    }
+
+    return { score, featureScores }
+  }
+}

package/src/Analysis/Passes/Analysis/WaveAnalyzer.ts

@@ -0,0 +1,211 @@
+/**
+ * Quasar Analysis Framework — Wave (Size Oscillation) Analyzer
+ *
+ * Detects sequences of [size=N] tags where the sizes follow a sinusoidal
+ * (or other periodic) oscillation pattern — the classic "wave/grow" effect.
+ *
+ * ## Confidence features
+ *
+ *   - periodicPattern (+0.35) — sizes follow a clear periodic pattern
+ *   - boundedRange (+0.20) — sizes stay within a plausible min-max range
+ *   - smoothTransitions (+0.20) — adjacent size differences are small
+ *   - contiguousWrappers (+0.15) — no gaps in the size sequence
+ *   - noFormattingBreaks (+0.10) — no formatting tags between size nodes
+ *
+ * @see SemanticContribution
+ */
+
+import type { AnalyzerPass } from '../../Contracts/Pass'
+import type { PipelineContext } from '../../Contracts/PipelineContext'
+import type { Contribution } from '../../Contracts/Contribution'
+import { ContributionKind } from '../../Contracts/Contribution'
+import type { GreenNode } from '../../../Syntax/GreenNode'
+import { childOffsets } from '../../../Syntax/GreenNode'
+import { extractSize, sigmoid, extractSequences, checkFormattingBreaks } from '../../Utils/color-utils'
+
+// ── Constants ─────────────────────────────────────────────────────
+
+const MIN_SEQUENCE_LENGTH = 5
+const SIGMOID_STEEPNESS = 6
+
+const WEIGHTS = {
+  periodicPattern: 0.45,
+  boundedRange: 0.25,
+  smoothTransitions: 0.25,
+  noFormattingBreaks: 0.05,
+} as const
+
+// ── Types ─────────────────────────────────────────────────────────
+
+export interface WaveModel {
+  readonly sizes: number[]
+  readonly minSize: number
+  readonly maxSize: number
+  readonly estimatedFrequency: number
+  readonly rangeStart: number
+  readonly rangeEnd: number
+  readonly charCount: number
+  readonly diagnostics: WaveDiagnostics
+}
+
+export interface WaveDiagnostics {
+  readonly periodicityScore: number      // 0-1, how well it matches a sinusoid
+  readonly hasSymmetry: boolean
+  readonly isBounded: boolean
+  readonly transitionSmoothness: number  // 0-1
+  readonly featureScores: Readonly<Record<string, number>>
+}
+
+// ── Main Analyzer ─────────────────────────────────────────────────
+
+export class WaveAnalyzer implements AnalyzerPass {
+  readonly id = 'wave-analyzer'
+
+  run(tree: GreenNode, _context: PipelineContext): Contribution[] {
+    const contributions: Contribution[] = []
+    this.findWaves(tree, contributions)
+    return contributions
+  }
+
+  private findWaves(node: GreenNode, sink: Contribution[], nodeStart: number = 0): void {
+    // Green nodes carry widths, not positions, so a walk that reports source
+    // ranges accumulates them on the way down.
+    const offsets = childOffsets(node, nodeStart)
+    if (node.children.length > 0) {
+      const children = node.children as GreenNode[]
+      const sequences = extractSequences(children, 'font_size', extractSize)
+
+      for (const seq of sequences) {
+        const sizes = seq.values as number[]
+        if (sizes.length < MIN_SEQUENCE_LENGTH) continue
+
+        let textLen = 0
+        for (let i = seq.startIdx; i < seq.endIdx; i++) {
+          for (const child of children[i].children as GreenNode[]) {
+            if (child.kind === 'text') textLen += child.text.length
+          }
+        }
+
+        const hasBreaks = checkFormattingBreaks(children, seq, 'font_size')
+        const diag = this.analyzeWave(sizes)
+        const { score, featureScores } = this.calculateRawScore(diag, hasBreaks)
+        const confidence = sigmoid(score, SIGMOID_STEEPNESS)
+
+        sink.push({
+          kind: ContributionKind.Semantic,
+          label: 'Wave',
+          confidence,
+          range: {
+            start: offsets[seq.startIdx],
+            end: offsets[seq.endIdx],
+          },
+          metadata: {
+            model: {
+              sizes,
+              minSize: Math.min(...sizes),
+              maxSize: Math.max(...sizes),
+              estimatedFrequency: diag.periodicityScore,
+              charCount: textLen,
+            },
+            diagnostics: { ...diag, featureScores },
+          },
+        })
+      }
+    }
+
+    const kids = node.children as GreenNode[]
+    for (let i = 0; i < kids.length; i++) {
+      this.findWaves(kids[i], sink, offsets[i])
+    }
+  }
+
+  // ── Wave Analysis ───────────────────────────────────────────────
+
+  private analyzeWave(sizes: number[]): Omit<WaveDiagnostics, 'featureScores'> {
+    const n = sizes.length
+
+    // 1. Detect periodicity: normalise to [0,1] and check correlation with sinusoid
+    const min = Math.min(...sizes)
+    const max = Math.max(...sizes)
+    const range = max - min || 1
+    const norm = sizes.map(s => (s - min) / range)
+
+    // Try multiple frequencies, pick the best match
+    let bestCorrelation = 0
+    for (let freq = 0.5; freq <= 4; freq += 0.25) {
+      let correlation = 0
+      for (let i = 0; i < n; i++) {
+        const t = i / (n - 1 || 1)
+        const sinVal = (Math.sin(t * Math.PI * 2 * freq) + 1) / 2
+        correlation += 1 - Math.abs(norm[i] - sinVal)
+      }
+      correlation /= n
+      bestCorrelation = Math.max(bestCorrelation, correlation)
+    }
+
+    const periodicityScore = Math.max(0, Math.min(1, bestCorrelation))
+
+    // 2. Check symmetry: is the first half a mirror of the second half?
+    let symmetry = 0
+    for (let i = 0; i < Math.floor(n / 2); i++) {
+      const j = n - 1 - i
+      symmetry += 1 - Math.abs(norm[i] - norm[j]) / (range || 1)
+    }
+    const hasSymmetry = symmetry / Math.max(1, Math.floor(n / 2)) > 0.7
+
+    // 3. Bounded range: are min and max within a sensible range?
+    const isBounded = min >= 50 && max <= 250 && range >= 20
+
+    // 4. Transition smoothness: are adjacent sizes close?
+    let smoothness = 0
+    for (let i = 1; i < n; i++) {
+      const diff = Math.abs(sizes[i] - sizes[i - 1])
+      smoothness += 1 - Math.min(1, diff / (range || 1))
+    }
+    const transitionSmoothness = smoothness / Math.max(1, n - 1)
+
+    return {
+      periodicityScore,
+      hasSymmetry,
+      isBounded,
+      transitionSmoothness,
+    }
+  }
+
+  // ── Confidence Scoring ──────────────────────────────────────────
+
+  private calculateRawScore(
+    diag: Omit<WaveDiagnostics, 'featureScores'>,
+    hasBreaks: boolean,
+  ): { score: number; featureScores: Record<string, number> } {
+    let score = 0
+
+    // Periodicity
+    if (diag.periodicityScore > 0.7) score += WEIGHTS.periodicPattern
+    else if (diag.periodicityScore > 0.4) score += WEIGHTS.periodicPattern * 0.5
+    else score -= WEIGHTS.periodicPattern * 0.5
+
+    // Bounded range
+    if (diag.isBounded) score += WEIGHTS.boundedRange
+    else score -= WEIGHTS.boundedRange * 0.5
+
+    // Smooth transitions
+    if (diag.transitionSmoothness > 0.6) score += WEIGHTS.smoothTransitions
+    else if (diag.transitionSmoothness > 0.3) score += WEIGHTS.smoothTransitions * 0.5
+    else score -= WEIGHTS.smoothTransitions * 0.5
+
+    // No formatting breaks
+    if (!hasBreaks) score += WEIGHTS.noFormattingBreaks
+
+    const featureScores = {
+      periodicPattern: diag.periodicityScore > 0.7 ? WEIGHTS.periodicPattern :
+                        diag.periodicityScore > 0.4 ? WEIGHTS.periodicPattern * 0.5 : -WEIGHTS.periodicPattern * 0.5,
+      boundedRange: diag.isBounded ? WEIGHTS.boundedRange : -WEIGHTS.boundedRange * 0.5,
+      smoothTransitions: diag.transitionSmoothness > 0.6 ? WEIGHTS.smoothTransitions :
+                         diag.transitionSmoothness > 0.3 ? WEIGHTS.smoothTransitions * 0.5 : -WEIGHTS.smoothTransitions * 0.5,
+      noFormattingBreaks: hasBreaks ? -WEIGHTS.noFormattingBreaks : WEIGHTS.noFormattingBreaks,
+    }
+
+    return { score, featureScores }
+  }
+}

package/src/Analysis/Passes/Analysis/__tests__/GradientAnalyzer.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Tests for refined GradientAnalyzer v2 (OKLab, change-point detection)
+ */
+
+import { describe, it, expect } from 'vitest'
+import { greenNode, greenLeaf } from '../../../../Syntax/GreenNode'
+import type { GreenNode } from '../../../../Syntax/GreenNode'
+import { GradientAnalyzer } from '../GradientAnalyzer'
+import type { PipelineContext } from '../../../Contracts/PipelineContext'
+import { PipelineMode, ExportTarget } from '../../../Contracts/PipelineContext'
+import { ContributionKind } from '../../../Contracts/Contribution'
+
+const mockContext: PipelineContext = {
+  mode: PipelineMode.Batch,
+  target: ExportTarget.Miliastry,
+  featureFlags: {},
+  metadata: {},
+}
+
+function colorNode(hex: string, text: string): GreenNode {
+  // Widths of the real BBCode this stands for: `[color=#RRGGBB]` and `[/color]`.
+  const textLeaf = greenLeaf('text', text)
+  return greenNode('color', `=${hex}`, [textLeaf], 8 + hex.length, 8)
+}
+
+describe('GradientAnalyzer v2', () => {
+  it('detects a smooth linear gradient with high confidence', () => {
+    // Perfectly spaced perceptual gradient: #FF0000 → #990000 → #330000
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'A'),
+      colorNode('#CC0022', 'B'),
+      colorNode('#990044', 'C'),
+      colorNode('#660066', 'D'),
+      colorNode('#330088', 'E'),
+      colorNode('#0000AA', 'F'),
+    ])
+
+    const analyzer = new GradientAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    expect(results.length).toBeGreaterThanOrEqual(1)
+    if (results[0].kind === 'semantic') {
+      expect(results[0].confidence).toBeGreaterThan(0.7)
+    }
+  })
+
+  it('detects change points (stops) in plateau-heavy sequences', () => {
+    // RRRR→G→BBBB: 4 R, 1 G, 4 B
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'R'),
+      colorNode('#FF0000', 'R'),
+      colorNode('#FF0000', 'R'),
+      colorNode('#FF0000', 'R'),
+      colorNode('#00FF00', 'G'),
+      colorNode('#0000FF', 'B'),
+      colorNode('#0000FF', 'B'),
+      colorNode('#0000FF', 'B'),
+      colorNode('#0000FF', 'B'),
+    ])
+
+    const analyzer = new GradientAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    expect(results.length).toBeGreaterThanOrEqual(1)
+    if (results[0].kind === 'semantic') {
+      // Check that stops were detected via change-point detection
+      const model = results[0].metadata.model as Record<string, unknown>
+      const stops = model.stops as Array<{ color: string; position: number }>
+      // Should detect 3 stops: R, G, B
+      expect(stops.length).toBeGreaterThanOrEqual(3)
+    }
+  })
+
+  it('gives low confidence to random colour jumps', () => {
+    // Red→Green→Blue: sharp perceptual jumps
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'A'),
+      colorNode('#00FF00', 'B'),
+      colorNode('#0000FF', 'C'),
+    ])
+
+    const analyzer = new GradientAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    // Should detect, but with low confidence (large perceptual error)
+    if (results.length > 0 && results[0].kind === 'semantic') {
+      expect(results[0].confidence).toBeLessThan(0.7)
+    }
+  })
+
+  it('ignores sequences shorter than minimum length', () => {
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'A'),
+      colorNode('#00FF00', 'B'),
+    ])
+
+    const analyzer = new GradientAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    expect(results).toHaveLength(0)
+  })
+
+  it('handles mixed content (non-color nodes between colors)', () => {
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'A'),
+      greenLeaf('text', ' break '),
+      colorNode('#EE1100', 'B'),
+    ])
+
+    const analyzer = new GradientAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    // The break text should separate the sequence into single nodes
+    expect(results).toHaveLength(0)
+  })
+
+  it('returns diagnostics with stop count in metadata', () => {
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'A'),
+      colorNode('#DD2222', 'B'),
+      colorNode('#BB4444', 'C'),
+      colorNode('#996666', 'D'),
+      colorNode('#778888', 'E'),
+    ])
+
+    const analyzer = new GradientAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    if (results.length > 0 && results[0].kind === 'semantic') {
+      const diag = results[0].metadata.diagnostics as Record<string, unknown>
+      expect(typeof diag.stopCount).toBe('number')
+      expect(typeof diag.maxPerceptualError).toBe('number')
+    }
+  })
+})

package/src/Analysis/Passes/Analysis/__tests__/MergeableColorAnalyzer.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Tests for MergeableColorAnalyzer
+ */
+
+import { describe, it, expect } from 'vitest'
+import { greenNode, greenLeaf } from '../../../../Syntax/GreenNode'
+import { MergeableColorAnalyzer } from '../MergeableColorAnalyzer'
+import type { PipelineContext } from '../../../Contracts/PipelineContext'
+import { PipelineMode, ExportTarget } from '../../../Contracts/PipelineContext'
+import { ContributionKind } from '../../../Contracts/Contribution'
+
+const mockContext: PipelineContext = {
+  mode: PipelineMode.Batch,
+  target: ExportTarget.Osu,
+  featureFlags: {},
+  metadata: {},
+}
+
+function colorNode(hex: string, text: string): import('../../../../Syntax/GreenNode').GreenNode {
+  // Widths of the real BBCode this stands for: `[color=#RRGGBB]` and `[/color]`.
+  const textLeaf = greenLeaf('text', text)
+  return greenNode('color', `=${hex}`, [textLeaf], 8 + hex.length, 8)
+}
+
+describe('MergeableColorAnalyzer', () => {
+  it('detects mergeable consecutive identical colors', () => {
+    // [color=#FF0000]H[/color][color=#FF0000]e[/color][color=#FF0000]l[/color]
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'H'),
+      colorNode('#FF0000', 'e'),
+      colorNode('#FF0000', 'l'),
+    ])
+
+    const analyzer = new MergeableColorAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    expect(results).toHaveLength(1)
+    expect(results[0]).toMatchObject({
+      kind: ContributionKind.Optimization,
+      label: 'Merge Colors',
+    })
+  })
+
+  it('does NOT report non-identical consecutive colors', () => {
+    // [color=#FF0000]H[/color][color=#EE1100]e[/color][color=#DD2200]l[/color]
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'H'),
+      colorNode('#EE1100', 'e'),
+      colorNode('#DD2200', 'l'),
+    ])
+
+    const analyzer = new MergeableColorAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    expect(results).toHaveLength(0)
+  })
+
+  it('does NOT report single color nodes', () => {
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'H'),
+    ])
+
+    const analyzer = new MergeableColorAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    expect(results).toHaveLength(0)
+  })
+
+  it('detects multiple separate mergeable sequences', () => {
+    // [color=#FF0000]A[/color][color=#FF0000]B[/color] --- [color=#00FF00]X[/color][color=#00FF00]Y[/color][color=#00FF00]Z[/color]
+    const tree = greenNode('document', '', [
+      colorNode('#FF0000', 'A'),
+      colorNode('#FF0000', 'B'),
+      colorNode('#00FF00', 'X'),
+      colorNode('#00FF00', 'Y'),
+      colorNode('#00FF00', 'Z'),
+    ])
+
+    const analyzer = new MergeableColorAnalyzer()
+    const results = analyzer.run(tree, mockContext)
+
+    expect(results).toHaveLength(2)
+  })
+})