@lincyaw/viewer 0.0.0-stage → 1.0.0-rc.1

package/src/client/viewer-messages.ts

@@ -0,0 +1,7 @@
+import { currentLocale } from '@lincyaw/host'
+import { VIEWER_MESSAGES } from '../domain/index.ts'
+import type { Messages } from '../domain/index.ts'
+
+export function viewerMessages(): Messages {
+  return VIEWER_MESSAGES[currentLocale()]
+}

package/src/client/viewer-plugins.ts

@@ -0,0 +1,35 @@
+import { errorMessage } from '@lincyaw/kernel'
+import { BlockView } from './block.ts'
+import { registerAction, registerComponent, registerLayer, registerNodeRenderer, registerView } from './registry.ts'
+import { SectionView } from './section.ts'
+import { useViewer } from './viewer-state.ts'
+
+export interface ViewerPluginContext {
+  registerView: typeof registerView
+  registerNodeRenderer: typeof registerNodeRenderer
+  registerComponent: typeof registerComponent
+  registerAction: typeof registerAction
+  registerLayer: typeof registerLayer
+  useViewer: typeof useViewer
+  SectionView: typeof SectionView
+  BlockView: typeof BlockView
+}
+
+export type ViewerPlugin = (context: ViewerPluginContext) => void
+
+const context: ViewerPluginContext = { registerView, registerNodeRenderer, registerComponent, registerAction, registerLayer, useViewer, SectionView, BlockView }
+
+/** Installs a viewer plugin; returns why it could not be installed, or undefined when it was. */
+export function tryInstallViewerPlugin(plugin: unknown, name = 'viewer plugin'): string | undefined {
+  if (typeof plugin !== 'function') {
+    console.error(`[presmium] ${name}: the default export is not a function`)
+    return 'the default export is not a function'
+  }
+  try {
+    (plugin as ViewerPlugin)(context)
+    return undefined
+  } catch (error) {
+    console.error(`[presmium] ${name} failed`, error)
+    return errorMessage(error)
+  }
+}

package/src/client/viewer-state.ts

@@ -0,0 +1,47 @@
+import { createContext, useContext } from 'react'
+import type { ReactNode } from 'react'
+import { createStore, joinWindows } from '@lincyaw/host'
+import type { Store } from '@lincyaw/host'
+import { PREVIEW_REVISION } from '@lincyaw/kernel'
+import type { IRDocument, IRSection, SourcePos } from '@lincyaw/kernel'
+import { applyUpdate, clampPosition, footnoteSections, keepPosition, nextPosition, prevPosition } from '../domain/index.ts'
+import type { LiveUpdate, Position } from '../domain/index.ts'
+import { findView } from './registry.ts'
+export interface ViewerOptions { renderer?: string, embedded?: boolean, externalControls?: boolean, documentIdentity?: string, editingActive?: Store<boolean>, confirmedRevision?: Store<string | undefined>, slidesOnly?: boolean, pageLink?(position: Position): { href: string, label: string } | undefined, sectionHref?(id: string): string, sectionHeading?(section: IRSection, step: number): ReactNode, diagnostics?: boolean, navigate?(position: Position): void, openPresenter?(position: Position): void, openSource?(source: SourcePos): void, refreshPresentation?(): void, exitPresentation?(): void }
+export interface Viewer {
+  doc: Store<IRDocument>, view: Store<string>, pageView: Store<string>, position: Store<Position>, restoring: Store<boolean>, options: ViewerOptions & { renderer: string },
+  section(id: string): IRSection | undefined, footnoteHref(identifier: string): string,
+  go(position: Position, remote?: boolean): void, show(position: Position): void, next(): boolean, prev(): boolean, setView(id: string): void, update(update: LiveUpdate): void, replace(doc: IRDocument): void,
+}
+/** A live presentation opens only the revision explicitly confirmed by its embedding author. */
+export function presentationConfirmed(viewer: Viewer): boolean {
+  const confirmed = viewer.options.confirmedRevision
+  return !confirmed || Boolean(confirmed.getSnapshot() && confirmed.getSnapshot() === viewer.doc.getSnapshot().meta[PREVIEW_REVISION])
+}
+export const VIEWER = createContext<Viewer | undefined>(undefined)
+export const footnoteId = (identifier: string) => `fn-${identifier}`
+export function createViewer(initial: IRDocument, options: ViewerOptions = {}): Viewer {
+  const doc = createStore(initial), view = createStore('document'), pageView = createStore('document'), position = createStore(clampPosition(initial, { section: initial.sections[0]?.id ?? '', step: 0 })), restoring = createStore(false)
+  const presenting = () => findView(view.getSnapshot())?.kind === 'overlay'
+  const windows = joinWindows(`presmium.viewer.position:${initial.meta.title}`, value => { if (presenting()) viewer.go(value as Position, true) }, () => undefined)
+  const replace = (next: IRDocument) => { const kept = keepPosition(doc.getSnapshot(), next, position.getSnapshot()); doc.set(next); position.set(kept) }
+  const viewer: Viewer = {
+    doc, view, pageView, position, restoring, options: { ...options, renderer: options.renderer ?? 'web' }, section: id => doc.getSnapshot().sections.find(s => s.id === id),
+    footnoteHref(identifier) { const anchor = `#${footnoteId(identifier)}`; const section = footnoteSections(doc.getSnapshot()).get(identifier); return section && options.sectionHref ? `${options.sectionHref(section).split('#')[0]}${anchor}` : anchor },
+    go(target, remote = false) { const next = clampPosition(doc.getSnapshot(), target); const before = position.getSnapshot(); if (before.section === next.section && before.step === next.step && before.boundary === next.boundary) return; position.set(next); if (!remote && presenting()) windows?.send(next) },
+    show(target) {
+      const before = position.getSnapshot()
+      viewer.go(target)
+      // Explicitly selecting the current step also pauses and repositions an
+      // active lecture through the existing navigation operation subscribers.
+      if (position.getSnapshot() === before) position.set({ ...before })
+      if (!presenting()) restoring.set(true)
+    },
+    next() { const next = nextPosition(doc.getSnapshot(), position.getSnapshot()); if (next) viewer.go(next); return Boolean(next) },
+    prev() { const next = prevPosition(doc.getSnapshot(), position.getSnapshot()); if (next) viewer.go(next); return Boolean(next) },
+    setView(id) { const target = findView(id); if (!target || id === view.getSnapshot() || (options.slidesOnly && target.kind === 'page')) return; view.set(id); if (target.kind === 'page') pageView.set(id); restoring.set(true) },
+    update: update => replace(applyUpdate(doc.getSnapshot(), update)), replace,
+  }
+  return viewer
+}
+export function useViewer(): Viewer { const viewer = useContext(VIEWER); if (!viewer) throw new Error('[presmium] no viewer provider'); return viewer }

package/src/client/views/actions.ts

@@ -0,0 +1,52 @@
+import { useEffect } from 'react'
+import { createStore } from '@lincyaw/host'
+import { keyBelongsToTarget, watchFocusSource } from '@lincyaw/kernel'
+import { listActions } from '../registry.ts'
+import type { ViewerAction } from '../registry.ts'
+import type { Viewer } from '../viewer-state.ts'
+import { presentationConfirmed } from '../viewer-state.ts'
+
+/** Whether the present view shows its overview of the sections. */
+export const overviewOpen = createStore(false)
+
+export const BUILTIN_ACTIONS: readonly ViewerAction[] = [
+  { id: 'next', keys: ['ArrowRight', 'ArrowDown', 'PageDown', ' '], run: (viewer) => { viewer.next() } },
+  { id: 'prev', keys: ['ArrowLeft', 'ArrowUp', 'PageUp', 'Backspace'], run: (viewer) => { viewer.prev() } },
+  { id: 'first', keys: ['Home'], run: viewer => viewer.go({ section: viewer.doc.getSnapshot().sections[0]?.id ?? '', step: 0 }) },
+  { id: 'last', keys: ['End'], run: viewer => viewer.go({ section: viewer.doc.getSnapshot().sections.at(-1)?.id ?? '', step: Number.POSITIVE_INFINITY }) },
+  { id: 'exit', keys: ['Escape'], views: ['present'], run: viewer => (viewer.options.slidesOnly ? false : viewer.options.exitPresentation ? viewer.options.exitPresentation() : viewer.setView(viewer.pageView.getSnapshot())) },
+  {
+    id: 'presenter',
+    keys: ['p'],
+    views: ['present'],
+    run: viewer => viewer.options.openPresenter ? viewer.options.openPresenter(viewer.position.getSnapshot()) : false,
+  },
+  { id: 'overview', keys: ['o'], views: ['present'], run: () => { overviewOpen.set(!overviewOpen.getSnapshot()) } },
+]
+
+const builtin = new Set(BUILTIN_ACTIONS.map(action => action.id))
+
+/**
+ * Runs the registered actions of a view on their keys while the view is mounted. A plugin's action comes before the
+ * built-in one on the same key and hands the key on by returning false: the lecture player takes Space to play or
+ * pause, and without a player Space moves to the next step.
+ */
+export function useActions(viewer: Viewer, view: string, extra: readonly ViewerAction[] = []): void {
+  const onKey = (event: KeyboardEvent) => {
+    if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || keyBelongsToTarget(event)) return
+    const actions = listActions(view)
+    for (const action of [...extra, ...actions.filter(action => !builtin.has(action.id)), ...actions.filter(action => builtin.has(action.id))]) {
+      if (!action.keys.includes(event.key)) continue
+      if (!presentationConfirmed(viewer) && action.id !== 'exit') return
+      if (action.run(viewer, event) === false) continue
+      event.preventDefault()
+      return
+    }
+  }
+  useEffect(() => {
+    watchFocusSource(document)
+    window.addEventListener('keydown', onKey)
+    document.documentElement.classList.add('pm-presenting')
+    return () => { window.removeEventListener('keydown', onKey); document.documentElement.classList.remove('pm-presenting') }
+  }, [viewer, view, extra])
+}

package/src/client/views/controls.css

@@ -0,0 +1,44 @@
+.pm-present .pm-present__bar,
+.pm-presenter .pm-presenter__bar {
+  gap: var(--pm-space-1);
+  padding: var(--pm-space-1) var(--pm-space-2);
+  font-size: var(--pm-text-xs);
+}
+
+.pm-present__bar .pm-present__counter {
+  font-family: var(--pm-font-mono);
+  font-variant-numeric: tabular-nums;
+}
+
+.pm-content-marks { display: none; }
+.pm-present__captions {
+  position: absolute;
+  box-sizing: border-box;
+  inset: 0;
+  display: flex;
+  align-items: flex-end;
+  justify-content: center;
+  padding: var(--pm-space-4) var(--pm-space-4) var(--pm-caption-safe-bottom);
+  pointer-events: none;
+}
+.pm-present__captions > * {
+  pointer-events: auto;
+}
+
+.pm-present .pm-present__bar {
+  position: relative;
+  flex-wrap: nowrap;
+  min-width: 0;
+}
+.pm-present .pm-present__bar[hidden] { display: none; }
+@media (max-width: 479px) {
+  .pm-present__bar:has(.pm-lecture-player) .pm-present__previous,
+  .pm-present__bar:has(.pm-lecture-player) .pm-present__next,
+  .pm-present__bar:has(.pm-lecture-player) .pm-present__presenter,
+  .pm-present__bar:has(.pm-lecture-player) .pm-present__overview {
+    display: none;
+  }
+}
+
+/* Keep recovery controls in the existing bar while unconfirmed content stays unavailable. */
+.pm-present[data-pending-confirmation] .pm-present__slide { visibility: hidden; }

package/src/client/views/document.ts

@@ -0,0 +1,12 @@
+import type { IRSection } from '@lincyaw/kernel'
+import { SectionView } from '../section.ts'
+import { useViewer } from '../viewer-state.ts'
+import { h } from '../element.ts'
+export function DocumentView({ sections }: { sections: IRSection[] }) {
+  const viewer = useViewer()
+  return h('div', { className: 'pm-view pm-view--document' }, sections.map(section => h(SectionView, {
+    key: section.id,
+    section,
+    layout: section.hints[viewer.options.renderer]?.layout === 'scrolly' ? 'scrolly' : 'document',
+  })))
+}

package/src/client/views/outlets.ts

@@ -0,0 +1,37 @@
+import { useEffect } from 'react'
+import { useStore } from '@lincyaw/host'
+import { blockVisible, irBlocks } from '@lincyaw/kernel'
+import { findView, registryRevision } from '../registry.ts'
+import { useViewer } from '../viewer-state.ts'
+import { h } from '../element.ts'
+
+/** A later step may belong to a block far below the page heading. */
+function stepElement(viewer: ReturnType<typeof useViewer>, sectionId: string, step: number): HTMLElement | null {
+  const heading = document.getElementById(sectionId)
+  const section = viewer.section(sectionId)
+  const root = heading?.closest('.pm-section')
+  if (!root || !section) return heading
+  if (root.classList.contains('pm-section--scrolly'))
+    return root.querySelector<HTMLElement>(`.pm-step[data-step="${step}"]`) ?? heading
+  if (step === 0) return heading
+  const candidates = [...irBlocks(section.blocks)]
+    .filter(block => block.role === 'visual' && blockVisible(block, step) && !(block.node.type === 'component' && block.node.layer === 'overlay'))
+    .sort((a, b) => {
+      const aCurrent = step <= a.at + (a.span ?? 0)
+      const bCurrent = step <= b.at + (b.span ?? 0)
+      return Number(bCurrent) - Number(aCurrent) || b.at - a.at
+    })
+  for (const block of candidates) {
+    const id = CSS.escape(block.id)
+    const element = root.querySelector<HTMLElement>(`[data-block="${id}"]`)
+    if (element && element.getBoundingClientRect().height > 0 && getComputedStyle(element).visibility !== 'hidden') return element
+  }
+  return heading
+}
+export function PageViewOutlet({ sections }: { sections: string[] }) {
+  const viewer = useViewer(); useStore(viewer.doc); const page = useStore(viewer.pageView); const view = useStore(viewer.view); const restoring = useStore(viewer.restoring); const position = useStore(viewer.position); useStore(registryRevision)
+  useEffect(() => { if (!restoring || findView(view)?.kind !== 'page') return; const frame = requestAnimationFrame(() => { const element = stepElement(viewer, position.section, position.step); if (element) { element.scrollIntoView({ block: 'start' }); viewer.restoring.set(false) } else { viewer.options.navigate?.(position) } }); return () => cancelAnimationFrame(frame) }, [restoring, view, position, sections])
+  const definition = findView(page) ?? findView('document')
+  return h('div', { className: 'pm-view-host pm-document', 'aria-busy': restoring }, definition ? h(definition.component, { sections: sections.flatMap(id => viewer.section(id) ?? []) }) : null)
+}
+export function OverlayViewOutlet() { const viewer = useViewer(); const view = useStore(viewer.view); useStore(registryRevision); const definition = findView(view); return definition?.kind === 'overlay' ? h(definition.component, { key: view }) : null }

package/src/client/views/overlay.ts

@@ -0,0 +1,16 @@
+import { useEffect } from 'react'
+import type { RefObject } from 'react'
+import { PmIconButton, useStore } from '@lincyaw/host'
+import type { IconName } from '@lincyaw/host'
+import type { IRSection } from '@lincyaw/kernel'
+import { BlockView } from '../block.ts'
+import { listLayers } from '../registry.ts'
+import type { ViewerLayer } from '../registry.ts'
+import type { Viewer } from '../viewer-state.ts'
+import { h } from '../element.ts'
+export function useModal(root: RefObject<HTMLElement | null>, embedded = false) { useEffect(() => { if (!embedded || document.hasFocus()) root.current?.focus({ preventScroll: true }) }, [root, embedded]) }
+export function useOverlayBar(bar: RefObject<HTMLElement | null>) { useEffect(() => { const element = bar.current; if (!element) return; const update = () => document.documentElement.style.setProperty('--pm-overlay-bar', `${element.offsetHeight}px`); const observer = new ResizeObserver(update); observer.observe(element); update(); return () => { observer.disconnect(); document.documentElement.style.removeProperty('--pm-overlay-bar') } }, [bar]) }
+export function useCurrentSection(viewer: Viewer, _view: string) { const position = useStore(viewer.position); useStore(viewer.doc); return { section: viewer.section(position.section), step: position.step } }
+export function visuals(section: IRSection, step: number) { return section.blocks.filter(block => block.role === 'visual' && (!block.stepStates?.length || block.stepStates.some(state => state.visible))).map(block => h(BlockView, { key: `${section.id}/${block.id}`, block, section, step })) }
+export function button(label: string, onClick: () => void, icon: IconName, shortcut?: string, attrs: Record<string, unknown> = {}) { const keys: Record<string, string> = { ArrowLeft: '←', ArrowRight: '→', Escape: 'Esc', 'Shift+F': '⇧ F' }; return h(PmIconButton, { ...attrs, icon, label, small: true, hint: shortcut ? `${label} · ${keys[shortcut] ?? shortcut.toUpperCase()}` : label, 'aria-keyshortcuts': shortcut, onClick }) }
+export function layers(view: string, scope: NonNullable<ViewerLayer['scope']>, props: Record<string, unknown> = {}) { return listLayers(view).filter(layer => (layer.scope ?? 'viewport') === scope).map(layer => h(layer.component, { key: layer.id, view, ...props })) }

package/src/client/views/present.ts

@@ -0,0 +1,132 @@
+import { FocusScope } from '@radix-ui/react-focus-scope'
+import { PmApprovals, PmCaption, PmCaptionProvider, PmIcon, TIMED_CAPTIONS, useService, PLAYBACK_CONTROL, presmiumService } from '@lincyaw/host'
+import { useEffect, useRef, useState } from 'react'
+import { useStore } from '@lincyaw/host'
+import { h } from '../element.ts'
+import { viewerMessages } from '../viewer-messages.ts'
+import { useViewer, presentationConfirmed } from '../viewer-state.ts'
+import type { Viewer } from '../viewer-state.ts'
+import { overviewOpen, useActions } from './actions.ts'
+import { button, layers, useCurrentSection, useModal, useOverlayBar } from './overlay.ts'
+import { SlideFace, SlideFit, useSlides } from './slide.ts'
+
+function moveInOverview(root: HTMLElement | null | undefined, key: string): boolean {
+  const items = [...root?.querySelectorAll<HTMLElement>('.pm-overview__item') ?? []]
+  if (!items.length) return false
+  const at = Math.max(items.indexOf(document.activeElement as HTMLElement), 0)
+  const columns = items.filter(item => item.offsetTop === items[0]!.offsetTop).length
+  const moves: Record<string, number> = { ArrowRight: 1, ArrowLeft: -1, ArrowDown: columns, ArrowUp: -columns, Home: -at, End: items.length }
+  if (!(key in moves)) return false
+  items[Math.min(Math.max(at + moves[key]!, 0), items.length - 1)]!.focus()
+  return true
+}
+
+/** The slides form's way out: a link to the same place on the document's page, when there is one. */
+function pageLink(viewer: Viewer) {
+  const link = viewer.options.pageLink?.(viewer.position.getSnapshot())
+  return link ? h('a', { 'class': 'pm-ui-icon-button pm-ui-icon-button--small', 'href': link.href, 'aria-label': link.label, 'title': link.label }, [h(PmIcon, { name: 'document' })]) : null
+}
+
+export function PresentView() {
+    const viewer = useViewer()
+    const { section, step } = useCurrentSection(viewer, 'present')
+    const root = useRef<HTMLDivElement>(null)
+    const bar = useRef<HTMLDivElement>(null)
+    const [captionContainer, setCaptionContainer] = useState<HTMLDivElement | null>(null)
+    const { shape } = useSlides()
+    useOverlayBar(bar)
+    const ownsFullscreen = useRef(false)
+    const [fullscreen, setFullscreen] = useState(false)
+    const [captions, setCaptions] = useState(true)
+    const timedCaptions = useStore(useService(TIMED_CAPTIONS)?.active, false)
+    const overview = useStore(overviewOpen)
+    const doc = useStore(viewer.doc)
+    useStore(viewer.options.confirmedRevision)
+    const pending = !presentationConfirmed(viewer)
+    useEffect(() => { if (pending) { overviewOpen.set(false); presmiumService(PLAYBACK_CONTROL)?.pause() } }, [pending])
+    const position = useStore(viewer.position)
+    const pageView = useStore(viewer.pageView)
+    const syncFullscreen = () => { setFullscreen(Boolean(document.fullscreenElement)) }
+    const enterFullscreen = () => {
+      if (document.fullscreenElement) return void document.exitFullscreen().catch(() => {})
+      void document.documentElement.requestFullscreen().then(() => {
+        if (!root.current) return document.exitFullscreen()
+        ownsFullscreen.current = true
+      }).catch(() => {})
+    }
+    const closeOverview = () => {
+      overviewOpen.set(false)
+      root.current?.focus()
+    }
+    useActions(viewer, 'present', [{ id: 'fullscreen', keys: ['F'], run: enterFullscreen }])
+    const onOverviewKey = (event: KeyboardEvent) => {
+      if (pending || !overview || event.key === 'Tab' || event.altKey || event.ctrlKey || event.metaKey) return
+      event.stopImmediatePropagation()
+      if (event.key === 'Escape' || event.key === 'o') closeOverview()
+      else if (!moveInOverview(root.current, event.key)) return
+      event.preventDefault()
+    }
+    useModal(root, viewer.options.embedded)
+    useEffect(() => {
+      window.addEventListener('keydown', onOverviewKey, { capture: true })
+      document.addEventListener('fullscreenchange', syncFullscreen)
+      return () => {
+      window.removeEventListener('keydown', onOverviewKey, { capture: true })
+      document.removeEventListener('fullscreenchange', syncFullscreen)
+      }
+    }, [overview])
+    useEffect(() => () => { overviewOpen.set(false); if (ownsFullscreen.current && document.fullscreenElement === document.documentElement) void document.exitFullscreen().catch(() => {}) }, [])
+    useEffect(() => { if (overview) root.current?.querySelector<HTMLElement>('.pm-overview__item[aria-current="true"]')?.focus() }, [overview])
+    const jump = (id: string) => {
+      viewer.go({ section: id, step: 0 })
+      closeOverview()
+    }
+
+      const current = section
+      if (!current) return null
+      const t = viewerMessages()
+      const { sections } = doc
+      const stepId = current.stepIds?.[step]
+      const narration = stepId ? current.stepNarrations?.[stepId] ?? [] : []
+      const hasNarration = sections.some(section => Object.values(section.stepNarrations ?? {}).some(lines => lines.some(line => line.text.trim())))
+      return h(PmCaptionProvider, { container: captionContainer }, h(FocusScope, { trapped: !viewer.options.embedded, loop: !viewer.options.embedded, asChild: true,
+        onMountAutoFocus: (event: Event) => { if (viewer.options.embedded) event.preventDefault() },
+        onUnmountAutoFocus: (event: Event) => { if (viewer.options.embedded) event.preventDefault() },
+      }, h('div', null, [h('div', {
+        'ref': root,
+        'class': 'pm-present',
+        'role': 'region',
+        'aria-label': t.present.region,
+        'tabindex': -1,
+        'data-section': current.id,
+        'data-step': step,
+        'data-pending-confirmation': pending || undefined,
+      }, [
+        h('div', { class: 'pm-present__slide', inert: pending ? '' : undefined, 'aria-hidden': pending || undefined }, [
+          h(SlideFit, { shape: shape, overlay: h('div', { ref: setCaptionContainer, className: 'pm-present__captions' }) }, h(SlideFace, { key: current.id, section: current, step: step })),
+          overview
+            ? h('div', { 'class': 'pm-overview', 'role': 'dialog', 'aria-label': t.present.overview }, h('ol', { class: 'pm-overview__grid' }, sections.map(s => h('li', { key: s.id }, h('button', {
+                'type': 'button',
+                'class': 'pm-overview__item',
+                'data-section': s.id,
+                'aria-current': s.id === current.id ? 'true' : undefined,
+                'onClick': () => jump(s.id),
+              }, [h('span', { class: 'pm-overview__index' }, String(s.index)), h('span', { class: 'pm-overview__title' }, s.title)])))))
+            : null,
+        ]),
+        !pending && captions && !timedCaptions && narration.some(item => item.text.trim()) ? h(PmCaption, { overlay: true, label: t.present.captions, lines: narration.map(item => item.text).filter(text => text.trim()), lang: doc.meta.lang }) : null,
+        h('div', { ref: bar, class: 'pm-present__bar', hidden: viewer.options.externalControls || undefined }, [
+          button(t.present.prev, () => viewer.prev(), 'chevron-left', 'ArrowLeft', { className: 'pm-present__previous', disabled: pending }),
+          button(t.present.next, () => viewer.next(), 'chevron-right', 'ArrowRight', { className: 'pm-present__next', disabled: pending }),
+          ...pending ? [] : layers('present', 'bar'),
+          hasNarration && !timedCaptions ? button(t.present.captions, () => setCaptions(value => !value), 'captions', undefined, { 'aria-pressed': captions, disabled: pending }) : null,
+          button(t.present.overview, () => overviewOpen.set(!overview), 'overview', 'o', { disabled: pending, 'aria-pressed': overview, className: 'pm-present__overview' }),
+          viewer.options.openPresenter ? button(t.present.presenter, () => viewer.options.openPresenter!(position), 'slides', 'p', { className: 'pm-present__presenter', disabled: pending }) : null,
+          viewer.options.refreshPresentation ? button(t.present.refresh, () => viewer.options.refreshPresentation!(), 'refresh') : null,
+          button(fullscreen ? t.present.exitFullscreen : t.present.fullscreen, enterFullscreen, fullscreen ? 'exit-fullscreen' : 'fullscreen', 'Shift+F', { 'aria-pressed': fullscreen, disabled: pending }),
+          viewer.options.slidesOnly ? pageLink(viewer) : button(t.present.exit, () => viewer.options.exitPresentation ? viewer.options.exitPresentation() : viewer.setView(pageView), 'close', 'Escape'),
+          pending ? null : h(PmApprovals, { placement: 'above' }),
+        ]),
+        ...pending ? [] : layers('present', 'view'),
+      ]), ...pending ? [] : layers('present', 'viewport')])))
+}

package/src/client/views/presenter.ts

@@ -0,0 +1,76 @@
+import { FocusScope } from '@radix-ui/react-focus-scope'
+import { PmApprovals } from '@lincyaw/host'
+import { blockText, sectionNarration } from '@lincyaw/kernel'
+import { useEffect, useRef, useState } from 'react'
+import { useStore } from '@lincyaw/host'
+import { h } from '../element.ts'
+import { nextPosition } from '../../domain/index.ts'
+import { BlockView } from '../block.ts'
+import { viewerMessages } from '../viewer-messages.ts'
+import { useViewer } from '../viewer-state.ts'
+import { useActions } from './actions.ts'
+import { button, layers, useCurrentSection, useModal, useOverlayBar } from './overlay.ts'
+import { SlideFace, SlideFit, useSlides } from './slide.ts'
+
+function clock(ms: number): string {
+  const s = Math.floor(ms / 1000)
+  return `${String(Math.floor(s / 60)).padStart(2, '0')}:${String(s % 60).padStart(2, '0')}`
+}
+
+export function PresenterView() {
+    const viewer = useViewer()
+    const { section, step } = useCurrentSection(viewer, 'presenter')
+    const root = useRef<HTMLDivElement>(null)
+    const bar = useRef<HTMLDivElement>(null)
+    useActions(viewer, 'presenter')
+    useOverlayBar(bar)
+    useModal(root, viewer.options.embedded)
+    const [started, setStarted] = useState(Date.now)
+    const [now, setNow] = useState(Date.now)
+    useEffect(() => { const timer = setInterval(() => setNow(Date.now()), 1000); return () => clearInterval(timer) }, [])
+    const { shape } = useSlides()
+    const doc = useStore(viewer.doc)
+    const position = useStore(viewer.position)
+    const following = nextPosition(doc, position)
+    const t = viewerMessages()
+    const target = following ? viewer.section(following.section) : undefined
+    const upcoming = !following ? t.presenter.end : following.section !== section?.id ? t.presenter.nextSection(target!.title) : sectionNarration(target!).filter(block => block.at === following.step).map(blockText).join('\n') || t.presenter.nextStep(following.step)
+      const current = section
+      if (!current) return null
+      const notes = sectionNarration(current)
+      return h(FocusScope, { trapped: !viewer.options.embedded, loop: !viewer.options.embedded, asChild: true,
+        onMountAutoFocus: (event: Event) => { if (viewer.options.embedded) event.preventDefault() },
+        onUnmountAutoFocus: (event: Event) => { if (viewer.options.embedded) event.preventDefault() },
+      }, h('div', null, [h('div', { 'ref': root, 'tabindex': -1, 'class': 'pm-presenter', 'data-section': current.id, 'data-step': step }, [
+        h('div', { ref: bar, class: 'pm-presenter__bar' }, [
+          h('strong', { class: 'pm-presenter__title' }, `${current.index}. ${current.title}`),
+          current.steps > 0 ? h('span', { class: 'pm-presenter__counter' }, t.presenter.step(step, current.steps)) : null,
+          h('span', { 'class': 'pm-presenter__timer', 'aria-label': t.presenter.timer }, clock(now - started)),
+          button(t.presenter.restart, () => { const time = Date.now(); setStarted(time); setNow(time) }, 'redo'),
+          button(t.present.prev, () => viewer.prev(), 'chevron-left', 'ArrowLeft'),
+          button(t.present.next, () => viewer.next(), 'chevron-right', 'ArrowRight'),
+          ...layers('presenter', 'bar'),
+          h(PmApprovals),
+        ]),
+        h('div', { class: 'pm-presenter__main' }, [
+          h('div', { class: 'pm-presenter__slide' }, h(SlideFit, { shape: shape }, h(SlideFace, { key: current.id, section: current, step: step, view: 'presenter' }))),
+          h('div', { class: 'pm-presenter__side' }, [
+            h('p', { class: 'pm-presenter__label' }, t.presenter.notes),
+            h('div', { class: 'pm-presenter__notes' }, notes.length
+              ? notes.map(block => h('div', {
+                  'key': block.id,
+                  'class': ['pm-presenter__note', { 'pm-current': block.at === step }],
+                  'data-step': block.at,
+                  'aria-current': block.at === step ? 'step' : undefined,
+                }, [h(BlockView, { block, section: current, step: step, expanded: true })]))
+              : [h('p', { class: 'pm-presenter__empty' }, t.presenter.noNotes)]),
+            h('p', { class: 'pm-presenter__label' }, t.presenter.upcoming),
+            following
+              ? h('div', { class: 'pm-presenter__upcoming', inert: '' }, h(SlideFit, { shape: shape }, h(SlideFace, { key: `${following!.section}@${following!.step}`, section: viewer.section(following!.section)!, step: following!.step, view: 'presenter-next' })))
+              : null,
+            h('p', { class: 'pm-presenter__next' }, upcoming),
+          ]),
+        ]),
+        ...layers('presenter', 'view'),
+      ]), ...layers('presenter', 'viewport')]))
+}

package/src/client/views/scrolly.ts

@@ -0,0 +1,4 @@
+import type { IRSection } from '@lincyaw/kernel'
+import { SectionView } from '../section.ts'
+import { h } from '../element.ts'
+export function ScrollyView({ sections }: { sections: IRSection[] }) { return h('div', { className: 'pm-view pm-view--scrolly' }, sections.map(section => h(SectionView, { key: section.id, section, layout: 'scrolly' }))) }

package/src/client/views/slide.css

@@ -0,0 +1,8 @@
+.pm-slide--cover .pm-slide__body {
+  flex: 0 1 auto;
+}
+
+.pm-slide-fit__overlay {
+  position: absolute;
+  pointer-events: none;
+}

package/src/client/views/slide.ts

@@ -0,0 +1,57 @@
+import { useMessages, useStore } from '@lincyaw/host'
+import { slideChapters, slideShape } from '@lincyaw/kernel'
+import type { IRSection, SlideShape } from '@lincyaw/kernel'
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import { SECTION_CONTEXT } from '../section-context.ts'
+import { useViewer } from '../viewer-state.ts'
+import { h } from '../element.ts'
+import { layers, visuals } from './overlay.ts'
+import './slide.css'
+const MESSAGES = { 'zh-CN': { steps: (at: number, of: number) => `第 ${at} 步，共 ${of} 步` }, en: { steps: (at: number, of: number) => `Step ${at} of ${of}` } }
+const LAYOUTS = new Set(['default', 'cover', 'center', 'full'])
+function slideOptions(section: IRSection, cover: boolean) { const hints = section.hints.slides ?? {}; const zoom = Number(hints.zoom); return { layout: typeof hints.layout === 'string' && LAYOUTS.has(hints.layout) ? hints.layout : cover ? 'cover' : 'default', className: typeof hints.class === 'string' ? hints.class : undefined, zoom: Number.isFinite(zoom) && zoom > 0 ? zoom : undefined } }
+export function useSlides() { const viewer = useViewer(); const doc = useStore(viewer.doc); return { viewer, shape: slideShape(doc), chapters: slideChapters(doc) } }
+export function SlideFit({ shape, scale: fixed, children, overlay }: { shape: SlideShape, scale?: number, children?: ReactNode, overlay?: ReactNode }) {
+  const box = useRef<HTMLDivElement>(null)
+  const [size, setSize] = useState<{ width: number, height: number }>()
+  useEffect(() => {
+    const observer = new ResizeObserver(([entry]) => setSize({ width: entry!.contentRect.width, height: entry!.contentRect.height }))
+    if (box.current) observer.observe(box.current)
+    return () => observer.disconnect()
+  }, [])
+  const { width, height } = shape
+  const scale = fixed ?? (size ? Math.min(size.width / width, size.height / height) : 1)
+  const left = size && fixed === undefined ? (size.width - width * scale) / 2 : 0
+  const top = size && fixed === undefined ? (size.height - height * scale) / 2 : 0
+  return h('div', { ref: box, className: 'pm-slide-fit' }, [
+    h('div', { className: 'pm-slide-fit__canvas', style: { width: `${width}px`, height: `${height}px`, transform: `translate(${left}px, ${top}px) scale(${scale})` } }, children),
+    // Captions follow the canvas bounds without shrinking their text with the slide.
+    overlay ? h('div', { className: 'pm-slide-fit__overlay', style: { left, top, width: width * scale, height: height * scale } }, overlay) : null,
+  ])
+}
+
+// The shrink is measured after layout and before paint and written to the element itself, not through a render:
+// a render would come a frame late, and the new slide would show for that frame at full size.
+function SlideBody({ zoom, children }: { zoom?: number, children?: ReactNode }) {
+  const frame = useRef<HTMLDivElement>(null)
+  const content = useRef<HTMLDivElement>(null)
+  useLayoutEffect(() => {
+    const outer = frame.current, inner = content.current
+    if (!outer || !inner) return
+    const measure = () => {
+      const scale = Math.min(1, outer.clientHeight / Math.max(1, inner.scrollHeight), outer.clientWidth / Math.max(1, inner.scrollWidth))
+      const left = Math.max(0, (outer.clientWidth - inner.offsetWidth * scale) / 2)
+      inner.style.transform = scale < 1 ? `translateX(${left}px) scale(${scale})` : ''
+    }
+    const observer = new ResizeObserver(measure)
+    observer.observe(outer)
+    observer.observe(inner)
+    measure()
+    return () => observer.disconnect()
+  }, [])
+  return h('div', { ref: frame, className: 'pm-slide__body' }, h('div', { ref: content, className: 'pm-slide__content', style: zoom ? { zoom } : undefined }, children))
+}
+
+export function SlideFace({ section, step, view = 'present' }: { section: IRSection, step: number, view?: string }) { const { viewer, chapters } = useSlides(); const doc = useStore(viewer.doc); const t = useMessages(MESSAGES); const { sections } = doc; const options = slideOptions(section, section.index === 1 && sections.length > 1); const chapter = options.layout === 'cover' || options.layout === 'full' ? undefined : chapters.get(section.id); const done = Math.min(step, section.steps); return h(SECTION_CONTEXT.Provider, { value: { section, step, view } }, h('div', { class: ['pm-slide', `pm-slide--${options.layout}`, options.className], 'data-section': section.id, 'data-slide': section.index, 'data-step': step }, [chapter ? h('p', { className: 'pm-slide__chapter' }, chapter) : null, h(SlideBody, { key: section.id, zoom: options.zoom }, [h(options.layout === 'cover' ? 'h1' : 'h2', { className: 'pm-slide__title' }, section.title), ...visuals(section, step)]), options.layout === 'full' ? null : h('footer', { className: 'pm-slide__footer' }, [options.layout === 'cover' ? null : h('span', { className: 'pm-slide__deck' }, doc.meta.title), section.steps > 0 ? h('span', { className: 'pm-slide__steps', role: 'img', 'aria-label': t.steps(done, section.steps), style: { '--pm-slide-steps': section.steps } }, Array.from({ length: section.steps }, (_, i) => h('span', { key: i, 'data-done': i < done ? '' : undefined }))) : null, h('span', { className: 'pm-slide__page' }, `${section.index} / ${sections.length}`)]), h('div', { className: 'pm-slide__layers' }, layers(view, 'slide', { section: section.id, step }))])) }
+export function SlidesPrint({ steps = false, slides }: { steps?: boolean, slides?: readonly number[] }) { const { viewer, shape } = useSlides(); const doc = useStore(viewer.doc); useEffect(() => { let disposed = false; void (async () => { await document.fonts.ready; await Promise.all([...document.images].map(image => image.complete ? undefined : new Promise<void>(done => { image.addEventListener('load', () => done(), { once: true }); image.addEventListener('error', () => done(), { once: true }) }))); if (!disposed) document.documentElement.setAttribute('data-presmium-printed', '') })(); return () => { disposed = true; document.documentElement.removeAttribute('data-presmium-printed') } }, []); const chosen = slides && new Set(slides); const pages = doc.sections.filter(section => !chosen || chosen.has(section.index)).flatMap(section => steps ? Array.from({ length: section.steps + 1 }, (_, step) => ({ section, step })) : [{ section, step: section.steps }]); return h('div', { className: 'pm-slides-print', style: { '--pm-slide-width': `${shape.width}px`, '--pm-slide-height': `${shape.height}px` } }, pages.map(({ section, step }) => h('div', { key: `${section.id}@${step}`, className: 'pm-slides-print__page', style: { width: `${shape.width}px`, height: `${shape.height}px` } }, h(SlideFace, { section, step, view: 'print' })))) }

package/src/domain/clicks.ts

@@ -0,0 +1,38 @@
+import { stepStateAt } from '@lincyaw/kernel'
+
+export interface ClickSpec {
+  kind: 'click' | 'after'
+  at?: unknown
+  hide?: boolean
+}
+
+export interface ClickRange {
+  from: number
+  to?: number
+  hide: boolean
+}
+
+function isRelative(at: unknown): at is string {
+  return typeof at === 'string' && /^[+-]\d+$/.test(at.trim())
+}
+
+export function resolveClicks(specs: readonly ClickSpec[]): ClickRange[] {
+  let last = 0
+  const position = (at: unknown, base: number): number => {
+    if (isRelative(at)) return base + Number(at.trim())
+    const value = Number(at)
+    return Number.isFinite(value) ? value : base + 1
+  }
+  return specs.map((spec) => {
+    const at = spec.kind === 'after' ? '+0' : spec.at ?? '+1'
+    const [enter, leave] = Array.isArray(at) ? at : [at]
+    const from = position(enter, last)
+    if (isRelative(enter) || !Number.isFinite(Number(enter))) last = from
+    const to = leave === undefined ? undefined : position(leave, from)
+    return { from, to, hide: spec.hide ?? false }
+  })
+}
+
+export function clickVisible(range: ClickRange, step: number): boolean {
+  return stepStateAt(range, step).active !== range.hide
+}

package/src/domain/code-width.ts

@@ -0,0 +1,11 @@
+const WIDE = /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]|[\u{1F300}-\u{1FAFF}\u{20000}-\u{3FFFD}]/u
+
+export function codeColumns(code: string): number {
+  let widest = 0
+  for (const line of code.split('\n')) {
+    let width = 0
+    for (const char of line) width += char === '\t' ? 4 : WIDE.test(char) ? 2 : 1
+    widest = Math.max(widest, width)
+  }
+  return widest
+}

package/src/domain/document-content.ts

@@ -0,0 +1,6 @@
+import type { IRBlock, IRDocument } from '@lincyaw/kernel'
+
+/** Legacy prose remains visible without changing its authored narration binding. */
+export function isLegacyNarration(document: IRDocument, block: IRBlock): boolean {
+  return document.meta.contentModel !== 'blocks' && block.role === 'narration' && (!block.only || block.only.includes('lecture'))
+}

package/src/domain/footnotes.ts

@@ -0,0 +1,15 @@
+import { docBlocks } from '@lincyaw/kernel'
+import type { IRDocument, MdastNode } from '@lincyaw/kernel'
+
+function definitions(node: MdastNode, found: (identifier: string) => void): void {
+  if (node.type === 'footnoteDefinition' && node.identifier !== undefined) found(String(node.identifier))
+  node.children?.forEach(child => definitions(child, found))
+}
+
+export function footnoteSections(doc: IRDocument): Map<string, string> {
+  const sections = new Map<string, string>()
+  for (const { section, block: { node } } of docBlocks(doc)) {
+    if (node.type === 'markdown') definitions(node.mdast, identifier => sections.set(identifier, section.id))
+  }
+  return sections
+}