@lincyaw/dsh 0.1.0 → 0.2.0-rc.1

package/src/client/messages.ts

@@ -1,78 +1,171 @@
-import type { Locale } from '@lincyaw/workbench'
+import type { Locale, Workbench } from '@lincyaw/workbench'
+import { useSyncExternalStore } from 'react'
 
 const zh = {
   product: 'Presmium',
-  activity: '活动栏',
+  activity: '应用栏',
   skip: '跳到内容',
-  documents: '文档',
-  files: '文件',
-  sessions: '会话',
-  conversation: '对话',
+  documents: '文稿',
+  document: '当前文稿',
+  assistant: 'AI 助手',
+  more: '更多',
+  conversation: 'AI 助手',
   newConversation: '新建对话',
-  conversationHistory: '历史对话',
-  closeHistory: '收起历史对话',
-  tools: '工具',
-  hideConversation: '收起对话',
-  source: '源码',
-  preview: '预览',
-  changes: '修改',
+  conversationHistory: '对话记录',
+  closeHistory: '隐藏对话记录',
+  hideConversation: '隐藏 AI 助手',
+  preview: '文稿',
+  history: '版本历史',
   settings: '设置',
-  help: '使用说明',
+  help: '帮助',
+  mascot: '小猫',
+  mascotHint: 'AI 助手工作时，对话和文稿旁的小猫会演示它在做什么：思考、阅读、修改或等你确认。',
+  mascotShow: '显示',
+  mascotHide: '隐藏',
   close: '关闭',
-  toggleSide: '展开／收起侧栏',
-  dark: '切换明暗',
-  side: '侧栏',
-  status: '状态栏',
+  toggleSide: '显示或隐藏对话记录',
+  keys: {
+    save: '保存',
+    undo: '撤消',
+    redo: '恢复',
+    play: '播放／暂停（放映、视频制作）',
+    step: '上一步／下一步（放映、视频制作）',
+    overview: '放映：总览',
+    fullscreen: '放映：全屏',
+  },
   resize: '拖动调整宽度',
-  centre: '工作区',
+  centre: '文稿',
   welcomeTitle: '欢迎使用 Presmium',
-  welcome: '打开讲义即可预览，按需要切换源码或并排查看。右侧对话可以收起；选中文字或点选预览中的块，就能把关注内容带给 AI。不配模型也能编辑、保存与预览。',
+  welcome: '打开文稿即可编辑全文、调整页面并添加批注，修改自动保存，可以撤消。放映前会用已保存的版本准备放映；配音和视频制作会先检查所需的服务。使用 AI 助手前请设置模型。',
   start: '开始使用',
   models: '设置模型',
-  helpText: '文档顶部可选“预览”“并排”“源码”；对话顶部可新建对话、打开历史。活动栏统一使用“历史对话”入口，选择历史会话会直接显示聊天，收起后也可从这里恢复。Mod+Alt+B 收起侧栏。选中文字或用“点选”选择一块，顶部显示带给 AI 的关注内容；可用关闭按钮清除。',
+  helpItems: [
+    '直接在文稿中输入即可修改。修改自动保存，文稿上方显示“已保存”。',
+    '选中文字会出现格式工具栏：段落样式、加粗、对齐、颜色、“插入链接”与“新建批注”。“新建批注”在选中的文字上留下批注，“批注”窗格列出全部批注。',
+    '鼠标移到一段内容上，旁边的“插入内容块”可插入标题、列表、表格、图片等内容，“打开内容块菜单”可删除这一段或修改它的颜色。',
+    '“导航窗格”列出全部页面：“新建页面”添加一页，页面旁的“更多”可以重命名、复制、上移、下移或删除这一页。',
+    '“撤消”（{undo}）与“恢复”（{redo}）逐步撤消或恢复修改。“版本历史”列出保存过的每次修改，“撤消此更改”单独撤消其中一次。',
+    '“放映”按幻灯片逐步展示文稿；“导出”可导出网站、幻灯片网站、Notebook、幻灯片 PDF、幻灯片图片或幻灯片 PowerPoint；“视频制作”制作讲授视频。',
+    '“AI 助手”显示或隐藏与 AI 的对话。用自己的话告诉它要改什么，它处理的是当前打开的文稿。第一次使用前，请在“设置”的“模型”中设置模型。',
+  ],
+  runtimeProblems: '有操作无法完成。请查看详细信息，或重试刚才的操作。',
+  runtimeStopped: 'Presmium 暂时无法显示。请重新加载后继续。',
+  runtimeDetails: '详细信息',
+  runtimeReportFailed: '暂时无法把诊断发送给工作区服务，下面的详细信息仍可查看。',
+  runtimeRetry: '重新发送诊断',
+  runtimeDismiss: '关闭这条提示',
+  runtimeReload: '重新加载',
+  repairStale: '文稿或对话已切换，请在当前文稿中重新发送。',
+  repairRequest: '请修复当前文稿中以下无法正确显示的内容。诊断是观测到的结果，请核对文稿内容后再修复。',
+  needsModelTitle: 'AI 助手需要先设置模型',
+  needsModel: '设置一个模型后，就能用自己的话告诉 AI 要改什么。已经写下的请求会保留在这里。',
+  needsModelTurn: '这次请求没有发出：还没有可用的模型。设置模型后重新发送即可。',
+  needsModelRequest: 'AI 助手需要先设置模型：在 AI 助手中选择“设置模型”，设置好后重试。',
+  keyRejectedTitle: '模型没有接受当前的密钥',
+  keyRejected: '无法完成这次请求：模型服务拒绝了设置中的密钥。请在模型设置中检查或重新填写，然后重新发送。',
+  quotaTitle: '模型的额度用完了',
+  quota: '无法完成这次请求：模型服务的额度不足。请充值，或在模型设置中换一个模型，然后重新发送。',
+  turnFailedTitle: '无法完成这次请求',
+  turnFailed: 'AI 助手无法完成这次请求。请重新发送；如果反复出现，请新建对话。',
+  busy: '模型服务暂时繁忙。请稍后重新发送。',
+  tooLong: '这段对话太长了，模型读不下。请新建对话，再把要改的内容告诉 AI。',
+  turnStoppedTitle: '这次请求中途停止',
+  turnStopped: 'Presmium 在 AI 处理时重新启动了。请重新发送。',
+  checkModels: '检查模型设置',
+  failureDetails: '详细信息',
 }
 
-export type FrameMessages = typeof zh
+export type ClientMessages = typeof zh
 
-const en: FrameMessages = {
+const en: ClientMessages = {
   product: 'Presmium',
-  activity: 'Activity bar',
-  skip: 'Skip to content',
+  activity: 'App Bar',
+  skip: 'Skip to Content',
   documents: 'Documents',
-  files: 'Files',
-  sessions: 'Sessions',
-  conversation: 'Conversation',
-  newConversation: 'New chat',
-  conversationHistory: 'Chat history',
-  closeHistory: 'Hide chat history',
-  tools: 'Tools',
-  hideConversation: 'Hide conversation',
-  source: 'Source',
-  preview: 'Preview',
-  changes: 'Changes',
+  document: 'Document',
+  assistant: 'AI Assistant',
+  more: 'More',
+  conversation: 'AI Assistant',
+  newConversation: 'New Chat',
+  conversationHistory: 'Chat History',
+  closeHistory: 'Hide Chat History',
+  hideConversation: 'Hide AI Assistant',
+  preview: 'Document',
+  history: 'Version History',
   settings: 'Settings',
-  help: 'How to use',
+  help: 'Help',
+  mascot: 'Kitten',
+  mascotHint: 'While the AI Assistant works, a kitten beside the chat and the document acts out what it is doing: thinking, reading, changing the document, or waiting for you.',
+  mascotShow: 'Show',
+  mascotHide: 'Hide',
   close: 'Close',
-  toggleSide: 'Toggle the side panel',
-  dark: 'Toggle light and dark',
-  side: 'Side panel',
-  status: 'Status bar',
+  toggleSide: 'Show or Hide Chat History',
+  keys: {
+    save: 'Save',
+    undo: 'Undo',
+    redo: 'Redo',
+    play: 'Play or Pause (Presentation, Video Production)',
+    step: 'Previous or Next Step (Presentation, Video Production)',
+    overview: 'Presentation: Overview',
+    fullscreen: 'Presentation: Full Screen',
+  },
   resize: 'Drag to resize',
-  centre: 'Workspace',
+  centre: 'Document',
   welcomeTitle: 'Welcome to Presmium',
-  welcome: 'Open a lecture to preview it, and switch to source or a side by side view when needed. The conversation can be hidden. Select text or pick a block to give the AI context. Editing, saving and previewing need no model.',
-  start: 'Start',
-  models: 'Set up a model',
-  helpText: 'Choose Preview, Side by side or Source above the document. Start a new chat or open history from the conversation header. Chat history in the activity bar is the shared entry for history and chat. Selecting a history row reveals its conversation, including when chat was hidden. Mod+Alt+B toggles the sidebar. Select text or pick a block to add conversation context, shown above the document. Clear it with its close button.',
+  welcome: 'Open a document to edit its full text, arrange its pages, and add comments. Changes save automatically and can be undone. Presenting prepares the saved version first; voiceover and Video Production check the services they need first. Set up a model before using the AI Assistant.',
+  start: 'Get Started',
+  models: 'Set Up a Model',
+  helpItems: [
+    'Type directly in the document to change it. Changes save automatically, and the top of the document shows Saved.',
+    'Select text to show the formatting toolbar: paragraph style, Bold, alignment, Colors, Insert Link, and New Comment. New Comment leaves a comment on the selected text; the Comments pane lists them all.',
+    'Point at a paragraph: Insert Block, beside it, inserts a heading, list, table, picture, and more; Open Block Menu deletes the paragraph or changes its colors.',
+    'The Navigation Pane lists the pages: New Page adds one, and More beside a page renames, duplicates, moves, or deletes it.',
+    'Undo ({undo}) and Redo ({redo}) step back and forth through your changes. Version History lists every saved change; Undo This Change reverses one of them.',
+    'Present shows the document as slides, step by step; Export makes a website, slides website, Notebook, slides as PDF, slides as pictures, or slides as PowerPoint; Video Production makes a lecture video with voiceover.',
+    'AI Assistant shows or hides the chat with the AI. Tell it in your own words what to change; it works on the document you have open. Before the first use, set up a model under Models in Settings.',
+  ],
+  runtimeProblems: 'An operation couldn’t finish. Check the details, or retry the operation.',
+  runtimeStopped: 'Presmium can’t display right now. Reload to continue.',
+  runtimeDetails: 'Details',
+  runtimeReportFailed: 'Couldn’t send the diagnostics to the workspace service. The details below are still available.',
+  runtimeRetry: 'Send Diagnostics Again',
+  runtimeDismiss: 'Close',
+  runtimeReload: 'Reload',
+  repairStale: 'The document or chat changed. Send it again from the current document.',
+  repairRequest: 'Please fix the content below that does not display correctly in the current document. The diagnostics are what was observed; check the document’s content before fixing it.',
+  needsModelTitle: 'The AI Assistant needs a model',
+  needsModel: 'Set up a model, then tell the AI in your own words what to change. Anything you have typed stays here.',
+  needsModelTurn: 'This request was not sent: no model is set up yet. Set one up, then send it again.',
+  needsModelRequest: 'The AI Assistant needs a model first: choose Set Up a Model in the AI Assistant, then try again.',
+  keyRejectedTitle: 'The model didn’t accept your API key',
+  keyRejected: 'Couldn’t finish this request: the model service refused the API key in Settings. Check or re-enter it in the model settings, then send again.',
+  quotaTitle: 'The model’s quota is used up',
+  quota: 'Couldn’t finish this request: the model service has no quota left. Top up, or choose another model in the model settings, then send again.',
+  turnFailedTitle: 'Couldn’t finish this request',
+  turnFailed: 'The AI Assistant couldn’t finish this request. Send it again; if this keeps happening, start a new chat.',
+  busy: 'The model service is busy right now. Wait a moment, then send again.',
+  tooLong: 'This chat has grown too long for the model. Start a new chat and tell the AI again what to change.',
+  turnStoppedTitle: 'This request stopped midway',
+  turnStopped: 'Presmium restarted while the AI was working. Send it again.',
+  checkModels: 'Check Model Settings',
+  failureDetails: 'Details',
+}
+
+export const CLIENT_MESSAGES: Record<Locale, ClientMessages> = { 'zh-CN': zh, 'en': en }
+
+export function useClientMessages(workbench: Workbench): ClientMessages {
+  const locale = useSyncExternalStore(workbench.subscribe, () => workbench.getState().locale)
+  return CLIENT_MESSAGES[locale]
 }
 
-export const FRAME_MESSAGES: Record<Locale, FrameMessages> = { 'zh-CN': zh, 'en': en }
+/** The languages the client part adds to DeepSeek Harness's language list, with Presmium's copy for them. */
+export const BRAND_LANGUAGES = [{ id: 'zh-CN', label: '简体中文（Presmium）', fallback: 'zh' }, { id: 'en-US', label: 'English (Presmium)', fallback: 'en' }] as const
 
 export const BRAND_COPY: Record<'zh-CN' | 'en-US', Record<string, Record<string, string>>> = {
   'zh-CN': {
-    conversation: { 'hero.headline': '写讲义，从这里开始', 'hero.preview': '工作台' },
+    conversation: { 'hero.headline': '有什么想改的，告诉我', 'hero.preview': 'AI 助手', 'placeholder.hero': '例如：给第二节补一个生活中的例子', 'placeholder.default': '继续告诉 AI 要改什么…', 'placeholder.workspace': '先打开一份文稿' },
   },
   'en-US': {
-    conversation: { 'hero.headline': 'Write your lecture', 'hero.preview': 'Studio' },
+    conversation: { 'hero.headline': 'Tell me what to change', 'hero.preview': 'AI Assistant', 'placeholder.hero': 'For example: add an everyday example to section 2', 'placeholder.default': 'Tell the AI what to change next…', 'placeholder.workspace': 'Open a document first' },
   },
 }

package/src/client/{chrome.tsx → navigation-shell.tsx}

@@ -1,41 +1,36 @@
 import { PmIconButton } from '@lincyaw/workbench'
 import type { Workbench } from '@lincyaw/workbench'
 import type { ReactNode } from 'react'
-import { useFrameMessages } from './brand.tsx'
+import { isBootEntryLoaded, UI_SIDEBAR } from './contract.ts'
 import type { LayoutActions, LayoutState } from './layout.ts'
 import { NARROW, SIDE_COLLAPSE } from './layout.ts'
+import { useClientMessages } from './messages.ts'
 
 interface SidebarProps {
   renderSlot(name: string, props?: Record<string, unknown>, options?: Record<string, unknown>): ReactNode
 }
 
-/** Replace navigation chrome through public slots; Harness still owns the session browser and dialogs. */
-export function chrome(ctx: DshClientContext, workbench: Workbench, actions: LayoutActions, currentLayout: () => LayoutState, startSession: () => Promise<void>): DshObservable<readonly DshSlotEntry[]> {
-  let panels: DshSlotEntry[] = []
-  const listeners = new Set<() => void>()
-  const panelStore = {
-    getSnapshot: () => panels,
-    subscribe(listener: () => void) { listeners.add(listener); return () => { listeners.delete(listener) } },
-  }
+/**
+ * Replaces Harness's navigation shell through public slots: the history sidebar, the conversation's header actions,
+ * and the global panels (`sidebar.panellist`), which it keeps in `globalPanels` for the activity bar. Harness still
+ * owns the session browser and its dialogs.
+ */
+export function registerNavigationShell(ctx: DshClientContext, workbench: Workbench, layout: { actions: LayoutActions, getSnapshot(): LayoutState }, globalPanels: { set(entries: readonly DshSlotEntry[]): void }, startSession: () => Promise<void>): void {
+  const { actions } = layout
   // An already running host retains its old plugin roster until it is restarted.
-  if (!window.__DSH_BOOT__?.entries.some(entry => entry.id === '@deepseek-ai/dsh-client-ui-sidebar')) ctx.effect(() => {
-    const offPanels = ctx.slots.subscribe('sidebar.panellist', () => {
-      panels = ctx.slots.entries('sidebar.panellist')
-      for (const listener of listeners) listener()
-    })
-    ctx.slots.inject('sidebar.panellist', () => {
-      panels = ctx.slots.entries('sidebar.panellist')
-      for (const listener of listeners) listener()
-    })
+  if (!isBootEntryLoaded(UI_SIDEBAR)) ctx.effect(() => {
+    const updatePanels = () => globalPanels.set(ctx.slots.entries('sidebar.panellist'))
+    const offPanels = ctx.slots.subscribe('sidebar.panellist', updatePanels)
+    ctx.slots.inject('sidebar.panellist', updatePanels)
     const closeHistory = () => {
-      if (currentLayout().layoutInfo.viewportWidth < SIDE_COLLAPSE) actions.revealConversation()
+      if (layout.getSnapshot().layoutInfo.viewportWidth < SIDE_COLLAPSE) actions.revealConversation()
       else actions.toggleSidebar()
     }
     function Sidebar({ renderSlot }: SidebarProps) {
-      const t = useFrameMessages(workbench)
+      const t = useClientMessages(workbench)
       return <section className="pmw-history" aria-label={t.conversationHistory}>
         <header className="pmw-history__header"><h2>{t.conversationHistory}</h2><PmIconButton icon="close" small label={t.closeHistory} onClick={closeHistory} /></header>
-        <div className="pmw-history__browser">{renderSlot('sidebar.workspaces', { wide: true, expandSidebar: () => actions.choose('sessions') })}</div>
+        <div className="pmw-history__browser">{renderSlot('sidebar.workspaces', { wide: true, expandSidebar: () => actions.selectActivity('sessions') })}</div>
         <div hidden>{renderSlot('sidebar.settings', { wide: false })}</div>
       </section>
     }
@@ -54,13 +49,14 @@ export function chrome(ctx: DshClientContext, workbench: Workbench, actions: Lay
   }, 'presmium: one navigation shell')
   ctx.effect(() => {
     function ConversationActions() {
-      const t = useFrameMessages(workbench)
+      const t = useClientMessages(workbench)
       return <div className="pmw-chat-actions pm-ui" role="group" aria-label={t.conversation}>
+        <span className="pmw-chat-actions__title" aria-hidden="true">{t.conversation}</span>
         <PmIconButton icon="plus" label={t.newConversation} small onClick={() => void startSession()} />
         <PmIconButton icon="history" label={t.conversationHistory} small onClick={() => actions.showHistory()} />
         <PmIconButton icon="close" label={t.hideConversation} small onClick={() => {
-          if (currentLayout().layoutInfo.viewportWidth < NARROW) actions.show(workbench.state.document === undefined ? 'documents' : 'preview')
-          else actions.setDockOpen(false)
+          if (layout.getSnapshot().layoutInfo.viewportWidth < NARROW) actions.showNarrowPane(workbench.state.document === undefined ? 'documents' : 'preview')
+          else actions.setConversationOpen(false)
         }} />
       </div>
     }
@@ -75,5 +71,4 @@ export function chrome(ctx: DshClientContext, workbench: Workbench, actions: Lay
     })
     return () => off?.()
   }, 'presmium: remove the duplicate sidebar opener')
-  return panelStore
 }

package/src/client/observable.ts

@@ -0,0 +1,16 @@
+/** A value with listeners, in the shape of DeepSeek Harness's observables. */
+export function createObservable<T>(initial: T): DshObservable<T> & { set(value: T): void } {
+  let value = initial
+  const listeners = new Set<() => void>()
+  return {
+    getSnapshot: () => value,
+    subscribe(listener: () => void) {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    set(next: T) {
+      value = next
+      for (const listener of listeners) listener()
+    },
+  }
+}

package/src/client/paths.ts

@@ -0,0 +1,17 @@
+/** A path with `/` separators and without `.`, `..` or empty parts; undefined when `..` climbs above its start. */
+export function normalizePath(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('/')}`
+}
+
+export function isSamePath(a: string, b: string): boolean {
+  const normalized = normalizePath(a)
+  return normalized !== undefined && normalized === normalizePath(b)
+}

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() }
+}