@lincyaw/dsh 0.1.0 → 0.2.0-rc.0

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.tsx → source-links.tsx}

@@ -1,44 +1,34 @@
 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'
-// These formats keep Harness's rich previews. Text files share the workbench editor.
-const PREVIEW = /\.(?:png|jpe?g|gif|webp|avif|ico|bmp|svg|pdf|html?|csv|tsv|wasm|zip|gz|tgz|bz2|xz|7z|woff2?|ttf|otf|eot|mp3|mp4|m4a|wav|ogg|oga|webm|mov|avi|mkv|bin|so|dylib|dll|exe|pyc|xlsx?|docx?|pptx?|parquet|npy|npz|pkl|db|sqlite)$/i
+// 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'])
 
-function normalized(path: string): string | undefined {
-  const parts: string[] = []
-  for (const part of path.replace(/\\/g, '/').split('/')) {
-    if (!part || part === '.') continue
-    if (part === '..') {
-      if (!parts.length || parts.at(-1)?.endsWith(':')) return
-      parts.pop()
-    } else parts.push(part)
-  }
-  return `${path.startsWith('/') ? '/' : ''}${parts.join('/')}`
-}
-
-/** Use the Harness resolver for file links and line references, then open the canonical editor. */
-export function sourceLinks(ctx: DshClientContext, workbench: Workbench, showEditor: (layout: DshClientContext['layout']) => void): void {
+/** 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.workbench().then(answer => { if (active && answer.root) root = normalized(answer.root) }).catch(() => {})
-    const locate = (address: string): { path: string, document: string } | undefined => {
+    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 || normalized(session.cwd) !== root || PREVIEW.test(file.path)) return
-      const absolute = normalized(resolveWorkspacePath(session.cwd, file.path))
+      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 && documents.single) return
-      return { path, document: document ?? '' }
+      if (document === undefined) return
+      return { path, document }
     }
     function SourceLink({ useTabInfo }: DshSourceTabProps) {
       const { tab } = useTabInfo()
@@ -52,7 +42,7 @@ export function sourceLinks(ctx: DshClientContext, workbench: Workbench, showEdi
         tab.actions.close()
         if (inner.sidebarRight.isExpanded()) inner.sidebarRight.toggleExpanded()
         showEditor(inner.layout)
-        void workbench.openSource(target.document, target.path, typeof line === 'number' && Number.isInteger(line) && line > 0 ? { line, mark: true } : undefined)
+        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 />
     }
@@ -63,11 +53,11 @@ export function sourceLinks(ctx: DshClientContext, workbench: Workbench, showEdi
         const tab = inner.sidebarRight.active()
         if (tab?.kind !== 'text') return
         const target = locate(tab.contentId)
-        if (!target || normalized(absolutePath) !== normalized(resolveWorkspacePath(root, target.path))) return
+        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.openSource(target.document, target.path)
+        void workbench.revealSource(target.path)
       }, [absolutePath, documents])
       return null
     }
@@ -77,5 +67,5 @@ export function sourceLinks(ctx: DshClientContext, workbench: Workbench, showEdi
     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: shared source editor'))
+  }, '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

@@ -1,3 +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; }
+}

package/src/client/theme.ts

@@ -6,7 +6,8 @@ const same = (value: string): Pair => ({ light: value, dark: value })
 const pm = (name: ColorName): Pair => same(color(name))
 const mix = (name: ColorName, percent: number, other = 'transparent'): Pair => same(`color-mix(in srgb, ${color(name)} ${percent}%, ${other})`)
 
-export const TOKENS: Record<string, Pair> = {
+/** DeepSeek Harness's theme tokens (`--dsw-*`) mapped onto Presmium's design tokens. */
+export const DSH_THEME_TOKENS: Record<string, Pair> = {
   '--dsw-alias-bg-base': pm('bg'),
   '--dsw-alias-bg-document-preview': pm('surface'),
   '--dsw-alias-bg-layer-1': pm('surface'),
@@ -142,7 +143,8 @@ export class ThemePresenter {
   }
 }
 
-export function followScheme(snapshot: DshThemeSnapshot): boolean {
+/** Sets the `dark` class of the page to DeepSeek Harness's colour scheme; returns whether it is dark. */
+export function syncDarkClass(snapshot: DshThemeSnapshot): boolean {
   const dark = snapshot.active.colorScheme === 'dark'
   document.documentElement.classList.toggle('dark', dark)
   return dark

package/src/client/workbench-keys.ts

@@ -0,0 +1,36 @@
+import type { Workbench } from '@lincyaw/workbench'
+import { CLIENT_MESSAGES } from './messages.ts'
+import type { ClientMessages } from './messages.ts'
+
+const apple = /Mac|iPhone|iPad|iPod/.test(navigator.platform || navigator.userAgent)
+const mod = apple ? '⌘' : 'Ctrl', shift = apple ? '⇧' : 'Shift'
+const key = (code: string, ...modifiers: string[]) => ({ code, modifiers })
+
+// The reference lists an extension's rows in the order of their ids, so the ids carry the order.
+const ROWS: { id: string, label: keyof ClientMessages['keys'], keys: string[], bindings: [DshShortcutBinding, ...DshShortcutBinding[]] }[] = [
+  { id: 'presmium.keys-1-save', label: 'save', keys: [mod, 'S'], bindings: [key('KeyS', 'primary')] },
+  { id: 'presmium.keys-2-undo', label: 'undo', keys: [mod, 'Z'], bindings: [key('KeyZ', 'primary')] },
+  { id: 'presmium.keys-3-redo', label: 'redo', keys: apple ? [mod, shift, 'Z'] : [mod, 'Y'], bindings: apple ? [key('KeyZ', 'primary', 'shift')] : [key('KeyY', 'primary'), key('KeyZ', 'primary', 'shift')] },
+  { id: 'presmium.keys-4-play', label: 'play', keys: ['Space'], bindings: [key('Space')] },
+  { id: 'presmium.keys-5-step', label: 'step', keys: ['←', '→'], bindings: [key('ArrowLeft'), key('ArrowRight')] },
+  { id: 'presmium.keys-6-overview', label: 'overview', keys: ['O'], bindings: [key('KeyO')] },
+  { id: 'presmium.keys-7-fullscreen', label: 'fullscreen', keys: [shift, 'F'], bindings: [key('KeyF', 'shift')] },
+]
+
+/**
+ * Lists the workbench's own keys in Harness's shortcut reference (Settings → General → Edit Shortcuts, or Mod+/). They are
+ * fixed rows: the workbench and its preview handle the keys themselves, and the rows keep them from editable commands.
+ */
+export function registerWorkbenchKeys(ctx: DshClientContext, workbench: Workbench): void {
+  ctx.effect(() => {
+    const disposers = ROWS.flatMap(({ label, ...row }) => {
+      try {
+        return [ctx.shortcuts.registerFixed({ ...row, label: () => CLIENT_MESSAGES[workbench.state.locale].keys[label], group: 'application' })]
+      } catch (error) {
+        console.warn(`[presmium] the shortcut reference did not take ${row.id}`, error)
+        return []
+      }
+    })
+    return () => { for (const dispose of disposers) dispose() }
+  }, 'presmium: the workbench keys in the shortcut reference')
+}

package/src/client/workspace-events.ts

@@ -0,0 +1,114 @@
+import { WebSocket } from 'partysocket'
+import type { WorkspaceSubscription } from '@lincyaw/workbench'
+import type { AuthoringClientAcknowledgement, AuthoringClientEvent, AuthoringClientReport } from '@lincyaw/kernel'
+import { AUTHORING_CLIENT_REQUEST_TIMEOUT_MS } from '@lincyaw/kernel'
+import { WORKSPACE_EVENTS_PATH, workspaceEventMessage } from '../workspace-events.ts'
+import type { WorkspaceEventTopic, WorkspaceEventCommand } from '../workspace-events.ts'
+
+const TOPICS: Readonly<Record<string, WorkspaceEventTopic>> = {
+  document: 'document', diagnostics: 'diagnostics', review: 'review', revision: 'ir', job: 'jobs', 'viewer-site': 'viewer-site', 'viewer-control': 'viewer-control', approvals: 'approvals',
+}
+
+/** Each live reader owns one logical subscription; the library owns physical reconnect timing. */
+export function workspaceSubscriptions(ctx: Pick<DshClientContext, 'effect'>): WorkspaceSubscription {
+  type Subscription = { id?: string, request: Extract<WorkspaceEventCommand, { type: 'subscribe' }>, received(data: string, event?: string): void, failed?(): void, ready?(): void, pending?: Map<number, { resolve(): void, reject(error: Error): void, timer: ReturnType<typeof setTimeout> }> }
+  const readers = new Set<Subscription>()
+  const ids = new Map<string, Subscription>()
+  const url = new URL(WORKSPACE_EVENTS_PATH.slice(1), document.baseURI)
+  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
+  const socket = new WebSocket(url.href, [], { startClosed: true, maxEnqueuedMessages: 0 })
+  let closed = false
+  let serial = 0
+  const subscribe = (reader: Subscription) => {
+    const id = String(++serial)
+    reader.id = id
+    ids.set(id, reader)
+    socket.send(JSON.stringify({ ...reader.request, id }))
+  }
+  const opened = () => {
+    if (closed) return
+    ids.clear()
+    for (const reader of readers) subscribe(reader)
+  }
+  const disconnected = () => {
+    ids.clear()
+    for (const reader of readers) { reader.id = undefined; rejectPublications(reader); reader.failed?.() }
+  }
+  const rejectPublications = (reader: Subscription) => { for (const pending of reader.pending?.values() ?? []) { clearTimeout(pending.timer); pending.reject(new Error('client-transport-disconnected')) }; reader.pending?.clear() }
+  const message = (event: MessageEvent) => {
+    let raw: unknown
+    try { raw = JSON.parse(event.data) } catch { return }
+    const parsed = workspaceEventMessage.safeParse(raw)
+    if (!parsed.success) return
+    const value = parsed.data
+    const reader = ids.get(value.id)
+    if (!reader || !readers.has(reader)) return
+    if (value.type === 'published') {
+      const pending = reader.pending?.get(value.sequence)
+      reader.pending?.delete(value.sequence)
+      if (pending) clearTimeout(pending.timer)
+      if (value.ok) pending?.resolve(); else pending?.reject(new Error('client-publication-refused'))
+    } else if (value.type === 'ready') reader.ready?.()
+    else if (value.type === 'error') { rejectPublications(reader); reader.failed?.() }
+    else {
+      const topic = reader.request.topic
+      const named = topic === 'viewer-site' ? ['ir', 'reload'] : topic === 'viewer-control' ? ['ready', 'approval', 'settled', 'go', 'session'] : topic === 'approvals' ? ['approval', 'settled'] : undefined
+      if (named && (!value.event || !named.includes(value.event))) return
+      reader.received(value.data, value.event)
+    }
+  }
+  socket.addEventListener('open', opened)
+  socket.addEventListener('close', disconnected)
+  socket.addEventListener('message', message)
+  ctx.effect(() => () => {
+    closed = true
+    for (const reader of readers) rejectPublications(reader)
+    readers.clear(); ids.clear()
+    socket.removeEventListener('open', opened)
+    socket.removeEventListener('close', disconnected)
+    socket.removeEventListener('message', message)
+    socket.close()
+  }, 'presmium: workspace subscriptions')
+  const add = (reader: Subscription) => {
+    if (!closed) {
+      readers.add(reader)
+      if (socket.readyState === WebSocket.OPEN) subscribe(reader)
+      else if (readers.size === 1) socket.reconnect()
+    }
+    return () => {
+      if (!readers.delete(reader)) return
+      rejectPublications(reader)
+      if (reader.id) {
+        ids.delete(reader.id)
+        if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify({ type: 'unsubscribe', id: reader.id }))
+      }
+      if (readers.size === 0) socket.close()
+    }
+  }
+  const subscription: WorkspaceSubscription = (address, name, received, failed, ready) => {
+    const topic = TOPICS[name]
+    const query = new URL(address).searchParams
+    const document = query.get('document')
+    if (!topic || topic === 'authoring-client' || document === null) throw new Error('Invalid workspace event subscription.')
+    const request: Subscription['request'] = topic === 'viewer-site'
+      ? { type: 'subscribe', id: '', topic, document, app: query.get('app') ?? '', lang: query.get('lang') ?? '', form: query.get('form') === 'slides' ? 'slides' : 'web' }
+      : topic === 'viewer-control' ? { type: 'subscribe', id: '', topic, document, window: query.get('window') ?? '' }
+        : { type: 'subscribe', id: '', topic, document }
+    const reader: Subscription = { request, received, failed, ready }
+    return add(reader)
+  }
+  subscription.openAuthoringClient = (document, open, received, failed) => {
+    const reader: Subscription = { request: { type: 'subscribe', id: '', topic: 'authoring-client', document, ...open }, pending: new Map(), failed,
+      received(raw) { let event: AuthoringClientEvent; try { event = JSON.parse(raw) } catch { return }; if (event.type === 'connected') rejectPublications(reader); received(event) } }
+    const close = add(reader)
+    const publish = (kind: 'state' | 'ack', connectionId: string, report: AuthoringClientReport | AuthoringClientAcknowledgement) => new Promise<void>((resolve, reject) => {
+      if (closed || !readers.has(reader) || !reader.id || socket.readyState !== WebSocket.OPEN || reader.pending!.has(report.sequence)) { reject(new Error('client-transport-disconnected')); return }
+      // A lost publication receipt must release the queue without authorizing a repeated action.
+      const timer = setTimeout(() => { reader.pending!.delete(report.sequence); reject(new Error('client-publication-timeout')) }, AUTHORING_CLIENT_REQUEST_TIMEOUT_MS / 2)
+      reader.pending!.set(report.sequence, { resolve, reject, timer })
+      socket.send(JSON.stringify({ type: 'authoring-client-publish', id: reader.id, connectionId, sequence: report.sequence, kind, value: report }))
+    })
+    return { close, publish: (connectionId, report) => publish('state', connectionId, report), acknowledge: (connectionId, report) => publish('ack', connectionId, report) }
+  }
+  return subscription
+}