dsh-smooth-stream 0.6.0 → 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

@@ -9,6 +9,7 @@ import { DEFAULT_STREAM_CONFIG, type StreamConfig } from './config.ts'
 import { injectStreamConfig } from './boot-config.ts'
 import { STREAM_PACKAGE_NAME, STREAM_PACKAGE_VERSION } from './package-meta.ts'
 import { inspectProfileInstallation, updateNpmProfilePackage } from './profile-installation.ts'
+import { registerSettingsChannel } from './settings-channel.ts'
 import {
   STREAM_SETTINGS_RPC,
   STREAM_SETTINGS_RPC_CHANNEL,
@@ -56,12 +57,18 @@ 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'),
     Schema.const('force-reduced'),
   ] as const).default(DEFAULT_STREAM_SETTINGS.motionPreference),
   thinkAutoExpand: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.thinkAutoExpand),
+  logarithmicFade: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.logarithmicFade),
   debugEnabled: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.debugEnabled),
   debugTuning: Schema.object({
     revealScale: Schema.number().min(0.25).max(2).default(DEFAULT_STREAM_SETTINGS.debugTuning.revealScale),
@@ -100,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
@@ -123,8 +182,10 @@ 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,
           canUpgrade: installation.kind === 'npm',
         }
       }
@@ -191,11 +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'
@@ -211,6 +289,16 @@ export function apply(ctx: Context, config: Config): void {
                 },
               }
             }
+            if (next.logarithmicFade !== undefined && typeof next.logarithmicFade !== 'boolean') {
+              return {
+                ok: false,
+                error: {
+                  code: 'settings-rejected',
+                  message: 'logarithmicFade must be a boolean',
+                  details: { ns: STREAM_SETTINGS_NS },
+                },
+              }
+            }
             const hasDebug = next.debugEnabled !== undefined || next.debugTuning !== undefined
             if (hasDebug && (typeof next.debugEnabled !== 'boolean' || !validDebugTuning(next.debugTuning))) {
               return {
@@ -225,8 +313,10 @@ 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 }),
               ...(hasDebug ? { debugEnabled: next.debugEnabled, debugTuning: next.debugTuning } : {}),
             })
           } catch {
@@ -308,10 +398,7 @@ export function apply(ctx: Context, config: Config): void {
         }
         return { ok: false, error: { code: 'internal', message: `unknown smooth-stream endpoint ${JSON.stringify(endpoint)}`, details: {} } }
       }
-      connectionCtx.effect(
-        () => connectionCtx.connection.rpc.handle(STREAM_SETTINGS_RPC_CHANNEL, handle, { authority: 'loopback' }),
-        'dsh-smooth-stream: settings RPC',
-      )
+      registerSettingsChannel(connectionCtx, STREAM_SETTINGS_RPC_CHANNEL, handle)
     })
   })
 }

package/src/settings-api.ts

@@ -27,10 +27,14 @@ 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. */
   thinkAutoExpand: boolean
+  /** Whether new answer/thinking text fades into its original color. */
+  logarithmicFade: boolean
   /** Whether a fixed npm update command is safe to offer. */
   canUpgrade: boolean
 }

package/src/settings-channel.ts

@@ -0,0 +1,303 @@
+/**
+ * Host-side registration of the plugin-owned settings RPC channel.
+ *
+ * The documented path is `connection.rpc.handle()`, and it is tried first: that
+ * service owns the channel's trust policy and its physical route. Some shipped
+ * kernel generations resolve `webServer` from inside that service through a
+ * Context that never injected it, so the call throws
+ * (`cannot get property "webServer" without inject`) and the channel is never
+ * mounted — the browser then reports the settings card as unreachable.
+ *
+ * When the service call fails, this module mounts the same absolute channel
+ * prefix directly on `webServer`, behind the connection service's own request
+ * fence and speaking the documented request/response envelopes. Nothing here
+ * weakens the fence: a kernel without `requestRejection` fails closed instead
+ * of exposing the channel to whoever can reach the port. The fallback retires
+ * on its own the moment the service call works again.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { ConnectionRpcHandler } from '@deepseek-ai/dsh-client-connection'
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
+
+/** Largest request body this channel buffers; settings payloads are tiny. */
+const MAX_REQUEST_BYTES = 1 << 20
+
+/** Endpoint segment shape accepted by the Connection router, mirrored here. */
+const ENDPOINT_SEGMENT = /^[A-Za-z0-9_$.-]+$/
+
+/** Envelope discriminator the browser caller sends. */
+const CLIENT_REQUEST = 'client-request'
+
+/** Envelope discriminator the browser caller expects back. */
+const SERVER_RESPONSE = 'server-response'
+
+/** One decoded browser request. */
+interface RequestEnvelope {
+  readonly rpcId: string
+  readonly method: string
+  readonly payload: unknown
+}
+
+/** The subset of the Host Connection handle this module depends on. */
+interface ChannelConnection {
+  readonly rpc?: {
+    handle?: (
+      channel: string,
+      handler: ConnectionRpcHandler,
+      options: { readonly authority: 'loopback' },
+    ) => unknown
+  }
+  readonly requestRejection?: (request: unknown) => 401 | 403 | undefined
+}
+
+/** The subset of the Web server service this module depends on. */
+interface ChannelWebServer {
+  register(route: WebRoute): () => void
+}
+
+/** Body read outcome, kept distinct so the reply can name the real failure. */
+type BodyRead =
+  | { readonly kind: 'value'; readonly value: unknown }
+  | { readonly kind: 'invalid' }
+  | { readonly kind: 'too-large' }
+
+/**
+ * Register the settings RPC channel on the most capable path the kernel has.
+ * The registration is an effect of `ctx`, so the caller's fiber owns the
+ * channel's lifetime on either path.
+ * @param ctx - Host context carrying `connection` and, when composed, `webServer`.
+ * @param channel - absolute channel prefix, e.g. `/smooth-stream`.
+ * @param handler - decoded endpoint handler for every endpoint on the channel.
+ * @returns Disposer that withdraws the channel.
+ */
+export function registerSettingsChannel(
+  ctx: Context,
+  channel: string,
+  handler: ConnectionRpcHandler,
+): () => void {
+  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)
+  }, `dsh-smooth-stream: ${channel} RPC channel`)
+}
+
+/**
+ * Try the service-owned registration, which is the only path that also carries
+ * the kernel's own channel policy.
+ * @returns Disposer on success, `undefined` when the kernel cannot mount it.
+ */
+function tryServiceChannel(
+  connection: ChannelConnection | undefined,
+  channel: string,
+  handler: ConnectionRpcHandler,
+): (() => void) | undefined {
+  const rpc = connection?.rpc
+  if (rpc === undefined || typeof rpc.handle !== 'function') return undefined
+  try {
+    const release = rpc.handle(channel, handler, { authority: 'loopback' })
+    if (typeof release !== 'function') return undefined
+    return () => { void (release as () => unknown)() }
+  } catch (error) {
+    // A kernel that cannot resolve `webServer` inside the service throws here;
+    // the direct route below keeps the card reachable on that kernel.
+    console.warn(
+      `[dsh-smooth-stream] connection.rpc.handle() could not mount ${channel}; `
+      + 'falling back to a directly registered route',
+      error,
+    )
+    return undefined
+  }
+}
+
+/**
+ * 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,
+  connection: ChannelConnection | undefined,
+  channel: string,
+  handler: ConnectionRpcHandler,
+): () => void {
+  const webServer = ctx.get('webServer') as ChannelWebServer | undefined
+  const reject = connection?.requestRejection
+  if (webServer === undefined || typeof webServer.register !== 'function') {
+    throw new Error(`dsh-smooth-stream: webServer is unavailable, so ${channel} cannot be mounted`)
+  }
+  if (typeof reject !== 'function') {
+    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)
+      if (rejection !== undefined) {
+        res.writeHead(rejection)
+        res.end(rejection === 401 ? 'unauthorized' : 'forbidden')
+        return
+      }
+      await answer(req, res, channel, handler)
+    },
+  })
+}
+
+/**
+ * Decode one request envelope, dispatch it, and write the decoded reply.
+ * Mirrors the Connection router's own carrier rules: method and endpoint must
+ * agree, the body must be JSON, and only endpoint failures are results while
+ * transport failures are statuses.
+ */
+async function answer(
+  req: Parameters<WebRoute['handler']>[0],
+  res: Parameters<WebRoute['handler']>[1],
+  channel: string,
+  handler: ConnectionRpcHandler,
+): Promise<void> {
+  const endpoint = endpointOf(channel, req.url)
+  if (req.method !== 'POST' || endpoint === undefined) {
+    res.writeHead(404)
+    res.end('not found')
+    return
+  }
+  const mediaType = (req.headers['content-type'] ?? '').split(';', 1)[0]?.trim().toLowerCase()
+  if (mediaType !== 'application/json') {
+    res.writeHead(415)
+    res.end('content type must be application/json')
+    return
+  }
+  const body = await readBody(req)
+  if (body.kind === 'too-large') {
+    res.writeHead(413)
+    res.end('request body too large')
+    return
+  }
+  if (body.kind === 'invalid') {
+    res.writeHead(400)
+    res.end('body is not JSON')
+    return
+  }
+  const envelope = requestEnvelope(body.value)
+  if (envelope === undefined) {
+    write(res, rpcIdOf(body.value), {
+      ok: false,
+      error: {
+        code: 'gateway/bad-request',
+        message: 'invalid client-request message',
+        details: { issues: [] },
+      },
+    })
+    return
+  }
+  if (envelope.method !== endpoint) {
+    write(res, envelope.rpcId, {
+      ok: false,
+      error: {
+        code: 'gateway/bad-request',
+        message: `method ${JSON.stringify(envelope.method)} does not match endpoint ${JSON.stringify(endpoint)}`,
+        details: { issues: [] },
+      },
+    })
+    return
+  }
+  const controller = new AbortController()
+  res.on('close', () => { controller.abort() })
+  try {
+    write(res, envelope.rpcId, await handler(endpoint, envelope.payload, controller.signal))
+  } catch (error) {
+    res.writeHead(500)
+    res.end(`handler failure: ${String(error)}`)
+  }
+}
+
+/**
+ * Resolve the channel-relative endpoint for one request path.
+ * @returns The endpoint, or `undefined` when the path is outside the channel
+ * or carries a segment the Connection router would refuse.
+ */
+function endpointOf(channel: string, rawUrl: string | undefined): string | undefined {
+  const pathname = new URL(rawUrl ?? '/', 'http://dsh.internal').pathname
+  if (!pathname.startsWith(`${channel}/`)) return undefined
+  const endpoint = pathname.slice(channel.length + 1)
+  const segments = endpoint.split('/')
+  if (segments.some(segment =>
+    segment === '' || segment === '.' || segment === '..' || !ENDPOINT_SEGMENT.test(segment))) {
+    return undefined
+  }
+  return endpoint
+}
+
+/** Structure one decoded request, rejecting anything the caller could not have sent. */
+function requestEnvelope(value: unknown): RequestEnvelope | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined
+  const record = value as Record<string, unknown>
+  if (record.type !== CLIENT_REQUEST) return undefined
+  if (typeof record.rpcId !== 'string' || typeof record.method !== 'string') return undefined
+  return { rpcId: record.rpcId, method: record.method, payload: record.payload }
+}
+
+/** Recover the correlation id of a malformed envelope so the caller can match it. */
+function rpcIdOf(value: unknown): string {
+  const raw = (value as { rpcId?: unknown } | null)?.rpcId
+  return typeof raw === 'string' ? raw : 'invalid-request'
+}
+
+/** Write one decoded reply in the envelope the browser caller parses. */
+function write(
+  res: Parameters<WebRoute['handler']>[1],
+  rpcId: string,
+  result: unknown,
+): void {
+  res.writeHead(200, { 'content-type': 'application/json' })
+  res.end(JSON.stringify({ type: SERVER_RESPONSE, rpcId, result }))
+}
+
+/** Buffer one request body, refusing both malformed JSON and unbounded input. */
+async function readBody(req: Parameters<WebRoute['handler']>[0]): Promise<BodyRead> {
+  const chunks: Buffer[] = []
+  let bytes = 0
+  for await (const chunk of req) {
+    const buffer = chunk as Buffer
+    bytes += buffer.length
+    if (bytes > MAX_REQUEST_BYTES) return { kind: 'too-large' }
+    chunks.push(buffer)
+  }
+  try {
+    return { kind: 'value', value: JSON.parse(Buffer.concat(chunks).toString('utf8')) }
+  } catch {
+    return { kind: 'invalid' }
+  }
+}

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
@@ -86,6 +95,8 @@ export interface StreamSettings {
    * it by hand — and stops the running state from re-owning the disclosure.
    */
   thinkAutoExpand: boolean
+  /** Logarithmic text fade for the answer and expanded thinking body. */
+  logarithmicFade: boolean
   /** Whether the live renderer diagnostics panel is enabled. */
   debugEnabled: boolean
   /** Values edited by the diagnostics panel. */
@@ -96,8 +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,
 }
+