@lincyaw/dsh 0.0.0-stage → 0.2.0-rc.0

package/src/client/root-reload.ts

@@ -0,0 +1,163 @@
+import type { Workbench } from '@lincyaw/workbench'
+
+const KEY = 'presmium.root-reload.v1'
+const DOCUMENT_KEY = 'presmium.open-document.v1'
+const CODE = Symbol('Presmium root client code')
+
+interface ReturnPoint {
+  workspace: string
+  directory: string
+  documentId: string
+  sectionId?: string
+  stepId?: string
+}
+
+interface Checkpoint { version: 1, armed: boolean, point?: ReturnPoint }
+
+function isReturnPoint(point: unknown): point is ReturnPoint {
+  return Boolean(point && typeof point === 'object' && 'workspace' in point && typeof point.workspace === 'string'
+    && 'directory' in point && typeof point.directory === 'string' && 'documentId' in point && typeof point.documentId === 'string'
+    && (!('sectionId' in point) || typeof point.sectionId === 'string') && (!('stepId' in point) || typeof point.stepId === 'string'))
+}
+
+function readOpenDocument(): ReturnPoint | undefined {
+  try {
+    const point: unknown = JSON.parse(sessionStorage.getItem(DOCUMENT_KEY) ?? 'null')
+    if (isReturnPoint(point)) return point
+  } catch { /* Invalid or unavailable storage cannot authorize navigation. */ }
+  try { sessionStorage.removeItem(DOCUMENT_KEY) } catch { /* Editing remains available. */ }
+}
+
+declare global {
+  interface Window {
+    /** A page-lifetime flag, never a retained plugin, context or React root. */
+    __presmiumRootReload?: symbol | 'reloading'
+  }
+}
+
+function checkpoint(): Checkpoint | undefined {
+  const value: unknown = JSON.parse(sessionStorage.getItem(KEY) ?? 'null')
+  if (!value || typeof value !== 'object' || !('version' in value) || value.version !== 1 || !('armed' in value) || typeof value.armed !== 'boolean') return
+  if (!('point' in value) || value.point === undefined) return { version: 1, armed: value.armed }
+  const point = value.point
+  if (!isReturnPoint(point)) return
+  return value as Checkpoint
+}
+
+/** Root-owner code replacement needs a new shell mount in this Harness version. */
+export function beginRootReload(): { reloading: boolean, point?: ReturnPoint } {
+  if (window.__presmiumRootReload && window.__presmiumRootReload !== CODE) {
+    if (window.__presmiumRootReload === 'reloading') return { reloading: true }
+    try {
+      const saved = checkpoint()
+      if (!saved) throw new Error('missing root return checkpoint')
+      sessionStorage.setItem(KEY, JSON.stringify({ ...saved, armed: true } satisfies Checkpoint))
+      window.__presmiumRootReload = 'reloading'
+      window.location.reload()
+    } catch {
+      // Do not navigate away when recovery storage could not be confirmed.
+      console.error('Presmium could not preserve the root reload checkpoint; automatic reload was stopped.')
+    }
+    return { reloading: true }
+  }
+  window.__presmiumRootReload = CODE
+  const opened = readOpenDocument()
+  try {
+    const saved = checkpoint()
+    sessionStorage.removeItem(KEY)
+    const point = saved?.armed && saved.point ? saved.point : opened
+    return { reloading: false, ...point ? { point } : {} }
+  } catch {
+    return { reloading: false, ...opened ? { point: opened } : {} }
+  }
+}
+
+/** Keep a pending address through another reload; only explicit navigation or settlement retires it. */
+function retainOpenDocument(workbench: Workbench, returning?: ReturnPoint): { open<T>(start: () => T): T, settle(): void, close(): void } {
+  let previous: string | undefined
+  let pending = Boolean(returning)
+  let opening = false, closed = false
+  const navigation = workbench.documentNavigationVersion
+  let remembered: ReturnPoint | undefined
+  const write = (point: ReturnPoint | undefined) => {
+    const next = point ? JSON.stringify(point) : ''
+    if (next === previous) return
+    try {
+      if (point) sessionStorage.setItem(DOCUMENT_KEY, next)
+      else sessionStorage.removeItem(DOCUMENT_KEY)
+      previous = next
+      remembered = point
+    } catch {
+      // Do not keep an earlier address after a later explicit choice could not be stored.
+      try { sessionStorage.removeItem(DOCUMENT_KEY) } catch { /* Editing does not depend on address storage. */ }
+      previous = undefined
+      remembered = undefined
+    }
+  }
+  if (returning) write({ workspace: returning.workspace, directory: returning.directory, documentId: returning.documentId })
+  const retain = () => {
+    if (closed || opening) return
+    const { document, authoring } = workbench.state
+    let point: ReturnPoint | undefined
+    if (document !== undefined && authoring?.directory === document && authoring.identity && authoring.content) {
+      try {
+        const identity: unknown = JSON.parse(authoring.identity)
+        if (Array.isArray(identity) && identity.length === 2 && typeof identity[0] === 'string' && identity[1] === authoring.content.id) {
+          point = { workspace: identity[0], directory: document, documentId: authoring.content.id }
+        }
+      } catch { /* An unknown identity cannot authorize opening another document. */ }
+    }
+    if (point) write(point)
+    else if (document === undefined) {
+      if (!pending || workbench.documentNavigationVersion !== navigation) write(undefined)
+    } else if (remembered?.directory !== document) write(undefined)
+  }
+  const stop = workbench.subscribe(retain)
+  retain()
+  return {
+    // Opening synchronously emits an intermediate Home while retiring the previous subscriptions.
+    open<T>(start: () => T): T { opening = true; try { return start() } finally { opening = false; retain() } },
+    settle() { if (!closed) { pending = false; retain() } },
+    close() { closed = true; stop() },
+  }
+}
+
+/** Store only a return address; document drafts keep their existing persistence and review rules. */
+export function saveRootReturnPoint(workbench: Workbench): void {
+  const state = workbench.state, source = state.authoring
+  try {
+    if (source?.storageFailure) throw new Error('document recovery storage unavailable')
+    let point: ReturnPoint | undefined
+    if (state.document !== undefined && source?.identity && source.content) {
+      const identity: unknown = JSON.parse(source.identity)
+      if (Array.isArray(identity) && identity.length === 2 && typeof identity[0] === 'string' && identity[1] === source.content.id) {
+        const sectionId = state.position?.section, section = sectionId ? source.content.sections[sectionId] : undefined
+        const stepId = section?.stepOrder[state.position?.step ?? 0]
+        point = { workspace: identity[0], directory: state.document, documentId: source.content.id, ...section ? { sectionId, stepId } : {} }
+      }
+    }
+    sessionStorage.setItem(KEY, JSON.stringify({ version: 1, armed: false, ...point ? { point } : {} } satisfies Checkpoint))
+  } catch {
+    // A previous checkpoint must not authorize a reload after this save failed.
+    try { sessionStorage.removeItem(KEY) } catch { /* Storage is unavailable. */ }
+  }
+}
+
+/** Restore only within this navigation; final source adoption checks the expected workspace and identity. */
+export function restoreRootReturnPoint(workbench: Workbench, point: ReturnPoint | undefined): () => void {
+  let active = true
+  const retaining = retainOpenDocument(workbench, point), navigation = workbench.documentNavigationVersion
+  const stop = workbench.subscribe(() => { if (workbench.documentNavigationVersion !== navigation) active = false })
+  const restore = async () => {
+    if (!point) return
+    const info = await workbench.client.readWorkbenchInfo()
+    if (!active || info.root !== point.workspace || workbench.state.document !== undefined) return
+    stop()
+    await retaining.open(() => workbench.openDocument(point.directory, {
+      expectedIdentity: JSON.stringify([point.workspace, point.documentId]),
+      ...point.sectionId ? { fallbackReturnPoint: { sectionId: point.sectionId, ...point.stepId ? { stepId: point.stepId } : {} } } : {},
+    }))
+  }
+  void restore().catch(() => { /* The normal home remains available when the return address no longer exists. */ }).finally(() => { stop(); retaining.settle() })
+  return () => { active = false; stop(); retaining.close() }
+}

package/src/client/runtime-diagnostics.tsx

@@ -0,0 +1,228 @@
+import { Component, useSyncExternalStore } from 'react'
+import type { ReactNode } from 'react'
+import { isObservedWorkspaceFailure, PmButton, PmNotice } from '@lincyaw/workbench'
+import type { Workbench, WorkspaceRequestEvent } from '@lincyaw/workbench'
+import type { AuthoringDiagnostics, CanonicalSource } from '@lincyaw/kernel'
+import { createObservable } from './observable.ts'
+import { useClientMessages } from './messages.ts'
+
+interface RuntimeIssue {
+  key: string
+  document?: string
+  checkId: string
+  message: string
+  feedbackOwner?: WorkspaceRequestEvent['feedbackOwner']
+  authoringSource?: CanonicalSource
+}
+interface RuntimeSnapshot { issues: readonly RuntimeIssue[], reportFailed: boolean }
+const instances = new WeakMap<Workbench, WorkbenchRuntimeDiagnostics>()
+const LIMIT = 20
+
+/** Diagnostics never include request payloads, stack traces or URL credentials. */
+export function runtimeMessage(value: unknown): string {
+  const text = value instanceof Error ? value.message : typeof value === 'string' ? value : ''
+  return (text || 'An unexpected workbench error occurred.')
+    .replace(/[a-z][a-z\d+.-]*:\/\/[^\s"'<>]+/gi, value => {
+      try { const url = new URL(value); return `${url.origin === 'null' ? `${url.protocol}//${url.host}` : url.origin}${url.pathname}` } catch { return '[URL]' }
+    })
+    .replace(/["']?authorization["']?\s*[:=]\s*(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*')/gi, '[credential redacted]')
+    .replace(/\bauthorization\s*[:=]\s*[^\r\n;,]+/gi, '[credential redacted]')
+    .replace(/\b(?:bearer|basic)\s+[^\s"',;&]+/gi, '[credential redacted]')
+    .replace(/["']?(?:access[_-]?token|refresh[_-]?token|client[_-]?secret|api[_-]?key|token|password|secret)["']?\s*[:=]\s*(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*')/gi, '[credential redacted]')
+    .replace(/\b(?:access[_-]?token|refresh[_-]?token|client[_-]?secret|api[_-]?key|token|password|secret)\b\s*[:=]\s*[^\s"',;&]+/gi, '[credential redacted]')
+    .replace(/\bsk-[A-Za-z0-9_-]{12,}\b/g, '[credential redacted]')
+    .slice(0, 600)
+}
+const aborted = (value: unknown) => value instanceof Error && value.name === 'AbortError'
+
+/** Root-window failures stay separate from the authored iframe's diagnostic contribution. */
+export class WorkbenchRuntimeDiagnostics {
+  readonly state = createObservable<RuntimeSnapshot>({ issues: [], reportFailed: false })
+  readonly #workbench: Workbench
+  readonly #instance = `workbench:${globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`}`
+  readonly #seen = new WeakSet<object>()
+  readonly #attempted = new Map<string, string>()
+  readonly #requests = new Map<number, { document?: string, key: string, feedbackOwner?: WorkspaceRequestEvent['feedbackOwner'], authoringSource?: CanonicalSource }>()
+  readonly #latestRequests = new Map<string, number>()
+  #reports = Promise.resolve()
+  #timer?: ReturnType<typeof setTimeout>
+  #stop?: () => void
+  #active = false
+  #document?: string
+
+  constructor(workbench: Workbench) { this.#workbench = workbench }
+
+  start(): () => void {
+    if (this.#stop) return this.#stop
+    this.#active = true
+    const error = (event: ErrorEvent | Event) => {
+      if (event instanceof ErrorEvent) this.capture(event.error ?? event.message)
+      else if (event.target instanceof HTMLScriptElement || event.target instanceof HTMLLinkElement) {
+        const source = event.target instanceof HTMLScriptElement ? event.target.src : event.target.href
+        this.capture(`A workbench resource could not be loaded: ${source}`)
+      }
+    }
+    const rejection = (event: PromiseRejectionEvent) => this.capture(event.reason)
+    window.addEventListener('error', error, true)
+    window.addEventListener('unhandledrejection', rejection)
+    const unwatchRequests = this.#workbench.client.subscribeRequests?.(event => this.#request(event))
+    const unwatchWorkbench = this.#workbench.subscribe(() => this.#schedule())
+    this.#schedule()
+    this.#stop = () => {
+      this.#active = false
+      clearTimeout(this.#timer)
+      this.#timer = undefined
+      window.removeEventListener('error', error, true)
+      window.removeEventListener('unhandledrejection', rejection)
+      unwatchRequests?.()
+      unwatchWorkbench()
+      this.#requests.clear()
+      this.#latestRequests.clear()
+      if (this.#document !== undefined) this.#send(this.#document, [])
+      this.#stop = undefined
+    }
+    return this.#stop
+  }
+
+  capture(error: unknown): void {
+    if (!this.#active || aborted(error) || isObservedWorkspaceFailure(error)) return
+    if (typeof error === 'object' && error !== null) {
+      if (this.#seen.has(error)) return
+      this.#seen.add(error)
+    }
+    const document = this.#workbench.state.document
+    const message = runtimeMessage(error)
+    this.#add({ key: JSON.stringify(['error', document, message]), document, checkId: 'presmium.workbench.error', message, authoringSource: this.#source(document) })
+  }
+
+  #source(document: string | undefined): CanonicalSource | undefined {
+    const value = this.#workbench.state.authoring
+    if (document === undefined || value?.directory !== document || !value.content || !value.version || !value.fingerprint) return
+    return { documentId: value.content.id, version: value.version, fingerprint: value.fingerprint }
+  }
+
+  #request(event: WorkspaceRequestEvent): void {
+    if (event.kind === 'start') {
+      const document = event.document === '' ? this.#workbench.state.document : event.document
+      const key = JSON.stringify(['request', document, event.method, event.path, event.feedbackOwner])
+      this.#requests.set(event.requestId, { document, key, feedbackOwner: event.feedbackOwner, authoringSource: this.#source(document) })
+      this.#latestRequests.delete(key)
+      this.#latestRequests.set(key, event.requestId)
+      while (this.#requests.size > LIMIT * 8) this.#requests.delete(this.#requests.keys().next().value!)
+      while (this.#latestRequests.size > LIMIT * 4) this.#latestRequests.delete(this.#latestRequests.keys().next().value!)
+      return
+    }
+    const request = this.#requests.get(event.requestId)
+    this.#requests.delete(event.requestId)
+    if (!request || this.#latestRequests.get(request.key) !== event.requestId || event.kind === 'cancel') return
+    const { document, key, feedbackOwner, authoringSource } = request
+    if (event.kind === 'recovery') {
+      const issues = this.state.getSnapshot().issues
+      if (issues.some(issue => issue.key === key)) this.#replace(issues.filter(issue => issue.key !== key))
+      return
+    }
+    const message = `${event.method} /api/presmium/${event.path}: ${event.status === undefined ? 'the workspace service could not be reached' : `HTTP ${event.status}`}`
+    this.#add({ key, document, checkId: 'presmium.workbench.request', message, authoringSource, ...event.status !== undefined && feedbackOwner ? { feedbackOwner } : {} })
+  }
+
+  #add(issue: RuntimeIssue): void {
+    const issues = this.state.getSnapshot().issues
+    const known = issues.find(known => known.key === issue.key)
+    if (known) {
+      if (known.message !== issue.message || known.feedbackOwner !== issue.feedbackOwner || JSON.stringify(known.authoringSource) !== JSON.stringify(issue.authoringSource)) this.#replace(issues.map(value => value === known ? issue : value))
+      return
+    }
+    this.#replace([...issues, issue].slice(-LIMIT))
+  }
+  #replace(issues: readonly RuntimeIssue[]): void {
+    this.state.set({ ...this.state.getSnapshot(), issues })
+    this.#schedule()
+  }
+
+  visible(): readonly RuntimeIssue[] {
+    const { document } = this.#workbench.state
+    return this.state.getSnapshot().issues.filter(issue => (issue.document === undefined || issue.document === document) && issue.feedbackOwner !== 'inline-preview')
+  }
+
+  dismiss(): void {
+    const document = this.#workbench.state.document
+    this.#replace(this.state.getSnapshot().issues.filter(issue => issue.document !== undefined && issue.document !== document))
+  }
+  retry(): void {
+    const document = this.#workbench.state.document
+    if (document !== undefined) this.#attempted.delete(document)
+    this.#schedule()
+  }
+
+  #schedule(): void {
+    if (!this.#active || this.#timer !== undefined) return
+    this.#timer = setTimeout(() => {
+      this.#timer = undefined
+      const { document } = this.#workbench.state
+      if (this.#document !== undefined && this.#document !== document) this.#send(this.#document, [])
+      this.#document = document
+      if (document === undefined) return
+      const findings: AuthoringDiagnostics['findings'] = this.state.getSnapshot().issues.filter(issue => issue.document === document).map(({ checkId, message, authoringSource }) => ({ checkId, message, severity: 'error', ...authoringSource ? { authoringSource } : {} }))
+      this.#send(document, findings)
+    }, 100)
+  }
+
+  #send(document: string, findings: AuthoringDiagnostics['findings']): void {
+    const signature = JSON.stringify(findings)
+    if (this.#attempted.get(document) === signature) return
+    this.#attempted.delete(document)
+    this.#attempted.set(document, signature)
+    while (this.#attempted.size > LIMIT * 2) this.#attempted.delete(this.#attempted.keys().next().value!)
+    const report: AuthoringDiagnostics = { document, instance: this.#instance, findings }
+    const current = () => this.#active && this.#workbench.state.document === document && this.#attempted.get(document) === signature
+    this.#reports = this.#reports.then(async () => {
+      // A queued failure may belong to a document that was closed before delivery.
+      // Empty reports still clear this instance's old contribution in queue order.
+      if (findings.length && !current()) {
+        if (this.#attempted.get(document) === signature) this.#attempted.delete(document)
+        return
+      }
+      try {
+        const result = await this.#workbench.client.reportAuthoringDiagnostics(report) as { accepted?: boolean }
+        const failed = result?.accepted !== true
+        if (current()) this.state.set({ ...this.state.getSnapshot(), reportFailed: failed })
+      } catch {
+        if (current()) this.state.set({ ...this.state.getSnapshot(), reportFailed: true })
+      }
+    })
+  }
+}
+
+export function runtimeDiagnostics(workbench: Workbench): WorkbenchRuntimeDiagnostics {
+  let diagnostics = instances.get(workbench)
+  if (!diagnostics) { diagnostics = new WorkbenchRuntimeDiagnostics(workbench); instances.set(workbench, diagnostics) }
+  return diagnostics
+}
+
+export function RuntimeDiagnosticsNotice({ workbench, fatal = false }: { workbench: Workbench, fatal?: boolean }) {
+  const diagnostics = runtimeDiagnostics(workbench)
+  const snapshot = useSyncExternalStore(diagnostics.state.subscribe, diagnostics.state.getSnapshot)
+  useSyncExternalStore(workbench.subscribe, workbench.getState)
+  const t = useClientMessages(workbench)
+  const issues = diagnostics.visible()
+  if (!fatal && !issues.length) return null
+  return <div className="pmw-runtime-feedback"><PmNotice tone="danger">
+    <p>{fatal ? t.runtimeStopped : t.runtimeProblems}</p>
+    {issues.length > 0 && <details><summary>{t.runtimeDetails}</summary><ul>{issues.map(issue => <li key={issue.key}>{issue.message}</li>)}</ul></details>}
+    {snapshot.reportFailed && <p>{t.runtimeReportFailed}</p>}
+    <div className="pmw-runtime-feedback__actions">
+      {snapshot.reportFailed && <PmButton small onClick={() => diagnostics.retry()}>{t.runtimeRetry}</PmButton>}
+      {!fatal && <PmButton small onClick={() => diagnostics.dismiss()}>{t.runtimeDismiss}</PmButton>}
+      <PmButton small icon="refresh" onClick={() => location.reload()}>{t.runtimeReload}</PmButton>
+    </div>
+  </PmNotice></div>
+}
+
+export class WorkbenchRuntimeBoundary extends Component<{ workbench: Workbench, children: ReactNode }, { failed: boolean }> {
+  state = { failed: false }
+  static getDerivedStateFromError() { return { failed: true } }
+  componentDidCatch(error: Error): void { runtimeDiagnostics(this.props.workbench).capture(error) }
+  render() {
+    return this.state.failed ? <main className="pmw-runtime-fallback pm-ui"><RuntimeDiagnosticsNotice workbench={this.props.workbench} fatal /></main> : this.props.children
+  }
+}

package/src/client/settings-opener.ts

@@ -0,0 +1,26 @@
+import { MODEL_SETTINGS } from './contract.ts'
+
+type OpenSection = (id: string) => void
+
+let remembered: OpenSection | undefined
+
+/**
+ * Keeps the settings shell's `openSection`, which it hands only to the onboarding steps it mounts (Presmium's welcome
+ * notice and the step in place of the DeepSeek sign-in, both at every page load), so other places can open a section.
+ */
+export function rememberOpenSection(openSection: OpenSection | undefined): void {
+  if (openSection) remembered = openSection
+}
+
+/** Opens Settings at Models, as the welcome notice's "Set up a model" does; false before the shell has offered a way. */
+export function openModelSettings(): boolean {
+  if (!remembered) return false
+  remembered(MODEL_SETTINGS.section)
+  return true
+}
+
+export function openSpeechSettings(): boolean {
+  if (!remembered) return false
+  remembered('presmium-speech')
+  return true
+}

package/src/client/source-links.tsx

@@ -0,0 +1,71 @@
+import { isAbsoluteWorkspacePath, parseFileAddress, resolveWorkspacePath, workspaceTitleOf } from '@deepseek-ai/dsh-util-workspace-path'
+import type { Workbench } from '@lincyaw/workbench'
+import { useLayoutEffect, useRef, useSyncExternalStore } from 'react'
+import { normalizePath } from './paths.ts'
+
+const ID = '@lincyaw/dsh/source'
+// A document's Markdown is shown as the document; other files keep Harness's own previews.
+const DOCUMENT_SOURCE = /\.(?:md|markdown)$/i
+const RESERVED = new Set(['node_modules', 'dist', '.git', '.presmium'])
+
+/** Routes Harness's links to a document's Markdown (with a line) to that place in the open document. */
+export function registerSourceLinks(ctx: DshClientContext, workbench: Workbench, showEditor: (layout: DshClientContext['layout']) => void): void {
+  ctx.inject(['sidebarRightTabs', 'sidebarRight', 'sessions', 'layout'], inner => inner.effect(() => {
+    let root: string | undefined
+    let active = true
+    void workbench.client.readWorkbenchInfo().then(answer => { if (active && answer.root) root = normalizePath(answer.root) }).catch(() => {})
+    /** The file a link names, relative to the workspace root, and the document it is in (none: the open one stays). */
+    const locate = (address: string): { path: string, document?: string } | undefined => {
+      const file = parseFileAddress(address)
+      if (!root || file?.scope !== 'session') return
+      const session = inner.sessions.list.getSnapshot().byId[file.sessionId]
+      if (!session?.cwd || normalizePath(session.cwd) !== root || !DOCUMENT_SOURCE.test(file.path)) return
+      const absolute = normalizePath(resolveWorkspacePath(session.cwd, file.path))
+      if (!absolute || !isAbsoluteWorkspacePath(absolute) || !absolute.startsWith(`${root}/`)) return
+      const path = absolute.slice(root.length + 1)
+      if (path.split('/').some(part => RESERVED.has(part))) return
+      const documents = workbench.state.documents
+      if (!documents) return
+      const document = [...documents.documents].sort((a, b) => b.dir.length - a.dir.length).find(doc => !doc.dir || path.startsWith(`${doc.dir}/`))?.dir
+      if (document === undefined) return
+      return { path, document }
+    }
+    function SourceLink({ useTabInfo }: DshSourceTabProps) {
+      const { tab } = useTabInfo()
+      const opened = useRef<number>()
+      useLayoutEffect(() => {
+        if (!tab.visible || opened.current === tab.navigation.revision) return
+        const target = locate(tab.contentId)
+        if (!target) return
+        opened.current = tab.navigation.revision
+        const line = tab.navigation.params?.line
+        tab.actions.close()
+        if (inner.sidebarRight.isExpanded()) inner.sidebarRight.toggleExpanded()
+        showEditor(inner.layout)
+        void workbench.revealSource(target.path, typeof line === 'number' && Number.isInteger(line) && line > 0 ? line : 1)
+      }, [tab.visible, tab.contentId, tab.navigation.revision])
+      return <span data-pmw-source-route="" hidden />
+    }
+    // Previously saved Harness text tabs keep their kind when restored. Route those too.
+    function RestoredSource({ absolutePath }: { absolutePath: string }) {
+      const documents = useSyncExternalStore(workbench.subscribe, () => workbench.state.documents)
+      useLayoutEffect(() => {
+        const tab = inner.sidebarRight.active()
+        if (tab?.kind !== 'text') return
+        const target = locate(tab.contentId)
+        if (!target || normalizePath(absolutePath) !== normalizePath(resolveWorkspacePath(root, target.path))) return
+        inner.sidebarRight.close(tab.id)
+        if (inner.sidebarRight.isExpanded()) inner.sidebarRight.toggleExpanded()
+        showEditor(inner.layout)
+        void workbench.revealSource(target.path)
+      }, [absolutePath, documents])
+      return null
+    }
+    const offType = inner.sidebarRightTabs.register({ id: ID, kind: 'presmium-source-link', priority: 'extension', patterns: ['dsh-resource://file/session/**'], canOpen: address => Boolean(locate(address)), title: (address = '') => workspaceTitleOf(parseFileAddress(address)?.path ?? address) })
+    let offBody: (() => void) | undefined
+    inner.slots.inject('sidebar.right.pane.tab', () => { offBody = inner.slots.register({ name: 'sidebar.right.pane.tab', key: ID }, SourceLink) })
+    let offRestored: (() => void) | undefined
+    inner.slots.inject('sidebar.right.tab.document.actions', () => { offRestored = inner.slots.register({ name: 'sidebar.right.tab.document.actions', id: ID }, RestoredSource) })
+    return () => { active = false; offRestored?.(); offBody?.(); offType() }
+  }, 'presmium: links to a document\'s source show the document'))
+}

package/src/client/speech-settings.tsx

@@ -0,0 +1,7 @@
+import { SpeechSettingsPanel, SPEECH_SETTINGS_MESSAGES, WorkbenchProvider } from '@lincyaw/workbench'
+import type { Workbench } from '@lincyaw/workbench'
+
+/** The framework owns Settings navigation; Presmium owns its operator service page. */
+export function registerSpeechSettings(ctx: DshClientContext, workbench: Workbench): void {
+  ctx.effect(() => ctx.slots.inject('settings.section', () => ctx.slots.register({ name: 'settings.section', id: 'presmium-speech', order: 30, label: () => SPEECH_SETTINGS_MESSAGES[workbench.state.locale].title }, () => <WorkbenchProvider workbench={workbench}><SpeechSettingsPanel /></WorkbenchProvider>)), 'presmium: voice service settings')
+}

package/src/client/styles.css

@@ -0,0 +1,45 @@
+@import '@lincyaw/design/design.css';
+@import '@lincyaw/workbench/styles.css';
+@import './frame.css';
+
+/* The kitten among the conversation header's actions. */
+.pmw-conversation-mascot {
+  display: inline-flex;
+  align-items: center;
+}
+
+/* The kitten's row in Settings → General, laid out as Harness's own rows: its name and note, then its choice. */
+.pmw-mascot-setting {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--pm-space-4);
+  padding-block: var(--pm-space-4);
+  border-top: var(--pm-size-hairline) solid var(--pm-color-line);
+}
+
+.pmw-mascot-setting__copy {
+  display: grid;
+  gap: var(--pm-space-1);
+  min-width: 0;
+}
+
+.pmw-mascot-setting__title {
+  margin: 0;
+  color: var(--pm-color-ink);
+  font-size: var(--pm-text-sm);
+}
+
+.pmw-mascot-setting__hint {
+  margin: 0;
+  color: var(--pm-color-muted);
+  font-size: var(--pm-text-xs);
+}
+
+.pmw-mascot-setting .pm-ui-segmented {
+  flex: none;
+}
+
+@media (max-width: 767px) {
+  .pmw-mascot-setting { flex-wrap: wrap; }
+}