@jcy2387/dsh-conversation-ui 0.1.0-rc.12

package/src/client/useFpsGuard.ts

@@ -0,0 +1,84 @@
+/**
+ * Performance guard for the streaming reveal.
+ *
+ * Feeds an EMA-smoothed frame-rate monitor from a rAF loop while streaming
+ * and tracks whether the reply is on-screen. The returned `shouldHoldBack`
+ * predicate is true only while the frame rate is below the threshold AND the
+ * reply is offscreen — exactly the spec's "skip offscreen DOM updates when
+ * FPS < 30" rule. The smoother consumes the predicate as its commit veto.
+ */
+
+import { useCallback, useEffect, useRef } from 'react'
+
+const FPS_THRESHOLD = 30
+const FPS_ALPHA = 0.12
+const RECOVER_FRAMES = 6
+const MAX_FRAME_MS = 100
+
+interface MutableFps {
+  emaMs: number
+  lastMs: number
+  healthyRun: number
+  degraded: boolean
+}
+
+export function useFpsGuard(active: boolean): {
+  ref: (element: HTMLElement | null) => void
+  shouldHoldBack: () => boolean
+} {
+  const fpsRef = useRef<MutableFps>({ emaMs: 0, lastMs: 0, healthyRun: 0, degraded: false })
+  const visibleRef = useRef(true)
+  const elementRef = useRef<HTMLElement | null>(null)
+
+  useEffect(() => {
+    if (!active) return
+    let rafId = 0
+    const frame = (now: number) => {
+      rafId = requestAnimationFrame(frame)
+      const fps = fpsRef.current
+      if (fps.lastMs === 0) {
+        fps.lastMs = now
+        return
+      }
+      const delta = Math.min(MAX_FRAME_MS, Math.max(1, now - fps.lastMs))
+      fps.lastMs = now
+      fps.emaMs = fps.emaMs === 0 ? delta : fps.emaMs + FPS_ALPHA * (delta - fps.emaMs)
+      const currentFps = 1000 / fps.emaMs
+      if (currentFps < FPS_THRESHOLD) {
+        fps.healthyRun = 0
+        fps.degraded = true
+      } else if (fps.degraded) {
+        fps.healthyRun += 1
+        if (fps.healthyRun >= RECOVER_FRAMES) fps.degraded = false
+      }
+    }
+    rafId = requestAnimationFrame(frame)
+    return () => {
+      cancelAnimationFrame(rafId)
+      fpsRef.current = { emaMs: 0, lastMs: 0, healthyRun: 0, degraded: false }
+    }
+  }, [active])
+
+  const ref = useCallback((element: HTMLElement | null) => {
+    elementRef.current = element
+  }, [])
+
+  useEffect(() => {
+    const element = elementRef.current
+    if (element === null || typeof IntersectionObserver === 'undefined') return
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) visibleRef.current = entry.isIntersecting
+      },
+      { rootMargin: '120px 0px' },
+    )
+    observer.observe(element)
+    return () => observer.disconnect()
+  })
+
+  const shouldHoldBack = useCallback(() => {
+    return active && fpsRef.current.degraded && !visibleRef.current
+  }, [active])
+
+  return { ref, shouldHoldBack }
+}

package/src/config.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared plugin configuration contract. The Host half defines the
+ * Schemastery schema over this shape (defaults live here so both halves stay
+ * symmetric); the client half falls back to the same defaults when the Host
+ * boot-config bridge is absent (client-only composition).
+ */
+
+import type { ConversationSmoothingPreset } from './client/useConversationContent.ts'
+
+/** Streaming render direction of the assistant node view. */
+export type ConversationMode = 'typewriter' | 'teleprompter'
+
+/** Plugin configuration validated by the Host schema and bridged to the browser half. */
+export interface ConversationConfig {
+  /** Render direction: horizontal per-character reveal or uniform upward glide. */
+  readonly mode: ConversationMode
+  /** Smoothing preset for the reveal cadence. */
+  readonly preset: ConversationSmoothingPreset
+  /** Fixed grapheme reveal rate used by `typewriter` mode. */
+  readonly revealCharsPerSec: number
+  /** Minimum visual follow speed while the transcript is pinned. */
+  readonly scrollSpeedPxPerSec: number
+  /**
+   * Follow velocity ceiling in CSS pixels per second, so a huge first lag
+   * does not teleport. Ordinary wraps stay well below this.
+   */
+  readonly maxScrollSpeedPxPerSec: number
+}
+
+/** Defaults shared by the Host schema and the client-side fallback. */
+export const DEFAULT_CONVERSATION_CONFIG: ConversationConfig = {
+  mode: 'teleprompter',
+  preset: 'balanced',
+  revealCharsPerSec: 80,
+  scrollSpeedPxPerSec: 48,
+  maxScrollSpeedPxPerSec: 1000,
+}
+
+/**
+ * Window global the Host writes into the served index HTML. The browser boot
+ * graph carries no per-entry config, so this inline script is the only
+ * Host-to-client configuration channel for a composed web plugin.
+ */
+export const CONVERSATION_BOOT_GLOBAL = '__DSH_CONVERSATION_UI_CONFIG__'

package/src/css-modules.d.ts

@@ -0,0 +1,9 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css' {
+  const stylesheet: string
+  export default stylesheet
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+/** Host entry. The browser implementation is exported from `./client`. */
+export { apply, name, Config } from './plugin.ts'

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-conversation-ui: package.json must contain a non-empty ${field}`)
+  }
+  return value
+}
+
+/** npm package name, read from this plugin's manifest. */
+export const CONVERSATION_PACKAGE_NAME = readRequiredString('name')
+
+/** Version of the code currently loaded by the Host, read from its manifest. */
+export const CONVERSATION_PACKAGE_VERSION = readRequiredString('version')

package/src/plugin.ts

@@ -0,0 +1,155 @@
+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_CONVERSATION_CONFIG, type ConversationConfig } from './config.ts'
+import { injectConversationConfig } from './boot-config.ts'
+import { CONVERSATION_PACKAGE_NAME, CONVERSATION_PACKAGE_VERSION } from './package-meta.ts'
+import { inspectProfileInstallation, updateNpmProfilePackage } from './profile-installation.ts'
+import { CONVERSATION_SETTINGS_RPC, CONVERSATION_SETTINGS_RPC_CHANNEL, type ConversationSettingsView } from './settings-api.ts'
+import { DEFAULT_CONVERSATION_SETTINGS, CONVERSATION_SETTINGS_NS, type ConversationSettings } from './settings.ts'
+
+/** Display name shown by the Host loader while the plugin is mounted. */
+export const name = 'dsh-conversation-ui'
+
+/**
+ * Plugin configuration accepted from the overlay's `config` section. Cordis
+ * validates the value against this schema at load and fills omitted fields
+ * from the shared defaults, so an invalid value fails the load loudly.
+ */
+export interface Config extends ConversationConfig {}
+
+export const Config: Schema<Config> = Schema.object({
+  mode: Schema.union(['typewriter', 'teleprompter'] as const).default(DEFAULT_CONVERSATION_CONFIG.mode),
+  preset: Schema.union(['realtime', 'balanced', 'silky'] as const).default(DEFAULT_CONVERSATION_CONFIG.preset),
+  revealCharsPerSec: Schema.number()
+    .min(5)
+    .max(200)
+    .default(DEFAULT_CONVERSATION_CONFIG.revealCharsPerSec),
+  scrollSpeedPxPerSec: Schema.number()
+    .min(1)
+    .max(200)
+    .default(DEFAULT_CONVERSATION_CONFIG.scrollSpeedPxPerSec),
+  maxScrollSpeedPxPerSec: Schema.number()
+    .min(1)
+    .max(2000)
+    .default(DEFAULT_CONVERSATION_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 ConversationSettingsSchema: Schema<ConversationSettings> = Schema.object({
+  thinkAutoExpand: Schema.boolean().default(DEFAULT_CONVERSATION_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
+ * value is injected into every served index response as a boot global the
+ * client entry reads at apply time.
+ * @param ctx - Host context carrying the web server service when composed.
+ * @param config - Schema-validated configuration with defaults filled.
+ */
+export function apply(ctx: Context, config: Config): void {
+  console.log(
+    `[dsh-conversation-ui] plugin loaded! mode=${config.mode} preset=${config.preset} `
+    + `seed=${config.revealCharsPerSec}cps scroll=${config.scrollSpeedPxPerSec}px/s `
+    + `maxScroll=${config.maxScrollSpeedPxPerSec}px/s`,
+  )
+  ctx.inject(['webServer'], (httpCtx) => {
+    httpCtx.effect(
+      () => httpCtx.webServer.tapIndex(html => injectConversationConfig(html, config)),
+      'dsh-conversation-ui: 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(CONVERSATION_SETTINGS_NS),
+      ConversationSettingsSchema,
+      { applies: 'live' },
+    )
+    settingsCtx.inject(['connection'], (connectionCtx) => {
+      let upgrade: Promise<void> | undefined
+
+      const view = (): ConversationSettingsView => {
+        const installation = inspectProfileInstallation(connectionCtx.baseUrl, CONVERSATION_PACKAGE_NAME)
+        return {
+          version: CONVERSATION_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 === CONVERSATION_SETTINGS_RPC.read) return { ok: true, value: view() }
+        if (endpoint === CONVERSATION_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: CONVERSATION_SETTINGS_NS },
+              },
+            }
+          }
+          if (!connectionCtx.settings.writable) {
+            return {
+              ok: false,
+              error: {
+                code: 'settings-rejected',
+                message: 'conversation-ui settings are read-only',
+                details: { ns: CONVERSATION_SETTINGS_NS },
+              },
+            }
+          }
+          try {
+            await scope.update({ thinkAutoExpand: (payload as { thinkAutoExpand: boolean }).thinkAutoExpand })
+          } catch {
+            return {
+              ok: false,
+              error: {
+                code: 'settings-rejected',
+                message: 'conversation-ui settings update failed',
+                details: { ns: CONVERSATION_SETTINGS_NS },
+              },
+            }
+          }
+          return { ok: true, value: view() }
+        }
+        if (endpoint === CONVERSATION_SETTINGS_RPC.upgrade) {
+          const installation = inspectProfileInstallation(connectionCtx.baseUrl, CONVERSATION_PACKAGE_NAME)
+          if (installation.kind !== 'npm') {
+            return { ok: false, error: { code: 'internal', message: 'conversation-ui is not an npm profile dependency', details: {} } }
+          }
+          if (upgrade !== undefined) {
+            return { ok: false, error: { code: 'internal', message: 'conversation-ui update is already running', details: {} } }
+          }
+          upgrade = updateNpmProfilePackage(installation.profileDir, CONVERSATION_PACKAGE_NAME)
+          try {
+            await upgrade
+          } catch {
+            return { ok: false, error: { code: 'internal', message: 'conversation-ui update failed', details: {} } }
+          } finally {
+            upgrade = undefined
+          }
+          return { ok: true, value: { restartRequired: true } }
+        }
+        return { ok: false, error: { code: 'internal', message: `unknown conversation-ui endpoint ${JSON.stringify(endpoint)}`, details: {} } }
+      }
+      connectionCtx.effect(
+        () => connectionCtx.connection.rpc.handle(CONVERSATION_SETTINGS_RPC_CHANNEL, handle, { authority: 'loopback' }),
+        'dsh-conversation-ui: 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-conversation-ui: 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 CONVERSATION_SETTINGS_RPC_CHANNEL = '/conversation-ui'
+
+/** Endpoints accepted by {@link CONVERSATION_SETTINGS_RPC_CHANNEL}. */
+export const CONVERSATION_SETTINGS_RPC = {
+  read: 'settings.read',
+  write: 'settings.write',
+  upgrade: 'plugin.upgrade',
+} as const
+
+/** How the active profile supplied this plugin. */
+export type ConversationInstallationKind = 'npm' | 'development' | 'unmanaged'
+
+/** Redacted, plugin-owned configuration state returned to the browser. */
+export interface ConversationSettingsView {
+  /** Version of the package currently running in the Host process. */
+  version: string
+  /** Source class of this package in the active profile. */
+  installation: ConversationInstallationKind
+  /** 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 ConversationUpgradeView {
+  restartRequired: true
+}

package/src/settings.ts

@@ -0,0 +1,30 @@
+/**
+ * User-owned settings for the conversation-ui plugin, exposed to the Host
+ * settings service and edited from the Web Settings "plugin configuration"
+ * page. This is the runtime-editable complement to {@link ConversationConfig}: 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 CONVERSATION_SETTINGS_NS = 'conversation-ui'
+
+/**
+ * Preferences a user may set. Deliberately separate from {@link ConversationConfig}
+ * 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 ConversationSettings {
+  /**
+   * 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_CONVERSATION_SETTINGS: ConversationSettings = {
+  thinkAutoExpand: true,
+}