@lincyaw/workbench 0.1.0 → 0.2.0-rc.1

package/src/document-editor/schema.tsx

@@ -0,0 +1,117 @@
+import { createContext, createElement, useContext } from 'react'
+import type { ReactNode } from 'react'
+import { BlockNoteSchema, defaultBlockSpecs, defaultInlineContentSpecs, defaultStyleSpecs } from '@blocknote/core'
+import type { Block, BlockNoteEditor, PartialBlock, StyleConfig, StyleSpec } from '@blocknote/core'
+import { createReactBlockSpec, createReactInlineContentSpec } from '@blocknote/react'
+import { DOCUMENT_IMAGE_MEDIA_TYPES } from '@lincyaw/kernel'
+import { tableIdentityExtension } from './table-identities.ts'
+import { documentColorStyles } from './colors.ts'
+import { mathBlock, mathInline } from './math.tsx'
+
+export interface DocumentNodeViews {
+  renderBlock?(id: string, kind: string): ReactNode
+  renderInline?(id: string, kind: string, label: string): ReactNode
+}
+export const DOCUMENT_NODE_VIEWS = createContext<DocumentNodeViews>({})
+
+const page = createReactBlockSpec({
+  type: 'presmiumPage',
+  propSchema: { sectionId: { default: '' }, level: { default: 1, values: [1, 2, 3, 4, 5, 6] as const } },
+  content: 'inline',
+}, {
+  render: ({ block, contentRef }) => createElement(`h${block.props.level}`, { className: 'pm-document-editor__page-title', 'data-document-section': block.props.sectionId, ref: contentRef }),
+})()
+
+const atom = createReactBlockSpec({
+  type: 'presmiumAtom',
+  propSchema: { entityId: { default: '' }, kind: { default: '' }, label: { default: '' } },
+  content: 'none',
+}, {
+  render: ({ block }) => {
+    const views = useContext(DOCUMENT_NODE_VIEWS)
+    return <div className="pm-document-editor__atom" contentEditable={false}>
+      {views.renderBlock?.(block.props.entityId, block.props.kind) ?? (block.props.label || block.props.kind)}
+    </div>
+  },
+})()
+
+const container = createReactBlockSpec({
+  type: 'presmiumContainer',
+  propSchema: { entityId: { default: '' }, layout: { default: 'stack', values: ['stack', 'columns', 'tabs'] as const }, title: { default: '' } },
+  content: 'none',
+}, {
+  render: ({ block }) => <div className="pm-document-editor__container-label" contentEditable={false}>{block.props.title || block.props.layout}</div>,
+})()
+
+const inline = createReactInlineContentSpec({
+  type: 'presmiumInline',
+  propSchema: { entityId: { default: '' }, kind: { default: '' }, label: { default: '' } },
+  content: 'none',
+}, {
+  render: ({ inlineContent }) => {
+    const views = useContext(DOCUMENT_NODE_VIEWS)
+    const { entityId, kind, label } = inlineContent.props
+    return <span className="pm-document-editor__inline" contentEditable={false}>
+      {views.renderInline?.(entityId, kind, label) ?? label}
+    </span>
+  },
+})
+
+const table = { ...defaultBlockSpecs.table, extensions: [...defaultBlockSpecs.table.extensions ?? [], tableIdentityExtension] }
+const image: typeof defaultBlockSpecs.image = { ...defaultBlockSpecs.image, implementation: { ...defaultBlockSpecs.image.implementation,
+  meta: { ...defaultBlockSpecs.image.implementation.meta, fileBlockAccept: [...DOCUMENT_IMAGE_MEDIA_TYPES] },
+  render(block, editor) {
+    const nativeRender = defaultBlockSpecs.image.implementation.render!
+    if (block.props.url) return nativeRender.call(this, block, editor)
+    const host = document.createElement('div')
+    let rendered = nativeRender.call(this, block, editor)
+    host.appendChild(rendered.dom)
+    // The native empty-image view starts a loader but does not restore its
+    // picker after failure. Own this render boundary, retaining native controls.
+    const stopUpload = editor.onUploadEnd(blockId => {
+      if (blockId !== block.id) return
+      const current = editor.getBlock(block.id)
+      if (!current || current.type !== 'image' || current.props.url) return
+      rendered.destroy?.()
+      rendered = nativeRender.call(this, { ...block, props: current.props }, editor)
+      host.replaceChildren(rendered.dom)
+    })
+    return { dom: host, destroy: () => { stopUpload(); rendered.destroy?.() } }
+  },
+} }
+
+function clipboardStyle<Config extends StyleConfig>(spec: StyleSpec<Config>): StyleSpec<Config> {
+  return { ...spec, implementation: { ...spec.implementation, mark: spec.implementation.mark.extend({ addPasteRules: () => [] }) } }
+}
+
+// HTML already carries formatting; its literal text must not run through inline Markdown paste rules again.
+const clipboardStyles = {
+  ...defaultStyleSpecs, ...documentColorStyles,
+  bold: clipboardStyle(defaultStyleSpecs.bold), italic: clipboardStyle(defaultStyleSpecs.italic),
+  strike: clipboardStyle(defaultStyleSpecs.strike), code: clipboardStyle(defaultStyleSpecs.code),
+}
+
+/** An editing projection. The product document schema remains owned by the kernel. */
+export const documentEditorSchema = BlockNoteSchema.create({
+  blockSpecs: {
+    paragraph: defaultBlockSpecs.paragraph, heading: defaultBlockSpecs.heading,
+    bulletListItem: defaultBlockSpecs.bulletListItem, numberedListItem: defaultBlockSpecs.numberedListItem,
+    checkListItem: defaultBlockSpecs.checkListItem, quote: defaultBlockSpecs.quote,
+    codeBlock: defaultBlockSpecs.codeBlock, table, image,
+    presmiumPage: page, presmiumAtom: atom, presmiumContainer: container, presmiumMath: mathBlock,
+  },
+  inlineContentSpecs: { ...defaultInlineContentSpecs, presmiumInline: inline, presmiumMathInline: mathInline },
+  styleSpecs: clipboardStyles,
+})
+export const commentEditorSchema = BlockNoteSchema.create({
+  blockSpecs: {
+    paragraph: defaultBlockSpecs.paragraph, heading: defaultBlockSpecs.heading,
+    bulletListItem: defaultBlockSpecs.bulletListItem, numberedListItem: defaultBlockSpecs.numberedListItem,
+    checkListItem: defaultBlockSpecs.checkListItem, quote: defaultBlockSpecs.quote,
+    codeBlock: defaultBlockSpecs.codeBlock, table, presmiumAtom: atom, presmiumMath: mathBlock,
+  },
+  inlineContentSpecs: { ...defaultInlineContentSpecs, presmiumInline: inline, presmiumMathInline: mathInline }, styleSpecs: { ...defaultStyleSpecs, ...documentColorStyles },
+})
+export type DocumentEditorBlock = Block<typeof documentEditorSchema.blockSchema, typeof documentEditorSchema.inlineContentSchema, typeof documentEditorSchema.styleSchema>
+export type DocumentEditorInput = PartialBlock<typeof documentEditorSchema.blockSchema, typeof documentEditorSchema.inlineContentSchema, typeof documentEditorSchema.styleSchema>
+export type NativeDocumentEditor = BlockNoteEditor<typeof documentEditorSchema.blockSchema, typeof documentEditorSchema.inlineContentSchema, typeof documentEditorSchema.styleSchema>

package/src/document-editor/selection.ts

@@ -0,0 +1,152 @@
+import { getBlockInfoFromNode, getBlockInfoNearPos, getNodeId } from '@blocknote/core'
+import { NodeSelection } from '@tiptap/pm/state'
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
+import type { NativeDocumentEditor } from './schema.tsx'
+import { TABLE_ENTITY_ATTRIBUTE } from './table-identities.ts'
+
+/** Ephemeral native coordinates, converted to product entity ranges by the document adapter. */
+export interface NativeTextPoint {
+  blockId: string
+  offset: number
+  contentKind: 'inline' | 'plain' | 'table'
+}
+export interface NativeDocumentSelection {
+  blockIds: string[]
+  text: string
+  from: NativeTextPoint
+  to: NativeTextPoint
+}
+
+export interface NativeEditingCursor {
+  nativeBlockId: string
+  position: number
+  objectSelected: boolean
+}
+
+/** The active endpoint owns text ranges; an object selection owns the selected object. */
+export function nativeEditingCursor(editor: NativeDocumentEditor): NativeEditingCursor | undefined {
+  if (editor.prosemirrorView.isDestroyed || !editor.isFocused()) return undefined
+  const state = editor.prosemirrorState
+  const objectSelected = state.selection instanceof NodeSelection
+  const position = objectSelected ? state.selection.from : state.selection.head
+  const info = getBlockInfoNearPos(state, position)
+  return { nativeBlockId: getNodeId(info.block.node, state.doc), position, objectSelected }
+}
+
+// Product text counts a character per text character and one per other inline node (a break, a formula, a
+// component), as in the kernel's comment anchors. A native inline formula holds its source as content, so native
+// positions after it are further along than product offsets.
+function inlineLength(content: ProseMirrorNode): number {
+  let length = 0
+  content.forEach(child => { length += child.isText ? child.nodeSize : 1 })
+  return length
+}
+
+function inlineOffset(content: ProseMirrorNode, position: number): number {
+  let offset = 0, start = 0
+  for (let index = 0; index < content.childCount; index++) {
+    const child = content.child(index)
+    if (child.isText && position <= start + child.nodeSize) return offset + Math.max(0, position - start)
+    // Inside an inline node is its start.
+    if (!child.isText && position < start + child.nodeSize) return offset
+    offset += child.isText ? child.nodeSize : 1
+    start += child.nodeSize
+  }
+  return offset
+}
+
+function inlinePosition(content: ProseMirrorNode, offset: number): number {
+  let remaining = Math.max(0, offset), start = 0
+  for (let index = 0; index < content.childCount; index++) {
+    const child = content.child(index), length = child.isText ? child.nodeSize : 1
+    if (remaining === 0 || child.isText && remaining <= length) return start + remaining
+    remaining -= length
+    start += child.nodeSize
+  }
+  return start
+}
+
+/** A native range as product text: breaks as line breaks, other inline nodes as one object character. */
+export function nativeProductText(document: ProseMirrorNode, from: number, to: number): string {
+  let text = '', started = false
+  document.nodesBetween(from, to, (node, position) => {
+    if (node.isTextblock) { if (started) text += '\n'; started = true; return true }
+    if (node.isText) { text += node.text!.slice(Math.max(from, position) - position, to - position); return false }
+    if (node.isInline) { if (position >= from) text += node.type.name === 'hardBreak' ? '\n' : '\uFFFC'; return false }
+    return true
+  })
+  return text
+}
+
+// Native cells contain paragraphs; the product flattens their boundaries to one break.
+function cellTextOffset(cell: ProseMirrorNode, position: number): number {
+  let offset = 0, before = 0
+  for (let index = 0; index < cell.childCount; index++) {
+    const paragraph = cell.child(index), start = before + 1
+    if (position <= start + paragraph.content.size) return offset + inlineOffset(paragraph, Math.max(0, position - start))
+    offset += inlineLength(paragraph) + 1
+    before += paragraph.nodeSize
+  }
+  return Math.max(0, offset - 1)
+}
+
+function cellTextPosition(cell: ProseMirrorNode, offset: number): number {
+  let remaining = Math.max(0, offset), before = 0, end = 1
+  for (let index = 0; index < cell.childCount; index++) {
+    const paragraph = cell.child(index), start = before + 1, length = inlineLength(paragraph)
+    end = start + paragraph.content.size
+    if (remaining <= length) return start + inlinePosition(paragraph, remaining)
+    remaining -= length + 1
+    before += paragraph.nodeSize
+  }
+  return end
+}
+
+export function nativeTextPoint(editor: NativeDocumentEditor, position: number): NativeTextPoint | undefined {
+  const state = editor.prosemirrorState, resolved = state.doc.resolve(position)
+  for (let depth = resolved.depth; depth > 0; depth--) {
+    const node = resolved.node(depth)
+    if ((node.type.name === 'tableCell' || node.type.name === 'tableHeader') && typeof node.attrs[TABLE_ENTITY_ATTRIBUTE] === 'string') {
+      return { blockId: node.attrs[TABLE_ENTITY_ATTRIBUTE] as string, offset: cellTextOffset(node, position - resolved.start(depth)), contentKind: 'table' }
+    }
+  }
+  const info = getBlockInfoNearPos(state, position)
+  if (!info.hasContent || info.contentKind === 'none') return undefined
+  const relative = Math.max(0, Math.min(position - info.contentStart, info.contentEnd - info.contentStart))
+  return { blockId: getNodeId(info.block.node, state.doc), offset: info.contentKind === 'inline' ? inlineOffset(info.content.node, relative) : relative, contentKind: info.contentKind }
+}
+
+export function nativeTextPosition(editor: NativeDocumentEditor, point: { blockId: string, offset: number }): number | undefined {
+  return nativeTextPositionInDocument(editor.prosemirrorState.doc, point)
+}
+
+/** Stable anchor lookup against a captured native transaction’s input document. */
+export function nativeTextPositionInDocument(document: ProseMirrorNode, point: { blockId: string, offset: number }): number | undefined {
+  let position: number | undefined
+  document.descendants((node, beforePos) => {
+    if ((node.type.name === 'tableCell' || node.type.name === 'tableHeader') && node.attrs[TABLE_ENTITY_ATTRIBUTE] === point.blockId) {
+      position = beforePos + 1 + cellTextPosition(node, point.offset)
+      return false
+    }
+    if (node.attrs.id !== point.blockId) return
+    const info = getBlockInfoFromNode(node, beforePos)
+    if (info.hasContent) position = info.contentStart + (info.contentKind === 'inline' ? inlinePosition(info.content.node, point.offset) : Math.max(0, Math.min(point.offset, info.contentEnd - info.contentStart)))
+    return false
+  })
+  return position
+}
+
+export function documentSelection(editor: NativeDocumentEditor): NativeDocumentSelection | undefined {
+  const state = editor.prosemirrorState
+  if (state.selection.empty) return undefined
+  const selected = editor.getSelection()
+  if (!selected?.blocks.length || !editor.getSelectedText().trim()) return undefined
+  const from = nativeTextPoint(editor, state.selection.from), to = nativeTextPoint(editor, state.selection.to)
+  if (!from || !to) return undefined
+  return {
+    blockIds: selected.blocks.map(block => block.id),
+    text: state.doc.textBetween(state.selection.from, state.selection.to, '\n'),
+    from,
+    to,
+  }
+}

package/src/document-editor/style.css

@@ -0,0 +1,9 @@
+.pm-document-editor { min-width: 0; }
+.pm-document-editor__file-errors { display: flex; align-items: flex-start; gap: var(--pm-space-2); }
+.pm-document-editor__file-errors ul { flex: 1; min-width: 0; margin: 0; padding-inline-start: var(--pm-space-4); overflow-wrap: anywhere; }
+.pm-document-editor .pm-document-editor__page-title { margin-block: var(--pm-space-5) var(--pm-space-3); font-family: var(--pm-font-sans); font-size: var(--pm-text-title); font-weight: var(--pm-weight-semibold); line-height: var(--pm-leading-tight); }
+.pm-document-editor__atom { flex: 1; width: 100%; min-width: 0; }
+.pm-document-editor .bn-block-content[data-content-type='presmiumAtom'] > * { flex: 1; width: 100%; min-width: 0; }
+.pm-document-editor__fallback { display: grid; gap: var(--pm-space-2); min-width: 0; }
+.pm-document-editor__fallback p { margin: 0; white-space: pre-wrap; }
+.pm-document-editor__comment-tools { position: sticky; top: var(--pm-space-2); z-index: var(--pm-z-site-header); width: fit-content; margin-inline-start: var(--pm-space-5); }

package/src/document-editor/styles.d.ts

@@ -0,0 +1 @@
+declare module '*.css'

package/src/document-editor/table-identities.ts

@@ -0,0 +1,67 @@
+import { createExtension, getBlockInfoNearPos, getNodeId } from '@blocknote/core'
+import { Extension } from '@tiptap/core'
+import { Plugin } from '@tiptap/pm/state'
+import type { NativeDocumentEditor } from './schema.tsx'
+import type { RichProjection } from './rich-text.ts'
+
+export const TABLE_ENTITY_ATTRIBUTE = 'presmiumEntityId'
+const ATTR = TABLE_ENTITY_ATTRIBUTE
+const TYPES = ['tableRow', 'tableCell', 'tableHeader']
+
+/** Public schema attributes give native table transactions stable product identities. */
+export const tableIdentityExtension = createExtension({
+  key: 'presmiumTableIdentities',
+  tiptapExtensions: [Extension.create({
+    name: 'presmiumTableEntityAttributes',
+    addGlobalAttributes: () => [{ types: TYPES, attributes: {
+      [ATTR]: { default: null, parseHTML: element => element.getAttribute('data-presmium-entity-id'), renderHTML: attributes => attributes[ATTR] ? { 'data-presmium-entity-id': attributes[ATTR] } : {} },
+    } }],
+  })],
+  prosemirrorPlugins: [new Plugin({
+    appendTransaction(transactions, _before, after) {
+      if (!transactions.some(transaction => transaction.docChanged)) return
+      const transaction = after.tr, used = new Set<string>()
+      after.doc.descendants((node, position) => {
+        if (!TYPES.includes(node.type.name)) return
+        let id = node.attrs[ATTR] as string | null
+        if (!id || used.has(id)) { id = crypto.randomUUID(); transaction.setNodeMarkup(position, undefined, { ...node.attrs, [ATTR]: id }) }
+        used.add(id)
+      })
+      if (transaction.steps.length) return transaction.setMeta('addToHistory', false)
+    },
+  })],
+})
+
+export function seedTableIdentities(editor: NativeDocumentEditor, context: RichProjection): void {
+  const state = editor.prosemirrorState, updates: { position: number, id: string }[] = []
+  state.doc.descendants((node, position) => {
+    if (node.type.name !== 'table') return
+    const info = getBlockInfoNearPos(state, position), original = context.rich.get(getNodeId(info.block.node, state.doc))?.original
+    if (original?.type !== 'table') return false
+    node.forEach((row, rowOffset, rowIndex) => {
+      const source = original.children[rowIndex]
+      if (!source) return
+      updates.push({ position: position + 1 + rowOffset, id: source.id })
+      row.forEach((_cell, cellOffset, cellIndex) => { if (source.children[cellIndex]) updates.push({ position: position + 2 + rowOffset + cellOffset, id: source.children[cellIndex]!.id }) })
+    })
+    return false
+  })
+  if (!updates.length) return
+  editor.transact(transaction => {
+    for (const { position, id } of updates) { const node = transaction.doc.nodeAt(position)!; transaction.setNodeMarkup(position, undefined, { ...node.attrs, [ATTR]: id }) }
+    transaction.setMeta('addToHistory', false)
+  })
+}
+
+export function captureTableIdentities(editor: NativeDocumentEditor, context: RichProjection): void {
+  const state = editor.prosemirrorState
+  context.tables.clear()
+  state.doc.descendants((node, position) => {
+    if (node.type.name !== 'table') return
+    const info = getBlockInfoNearPos(state, position), tableId = getNodeId(info.block.node, state.doc)
+    const rows: { id: string, cells: string[] }[] = []
+    node.forEach(row => { const cells: string[] = []; row.forEach(cell => cells.push(cell.attrs[ATTR] as string)); rows.push({ id: row.attrs[ATTR] as string, cells }) })
+    context.tables.set(tableId, rows)
+    return false
+  })
+}

package/src/document-preview.ts

@@ -0,0 +1,112 @@
+import { WorkspaceServerError } from './workspace-client.ts'
+import type { WorkspaceClient, WorkspaceRequestEvent } from './workspace-client.ts'
+import type { IrAnswer, PreviewAnswer, PreviewRenderer } from '@lincyaw/kernel'
+
+export interface DocumentPreview { address: string, revision: string, preview: PreviewAnswer }
+export interface CompiledDocumentPreview extends DocumentPreview { ir: IrAnswer }
+interface PreviewSource { directory: string, version: string, fingerprint: string, project: number }
+interface Prepared { work: Promise<DocumentPreview>, preparing: boolean, listeners: Set<() => void> }
+const prepared = new WeakMap<WorkspaceClient, Map<string, Prepared>>()
+const PREPARING_MAX_DELAY_MS = 5000
+
+/** The server is still building what the preview needs (the viewer app, the document's code) and asks to be asked again. */
+export function isPreviewPreparing(error: unknown): error is WorkspaceServerError {
+  return error instanceof WorkspaceServerError && error.status === 503 && error.answer.error === 'preview-preparing'
+}
+
+/**
+ * The document's preview addresses. While the server is still preparing them it is asked again, sooner first, until they
+ * are ready, `signal` aborts or `waiting()` says the answer is no longer wanted.
+ */
+export async function readPreviewWhenReady(client: WorkspaceClient, directory: string, renderer: PreviewRenderer, options: { signal?: AbortSignal, feedbackOwner?: WorkspaceRequestEvent['feedbackOwner'], onPreparing?(): void, waiting?(): boolean } = {}): Promise<PreviewAnswer> {
+  const { signal, feedbackOwner } = options
+  let timeouts = 0
+  for (let attempt = 0; ; attempt++) {
+    signal?.throwIfAborted()
+    const request = new AbortController(), timeout = setTimeout(() => request.abort(new DOMException('Preview preparation timed out', 'TimeoutError')), 45_000)
+    const cancel = () => request.abort(signal?.reason)
+    signal?.addEventListener('abort', cancel, { once: true })
+    try {
+      return await client.readPreview(directory, renderer, request.signal, feedbackOwner)
+    } catch (error) {
+      // A busy server (building on a slow machine) may not answer in time: asked again twice before it counts as a failure.
+      const timedOut = request.signal.reason instanceof DOMException && request.signal.reason.name === 'TimeoutError' && !signal?.aborted
+      if (!isPreviewPreparing(error) && !(timedOut && ++timeouts < 3) || options.waiting?.() === false) throw error
+      if (!timedOut) timeouts = 0
+      options.onPreparing?.()
+      const delay = Math.min((isPreviewPreparing(error) ? error.answer.retryAfterMs ?? 1000 : 1000) * 2 ** Math.min(attempt, 3), PREPARING_MAX_DELAY_MS)
+      await waitForPreviewRequest(new Promise<void>(resolve => setTimeout(resolve, delay)), signal)
+    } finally { clearTimeout(timeout); signal?.removeEventListener('abort', cancel) }
+  }
+}
+
+export function waitForPreviewRequest<T>(work: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return work
+  return new Promise<T>((resolve, reject) => {
+    const cancel = () => { signal.removeEventListener('abort', cancel); reject(signal.reason) }
+    if (signal.aborted) { work.catch(() => {}); cancel(); return }
+    signal.addEventListener('abort', cancel, { once: true })
+    work.then(value => { signal.removeEventListener('abort', cancel); resolve(value) }, error => { signal.removeEventListener('abort', cancel); reject(error) })
+  })
+}
+
+/** Speech preflights need a confirmed source snapshot without building a visual output. */
+export async function readDocumentSnapshot(client: WorkspaceClient, source: Pick<PreviewSource, 'directory' | 'version' | 'fingerprint'>, signal?: AbortSignal): Promise<IrAnswer> {
+  const entry = source.directory ? `${source.directory}/lecture.json` : 'lecture.json', started = Date.now()
+  for (;;) {
+    signal?.throwIfAborted()
+    const ir = await waitForPreviewRequest(client.readIr(source.directory), signal)
+    if (ir.sourceFingerprints?.[entry] === source.fingerprint && ir.doc.source?.version === source.version && ir.doc.source.fingerprint === source.fingerprint) return ir
+    if (Date.now() - started > 15_000) throw new Error('voice-source-pending')
+    await waitForPreviewRequest(new Promise<void>(resolve => setTimeout(resolve, 150)), signal)
+  }
+}
+
+/** The explicit request owner can abort while the compiler confirms one exact source snapshot. */
+export async function compileDocumentPreview(client: WorkspaceClient, source: PreviewSource, signal?: AbortSignal, feedbackOwner?: WorkspaceRequestEvent['feedbackOwner'], onPreparing?: () => void): Promise<CompiledDocumentPreview> {
+  const { directory, fingerprint } = source, entry = directory ? `${directory}/lecture.json` : 'lecture.json'
+  let started = Date.now()
+  for (;;) {
+    signal?.throwIfAborted()
+    const ir = await waitForPreviewRequest(client.readIr(directory), signal)
+    if (ir.sourceFingerprints?.[entry] === fingerprint && ir.doc.source?.version === source.version && ir.doc.source.fingerprint === fingerprint) {
+      const preview = await readPreviewWhenReady(client, directory, 'web', { signal, feedbackOwner, onPreparing })
+      // Time spent while the server prepared the preview does not count against the source's confirmation.
+      started = Math.max(started, Date.now() - 1000)
+      const confirmed = await waitForPreviewRequest(client.readIr(directory), signal)
+      if (confirmed.sourceFingerprints?.[entry] !== fingerprint || confirmed.doc.source?.version !== source.version || confirmed.doc.source.fingerprint !== fingerprint) throw new Error('presentation-source-changed')
+      if (confirmed.revision === ir.revision) return { address: preview.web, revision: confirmed.revision, preview, ir: confirmed }
+    }
+    if (Date.now() - started > 15_000) throw new Error('document-preview-source-pending')
+    await waitForPreviewRequest(new Promise<void>(resolve => setTimeout(resolve, 150)), signal)
+  }
+}
+
+/**
+ * Visible widgets share lightweight references, without retaining old IR payloads or another event stream. `onPreparing`
+ * hears that the server is still building what the preview needs; the preview follows once it is ready.
+ */
+export function prepareDocumentPreview(client: WorkspaceClient, source: PreviewSource, retry = false, onPreparing?: () => void): Promise<DocumentPreview> {
+  let cache = prepared.get(client)
+  if (!cache) prepared.set(client, cache = new Map())
+  const { directory, version, fingerprint, project } = source
+  const key = JSON.stringify([directory, version, fingerprint, project])
+  if (retry) cache.delete(key)
+  let entry = cache.get(key)
+  if (!entry) {
+    const created: Prepared = { work: undefined!, preparing: false, listeners: new Set() }
+    created.work = compileDocumentPreview(client, source, undefined, 'inline-preview', () => {
+      created.preparing = true
+      for (const listener of created.listeners) listener()
+    }).then(({ address, revision, preview }) => ({ address, revision, preview }))
+    entry = created
+    cache.set(key, entry)
+    created.work.catch(() => { if (cache?.get(key) === created) cache.delete(key) }).finally(() => created.listeners.clear())
+    while (cache.size > 8) cache.delete(cache.keys().next().value!)
+  }
+  if (onPreparing) {
+    if (entry.preparing) onPreparing()
+    entry.listeners.add(onPreparing)
+  }
+  return entry.work
+}

package/src/document-return-point.ts

@@ -0,0 +1,59 @@
+import type { TeachingDocument } from '@lincyaw/kernel'
+
+export interface DocumentReturnPoint {
+  sectionId: string
+  stepId?: string
+  offset?: number
+}
+
+/** A browser return address, never document content or an instruction to open another document. */
+export class DocumentReturnPoints {
+  readonly #memory = new Map<string, DocumentReturnPoint>()
+
+  read(identity: string): DocumentReturnPoint | undefined {
+    const cached = this.#memory.get(identity)
+    if (cached) return cached
+    try {
+      const value: unknown = JSON.parse(sessionStorage.getItem(`presmium.document-position.v1:${identity}`) ?? 'null')
+      if (!value || typeof value !== 'object' || !('sectionId' in value) || typeof value.sectionId !== 'string') return
+      const stepId = 'stepId' in value ? value.stepId : undefined, offset = 'offset' in value ? value.offset : undefined
+      if (stepId !== undefined && typeof stepId !== 'string' || offset !== undefined && (typeof offset !== 'number' || !Number.isFinite(offset))) return
+      const point: DocumentReturnPoint = { sectionId: value.sectionId,
+        ...stepId !== undefined ? { stepId } : {}, ...offset !== undefined ? { offset } : {} }
+      this.#memory.set(identity, point)
+      return point
+    } catch { return }
+  }
+
+  write(identity: string, point: DocumentReturnPoint): void {
+    const previous = this.#memory.get(identity)
+    if (previous?.sectionId === point.sectionId && previous.stepId === point.stepId && previous.offset === point.offset) return
+    this.#memory.set(identity, point)
+    try { sessionStorage.setItem(`presmium.document-position.v1:${identity}`, JSON.stringify(point)) } catch { /* Editing does not depend on position storage. */ }
+  }
+
+  forget(identity: string): void {
+    this.#memory.delete(identity)
+    try { sessionStorage.removeItem(`presmium.document-position.v1:${identity}`) } catch { /* Editing remains available. */ }
+  }
+}
+
+export function documentReturnStep(document: TeachingDocument, point: DocumentReturnPoint): number | undefined {
+  const section = document.sections[point.sectionId]
+  if (!section || !document.sectionOrder.includes(point.sectionId)) return
+  if (point.stepId === undefined) return section.stepOrder.length === 0 ? 0 : undefined
+  const index = section.stepOrder.indexOf(point.stepId)
+  return index >= 0 && document.steps[point.stepId]?.sectionId === point.sectionId ? index : undefined
+}
+
+export function documentViewportOffset(element: HTMLElement, sectionId: string): number | undefined {
+  if (!element.clientHeight) return
+  const heading = element.querySelector<HTMLElement>(`[data-document-section="${CSS.escape(sectionId)}"]`)
+  return heading ? element.getBoundingClientRect().top - heading.getBoundingClientRect().top : undefined
+}
+
+export function restoreDocumentViewport(element: HTMLElement, point: DocumentReturnPoint): void {
+  if (!element.clientHeight) return
+  const heading = element.querySelector<HTMLElement>(`[data-document-section="${CSS.escape(point.sectionId)}"]`)
+  if (heading) element.scrollTop += heading.getBoundingClientRect().top - element.getBoundingClientRect().top + (point.offset ?? 0)
+}