dsh-smooth-stream 0.1.0 → 0.3.2

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

@@ -0,0 +1,65 @@
+/** Browser adapter for the Host-owned smooth-stream settings RPC. */
+
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import {
+  STREAM_SETTINGS_RPC,
+  STREAM_SETTINGS_RPC_CHANNEL,
+  type StreamSettingsView,
+  type StreamUpgradeView,
+} from '../settings-api.ts'
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
+}
+
+function settingsView(value: unknown): StreamSettingsView {
+  const data = record(value)
+  if (data === undefined
+    || typeof data.version !== 'string'
+    || !['npm', 'development', 'unmanaged'].includes(data.installation as string)
+    || typeof data.writable !== 'boolean'
+    || typeof data.thinkAutoExpand !== 'boolean'
+    || typeof data.canUpgrade !== 'boolean') {
+    throw new Error('dsh-smooth-stream: malformed settings response')
+  }
+  return data as unknown as StreamSettingsView
+}
+
+function upgradeView(value: unknown): StreamUpgradeView {
+  const data = record(value)
+  if (data?.restartRequired !== true) throw new Error('dsh-smooth-stream: malformed update response')
+  return { restartRequired: true }
+}
+
+function accepted(result: Awaited<ReturnType<ConnectionHandle['rpc']['call']>>): unknown {
+  if (!result.ok) throw new Error(result.error.message)
+  return result.value
+}
+
+/** Narrow client contract consumed by the staged settings-card controller. */
+export interface SmoothStreamSettingsApi {
+  read(): Promise<StreamSettingsView>
+  write(thinkAutoExpand: boolean): Promise<StreamSettingsView>
+  upgrade(): Promise<StreamUpgradeView>
+}
+
+/** Build the typed facade over the generic Connection RPC service. */
+export function createSmoothStreamSettingsApi(connection: ConnectionHandle): SmoothStreamSettingsApi {
+  return {
+    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> {
+      return settingsView(accepted(await connection.rpc.call(
+        STREAM_SETTINGS_RPC_CHANNEL,
+        STREAM_SETTINGS_RPC.write,
+        { thinkAutoExpand },
+      )))
+    },
+    async upgrade(): Promise<StreamUpgradeView> {
+      return upgradeView(accepted(await connection.rpc.call(STREAM_SETTINGS_RPC_CHANNEL, STREAM_SETTINGS_RPC.upgrade, {})))
+    },
+  }
+}

package/src/client/teleprompterGlide.ts

@@ -14,17 +14,15 @@
  * - while the port has scroll room, writes the interpolated lag as
  *   `translate3d` on `[data-chat-transcript]` (message rows only), so the
  *   turn-status chrome stays pinned at the floor;
- * - before the port has scroll room (content shorter than the viewport), the
- *   same lag is a content-height lag written as a negative translate on
- *   `[data-chat-turn-status]`, so the status label descends smoothly with
- *   each wrap instead of hopping a line at a time.
+ * - clips only the part of the translated surface that crosses the
+ *   turn-status line, preserving the normal gap above that line;
+ * - leaves `[data-chat-turn-status]` in normal flow at every height, so its
+ *   layout gap cannot be consumed by an interpolated transform.
  *
- * Handing the port back to the reader (unpin, or the owner going inactive)
- * first writes the effective visual top (`engine - lag`) into `scrollTop`
- * before clearing the transform, so the frame stays continuous. That write
- * also lands in ChatView's observed-top ledger as reader input beyond
- * `FOLLOW_THRESHOLD`, releasing its native snap-follow instead of fighting
- * the gesture for the port.
+ * A real reader unpin first writes the effective visual top (`engine - lag`)
+ * into `scrollTop` before clearing the transform, so the frame stays
+ * continuous. Lifecycle completion is different: without a reader gesture,
+ * the last owner settles at the floor and preserves bottom-follow.
  *
  * Unpin is a real gesture (wheel / touch / pointer / key) that leaves the
  * floor; a `scrollTop` delta from our own write must not release the pin.
@@ -136,35 +134,54 @@ function hasShiftSurface(port: HTMLElement): boolean {
   return shiftRootOf(port) !== null || shiftRowsOf(port).length > 0
 }
 
-function setShift(element: HTMLElement, px: number, negative = false): void {
-  const value = negative ? -px : px
-  if (Math.abs(value) > 0.01) {
-    element.style.transform = `translate3d(0, ${value}px, 0)`
+/** Cached natural gap from a shifted surface's bottom to the status line. */
+const statusGapCache = new WeakMap<HTMLElement, { chrome: HTMLElement; px: number }>()
+
+function currentShiftOf(element: HTMLElement): number {
+  return Number(/translate3d\(0, ([\d.]+)px, 0\)/.exec(element.style.transform)?.[1] ?? 0)
+}
+
+function statusGapBelow(surface: HTMLElement, chrome: HTMLElement): number {
+  const cached = statusGapCache.get(surface)
+  if (cached?.chrome === chrome) return cached.px
+  // getBoundingClientRect includes our current transform. Remove it to recover
+  // the layout bottom, then keep the existing gap available to the reveal.
+  const naturalBottom = surface.getBoundingClientRect().bottom - currentShiftOf(surface)
+  const px = Math.max(0, chrome.getBoundingClientRect().top - naturalBottom)
+  statusGapCache.set(surface, { chrome, px })
+  return px
+}
+
+function setShift(element: HTMLElement, px: number, paintAllowance?: number): void {
+  if (Math.abs(px) > 0.01) {
+    element.style.transform = `translate3d(0, ${px}px, 0)`
     element.style.willChange = 'transform'
+    const bottomClip = paintAllowance === undefined ? 0 : Math.max(0, px - paintAllowance)
+    element.style.clipPath = bottomClip > 0.01 ? `inset(0 0 ${bottomClip}px 0)` : ''
   } else {
     element.style.transform = ''
     element.style.willChange = ''
+    element.style.clipPath = ''
   }
 }
 
 /**
- * The running-turn label. Before the port scrolls (content shorter than the
- * viewport) the content-height lag has no `scrollTop` room to ride, so it is
- * expressed as a negative translate on this sibling: the label descends
- * smoothly with each wrap instead of hopping down a line at a time.
+ * The running-turn label. It stays in normal flow so the host column's gap
+ * always separates it from the transcript.
  */
-function chromeShiftOf(port: HTMLElement): HTMLElement | null {
-  return port.querySelector<HTMLElement>('[data-chat-turn-status]')
+function statusChromeOf(port: HTMLElement): HTMLElement | null {
+  return port.querySelector<HTMLElement>(
+    '[data-chat-turn-status], [data-chat-flow] > [role="status"]',
+  )
 }
 
 /**
- * Render the single smoothed extent `animatedH`. Before the port scrolls
- * (content shorter than the viewport) `animatedH` is clamped to the content
- * height and the content-height lag rides a negative translate on the
- * turn-status label; once the port has scroll room the engine is pinned at
- * the floor and the lag rides `[data-chat-transcript]` (or each message row
- * when the host has no transcript box) so the chrome stays put. Without any
- * shift surface the engine itself carries the interpolated top.
+ * Render the single smoothed extent `animatedH`. Once the port has scroll
+ * room the engine is pinned at the floor and the lag rides
+ * `[data-chat-transcript]` (or each message row when the host has no
+ * transcript box). Before that, message rows and status chrome remain in
+ * normal flow. Without any shift surface the engine carries the interpolated
+ * top itself.
  */
 function applyVisual(port: HTMLElement, animatedH: number): void {
   const contentHeight = Math.max(0, port.scrollHeight)
@@ -173,19 +190,19 @@ function applyVisual(port: HTMLElement, animatedH: number): void {
   const lag = contentHeight - extent
   port.style.overflowAnchor = 'none'
   port.style.scrollBehavior = 'auto'
+  const chrome = statusChromeOf(port)
+  if (chrome !== null) setShift(chrome, 0)
   const shiftRoot = shiftRootOf(port)
   if (shiftRoot !== null) {
     if (floor <= 0) {
       port.scrollTop = 0
       port.setAttribute(FOLLOW_OWNED_ATTR, String(port.scrollTop))
-      const chrome = chromeShiftOf(port)
-      if (chrome !== null) setShift(chrome, lag, true)
       setShift(shiftRoot, 0)
       return
     }
     port.scrollTop = floor
     port.setAttribute(FOLLOW_OWNED_ATTR, String(port.scrollTop))
-    setShift(shiftRoot, lag)
+    setShift(shiftRoot, lag, chrome === null ? undefined : statusGapBelow(shiftRoot, chrome))
     return
   }
   const rows = shiftRowsOf(port)
@@ -193,14 +210,16 @@ function applyVisual(port: HTMLElement, animatedH: number): void {
     if (floor <= 0) {
       port.scrollTop = 0
       port.setAttribute(FOLLOW_OWNED_ATTR, String(port.scrollTop))
-      const chrome = chromeShiftOf(port)
-      if (chrome !== null) setShift(chrome, lag, true)
       for (const row of rows) setShift(row, 0)
       return
     }
     port.scrollTop = floor
     port.setAttribute(FOLLOW_OWNED_ATTR, String(port.scrollTop))
-    for (const row of rows) setShift(row, lag)
+    const last = rows.length - 1
+    for (const [index, row] of rows.entries()) {
+      const allowance = index === last && chrome !== null ? statusGapBelow(row, chrome) : undefined
+      setShift(row, lag, allowance)
+    }
     return
   }
   port.scrollTop = Math.min(floor, Math.max(0, extent))
@@ -213,21 +232,32 @@ function clearVisual(port: HTMLElement): void {
   port.style.scrollBehavior = ''
   const shiftRoot = shiftRootOf(port)
   if (shiftRoot !== null) {
+    statusGapCache.delete(shiftRoot)
     shiftRoot.style.transform = ''
     shiftRoot.style.willChange = ''
+    shiftRoot.style.clipPath = ''
   } else {
     for (const row of shiftRowsOf(port)) {
+      statusGapCache.delete(row)
       row.style.transform = ''
       row.style.willChange = ''
+      row.style.clipPath = ''
     }
   }
-  const chrome = chromeShiftOf(port)
+  const chrome = statusChromeOf(port)
   if (chrome !== null) {
     chrome.style.transform = ''
     chrome.style.willChange = ''
+    chrome.style.clipPath = ''
   }
 }
 
+function settleAtFloor(port: HTMLElement): void {
+  const floor = Math.max(0, port.scrollHeight - port.clientHeight)
+  port.scrollTop = floor
+  port.setAttribute(FOLLOW_OWNED_ATTR, String(port.scrollTop))
+}
+
 /** Live follow hosts per conversation port so one unmount does not clear another. */
 const followOwners = new WeakMap<HTMLElement, number>()
 
@@ -412,15 +442,15 @@ export function useConversationFollow(
       const root = rootRef.current
       const host = root?.closest<HTMLElement>('[data-conversation-scroll]') ?? port
       if (host === null) return
-      if (following) {
-        // Same handback as an unpin: land on the effective visual top rather
-        // than the floor, so the owner change (stream close, unmount) does
-        // not snap the flow up by the remaining lag.
-        handBackVisual(host)
-      }
       const remaining = holding === host ? releaseFollow(host) : (followOwners.get(host) ?? 0)
       holding = null
-      if (remaining === 0) clearVisual(host)
+      if (remaining === 0) {
+        if (following) {
+          if (interacting && awayPx >= FOLLOW_UNPIN_GESTURE_PX) handBackVisual(host)
+          else settleAtFloor(host)
+        }
+        clearVisual(host)
+      }
     }
   }, [active, rootRef, speedCpsRef])
 }

package/src/package-meta.ts

@@ -0,0 +1,39 @@
+/** Host-only package metadata. The package manifest remains the source of truth. */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+interface PackageManifest {
+  name?: unknown
+  version?: unknown
+}
+
+function packageManifestPath(): string {
+  // Production loads this Node entry from its installed file. Vite's test
+  // transform instead supplies an http URL, where the project manifest is the
+  // closest equivalent source of truth.
+  try {
+    return join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')
+  } catch {
+    // Fall through to the project root when a browser-oriented test transform
+    // has replaced import.meta.url with a non-file URL.
+  }
+  return join(process.cwd(), 'package.json')
+}
+
+const manifest = JSON.parse(readFileSync(packageManifestPath(), 'utf8')) as PackageManifest
+
+function readRequiredString(field: keyof PackageManifest): string {
+  const value = manifest[field]
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`dsh-smooth-stream: package.json must contain a non-empty ${field}`)
+  }
+  return value
+}
+
+/** npm package name, read from this plugin's manifest. */
+export const STREAM_PACKAGE_NAME = readRequiredString('name')
+
+/** Version of the code currently loaded by the Host, read from its manifest. */
+export const STREAM_PACKAGE_VERSION = readRequiredString('version')

package/src/plugin.ts

@@ -1,8 +1,14 @@
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-host-webserver'
+import type { ConnectionRpcHandler } from '@deepseek-ai/dsh-client-connection'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 import Schema from '@deepseek-ai/schemastery'
 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 { STREAM_SETTINGS_RPC, STREAM_SETTINGS_RPC_CHANNEL, type StreamSettingsView } from './settings-api.ts'
+import { DEFAULT_STREAM_SETTINGS, STREAM_SETTINGS_NS, type StreamSettings } from './settings.ts'
 
 /** Display name shown by the Host loader while the plugin is mounted. */
 export const name = 'dsh-smooth-stream'
@@ -31,6 +37,14 @@ export const Config: Schema<Config> = Schema.object({
     .default(DEFAULT_STREAM_CONFIG.maxScrollSpeedPxPerSec),
 })
 
+/**
+ * Schema of the user-owned settings section. The Host keeps it in the durable
+ * settings provider while the browser edits it through the plugin RPC below.
+ */
+export const StreamSettingsSchema: Schema<StreamSettings> = Schema.object({
+  thinkAutoExpand: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.thinkAutoExpand),
+})
+
 /**
  * Host half: log the resolved configuration and bridge it to the browser
  * half. The web boot graph carries no per-entry config, so the validated
@@ -51,4 +65,91 @@ export function apply(ctx: Context, config: Config): void {
       'dsh-smooth-stream: boot config bridge',
     )
   })
+  // The core settings RPC deliberately filters third-party namespaces. Keep
+  // 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) => {
+    const scope = settingsCtx.settings.register(
+      settingsNamespace(STREAM_SETTINGS_NS),
+      StreamSettingsSchema,
+      { applies: 'live' },
+    )
+    settingsCtx.inject(['connection'], (connectionCtx) => {
+      let upgrade: Promise<void> | undefined
+
+      const view = (): StreamSettingsView => {
+        const installation = inspectProfileInstallation(connectionCtx.baseUrl, STREAM_PACKAGE_NAME)
+        return {
+          version: STREAM_PACKAGE_VERSION,
+          installation: installation.kind,
+          writable: connectionCtx.settings.writable,
+          thinkAutoExpand: scope.get().thinkAutoExpand,
+          canUpgrade: installation.kind === 'npm',
+        }
+      }
+
+      const handle: ConnectionRpcHandler = async (endpoint, payload) => {
+        if (endpoint === STREAM_SETTINGS_RPC.read) return { ok: true, value: view() }
+        if (endpoint === STREAM_SETTINGS_RPC.write) {
+          if (typeof payload !== 'object' || payload === null
+            || typeof (payload as { thinkAutoExpand?: unknown }).thinkAutoExpand !== 'boolean') {
+            return {
+              ok: false,
+              error: {
+                code: 'settings-rejected',
+                message: 'thinkAutoExpand must be a boolean',
+                details: { ns: STREAM_SETTINGS_NS },
+              },
+            }
+          }
+          if (!connectionCtx.settings.writable) {
+            return {
+              ok: false,
+              error: {
+                code: 'settings-rejected',
+                message: 'smooth-stream settings are read-only',
+                details: { ns: STREAM_SETTINGS_NS },
+              },
+            }
+          }
+          try {
+            await scope.update({ thinkAutoExpand: (payload as { thinkAutoExpand: boolean }).thinkAutoExpand })
+          } catch {
+            return {
+              ok: false,
+              error: {
+                code: 'settings-rejected',
+                message: 'smooth-stream settings update failed',
+                details: { ns: STREAM_SETTINGS_NS },
+              },
+            }
+          }
+          return { ok: true, value: view() }
+        }
+        if (endpoint === STREAM_SETTINGS_RPC.upgrade) {
+          const installation = inspectProfileInstallation(connectionCtx.baseUrl, STREAM_PACKAGE_NAME)
+          if (installation.kind !== 'npm') {
+            return { ok: false, error: { code: 'internal', message: 'smooth-stream is not an npm profile dependency', details: {} } }
+          }
+          if (upgrade !== undefined) {
+            return { ok: false, error: { code: 'internal', message: 'smooth-stream update is already running', details: {} } }
+          }
+          upgrade = updateNpmProfilePackage(installation.profileDir, STREAM_PACKAGE_NAME)
+          try {
+            await upgrade
+          } catch {
+            return { ok: false, error: { code: 'internal', message: 'smooth-stream update failed', details: {} } }
+          } finally {
+            upgrade = undefined
+          }
+          return { ok: true, value: { restartRequired: true } }
+        }
+        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',
+      )
+    })
+  })
 }

package/src/profile-installation.ts

@@ -0,0 +1,121 @@
+/** Host-only profile source inspection and fixed npm update runner. */
+
+import { spawn } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { basename, isAbsolute, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** A profile installation that can be updated through a fixed pnpm invocation. */
+export interface NpmProfileInstallation {
+  kind: 'npm'
+  profileDir: string
+  profileName: string
+}
+
+/** A local source is deliberately not eligible for one-click npm updates. */
+export interface DevelopmentProfileInstallation {
+  kind: 'development'
+}
+
+/** The active context is not a recognized profile dependency. */
+export interface UnmanagedProfileInstallation {
+  kind: 'unmanaged'
+}
+
+/** Installation source visible to the plugin's Host RPC. */
+export type ProfileInstallation = NpmProfileInstallation | DevelopmentProfileInstallation | UnmanagedProfileInstallation
+
+interface ProfileManifest {
+  dependencies?: unknown
+  dsh?: unknown
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
+}
+
+function profileDirectory(baseUrl: string | undefined): string | undefined {
+  if (baseUrl === undefined) return undefined
+  try {
+    const url = new URL(baseUrl)
+    return url.protocol === 'file:' ? fileURLToPath(url) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function hasBundle(manifest: ProfileManifest, packageName: string): boolean {
+  const dsh = record(manifest.dsh)
+  const profile = record(dsh?.profile)
+  const bundles = profile?.bundles
+  return Array.isArray(bundles) && bundles.includes(packageName)
+}
+
+function isLocalSpecifier(specifier: string): boolean {
+  return specifier.startsWith('link:')
+    || specifier.startsWith('file:')
+    || specifier.startsWith('.')
+    || isAbsolute(specifier)
+    || /^[A-Za-z]:[\\/]/.test(specifier)
+}
+
+function isRegistrySpecifier(specifier: string): boolean {
+  // A registry range/tag contains neither a scheme nor a path. Treat every
+  // package-manager extension (catalog:, patch:, portal:, workspace:, etc.)
+  // as unconfirmed rather than guessing that an update may replace it.
+  return specifier.length > 0 && !specifier.includes(':') && !/[\\/]/.test(specifier)
+}
+
+function isNpmSpecifier(specifier: string, packageName: string): boolean {
+  if (!specifier.startsWith('npm:')) return isRegistrySpecifier(specifier)
+  const aliased = specifier.slice('npm:'.length)
+  if (aliased === packageName) return true
+  const prefix = `${packageName}@`
+  return aliased.startsWith(prefix) && isRegistrySpecifier(aliased.slice(prefix.length))
+}
+
+/**
+ * Read only the profile manifest anchored by the current Cordis config tree.
+ * A malformed or unrelated tree never receives an update affordance.
+ */
+export function inspectProfileInstallation(
+  baseUrl: string | undefined,
+  packageName: string,
+): ProfileInstallation {
+  const profileDir = profileDirectory(baseUrl)
+  if (profileDir === undefined) return { kind: 'unmanaged' }
+  let manifest: ProfileManifest
+  try {
+    manifest = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8')) as ProfileManifest
+  } catch {
+    return { kind: 'unmanaged' }
+  }
+  const dependencies = record(manifest.dependencies)
+  const specifier = dependencies?.[packageName]
+  if (typeof specifier !== 'string' || !hasBundle(manifest, packageName)) {
+    return { kind: 'unmanaged' }
+  }
+  if (isLocalSpecifier(specifier)) return { kind: 'development' }
+  if (!isNpmSpecifier(specifier, packageName)) return { kind: 'unmanaged' }
+  return { kind: 'npm', profileDir, profileName: basename(profileDir) }
+}
+
+/** Run the same fixed package update operation that a profile user would invoke. */
+export function updateNpmProfilePackage(profileDir: string, packageName: string): Promise<void> {
+  const command = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm'
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, ['update', packageName], {
+      cwd: profileDir,
+      stdio: 'ignore',
+      shell: false,
+      windowsHide: true,
+    })
+    child.once('error', reject)
+    child.once('exit', (code, signal) => {
+      if (code === 0) resolve()
+      else reject(new Error(`dsh-smooth-stream: pnpm update failed (${signal ?? String(code)})`))
+    })
+  })
+}

package/src/settings-api.ts

@@ -0,0 +1,33 @@
+/** Shared wire vocabulary for the plugin-owned settings RPC channel. */
+
+/** Dedicated, loopback-only RPC channel registered by the Host half. */
+export const STREAM_SETTINGS_RPC_CHANNEL = '/smooth-stream'
+
+/** Endpoints accepted by {@link STREAM_SETTINGS_RPC_CHANNEL}. */
+export const STREAM_SETTINGS_RPC = {
+  read: 'settings.read',
+  write: 'settings.write',
+  upgrade: 'plugin.upgrade',
+} as const
+
+/** How the active profile supplied this plugin. */
+export type StreamInstallationKind = 'npm' | 'development' | 'unmanaged'
+
+/** Redacted, plugin-owned configuration state returned to the browser. */
+export interface StreamSettingsView {
+  /** Version of the package currently running in the Host process. */
+  version: string
+  /** Source class of this package in the active profile. */
+  installation: StreamInstallationKind
+  /** Whether the Host settings provider permits a write. */
+  writable: boolean
+  /** Current resolved preference. */
+  thinkAutoExpand: boolean
+  /** Whether a fixed npm update command is safe to offer. */
+  canUpgrade: boolean
+}
+
+/** Successful package update acknowledgement; loading the new code needs a restart. */
+export interface StreamUpgradeView {
+  restartRequired: true
+}

package/src/settings.ts

@@ -0,0 +1,30 @@
+/**
+ * User-owned settings for the smooth-stream plugin, exposed to the Host
+ * settings service and edited from the Web Settings "plugin configuration"
+ * page. This is the runtime-editable complement to {@link StreamConfig}: that
+ * contract is composed at load and bridged once through the boot global, while
+ * these preferences live in the durable user-settings document and take effect
+ * live.
+ */
+
+/** Settings namespace registered by the Host and served through the plugin RPC. */
+export const STREAM_SETTINGS_NS = 'smooth-stream'
+
+/**
+ * Preferences a user may set. Deliberately separate from {@link StreamConfig}
+ * because the two change at different times: composition-time values go
+ * through the boot global, a live UI edit goes through the protected plugin RPC.
+ */
+export interface StreamSettings {
+  /**
+   * Whether a reasoning ("Think") block auto-expands while it is the
+   * streaming tail. Off keeps the block collapsed — the user can still open
+   * it by hand — and stops the running state from re-owning the disclosure.
+   */
+  thinkAutoExpand: boolean
+}
+
+/** Defaults shared by the Host schema and the client-side fallback. */
+export const DEFAULT_STREAM_SETTINGS: StreamSettings = {
+  thinkAutoExpand: true,
+}