dsh-smooth-stream 0.1.0 → 0.3.1

package/src/client/SmoothStreamCard.tsx

@@ -0,0 +1,122 @@
+/**
+ * The smooth-stream plugin configuration card, rendered inside the Web
+ * Settings "plugin configuration" page. One toggle, staged until the user
+ * saves — the same shape as the Host-shipped cards, hand-drawn because the
+ * Host cards' chrome is not exported for reuse.
+ */
+
+import { useState } from 'react'
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-settings-plugins/client'
+import { IconChevronDownOutline14, IconRefreshOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { SmoothStreamCardFace } from './smooth-stream-card-controller.ts'
+import css from './SmoothStreamCard.module.css'
+
+/** Props the renderer binds for the smooth-stream card. */
+export type SmoothStreamCardProps =
+  PropsRuntime<'settings.plugin.item'>
+  & PropsLocale<'settings.smoothStream'>
+  & InjectFace<SmoothStreamCardFace>
+
+/** Render the smooth-stream card independently of the core settings namespace allowlist. */
+export function SmoothStreamCard(props: SmoothStreamCardProps) {
+  const { t } = props
+  const [open, setOpen] = useState(false)
+  const state = props.useSmoothStreamCard(snapshot => snapshot)
+  const blocked = !state.dirty || state.saving || state.status !== 'ready'
+  const versionLabel = state.version === undefined
+    ? null
+    : t(state.installation === 'development' ? 'developmentVersion' : 'version')
+      .replace('{version}', state.version)
+
+  return (
+    <li className={open ? `${css.card} ${css.cardOpen}` : css.card}>
+      <button
+        type="button"
+        className={css.header}
+        aria-expanded={open}
+        onClick={() => { setOpen(!open) }}
+      >
+        <span className={css.headText}>
+          <span className={css.name}>{t('title')}</span>
+          <span className={css.description}>{t('description')}</span>
+        </span>
+        {versionLabel === null ? null : <span className={css.version}>{versionLabel}</span>}
+        {state.dirty ? <span className={css.pending}>{t('unsaved')}</span> : null}
+        <IconChevronDownOutline14 className={open ? `${css.chevron} ${css.chevronOpen}` : css.chevron} />
+      </button>
+      {open
+        ? (
+          <div className={css.body}>
+            {state.status === 'loading' ? <p className={css.readOnly} role="status">{t('loading')}</p> : null}
+            {state.status === 'unavailable' ? (
+              <div className={css.failure}>
+                <p className={css.readOnly} role="status">{t('unavailable')}</p>
+                <button type="button" className={css.discard} onClick={props.reload}>{t('retry')}</button>
+              </div>
+            ) : null}
+            {state.status === 'ready' ? (
+              <>
+                {!state.writable ? <p className={css.readOnly} role="status">{t('readOnly')}</p> : null}
+                <label className={css.field}>
+                  <span className={css.fieldHead}>
+                    <span className={css.label}>{t('thinkAutoExpand')}</span>
+                    <input
+                      type="checkbox"
+                      className={css.toggle}
+                      checked={state.thinkAutoExpand}
+                      disabled={!state.writable}
+                      onChange={(event) => { props.edit(event.target.checked) }}
+                    />
+                  </span>
+                  <span className={css.hint}>{t('thinkAutoExpandHint')}</span>
+                </label>
+                <div className={css.updateRow}>
+                  <span className={css.updateCopy}>
+                    <span className={css.label}>{t('updates')}</span>
+                    <span className={css.hint}>
+                      {state.restartRequired
+                        ? t('restartRequired')
+                        : state.installation === 'npm' ? t('updateHint')
+                          : state.installation === 'development' ? t('developmentBuild') : t('updateUnavailable')}
+                    </span>
+                  </span>
+                  <button
+                    type="button"
+                    className={css.update}
+                    disabled={!state.canUpgrade || state.upgrading || state.restartRequired}
+                    title={state.canUpgrade ? undefined : t('updateUnavailable')}
+                    onClick={props.upgrade}
+                  >
+                    <span aria-hidden="true"><IconRefreshOutline14 /></span>
+                    {t(state.upgrading ? 'updating' : 'update')}
+                  </button>
+                </div>
+                {state.upgradeFailed ? <p className={css.failed} role="status">{t('updateFailed')}</p> : null}
+                <div className={css.footer}>
+                  {state.failed ? <p className={css.failed} role="status">{t('saveFailed')}</p> : null}
+                  <button
+                    type="button"
+                    className={css.discard}
+                    disabled={!state.dirty || state.saving}
+                    onClick={props.discard}
+                  >
+                    {t('discard')}
+                  </button>
+                  <button
+                    type="button"
+                    className={css.save}
+                    disabled={blocked}
+                    onClick={props.save}
+                  >
+                    {t(state.saving ? 'saving' : 'save')}
+                  </button>
+                </div>
+              </>
+            ) : null}
+          </div>
+        )
+        : null}
+    </li>
+  )
+}

package/src/client/TypewriterAssistantNodeView.tsx

@@ -7,6 +7,7 @@ import { useSmoothStreamContent, type StreamSmoothingPreset } from './useSmoothS
 import { useFpsGuard } from './useFpsGuard.ts'
 import { FollowHost } from './FollowHost.tsx'
 import { DEFAULT_STREAM_CONFIG, type StreamMode } from '../config.ts'
+import { DEFAULT_STREAM_SETTINGS } from '../settings.ts'
 import css from './TypewriterAssistantNodeView.module.css'
 
 type AssistantProps = ChatNodeViewProps<'assistant-step'>
@@ -125,17 +126,19 @@ function AnimatedReasoning({
   text,
   running,
   preset,
+  thinkAutoExpand,
   shouldHoldBack,
   t,
 }: {
   text: string
   running: boolean
   preset: StreamSmoothingPreset
+  thinkAutoExpand: boolean
   shouldHoldBack: () => boolean
   t: AssistantProps['t']
 }) {
   const reduced = usePrefersReducedMotion()
-  const [expanded, setExpanded] = useState(running)
+  const [expanded, setExpanded] = useState(running && thinkAutoExpand)
   const summaryRef = useRef<HTMLSpanElement>(null)
   const speedCpsRef = useRef(35)
   const displayed = useSmoothStreamContent(text, {
@@ -148,8 +151,10 @@ function AnimatedReasoning({
   const summary = running ? latestLine(shown) : firstLine(text)
 
   useEffect(() => {
-    setExpanded(running)
-  }, [running])
+    // Only the running state owns disclosure while auto-expand is on; with it
+    // off, a manual toggle is never wrestled back by the stream.
+    if (thinkAutoExpand) setExpanded(running)
+  }, [running, thinkAutoExpand])
 
   useEffect(() => {
     const element = summaryRef.current
@@ -200,6 +205,7 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
   revealCharsPerSec: _revealCharsPerSec = DEFAULT_STREAM_CONFIG.revealCharsPerSec,
   scrollSpeedPxPerSec: _scrollSpeedPxPerSec = DEFAULT_STREAM_CONFIG.scrollSpeedPxPerSec,
   maxScrollSpeedPxPerSec: _maxScrollSpeedPxPerSec = DEFAULT_STREAM_CONFIG.maxScrollSpeedPxPerSec,
+  thinkAutoExpand = DEFAULT_STREAM_SETTINGS.thinkAutoExpand,
   node,
   useTurnData,
   openFile,
@@ -212,6 +218,7 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
   revealCharsPerSec?: number
   scrollSpeedPxPerSec?: number
   maxScrollSpeedPxPerSec?: number
+  thinkAutoExpand?: boolean
 }) {
   const data = node.data
   const streaming = data.status === 'running'
@@ -272,6 +279,7 @@ export const TypewriterAssistantNodeView = memo(function TypewriterAssistantNode
             text={block.text}
             running={streaming && index === last}
             preset={preset}
+            thinkAutoExpand={thinkAutoExpand}
             shouldHoldBack={shouldHoldBack}
             t={t}
           />,

package/src/client/index.ts

@@ -1,12 +1,26 @@
-import { createElement, type ComponentType } from 'react'
+import { createElement, useSyncExternalStore, type ComponentType } from 'react'
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type {} from '@deepseek-ai/dsh-client-locale/client'
+// Type-only: the connection Context merge and the plugins section's SlotMap
+// entry ('settings.plugin.item').
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import type {} from '@deepseek-ai/dsh-client-ui-settings-plugins/client'
 import type { ChatNodeViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { TypewriterAssistantNodeView } from './TypewriterAssistantNodeView.tsx'
 import { wrapFollowNodeView, type FollowWrapProps } from './TypewriterToolNodeView.tsx'
+import { SmoothStreamCard } from './SmoothStreamCard.tsx'
+import { SmoothStreamCardController } from './smooth-stream-card-controller.ts'
+import { createSmoothStreamSettingsApi } from './smooth-stream-settings-api.ts'
+import { NS as SETTINGS_NS, en, zh } from './locales.ts'
 import { DEFAULT_STREAM_CONFIG, STREAM_BOOT_GLOBAL, type StreamConfig } from '../config.ts'
+import { DEFAULT_STREAM_SETTINGS } from '../settings.ts'
 
-/** Cordis services required by the browser half. */
+/**
+ * Cordis services required by the browser half. Only `slots` is load-bearing
+ * for the stream itself; locale and Connection power the configuration card
+ * and are wired through `ctx.inject` below so a deployment without them still
+ * streams with defaults.
+ */
 export const inject = ['slots']
 
 type AssistantProps = ChatNodeViewProps<'assistant-step'>
@@ -85,17 +99,95 @@ function wrapGrowingChatRows(ctx: ClientContext): () => void {
   }
 }
 
+/**
+ * A live preference cell read by `useSyncExternalStore`. It starts on the
+ * shared default and, once the plugin-owned settings controller is attached,
+ * tracks the resolved `thinkAutoExpand` value. A composition (or test) that
+ * ships no settings surface keeps the cell on the default.
+ */
+class PreferenceCell {
+  private readonly listeners = new Set<() => void>()
+  private card: SmoothStreamCardController | undefined
+  private value = DEFAULT_STREAM_SETTINGS.thinkAutoExpand
+
+  /** Re-point the cell at the plugin-owned settings controller. */
+  attach(card: SmoothStreamCardController): () => void {
+    this.card = card
+    this.refresh()
+    const unsubscribe = card.subscribe(() => { this.refresh() })
+    return () => {
+      unsubscribe()
+      if (this.card !== card) return
+      this.card = undefined
+      this.refresh()
+    }
+  }
+
+  private read(): boolean {
+    return this.card?.getSnapshot().thinkAutoExpand ?? DEFAULT_STREAM_SETTINGS.thinkAutoExpand
+  }
+
+  private refresh(): void {
+    const next = this.read()
+    if (next === this.value) return
+    this.value = next
+    for (const listener of this.listeners) listener()
+  }
+
+  readonly getSnapshot = (): boolean => this.value
+
+  readonly subscribe = (listener: () => void): () => void => {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+}
+
 /**
  * Register the typewriter renderer after the conversation package declares the
  * keyed Chat node seat. A lower priority shadows the built-in assistant row;
  * every other growing row is wrapped in place so Tool cards, retries, and
  * workflow runs share conversation follow. The Host-bridged configuration
- * selects the render direction, smoothing preset, and glide speed.
+ * selects the render direction, smoothing preset, and glide speed; the
+ * plugin-owned settings RPC supplies the live auto-expand preference when the
+ * settings surface is composed.
  * @param ctx - Browser context carrying the shared slot registry.
  */
 export function apply(ctx: ClientContext): void {
   const config = readBootConfig()
+  const preference = new PreferenceCell()
+
+  // The card talks to the plugin-owned loopback RPC, so the core settings
+  // namespace allowlist cannot make it disappear. The stream still applies
+  // with defaults when the optional Settings UI or Connection is absent.
+  ctx.inject(['slots', 'locale', 'connection'], (settingsCtx) => {
+    const card = new SmoothStreamCardController(
+      // The shared Context augmentation also carries the Host-side Connection
+      // shape. This browser entry runs after the client provider installs its
+      // handle, so narrow through unknown to its client contract here.
+      createSmoothStreamSettingsApi(settingsCtx.get('connection') as unknown as ConnectionHandle),
+    )
+    const detachPreference = preference.attach(card)
+    card.start()
+    settingsCtx.effect(() => settingsCtx.locale.register(SETTINGS_NS, { zh, en }), 'dsh-smooth-stream: settings dictionaries')
+    settingsCtx.slots.inject('settings.plugin.item', () => settingsCtx.slots.register({
+      name: 'settings.plugin.item',
+      id: 'smooth-stream',
+      order: 30,
+      locale: SETTINGS_NS,
+      inject: () => card.inject(),
+    }, SmoothStreamCard))
+    return () => {
+      card.stop()
+      detachPreference()
+    }
+  })
+
   const configured = function StreamConfiguredView(props: AssistantProps) {
+    const thinkAutoExpand = useSyncExternalStore(
+      preference.subscribe,
+      preference.getSnapshot,
+      preference.getSnapshot,
+    )
     return createElement(TypewriterAssistantNodeView, {
       ...props,
       mode: config.mode,
@@ -103,6 +195,7 @@ export function apply(ctx: ClientContext): void {
       revealCharsPerSec: config.revealCharsPerSec,
       scrollSpeedPxPerSec: config.scrollSpeedPxPerSec,
       maxScrollSpeedPxPerSec: config.maxScrollSpeedPxPerSec,
+      thinkAutoExpand,
     })
   }
   ctx.slots.inject('conversation.chat.node', () => {

package/src/client/locales.ts

@@ -0,0 +1,74 @@
+/** Locale bundles for the smooth-stream plugin configuration card. */
+
+/** Dictionary namespace owned by this plugin's settings card. */
+export const NS = 'settings.smoothStream'
+
+/** Locale keys the card renders. */
+export type SmoothStreamLocaleKey =
+  | 'title' | 'description'
+  | 'thinkAutoExpand' | 'thinkAutoExpandHint'
+  | 'readOnly' | 'loading' | 'unavailable' | 'retry'
+  | 'version' | 'developmentVersion'
+  | 'updates' | 'updateHint' | 'developmentBuild' | 'updateUnavailable'
+  | 'update' | 'updating' | 'restartRequired' | 'updateFailed'
+  | 'save' | 'saving' | 'discard' | 'unsaved' | 'saveFailed'
+
+/** English copy. */
+export const en: Record<SmoothStreamLocaleKey, string> = {
+  title: 'Smooth stream',
+  description: 'How replies are revealed while they stream.',
+  thinkAutoExpand: 'Auto-expand thinking',
+  thinkAutoExpandHint: 'Open the thinking block while it streams. Turn off to keep it collapsed.',
+  readOnly: 'This deployment stores settings read-only.',
+  loading: 'Loading plugin settings…',
+  unavailable: 'Plugin settings are unavailable in this connection.',
+  retry: 'Retry',
+  version: 'Version {version}',
+  developmentVersion: 'Development version {version}',
+  updates: 'Updates',
+  updateHint: 'Install the newest npm version, then restart Harness.',
+  developmentBuild: 'Linked source; updates are managed in the checkout.',
+  updateUnavailable: 'Updates are available only for an npm profile installation.',
+  update: 'Update',
+  updating: 'Updating…',
+  restartRequired: 'Updated. Restart Harness to load the new version.',
+  updateFailed: 'The package update failed; your current version is unchanged.',
+  save: 'Save',
+  saving: 'Saving…',
+  discard: 'Discard',
+  unsaved: 'Unsaved',
+  saveFailed: 'The deployment did not accept these values; they were left for you to correct.',
+}
+
+/** Simplified Chinese copy. */
+export const zh: Record<SmoothStreamLocaleKey, string> = {
+  title: '丝滑流式',
+  description: '回复在流式输出时如何逐字展现。',
+  thinkAutoExpand: '自动展开思考',
+  thinkAutoExpandHint: '思考块在流式时自动展开；关闭后保持折叠，可手动展开。',
+  readOnly: '本部署的设置为只读。',
+  loading: '正在加载插件设置…',
+  unavailable: '当前连接无法访问插件设置。',
+  retry: '重试',
+  version: '版本 {version}',
+  developmentVersion: '开发版本 {version}',
+  updates: '更新',
+  updateHint: '安装最新 npm 版本后重启 Harness。',
+  developmentBuild: '当前为本地链接版本，请在源码目录管理更新。',
+  updateUnavailable: '只有 profile 使用 npm 包时才能更新。',
+  update: '更新',
+  updating: '更新中…',
+  restartRequired: '已更新；重启 Harness 后加载新版本。',
+  updateFailed: '包更新失败，当前版本未改变。',
+  save: '保存',
+  saving: '保存中…',
+  discard: '放弃修改',
+  unsaved: '未保存',
+  saveFailed: '本部署没有接受这些值，已保留供你修改。',
+}
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    'settings.smoothStream': SmoothStreamLocaleKey
+  }
+}

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

@@ -0,0 +1,162 @@
+/** Staged form state for the plugin-owned smooth-stream settings RPC. */
+
+import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { DEFAULT_STREAM_SETTINGS } from '../settings.ts'
+import type { StreamInstallationKind, StreamSettingsView } from '../settings-api.ts'
+import type { SmoothStreamSettingsApi } from './smooth-stream-settings-api.ts'
+
+/** What the smooth-stream card renders. It remains visible while its Host RPC loads. */
+export interface SmoothStreamCardState {
+  status: 'loading' | 'ready' | 'unavailable'
+  writable: boolean
+  dirty: boolean
+  saving: boolean
+  failed: boolean
+  thinkAutoExpand: boolean
+  version: string | undefined
+  installation: StreamInstallationKind
+  canUpgrade: boolean
+  upgrading: boolean
+  upgradeFailed: boolean
+  restartRequired: boolean
+}
+
+/** The registration-side face injected into the settings slot renderer. */
+export interface SmoothStreamCardFace {
+  hooks: {
+    smoothStreamCard: SnapshotStore<SmoothStreamCardState>
+  }
+  edit: (value: boolean) => void
+  save: () => void
+  discard: () => void
+  reload: () => void
+  upgrade: () => void
+}
+
+/** Bridges the plugin's protected Host interface onto a staged settings form. */
+export class SmoothStreamCardController {
+  private readonly store = createSnapshotStore<SmoothStreamCardState>(this.projection())
+  private loaded: StreamSettingsView | undefined
+  private staged: boolean | undefined
+  private saving = false
+  private failed = false
+  private upgrading = false
+  private upgradeFailed = false
+  private restartRequired = false
+  private loadGeneration = 0
+  private loadStatus: 'loading' | 'ready' | 'unavailable' = 'loading'
+
+  constructor(private readonly api: SmoothStreamSettingsApi) {}
+
+  /** Begin the background read after the card has been registered. */
+  start(): void {
+    void this.load()
+  }
+
+  /** Ignore a late response after the surrounding optional services unload. */
+  stop(): void {
+    this.loadGeneration += 1
+  }
+
+  /** Current card snapshot, also consumed by the streaming preference cell. */
+  getSnapshot(): SmoothStreamCardState {
+    return this.store.getSnapshot()
+  }
+
+  /** Subscribe to state changes. */
+  subscribe(listener: () => void): () => void {
+    return this.store.subscribe(listener)
+  }
+
+  /** Build the face consumed by the settings slot renderer. */
+  inject(): SmoothStreamCardFace {
+    return {
+      hooks: { smoothStreamCard: this.store },
+      edit: (value) => {
+        this.staged = value
+        this.failed = false
+        this.publish()
+      },
+      save: () => { void this.save() },
+      discard: () => {
+        if (this.staged === undefined && !this.failed) return
+        this.staged = undefined
+        this.failed = false
+        this.publish()
+      },
+      reload: () => { void this.load() },
+      upgrade: () => { void this.upgrade() },
+    }
+  }
+
+  private projection(): SmoothStreamCardState {
+    return {
+      status: this.loadStatus,
+      writable: this.loaded?.writable ?? false,
+      dirty: this.staged !== undefined,
+      saving: this.saving,
+      failed: this.failed,
+      thinkAutoExpand: this.staged ?? this.loaded?.thinkAutoExpand ?? DEFAULT_STREAM_SETTINGS.thinkAutoExpand,
+      version: this.loaded?.version,
+      installation: this.loaded?.installation ?? 'unmanaged',
+      canUpgrade: this.loaded?.canUpgrade ?? false,
+      upgrading: this.upgrading,
+      upgradeFailed: this.upgradeFailed,
+      restartRequired: this.restartRequired,
+    }
+  }
+
+  private async load(): Promise<void> {
+    const generation = ++this.loadGeneration
+    this.loadStatus = 'loading'
+    this.loaded = undefined
+    this.publish()
+    try {
+      const view = await this.api.read()
+      if (generation !== this.loadGeneration) return
+      this.loaded = view
+      this.loadStatus = 'ready'
+    } catch {
+      if (generation !== this.loadGeneration) return
+      this.loaded = undefined
+      this.loadStatus = 'unavailable'
+    }
+    this.publish()
+  }
+
+  private async save(): Promise<void> {
+    if (this.staged === undefined || this.saving || this.loaded?.writable !== true) return
+    const value = this.staged
+    this.saving = true
+    this.failed = false
+    this.publish()
+    try {
+      this.loaded = await this.api.write(value)
+      this.staged = undefined
+    } catch {
+      this.failed = true
+    }
+    this.saving = false
+    this.publish()
+  }
+
+  private async upgrade(): Promise<void> {
+    if (this.loaded?.canUpgrade !== true || this.upgrading) return
+    this.upgrading = true
+    this.upgradeFailed = false
+    this.restartRequired = false
+    this.publish()
+    try {
+      const result = await this.api.upgrade()
+      this.restartRequired = result.restartRequired
+    } catch {
+      this.upgradeFailed = true
+    }
+    this.upgrading = false
+    this.publish()
+  }
+
+  private publish(): void {
+    this.store.set(this.projection())
+  }
+}

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/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')