dsh-smooth-stream 0.6.1 → 0.7.0

package/src/client/useProgressiveDomText.ts

@@ -11,6 +11,7 @@
 import { useLayoutEffect, type RefObject } from 'react'
 import { computeAdaptiveQueueStep } from './useSmoothStreamContent.ts'
 import { debugRuntime } from './debugRuntime.ts'
+import { FrameCoordinator } from './FrameCoordinator.ts'
 
 interface TextRevealRecord {
   chars: readonly string[]
@@ -113,13 +114,20 @@ export function useProgressiveDomText(
 
     const pending = new Set<Text>()
     const internalWrites = new WeakMap<Text, string>()
-    let rafId = 0
+    let frameTaskId: string | null = null
     let lastFrame: number | null = null
     let debt = 0
     let stopped = false
     let announcedSettled = false
     const streamId = `dom-${Math.random().toString(36).slice(2)}`
 
+    const coordinator = FrameCoordinator.forDocument()
+    const stopFrameTask = (): void => {
+      if (frameTaskId === null) return
+      coordinator.unregisterTask(frameTaskId)
+      frameTaskId = null
+    }
+
     const announceSettled = (): void => {
       lastFrame = null
       debt = 0
@@ -173,22 +181,25 @@ export function useProgressiveDomText(
     }
 
     const scheduleFrame = (): void => {
-      if (stopped || pending.size === 0 || rafId !== 0) return
-      rafId = requestAnimationFrame(frame)
+      if (stopped || pending.size === 0 || frameTaskId !== null) return
+      // Ride the shared document clock instead of a private rAF chain, so
+      // tool-output reveal cannot race the assistant reveal or the follower.
+      frameTaskId = coordinator.registerTask({
+        onSimulate: (_dtMs, now) => frame(now),
+      })
     }
 
-    const frame = (now: number): void => {
-      rafId = 0
-      if (stopped) return
+    const frame = (now: number): boolean => {
+      if (stopped) return false
       if (pending.size === 0) {
         announceSettled()
-        return
+        stopFrameTask()
+        return false
       }
       announcedSettled = false
       if (lastFrame === null) {
         lastFrame = now
-        scheduleFrame()
-        return
+        return true
       }
       const elapsed = Math.max(0, now - lastFrame)
       lastFrame = now
@@ -236,9 +247,14 @@ export function useProgressiveDomText(
         targetChars,
         displayedChars,
         active: pending.size > 0,
+        // This path reveals a node at a time and never observes the model
+        // stream's own end, so it cannot claim a terminal drain. Reporting
+        // `false` keeps the follower's terminal phase driven by the smoother
+        // that actually owns the completion signal.
+        producerComplete: false,
       })
       if (pending.size === 0) announceSettled()
-      else scheduleFrame()
+      return pending.size > 0
     }
 
     visit(root, revealInitial)
@@ -269,7 +285,7 @@ export function useProgressiveDomText(
 
     return () => {
       stopped = true
-      cancelAnimationFrame(rafId)
+      stopFrameTask()
       observer?.disconnect()
       for (const [node, record] of records) {
         const controlled = record.chars.slice(0, record.shown).join('')

package/src/client/useSmoothStreamContent.ts

@@ -434,18 +434,9 @@ export function useSmoothStreamContent(
       let revealSpeedCps: number
       let nextQueueDebt = 0
       if (producerComplete) {
-        // Backpressure protects live layout. Once input has ended, retaining
-        // that scale only makes a completed response keep typing onscreen.
-        // Keep one TARGET velocity for the whole completion tail — recomputing
-        // it from the shrinking backlog creates an exponential slow tail —
-        // but RAMP the effective velocity up from the last reveal speed over
-        // ~3 frames: an instant jump from streaming pace to max flush is
-        // itself a visible jerk at exactly the moment the reader is watching
-        // the reply finish.
-        // The pre-drain reveal speed is the streaming EMA, not the debug seed.
-        // Seeding the ramp from the 35cps default when the reply ran at the
-        // max-flush ceiling stretched a 420ms tail past the 800ms announcer
-        // step and the visible Markdown mutated across it.
+        // Completion uses one bounded target velocity rather than the
+        // backlog-pressure curve. The latter changes speed as the queue
+        // shrinks and visibly kicks the final wrapped lines.
         const previousCps = lastDrainCpsRef.current > 0
           ? lastDrainCpsRef.current
           : Math.max(config.minCps, emaCpsRef.current)
@@ -495,7 +486,8 @@ export function useSmoothStreamContent(
         speedCps: revealSpeedCps,
         targetChars: targetCount,
         displayedChars: displayedCount,
-        active: !producerComplete,
+        active: !producerComplete || backlog > 0,
+        producerComplete,
       })
 
       // Performance guard: while degraded and the reply is offscreen, skip

package/src/config.ts

@@ -33,7 +33,7 @@ export interface StreamConfig {
 /** Defaults shared by the Host schema and the client-side fallback. */
 export const DEFAULT_STREAM_CONFIG: StreamConfig = {
   mode: 'typewriter',
-  preset: 'balanced',
+  preset: 'silky',
   revealCharsPerSec: 80,
   scrollSpeedPxPerSec: 48,
   maxScrollSpeedPxPerSec: 1000,

package/src/plugin.ts

@@ -57,6 +57,11 @@ export const Config: Schema<Config> = Schema.object({
 export const StreamSettingsSchema: Schema<StreamSettings> = Schema.object({
   enabled: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.enabled),
   controlScroll: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.controlScroll),
+  preset: Schema.union([
+    Schema.const('realtime'),
+    Schema.const('balanced'),
+    Schema.const('silky'),
+  ] as const).default(DEFAULT_STREAM_SETTINGS.preset),
   motionPreference: Schema.union([
     Schema.const('auto'),
     Schema.const('force-smooth'),
@@ -102,16 +107,68 @@ export function apply(ctx: Context, config: Config): void {
   // the durable provider as the authority, but expose this one schema through
   // the plugin's own loopback-only connection channel instead.
   ctx.inject(['settings'], (settingsCtx) => {
-    // 0.1.2 kernels dropped the `settingsNamespace()` helper — a validating
-    // identity on ≤ 0.1.1 — and take the raw string, so the rc-era brand is
-    // reproduced locally instead of statically importing a removed symbol.
-    // The namespace is a compile-time constant matching the kernel's
-    // /^[a-z][a-z0-9-]*$/ pattern.
-    const settingsNamespace = STREAM_SETTINGS_NS as SettingsNamespace
-    const scope = settingsCtx.settings.register(
+  // dsh 0.1.x: durable plugin-owned namespace registered on the settings
+  // service. dsh 0.2.x: `register` is gone — SettingsForms owns persistence
+  // through profile entry config — so serve the card read-only from the
+  // composition config until that migration lands, and keep the channel
+  // reachable so the card renders instead of dying as a 405.
+  const settingsSvc = settingsCtx.settings
+  const legacyRegister = (settingsSvc as { register?: unknown }).register
+  if (typeof legacyRegister !== 'function') {
+    const view02 = (): StreamSettingsView => ({
+      version: STREAM_PACKAGE_VERSION,
+      installation: inspectProfileInstallation(ctx.baseUrl, STREAM_PACKAGE_NAME).kind,
+      writable: false,
+      enabled: DEFAULT_STREAM_SETTINGS.enabled,
+      controlScroll: DEFAULT_STREAM_SETTINGS.controlScroll,
+      preset: config.preset,
+      motionPreference: DEFAULT_STREAM_SETTINGS.motionPreference,
+      thinkAutoExpand: DEFAULT_STREAM_SETTINGS.thinkAutoExpand,
+      logarithmicFade: DEFAULT_STREAM_SETTINGS.logarithmicFade,
+      canUpgrade: false,
+    })
+    const handle02: ConnectionRpcHandler = async (endpoint) => {
+      if (endpoint === STREAM_SETTINGS_RPC.read) return { ok: true, value: view02() }
+      if (endpoint === STREAM_SETTINGS_RPC.debugRead) {
+        return { ok: true, value: { debugEnabled: DEFAULT_STREAM_SETTINGS.debugEnabled, tuning: DEFAULT_STREAM_SETTINGS.debugTuning } }
+      }
+      if (endpoint === STREAM_SETTINGS_RPC.upgrade) {
+        const installation = inspectProfileInstallation(ctx.baseUrl, STREAM_PACKAGE_NAME)
+        if (installation.kind !== 'npm') {
+          return { ok: false, error: { code: 'internal', message: 'smooth-stream is not an npm profile dependency', details: {} } }
+        }
+        return { ok: false, error: { code: 'internal', message: 'upgrade is unavailable until the 0.2.x settings migration lands', details: {} } }
+      }
+      return {
+        ok: false,
+        error: {
+          code: 'settings-rejected',
+          message: 'smooth-stream settings are read-only on dsh 0.2.x; durable storage moved to profile entry config',
+          details: { ns: STREAM_SETTINGS_NS },
+        },
+      }
+    }
+    // The connection service is not injectable from a plugin scope on 0.2.x,
+    // so mount through the web server fiber. registerSettingsChannel serves
+    // the route unfenced there (loopback + app token gate remain).
+    ctx.inject(['webServer'], (webCtx) => {
+      registerSettingsChannel(webCtx, STREAM_SETTINGS_RPC_CHANNEL, handle02)
+    })
+    return
+  }
+  const settingsNamespace = STREAM_SETTINGS_NS as SettingsNamespace
+  const scope = settingsCtx.settings.register(
       settingsNamespace,
       StreamSettingsSchema,
-      { applies: 'live' },
+      {
+        // The install-time entry config is the composition base, so it resolves
+        // *below* the user layer: a stored pick still wins, while "the user
+        // never chose" keeps following the overlay (cordis.patch.yml / profile
+        // config). Keeping it out of the schema default is what makes those two
+        // states distinguishable at all.
+        base: { preset: config.preset },
+        applies: 'live',
+      },
     )
     settingsCtx.inject(['connection'], (connectionCtx) => {
       let upgrade: Promise<void> | undefined
@@ -125,6 +182,7 @@ export function apply(ctx: Context, config: Config): void {
           writable: connectionCtx.settings.writable,
           enabled: settings.enabled,
           controlScroll: settings.controlScroll,
+          preset: settings.preset ?? config.preset,
           motionPreference: settings.motionPreference,
           thinkAutoExpand: settings.thinkAutoExpand,
           logarithmicFade: settings.logarithmicFade,
@@ -194,12 +252,28 @@ export function apply(ctx: Context, config: Config): void {
             const next = payload as {
               enabled: boolean
               controlScroll: boolean
+              preset?: unknown
               motionPreference?: unknown
               thinkAutoExpand: boolean
               logarithmicFade?: unknown
               debugEnabled?: unknown
               debugTuning?: unknown
             }
+            if (
+              next.preset !== undefined
+              && next.preset !== 'realtime'
+              && next.preset !== 'balanced'
+              && next.preset !== 'silky'
+            ) {
+              return {
+                ok: false,
+                error: {
+                  code: 'settings-rejected',
+                  message: 'preset must be one of realtime | balanced | silky',
+                  details: { ns: STREAM_SETTINGS_NS },
+                },
+              }
+            }
             if (
               next.motionPreference !== undefined
               && next.motionPreference !== 'auto'
@@ -239,6 +313,7 @@ export function apply(ctx: Context, config: Config): void {
             await scope.update({
               enabled: next.enabled,
               controlScroll: next.controlScroll,
+              ...(next.preset === undefined ? {} : { preset: next.preset }),
               ...(next.motionPreference === undefined ? {} : { motionPreference: next.motionPreference }),
               thinkAutoExpand: next.thinkAutoExpand,
               ...(next.logarithmicFade === undefined ? {} : { logarithmicFade: next.logarithmicFade }),

package/src/settings-api.ts

@@ -27,6 +27,8 @@ export interface StreamSettingsView {
   enabled: boolean
   /** Whether smooth-stream also owns conversation bottom-follow. */
   controlScroll: boolean
+  /** Smoothing preset for the reveal cadence and follow physics. */
+  preset: import('./settings.ts').StreamSmoothingPreset
   /** How the reveal honors the OS reduced-motion preference. */
   motionPreference: import('./settings.ts').StreamMotionPreference
   /** Current resolved preference. */

package/src/settings-channel.ts

@@ -76,8 +76,21 @@ export function registerSettingsChannel(
   channel: string,
   handler: ConnectionRpcHandler,
 ): () => void {
-  const connection = ctx.get('connection') as ChannelConnection | undefined
+  let connection: ChannelConnection | undefined
+  try {
+    connection = ctx.get('connection') as ChannelConnection | undefined
+  } catch {
+    // dsh 0.2.x: the connection service may be unresolvable from a plugin
+    // scope; the direct mount below then serves the channel unfenced.
+    connection = undefined
+  }
   return ctx.effect(() => {
+    try {
+      const direct = mountDirectRoute(ctx, connection, channel, handler)
+      if (direct !== undefined) return direct
+    } catch {
+      // fall through to the service path
+    }
     const viaService = tryServiceChannel(connection, channel, handler)
     if (viaService !== undefined) return viaService
     return mountDirectRoute(ctx, connection, channel, handler)
@@ -113,9 +126,15 @@ function tryServiceChannel(
 }
 
 /**
- * Mount the channel prefix on the Web server with the connection fence intact.
- * @throws when the kernel exposes neither the fence nor a Web server, so the
- * failure is reported instead of silently leaving the card unreachable.
+ * Mount the channel prefix on the Web server.
+ *
+ * With the connection service reachable the route sits behind the connection
+ * trust fence. On dsh 0.2.x the connection service is unresolvable from a
+ * plugin scope, so the route is then served unfenced (loopback + the app's
+ * own token gate only) with a warning — the same trade-off the skill center
+ * plugin ships on 0.2.x.
+ * @throws fail-closed when the connection service is reachable but cannot
+ * fence, so the channel is never exposed without the trust policy.
  */
 function mountDirectRoute(
   ctx: Context,
@@ -129,16 +148,23 @@ function mountDirectRoute(
     throw new Error(`dsh-smooth-stream: webServer is unavailable, so ${channel} cannot be mounted`)
   }
   if (typeof reject !== 'function') {
-    throw new Error(
-      `dsh-smooth-stream: connection.requestRejection is unavailable, so ${channel} `
-      + 'cannot be mounted behind the connection trust fence',
+    if (connection !== undefined) {
+      throw new Error(
+        `dsh-smooth-stream: connection.requestRejection is unavailable, so ${channel} `
+        + 'cannot be mounted behind the connection trust fence',
+      )
+    }
+    console.warn(
+      `[dsh-smooth-stream] ${channel} mounted without the connection trust fence `
+      + '(dsh 0.2.x: the connection service is not injectable here); '
+      + 'loopback and the app token gate remain the only protections',
     )
   }
   return webServer.register({
     kind: 'prefix',
     path: channel,
     handler: async (req, res) => {
-      const rejection = reject.call(connection, req)
+      const rejection = reject?.call(connection, req)
       if (rejection !== undefined) {
         res.writeHead(rejection)
         res.end(rejection === 401 ? 'unauthorized' : 'forbidden')

package/src/settings.ts

@@ -57,6 +57,11 @@ export type StreamMotionPreference =
   /** Always render raw text, ignoring the OS preference. */
   | 'force-reduced'
 
+/**
+ * Smoothing cadence and damping profile.
+ */
+export type StreamSmoothingPreset = 'realtime' | 'balanced' | 'silky'
+
 /**
  * Preferences a user may set. Deliberately separate from {@link StreamConfig}
  * because the two change at different times: composition-time values go
@@ -73,6 +78,10 @@ export interface StreamSettings {
    * scroll ownership to the Harness; text reveal still runs.
    */
   controlScroll: boolean
+  /**
+   * Smoothing preset for the reveal cadence and follow physics.
+   */
+  preset: StreamSmoothingPreset
   /**
    * How the reveal honors the OS reduced-motion preference. `auto` preserves
    * the accessibility-first default; `force-smooth` keeps the engine on
@@ -98,9 +107,11 @@ export interface StreamSettings {
 export const DEFAULT_STREAM_SETTINGS: StreamSettings = {
   enabled: true,
   controlScroll: true,
+  preset: 'silky',
   motionPreference: 'auto',
   thinkAutoExpand: true,
   logarithmicFade: true,
   debugEnabled: false,
   debugTuning: DEFAULT_STREAM_DEBUG_TUNING,
 }
+