dsh-smooth-stream 0.3.3 → 0.4.0

package/src/client/locales.ts

@@ -6,7 +6,23 @@ export const NS = 'settings.smoothStream'
 /** Locale keys the card renders. */
 export type SmoothStreamLocaleKey =
   | 'title' | 'description'
+  | 'enabled' | 'enabledHint'
   | 'thinkAutoExpand' | 'thinkAutoExpandHint'
+  | 'autoCollapse' | 'autoCollapseHint'
+  | 'debugEnabled' | 'debugEnabledHint' | 'debugUnavailable'
+  | 'debugPanelTitle' | 'debugPanelToggle' | 'debugPanelClose' | 'debugGuide'
+  | 'debugLive' | 'debugIdle' | 'debugUnsaved'
+  | 'debugSave' | 'debugDiscard' | 'debugReset' | 'debugCopy' | 'debugCopied'
+  | 'debugSectionLive' | 'debugSectionReveal' | 'debugSectionFollow'
+  | 'debugFps' | 'debugFrameTime' | 'debugBacklog' | 'debugRevealSpeed' | 'debugProgress'
+  | 'debugFollowState' | 'debugFollowing' | 'debugReleased'
+  | 'debugLag' | 'debugVelocity' | 'debugReserve' | 'debugCapacity' | 'debugAppliedScale'
+  | 'debugRevealMultiplier' | 'debugQueuePressure' | 'debugMaxReveal'
+  | 'debugSpringStiffness' | 'debugSpringDamping' | 'debugSpringMass'
+  | 'debugRunway' | 'debugReserveResponse' | 'debugBackpressureMin'
+  | 'debugTipRevealMultiplier' | 'debugTipQueuePressure' | 'debugTipMaxReveal'
+  | 'debugTipSpringStiffness' | 'debugTipSpringDamping' | 'debugTipSpringMass'
+  | 'debugTipRunway' | 'debugTipReserveResponse' | 'debugTipBackpressureMin'
   | 'readOnly' | 'loading' | 'unavailable' | 'retry'
   | 'version' | 'developmentVersion'
   | 'updates' | 'updateHint' | 'developmentBuild' | 'updateUnavailable'
@@ -17,8 +33,61 @@ export type SmoothStreamLocaleKey =
 export const en: Record<SmoothStreamLocaleKey, string> = {
   title: 'Smooth stream',
   description: 'How replies are revealed while they stream.',
+  enabled: 'Enable smooth streaming',
+  enabledHint: 'Let this plugin render and follow streaming replies. Turn off to use the built-in Harness renderer.',
   thinkAutoExpand: 'Auto-expand thinking',
   thinkAutoExpandHint: 'Open the thinking block while it streams. Turn off to keep it collapsed.',
+  autoCollapse: 'Collapse finished work',
+  autoCollapseHint: 'When a reply finishes, fold its thinking, tools, and intermediate output behind one “Processed” summary so only the final answer shows. Click the summary to expand again; works with streaming on or off.',
+  debugEnabled: 'Show render diagnostics',
+  debugEnabledHint: 'Show live streaming and scroll metrics on the right side of the chat. Tune values there, then save them here.',
+  debugUnavailable: 'Live diagnostics require a newer plugin Host.',
+  debugPanelTitle: 'Render diagnostics',
+  debugPanelToggle: 'Toggle render diagnostics',
+  debugPanelClose: 'Hide diagnostics panel',
+  debugGuide: 'Tune one value at a time while a reply streams. Keep FPS stable and backlog near zero. If text lags, raise the reveal multiplier, queue pressure, or maximum reveal; if a blank gap appears, reduce Predictive runway. Increase damping when the scroll feels springy. Save only after the behavior is stable; Reset restores the production defaults.',
+  debugLive: 'Streaming',
+  debugIdle: 'Idle',
+  debugUnsaved: 'Unsaved tuning',
+  debugSave: 'Save tuning',
+  debugDiscard: 'Discard changes',
+  debugReset: 'Reset tuning',
+  debugCopy: 'Copy diagnostics',
+  debugCopied: 'Copied',
+  debugSectionLive: 'Live renderer',
+  debugSectionReveal: 'Reveal tuning',
+  debugSectionFollow: 'Scroll tuning',
+  debugFps: 'FPS',
+  debugFrameTime: 'Frame',
+  debugBacklog: 'Backlog',
+  debugRevealSpeed: 'Reveal',
+  debugProgress: 'Progress',
+  debugFollowState: 'Follow',
+  debugFollowing: 'Pinned',
+  debugReleased: 'Released',
+  debugLag: 'Visual lag',
+  debugVelocity: 'Velocity',
+  debugReserve: 'Reserve',
+  debugCapacity: 'Capacity',
+  debugAppliedScale: 'Applied scale',
+  debugRevealMultiplier: 'Reveal multiplier',
+  debugQueuePressure: 'Queue pressure',
+  debugMaxReveal: 'Maximum reveal',
+  debugSpringStiffness: 'Spring stiffness',
+  debugSpringDamping: 'Spring damping',
+  debugSpringMass: 'Spring mass',
+  debugRunway: 'Predictive runway',
+  debugReserveResponse: 'Runway response',
+  debugBackpressureMin: 'Minimum backpressure',
+  debugTipRevealMultiplier: 'Overall reveal speed multiplier. Higher reveals text faster and clears backlog sooner, but can feel jumpy. Lower is smoother but takes longer to finish.',
+  debugTipQueuePressure: 'Backlog acceleration strength. Higher catches up to a growing queue more aggressively; lower keeps speed steadier but may leave backlog.',
+  debugTipMaxReveal: 'Hard cap for reveal speed in characters per second. Higher allows faster catch-up; lower limits bursts and keeps motion calmer.',
+  debugTipSpringStiffness: 'Scroll spring strength. Higher closes visual lag faster but can feel sharp; lower feels softer but follows more slowly.',
+  debugTipSpringDamping: 'Scroll energy damping. Higher suppresses overshoot and jitter but feels heavier; lower feels livelier but may oscillate.',
+  debugTipSpringMass: 'Scroll inertia. Higher makes movement slower and heavier; lower makes it react faster but can feel abrupt.',
+  debugTipRunway: 'Predictive blank space reserved while content grows. Higher absorbs growth and protects the bottom follow, but can create a larger visible gap; lower reduces blank space but leaves less room to absorb lag.',
+  debugTipReserveResponse: 'How quickly the reserved runway opens or closes. Higher changes more gradually; lower reacts faster but can look abrupt.',
+  debugTipBackpressureMin: 'Slowest reveal multiplier under scroll pressure. Higher keeps text moving but may increase visual lag; lower slows text more to protect smooth following.',
   readOnly: 'This deployment stores settings read-only.',
   loading: 'Loading plugin settings…',
   unavailable: 'Plugin settings are unavailable in this connection.',
@@ -44,8 +113,61 @@ export const en: Record<SmoothStreamLocaleKey, string> = {
 export const zh: Record<SmoothStreamLocaleKey, string> = {
   title: '丝滑流式',
   description: '回复在流式输出时如何逐字展现。',
+  enabled: '启用丝滑流式渲染',
+  enabledHint: '由本插件渲染并跟随流式回复；关闭后使用 Harness 内置渲染。',
   thinkAutoExpand: '自动展开思考',
   thinkAutoExpandHint: '思考块在流式时自动展开；关闭后保持折叠，可手动展开。',
+  autoCollapse: '完成后自动折叠',
+  autoCollapseHint: '回复处理完成后，把思考、工具与过程输出折叠为一行“已处理”摘要，只展示最终回复；点击摘要可再次展开。开启或关闭流式渲染均可用，默认开启。',
+  debugEnabled: '显示渲染调试面板',
+  debugEnabledHint: '在聊天右侧显示流式渲染和滚动的实时参数，可在面板中调节并在这里保存。',
+  debugUnavailable: '当前 Host 版本不支持实时调试，请先更新插件 Host。',
+  debugPanelTitle: '渲染诊断',
+  debugPanelToggle: '显示或隐藏渲染诊断',
+  debugPanelClose: '收起诊断面板',
+  debugGuide: '流式输出时一次只调一个参数，观察帧率、积压和视觉滞后。优先保持帧率稳定、积压接近 0；如果文字滞后，提高揭示倍率、队列压力或最大揭示速度；如果底部出现空白，降低“预测预留空间”。滚动有回弹或抖动时提高阻尼。确认表现稳定后再保存；“恢复默认参数”会回到生产默认值。',
+  debugLive: '正在流式输出',
+  debugIdle: '空闲',
+  debugUnsaved: '参数尚未保存',
+  debugSave: '保存参数',
+  debugDiscard: '放弃修改',
+  debugReset: '恢复默认参数',
+  debugCopy: '复制诊断数据',
+  debugCopied: '已复制',
+  debugSectionLive: '实时渲染',
+  debugSectionReveal: '流式参数',
+  debugSectionFollow: '滚动参数',
+  debugFps: '帧率',
+  debugFrameTime: '帧耗时',
+  debugBacklog: '积压字符',
+  debugRevealSpeed: '揭示速度',
+  debugProgress: '渲染进度',
+  debugFollowState: '跟随状态',
+  debugFollowing: '跟随底部',
+  debugReleased: '用户已释放',
+  debugLag: '视觉滞后',
+  debugVelocity: '滚动速度',
+  debugReserve: '预留空间',
+  debugCapacity: '安全容量',
+  debugAppliedScale: '实际倍率',
+  debugRevealMultiplier: '揭示倍率',
+  debugQueuePressure: '队列压力',
+  debugMaxReveal: '最大揭示速度',
+  debugSpringStiffness: '弹簧刚度',
+  debugSpringDamping: '弹簧阻尼',
+  debugSpringMass: '弹簧质量',
+  debugRunway: '预测预留空间',
+  debugReserveResponse: '预留响应时间',
+  debugBackpressureMin: '最小背压倍率',
+  debugTipRevealMultiplier: '整体文字揭示速度倍率。调大能更快清空积压，但可能显得跳；调小更平滑，但完成回复需要更久。',
+  debugTipQueuePressure: '积压对加速的影响强度。调大能更积极追赶增长中的队列；调小速度更稳定，但积压可能持续。',
+  debugTipMaxReveal: '每秒揭示字符数上限。调大允许更快追赶；调小限制突发速度，让动作更平稳。',
+  debugTipSpringStiffness: '滚动弹簧刚度。调大更快收拢视觉滞后，但感觉更硬；调小更柔和，但跟随更慢。',
+  debugTipSpringDamping: '滚动能量阻尼。调大能抑制过冲和抖动，但感觉更沉；调小更灵活，但可能回弹。',
+  debugTipSpringMass: '滚动惯性。调大移动更慢更沉；调小反应更快，但可能显得突兀。',
+  debugTipRunway: '内容增长时预留的预测空白。调大更能吸收增长、保护底部跟随，但可能产生更大的可见空区；调小能减少空白，但可吸收滞后的空间也更少。',
+  debugTipReserveResponse: '预留空间打开或关闭的响应时间。调大变化更渐进；调小反应更快，但可能显得突变。',
+  debugTipBackpressureMin: '滚动压力下允许的最低揭示倍率。调大文字仍会较快前进，但视觉滞后可能增加；调小会更积极减速，以保护跟随平滑。',
   readOnly: '本部署的设置为只读。',
   loading: '正在加载插件设置…',
   unavailable: '当前连接无法访问插件设置。',

package/src/client/smooth-stream-card-controller.ts

@@ -1,8 +1,17 @@
 /** Staged form state for the plugin-owned smooth-stream settings RPC. */
 
 import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { DEFAULT_STREAM_SETTINGS } from '../settings.ts'
-import type { StreamInstallationKind, StreamSettingsView } from '../settings-api.ts'
+import {
+  DEFAULT_STREAM_DEBUG_TUNING,
+  DEFAULT_STREAM_SETTINGS,
+  type StreamDebugTuning,
+  type StreamSettings,
+} from '../settings.ts'
+import type {
+  StreamDebugSettingsView,
+  StreamInstallationKind,
+  StreamSettingsView,
+} from '../settings-api.ts'
 import type { SmoothStreamSettingsApi } from './smooth-stream-settings-api.ts'
 
 /** What the smooth-stream card renders. It remains visible while its Host RPC loads. */
@@ -12,7 +21,12 @@ export interface SmoothStreamCardState {
   dirty: boolean
   saving: boolean
   failed: boolean
+  enabled: boolean
   thinkAutoExpand: boolean
+  autoCollapse: boolean
+  debugEnabled: boolean
+  debugTuning: StreamDebugTuning
+  debugAvailable: boolean
   version: string | undefined
   installation: StreamInstallationKind
   canUpgrade: boolean
@@ -26,7 +40,7 @@ export interface SmoothStreamCardFace {
   hooks: {
     smoothStreamCard: SnapshotStore<SmoothStreamCardState>
   }
-  edit: (value: boolean) => void
+  edit: (patch: Partial<StreamSettings>) => void
   save: () => void
   discard: () => void
   reload: () => void
@@ -37,7 +51,9 @@ export interface SmoothStreamCardFace {
 export class SmoothStreamCardController {
   private readonly store = createSnapshotStore<SmoothStreamCardState>(this.projection())
   private loaded: StreamSettingsView | undefined
-  private staged: boolean | undefined
+  private loadedDebug: StreamDebugSettingsView | undefined
+  private stagedBase: Pick<StreamSettings, 'enabled' | 'thinkAutoExpand' | 'autoCollapse'> | undefined
+  private stagedDebug: Pick<StreamSettings, 'debugEnabled' | 'debugTuning'> | undefined
   private saving = false
   private failed = false
   private upgrading = false
@@ -72,15 +88,31 @@ export class SmoothStreamCardController {
   inject(): SmoothStreamCardFace {
     return {
       hooks: { smoothStreamCard: this.store },
-      edit: (value) => {
-        this.staged = value
+      edit: (patch) => {
+        if (this.saving) return
+        if (patch.enabled !== undefined || patch.thinkAutoExpand !== undefined || patch.autoCollapse !== undefined) {
+          this.stagedBase = {
+            ...this.baseValues(),
+            ...(patch.enabled === undefined ? {} : { enabled: patch.enabled }),
+            ...(patch.thinkAutoExpand === undefined ? {} : { thinkAutoExpand: patch.thinkAutoExpand }),
+            ...(patch.autoCollapse === undefined ? {} : { autoCollapse: patch.autoCollapse }),
+          }
+        }
+        if (this.loadedDebug !== undefined && (patch.debugEnabled !== undefined || patch.debugTuning !== undefined)) {
+          this.stagedDebug = {
+            ...this.debugValues(),
+            ...(patch.debugEnabled === undefined ? {} : { debugEnabled: patch.debugEnabled }),
+            ...(patch.debugTuning === undefined ? {} : { debugTuning: { ...this.debugValues().debugTuning, ...patch.debugTuning } }),
+          }
+        }
         this.failed = false
         this.publish()
       },
       save: () => { void this.save() },
       discard: () => {
-        if (this.staged === undefined && !this.failed) return
-        this.staged = undefined
+        if (this.stagedBase === undefined && this.stagedDebug === undefined && !this.failed) return
+        this.stagedBase = undefined
+        this.stagedDebug = undefined
         this.failed = false
         this.publish()
       },
@@ -93,10 +125,12 @@ export class SmoothStreamCardController {
     return {
       status: this.loadStatus,
       writable: this.loaded?.writable ?? false,
-      dirty: this.staged !== undefined,
+      dirty: this.stagedBase !== undefined || this.stagedDebug !== undefined,
       saving: this.saving,
       failed: this.failed,
-      thinkAutoExpand: this.staged ?? this.loaded?.thinkAutoExpand ?? DEFAULT_STREAM_SETTINGS.thinkAutoExpand,
+      ...this.baseValues(),
+      ...this.debugValues(),
+      debugAvailable: this.loadedDebug !== undefined,
       version: this.loaded?.version,
       installation: this.loaded?.installation ?? 'unmanaged',
       canUpgrade: this.loaded?.canUpgrade ?? false,
@@ -106,33 +140,82 @@ export class SmoothStreamCardController {
     }
   }
 
+  private baseValues(): Pick<StreamSettings, 'enabled' | 'thinkAutoExpand' | 'autoCollapse'> {
+    return this.stagedBase ?? {
+      enabled: this.loaded?.enabled ?? DEFAULT_STREAM_SETTINGS.enabled,
+      thinkAutoExpand: this.loaded?.thinkAutoExpand ?? DEFAULT_STREAM_SETTINGS.thinkAutoExpand,
+      autoCollapse: this.loaded?.autoCollapse ?? DEFAULT_STREAM_SETTINGS.autoCollapse,
+    }
+  }
+
+  private debugValues(): Pick<StreamSettings, 'debugEnabled' | 'debugTuning'> {
+    return this.stagedDebug ?? {
+      debugEnabled: this.loadedDebug?.debugEnabled ?? DEFAULT_STREAM_SETTINGS.debugEnabled,
+      debugTuning: this.loadedDebug?.tuning ?? DEFAULT_STREAM_DEBUG_TUNING,
+    }
+  }
+
+  /** Complete settings projection consumed by the live SettingsCell bridge. */
+  values(): StreamSettings {
+    return { ...this.baseValues(), ...this.debugValues() }
+  }
+
   private async load(): Promise<void> {
     const generation = ++this.loadGeneration
     this.loadStatus = 'loading'
     this.loaded = undefined
+    this.loadedDebug = undefined
     this.publish()
     try {
       const view = await this.api.read()
       if (generation !== this.loadGeneration) return
       this.loaded = view
       this.loadStatus = 'ready'
+      this.publish()
+      try {
+        const debug = await this.api.readDebug()
+        if (generation !== this.loadGeneration) return
+        this.loadedDebug = debug
+      } catch {
+        if (generation !== this.loadGeneration) return
+        // Older hosts expose the original settings endpoints only. Keep the
+        // card usable and hide debug-only controls until the host is upgraded.
+        this.loadedDebug = undefined
+      }
     } catch {
       if (generation !== this.loadGeneration) return
       this.loaded = undefined
+      this.loadedDebug = undefined
       this.loadStatus = 'unavailable'
     }
     this.publish()
   }
 
   private async save(): Promise<void> {
-    if (this.staged === undefined || this.saving || this.loaded?.writable !== true) return
-    const value = this.staged
+    if ((this.stagedBase === undefined && this.stagedDebug === undefined)
+      || this.saving || this.loaded?.writable !== true) return
+    const base = this.stagedBase
+    const debug = this.stagedDebug
     this.saving = true
     this.failed = false
     this.publish()
     try {
-      this.loaded = await this.api.write(value)
-      this.staged = undefined
+      if (base !== undefined) {
+        const combined = debug !== undefined && this.loadedDebug !== undefined
+        this.loaded = await this.api.write(combined ? { ...base, ...debug } : base)
+        this.stagedBase = undefined
+        if (combined) {
+          this.loadedDebug = {
+            debugEnabled: debug.debugEnabled,
+            tuning: { ...debug.debugTuning },
+          }
+          this.stagedDebug = undefined
+        }
+      }
+      if (debug !== undefined && this.loadedDebug !== undefined && this.stagedDebug !== undefined) {
+        this.loadedDebug = await this.api.writeDebug(debug)
+        this.stagedDebug = undefined
+      }
     } catch {
       this.failed = true
     }

package/src/client/smooth-stream-settings-api.ts

@@ -1,9 +1,11 @@
 /** Browser adapter for the Host-owned smooth-stream settings RPC. */
 
 import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import type { StreamDebugTuning, StreamSettings } from '../settings.ts'
 import {
   STREAM_SETTINGS_RPC,
   STREAM_SETTINGS_RPC_CHANNEL,
+  type StreamDebugSettingsView,
   type StreamSettingsView,
   type StreamUpgradeView,
 } from '../settings-api.ts'
@@ -20,7 +22,9 @@ function settingsView(value: unknown): StreamSettingsView {
     || typeof data.version !== 'string'
     || !['npm', 'development', 'unmanaged'].includes(data.installation as string)
     || typeof data.writable !== 'boolean'
+    || typeof data.enabled !== 'boolean'
     || typeof data.thinkAutoExpand !== 'boolean'
+    || typeof data.autoCollapse !== 'boolean'
     || typeof data.canUpgrade !== 'boolean') {
     throw new Error('dsh-smooth-stream: malformed settings response')
   }
@@ -33,6 +37,29 @@ function upgradeView(value: unknown): StreamUpgradeView {
   return { restartRequired: true }
 }
 
+function debugSettingsView(value: unknown): StreamDebugSettingsView {
+  const data = record(value)
+  const tuning = record(data?.tuning)
+  if (data === undefined
+    || typeof data.debugEnabled !== 'boolean'
+    || tuning === undefined
+    || typeof tuning.revealScale !== 'number'
+    || typeof tuning.queuePressure !== 'number'
+    || typeof tuning.maxRevealCps !== 'number'
+    || typeof tuning.springStiffness !== 'number'
+    || typeof tuning.springDamping !== 'number'
+    || typeof tuning.springMass !== 'number'
+    || typeof tuning.runwayPx !== 'number'
+    || typeof tuning.reserveResponseMs !== 'number'
+    || typeof tuning.backpressureMinScale !== 'number') {
+    throw new Error('dsh-smooth-stream: malformed debug settings response')
+  }
+  return {
+    debugEnabled: data.debugEnabled,
+    tuning: tuning as unknown as StreamDebugTuning,
+  }
+}
+
 function accepted(result: Awaited<ReturnType<ConnectionHandle['rpc']['call']>>): unknown {
   if (!result.ok) throw new Error(result.error.message)
   return result.value
@@ -41,7 +68,9 @@ function accepted(result: Awaited<ReturnType<ConnectionHandle['rpc']['call']>>):
 /** Narrow client contract consumed by the staged settings-card controller. */
 export interface SmoothStreamSettingsApi {
   read(): Promise<StreamSettingsView>
-  write(thinkAutoExpand: boolean): Promise<StreamSettingsView>
+  write(settings: Pick<StreamSettings, 'enabled' | 'thinkAutoExpand' | 'autoCollapse'> & Partial<Pick<StreamSettings, 'debugEnabled' | 'debugTuning'>>): Promise<StreamSettingsView>
+  readDebug(): Promise<StreamDebugSettingsView>
+  writeDebug(settings: Pick<StreamSettings, 'debugEnabled' | 'debugTuning'>): Promise<StreamDebugSettingsView>
   upgrade(): Promise<StreamUpgradeView>
 }
 
@@ -51,11 +80,32 @@ export function createSmoothStreamSettingsApi(connection: ConnectionHandle): Smo
     async read(): Promise<StreamSettingsView> {
       return settingsView(accepted(await connection.rpc.call(STREAM_SETTINGS_RPC_CHANNEL, STREAM_SETTINGS_RPC.read, {})))
     },
-    async write(thinkAutoExpand: boolean): Promise<StreamSettingsView> {
+    async write(settings: Pick<StreamSettings, 'enabled' | 'thinkAutoExpand' | 'autoCollapse'> & Partial<Pick<StreamSettings, 'debugEnabled' | 'debugTuning'>>): Promise<StreamSettingsView> {
       return settingsView(accepted(await connection.rpc.call(
         STREAM_SETTINGS_RPC_CHANNEL,
         STREAM_SETTINGS_RPC.write,
-        { thinkAutoExpand },
+        {
+          enabled: settings.enabled,
+          thinkAutoExpand: settings.thinkAutoExpand,
+          autoCollapse: settings.autoCollapse,
+          ...(settings.debugEnabled === undefined || settings.debugTuning === undefined
+            ? {}
+            : { debugEnabled: settings.debugEnabled, debugTuning: settings.debugTuning }),
+        },
+      )))
+    },
+    async readDebug(): Promise<StreamDebugSettingsView> {
+      return debugSettingsView(accepted(await connection.rpc.call(
+        STREAM_SETTINGS_RPC_CHANNEL,
+        STREAM_SETTINGS_RPC.debugRead,
+        {},
+      )))
+    },
+    async writeDebug(settings: Pick<StreamSettings, 'debugEnabled' | 'debugTuning'>): Promise<StreamDebugSettingsView> {
+      return debugSettingsView(accepted(await connection.rpc.call(
+        STREAM_SETTINGS_RPC_CHANNEL,
+        STREAM_SETTINGS_RPC.debugWrite,
+        { debugEnabled: settings.debugEnabled, tuning: settings.debugTuning },
       )))
     },
     async upgrade(): Promise<StreamUpgradeView> {