dsh-smooth-stream 0.6.0 → 0.7.0

package/src/client/FrameCoordinator.ts

@@ -0,0 +1,180 @@
+/**
+ * FrameCoordinator: unified per-document frame clock and phased layout scheduler.
+ *
+ * Replaces competing, uncoordinated rAF loops across text reveal, follow
+ * physics, fade painting, and diagnostic sampling. One document owns exactly
+ * one live animation frame while any task is active.
+ *
+ * Strict phase order in every frame:
+ * 1. Read Phase: layout reads ONLY when some task declared them dirty.
+ * 2. Simulate Phase: pure math / integration (pacing, spring, buckets).
+ *    A task returns `true` to stay armed for the next frame.
+ * 3. Write Phase: batched DOM mutations (text nodes, transforms, CSS vars,
+ *    at most one scrollTop write per owner).
+ *
+ * Tasks registered later never overtake earlier ones inside a phase, so a
+ * task's relative order is its registration order.
+ *
+ * `requestRead` is the bridge to the previous frame: a task that just wrote
+ * layout-affecting DOM (pacing revealed text, mutate() batch) declares that
+ * geometry must be re-read at the top of the NEXT frame, before the follow
+ * engine simulates. That keeps the "no layout read after a layout write in
+ * the same frame" invariant without giving up a same-reveal measurement.
+ */
+
+export interface FrameTask {
+  readonly id: string
+  /** Called if any task marked layout as dirty during the frame cycle. */
+  onRead?: ((now: number) => void) | undefined
+  /** Physics, trajectory, and character pace calculation. Returns true if active. */
+  onSimulate?: ((dtMs: number, now: number) => boolean) | undefined
+  /** DOM and visual style mutation phase (transform, text, scrollTop). */
+  onWrite?: ((now: number) => void) | undefined
+}
+
+export class FrameCoordinator {
+  private static coordinators = new WeakMap<Document, FrameCoordinator>()
+
+  private tasks = new Map<string, FrameTask>()
+  private rafId: number | null = null
+  private lastTs: number | null = null
+  /**
+   * Owed layout read. Starts false: a fresh coordinator has no unread writes,
+   * and starting dirty would keep the clock armed forever after the first
+   * frame. Consumers declare reads via {@link markLayoutDirty}.
+   */
+  private layoutDirty = false
+  /** One id per consumer, so an unregister cannot evict a re-registered task. */
+  private nextTaskId = 0
+  private doc: Document
+
+  private constructor(doc: Document) {
+    this.doc = doc
+  }
+
+  static forDocument(doc: Document = document): FrameCoordinator {
+    let coordinator = FrameCoordinator.coordinators.get(doc)
+    if (coordinator === undefined) {
+      coordinator = new FrameCoordinator(doc)
+      FrameCoordinator.coordinators.set(doc, coordinator)
+    }
+    return coordinator
+  }
+
+  /**
+   * Mark that a DOM or geometry change requires a layout read next frame.
+   */
+  markLayoutDirty(): void {
+    this.layoutDirty = true
+    this.ensureLoop()
+  }
+
+  /**
+   * Declare that geometry written since the last frame must be re-read at the
+   * top of the next one, and keep the clock running for it.
+   */
+  requestRead(): void {
+    this.markLayoutDirty()
+  }
+
+  /**
+   * Register or replace an animation/render task. Returns the task id to hand
+   * back to {@link unregisterTask}.
+   */
+  registerTask(task: Omit<FrameTask, 'id'> & { id?: string }): string {
+    const id = task.id ?? `frame-task-${this.nextTaskId++}`
+    this.tasks.set(id, { ...task, id })
+    this.ensureLoop()
+    return id
+  }
+
+  /**
+   * Unregister a task when its stream completes or the element unmounts.
+   */
+  unregisterTask(id: string | null | undefined): void {
+    if (id === null || id === undefined) return
+    this.tasks.delete(id)
+    if (this.tasks.size === 0 && !this.layoutDirty) this.stopLoop()
+  }
+
+  private ensureLoop(): void {
+    if (this.rafId !== null) return
+    const win = this.doc.defaultView ?? (typeof window !== 'undefined' ? window : null)
+    if (win === null) return
+
+    const tick = (now: number) => {
+      this.rafId = null
+
+      if (this.lastTs === null) {
+        this.lastTs = now
+        // First frame after an idle gap only establishes the time base.
+        this.ensureLoop()
+        return
+      }
+
+      const frameIntervalMs = Math.max(0, now - this.lastTs)
+      // Clamp frame delta between 1ms and 100ms to avoid physics explosions
+      // during main-thread hiccups.
+      const dtMs = Math.max(1, Math.min(frameIntervalMs, 100))
+      this.lastTs = now
+
+      // 1. Read phase (only when some task declared layout dirty).
+      if (this.layoutDirty) {
+        this.layoutDirty = false
+        for (const task of this.tasks.values()) task.onRead?.(now)
+      }
+
+      // 2. Simulate phase (pacing step, spring, lag, bucket math).
+      let anyActive = false
+      for (const task of this.tasks.values()) {
+        if (task.onSimulate?.(dtMs, now) === true) anyActive = true
+      }
+
+      // 3. Write phase (transforms, text nodes, CSS variables, scrollTop).
+      for (const task of this.tasks.values()) task.onWrite?.(now)
+
+      // Stay armed while a task is active, while a pending read is owed, or
+      // while callers keep the clock explicitly running.
+      if ((anyActive || this.layoutDirty) && this.rafId === null) {
+        this.ensureLoop()
+      } else if (!anyActive && !this.layoutDirty) {
+        this.lastTs = null
+      }
+    }
+
+    this.rafId = win.requestAnimationFrame(tick)
+  }
+
+  private stopLoop(): void {
+    if (this.rafId !== null) {
+      const win = this.doc.defaultView ?? (typeof window !== 'undefined' ? window : null)
+      win?.cancelAnimationFrame(this.rafId)
+      this.rafId = null
+    }
+    this.lastTs = null
+  }
+
+  /**
+   * Whether this document currently owns a live, still-needed animation
+   * frame. A frame that is merely draining an owed read with no registered
+   * task left is not considered active work.
+   */
+  get active(): boolean {
+    return this.rafId !== null && (this.tasks.size > 0 || this.layoutDirty)
+  }
+
+  /** Number of registered tasks; used by tests to pin the single-clock contract. */
+  get taskCount(): number {
+    return this.tasks.size
+  }
+
+  /**
+   * Release every task, drop any owed read, and stop the clock. Used by tests
+   * for isolation; production consumers unregister their own task.
+   */
+  shutdown(): void {
+    this.tasks.clear()
+    this.layoutDirty = false
+    this.stopLoop()
+  }
+}

package/src/client/LogarithmicFade.module.css

@@ -0,0 +1,160 @@
+/* Shared buckets change paint only; original DOM, layout and colors survive. */
+.scope::highlight(dsh-smooth-stream-log-fade-0),
+.scope *::highlight(dsh-smooth-stream-log-fade-0) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 0.00000%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-1),
+.scope *::highlight(dsh-smooth-stream-log-fade-1) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 3.22581%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-2),
+.scope *::highlight(dsh-smooth-stream-log-fade-2) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 6.45161%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-3),
+.scope *::highlight(dsh-smooth-stream-log-fade-3) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 9.67742%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-4),
+.scope *::highlight(dsh-smooth-stream-log-fade-4) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 12.90323%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-5),
+.scope *::highlight(dsh-smooth-stream-log-fade-5) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 16.12903%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-6),
+.scope *::highlight(dsh-smooth-stream-log-fade-6) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 19.35484%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-7),
+.scope *::highlight(dsh-smooth-stream-log-fade-7) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 22.58065%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-8),
+.scope *::highlight(dsh-smooth-stream-log-fade-8) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 25.80645%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-9),
+.scope *::highlight(dsh-smooth-stream-log-fade-9) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 29.03226%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-10),
+.scope *::highlight(dsh-smooth-stream-log-fade-10) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 32.25806%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-11),
+.scope *::highlight(dsh-smooth-stream-log-fade-11) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 35.48387%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-12),
+.scope *::highlight(dsh-smooth-stream-log-fade-12) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 38.70968%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-13),
+.scope *::highlight(dsh-smooth-stream-log-fade-13) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 41.93548%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-14),
+.scope *::highlight(dsh-smooth-stream-log-fade-14) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 45.16129%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-15),
+.scope *::highlight(dsh-smooth-stream-log-fade-15) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 48.38710%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-16),
+.scope *::highlight(dsh-smooth-stream-log-fade-16) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 51.61290%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-17),
+.scope *::highlight(dsh-smooth-stream-log-fade-17) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 54.83871%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-18),
+.scope *::highlight(dsh-smooth-stream-log-fade-18) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 58.06452%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-19),
+.scope *::highlight(dsh-smooth-stream-log-fade-19) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 61.29032%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-20),
+.scope *::highlight(dsh-smooth-stream-log-fade-20) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 64.51613%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-21),
+.scope *::highlight(dsh-smooth-stream-log-fade-21) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 67.74194%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-22),
+.scope *::highlight(dsh-smooth-stream-log-fade-22) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 70.96774%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-23),
+.scope *::highlight(dsh-smooth-stream-log-fade-23) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 74.19355%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-24),
+.scope *::highlight(dsh-smooth-stream-log-fade-24) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 77.41935%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-25),
+.scope *::highlight(dsh-smooth-stream-log-fade-25) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 80.64516%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-26),
+.scope *::highlight(dsh-smooth-stream-log-fade-26) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 83.87097%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-27),
+.scope *::highlight(dsh-smooth-stream-log-fade-27) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 87.09677%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-28),
+.scope *::highlight(dsh-smooth-stream-log-fade-28) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 90.32258%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-29),
+.scope *::highlight(dsh-smooth-stream-log-fade-29) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 93.54839%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-30),
+.scope *::highlight(dsh-smooth-stream-log-fade-30) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 96.77419%, transparent);
+}
+
+.scope::highlight(dsh-smooth-stream-log-fade-31),
+.scope *::highlight(dsh-smooth-stream-log-fade-31) {
+  color: color-mix(in srgb, var(--dsh-smooth-stream-fade-color, currentColor) 100.00000%, transparent);
+}

package/src/client/SmoothStreamCard.tsx

@@ -8,7 +8,7 @@
 import { useState } from 'react'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import type {} from '@deepseek-ai/dsh-client-ui-settings-plugins/client'
-import { IconChevronDownOutline14, IconRefreshOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconChevronDown, IconRefresh } from './harnessIcons.ts'
 import type { SmoothStreamCardFace } from './smooth-stream-card-controller.ts'
 import css from './SmoothStreamCard.module.css'
 
@@ -43,7 +43,7 @@ export function SmoothStreamCard(props: SmoothStreamCardProps) {
         </span>
         {versionLabel === null ? null : <span className={css.version}>{versionLabel}</span>}
         {state.dirty ? <span className={css.pending}>{t('unsaved')}</span> : null}
-        <IconChevronDownOutline14 className={open ? `${css.chevron} ${css.chevronOpen}` : css.chevron} />
+        <IconChevronDown className={open ? `${css.chevron} ${css.chevronOpen}` : css.chevron} />
       </button>
       {open
         ? (
@@ -84,6 +84,19 @@ export function SmoothStreamCard(props: SmoothStreamCardProps) {
                   </span>
                   <span className={css.hint}>{t('controlScrollHint')}</span>
                 </label>
+                <label className={state.enabled ? css.field : `${css.field} ${css.fieldDisabled}`}>
+                  <span className={css.fieldHead}>
+                    <span className={css.label}>{t('logarithmicFade')}</span>
+                    <input
+                      type="checkbox"
+                      className={css.toggle}
+                      checked={state.logarithmicFade}
+                      disabled={!state.writable || state.saving || !state.enabled}
+                      onChange={(event) => { props.edit({ logarithmicFade: event.target.checked }) }}
+                    />
+                  </span>
+                  <span className={css.hint}>{t('logarithmicFadeHint')}</span>
+                </label>
                 {/* Motion preference is a radio group, so this row is a div:
                     nesting the choice labels inside a field <label> would be
                     illegal HTML (label within label) and browsers route the
@@ -113,6 +126,31 @@ export function SmoothStreamCard(props: SmoothStreamCardProps) {
                     ))}
                   </span>
                 </div>
+                <div className={state.enabled ? css.field : `${css.field} ${css.fieldDisabled}`}>
+                  <span className={css.fieldHead}>
+                    <span className={css.label}>{t('preset')}</span>
+                  </span>
+                  <span className={css.hint}>{t('presetHint')}</span>
+                  <span className={css.choiceRow} role="radiogroup" aria-label={t('preset')}>
+                    {([
+                      ['realtime', 'presetRealtime', 'presetRealtimeHint'],
+                      ['balanced', 'presetBalanced', 'presetBalancedHint'],
+                      ['silky', 'presetSilky', 'presetSilkyHint'],
+                    ] as const).map(([value, label, hint]) => (
+                      <label key={value} className={css.choice} title={t(hint)}>
+                        <input
+                          type="radio"
+                          className={css.choiceInput}
+                          name="smooth-stream-preset"
+                          checked={state.preset === value}
+                          disabled={!state.writable || state.saving || !state.enabled}
+                          onChange={() => { props.edit({ preset: value }) }}
+                        />
+                        {t(label)}
+                      </label>
+                    ))}
+                  </span>
+                </div>
                 <label className={state.enabled ? css.field : `${css.field} ${css.fieldDisabled}`}>
                   <span className={css.fieldHead}>
                     <span className={css.label}>{t('thinkAutoExpand')}</span>
@@ -156,7 +194,7 @@ export function SmoothStreamCard(props: SmoothStreamCardProps) {
                     title={state.canUpgrade ? undefined : t('updateUnavailable')}
                     onClick={props.upgrade}
                   >
-                    <span aria-hidden="true"><IconRefreshOutline14 /></span>
+                    <span aria-hidden="true"><IconRefresh /></span>
                     {t(state.upgrading ? 'updating' : 'update')}
                   </button>
                 </div>

package/src/client/StreamBuffer.ts

@@ -0,0 +1,145 @@
+/**
+ * High-performance append-only stream buffer with code-point cursor addressing.
+ *
+ * Avoids per-frame `[...content].slice().join('')` or repeated full-string allocations.
+ * Chunks are stored in an indexed rope array, and code-point to UTF-16 offset maps
+ * are updated incrementally per chunk.
+ */
+
+export class StreamBuffer {
+  private chunks: string[] = []
+  private chunkCodePoints: number[] = []
+  private chunkCharLengths: number[] = []
+  private totalCodePoints = 0
+  private fullStringCache: string | null = null
+
+  constructor(initialText = '') {
+    if (initialText.length > 0) {
+      this.append(initialText)
+    }
+  }
+
+  /**
+   * Count Unicode code points (perceived characters, UTF-16 surrogate pairs counted as 1).
+   */
+  static countCodePoints(str: string): number {
+    let count = 0
+    for (let i = 0; i < str.length; i++) {
+      const code = str.charCodeAt(i)
+      if (code >= 0xd800 && code <= 0xdbff && i + 1 < str.length) {
+        const next = str.charCodeAt(i + 1)
+        if (next >= 0xdc00 && next <= 0xdfff) {
+          i++
+        }
+      }
+      count++
+    }
+    return count
+  }
+
+  /**
+   * Convert code-point index into UTF-16 unit offset within a single chunk.
+   */
+  private static codePointToOffset(str: string, targetCp: number): number {
+    let cp = 0
+    let offset = 0
+    while (offset < str.length && cp < targetCp) {
+      const code = str.charCodeAt(offset)
+      if (code >= 0xd800 && code <= 0xdbff && offset + 1 < str.length) {
+        const next = str.charCodeAt(offset + 1)
+        if (next >= 0xdc00 && next <= 0xdfff) {
+          offset++
+        }
+      }
+      offset++
+      cp++
+    }
+    return offset
+  }
+
+  /**
+   * Append a new chunk to the buffer.
+   */
+  append(chunk: string): void {
+    if (chunk.length === 0) return
+    const cps = StreamBuffer.countCodePoints(chunk)
+    this.chunks.push(chunk)
+    this.chunkCodePoints.push(cps)
+    this.chunkCharLengths.push(chunk.length)
+    this.totalCodePoints += cps
+    this.fullStringCache = null
+  }
+
+  /**
+   * Total perceived characters (code points) in the buffer.
+   */
+  get length(): number {
+    return this.totalCodePoints
+  }
+
+  /**
+   * Reset the buffer to empty or to a new baseline string.
+   */
+  reset(text = ''): void {
+    this.chunks = []
+    this.chunkCodePoints = []
+    this.chunkCharLengths = []
+    this.totalCodePoints = 0
+    this.fullStringCache = null
+    if (text.length > 0) {
+      this.append(text)
+    }
+  }
+
+  /**
+   * Extract a slice of text between `fromCp` and `toCp` (both in code points).
+   */
+  slice(fromCp: number, toCp: number): string {
+    const start = Math.max(0, fromCp)
+    const end = Math.min(this.totalCodePoints, toCp)
+    if (start >= end) return ''
+
+    // Fast path: if requesting the full string
+    if (start === 0 && end === this.totalCodePoints) {
+      return this.toString()
+    }
+
+    let result = ''
+    let accumulatedCp = 0
+
+    for (let i = 0; i < this.chunks.length; i++) {
+      const chunkCps = this.chunkCodePoints[i]!
+      const chunkEndCp = accumulatedCp + chunkCps
+
+      if (chunkEndCp <= start) {
+        accumulatedCp = chunkEndCp
+        continue
+      }
+      if (accumulatedCp >= end) {
+        break
+      }
+
+      const chunk = this.chunks[i]!
+      const localStartCp = Math.max(0, start - accumulatedCp)
+      const localEndCp = Math.min(chunkCps, end - accumulatedCp)
+
+      const startOffset = localStartCp === 0 ? 0 : StreamBuffer.codePointToOffset(chunk, localStartCp)
+      const endOffset = localEndCp === chunkCps ? chunk.length : StreamBuffer.codePointToOffset(chunk, localEndCp)
+
+      result += chunk.slice(startOffset, endOffset)
+      accumulatedCp = chunkEndCp
+    }
+
+    return result
+  }
+
+  /**
+   * Get the full concatenated string (cached until next append/reset).
+   */
+  toString(): string {
+    if (this.fullStringCache === null) {
+      this.fullStringCache = this.chunks.join('')
+    }
+    return this.fullStringCache
+  }
+}