@miliastry/quasar 1.0.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@miliastry/quasar",
+  "version": "1.0.0",
+  "description": "Quasar Document Engine - Advanced BBCode/Markdown/HTML AST Engine",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "MSL-1.0",
+  "sideEffects": [
+    "./src/Visuals/*.css",
+    "./dist/Visuals/*.css"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./Visuals/lyne.css": "./dist/Visuals/lyne.css",
+    "./Visuals/osu.css": "./dist/Visuals/osu.css",
+    "./dist/Visuals/*": "./dist/Visuals/*",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/copy-css.mjs",
+    "prepublishOnly": "npm run verify && npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "verify": "npm run typecheck && npm run test"
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@miliastry/quasar-studio": "*",
+    "tsup": "^8.5.1",
+    "typescript": "5.7.3"
+  }
+}

package/src/Analysis/Contracts/AnalysisReport.ts

@@ -0,0 +1,26 @@
+/**
+ * Quasar Analysis Framework — Analysis Report
+ *
+ * Once all AnalyzerPasses have run, their Contributions are collected
+ * into an immutable AnalysisReport.  This report is the sole input to
+ * the DecisionPass(es).
+ *
+ * We deliberately keep the aggregator simple for now — just an array
+ * of contributions.  As more pass types emerge we may introduce a
+ * structured Aggregator that indexes/categorises contributions.
+ *
+ * @see DecisionPass
+ */
+
+import type { Contribution } from './Contribution'
+
+export interface AnalysisReport {
+  /** All contributions gathered from every AnalyzerPass. */
+  readonly contributions: readonly Contribution[]
+
+  /** Total number of analysis passes that ran. */
+  readonly passCount: number
+
+  /** Wall-clock time spent in analysis (ms). */
+  readonly elapsedMs: number
+}

package/src/Analysis/Contracts/Contribution.ts

@@ -0,0 +1,76 @@
+/**
+ * Quasar Analysis Framework — Contribution Types
+ *
+ * Every AnalyzerPass produces an array of Contributions.  A Contribution
+ * is a discriminated union so that downstream consumers (DecisionPass,
+ * AnalysisReport consumers, debug UI) can switch on `kind` and get
+ * perfect TypeScript narrowing.
+ *
+ * @see AnalysisReport
+ */
+
+// ── Kind enum ─────────────────────────────────────────────────────
+
+export const ContributionKind = {
+  Semantic: 'semantic',
+  Diagnostic: 'diagnostic',
+  Optimization: 'optimization',
+  Metrics: 'metrics',
+} as const
+
+export type ContributionKind = (typeof ContributionKind)[keyof typeof ContributionKind]
+
+// ── Individual contribution shapes ────────────────────────────────
+
+/**
+ * A semantic pattern recognised in the tree (gradient, wave, rainbow,…).
+ * These describe *meaning* of the document, not just surface syntax.
+ */
+export interface SemanticContribution {
+  readonly kind: typeof ContributionKind.Semantic
+  readonly label: string
+  readonly confidence: number       // 0-1
+  readonly range: { start: number; end: number }
+  readonly metadata: Record<string, unknown>
+  /** Human-readable description (optional). */
+  readonly description?: string
+}
+
+/**
+ * A diagnostic (warning, error, info) attached to a range in the tree.
+ */
+export interface DiagnosticContribution {
+  readonly kind: typeof ContributionKind.Diagnostic
+  readonly severity: 'error' | 'warning' | 'info' | 'hint'
+  readonly message: string
+  readonly range?: { start: number; end: number }
+  readonly code?: string
+}
+
+/**
+ * An optimisation opportunity detected in the tree (mergeable colours,
+ * redundant wrapping, empty tags, …).
+ */
+export interface OptimizationContribution {
+  readonly kind: typeof ContributionKind.Optimization
+  readonly label: string
+  readonly description: string
+  readonly estimatedImprovement?: string
+  readonly range: { start: number; end: number }
+}
+
+/**
+ * Aggregate metrics about the tree (character count, node depth, …).
+ */
+export interface MetricsContribution {
+  readonly kind: typeof ContributionKind.Metrics
+  readonly metrics: Record<string, number | string>
+}
+
+// ── Discriminated union ───────────────────────────────────────────
+
+export type Contribution =
+  | SemanticContribution
+  | DiagnosticContribution
+  | OptimizationContribution
+  | MetricsContribution

package/src/Analysis/Contracts/Pass.ts

@@ -0,0 +1,76 @@
+/**
+ * Quasar Analysis Framework — Pass Contracts
+ *
+ * Each pass in the analysis/transform pipeline implements one of these
+ * specialized interfaces.  The three kinds mirror LLVM's pass structure:
+ *
+ *   Analysis  — observe the tree, produce Contributions (never mutate)
+ *   Decision  — consume an AnalysisReport, produce a TransformationPlan
+ *   Transform — mutate the tree according to a plan
+ *
+ * @see ARCHITECTURE.md (Analysis Framework)
+ */
+
+import type { PipelineContext } from './PipelineContext'
+import type { Contribution } from './Contribution'
+import type { GreenNode } from '../../Syntax/GreenNode'
+import type { AnalysisReport } from './AnalysisReport'
+
+// ── Base ──────────────────────────────────────────────────────────
+
+/** Every pass has an identity string and belongs to a stage. */
+export interface Pass {
+  readonly id: string
+}
+
+// ── Analysis — observe, never mutate ──────────────────────────────
+
+/**
+ * An AnalyzerPass observes the Green Tree and produces one or more
+ * Contributions.  It MUST NOT mutate the tree or the context.
+ */
+export interface AnalyzerPass extends Pass {
+  run(tree: GreenNode, context: PipelineContext): Contribution[]
+}
+
+// ── Decision — plan actions from evidence ─────────────────────────
+
+/**
+ * A DecisionPass consumes an AnalysisReport (which itself is the
+ * aggregated output of all AnalyzerPasses) and produces a
+ * TransformationPlan that describes *intended* tree mutations.
+ */
+export interface DecisionPass extends Pass {
+  run(report: AnalysisReport, context: PipelineContext): TransformationPlan
+}
+
+// ── Transform — execute a plan on the tree ────────────────────────
+
+/**
+ * A TransformPass receives the current Green Tree together with a
+ * TransformationPlan and returns a **new** Green Tree.  It MUST NOT
+ * mutate the original tree — immutability guarantees deterministic
+ * replay and debugging.
+ */
+export interface TransformPass extends Pass {
+  run(tree: GreenNode, plan: TransformationPlan, context: PipelineContext): GreenNode
+}
+
+// ── Supporting types ──────────────────────────────────────────────
+
+/**
+ * A single action described by a TransformationPlan.
+ * `kind` tells the TransformPass what to do; `payload` carries
+ * per-kind parameters.
+ */
+export interface TransformAction {
+  readonly kind: string
+  readonly payload: Record<string, unknown>
+}
+
+/**
+ * Ordered set of actions that a DecisionPass produces.
+ */
+export interface TransformationPlan {
+  readonly actions: readonly TransformAction[]
+}

package/src/Analysis/Contracts/PipelineContext.ts

@@ -0,0 +1,48 @@
+/**
+ * Quasar Analysis Framework — Pipeline Context
+ *
+ * PipelineContext is **read-only by contract**.  It is built *before*
+ * the pipeline starts and MUST NOT be modified by any pass.
+ *
+ * If a pass needs to make information available to downstream passes it
+ * should emit a Contribution rather than mutating the context.
+ *
+ * @immutable
+ */
+
+// ── Mode ──────────────────────────────────────────────────────────
+
+export const PipelineMode = {
+  Interactive: 'interactive',     // TextStudio, editor integration
+  Batch: 'batch',                 // CLI, automated processing
+  Import: 'import',               // Clipboard / file import
+} as const
+
+export type PipelineMode = (typeof PipelineMode)[keyof typeof PipelineMode]
+
+// ── Export target ─────────────────────────────────────────────────
+
+export const ExportTarget = {
+  Osu: 'osu',
+  Miliastry: 'miliastry',
+  HTML: 'html',
+  Markdown: 'markdown',
+} as const
+
+export type ExportTarget = (typeof ExportTarget)[keyof typeof ExportTarget]
+
+// ── Context ───────────────────────────────────────────────────────
+
+export interface PipelineContext {
+  /** Where this pipeline run originates from. */
+  readonly mode: PipelineMode
+
+  /** The format we intend to export to (influences decisions). */
+  readonly target: ExportTarget
+
+  /** Feature flags that may enable/disable certain behaviours. */
+  readonly featureFlags: Readonly<Record<string, boolean>>
+
+  /** Free-form metadata provided by the caller (e.g. selection range). */
+  readonly metadata: Readonly<Record<string, unknown>>
+}

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

@@ -0,0 +1,292 @@
+/**
+ * Quasar Analysis Framework — Gradient Analyzer (v2)
+ *
+ * Detects sequences of [color=#HEX] tags that form a gradient pattern
+ * and reports them as SemanticContributions with a confidence score.
+ *
+ * ## Refinements over v1
+ *
+ * 1. **OKLab color space** — Uses OKLab (Bottosson 2020) for perceptual
+ *    colour distance instead of RGB.  Two colours with small OKLab distance
+ *    look nearly identical to the human eye, making gradient detection
+ *    much more accurate.
+ *
+ * 2. **Change-point detection** — Identifies gradient *stops* even when
+ *    plateaus (runs of identical colour) exist, so a sequence like
+ *    RRRR→G→BBBB is correctly parsed as a 3-stop gradient rather than
+ *    a failed linear interpolation.
+ *
+ * 3. **Sharper sigmoid (k=6)** — Better separation between "likely
+ *    gradient" and "maybe gradient" at the decision thresholds.
+ *
+ * ## Confidence features (weights sum to 1.0)
+ *
+ *   - uniformPerceptualSpacing  (+0.30)
+ *   - contiguousWrappers        (+0.25)
+ *   - noFormattingBreaks        (+0.15)
+ *   - monotonicProgression      (+0.20)
+ *   - lowPerceptualError        (+0.10)
+ *
+ * @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 { hexToOklab, mixHexOklab, perceptualDistance, hexToRgb } from '../../../Utils/ColorMath'
+import { extractHex, sigmoid, extractSequences, checkFormattingBreaks } from '../../Utils/color-utils'
+
+// ── Constants ─────────────────────────────────────────────────────
+
+const MIN_SEQUENCE_LENGTH = 3
+const SIGMOID_STEEPNESS = 6
+
+const WEIGHTS = {
+  uniformPerceptualSpacing: 0.30,
+  contiguousWrappers: 0.25,
+  noFormattingBreaks: 0.15,
+  monotonicProgression: 0.20,
+  lowPerceptualError: 0.10,
+} as const
+
+// ── Types ─────────────────────────────────────────────────────────
+
+export interface GradientModel {
+  readonly colors: string[]
+  readonly easing: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut'
+  readonly stops: GradientStop[]
+  readonly rangeStart: number
+  readonly rangeEnd: number
+  readonly charCount: number
+  readonly diagnostics: GradientDiagnostics
+}
+
+export interface GradientStop {
+  /** Hex colour at this stop */
+  readonly color: string
+  /** Normalised position 0-1 */
+  readonly position: number
+}
+
+export interface GradientDiagnostics {
+  readonly uniformSpacing: boolean
+  readonly monotonic: boolean
+  readonly plateauCount: number
+  readonly maxPerceptualError: number
+  readonly stopCount: number
+  readonly featureScores: Readonly<Record<string, number>>
+}
+
+// ── Main Analyzer ─────────────────────────────────────────────────
+
+export class GradientAnalyzer implements AnalyzerPass {
+  readonly id = 'gradient-analyzer'
+
+  run(tree: GreenNode, _context: PipelineContext): Contribution[] {
+    const contributions: Contribution[] = []
+    this.findGradients(tree, contributions)
+    return contributions
+  }
+
+  // ── Sequence Detection ──────────────────────────────────────────
+
+  private findGradients(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
+
+        // Sum text length in the sequence
+        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 { stops, easing } = this.detectStops(colors)
+        const diag = this.buildDiagnostics(colors, stops)
+        const { score: rawScore, featureScores } = this.calculateRawScore(diag, hasBreaks)
+        const confidence = sigmoid(rawScore, SIGMOID_STEEPNESS)
+
+        sink.push({
+          kind: ContributionKind.Semantic,
+          label: 'Gradient',
+          confidence,
+          range: {
+            start: offsets[seq.startIdx],
+            end: offsets[seq.endIdx],
+          },
+          metadata: {
+            model: { colors, easing, stops, charCount: textLen },
+            diagnostics: { ...diag, featureScores },
+          },
+        })
+      }
+    }
+
+    const kids = node.children as GreenNode[]
+    for (let i = 0; i < kids.length; i++) {
+      this.findGradients(kids[i], sink, offsets[i])
+    }
+  }
+
+  // ── Change-point Detection ──────────────────────────────────────
+
+  /**
+   * Detect gradient stops from a sequence of hex colours, handling plateaus.
+   *
+   * Algorithm: Scan for "significant changes" in perceptual distance.
+   * Wherever the cumulative perceptual distance from the last stop exceeds a
+   * threshold, a new stop is recorded.  This naturally skips over plateaus.
+   */
+  private detectStops(colors: string[]): { stops: GradientStop[]; easing: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' } {
+    const n = colors.length
+    const stops: GradientStop[] = [{ color: colors[0], position: 0 }]
+
+    const totalDist = perceptualDistance(colors[0], colors[n - 1])
+    const minStep = totalDist * 0.08  // At least 8% of total range
+    let accumulated = 0
+
+    for (let i = 1; i < n; i++) {
+      const dist = perceptualDistance(colors[i - 1], colors[i])
+      accumulated += dist
+      if (accumulated >= minStep && i < n - 1) {
+        stops.push({ color: colors[i], position: i / (n - 1) })
+        accumulated = 0
+      }
+    }
+
+    // Always include the last colour
+    if (stops[stops.length - 1].position < 1) {
+      stops.push({ color: colors[n - 1], position: 1 })
+    }
+
+    // Infer easing from change in perceptual distance across segments
+    let easing: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' = 'linear'
+    if (stops.length >= 3) {
+      const segDists: number[] = []
+      for (let i = 1; i < stops.length; i++) {
+        const segLen = stops[i].position - stops[i - 1].position
+        const segDist = perceptualDistance(stops[i - 1].color, stops[i].color)
+        segDists.push(segLen > 0 ? segDist / segLen : 0)
+      }
+
+      const earlyAvg = segDists.slice(0, Math.ceil(segDists.length / 3)).reduce((a, b) => a + b, 0) / Math.max(1, Math.ceil(segDists.length / 3))
+      const lateAvg = segDists.slice(-Math.ceil(segDists.length / 3)).reduce((a, b) => a + b, 0) / Math.max(1, Math.ceil(segDists.length / 3))
+
+      if (earlyAvg > lateAvg * 1.5) easing = 'easeIn'
+      else if (lateAvg > earlyAvg * 1.5) easing = 'easeOut'
+      else if (segDists.length >= 3) {
+        const midStart = Math.floor(segDists.length / 3)
+        const midEnd = Math.floor(2 * segDists.length / 3)
+        const midAvg = segDists.slice(midStart, midEnd).reduce((a, b) => a + b, 0) / (midEnd - midStart)
+        const edgeAvg = [...segDists.slice(0, midStart), ...segDists.slice(midEnd)].reduce((a, b) => a + b, 0) / Math.max(1, segDists.length - (midEnd - midStart))
+        if (midAvg > edgeAvg * 1.3) easing = 'easeInOut'
+      }
+    }
+
+    return { stops, easing }
+  }
+
+  // ── Diagnostics ─────────────────────────────────────────────────
+
+  private buildDiagnostics(
+    colors: string[],
+    stops: GradientStop[],
+  ): Omit<GradientDiagnostics, 'featureScores'> {
+    const n = colors.length
+    const oklabArray = colors.map(c => hexToOklab(c))
+
+    // 1. Uniform perceptual spacing
+    const pDiffs: number[] = []
+    for (let i = 1; i < n; i++) {
+      pDiffs.push(perceptualDistance(colors[i - 1], colors[i]))
+    }
+    const avgDiff = pDiffs.reduce((a, b) => a + b, 0) / pDiffs.length
+    const diffVariance = pDiffs.reduce((sum, d) => sum + (d - avgDiff) ** 2, 0) / pDiffs.length
+    const uniformSpacing = diffVariance < 0.001  // Tiny variance in perceptual space
+
+    // 2. Check monotonic: does each OKLab dimension change in one direction?
+    const first = oklabArray[0]
+    const last = oklabArray[n - 1]
+    const lDir = Math.sign(last[0] - first[0])
+    const aDir = Math.sign(last[1] - first[1])
+    const bDir = Math.sign(last[2] - first[2])
+
+    let violations = 0
+    for (let i = 1; i < n; i++) {
+      const curr = oklabArray[i]
+      const prev = oklabArray[i - 1]
+      if (lDir !== 0 && Math.sign(curr[0] - prev[0]) !== lDir && Math.abs(curr[0] - prev[0]) > 0.005) violations++
+      if (aDir !== 0 && Math.sign(curr[1] - prev[1]) !== aDir && Math.abs(curr[1] - prev[1]) > 0.005) violations++
+      if (bDir !== 0 && Math.sign(curr[2] - prev[2]) !== bDir && Math.abs(curr[2] - prev[2]) > 0.005) violations++
+    }
+    const monotonic = violations < n * 0.2
+
+    // 3. Count plateaus (consecutive perceptually identical colours)
+    let plateauCount = 0
+    for (let i = 1; i < n; i++) {
+      if (perceptualDistance(colors[i - 1], colors[i]) < 0.01) plateauCount++
+    }
+
+    // 4. Perceptual error vs ideal OKLab interpolation
+    let maxPerceptualError = 0
+    if (n >= 3 && stops.length >= 2) {
+      for (let i = 0; i < n; i++) {
+        const t = n > 1 ? i / (n - 1) : 0
+        const ideal = mixHexOklab(stops[0].color, stops[stops.length - 1].color, t)
+        const error = perceptualDistance(ideal, colors[i])
+        maxPerceptualError = Math.max(maxPerceptualError, error)
+      }
+    }
+
+    return { uniformSpacing, monotonic, plateauCount, maxPerceptualError, stopCount: stops.length }
+  }
+
+  // ── Confidence Scoring ──────────────────────────────────────────
+
+  private calculateRawScore(
+    diag: Omit<GradientDiagnostics, 'featureScores'>,
+    hasBreaks: boolean,
+  ): { score: number; featureScores: Record<string, number> } {
+    let score = 0
+
+    if (diag.uniformSpacing) score += WEIGHTS.uniformPerceptualSpacing
+    else score -= WEIGHTS.uniformPerceptualSpacing * 0.5
+
+    score += WEIGHTS.contiguousWrappers
+
+    if (!hasBreaks) score += WEIGHTS.noFormattingBreaks
+
+    if (diag.monotonic) score += WEIGHTS.monotonicProgression
+    else score -= WEIGHTS.monotonicProgression * 0.3
+
+    if (diag.maxPerceptualError < 0.02) score += WEIGHTS.lowPerceptualError
+    else if (diag.maxPerceptualError < 0.05) score += WEIGHTS.lowPerceptualError * 0.5
+    else {
+      const penalty = WEIGHTS.lowPerceptualError * Math.min(diag.maxPerceptualError * 20, 5)
+      score -= penalty
+    }
+
+    const featureScores = {
+      uniformPerceptualSpacing: diag.uniformSpacing ? WEIGHTS.uniformPerceptualSpacing : -WEIGHTS.uniformPerceptualSpacing * 0.5,
+      contiguousWrappers: WEIGHTS.contiguousWrappers,
+      noFormattingBreaks: hasBreaks ? -WEIGHTS.noFormattingBreaks : WEIGHTS.noFormattingBreaks,
+      monotonicProgression: diag.monotonic ? WEIGHTS.monotonicProgression : -WEIGHTS.monotonicProgression * 0.3,
+      lowPerceptualError: diag.maxPerceptualError < 0.05 ? WEIGHTS.lowPerceptualError : -WEIGHTS.lowPerceptualError * 0.5,
+    }
+
+    return { score, featureScores }
+  }
+}

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

@@ -0,0 +1,112 @@
+/**
+ * Quasar Analysis Framework — Mergeable Color Analyzer
+ *
+ * Detects sequences of consecutive [color=#HEX] wrappers where ALL
+ * adjacent colours are identical.  These are optimisation opportunities:
+ * the user could merge them into a single `[color]` tag.
+ *
+ * Example:
+ *   [color=#FF0000]H[/color][color=#FF0000]e[/color] → mergeable
+ *   [color=#FF0000]H[/color][color=#EE1100]e[/color] → NOT mergeable
+ *
+ * @see OptimizationContribution
+ */
+
+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 { extractHex } from '../../Utils/color-utils'
+
+export class MergeableColorAnalyzer implements AnalyzerPass {
+  readonly id = 'mergeable-color'
+
+  run(tree: GreenNode, _context: PipelineContext): Contribution[] {
+    const contributions: Contribution[] = []
+
+    // Walk all children of each node to find sequences of colour wrappers
+    this.findMergeableColorSequences(tree, contributions)
+
+    return contributions
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  /**
+   * Walk the tree and find consecutive color nodes with identical colours.
+   */
+  private findMergeableColorSequences(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)
+    // Only look at container nodes that might have colour children
+    if (node.children.length > 1) {
+      const children = node.children as GreenNode[]
+      let seqStart = -1
+      let seqHex: string | null = null
+
+      for (let i = 0; i < children.length; i++) {
+        const hex = extractHex(children[i])
+
+        if (hex !== null) {
+          if (seqStart === -1) {
+            // Start a new sequence
+            seqStart = i
+            seqHex = hex
+          } else if (hex !== seqHex) {
+            // Color changed — check if previous sequence was mergeable
+            if (i - seqStart > 1) {
+              this.emitMergeable(children, seqStart, i, seqHex!, sink, offsets)
+            }
+            seqStart = i
+            seqHex = hex
+          }
+          // If hex === seqHex, sequence continues — do nothing
+        } else {
+          // Non-color node — end any active sequence
+          if (seqStart !== -1 && seqStart < i - 1) {
+            this.emitMergeable(children, seqStart, i, seqHex!, sink, offsets)
+          }
+          seqStart = -1
+          seqHex = null
+        }
+      }
+
+      // Check if the last sequence is mergeable
+      if (seqStart !== -1 && seqStart < children.length - 1) {
+        this.emitMergeable(children, seqStart, children.length, seqHex!, sink, offsets)
+      }
+    }
+
+    // Recurse into children (colour nodes' children are text, so only recurse non-color nodes)
+    const kids = node.children as GreenNode[]
+    for (let i = 0; i < kids.length; i++) {
+      if (kids[i].kind !== 'color') {
+        this.findMergeableColorSequences(kids[i], sink, offsets[i])
+      }
+    }
+  }
+
+  private emitMergeable(
+    children: GreenNode[],
+    start: number,
+    end: number,
+    hex: string,
+    sink: Contribution[],
+    offsets: number[],
+  ): void {
+    const count = end - start
+    sink.push({
+      kind: ContributionKind.Optimization,
+      label: 'Merge Colors',
+      description: `${count} consecutive [color=${hex}] tags can be merged into one`,
+      estimatedImprovement: `-${(count - 1) * 100}% color tags`,
+      range: {
+        start: offsets[start],
+        end: offsets[end],
+      },
+    })
+  }
+}