@createiq/htmldiff 1.1.0 → 1.2.0-beta.0

package/src/HtmlDiff.ts

@@ -3,9 +3,74 @@ import Match from './Match'
 import MatchFinder from './MatchFinder'
 import Operation from './Operation'
 import { preprocessTables, restoreTablePlaceholders } from './TableDiff'
-import Utils from './Utils'
+import { buildSegments, type Segment, segmentEmissionShape } from './ThreeWayDiff'
+import { preprocessTablesThreeWay } from './ThreeWayTable'
+import Utils, { type WrapMetadata } from './Utils'
 import WordSplitter from './WordSplitter'
 
+/**
+ * State threaded into the recursive cell-level diff inside
+ * `preprocessTables`. Bundles the nesting depth (for the recursion-cap
+ * guard) with the caller-configurable settings that must propagate
+ * unchanged to inner instances so cell-level output stays consistent
+ * with the top-level call. Internal — never crosses the public API.
+ */
+interface RecursionContext {
+  depth: number
+  blockExpressions: readonly RegExp[]
+  repeatingWordsAccuracy: number
+  orphanMatchThreshold: number
+  ignoreWhitespaceDifferences: boolean
+}
+
+/**
+ * Options for the `HtmlDiff.analyze` static helper.
+ *
+ * `useProjections` controls structural-tag normalisation:
+ *   - `undefined` → use the same heuristic as `build()` (per-call decision)
+ *   - `true` → force projection on (skipped if either side has no content)
+ *   - `false` → force projection off (diff runs on raw word arrays)
+ * Composers of multiple analyses (e.g. three-way diff) MUST pass the
+ * same explicit boolean to all calls so shared inputs tokenise
+ * identically across analyses.
+ *
+ * The remaining options mirror the per-instance fields on `HtmlDiff`
+ * itself — they exist on the options bag because `analyze` constructs
+ * the inner instance internally.
+ */
+export interface AnalyzeOptions {
+  useProjections?: boolean
+  blockExpressions?: readonly RegExp[]
+  repeatingWordsAccuracy?: number
+  orphanMatchThreshold?: number
+  ignoreWhitespaceDifferences?: boolean
+}
+
+export interface AnalyzeResult {
+  /** Word array the `operations` index into (projected or raw). */
+  readonly oldDiffWords: readonly string[]
+  readonly newDiffWords: readonly string[]
+  readonly operations: readonly Operation[]
+  /** Original WordSplitter output, before any projection. */
+  readonly oldOriginalWords: readonly string[]
+  readonly newOriginalWords: readonly string[]
+  /** Diff-index → original-word-index map; null when projections inactive. */
+  readonly oldContentToOriginal: readonly number[] | null
+  readonly newContentToOriginal: readonly number[] | null
+}
+
+/**
+ * Options for `HtmlDiff.executeThreeWay`. Same shape as `AnalyzeOptions`
+ * — the values flow unchanged into both internal `analyze` calls so V2's
+ * tokenisation stays symmetric. Aliased so future divergence in either
+ * direction lives in one place.
+ *
+ * `useProjections`: when undefined, `executeThreeWay` computes the
+ * decision as the conjunction of both pair-wise
+ * `evaluateProjectionApplicability` results.
+ */
+export type ThreeWayOptions = AnalyzeOptions
+
 export default class HtmlDiff {
   /**
    * This value defines balance between speed and memory utilization. The higher it is the faster it works and more memory consumes.
@@ -76,10 +141,26 @@ export default class HtmlDiff {
    */
   private static MaxTablePreprocessDepth = 8
 
+  /**
+   * Mirror cap for the three-way path. The 2-way `MaxTablePreprocessDepth`
+   * guards the recursion inside `executeWithContext`; the 3-way path has
+   * its own recursion (`executeThreeWay` → `preprocessTablesThreeWay` →
+   * `cellDiff` → `executeThreeWay`) which needs its own guard. Once the
+   * cap is reached, `executeThreeWay` skips table preprocessing and
+   * falls back to the word-level merge — same bail-out semantics as the
+   * 2-way path.
+   */
+  private static MaxThreeWayDepth = 8
+
   private content: string[] = []
   private newText: string
   private oldText: string
-  private readonly tablePreprocessDepth: number
+  // Written exactly once, by `executeWithContext` on the inner instance
+  // for a recursive cell-diff. Top-level instances stay at 0. Treated as
+  // effectively-readonly elsewhere — we dropped the modifier only so
+  // `executeWithContext` can populate it without needing a private
+  // constructor overload that would re-leak the parameter we just hid.
+  private tablePreprocessDepth = 0
 
   private specialTagDiffStack: string[] = []
   private newWords: string[] = []
@@ -147,18 +228,225 @@ export default class HtmlDiff {
    * Initializes a new instance of the class.
    * @param oldText The old text.
    * @param newText The new text.
-   * @param tablePreprocessDepth Internal: nested-call depth for table
-   *   preprocessing. Callers should leave at default (0); the recursive
-   *   `diffCell` callback in TableDiff bumps it.
    */
-  constructor(oldText: string, newText: string, tablePreprocessDepth = 0) {
+  constructor(oldText: string, newText: string) {
     this.oldText = oldText
     this.newText = newText
-    this.tablePreprocessDepth = tablePreprocessDepth
   }
 
-  static execute(oldText: string, newText: string, tablePreprocessDepth = 0) {
-    return new HtmlDiff(oldText, newText, tablePreprocessDepth).build()
+  static execute(oldText: string, newText: string): string {
+    return new HtmlDiff(oldText, newText).build()
+  }
+
+  /**
+   * Analyse a two-way diff and return its raw building blocks: the word
+   * arrays the diff ran against, the operations produced, the original
+   * (pre-projection) word arrays, and the mappings from diff-index back
+   * to original-word index when structural projection is active.
+   * Consumed by `executeThreeWay` so it can compose two diffs by walking
+   * their Operation streams.
+   *
+   * The caller is expected to coordinate `useProjections` symmetrically
+   * across composed analyses — if V1↔V2 projects but V2↔V3 doesn't,
+   * V2's "new" array in the first analysis won't equal V2's "old" array
+   * in the second. `evaluateProjectionApplicability` exposes the same
+   * heuristic `build()` uses internally, so the orchestrator can compute
+   * a single decision and pass it into every `analyze` call.
+   *
+   * Table preprocessing is skipped here. Placeholders mutate the input
+   * in ways that don't compose across two independent analyses; the
+   * 3-way orchestrator handles tables explicitly before calling analyze.
+   */
+  static analyze(oldText: string, newText: string, options: AnalyzeOptions = {}): AnalyzeResult {
+    const inner = new HtmlDiff(oldText, newText)
+    // Bypass table preprocessing — the caller handles tables.
+    inner.tablePreprocessDepth = HtmlDiff.MaxTablePreprocessDepth
+    if (options.blockExpressions) {
+      for (const expr of options.blockExpressions) inner.addBlockExpression(expr)
+    }
+    if (options.repeatingWordsAccuracy !== undefined) inner.repeatingWordsAccuracy = options.repeatingWordsAccuracy
+    if (options.orphanMatchThreshold !== undefined) inner.orphanMatchThreshold = options.orphanMatchThreshold
+    if (options.ignoreWhitespaceDifferences !== undefined) {
+      inner.ignoreWhitespaceDifferences = options.ignoreWhitespaceDifferences
+    }
+    inner.splitInputsToWords()
+    if (options.useProjections === undefined) {
+      // Mirror build()'s heuristic — same behaviour as a standalone 2-way diff.
+      inner.buildContentProjections()
+    } else if (options.useProjections) {
+      // Caller forced projections on. Still skip if either side has no
+      // structural content, since projecting an empty side produces an
+      // empty diff space and the merge degrades.
+      const oldProj = HtmlDiff.createContentProjection(inner.oldWords)
+      const newProj = HtmlDiff.createContentProjection(inner.newWords)
+      if (oldProj.contentWords.length > 0 && newProj.contentWords.length > 0) {
+        inner.oldContentWords = oldProj.contentWords
+        inner.oldContentToOriginal = oldProj.contentToOriginal
+        inner.newContentWords = newProj.contentWords
+        inner.newContentToOriginal = newProj.contentToOriginal
+      }
+    }
+    // useProjections === false: leave projections unset, diff runs on raw words.
+    const wordsForDiffOld = inner.oldContentWords ?? inner.oldWords
+    const wordsForDiffNew = inner.newContentWords ?? inner.newWords
+    inner.matchGranularity = Math.min(
+      HtmlDiff.MatchGranularityMaximum,
+      Math.min(wordsForDiffOld.length, wordsForDiffNew.length)
+    )
+    return {
+      oldDiffWords: wordsForDiffOld,
+      newDiffWords: wordsForDiffNew,
+      operations: inner.operations(),
+      oldOriginalWords: inner.oldWords,
+      newOriginalWords: inner.newWords,
+      oldContentToOriginal: inner.oldContentToOriginal,
+      newContentToOriginal: inner.newContentToOriginal,
+    }
+  }
+
+  /**
+   * Whether content-projection (structural-tag normalisation) would
+   * apply to this pair of inputs under `build()`'s default heuristic.
+   * Exposed so composers of multiple analyses can compute a symmetric
+   * decision before calling `analyze` — see `analyze`'s docstring for
+   * why symmetry matters.
+   */
+  static evaluateProjectionApplicability(oldText: string, newText: string): boolean {
+    const oldWords = WordSplitter.convertHtmlToListOfWords(oldText, [])
+    const newWords = WordSplitter.convertHtmlToListOfWords(newText, [])
+    if (!HtmlDiff.hasStructuralDifferences(oldWords, newWords)) return false
+    const oldProj = HtmlDiff.createContentProjection(oldWords)
+    const newProj = HtmlDiff.createContentProjection(newWords)
+    return HtmlDiff.shouldUseContentProjections(oldWords, newWords, oldProj, newProj)
+  }
+
+  /**
+   * Three-way HTML diff. Given V1 (the version Me last sent), V2 (the
+   * version CP sent back), and V3 (Me's current draft), produces a
+   * single attributed HTML output where CP's and Me's changes are
+   * distinguished by `data-author` ('cp' or 'me') and matching
+   * `class='diffins cp'` / `class='diffdel me'` etc. The "Me rejected
+   * CP's proposal" case (Me deleted text CP had inserted) gets a
+   * dedicated marker: `data-rejects='cp'` plus `class='... rejects-cp'`.
+   *
+   * Coordinates the symmetric-projection decision (D1) across both
+   * internal `analyze` calls so V2 tokenises identically on each side
+   * of the spine. When `useProjections` is left undefined, the decision
+   * is the conjunction of both pair-wise heuristics — project iff both
+   * pairs would project on their own. Pass an explicit boolean to
+   * override.
+   */
+  static executeThreeWay(v1: string, v2: string, v3: string, options: ThreeWayOptions = {}): string {
+    return HtmlDiff.executeThreeWayWithDepth(v1, v2, v3, options, 0)
+  }
+
+  private static executeThreeWayWithDepth(
+    v1: string,
+    v2: string,
+    v3: string,
+    options: ThreeWayOptions,
+    depth: number
+  ): string {
+    // Table preprocessing first — replaces each V1/V2/V3 table with a
+    // shared-nonce placeholder, then the word-level merge runs over the
+    // table-free inputs. Cells are diffed recursively via executeThreeWay
+    // so the cell content is itself three-way attributed. Restoration
+    // happens at the end.
+    //
+    // Depth-cap the recursion. Each level recurses cellDiff → executeThreeWay,
+    // which would otherwise run unbounded on adversarially-nested input.
+    // Beyond the cap, skip table preprocessing entirely and let the
+    // word-level merge handle the raw HTML — same bail-out semantics as
+    // the 2-way `MaxTablePreprocessDepth` cap.
+    const tablePreprocess =
+      depth < HtmlDiff.MaxThreeWayDepth
+        ? preprocessTablesThreeWay(v1, v2, v3, (c1, c2, c3) =>
+            HtmlDiff.executeThreeWayWithDepth(c1, c2, c3, options, depth + 1)
+          )
+        : null
+    const inV1 = tablePreprocess?.modifiedV1 ?? v1
+    const inV2 = tablePreprocess?.modifiedV2 ?? v2
+    const inV3 = tablePreprocess?.modifiedV3 ?? v3
+
+    const useProjections =
+      options.useProjections ??
+      (HtmlDiff.evaluateProjectionApplicability(inV1, inV2) && HtmlDiff.evaluateProjectionApplicability(inV2, inV3))
+
+    const analyzeOpts: AnalyzeOptions = {
+      useProjections,
+      blockExpressions: options.blockExpressions,
+      repeatingWordsAccuracy: options.repeatingWordsAccuracy,
+      orphanMatchThreshold: options.orphanMatchThreshold,
+      ignoreWhitespaceDifferences: options.ignoreWhitespaceDifferences,
+    }
+    const d1 = HtmlDiff.analyze(inV1, inV2, analyzeOpts)
+    const d2 = HtmlDiff.analyze(inV2, inV3, analyzeOpts)
+
+    // Spine sanity check. Symmetric `useProjections` should guarantee
+    // alignment, but if a bug ever lets these diverge we want to fail
+    // loudly rather than silently produce a misattributed output.
+    if (d1.newDiffWords.length !== d2.oldDiffWords.length) {
+      throw new Error(
+        'HtmlDiff.executeThreeWay: V2 tokenisation diverged across pair-wise analyses ' +
+          `(${d1.newDiffWords.length} vs ${d2.oldDiffWords.length}). ` +
+          'This indicates the symmetric-projection coordination has a bug.'
+      )
+    }
+
+    const segments = buildSegments(d1, d2)
+    const merged = HtmlDiff.emitSegments(segments)
+    return tablePreprocess ? restoreTablePlaceholders(merged, tablePreprocess.placeholderToDiff) : merged
+  }
+
+  /**
+   * Drives a fresh `HtmlDiff` instance through `insertTag` for ins/del
+   * segments and pushes equal segments straight to its `content`
+   * buffer. Reusing the instance keeps the formatting-tag stack
+   * (`specialTagDiffStack`) coherent across segments — a `<strong>`
+   * opened in one segment and closed in another stays balanced.
+   */
+  private static emitSegments(segments: Segment[]): string {
+    const emitter = new HtmlDiff('', '')
+    for (const seg of segments) {
+      if (seg.attr.kind === 'equal') {
+        emitter.content.push(seg.words.join(''))
+        continue
+      }
+      const { tag, baseClass, metadata } = segmentEmissionShape(seg.attr)
+      // insertTag mutates its `words` array; pass a copy.
+      emitter.insertTag(tag, baseClass, [...seg.words], metadata)
+    }
+    // Stack-balance invariant: every special-case opening tag pushed onto
+    // `specialTagDiffStack` during emission must have been matched by a
+    // closing tag. An unbalanced stack means the input had unbalanced
+    // formatting tags AND a Replace at an inconvenient position — the
+    // output would be silently malformed (half-closed `<ins>`). Fail
+    // loudly so the caller can investigate rather than ship broken HTML.
+    if (emitter.specialTagDiffStack.length > 0) {
+      throw new Error(
+        `HtmlDiff.executeThreeWay: emission left ${emitter.specialTagDiffStack.length} ` +
+          'unclosed formatting tag(s) on the stack — input may have unbalanced ' +
+          '<strong>/<em>/etc. or there is a bug in segment emission.'
+      )
+    }
+    return emitter.content.join('')
+  }
+
+  /**
+   * Internal entry point used by the table-cell recursion. Constructs an
+   * inner `HtmlDiff`, applies the caller's settings, and bumps the
+   * recursion depth — keeping the public constructor signature clean
+   * while still threading the configuration that's required for cell-
+   * level output to match the top-level call's behaviour.
+   */
+  private static executeWithContext(oldText: string, newText: string, ctx: RecursionContext): string {
+    const inner = new HtmlDiff(oldText, newText)
+    inner.tablePreprocessDepth = ctx.depth
+    for (const expr of ctx.blockExpressions) inner.addBlockExpression(expr)
+    inner.repeatingWordsAccuracy = ctx.repeatingWordsAccuracy
+    inner.orphanMatchThreshold = ctx.orphanMatchThreshold
+    inner.ignoreWhitespaceDifferences = ctx.ignoreWhitespaceDifferences
+    return inner.build()
   }
 
   /**
@@ -174,26 +462,26 @@ export default class HtmlDiff {
     // Table preprocessing: when both sides have matching `<table>` structures,
     // diff cells positionally so cross-cell content shifts produce one
     // independent del/ins per cell rather than cell-misaligned output.
-    // Recursion guarded by MaxTablePreprocessDepth to bound work on
-    // deeply-nested table-in-cell-in-table inputs. Caller-configured
-    // settings (block expressions, accuracy thresholds) are propagated to
-    // the recursive cell diff so cell-level output is consistent with the
-    // top-level configuration.
-    const blockExpressions = this.blockExpressions
-    const repeatingWordsAccuracy = this.repeatingWordsAccuracy
-    const orphanMatchThreshold = this.orphanMatchThreshold
-    const ignoreWhitespaceDifferences = this.ignoreWhitespaceDifferences
-    const tablePreprocess =
-      this.tablePreprocessDepth >= HtmlDiff.MaxTablePreprocessDepth
-        ? null
-        : preprocessTables(this.oldText, this.newText, (oldCell, newCell) => {
-            const inner = new HtmlDiff(oldCell, newCell, this.tablePreprocessDepth + 1)
-            for (const expr of blockExpressions) inner.addBlockExpression(expr)
-            inner.repeatingWordsAccuracy = repeatingWordsAccuracy
-            inner.orphanMatchThreshold = orphanMatchThreshold
-            inner.ignoreWhitespaceDifferences = ignoreWhitespaceDifferences
-            return inner.build()
-          })
+    // Recursion is guarded by MaxTablePreprocessDepth — check the cap
+    // first so we don't construct a context that will never be used.
+    let tablePreprocess: ReturnType<typeof preprocessTables> = null
+    if (this.tablePreprocessDepth < HtmlDiff.MaxTablePreprocessDepth) {
+      // Caller-configured settings (block expressions, accuracy
+      // thresholds) flow to the recursive cell diff via `RecursionContext`
+      // so cell-level output is consistent with the top-level
+      // configuration. The context is built once here and reused for
+      // every cell-diff callback invocation.
+      const ctx: RecursionContext = {
+        depth: this.tablePreprocessDepth + 1,
+        blockExpressions: this.blockExpressions,
+        repeatingWordsAccuracy: this.repeatingWordsAccuracy,
+        orphanMatchThreshold: this.orphanMatchThreshold,
+        ignoreWhitespaceDifferences: this.ignoreWhitespaceDifferences,
+      }
+      tablePreprocess = preprocessTables(this.oldText, this.newText, (oldCell, newCell) =>
+        HtmlDiff.executeWithContext(oldCell, newCell, ctx)
+      )
+    }
     if (tablePreprocess) {
       this.oldText = tablePreprocess.modifiedOld
       this.newText = tablePreprocess.modifiedNew
@@ -491,7 +779,7 @@ export default class HtmlDiff {
    * @param words
    * @private
    */
-  private insertTag(tag: string, cssClass: string, words: string[]) {
+  private insertTag(tag: string, cssClass: string, words: string[], metadata?: WrapMetadata) {
     while (true) {
       if (words.length === 0) {
         break
@@ -499,7 +787,7 @@ export default class HtmlDiff {
 
       const allWordsUntilFirstTag = this.extractConsecutiveWords(words, x => !Utils.isTag(x))
       if (allWordsUntilFirstTag.length > 0) {
-        const text = Utils.wrapText(allWordsUntilFirstTag.join(''), tag, cssClass)
+        const text = Utils.wrapText(allWordsUntilFirstTag.join(''), tag, cssClass, metadata)
         this.content.push(text)
       }
 
@@ -533,7 +821,9 @@ export default class HtmlDiff {
         const styledTagNames = Array.from(tagNames).join(' ')
 
         this.specialTagDiffStack.push(words[0])
-        specialCaseTagInjection = `<ins class='mod ${styledTagNames}'>`
+        // Carry the caller's metadata into the formatting-tag wrapper so
+        // a 3-way author tag survives a `<strong>`/`<em>` content edit.
+        specialCaseTagInjection = `<ins${Utils.composeTagAttributes(`mod ${styledTagNames}`, metadata ?? {})}>`
         if (tag === HtmlDiff.DelTag) {
           words.shift()
 
@@ -608,7 +898,7 @@ export default class HtmlDiff {
       if (words.length === 0) continue
 
       // if there are still words left, they must start with a nonTag and need to be handled in the next iteration.
-      this.insertTag(tag, cssClass, words)
+      this.insertTag(tag, cssClass, words, metadata)
       break
     }
   }

package/src/HtmlScanner.ts

@@ -0,0 +1,200 @@
+/**
+ * Low-level HTML tag-parsing primitives shared by the table-aware
+ * preprocessing and (potentially) other consumers. These are deliberately
+ * generic over the document type — no table-specific assumptions live
+ * here.
+ *
+ * The goal is to walk HTML at the tag boundary level *without* parsing
+ * into a full DOM, so we stay fast and never round-trip through
+ * htmlparser2/DOMPurify in the diff hot path.
+ */
+
+export interface OpeningTag {
+  /** Index just past the closing `>` of the opening tag. */
+  end: number
+}
+
+export interface ClassAttributeLocation {
+  /** Index of the value's first character (inside the surrounding quotes). */
+  valueStart: number
+  /** Index just past the last character of the value (still inside quotes). */
+  valueEnd: number
+  /** The class attribute's value, with surrounding quotes stripped. */
+  value: string
+}
+
+/**
+ * Parses the opening tag (or comment/CDATA/PI) starting at `i`. Returns
+ * the index just past the closing delimiter, or null if the tag is
+ * malformed (unterminated). HTML comments, CDATA, processing
+ * instructions, and DOCTYPE need their own terminators — a plain
+ * `>`-walker would cut a comment like `<!-- a > b -->` at the first
+ * inner `>`, treating the rest as text and corrupting downstream
+ * offsets. Word-exported HTML routinely emits comments inside tables
+ * (conditional comments, OLE markers) so these have to be handled.
+ */
+export function parseOpeningTagAt(html: string, i: number): OpeningTag | null {
+  if (html.startsWith('<!--', i)) {
+    const close = html.indexOf('-->', i + 4)
+    return close === -1 ? null : { end: close + 3 }
+  }
+  if (html.startsWith('<![CDATA[', i)) {
+    const close = html.indexOf(']]>', i + 9)
+    return close === -1 ? null : { end: close + 3 }
+  }
+  if (html.startsWith('<?', i)) {
+    const close = html.indexOf('?>', i + 2)
+    return close === -1 ? null : { end: close + 2 }
+  }
+  // Walk to the next unquoted '>'. Handles attributes whose values contain
+  // a literal '>' inside quotes, which a plain indexOf would mishandle.
+  let j = i + 1
+  let quote: string | null = null
+  while (j < html.length) {
+    const ch = html[j]
+    if (quote) {
+      if (ch === quote) quote = null
+    } else if (ch === '"' || ch === "'") {
+      quote = ch
+    } else if (ch === '>') {
+      return { end: j + 1 }
+    }
+    j++
+  }
+  return null
+}
+
+export function matchesTagAt(html: string, i: number, tagName: string): boolean {
+  if (html[i] !== '<') return false
+  const candidate = html.slice(i + 1, i + 1 + tagName.length).toLowerCase()
+  if (candidate !== tagName) return false
+  const after = html[i + 1 + tagName.length]
+  return after === '>' || after === ' ' || after === '\t' || after === '\n' || after === '\r' || after === '/'
+}
+
+export function matchesClosingTagAt(html: string, i: number, tagName: string): boolean {
+  if (html[i] !== '<' || html[i + 1] !== '/') return false
+  const candidate = html.slice(i + 2, i + 2 + tagName.length).toLowerCase()
+  if (candidate !== tagName) return false
+  const after = html[i + 2 + tagName.length]
+  return after === '>' || after === ' ' || after === '\t' || after === '\n' || after === '\r'
+}
+
+/**
+ * Returns the index just past the matching `</tagName>`, accounting for
+ * nested tags of the same name. Returns -1 if no match before `limit`.
+ */
+export function findMatchingClosingTag(
+  html: string,
+  from: number,
+  tagName: string,
+  limit: number = html.length
+): number {
+  let depth = 1
+  let i = from
+  while (i < limit) {
+    if (matchesTagAt(html, i, tagName)) {
+      const opening = parseOpeningTagAt(html, i)
+      if (!opening) {
+        i++
+        continue
+      }
+      const tagText = html.slice(i, opening.end)
+      if (!tagText.endsWith('/>')) depth++
+      i = opening.end
+    } else if (matchesClosingTagAt(html, i, tagName)) {
+      depth--
+      const closing = parseOpeningTagAt(html, i)
+      const closingEnd = closing?.end ?? i + `</${tagName}>`.length
+      if (depth === 0) return closingEnd
+      i = closingEnd
+    } else {
+      i++
+    }
+  }
+  return -1
+}
+
+/**
+ * Returns the opening tag with the given class injected. Locates the real
+ * `class` attribute via attribute-aware walking (NOT a flat regex — that
+ * would mis-match inside a foreign attribute value like
+ * `title="see class='x'"`). When the class already partially overlaps with
+ * `cls` — e.g. existing `class="mod"` and we're injecting `mod colspan` —
+ * only the missing tokens get appended, so we never end up with
+ * `class="mod mod colspan"`.
+ */
+export function injectClass(openingTag: string, cls: string): string {
+  const clsTokens = cls.split(/\s+/).filter(Boolean)
+  if (clsTokens.length === 0) return openingTag
+
+  const classAttr = findClassAttribute(openingTag)
+  if (classAttr) {
+    const existingTokens = classAttr.value.split(/\s+/).filter(Boolean)
+    const missing = clsTokens.filter(t => !existingTokens.includes(t))
+    if (missing.length === 0) return openingTag
+    const updatedValue =
+      existingTokens.length === 0 ? missing.join(' ') : `${existingTokens.join(' ')} ${missing.join(' ')}`
+    return openingTag.slice(0, classAttr.valueStart) + updatedValue + openingTag.slice(classAttr.valueEnd)
+  }
+
+  const isSelfClosing = openingTag.endsWith('/>')
+  const insertAt = isSelfClosing ? openingTag.length - 2 : openingTag.length - 1
+  return `${openingTag.slice(0, insertAt).replace(/\s*$/, '')} class='${cls}'${openingTag.slice(insertAt)}`
+}
+
+/**
+ * Walks the opening tag's attributes (respecting quoted values) to find
+ * the actual `class` attribute. Returns the value range (start/end of the
+ * value content, *excluding* the surrounding quotes) and the value, or
+ * null if no `class` attribute is present.
+ */
+export function findClassAttribute(openingTag: string): ClassAttributeLocation | null {
+  // Skip past the tag name. Tag starts with `<`; first run of [A-Za-z0-9-]
+  // is the tag name. Anything after is attribute territory.
+  let i = 1
+  while (i < openingTag.length && /[A-Za-z0-9_:-]/.test(openingTag[i])) i++
+
+  while (i < openingTag.length) {
+    // Skip whitespace
+    while (i < openingTag.length && /\s/.test(openingTag[i])) i++
+    if (i >= openingTag.length) break
+    if (openingTag[i] === '>' || openingTag[i] === '/') break
+
+    // Read attribute name
+    const nameStart = i
+    while (i < openingTag.length && !/[\s=>/]/.test(openingTag[i])) i++
+    const name = openingTag.slice(nameStart, i)
+
+    // Optional whitespace + '=' + optional whitespace + value
+    while (i < openingTag.length && /\s/.test(openingTag[i])) i++
+    if (openingTag[i] !== '=') {
+      // Bare attribute (no value) — not class
+      continue
+    }
+    i++ // past '='
+    while (i < openingTag.length && /\s/.test(openingTag[i])) i++
+
+    // Value: quoted or unquoted
+    let valueStart: number
+    let valueEnd: number
+    if (openingTag[i] === '"' || openingTag[i] === "'") {
+      const quote = openingTag[i]
+      i++
+      valueStart = i
+      while (i < openingTag.length && openingTag[i] !== quote) i++
+      valueEnd = i
+      if (i < openingTag.length) i++ // past closing quote
+    } else {
+      valueStart = i
+      while (i < openingTag.length && !/[\s>/]/.test(openingTag[i])) i++
+      valueEnd = i
+    }
+
+    if (name.toLowerCase() === 'class') {
+      return { valueStart, valueEnd, value: openingTag.slice(valueStart, valueEnd) }
+    }
+  }
+
+  return null
+}