dsh-smooth-stream 0.5.0 → 0.6.1

package/src/client/useLogarithmicFade.ts

@@ -0,0 +1,293 @@
+import { useLayoutEffect, useRef, type RefObject } from 'react'
+import css from './LogarithmicFade.module.css'
+
+export const FADE_DURATION_MS = 240
+export const FADE_TAIL_SIZE = 24
+export const FADE_MAX_TAIL_SIZE = 160
+export const FADE_MIN_OPACITY = 0
+const FADE_STEPS = 32
+const PREFIX = 'dsh-smooth-stream-log-fade-'
+const COLOR_PROPERTY = '--dsh-smooth-stream-fade-color'
+// Lightning CSS scopes highlight identifiers as well as class names.
+const highlightName = (index: number): string => css[`${PREFIX}${index}`] ?? `${PREFIX}${index}`
+const EXCLUDED = 'pre,code,math,.katex,.katex-display,mjx-container,svg,script,style,textarea,input,button,select,[role="button"],[contenteditable],[hidden],[aria-hidden="true"],[aria-live]'
+
+export function logarithmicOpacity(progress: number): number {
+  const p = Number.isFinite(progress) ? Math.max(0, Math.min(1, progress)) : 1
+  // Reverse the log easing: preserve translucency early, then settle to ink.
+  return FADE_MIN_OPACITY + (1 - FADE_MIN_OPACITY) * (1 - Math.log1p(5 * (1 - p)) / Math.log(6))
+}
+
+export function fadeTailSize(speedCps: number): number {
+  const speed = Number.isFinite(speedCps) ? Math.max(0, speedCps) : 0
+  return Math.min(FADE_MAX_TAIL_SIZE, Math.max(FADE_TAIL_SIZE, Math.ceil(speed * FADE_DURATION_MS / 1000)))
+}
+
+interface FadeCharacter {
+  start: number
+  end: number
+  born: number
+  range: Range
+  bucket: number
+}
+
+interface Scheduler {
+  highlights: Highlight[]
+  clients: Set<LogarithmicFadeController>
+  pending: Set<LogarithmicFadeController>
+  frame: number
+  registry: HighlightRegistry
+  window: Window
+}
+
+const schedulers = new WeakMap<Document, Scheduler>()
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+
+function schedule(scheduler: Scheduler): void {
+  if (scheduler.frame !== 0 || scheduler.pending.size === 0) return
+  scheduler.frame = scheduler.window.requestAnimationFrame((now) => {
+    scheduler.frame = 0
+    for (const client of scheduler.pending) {
+      if (!client.paint(now)) scheduler.pending.delete(client)
+    }
+    schedule(scheduler)
+  })
+}
+
+function schedulerFor(root: HTMLElement): Scheduler | null {
+  const doc = root.ownerDocument
+  const win = doc.defaultView
+  if (win === null) return null
+  // Use the root's realm, including when a renderer lives in another document.
+  const realm = win as Window & typeof globalThis
+  if (typeof realm.Highlight !== 'function' || !realm.CSS?.highlights
+    || !realm.CSS.supports('color', 'color-mix(in srgb, currentColor 15%, transparent)')) return null
+  let scheduler = schedulers.get(doc)
+  if (scheduler === undefined) {
+    const highlights = Array.from({ length: FADE_STEPS }, () => new realm.Highlight())
+    for (const [index, highlight] of highlights.entries()) realm.CSS.highlights.set(highlightName(index), highlight)
+    scheduler = {
+      highlights,
+      clients: new Set(),
+      pending: new Set(),
+      frame: 0,
+      registry: realm.CSS.highlights,
+      window: win,
+    }
+    schedulers.set(doc, scheduler)
+  }
+  return scheduler
+}
+
+/** Owns ranges only: React retains ownership of every element and Text node. */
+export class LogarithmicFadeController {
+  private previous = ''
+  private characters: FadeCharacter[] = []
+  private colors = new Map<HTMLElement, { value: string, priority: string }>()
+  private enabled = false
+  private active = false
+  private speedCps = 100
+  private pausedAt: number | null = null
+  private disposed = false
+  private readonly observer: MutationObserver
+
+  private constructor(private readonly root: HTMLElement, private readonly scheduler: Scheduler) {
+    scheduler.clients.add(this)
+    const win = root.ownerDocument.defaultView as Window & typeof globalThis
+    this.observer = new win.MutationObserver(() => { this.reconcile() })
+    this.observer.observe(root, { subtree: true, childList: true, characterData: true })
+  }
+
+  static create(root: HTMLElement): LogarithmicFadeController | null {
+    const scheduler = schedulerFor(root)
+    return scheduler === null ? null : new LogarithmicFadeController(root, scheduler)
+  }
+
+  update(enabled: boolean, active: boolean, speedCps = 100, paused = false): void {
+    const now = this.scheduler.window.performance.now()
+    if (paused && this.pausedAt === null) this.pausedAt = now
+    if (!paused && this.pausedAt !== null) {
+      const pauseDuration = now - this.pausedAt
+      for (const character of this.characters) character.born += pauseDuration
+      this.pausedAt = null
+    }
+    this.enabled = enabled
+    this.active = active
+    this.speedCps = speedCps
+    this.reconcile()
+  }
+
+  private clearRanges(): void {
+    for (const character of this.characters) {
+      this.scheduler.highlights[character.bucket]?.delete(character.range)
+    }
+    this.characters = []
+    this.restoreColors()
+  }
+
+  private restoreColors(): void {
+    for (const [element, original] of this.colors) {
+      if (original.value === '') element.style.removeProperty(COLOR_PROPERTY)
+      else element.style.setProperty(COLOR_PROPERTY, original.value, original.priority)
+    }
+    this.colors.clear()
+  }
+
+  private preserveColor(element: HTMLElement): void {
+    if (this.colors.has(element)) return
+    const color = this.scheduler.window.getComputedStyle(element).color
+    this.colors.set(element, {
+      value: element.style.getPropertyValue(COLOR_PROPERTY),
+      priority: element.style.getPropertyPriority(COLOR_PROPERTY),
+    })
+    // An explicit source color prevents highlight inheritance from multiplying
+    // alpha through nested Markdown elements (root → paragraph → strong).
+    element.style.setProperty(COLOR_PROPERTY, color)
+  }
+
+  private reconcile(): void {
+    if (this.disposed) return
+    const text = this.root.textContent ?? ''
+    const previous = this.previous
+    this.previous = text
+    const old = this.characters
+    this.clearRanges()
+    if (!this.enabled) {
+      this.root.classList.remove(css.scope!)
+      this.scheduler.pending.delete(this)
+      this.stopIfIdle()
+      return
+    }
+    this.root.classList.add(css.scope!)
+    const now = this.pausedAt ?? this.scheduler.window.performance.now()
+    // A parser rewrite must not replay already readable content. Retain only
+    // the unchanged prefix; future appends resume the effect normally.
+    let prefix = 0
+    while (prefix < previous.length && prefix < text.length && previous[prefix] === text[prefix]) prefix += 1
+    const appended = text.startsWith(previous)
+    const nodes: { node: Text, start: number, end: number, eligible: boolean }[] = []
+    const walker = this.root.ownerDocument.createTreeWalker(this.root, NodeFilter.SHOW_TEXT)
+    let offset = 0
+    for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+      const end = offset + (node.textContent?.length ?? 0)
+      nodes.push({ node: node as Text, start: offset, end, eligible: node.parentElement?.closest(EXCLUDED) === null })
+      offset = end
+    }
+    // containing() walks backwards by grapheme without segmenting the entire
+    // answer into an array. Offsets still refer to the original DOM text.
+    const segments = segmenter.segment(text)
+    // Keep existing characters alive when the engine resets its speed during
+    // completion. A shrinking window must not abruptly darken the old tail.
+    const tailSize = fadeTailSize(this.speedCps)
+    const oldestLiveStart = old.reduce((start, character) => (
+      now - character.born < FADE_DURATION_MS && character.end <= prefix
+        ? Math.min(start, character.start)
+        : start
+    ), Infinity)
+    let end = text.length
+    for (let count = 0; count < FADE_MAX_TAIL_SIZE && end > 0 && (count < tailSize || end > oldestLiveStart); count += 1) {
+      const segment = segments.containing(end - 1)
+      if (segment === undefined) break
+      const start = segment.index
+      const parts = nodes.filter(node => node.end > start && node.start < end)
+      const retained = old.find(character => character.start === start && character.end === end && end <= prefix)
+      const born = retained?.born ?? (this.active && appended && start >= previous.length ? now : null)
+      if (born !== null && now - born < FADE_DURATION_MS && segment.segment.trim() !== ''
+        && parts.length > 0 && parts.every(part => part.eligible)) {
+        const first = parts[0]!
+        const last = parts[parts.length - 1]!
+        const range = this.root.ownerDocument.createRange()
+        range.setStart(first.node, start - first.start)
+        range.setEnd(last.node, end - last.start)
+        for (const part of parts) this.preserveColor(part.node.parentElement!)
+        this.characters.push({ start, end, born, range, bucket: -1 })
+      }
+      end = start
+    }
+    if (this.paint(now)) {
+      if (this.pausedAt === null) {
+        this.scheduler.pending.add(this)
+        schedule(this.scheduler)
+      } else {
+        this.scheduler.pending.delete(this)
+        this.stopIfIdle()
+      }
+    } else {
+      this.scheduler.pending.delete(this)
+      this.stopIfIdle()
+    }
+  }
+
+  paint(now: number): boolean {
+    this.characters = this.characters.filter((character) => {
+      const progress = (now - character.born) / FADE_DURATION_MS
+      if (progress >= 1 || !this.root.isConnected || !this.root.contains(character.range.startContainer)) {
+        this.scheduler.highlights[character.bucket]?.delete(character.range)
+        return false
+      }
+      const bucket = Math.min(FADE_STEPS - 1, Math.round((logarithmicOpacity(progress) - FADE_MIN_OPACITY) / (1 - FADE_MIN_OPACITY) * (FADE_STEPS - 1)))
+      if (bucket !== character.bucket) {
+        this.scheduler.highlights[character.bucket]?.delete(character.range)
+        this.scheduler.highlights[bucket]!.add(character.range)
+        character.bucket = bucket
+      }
+      return true
+    })
+    if (this.characters.length === 0) this.restoreColors()
+    return this.characters.length > 0
+  }
+
+  private stopIfIdle(): void {
+    if (this.scheduler.pending.size !== 0) return
+    this.scheduler.window.cancelAnimationFrame(this.scheduler.frame)
+    this.scheduler.frame = 0
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.observer.disconnect()
+    this.clearRanges()
+    this.root.classList.remove(css.scope!)
+    this.scheduler.pending.delete(this)
+    this.scheduler.clients.delete(this)
+    this.stopIfIdle()
+    if (this.scheduler.clients.size === 0) {
+      for (const [index, highlight] of this.scheduler.highlights.entries()) {
+        const name = highlightName(index)
+        if (this.scheduler.registry.get(name) === highlight) this.scheduler.registry.delete(name)
+      }
+      schedulers.delete(this.root.ownerDocument)
+    }
+  }
+}
+
+/** active admits new characters; enabled=false also cancels completion linger. */
+export function useLogarithmicFade(
+  rootRef: RefObject<HTMLElement | null>,
+  enabled: boolean,
+  active: boolean,
+  speedCpsRef?: { current: number },
+  paused = false,
+): void {
+  const controller = useRef<LogarithmicFadeController | null>(null)
+  const committed = useRef(false)
+  useLayoutEffect(() => {
+    return () => {
+      controller.current?.dispose()
+      controller.current = null
+    }
+  }, [rootRef])
+  // Deliberately commit-driven, including Markdown updates with unchanged source.
+  useLayoutEffect(() => {
+    const root = rootRef.current
+    // Settled history allocates neither observers nor highlight buckets.
+    if (controller.current === null && root !== null && enabled && active) {
+      controller.current = LogarithmicFadeController.create(root)
+      // Enabling midway through a message must not replay readable text.
+      if (committed.current) controller.current?.update(false, false)
+    }
+    controller.current?.update(enabled, active, speedCpsRef?.current, paused)
+    committed.current = true
+  })
+}

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,7 +57,13 @@ 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),
+  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),
@@ -118,7 +125,9 @@ export function apply(ctx: Context, config: Config): void {
           writable: connectionCtx.settings.writable,
           enabled: settings.enabled,
           controlScroll: settings.controlScroll,
+          motionPreference: settings.motionPreference,
           thinkAutoExpand: settings.thinkAutoExpand,
+          logarithmicFade: settings.logarithmicFade,
           canUpgrade: installation.kind === 'npm',
         }
       }
@@ -185,10 +194,37 @@ export function apply(ctx: Context, config: Config): void {
             const next = payload as {
               enabled: boolean
               controlScroll: boolean
+              motionPreference?: unknown
               thinkAutoExpand: boolean
+              logarithmicFade?: unknown
               debugEnabled?: unknown
               debugTuning?: unknown
             }
+            if (
+              next.motionPreference !== undefined
+              && next.motionPreference !== 'auto'
+              && next.motionPreference !== 'force-smooth'
+              && next.motionPreference !== 'force-reduced'
+            ) {
+              return {
+                ok: false,
+                error: {
+                  code: 'settings-rejected',
+                  message: 'motionPreference must be one of auto | force-smooth | force-reduced',
+                  details: { ns: STREAM_SETTINGS_NS },
+                },
+              }
+            }
+            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 {
@@ -203,7 +239,9 @@ export function apply(ctx: Context, config: Config): void {
             await scope.update({
               enabled: next.enabled,
               controlScroll: next.controlScroll,
+              ...(next.motionPreference === undefined ? {} : { motionPreference: next.motionPreference }),
               thinkAutoExpand: next.thinkAutoExpand,
+              ...(next.logarithmicFade === undefined ? {} : { logarithmicFade: next.logarithmicFade }),
               ...(hasDebug ? { debugEnabled: next.debugEnabled, debugTuning: next.debugTuning } : {}),
             })
           } catch {
@@ -285,10 +323,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,8 +27,12 @@ export interface StreamSettingsView {
   enabled: boolean
   /** Whether smooth-stream also owns conversation bottom-follow. */
   controlScroll: boolean
+  /** 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,277 @@
+/**
+ * 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 {
+  const connection = ctx.get('connection') as ChannelConnection | undefined
+  return ctx.effect(() => {
+    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 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.
+ */
+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') {
+    throw new Error(
+      `dsh-smooth-stream: connection.requestRejection is unavailable, so ${channel} `
+      + 'cannot be mounted behind the connection trust fence',
+    )
+  }
+  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' }
+  }
+}