dsh-smooth-stream 0.3.4 → 0.4.1

package/src/client/debugRuntime.ts

@@ -0,0 +1,355 @@
+/**
+ * Shared browser-side diagnostics state.
+ *
+ * The settings card owns persistence. This module is the live bridge used by
+ * the renderer and the chat-side panel: renderer loops publish measurements,
+ * while panel edits are staged through the settings-card controller.
+ */
+
+import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  DEFAULT_STREAM_DEBUG_TUNING,
+  type StreamDebugTuning,
+  type StreamSettings,
+} from '../settings.ts'
+
+export interface DebugMetrics {
+  fps: number | null
+  frameMs: number | null
+  fpsDegraded: boolean
+  streamActive: boolean
+  streamBacklog: number
+  streamSpeedCps: number
+  streamTargetChars: number
+  streamDisplayedChars: number
+  followActive: boolean
+  followLagPx: number
+  followVelocityPxPerSec: number
+  followReservePx: number
+  followCapacityPx: number
+  followRevealScale: number
+  followFollowing: boolean
+  followConstrained: boolean
+  scrollTop: number | null
+  scrollHeight: number | null
+  clientHeight: number | null
+  lastUpdatedMs: number | null
+}
+
+export interface DebugRuntimeState {
+  available: boolean
+  enabled: boolean
+  writable: boolean
+  dirty: boolean
+  status: 'loading' | 'ready' | 'unavailable'
+  tuning: StreamDebugTuning
+  metrics: DebugMetrics
+}
+
+export type DebugSettingsPatch = Partial<Pick<StreamSettings, 'debugEnabled' | 'debugTuning'>>
+
+export interface DebugPanelFace {
+  hooks: {
+    debugRuntime: SnapshotStore<DebugRuntimeState>
+  }
+  edit: (patch: DebugSettingsPatch) => void
+  save: () => void
+  discard: () => void
+  reset: () => void
+}
+
+interface DebugSettingsActions {
+  edit: (patch: DebugSettingsPatch) => void
+  save: () => void
+  discard: () => void
+}
+
+interface StreamMetric {
+  backlog: number
+  speedCps: number
+  targetChars: number
+  displayedChars: number
+  active: boolean
+  updatedAt: number
+}
+
+interface FollowMetric {
+  lagPx: number
+  velocityPxPerSec: number
+  reservePx: number
+  capacityPx: number
+  revealScale: number
+  following: boolean
+  constrained: boolean
+  scrollTop: number
+  scrollHeight: number
+  clientHeight: number
+  active: boolean
+  updatedAt: number
+}
+
+const EMPTY_METRICS: DebugMetrics = {
+  fps: null,
+  frameMs: null,
+  fpsDegraded: false,
+  streamActive: false,
+  streamBacklog: 0,
+  streamSpeedCps: 0,
+  streamTargetChars: 0,
+  streamDisplayedChars: 0,
+  followActive: false,
+  followLagPx: 0,
+  followVelocityPxPerSec: 0,
+  followReservePx: 0,
+  followCapacityPx: 0,
+  followRevealScale: 1,
+  followFollowing: false,
+  followConstrained: false,
+  scrollTop: null,
+  scrollHeight: null,
+  clientHeight: null,
+  lastUpdatedMs: null,
+}
+
+const INITIAL_STATE: DebugRuntimeState = {
+  available: false,
+  enabled: false,
+  writable: false,
+  dirty: false,
+  status: 'loading',
+  tuning: { ...DEFAULT_STREAM_DEBUG_TUNING },
+  metrics: EMPTY_METRICS,
+}
+
+const store = createSnapshotStore<DebugRuntimeState>(INITIAL_STATE)
+const streamMetrics = new Map<string, StreamMetric>()
+const followMetrics = new Map<HTMLElement, FollowMetric>()
+let actions: DebugSettingsActions | undefined
+let lastMetricPublish = 0
+
+function resetMetrics(): void {
+  streamMetrics.clear()
+  followMetrics.clear()
+  lastMetricPublish = 0
+}
+
+function resetRuntime(): void {
+  actions = undefined
+  resetMetrics()
+  store.set({ ...INITIAL_STATE, metrics: EMPTY_METRICS })
+}
+
+function now(): number {
+  return typeof performance === 'undefined' ? Date.now() : performance.now()
+}
+
+function sameTuning(left: StreamDebugTuning, right: StreamDebugTuning): boolean {
+  return left.revealScale === right.revealScale
+    && left.queuePressure === right.queuePressure
+    && left.maxRevealCps === right.maxRevealCps
+    && left.springStiffness === right.springStiffness
+    && left.springDamping === right.springDamping
+    && left.springMass === right.springMass
+    && left.runwayPx === right.runwayPx
+    && left.reserveResponseMs === right.reserveResponseMs
+    && left.backpressureMinScale === right.backpressureMinScale
+}
+
+function currentMetrics(timestamp: number): DebugMetrics {
+  let stream: StreamMetric | undefined
+  for (const candidate of streamMetrics.values()) {
+    if (stream === undefined || candidate.updatedAt > stream.updatedAt) stream = candidate
+  }
+  let follow: FollowMetric | undefined
+  for (const candidate of followMetrics.values()) {
+    if (follow === undefined || candidate.updatedAt > follow.updatedAt) follow = candidate
+  }
+  return {
+    fps: store.getSnapshot().metrics.fps,
+    frameMs: store.getSnapshot().metrics.frameMs,
+    fpsDegraded: store.getSnapshot().metrics.fpsDegraded,
+    streamActive: stream?.active ?? false,
+    streamBacklog: stream?.backlog ?? 0,
+    streamSpeedCps: stream?.speedCps ?? 0,
+    streamTargetChars: stream?.targetChars ?? 0,
+    streamDisplayedChars: stream?.displayedChars ?? 0,
+    followActive: follow?.active ?? false,
+    followLagPx: follow?.lagPx ?? 0,
+    followVelocityPxPerSec: follow?.velocityPxPerSec ?? 0,
+    followReservePx: follow?.reservePx ?? 0,
+    followCapacityPx: follow?.capacityPx ?? 0,
+    followRevealScale: follow?.revealScale ?? 1,
+    followFollowing: follow?.following ?? false,
+    followConstrained: follow?.constrained ?? false,
+    scrollTop: follow?.scrollTop ?? null,
+    scrollHeight: follow?.scrollHeight ?? null,
+    clientHeight: follow?.clientHeight ?? null,
+    lastUpdatedMs: timestamp,
+  }
+}
+
+function publishMetrics(force = false): void {
+  const timestamp = now()
+  if (!force && timestamp - lastMetricPublish < 80) return
+  lastMetricPublish = timestamp
+  store.set({ ...store.getSnapshot(), metrics: currentMetrics(timestamp) })
+}
+
+export const debugRuntime = {
+  store,
+
+  getSnapshot(): DebugRuntimeState {
+    return store.getSnapshot()
+  },
+
+  subscribe(listener: () => void): () => void {
+    return store.subscribe(listener)
+  },
+
+  /** Whether hot-path instrumentation should do any work. */
+  isEnabled(): boolean {
+    return store.getSnapshot().enabled
+  },
+
+  tuning(): StreamDebugTuning {
+    return store.getSnapshot().tuning
+  },
+
+  /** Production values remain untouched until the user explicitly enables diagnostics. */
+  activeTuning(): StreamDebugTuning {
+    return store.getSnapshot().enabled ? store.getSnapshot().tuning : DEFAULT_STREAM_DEBUG_TUNING
+  },
+
+  bindSettings(nextActions: DebugSettingsActions | undefined): () => void {
+    actions = nextActions
+    return () => {
+      if (actions !== nextActions) return
+      resetRuntime()
+    }
+  },
+
+  syncSettings(input: {
+    available?: boolean
+    enabled: boolean
+    writable: boolean
+    dirty: boolean
+    status: DebugRuntimeState['status']
+    tuning?: StreamDebugTuning
+  }): void {
+    const current = store.getSnapshot()
+    // Callers predating the Host capability flag are local diagnostics tests
+    // and renderer probes; preserve their enabled behavior unless the wiring
+    // explicitly reports that the RPC is unavailable.
+    const available = input.available ?? true
+    const enabled = available && input.enabled
+    const availabilityChanged = current.available !== available
+    const enabledChanged = current.enabled !== enabled
+    if (availabilityChanged || enabledChanged) resetMetrics()
+    const tuning = input.tuning === undefined
+      ? current.tuning
+      : { ...DEFAULT_STREAM_DEBUG_TUNING, ...input.tuning }
+    if (
+      current.available === available
+      && current.enabled === enabled
+      && current.writable === input.writable
+      && current.dirty === input.dirty
+      && current.status === input.status
+      && sameTuning(current.tuning, tuning)
+    ) return
+    store.set({
+      ...current,
+      available,
+      enabled,
+      writable: input.writable,
+      dirty: input.dirty,
+      status: input.status,
+      tuning,
+      metrics: availabilityChanged || enabledChanged || !enabled ? EMPTY_METRICS : current.metrics,
+    })
+  },
+
+  edit(patch: DebugSettingsPatch): void {
+    const current = store.getSnapshot()
+    const enabled = patch.debugEnabled ?? current.enabled
+    const enabledChanged = current.enabled !== enabled
+    if (enabledChanged) resetMetrics()
+    const tuning = patch.debugTuning === undefined
+      ? current.tuning
+      : { ...current.tuning, ...patch.debugTuning }
+    store.set({
+      ...current,
+      enabled,
+      dirty: true,
+      tuning,
+      metrics: enabledChanged || !enabled ? EMPTY_METRICS : current.metrics,
+    })
+    actions?.edit({
+      ...(patch.debugEnabled === undefined ? {} : { debugEnabled: patch.debugEnabled }),
+      ...(patch.debugTuning === undefined ? {} : { debugTuning: tuning }),
+    })
+  },
+
+  save(): void {
+    actions?.save()
+  },
+
+  discard(): void {
+    actions?.discard()
+  },
+
+  reset(): void {
+    this.edit({ debugTuning: { ...DEFAULT_STREAM_DEBUG_TUNING } })
+  },
+
+  reportStream(id: string, metric: Omit<StreamMetric, 'updatedAt'> | null): void {
+    if (!this.isEnabled()) return
+    if (metric === null) streamMetrics.delete(id)
+    else streamMetrics.set(id, { ...metric, updatedAt: now() })
+    publishMetrics(metric === null)
+  },
+
+  reportFollow(port: HTMLElement, metric: Omit<FollowMetric, 'updatedAt'> | null): void {
+    if (!this.isEnabled()) return
+    if (metric === null) followMetrics.delete(port)
+    else followMetrics.set(port, { ...metric, updatedAt: now() })
+    publishMetrics(metric === null)
+  },
+
+  reportFps(fps: number, frameMs: number, degraded: boolean): void {
+    if (!this.isEnabled()) return
+    const current = store.getSnapshot()
+    store.set({
+      ...current,
+      metrics: { ...current.metrics, fps, frameMs, fpsDegraded: degraded, lastUpdatedMs: now() },
+    })
+  },
+
+  clearFps(): void {
+    if (!this.isEnabled()) return
+    const current = store.getSnapshot()
+    store.set({
+      ...current,
+      metrics: {
+        ...current.metrics,
+        fps: null,
+        frameMs: null,
+        fpsDegraded: false,
+        lastUpdatedMs: now(),
+      },
+    })
+  },
+
+  panelFace(): DebugPanelFace {
+    return {
+      hooks: { debugRuntime: store },
+      edit: patch => { this.edit(patch) },
+      save: () => { this.save() },
+      discard: () => { this.discard() },
+      reset: () => { this.reset() },
+    }
+  },
+
+  resetRuntime(): void {
+    resetRuntime()
+  },
+}

package/src/client/index.ts

@@ -7,13 +7,16 @@ import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client
 import type {} from '@deepseek-ai/dsh-client-ui-settings-plugins/client'
 import type { ChatNodeViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { TypewriterAssistantNodeView } from './TypewriterAssistantNodeView.tsx'
+import { AutoCollapseController } from './auto-collapse-controller.ts'
 import { wrapFollowNodeView, type FollowWrapProps } from './TypewriterToolNodeView.tsx'
 import { SmoothStreamCard } from './SmoothStreamCard.tsx'
 import { SmoothStreamCardController } from './smooth-stream-card-controller.ts'
 import { createSmoothStreamSettingsApi } from './smooth-stream-settings-api.ts'
+import { DebugPanel } from './DebugPanel.tsx'
+import { debugRuntime } from './debugRuntime.ts'
 import { NS as SETTINGS_NS, en, zh } from './locales.ts'
 import { DEFAULT_STREAM_CONFIG, STREAM_BOOT_GLOBAL, type StreamConfig } from '../config.ts'
-import { DEFAULT_STREAM_SETTINGS } from '../settings.ts'
+import { DEFAULT_STREAM_SETTINGS, STREAM_SETTINGS_NS, type StreamSettings } from '../settings.ts'
 
 /**
  * Cordis services required by the browser half. Only `slots` is load-bearing
@@ -116,15 +119,15 @@ function wrapAgentChatRows(ctx: ClientContext): () => void {
 }
 
 /**
- * A live preference cell read by `useSyncExternalStore`. It starts on the
- * shared default and, once the plugin-owned settings controller is attached,
- * tracks the resolved `thinkAutoExpand` value. A composition (or test) that
- * ships no settings surface keeps the cell on the default.
+ * A live settings cell shared by the renderer lifecycle and React views. It
+ * starts on the shared defaults and follows the plugin-owned controller once
+ * the optional settings services arrive.
  */
-class PreferenceCell {
+class SettingsCell {
   private readonly listeners = new Set<() => void>()
   private card: SmoothStreamCardController | undefined
-  private value = DEFAULT_STREAM_SETTINGS.thinkAutoExpand
+  private value: StreamSettings = DEFAULT_STREAM_SETTINGS
+  private pending = false
 
   /** Re-point the cell at the plugin-owned settings controller. */
   attach(card: SmoothStreamCardController): () => void {
@@ -139,18 +142,39 @@ class PreferenceCell {
     }
   }
 
-  private read(): boolean {
-    return this.card?.getSnapshot().thinkAutoExpand ?? DEFAULT_STREAM_SETTINGS.thinkAutoExpand
+  private read(): StreamSettings {
+    const snapshot = this.card?.getSnapshot()
+    if (snapshot === undefined || snapshot.status !== 'ready') return this.value
+    return this.card?.values() ?? this.value
   }
 
   private refresh(): void {
     const next = this.read()
-    if (next === this.value) return
+    const pending = this.card?.getSnapshot().status === 'loading'
+    if (
+      pending === this.pending
+      && next.enabled === this.value.enabled
+      && next.thinkAutoExpand === this.value.thinkAutoExpand
+      && next.autoCollapse === this.value.autoCollapse
+      && next.debugEnabled === this.value.debugEnabled
+      && next.debugTuning === this.value.debugTuning
+    ) return
+    this.pending = pending
     this.value = next
     for (const listener of this.listeners) listener()
   }
 
-  readonly getSnapshot = (): boolean => this.value
+  /** False while an available settings service is resolving its authority. */
+  takeoverEnabled(): boolean {
+    return !this.pending && this.value.enabled
+  }
+
+  /** Whether finished turns should fold behind a summary row right now. */
+  autoCollapseActive(): boolean {
+    return !this.pending && this.value.autoCollapse
+  }
+
+  readonly getSnapshot = (): StreamSettings => this.value
 
   readonly subscribe = (listener: () => void): () => void => {
     this.listeners.add(listener)
@@ -171,7 +195,26 @@ class PreferenceCell {
  */
 export function apply(ctx: ClientContext): void {
   const config = readBootConfig()
-  const preference = new PreferenceCell()
+  const settings = new SettingsCell()
+
+  // Auto-collapse works at the DOM level and is independent of the renderer
+  // takeover: it also folds finished turns when the built-in Harness renderer
+  // owns the conversation. The lifecycle rides the guaranteed `slots` service
+  // (this entry's own inject list) and follows the same live settings cell, so
+  // flipping the preference restores every folded row immediately.
+  ctx.inject(['slots'], () => {
+    const autoCollapse = new AutoCollapseController()
+    const syncAutoCollapse = (): void => {
+      if (settings.autoCollapseActive()) autoCollapse.start()
+      else autoCollapse.stop()
+    }
+    const unsubscribe = settings.subscribe(syncAutoCollapse)
+    syncAutoCollapse()
+    return () => {
+      unsubscribe()
+      autoCollapse.stop()
+    }
+  })
 
   // The card talks to the plugin-owned loopback RPC, so the core settings
   // namespace allowlist cannot make it disappear. The stream still applies
@@ -183,27 +226,57 @@ export function apply(ctx: ClientContext): void {
       // handle, so narrow through unknown to its client contract here.
       createSmoothStreamSettingsApi(settingsCtx.get('connection') as unknown as ConnectionHandle),
     )
-    const detachPreference = preference.attach(card)
+    const detachSettings = settings.attach(card)
+    const syncDebug = (): void => {
+      const snapshot = card.getSnapshot()
+      debugRuntime.syncSettings({
+        available: snapshot.debugAvailable,
+        enabled: snapshot.debugEnabled,
+        writable: snapshot.writable && !snapshot.saving,
+        dirty: snapshot.dirty,
+        status: snapshot.status,
+        tuning: snapshot.debugTuning,
+      })
+    }
+    const detachBinding = debugRuntime.bindSettings({
+      edit: patch => { card.inject().edit(patch) },
+      save: () => { card.inject().save() },
+      discard: () => { card.inject().discard() },
+    })
+    const detachDebug = card.subscribe(syncDebug)
+    syncDebug()
     card.start()
     settingsCtx.effect(() => settingsCtx.locale.register(SETTINGS_NS, { zh, en }), 'dsh-smooth-stream: settings dictionaries')
     settingsCtx.slots.inject('settings.plugin.item', () => settingsCtx.slots.register({
       name: 'settings.plugin.item',
       id: 'smooth-stream',
+      key: STREAM_SETTINGS_NS,
       order: 30,
       locale: SETTINGS_NS,
       inject: () => card.inject(),
-    }, SmoothStreamCard))
+    // Older Harness declares this slot as a list (`id`); newer Harness uses a
+    // keyed slot filtered by the Host settings namespace (`key`).
+    } as never, SmoothStreamCard))
+    settingsCtx.slots.inject('conversation.session.header.utilities', () => settingsCtx.slots.register({
+      name: 'conversation.session.header.utilities',
+      id: 'smooth-stream-debug',
+      order: 40,
+      locale: SETTINGS_NS,
+      inject: () => debugRuntime.panelFace(),
+    }, DebugPanel))
     return () => {
       card.stop()
-      detachPreference()
+      detachDebug()
+      detachSettings()
+      detachBinding()
     }
   })
 
   const configured = function StreamConfiguredView(props: AssistantProps) {
-    const thinkAutoExpand = useSyncExternalStore(
-      preference.subscribe,
-      preference.getSnapshot,
-      preference.getSnapshot,
+    const preferences = useSyncExternalStore(
+      settings.subscribe,
+      settings.getSnapshot,
+      settings.getSnapshot,
     )
     return createElement(TypewriterAssistantNodeView, {
       ...props,
@@ -212,21 +285,39 @@ export function apply(ctx: ClientContext): void {
       revealCharsPerSec: config.revealCharsPerSec,
       scrollSpeedPxPerSec: config.scrollSpeedPxPerSec,
       maxScrollSpeedPxPerSec: config.maxScrollSpeedPxPerSec,
-      thinkAutoExpand,
+      thinkAutoExpand: preferences.thinkAutoExpand,
     })
   }
   ctx.slots.inject('conversation.chat.node', () => {
-    const unwrap = wrapAgentChatRows(ctx)
-    const unshadow = ctx.slots.register({
-      name: 'conversation.chat.node',
-      key: 'assistant-step',
-      priority: -100,
-      locale: 'conversation',
-      registrant: 'dsh-smooth-stream',
-    }, configured)
+    let releaseTakeover: (() => void) | undefined
+
+    const syncTakeover = (): void => {
+      if (!settings.takeoverEnabled()) {
+        releaseTakeover?.()
+        releaseTakeover = undefined
+        return
+      }
+      if (releaseTakeover !== undefined) return
+      const unwrap = wrapAgentChatRows(ctx)
+      const unshadow = ctx.slots.register({
+        name: 'conversation.chat.node',
+        key: 'assistant-step',
+        priority: -100,
+        locale: 'conversation',
+        registrant: 'dsh-smooth-stream',
+      }, configured)
+      releaseTakeover = () => {
+        // Stop observing slot changes before the shadow entry is removed.
+        unwrap()
+        unshadow()
+      }
+    }
+
+    const unsubscribe = settings.subscribe(syncTakeover)
+    syncTakeover()
     return () => {
-      unshadow()
-      unwrap()
+      unsubscribe()
+      releaseTakeover?.()
     }
   })
 }