dsh-smooth-stream 0.6.1 → 0.7.0

package/src/client/useLogarithmicFade.ts

@@ -1,4 +1,5 @@
 import { useLayoutEffect, useRef, type RefObject } from 'react'
+import { FrameCoordinator } from './FrameCoordinator.ts'
 import css from './LogarithmicFade.module.css'
 
 export const FADE_DURATION_MS = 240
@@ -11,6 +12,15 @@ const COLOR_PROPERTY = '--dsh-smooth-stream-fade-color'
 // Lightning CSS scopes highlight identifiers as well as class names.
 const highlightName = (index: number): string => css[`${PREFIX}${index}`] ?? `${PREFIX}${index}`
 const EXCLUDED = 'pre,code,math,.katex,.katex-display,mjx-container,svg,script,style,textarea,input,button,select,[role="button"],[contenteditable],[hidden],[aria-hidden="true"],[aria-live]'
+// Attributes that can start or stop an EXCLUDED match mid-stream (`hidden` and
+// `aria-hidden` flip whole subtrees, `class` carries the math renderers,
+// `role`/`contenteditable` match their own selectors). `style` is deliberately
+// absent: every colour write below is a style property, so observing it would
+// make the fade re-enter its own observer.
+const EXCLUDED_ATTRIBUTES = ['hidden', 'aria-hidden', 'role', 'contenteditable', 'class']
+// Attributes on <html>/<body> that can move the resolved `currentColor`, i.e.
+// an app theme switch that is not delivered through the media query.
+const APPEARANCE_ATTRIBUTES = ['class', 'style', 'data-theme', 'data-color-scheme', 'data-appearance']
 
 export function logarithmicOpacity(progress: number): number {
   const p = Number.isFinite(progress) ? Math.max(0, Math.min(1, progress)) : 1
@@ -31,29 +41,130 @@ interface FadeCharacter {
   bucket: number
 }
 
+/** One text node of the fade root with its span in the concatenated source text. */
+interface TextNodeEntry {
+  node: Text
+  start: number
+  end: number
+  eligible: boolean
+}
+
+interface PreservedColor {
+  value: string
+  priority: string
+  /** Reconcile pass that last wanted this element, so stale entries can be pruned. */
+  generation: number
+}
+
 interface Scheduler {
   highlights: Highlight[]
   clients: Set<LogarithmicFadeController>
   pending: Set<LogarithmicFadeController>
-  frame: number
+  /** Task handle on the shared frame clock; non-null while a client is live. */
+  taskId: string | null
   registry: HighlightRegistry
   window: Window
+  coordinator: FrameCoordinator
+  /** Detaches the document-level appearance watcher when the last client goes. */
+  unwatchAppearance: () => void
 }
 
 const schedulers = new WeakMap<Document, Scheduler>()
 const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' })
 
+/**
+ * Hot-path counters for the streaming benchmark. Increments only — this is the
+ * evidence that the per-frame pass count collapsed, not a control input.
+ */
+export const fadeHotPathStats = {
+  /** Observer batches that reached reconcile(). */
+  reconcileCalls: 0,
+  /** Reconciles that did real work (the rest are dirty-check no-ops). */
+  reconcilePasses: 0,
+  /** Full text-node table rebuilds (structural DOM change). */
+  nodeScans: 0,
+  /** Forced style resolutions for newly faded elements. */
+  styleReads: 0,
+}
+
+export function resetFadeHotPathStats(): void {
+  fadeHotPathStats.reconcileCalls = 0
+  fadeHotPathStats.reconcilePasses = 0
+  fadeHotPathStats.nodeScans = 0
+  fadeHotPathStats.styleReads = 0
+}
+
 function schedule(scheduler: Scheduler): void {
-  if (scheduler.frame !== 0 || scheduler.pending.size === 0) return
-  scheduler.frame = scheduler.window.requestAnimationFrame((now) => {
-    scheduler.frame = 0
-    for (const client of scheduler.pending) {
-      if (!client.paint(now)) scheduler.pending.delete(client)
-    }
-    schedule(scheduler)
+  if (scheduler.taskId !== null || scheduler.pending.size === 0) return
+  // One fade task per document on the shared clock, so the fade's bucket
+  // bookkeeping shares the reveal/follow frame instead of racing it.
+  scheduler.taskId = scheduler.coordinator.registerTask({
+    onSimulate: (_dtMs, now) => {
+      for (const client of scheduler.pending) {
+        if (!client.paint(now)) scheduler.pending.delete(client)
+      }
+      if (scheduler.pending.size === 0) {
+        scheduler.taskId = null
+        return false
+      }
+      return true
+    },
   })
 }
 
+/**
+ * Whether an attribute record actually moved the attribute's value. jsdom (and
+ * some engines) report a write even when the serialized value is unchanged, and
+ * this controller writes the scope class on every enable/disable transition —
+ * counting a no-op record as a DOM change would re-enter the observer forever.
+ * Requires `attributeOldValue` on the observing call.
+ * @param record - attribute mutation record from either observer.
+ * @returns true only when the value differs from the recorded old value.
+ */
+function attributeChanged(record: MutationRecord): boolean {
+  const attribute = record.attributeName
+  if (attribute === null) return true
+  return record.oldValue !== (record.target as Element).getAttribute(attribute)
+}
+
+/**
+ * One appearance watcher per document. A theme switch arrives either as an OS
+ * media-query flip (the app's default `preference: system`) or as an attribute
+ * write on <html>/<body>, so both are observed; the fade only ever writes
+ * custom properties on its own root, never on those elements, so this watcher
+ * cannot observe the controller's own output.
+ * @param scheduler - document-scoped registry notified when the look changes.
+ * @returns teardown for the last client's dispose.
+ */
+function watchAppearance(scheduler: Scheduler): () => void {
+  // The scheduler already resolved the root's realm; re-state it so the DOM
+  // constructors resolve off that window rather than the ambient global.
+  const win = scheduler.window as Window & typeof globalThis
+  const doc = win.document
+  const invalidate = (): void => {
+    for (const client of scheduler.clients) client.invalidateColors()
+  }
+  const observer = new win.MutationObserver((records) => {
+    if (records.some(attributeChanged)) invalidate()
+  })
+  const watched = doc.body === null ? [doc.documentElement] : [doc.documentElement, doc.body]
+  for (const element of watched) {
+    observer.observe(element, {
+      attributes: true,
+      attributeFilter: APPEARANCE_ATTRIBUTES,
+      attributeOldValue: true,
+    })
+  }
+  const query = typeof win.matchMedia === 'function'
+    ? win.matchMedia('(prefers-color-scheme: dark)')
+    : null
+  if (query !== null) query.addEventListener('change', invalidate)
+  return () => {
+    observer.disconnect()
+    query?.removeEventListener('change', invalidate)
+  }
+}
+
 function schedulerFor(root: HTMLElement): Scheduler | null {
   const doc = root.ownerDocument
   const win = doc.defaultView
@@ -70,32 +181,78 @@ function schedulerFor(root: HTMLElement): Scheduler | null {
       highlights,
       clients: new Set(),
       pending: new Set(),
-      frame: 0,
+      taskId: null,
       registry: realm.CSS.highlights,
       window: win,
+      coordinator: FrameCoordinator.forDocument(doc),
+      unwatchAppearance: () => {},
     }
+    scheduler.unwatchAppearance = watchAppearance(scheduler)
     schedulers.set(doc, scheduler)
   }
   return scheduler
 }
 
-/** Owns ranges only: React retains ownership of every element and Text node. */
+/**
+ * Owns ranges only: React retains ownership of every element and Text node.
+ *
+ * The controller used to re-derive its whole view of the subtree (textContent,
+ * prefix walk, full TreeWalker, an O(tail x #nodes) filter) on *every* commit
+ * AND on every observer batch for that same commit. It now keeps an
+ * incremental text-node table, reconciles at most once per observed DOM
+ * change, and preserves the per-element colour memo across passes.
+ */
 export class LogarithmicFadeController {
   private previous = ''
   private characters: FadeCharacter[] = []
-  private colors = new Map<HTMLElement, { value: string, priority: string }>()
+  private colors = new Map<HTMLElement, PreservedColor>()
   private enabled = false
   private active = false
   private speedCps = 100
   private pausedAt: number | null = null
   private disposed = false
   private readonly observer: MutationObserver
+  /** Text nodes of the root with their source offsets; survives data-only edits. */
+  private nodes: TextNodeEntry[] = []
+  /** Ineligible nodes in nodes[0..index): a span is fadeable when its bounds match. */
+  private ineligiblePrefix: number[] = [0]
+  /**
+   * `closest(EXCLUDED)` derived once per element instead of once per Text node:
+   * exclusion is inherited from the ancestor chain, so a memo stays usable only
+   * while the element keeps its own parent. Moving a subtree into `code` — or
+   * into anything else that matches — invalidates exactly the moved chain the
+   * next time it is read.
+   */
+  private excludedElements = new WeakMap<Element, { parent: Element | null, excluded: boolean }>()
+  /** Own tag/attribute match per element; dropped when an exclusion attribute moves. */
+  private ownExcluded = new WeakMap<Element, boolean>()
+  /** Bumped by every observed mutation; reconcile() no-ops while it does not move. */
+  private domRevision = 0
+  /** Bumped only by structural (childList) mutations; the node table is rebuilt then. */
+  private structureRevision = 0
+  private scannedStructureRevision = -1
+  private reconciledRevision = -1
+  private reconciledEnabled = false
+  private reconciledActive = false
+  private reconciledPaused = false
+  private reconciledTailSize = 0
+  private colorGeneration = 0
 
   private constructor(private readonly root: HTMLElement, private readonly scheduler: Scheduler) {
     scheduler.clients.add(this)
     const win = root.ownerDocument.defaultView as Window & typeof globalThis
-    this.observer = new win.MutationObserver(() => { this.reconcile() })
-    this.observer.observe(root, { subtree: true, childList: true, characterData: true })
+    // The observer is the single invalidation source. It watches structure,
+    // text and only the exclusion-relevant attributes; every colour write below
+    // is a `style` property, which stays unobserved, so it cannot re-enter.
+    this.observer = new win.MutationObserver((records) => { this.onDomMutation(records) })
+    this.observer.observe(root, {
+      subtree: true,
+      childList: true,
+      characterData: true,
+      attributes: true,
+      attributeFilter: EXCLUDED_ATTRIBUTES,
+      attributeOldValue: true,
+    })
   }
 
   static create(root: HTMLElement): LogarithmicFadeController | null {
@@ -117,90 +274,292 @@ export class LogarithmicFadeController {
     this.reconcile()
   }
 
+  /** Invalidate and reconcile from one observer batch (one batch per commit). */
+  private onDomMutation(records: MutationRecord[]): void {
+    let changed = false
+    let exclusionAttributesMoved = false
+    for (const record of records) {
+      if (record.type === 'childList') {
+        this.structureRevision += 1
+        changed = true
+        continue
+      }
+      if (record.type === 'characterData') {
+        changed = true
+        continue
+      }
+      // Only EXCLUDED_ATTRIBUTES reach this branch, and only value changes
+      // count: this controller writes its own scope class below, which must not
+      // be mistaken for a DOM change (it re-renders the same token list).
+      if (!attributeChanged(record)) continue
+      exclusionAttributesMoved = true
+      changed = true
+    }
+    // A batch made only of this controller's own no-op writes is not a DOM
+    // change. Reconciling on it would re-add the scope class, whose record is
+    // another such batch, and the observer would re-enter itself forever.
+    if (!changed) return
+    if (exclusionAttributesMoved) {
+      // `hidden`/`aria-hidden`/`class` on an ancestor decides the eligibility of
+      // every descendant Text node, so the whole memo is stale — not just the
+      // mutation target — and the next pass has to re-derive the table.
+      this.excludedElements = new WeakMap()
+      this.ownExcluded = new WeakMap()
+      this.structureRevision += 1
+    }
+    this.domRevision += 1
+    this.reconcile()
+  }
+
+  /**
+   * Whether this element matches a SKIP rule itself or inherits one from an
+   * ancestor — the memoised form of `element.closest(EXCLUDED) !== null`.
+   * Memoised per element and revalidated through the parent chain, so a node
+   * that moves into `code` — or whose ancestor does — is re-decided without
+   * paying the selector walk once per Text node per pass.
+   * @param element - element owning the Text node being classified.
+   * @returns true when text under this element must stay out of the fade.
+   */
+  private elementExcluded(element: Element): boolean {
+    const cached = this.excludedElements.get(element)
+    if (cached !== undefined && cached.parent === element.parentElement) return cached.excluded
+    const parent = element.parentElement
+    const inherited = parent === null ? false : this.elementExcluded(parent)
+    let own = this.ownExcluded.get(element)
+    if (own === undefined) {
+      own = element.matches(EXCLUDED)
+      this.ownExcluded.set(element, own)
+    }
+    const excluded = inherited || own
+    this.excludedElements.set(element, { parent, excluded })
+    return excluded
+  }
+
+  /** Rebuild the text-node table after a structural change. */
+  private scanNodes(): void {
+    const nodes: TextNodeEntry[] = []
+    const walker = this.root.ownerDocument.createTreeWalker(this.root, NodeFilter.SHOW_TEXT)
+    for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+      const text = node as Text
+      const parent = text.parentElement
+      // Derived through the parent element, never cached on Text identity: a
+      // node that was moved keeps its identity, so a Text-keyed memo would keep
+      // answering for the tree it used to live in.
+      const eligible = parent !== null && !this.elementExcluded(parent)
+      nodes.push({ node: text, start: 0, end: 0, eligible })
+    }
+    this.nodes = nodes
+    this.scannedStructureRevision = this.structureRevision
+    fadeHotPathStats.nodeScans += 1
+  }
+
+  /**
+   * Re-derive the source text, the per-node spans and the eligibility prefix
+   * sums from the cached table. No DOM read, no selector match, no allocation
+   * beyond the string itself.
+   */
+  private readText(): string {
+    if (this.scannedStructureRevision !== this.structureRevision) this.scanNodes()
+    // The commit-driven pass runs before the observer microtask for the same
+    // commit, so a replaced text node can still be in the table. A removed
+    // node keeps its data, which would silently hand a detached node to the
+    // Range and colour code, so re-scan on the first eviction.
+    for (const entry of this.nodes) {
+      if (entry.node.parentNode !== null) continue
+      this.scanNodes()
+      break
+    }
+    const nodes = this.nodes
+    const prefix = this.ineligiblePrefix
+    if (prefix.length < nodes.length + 1) prefix.length = nodes.length + 1
+    prefix[0] = 0
+    let text = ''
+    let offset = 0
+    for (let index = 0; index < nodes.length; index += 1) {
+      const entry = nodes[index]!
+      const data = entry.node.data
+      entry.start = offset
+      offset += data.length
+      entry.end = offset
+      text += data
+      prefix[index + 1] = prefix[index]! + (entry.eligible ? 0 : 1)
+    }
+    prefix.length = nodes.length + 1
+    this.ineligiblePrefix = prefix
+    return text
+  }
+
+  /** First cached node whose span ends after `offset` (binary search). */
+  private firstNodeEndingAfter(offset: number): number {
+    const nodes = this.nodes
+    let low = 0
+    let high = nodes.length
+    while (low < high) {
+      const mid = (low + high) >> 1
+      if (nodes[mid]!.end > offset) high = mid
+      else low = mid + 1
+    }
+    return low
+  }
+
+  /** Last cached node whose span starts before `offset` (binary search). */
+  private lastNodeStartingBefore(offset: number): number {
+    const nodes = this.nodes
+    let low = -1
+    let high = nodes.length - 1
+    while (low < high) {
+      const mid = (low + high + 1) >> 1
+      if (nodes[mid]!.start < offset) low = mid
+      else high = mid - 1
+    }
+    return low
+  }
+
   private clearRanges(): void {
     for (const character of this.characters) {
       this.scheduler.highlights[character.bucket]?.delete(character.range)
     }
     this.characters = []
-    this.restoreColors()
+  }
+
+  private restoreColor(element: HTMLElement, preserved: PreservedColor): void {
+    if (preserved.value === '') element.style.removeProperty(COLOR_PROPERTY)
+    else element.style.setProperty(COLOR_PROPERTY, preserved.value, preserved.priority)
+  }
+
+  private rootColorSet = false
+
+  private ensureRootColor(): void {
+    if (this.rootColorSet) return
+    const win = this.scheduler.window
+    const color = win.getComputedStyle(this.root).color || 'currentColor'
+    this.root.style.setProperty(COLOR_PROPERTY, color)
+    this.rootColorSet = true
   }
 
   private restoreColors(): void {
-    for (const [element, original] of this.colors) {
-      if (original.value === '') element.style.removeProperty(COLOR_PROPERTY)
-      else element.style.setProperty(COLOR_PROPERTY, original.value, original.priority)
+    if (this.rootColorSet) {
+      this.root.style.removeProperty(COLOR_PROPERTY)
+      this.rootColorSet = false
     }
+    for (const [element, preserved] of this.colors) this.restoreColor(element, preserved)
     this.colors.clear()
   }
 
-  private preserveColor(element: HTMLElement): void {
-    if (this.colors.has(element)) return
-    const color = this.scheduler.window.getComputedStyle(element).color
-    this.colors.set(element, {
-      value: element.style.getPropertyValue(COLOR_PROPERTY),
-      priority: element.style.getPropertyPriority(COLOR_PROPERTY),
-    })
-    // An explicit source color prevents highlight inheritance from multiplying
-    // alpha through nested Markdown elements (root → paragraph → strong).
-    element.style.setProperty(COLOR_PROPERTY, color)
+  /**
+   * The document's appearance moved (theme switch, restyle): the captured ink
+   * colour is stale, so drop it and let the next pass read the new one. Costs
+   * nothing while no colour is captured, which is the common case — the read
+   * still happens only when text is actually fading.
+   */
+  invalidateColors(): void {
+    if (this.disposed || (!this.rootColorSet && this.colors.size === 0)) return
+    this.restoreColors()
+    // Force the next reconcile past its dirty check; it re-reads the colour and
+    // re-cuts the live tail, so the characters already fading recolour in place
+    // instead of finishing in the previous theme's ink.
+    this.domRevision += 1
+    this.reconcile()
   }
 
+
+  /**
+   * Refresh the fade ranges. Two triggers used to run this 2-3x per frame with
+   * no dirty check: the commit-driven `update()` and the observer batch for the
+   * very same DOM write. Both converge here, and the pass is skipped unless the
+   * DOM revision, the gate, the fade window or the pause state actually moved.
+   */
   private reconcile(): void {
     if (this.disposed) return
-    const text = this.root.textContent ?? ''
+    fadeHotPathStats.reconcileCalls += 1
+    const tailSize = fadeTailSize(this.speedCps)
+    const paused = this.pausedAt !== null
+    const domChanged = this.domRevision !== this.reconciledRevision
+    // The window only matters while characters are still fading: an idle
+    // controller has nothing to re-cut, and the next append reconciles anyway.
+    const paramsChanged = this.enabled !== this.reconciledEnabled
+      || this.active !== this.reconciledActive
+      || paused !== this.reconciledPaused
+      || (tailSize !== this.reconciledTailSize && this.characters.length > 0)
+    if (!domChanged && !paramsChanged) return
+    fadeHotPathStats.reconcilePasses += 1
+    this.reconciledRevision = this.domRevision
+    this.reconciledEnabled = this.enabled
+    this.reconciledActive = this.active
+    this.reconciledPaused = paused
+    this.reconciledTailSize = tailSize
+
+    const text = this.readText()
     const previous = this.previous
     this.previous = text
     const old = this.characters
     this.clearRanges()
     if (!this.enabled) {
       this.root.classList.remove(css.scope!)
+      this.restoreColors()
       this.scheduler.pending.delete(this)
       this.stopIfIdle()
       return
     }
     this.root.classList.add(css.scope!)
+    this.ensureRootColor()
     const now = this.pausedAt ?? this.scheduler.window.performance.now()
-    // A parser rewrite must not replay already readable content. Retain only
-    // the unchanged prefix; future appends resume the effect normally.
-    let prefix = 0
-    while (prefix < previous.length && prefix < text.length && previous[prefix] === text[prefix]) prefix += 1
     const appended = text.startsWith(previous)
-    const nodes: { node: Text, start: number, end: number, eligible: boolean }[] = []
-    const walker = this.root.ownerDocument.createTreeWalker(this.root, NodeFilter.SHOW_TEXT)
-    let offset = 0
-    for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
-      const end = offset + (node.textContent?.length ?? 0)
-      nodes.push({ node: node as Text, start: offset, end, eligible: node.parentElement?.closest(EXCLUDED) === null })
-      offset = end
+    let prefix = appended ? previous.length : 0
+    if (!appended) {
+      while (prefix < previous.length && prefix < text.length && previous[prefix] === text[prefix]) prefix += 1
     }
-    // containing() walks backwards by grapheme without segmenting the entire
-    // answer into an array. Offsets still refer to the original DOM text.
-    const segments = segmenter.segment(text)
+    const nodes = this.nodes
+    const ineligible = this.ineligiblePrefix
     // Keep existing characters alive when the engine resets its speed during
     // completion. A shrinking window must not abruptly darken the old tail.
-    const tailSize = fadeTailSize(this.speedCps)
     const oldestLiveStart = old.reduce((start, character) => (
       now - character.born < FADE_DURATION_MS && character.end <= prefix
         ? Math.min(start, character.start)
         : start
     ), Infinity)
+    const retainedBySpan = new Map<string, FadeCharacter>()
+    for (const character of old) retainedBySpan.set(`${String(character.start)}:${String(character.end)}`, character)
+    this.colorGeneration += 1
+
+    // Windowed segmentation: fade only affects the active tail. Windowing to the
+    // safe boundary keeps Intl.Segmenter at O(1) constant time (<0.1ms) even for
+    // long texts with tens of thousands of characters.
+    const windowStart = Math.max(
+      0,
+      Math.min(
+        text.length - FADE_MAX_TAIL_SIZE * 2,
+        oldestLiveStart < Infinity ? oldestLiveStart : text.length,
+      ),
+    )
+    const tailText = windowStart > 0 ? text.slice(windowStart) : text
+    const segments = segmenter.segment(tailText)
+
     let end = text.length
     for (let count = 0; count < FADE_MAX_TAIL_SIZE && end > 0 && (count < tailSize || end > oldestLiveStart); count += 1) {
-      const segment = segments.containing(end - 1)
+      const localEnd = end - windowStart
+      if (localEnd <= 0) break
+      const segment = segments.containing(localEnd - 1)
       if (segment === undefined) break
-      const start = segment.index
-      const parts = nodes.filter(node => node.end > start && node.start < end)
-      const retained = old.find(character => character.start === start && character.end === end && end <= prefix)
+      const start = segment.index + windowStart
+      const retained = end <= prefix
+        ? retainedBySpan.get(`${String(start)}:${String(end)}`)
+        : undefined
       const born = retained?.born ?? (this.active && appended && start >= previous.length ? now : null)
-      if (born !== null && now - born < FADE_DURATION_MS && segment.segment.trim() !== ''
-        && parts.length > 0 && parts.every(part => part.eligible)) {
-        const first = parts[0]!
-        const last = parts[parts.length - 1]!
-        const range = this.root.ownerDocument.createRange()
-        range.setStart(first.node, start - first.start)
-        range.setEnd(last.node, end - last.start)
-        for (const part of parts) this.preserveColor(part.node.parentElement!)
-        this.characters.push({ start, end, born, range, bucket: -1 })
+      if (born !== null && now - born < FADE_DURATION_MS && segment.segment.trim() !== '') {
+        // One binary-searched node span replaces the former O(tail x #nodes)
+        // filter; the prefix sums answer "is every part eligible" in O(1).
+        const first = this.firstNodeEndingAfter(start)
+        const last = this.lastNodeStartingBefore(end)
+        if (last >= first && first < nodes.length && nodes[last]!.end > start
+          && ineligible[last + 1] === ineligible[first]) {
+          const firstPart = nodes[first]!
+          const lastPart = nodes[last]!
+          const range = this.root.ownerDocument.createRange()
+          range.setStart(firstPart.node, start - firstPart.start)
+          range.setEnd(lastPart.node, end - lastPart.start)
+          this.characters.push({ start, end, born, range, bucket: -1 })
+        }
       }
       end = start
     }
@@ -239,8 +598,9 @@ export class LogarithmicFadeController {
 
   private stopIfIdle(): void {
     if (this.scheduler.pending.size !== 0) return
-    this.scheduler.window.cancelAnimationFrame(this.scheduler.frame)
-    this.scheduler.frame = 0
+    if (this.scheduler.taskId === null) return
+    this.scheduler.coordinator.unregisterTask(this.scheduler.taskId)
+    this.scheduler.taskId = null
   }
 
   dispose(): void {
@@ -248,6 +608,9 @@ export class LogarithmicFadeController {
     this.disposed = true
     this.observer.disconnect()
     this.clearRanges()
+    this.restoreColors()
+    this.nodes = []
+    this.scannedStructureRevision = -1
     this.root.classList.remove(css.scope!)
     this.scheduler.pending.delete(this)
     this.scheduler.clients.delete(this)
@@ -257,6 +620,9 @@ export class LogarithmicFadeController {
         const name = highlightName(index)
         if (this.scheduler.registry.get(name) === highlight) this.scheduler.registry.delete(name)
       }
+      // "Fade off" must cost nothing: no observer, no frame seat, no media
+      // listener left behind for a document that no longer fades.
+      this.scheduler.unwatchAppearance()
       schedulers.delete(this.root.ownerDocument)
     }
   }
@@ -278,11 +644,24 @@ export function useLogarithmicFade(
       controller.current = null
     }
   }, [rootRef])
-  // Deliberately commit-driven, including Markdown updates with unchanged source.
+  // Deliberately commit-driven, including Markdown updates with unchanged
+  // source: React may swap text nodes for identical text, and the controller's
+  // observer cannot report that before the commit's layout effects. The
+  // controller itself drops the redundant half of those passes now.
   useLayoutEffect(() => {
     const root = rootRef.current
+    if (!enabled) {
+      // "Fade off" must cost nothing: no observer, no reconcile, no rAF seat,
+      // no leftover scope class or colour property.
+      if (controller.current !== null) {
+        controller.current.dispose()
+        controller.current = null
+      }
+      committed.current = true
+      return
+    }
     // Settled history allocates neither observers nor highlight buckets.
-    if (controller.current === null && root !== null && enabled && active) {
+    if (controller.current === null && root !== null && active) {
       controller.current = LogarithmicFadeController.create(root)
       // Enabling midway through a message must not replay readable text.
       if (committed.current) controller.current?.update(false, false)