@miliastry/quasar 1.0.6 → 1.1.0

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

@@ -36,7 +36,7 @@ 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 { hexToOklab, mixOklabToHex, perceptualDistanceOklab, hexToRgb } from '../../../Utils/ColorMath'
 import { extractHex, sigmoid, extractSequences, checkFormattingBreaks } from '../../Utils/color-utils'
 
 // ── Constants ─────────────────────────────────────────────────────
@@ -82,6 +82,61 @@ export interface GradientDiagnostics {
 
 // ── Main Analyzer ─────────────────────────────────────────────────
 
+export interface CollapsibleGradient {
+  readonly range: { start: number; end: number }
+  readonly colors: string[]
+  readonly stops: GradientStop[]
+  readonly easing: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut'
+  readonly combinedText: string
+  readonly replacementText: string
+  readonly confidence: number
+  readonly colorCount: number
+}
+
+export function formatGradientTag(
+  stops: GradientStop[],
+  colors: string[],
+  easing: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut',
+  text: string,
+): string {
+  const effectiveStops = stops.length >= 2
+    ? stops
+    : [{ color: colors[0], position: 0 }, { color: colors[colors.length - 1], position: 1 }]
+
+  // Deduplicate consecutive identical colors
+  const filteredStops: GradientStop[] = []
+  for (const s of effectiveStops) {
+    if (
+      filteredStops.length === 0 ||
+      filteredStops[filteredStops.length - 1].color.toLowerCase() !== s.color.toLowerCase()
+    ) {
+      filteredStops.push(s)
+    }
+  }
+
+  const finalStops = filteredStops.length >= 2
+    ? filteredStops
+    : [{ color: colors[0], position: 0 }, { color: colors[colors.length - 1], position: 1 }]
+
+  const n = finalStops.length
+  const isEvenlySpaced = finalStops.every((s, i) => {
+    const expected = n <= 1 ? 0 : i / (n - 1)
+    return Math.abs(s.position - expected) < 0.04
+  })
+
+  let stopsStr: string
+  if (isEvenlySpaced) {
+    stopsStr = finalStops.map(s => s.color).join(',')
+  } else {
+    stopsStr = finalStops
+      .map(s => `${s.color} ${Math.round(s.position * 100)}%`)
+      .join(',')
+  }
+
+  const easingStr = easing !== 'linear' ? `;easing=${easing}` : ''
+  return `[gradient=${stopsStr}${easingStr}]${text}[/gradient]`
+}
+
 export class GradientAnalyzer implements AnalyzerPass {
   readonly id = 'gradient-analyzer'
 
@@ -91,6 +146,115 @@ export class GradientAnalyzer implements AnalyzerPass {
     return contributions
   }
 
+  findCollapsibleGradients(tree: GreenNode, minConfidence = 0.6): CollapsibleGradient[] {
+    const results: CollapsibleGradient[] = []
+    this.collectCollapsibleGradients(tree, results, 0, minConfidence)
+    return results
+  }
+
+  private collectCollapsibleGradients(
+    node: GreenNode,
+    sink: CollapsibleGradient[],
+    nodeStart: number = 0,
+    minConfidence: number = 0.6,
+  ): void {
+    const children = node.children as GreenNode[]
+    if (children.length === 0) return
+    this.collapsibleGradientsAt(node, nodeStart, sink, minConfidence)
+    // Los desplazamientos se acumulan sobre la marcha, que es lo mismo que
+    // hace `childOffsets` pero sin el array.
+    let offset = nodeStart + node.leadingWidth
+    for (let i = 0; i < children.length; i++) {
+      this.collectCollapsibleGradients(children[i], sink, offset, minConfidence)
+      offset += children[i].width
+    }
+  }
+
+  /**
+   * The collapsible runs among the DIRECT children of `node`, and nothing
+   * below them.
+   *
+   * A run is a property of one children list: which siblings are `color`,
+   * what sits between them, what each one wraps. That is what makes it the
+   * unit the incremental analysis can work with — an edit rebuilds the child
+   * lists on the path down to it and nothing else, so only those lists can
+   * have gained or lost a run (see `SemanticAnalyzer.analyzeWindow`). The
+   * full scan above is this, applied to every node in pre-order; running it
+   * per list keeps the two paths producing the same items in the same order.
+   *
+   * Returns the number of runs appended to `sink`. `nodeStart` is the absolute
+   * offset of `node`, so the ranges come out in document coordinates.
+   */
+  collapsibleGradientsAt(
+    node: GreenNode,
+    nodeStart: number,
+    sink: CollapsibleGradient[],
+    minConfidence: number = 0.6,
+  ): number {
+    // El corte por arriba: la inmensa mayoría de los nodos del documento son
+    // hojas o no tienen suficientes hijos `color` seguidos como para formar
+    // un degradado. `childOffsets` asigna un array por nodo y
+    // `extractSequences` otro más; hacerlo para todos era pagar dos
+    // asignaciones por nodo del árbol para descartarlos acto seguido.
+    const children = node.children as GreenNode[]
+    if (children.length === 0) return 0
+    if (countColorChildren(children) < MIN_SEQUENCE_LENGTH) return 0
+
+    const offsets = childOffsets(node, nodeStart)
+    const sequences = extractSequences(children, 'color', extractHex)
+    let found = 0
+
+    for (const seq of sequences) {
+      const colors = seq.values as string[]
+      if (colors.length < MIN_SEQUENCE_LENGTH) continue
+
+      let textLen = 0
+      const textChunks: string[] = []
+      for (let i = seq.startIdx; i < seq.endIdx; i++) {
+        const child = children[i]
+        if (child.kind === 'color') {
+          for (const textChild of child.children as GreenNode[]) {
+            if (textChild.kind === 'text') {
+              textLen += textChild.text.length
+              textChunks.push(textChild.text)
+            } else if (textChild.kind === 'spacing' || textChild.kind === 'empty_line') {
+              textChunks.push('\n')
+            }
+          }
+        } else if (child.kind === 'text') {
+          textChunks.push(child.text)
+        }
+      }
+
+      const combinedText = textChunks.join('')
+      const hasBreaks = checkFormattingBreaks(children, seq, 'color')
+      const { stops, easing } = this.detectStops(colors)
+      const diag = this.buildDiagnostics(colors, stops)
+      const { score: rawScore } = this.calculateRawScore(diag, hasBreaks)
+      const confidence = sigmoid(rawScore, SIGMOID_STEEPNESS)
+
+      if (confidence >= minConfidence && stops.length >= 2) {
+        const range = {
+          start: offsets[seq.startIdx],
+          end: offsets[seq.endIdx],
+        }
+        const replacementText = formatGradientTag(stops, colors, easing, combinedText)
+        sink.push({
+          range,
+          colors,
+          stops,
+          easing,
+          combinedText,
+          replacementText,
+          confidence,
+          colorCount: colors.length,
+        })
+        found++
+      }
+    }
+    return found
+  }
+
   // ── Sequence Detection ──────────────────────────────────────────
 
   private findGradients(node: GreenNode, sink: Contribution[], nodeStart: number = 0): void {
@@ -152,33 +316,104 @@ export class GradientAnalyzer implements AnalyzerPass {
    */
   private detectStops(colors: string[]): { stops: GradientStop[]; easing: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' } {
     const n = colors.length
-    const stops: GradientStop[] = [{ color: colors[0], position: 0 }]
+    if (n <= 2) {
+      return {
+        stops: colors.map((c, i) => ({ color: c, position: n === 1 ? 0 : i / (n - 1) })),
+        easing: 'linear',
+      }
+    }
 
-    const totalDist = perceptualDistance(colors[0], colors[n - 1])
-    const minStep = totalDist * 0.08  // At least 8% of total range
-    let accumulated = 0
+    const oklab = colors.map(c => hexToOklab(c))
+    const rgb = colors.map(h => {
+      const [r, g, b] = hexToRgb(h)
+      return [r / 255, g / 255, b / 255]
+    })
 
+    // From `oklab`, not from the hex strings: `perceptualDistance` would
+    // convert both endpoints again, and both are already in hand.
+    const deltas: number[] = []
     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
+      deltas.push(perceptualDistanceOklab(oklab[i - 1], oklab[i]))
+    }
+
+    // 1. Text Studio change-point detection (derivative jump between neighbours)
+    const detectedIndices = new Set<number>([0, n - 1])
+    const STOP_THRESHOLD = 0.08
+    for (let i = 1; i < n - 1; i++) {
+      const curr = deltas[i]
+      const prev = deltas[i - 1]
+      if (curr > prev * 1.5 && curr > STOP_THRESHOLD) {
+        detectedIndices.add(i)
       }
     }
 
-    // Always include the last colour
-    if (stops[stops.length - 1].position < 1) {
-      stops.push({ color: colors[n - 1], position: 1 })
+    // 2. Dual-space (RGB + OKLab) chord deviation (Douglas-Peucker)
+    // Avoids over-segmenting smooth linear ramps (which are straight lines in RGB or OKLab)
+    // while accurately capturing true inflection points / color turns.
+    function checkChord(startIdx: number, endIdx: number): void {
+      if (endIdx - startIdx <= 1) return
+
+      const aR = rgb[startIdx]
+      const bR = rgb[endIdx]
+      const abRLenSq = (bR[0] - aR[0]) ** 2 + (bR[1] - aR[1]) ** 2 + (bR[2] - aR[2]) ** 2
+
+      const aO = oklab[startIdx]
+      const bO = oklab[endIdx]
+      const abOLenSq = (bO[0] - aO[0]) ** 2 + (bO[1] - aO[1]) ** 2 + (bO[2] - aO[2]) ** 2
+
+      let maxDev = 0
+      let maxIdx = -1
+
+      for (let i = startIdx + 1; i < endIdx; i++) {
+        let dR = 0
+        if (abRLenSq > 1e-7) {
+          const tR = Math.max(0, Math.min(1, ((rgb[i][0] - aR[0]) * (bR[0] - aR[0]) + (rgb[i][1] - aR[1]) * (bR[1] - aR[1]) + (rgb[i][2] - aR[2]) * (bR[2] - aR[2])) / abRLenSq))
+          dR = Math.hypot(rgb[i][0] - (aR[0] + tR * (bR[0] - aR[0])), rgb[i][1] - (aR[1] + tR * (bR[1] - aR[1])), rgb[i][2] - (aR[2] + tR * (bR[2] - aR[2])))
+        } else {
+          dR = Math.hypot(rgb[i][0] - aR[0], rgb[i][1] - aR[1], rgb[i][2] - aR[2])
+        }
+
+        let dO = 0
+        if (abOLenSq > 1e-7) {
+          const tO = Math.max(0, Math.min(1, ((oklab[i][0] - aO[0]) * (bO[0] - aO[0]) + (oklab[i][1] - aO[1]) * (bO[1] - aO[1]) + (oklab[i][2] - aO[2]) * (bO[2] - aO[2])) / abOLenSq))
+          dO = Math.hypot(oklab[i][0] - (aO[0] + tO * (bO[0] - aO[0])), oklab[i][1] - (aO[1] + tO * (bO[1] - aO[1])), oklab[i][2] - (aO[2] + tO * (bO[2] - aO[2])))
+        } else {
+          dO = Math.hypot(oklab[i][0] - aO[0], oklab[i][1] - aO[1], oklab[i][2] - aO[2])
+        }
+
+        // Must deviate from linear in both sRGB and OKLab models to count as a genuine stop
+        const dev = Math.min(dR / 0.05, dO / 0.08)
+        if (dev > maxDev) {
+          maxDev = dev
+          maxIdx = i
+        }
+      }
+
+      if (maxDev > 1.0 && maxIdx !== -1) {
+        detectedIndices.add(maxIdx)
+        checkChord(startIdx, maxIdx)
+        checkChord(maxIdx, endIdx)
+      }
     }
 
+    checkChord(0, n - 1)
+
+    const sortedIndices = Array.from(detectedIndices).sort((a, b) => a - b)
+    const stops: GradientStop[] = sortedIndices.map(idx => ({
+      color: colors[idx],
+      position: idx / (n - 1),
+    }))
+    // Where each stop sits in `colors`, so the easing pass below can index
+    // into `oklab` instead of re-converting `stop.color`.
+    const stopSourceIndex = sortedIndices
+
     // 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)
+        const segDist = perceptualDistanceOklab(oklab[stopSourceIndex[i - 1]], oklab[stopSourceIndex[i]])
         segDists.push(segLen > 0 ? segDist / segLen : 0)
       }
 
@@ -211,7 +446,7 @@ export class GradientAnalyzer implements AnalyzerPass {
     // 1. Uniform perceptual spacing
     const pDiffs: number[] = []
     for (let i = 1; i < n; i++) {
-      pDiffs.push(perceptualDistance(colors[i - 1], colors[i]))
+      pDiffs.push(perceptualDistanceOklab(oklabArray[i - 1], oklabArray[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
@@ -234,19 +469,26 @@ export class GradientAnalyzer implements AnalyzerPass {
     }
     const monotonic = violations < n * 0.2
 
-    // 3. Count plateaus (consecutive perceptually identical colours)
+    // 3. Count plateaus (consecutive perceptually identical colours).
+    // These are the neighbour distances from step 1, not a new measurement.
     let plateauCount = 0
-    for (let i = 1; i < n; i++) {
-      if (perceptualDistance(colors[i - 1], colors[i]) < 0.01) plateauCount++
+    for (let i = 0; i < pDiffs.length; i++) {
+      if (pDiffs[i] < 0.01) plateauCount++
     }
 
     // 4. Perceptual error vs ideal OKLab interpolation
     let maxPerceptualError = 0
     if (n >= 3 && stops.length >= 2) {
+      // The ramp's endpoints are fixed for the whole loop; only `t` moves.
+      // The mix still round-trips through hex because the comparison is
+      // against a colour that has been quantised to 8 bits per channel, and
+      // dropping that would change the score.
+      const rampFrom = hexToOklab(stops[0].color)
+      const rampTo = hexToOklab(stops[stops.length - 1].color)
       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])
+        const ideal = mixOklabToHex(rampFrom, rampTo, t)
+        const error = perceptualDistanceOklab(hexToOklab(ideal), oklabArray[i])
         maxPerceptualError = Math.max(maxPerceptualError, error)
       }
     }
@@ -290,3 +532,35 @@ export class GradientAnalyzer implements AnalyzerPass {
     return { score, featureScores }
   }
 }
+
+/** Cuántos hijos directos son nodos `color`. Sin asignar nada. */
+function countColorChildren(children: readonly GreenNode[]): number {
+  let count = 0
+  for (let i = 0; i < children.length; i++) {
+    if (children[i].kind === 'color') count++
+  }
+  return count
+}
+
+export function findCollapsibleGradients(
+  tree: GreenNode,
+  minConfidence = 0.6,
+): CollapsibleGradient[] {
+  return new GradientAnalyzer().findCollapsibleGradients(tree, minConfidence)
+}
+
+const sharedAnalyzer = new GradientAnalyzer()
+
+/**
+ * The collapsible runs among the direct children of `node`, whose absolute
+ * start is `nodeStart`. See {@link GradientAnalyzer.collapsibleGradientsAt}.
+ */
+export function collapsibleGradientsAt(
+  node: GreenNode,
+  nodeStart: number,
+  sink: CollapsibleGradient[],
+  minConfidence = 0.6,
+): number {
+  return sharedAnalyzer.collapsibleGradientsAt(node, nodeStart, sink, minConfidence)
+}
+

package/src/Analysis/Passes/Analysis/SymbolAnalyzer.ts

@@ -0,0 +1,257 @@
+/**
+ * Quasar Analysis Framework — Symbol Analyzer
+ *
+ * Detects decorative Unicode glyphs — `✧ ⚔ ☽ ━ ◈` — in document text and
+ * reports them as SemanticContributions.
+ *
+ * The colour analyzers recognise structure that BBCode itself encodes: a
+ * gradient is a *sequence of tags*, so the tree already separates it from the
+ * prose around it. Symbols have no such marker. They are ordinary characters
+ * inside ordinary text nodes, indistinguishable at the syntax level from the
+ * words beside them. Recognising them therefore has to happen at the character
+ * level, against the Unicode blocks they come from.
+ *
+ * ## Runs, not characters
+ *
+ * Symbols are reported as contiguous *runs*, because the two ways a document
+ * uses them need different treatment:
+ *
+ *   `✧ airi ✧`      two one-glyph runs — ornaments framing a word
+ *   `✧⋆⋅⋆⋅⋆✧`       one seven-glyph run — a divider line
+ *
+ * Swapping the first means substituting glyph for glyph. Swapping the second
+ * means replacing the whole line with a different divider. A run of
+ * `MIN_SEPARATOR_LENGTH` or more is labelled `Separator`; anything shorter is
+ * labelled `Symbol`. Both carry per-glyph offsets in their metadata, so a
+ * consumer can address either the run or its individual characters.
+ *
+ * ## Confidence
+ *
+ * Detection is exact — a code point is either in a decorative block or it is
+ * not. Confidence answers the question that actually matters: is this glyph
+ * *ornamental*, or does it carry meaning? A dingbat is almost always
+ * decoration; `≈` in a sentence is probably arithmetic, and re-theming it
+ * would corrupt the text.
+ *
+ * Each block carries a base confidence, a run takes the *lowest* of its
+ * members — a run is only as safely ornamental as its least ornamental glyph —
+ * and separator-length runs receive a bonus, because a seven-character line of
+ * symbols is decoration regardless of which blocks it draws from.
+ *
+ * @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'
+
+// ── Constants ─────────────────────────────────────────────────────
+
+/** Runs at least this long read as a divider rather than as ornaments. */
+const MIN_SEPARATOR_LENGTH = 3
+
+/** Added to a separator-length run, on top of its lowest block confidence. */
+const SEPARATOR_BONUS = 0.25
+
+/** Confidence is never reported as certainty. */
+const MAX_CONFIDENCE = 0.99
+
+/**
+ * Node kinds whose text is not prose and must never be re-themed.
+ *
+ * `code` and `inline_code` are the lexer's raw tags (`BBCODE_RAW_TAGS`): their
+ * content is literal by definition, and a user who typed `✧` inside a code
+ * block meant that exact character. `image` holds a URL as its child text,
+ * where a matching code point would be part of an address, not decoration.
+ */
+const OPAQUE_KINDS: ReadonlySet<string> = new Set(['code', 'inline_code', 'image'])
+
+// ── Unicode blocks ────────────────────────────────────────────────
+
+interface SymbolBlock {
+  readonly name: string
+  readonly first: number
+  readonly last: number
+  /** How reliably a glyph from this block is decoration rather than content. */
+  readonly confidence: number
+}
+
+/**
+ * The decorative blocks, ordered by code point.
+ *
+ * Deliberately narrower than "everything that is not a letter". Latin
+ * punctuation, currency signs and CJK are all excluded: they appear in real
+ * prose, and a re-theming pass that rewrote them would be destroying text
+ * rather than restyling it.
+ */
+const SYMBOL_BLOCKS: readonly SymbolBlock[] = [
+  // Arrows and maths are the least certain: `→` and `≈` are ordinary in prose.
+  { name: 'arrows',           first: 0x2190,  last: 0x21ff,  confidence: 0.65 },
+  { name: 'math-operators',   first: 0x2200,  last: 0x22ff,  confidence: 0.60 },
+  { name: 'technical',        first: 0x2300,  last: 0x23ff,  confidence: 0.80 },
+  // Box drawing exists only to draw boxes and rules.
+  { name: 'box-drawing',      first: 0x2500,  last: 0x257f,  confidence: 0.95 },
+  { name: 'block-elements',   first: 0x2580,  last: 0x259f,  confidence: 0.90 },
+  { name: 'geometric',        first: 0x25a0,  last: 0x25ff,  confidence: 0.90 },
+  { name: 'misc-symbols',     first: 0x2600,  last: 0x26ff,  confidence: 0.90 },
+  { name: 'dingbats',         first: 0x2700,  last: 0x27bf,  confidence: 0.95 },
+  { name: 'symbols-arrows',   first: 0x2b00,  last: 0x2bff,  confidence: 0.90 },
+  // Astral emoji — always two UTF-16 units, see `scanText`.
+  { name: 'pictographs',      first: 0x1f300, last: 0x1f5ff, confidence: 0.85 },
+  { name: 'emoticons',        first: 0x1f600, last: 0x1f64f, confidence: 0.85 },
+  { name: 'supplemental',     first: 0x1f900, last: 0x1f9ff, confidence: 0.85 },
+]
+
+function blockOf(codePoint: number): SymbolBlock | null {
+  for (const block of SYMBOL_BLOCKS) {
+    if (codePoint >= block.first && codePoint <= block.last) return block
+  }
+  return null
+}
+
+// ── Types ─────────────────────────────────────────────────────────
+
+export interface SymbolGlyph {
+  readonly char: string
+  readonly codePoint: number
+  /** Unicode block name this glyph was matched in. */
+  readonly block: string
+  /** Absolute source offsets, UTF-16 code units — `source.slice(start, end)`. */
+  readonly start: number
+  readonly end: number
+}
+
+export interface SymbolRunModel {
+  /** The run exactly as it appears in the source. */
+  readonly text: string
+  readonly glyphs: readonly SymbolGlyph[]
+  /** Distinct block names present, in first-seen order. */
+  readonly blocks: readonly string[]
+  /** Length in glyphs — not in UTF-16 units, which astral symbols inflate. */
+  readonly length: number
+  /** Whether the run was long enough to read as a divider. */
+  readonly isSeparator: boolean
+}
+
+// ── Analyzer ──────────────────────────────────────────────────────
+
+export class SymbolAnalyzer implements AnalyzerPass {
+  readonly id = 'symbol'
+
+  run(tree: GreenNode, _context: PipelineContext): Contribution[] {
+    const contributions: Contribution[] = []
+    this.walk(tree, contributions, 0)
+    return contributions
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  /**
+   * Descend the tree, accumulating absolute offsets.
+   *
+   * Green nodes carry widths rather than positions (see `GreenNode.ts`), so
+   * the offsets a Contribution reports are built on the way down. Only `text`
+   * leaves are scanned: an element node's own `text` holds its attributes
+   * (`=#D194B3`), which are syntax, not content.
+   */
+  private walk(node: GreenNode, sink: Contribution[], start: number): void {
+    if (OPAQUE_KINDS.has(node.kind)) return
+
+    if (node.kind === 'text') {
+      this.scanText(node.text, start, sink)
+      return
+    }
+
+    const children = node.children as readonly GreenNode[]
+    if (children.length === 0) return
+
+    const offsets = childOffsets(node, start)
+    for (let i = 0; i < children.length; i++) {
+      this.walk(children[i], sink, offsets[i])
+    }
+  }
+
+  /**
+   * Find runs of decorative glyphs in one text leaf.
+   *
+   * Iterates by code point, not by index: an astral symbol such as `🌸`
+   * occupies two UTF-16 units, and stepping one unit at a time would split it
+   * into unpaired surrogates that match no block. The offsets recorded stay in
+   * UTF-16 units so they address the source directly.
+   */
+  private scanText(text: string, textStart: number, sink: Contribution[]): void {
+    let run: SymbolGlyph[] = []
+
+    const flush = () => {
+      if (run.length > 0) {
+        sink.push(this.toContribution(text, textStart, run))
+        run = []
+      }
+    }
+
+    let i = 0
+    while (i < text.length) {
+      const codePoint = text.codePointAt(i)!
+      const width = codePoint > 0xffff ? 2 : 1
+      const block = blockOf(codePoint)
+
+      if (block) {
+        run.push({
+          char: String.fromCodePoint(codePoint),
+          codePoint,
+          block: block.name,
+          start: textStart + i,
+          end: textStart + i + width,
+        })
+      } else {
+        flush()
+      }
+
+      i += width
+    }
+
+    flush()
+  }
+
+  private toContribution(
+    text: string,
+    textStart: number,
+    glyphs: readonly SymbolGlyph[],
+  ): Contribution {
+    const start = glyphs[0].start
+    const end = glyphs[glyphs.length - 1].end
+    const isSeparator = glyphs.length >= MIN_SEPARATOR_LENGTH
+
+    const blocks: string[] = []
+    for (const glyph of glyphs) {
+      if (!blocks.includes(glyph.block)) blocks.push(glyph.block)
+    }
+
+    // The lowest base wins: a run is only as safely ornamental as its least
+    // ornamental glyph, so `≈≈≈` stays more doubtful than `✧✧✧`.
+    let confidence = Math.min(...glyphs.map(g => blockOf(g.codePoint)!.confidence))
+    if (isSeparator) confidence = Math.min(MAX_CONFIDENCE, confidence + SEPARATOR_BONUS)
+
+    const model: SymbolRunModel = {
+      text: text.slice(start - textStart, end - textStart),
+      glyphs,
+      blocks,
+      length: glyphs.length,
+      isSeparator,
+    }
+
+    return {
+      kind: ContributionKind.Semantic,
+      label: isSeparator ? 'Separator' : 'Symbol',
+      confidence,
+      range: { start, end },
+      metadata: { model },
+      description: isSeparator
+        ? `Separator of ${glyphs.length} glyphs (${blocks.join(', ')})`
+        : `Decorative symbol ${model.text} (${blocks.join(', ')})`,
+    }
+  }
+}