@lincyaw/host 1.0.0-rc.0 → 1.0.0-rc.2

package/README.md

@@ -1,8 +1,8 @@
 # @lincyaw/host
 
-Presmium's host interface for plugin components: step state, services, shared state, interface text and the design system, the same in the web form (VitePress) and in the slides (Slidev).
+Presmium's host interface for plugin components: step state, services, shared state, interface text, the site path and the design system, the same in the web form and in the slides (both are the viewer).
 
-Part of [Presmium](https://github.com/Lincyaw/presmium), which turns lectures written in MyST Markdown into web pages, slides, Jupyter notebooks and narrated lectures.
+Part of [Presmium](https://github.com/Lincyaw/presmium), which compiles canonical lecture.json teaching documents into web pages, slides, Jupyter notebooks and narrated playback.
 
 ## Install
 
@@ -10,30 +10,29 @@ Plugins declare it as a peer dependency (`"@lincyaw/host": "^1.0.0"`); a documen
 
 ## Usage
 
-```vue
-<script setup lang="ts">
+```tsx
 import { useMessages, useStepState } from '@lincyaw/host'
 
-const shown = useStepState({ from: 1 })
-const t = useMessages({ 'zh-CN': { done: '完成' }, 'en': { done: 'Done' } })
-</script>
-
-<template>
-  <p v-if="shown.reached">{{ t.done }}</p>
-</template>
+export default function Completion() {
+  const shown = useStepState({ from: 1 })
+  const t = useMessages({ 'zh-CN': { done: '完成' }, en: { done: 'Done' } })
+  return shown.reached ? <p>{t.done}</p> : null
+}
 ```
 
-Components get everything through this package, never from `@slidev/*` or `vitepress`, so both forms render them. It also provides the design system: the `Pm*` components (`PmButton`, `PmDialog`, `PmIcon` and others) in Vue, over the `--pm-*` tokens, the classes and the fonts (IBM Plex Sans, IBM Plex Mono and Source Serif 4, SIL Open Font License 1.1) of `@lincyaw/design`, which it loads into every page.
+Components get everything through this package, so both forms render them; browser code finds the site path with `siteBase()`, not `import.meta.env.BASE_URL`. It also provides the design system: the `Pm*` components (`PmButton`, `PmDialog`, `PmIcon` and others) in React, over the `--pm-*` tokens, the classes and the fonts (IBM Plex Sans, IBM Plex Mono and Source Serif 4, SIL Open Font License 1.1) of `@lincyaw/design`, which it loads into every page.
+
+The interactive primitives wrap Radix Primitives; positioning, dismissal, keyboard navigation and focus management come from the library. Theme observation uses host React hooks, and shared icon names map to Lucide.
 
-The interactive primitives wrap Reka UI; positioning, dismissal, keyboard navigation and focus management come from the library. Theme observation uses VueUse, and the shared icon names map to Lucide.
+Hooks return ordinary React values. `useSharedState` returns `[value, setValue]`; service observables use `Store<T>` and `useStore(store)`. Outside components, read services with `presmiumService` and server access with `serverClient()`, then release subscriptions in plugin disposal.
 
 ## Experimental parts
 
-`useToolbarPlace` and `provideToolbarPlace` are experimental and outside the 1.x semver promise; their declarations carry the TSDoc tag `@experimental`, and the interface list names them.
+`useToolbarPlacement` and `provideToolbarPlacement` are experimental and outside the 1.x semver promise; their declarations carry the TSDoc tag `@experimental`, and the interface list names them.
 
 ## Documentation
 
-- [Plugin guide](https://github.com/Lincyaw/presmium/blob/main/site/plugins/lecture.en.md)
+- [Plugin guide](https://github.com/Lincyaw/presmium/blob/main/site/plugins/locales/en/lecture.json)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincyaw/host",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.2",
   "description": "Presmium's host interface for plugin components in every form: step state, services, interface text, and the design system (tokens, components, fonts)",
   "license": "Apache-2.0",
   "repository": {
@@ -12,7 +12,7 @@
   "bugs": "https://github.com/Lincyaw/presmium/issues",
   "keywords": [
     "presmium",
-    "vue",
+    "react",
     "design-system"
   ],
   "type": "module",
@@ -33,10 +33,19 @@
     "@fontsource/ibm-plex-mono": "5.3.0",
     "@fontsource/ibm-plex-sans": "5.3.0",
     "@fontsource/source-serif-4": "5.3.1",
-    "@vueuse/core": "15.0.0",
-    "reka-ui": "2.11.0",
-    "vue": "^3.5.42",
-    "@lincyaw/design": "1.0.0-rc.0",
-    "@lincyaw/kernel": "1.0.0-rc.0"
+    "@radix-ui/react-dialog": "^1.3.1",
+    "@radix-ui/react-dropdown-menu": "^2.2.1",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-radio-group": "^1.5.1",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "@lincyaw/design": "1.0.0-rc.2",
+    "@lincyaw/kernel": "1.0.0-rc.2"
+  },
+  "devDependencies": {
+    "@types/react": "18.3.28",
+    "@types/react-dom": "18.3.7"
   }
 }

package/src/actions.ts

@@ -0,0 +1,22 @@
+import { useEffect, useRef } from 'react'
+import type { RefObject } from 'react'
+import { blockKeyOf } from './blocks.ts'
+import type { Operations, ReplayHandler } from './contracts.ts'
+export type ComponentAction = (seeking: boolean) => void
+export interface ActionOptions { clear?(): void }
+interface Registration { element(): Element | undefined, actions: Readonly<Record<string, ComponentAction>>, clear?(): void }
+const registered = new Set<Registration>()
+const done = new Map<string, string[]>()
+let operations: Operations | undefined
+const record = (block: string, action: string) => done.set(block, [...done.get(block) ?? [], action])
+function keyOf(element: Element | null | undefined) { const block = element?.closest<HTMLElement>('.pm-block[data-block]'); return block ? blockKeyOf(block) : undefined }
+export function useActions(element: RefObject<Element | null | undefined>, actions: Readonly<Record<string, ComponentAction>>, options: ActionOptions = {}): (name: string) => void {
+  const current = useRef({ actions, options }); current.current = { actions, options }
+  useEffect(() => { const registration: Registration = { element: () => element.current ?? undefined, get actions() { return current.current.actions }, clear: () => current.current.options.clear?.() }; registered.add(registration); const block = keyOf(element.current); for (const name of block ? done.get(block) ?? [] : []) current.current.actions[name]?.(true); return () => { registered.delete(registration) } }, [element])
+  return name => { const action = current.current.actions[name]; if (!action) return; action(false); const block = keyOf(element.current); if (!block) return; record(block, name); operations?.report({ type: 'click', data: { block, action: name } }) }
+}
+const clickReplay: ReplayHandler = {
+  apply(data, seeking) { if (typeof data.block !== 'string' || typeof data.action !== 'string') return; record(data.block, data.action); for (const registration of registered) { const action = registration.actions[data.action]; if (action && keyOf(registration.element()) === data.block) action(seeking) } },
+  clear() { done.clear(); for (const registration of registered) registration.clear?.() },
+}
+export function connectActions(to: Operations): void { operations = to; to.onReplay('click', clickReplay) }

package/src/approvals.ts

@@ -1,58 +1,12 @@
-import type { PropType } from 'vue'
-import { defineComponent, h, ref, watch } from 'vue'
+import { createElement as h, useState } from 'react'
 import { PmButton, PmNotice, PmPopover } from './design/components.ts'
 import { useMessages } from './locale.ts'
 import { HOST_MESSAGES } from './messages.ts'
-import { approvals } from './server.ts'
-
-export const PmApprovals = defineComponent({
-  name: 'PmApprovals',
-  props: {
-    placement: { type: String as PropType<'below' | 'above'>, default: 'below' },
-  },
-  setup(props) {
-    const t = useMessages(HOST_MESSAGES)
-    const open = ref(false)
-    const failed = ref<string>()
-    watch(() => approvals.pending.value.length, (count) => {
-      if (count === 0) open.value = false
-    })
-    const answer = (id: string, allow: boolean) => {
-      failed.value = undefined
-      approvals.answer(id, allow).catch((error: unknown) => {
-        failed.value = error instanceof Error ? error.message : String(error)
-      })
-    }
-    return () => {
-      const pending = approvals.pending.value
-      if (pending.length === 0) return null
-      return h(PmPopover, {
-        'open': open.value,
-        'label': t.value.approvalsTitle,
-        'name': 'pm-approvals',
-        'placement': props.placement === 'above' ? 'above-end' : 'below-end',
-        'onUpdate:open': (next: boolean) => open.value = next,
-      }, {
-        trigger: () => h(PmButton, {
-          'variant': 'accent',
-          'small': true,
-          'class': 'pm-approvals__toggle',
-          'aria-expanded': open.value ? 'true' : 'false',
-          'onClick': () => open.value = !open.value,
-        }, () => t.value.approvals(pending.length)),
-        default: () => [
-          ...pending.map(({ id, request }) => h('div', { 'key': id, 'class': 'pm-approvals__item', 'data-approval': id, 'style': { display: 'grid', gap: 'var(--pm-space-2)' } }, [
-            h('p', { class: 'pm-approvals__title', style: { margin: 0, fontWeight: 600 } }, request.title),
-            h('p', { class: 'pm-approvals__from', style: { margin: 0, color: 'var(--pm-color-muted)' } }, t.value.from(request.from)),
-            request.detail ? h('pre', { class: 'pm-approvals__detail pm-ui-code', style: { margin: 0, whiteSpace: 'pre-wrap' } }, request.detail) : null,
-            h('div', { class: 'pm-approvals__actions', style: { display: 'flex', gap: 'var(--pm-space-2)' } }, [
-              h(PmButton, { variant: 'primary', small: true, onClick: () => answer(id, true) }, () => t.value.allow),
-              h(PmButton, { small: true, onClick: () => answer(id, false) }, () => t.value.deny),
-            ]),
-          ])),
-          failed.value ? h(PmNotice, { class: 'pm-approvals__error', tone: 'danger' }, () => failed.value) : null,
-        ],
-      })
-    }
-  },
-})
+import { approvals } from './control.ts'
+import { useStore } from './store.ts'
+export function PmApprovals({ placement = 'below' }: { placement?: 'below' | 'above' }) {
+  const t = useMessages(HOST_MESSAGES); const [open, setOpen] = useState(false); const [failed, setFailed] = useState<string>(); const pending = useStore(approvals.pending)
+  if (!pending.length) return null
+  const answer = (id: string, allow: boolean) => { setFailed(undefined); void approvals.answer(id, allow).catch(() => setFailed(t.answerFailed)) }
+  return h(PmPopover, { open, label: t.approvalsTitle, name: 'pm-approvals', placement: placement === 'above' ? 'above-end' : 'below-end', onOpenChange: setOpen, trigger: h(PmButton, { variant: 'accent', small: true }, t.approvals(pending.length)) }, pending.map(({ id, request }) => h('div', { key: id, 'data-approval': id }, h('p', {}, request.title), h('p', {}, t.from(t.origins[request.from] ?? t.otherOrigin)), ...(request.detail ?? '').split('\n').filter(Boolean).map((line, key) => h('p', { key }, line)), h(PmButton, { small: true, variant: 'primary', onClick: () => answer(id, true) }, t.allow), h(PmButton, { small: true, onClick: () => answer(id, false) }, t.deny))), failed ? h(PmNotice, { tone: 'danger' }, failed) : null)
+}

package/src/blocks.ts

@@ -1,5 +1,3 @@
-import type { NavigationPosition } from './types.ts'
-
 const UNSEEN = '[inert], .pm-hidden'
 
 export function blockKey(section: string, block: string): string {
@@ -35,13 +33,19 @@ export function codeLines(block: Element): HTMLElement[] {
   return [...block.querySelectorAll<HTMLElement>('.pm-code .line')]
 }
 
+/** The `<section>/<block>` key of a block's element (`.pm-block[data-block]`). */
+export function blockKeyOf(block: HTMLElement): string | undefined {
+  const section = block.closest<HTMLElement>('[data-section]')?.dataset.section
+  return section ? blockKey(section, block.dataset.block!) : undefined
+}
+
 export function blockAt(x: number, y: number, options: { skip?: Element, within?: string } = {}): BlockPoint | undefined {
   if (typeof document === 'undefined') return undefined
   const { skip, within } = options
   const hit = document.elementsFromPoint(x, y).find(el => el !== skip && !skip?.contains(el))
   const element = hit?.closest<HTMLElement>(`${within ? `${within} ` : ''}.pm-block[data-block]`)
-  const section = element?.closest<HTMLElement>('[data-section]')?.dataset.section
-  if (!element || !section || !seen(element)) return undefined
+  const key = element && blockKeyOf(element)
+  if (!element || !key || !seen(element)) return undefined
   const box = element.getBoundingClientRect()
   if (!box.width || !box.height) return undefined
   const index = codeLines(element).findIndex((line) => {
@@ -49,7 +53,7 @@ export function blockAt(x: number, y: number, options: { skip?: Element, within?
     return y >= r.top && y < r.bottom
   })
   return {
-    key: blockKey(section, element.dataset.block!),
+    key,
     element,
     x: (x - box.left) / box.width,
     y: (y - box.top) / box.height,
@@ -75,8 +79,3 @@ export function linesText(numbers: number[]): string {
   }
   return runs.join(',')
 }
-
-export function positionSlide(position: NavigationPosition, sections: readonly { id: string, index: number }[]): number {
-  const named = position.section === undefined ? undefined : sections.find(s => s.id === position.section)
-  return named?.index ?? position.slide
-}

package/src/claim-first.ts

@@ -0,0 +1,13 @@
+import { createStore } from './store.ts'
+import type { Store } from './store.ts'
+const groups = new Map<string, Store<symbol[]>>()
+export function claimFirst(group: string): { owns: Store<boolean>, release(): void } {
+  let owners = groups.get(group)
+  if (!owners) { owners = createStore<symbol[]>([]); groups.set(group, owners) }
+  const list = owners
+  const claim = Symbol(group)
+  list.set([...list.getSnapshot(), claim])
+  const owns = createStore(list.getSnapshot()[0] === claim)
+  const stop = list.subscribe(() => owns.set(list.getSnapshot()[0] === claim))
+  return { owns, release() { stop(); list.set(list.getSnapshot().filter(other => other !== claim)) } }
+}

package/src/code-lines-box.ts

@@ -0,0 +1,11 @@
+import { codeLines, lineNumbers } from './blocks.ts'
+
+export function codeLinesBox(block: HTMLElement, lines: string): DOMRect | undefined {
+  const rows = codeLines(block)
+  const named = lineNumbers(lines).map(n => rows[n - 1]).filter((row): row is HTMLElement => Boolean(row))
+  if (named.length === 0) return undefined
+  const code = block.querySelector('.pm-code')?.getBoundingClientRect() ?? block.getBoundingClientRect()
+  const top = Math.min(...named.map(row => row.getBoundingClientRect().top))
+  const bottom = Math.max(...named.map(row => row.getBoundingClientRect().bottom))
+  return new DOMRect(code.left, top, code.width, bottom - top)
+}

package/src/{types.ts → contracts.ts}

@@ -1,6 +1,8 @@
-import type { Ref } from 'vue'
+import type { Dispatch, SetStateAction } from 'react'
+import type { Store } from './store.ts'
 import { defineService } from '@lincyaw/kernel/contracts'
 import type { Cursor, Member, Operation, PresentationMode, ServiceToken, StartReport, Unsubscribe } from '@lincyaw/kernel/contracts'
+import type { IRDocument, ProductionPlaybackCommand, ProductionPlaybackState } from '@lincyaw/kernel'
 import type { IconName } from '@lincyaw/design'
 
 export type ViewRole = 'audience' | 'presenter' | 'reader'
@@ -10,15 +12,17 @@ export type SharedStateScope = 'view' | 'local' | 'remote'
 export interface HostAdapter {
   readonly mode: PresentationMode
   readonly lang?: string
-  useCursor(): Readonly<Ref<Cursor>>
-  useStep(): Readonly<Ref<number>>
-  useViewRole(): Readonly<Ref<ViewRole>>
-  useStaticRender(): Readonly<Ref<boolean>>
-  useSectionConfig(pluginId: string): Readonly<Ref<Record<string, unknown>>>
-  useSharedState<T>(key: string, initial: T, scope: SharedStateScope): Ref<T>
+  useDoc?(): IRDocument
+  useCursor(): Cursor
+  useStep(): number
+  useViewRole(): ViewRole
+  useStaticRender(): boolean
+  useSectionConfig(pluginId: string): Record<string, unknown>
+  useSharedState<T>(key: string, initial: T, scope: SharedStateScope): [T, Dispatch<SetStateAction<T>>]
+  sharedStateStore?<T>(key: string, initial: T, scope: SharedStateScope): Store<T>
   getService<T>(token: ServiceToken<T>): T | undefined
   startReport(): StartReport | undefined
-  useDarkMode?(): Ref<boolean>
+  useDarkMode?(): [boolean, Dispatch<SetStateAction<boolean>>]
 }
 
 export type SyncPublish = (state: Readonly<Record<string, unknown>>, fromRemote: boolean) => void
@@ -39,12 +43,14 @@ export interface SyncTransports {
 export const SYNC_TRANSPORTS = defineService<SyncTransports>('presmium.syncTransports')
 
 export interface NavigationPosition extends Cursor {
+  /** Transient seek intent; authoring steps and Production retain no duplicate timing. */
+  boundary?: 'start' | 'end'
   view?: string
   section?: string
 }
 
 export interface Navigation {
-  readonly position: Readonly<Ref<NavigationPosition>>
+  readonly position: Store<NavigationPosition>
   go(position: NavigationPosition): void
 }
 
@@ -52,7 +58,7 @@ export const NAVIGATION = defineService<Navigation>('presmium.navigation')
 
 export type ToolbarSlot = 'tools' | 'settings' | 'status'
 
-export type ToolbarPlace = 'bar' | 'status'
+export type ToolbarPlacement = 'bar' | 'status'
 
 export interface ToolbarItem {
   id: string
@@ -73,7 +79,7 @@ export const TOOLBAR = defineService<Toolbar>('presmium.toolbar')
 
 export interface ServerClient {
   readonly available: boolean
-  readonly member: Readonly<Ref<Member | undefined>>
+  readonly member: Store<Member | undefined>
   fetch(plugin: string, path: string, init?: RequestInit): Promise<Response>
   events(plugin: string, path: string): EventSource
 }
@@ -101,7 +107,51 @@ export interface Operations {
   onReplay(type: string, handler: ReplayHandler): Unsubscribe
   replay(operation: Operation, seeking?: boolean): boolean
   clear(): void
-  readonly replaying: Ref<boolean>
+  readonly replaying: Store<boolean>
 }
 
 export const OPERATIONS = defineService<Operations>('presmium.operations')
+
+/** A registered player keeps its existing clock; this lease only coordinates whether it may start. */
+export interface PlaybackLease {
+  requestStart(): Promise<boolean>
+  cancel(): void
+  dispose(): void
+}
+
+export interface PlaybackControl {
+  register(pause: () => void): PlaybackLease
+  pause(): void
+  /** Embedded previews await their author's audio focus before starting. Ordinary pages need no gate. */
+  setGate(authorize: (signal: AbortSignal) => Promise<void>): Unsubscribe
+}
+
+export const PLAYBACK_CONTROL = defineService<PlaybackControl>('presmium.playbackControl')
+
+/** Observes the loaded player's clock and selects stable step boundaries; author interfaces never synthesize time. */
+export interface ProductionPlayback {
+  readonly version: 1
+  readonly state: Pick<Store<ProductionPlaybackState | undefined>, 'getSnapshot' | 'subscribe'>
+  control(command: ProductionPlaybackCommand, signal?: AbortSignal): Promise<ProductionPlaybackState>
+}
+export const PRODUCTION_PLAYBACK = defineService<ProductionPlayback>('presmium.productionPlayback')
+
+/** A loaded timed-caption player owns presentation captions until its lease is released. */
+export interface TimedCaptions {
+  readonly active: Store<boolean>
+  claim(): Unsubscribe
+}
+export const TIMED_CAPTIONS = defineService<TimedCaptions>('presmium.timedCaptions')
+
+export interface StepClockDriver {
+  readonly elapsed: Store<number | undefined>
+  readonly recording?: boolean
+}
+
+export interface StepClock {
+  drive(driver: StepClockDriver): Unsubscribe
+  wait(work: Promise<unknown>): void
+  settled(): Promise<void>
+}
+
+export const STEP_CLOCK = defineService<StepClock>('presmium.stepClock')

package/src/control.ts

@@ -0,0 +1,117 @@
+import { SESSION } from '@lincyaw/kernel/contracts'
+import type { ApprovalRequest, ServiceToken, Unsubscribe } from '@lincyaw/kernel/contracts'
+import { createStore } from './store.ts'
+import type { Store } from './store.ts'
+import type { Navigation, NavigationPosition, ServerClient, StatusRegistry, ViewRole } from './contracts.ts'
+import { clientDocument, clientEventSubscription, documentHeader, pluginRoutePath } from './server.ts'
+
+export interface PendingApproval {
+  id: string
+  request: ApprovalRequest
+}
+
+export interface ApprovalState {
+  pending: Store<PendingApproval[]>
+  answer(id: string, allow: boolean): Promise<void>
+}
+
+const pending = createStore<PendingApproval[]>([])
+let answering: (id: string, allow: boolean) => Promise<void> = async () => {}
+
+export const approvals: ApprovalState = {
+  pending,
+  answer: (id, allow) => answering(id, allow),
+}
+
+function roleOf(position: NavigationPosition): ViewRole {
+  if (position.view === 'presenter') return 'presenter'
+  if (position.view === 'present') return 'audience'
+  if (position.view !== undefined) return 'reader'
+  return typeof location !== 'undefined' && /\/presenter(?:\/|$)/.test(location.pathname) ? 'presenter' : 'audience'
+}
+
+export function connectControl(client: ServerClient, host: {
+  navigation: Navigation
+  status: StatusRegistry
+  service<T>(token: ServiceToken<T>): T | undefined
+}): Unsubscribe {
+  const { navigation, status } = host
+  const document = clientDocument(client)
+  const id = Math.random().toString(36).slice(2, 12)
+  const control = `${pluginRoutePath(client, 'presmium.server')}control`
+  const post = (body: Record<string, unknown>) => fetch(control, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'Presmium-Document': documentHeader(document) },
+    body: JSON.stringify({ window: id, ...body }),
+  }).then(async response => ({ ok: response.ok, status: response.status, text: await response.text() }))
+  answering = async (approval, allow) => {
+    const response = await post({ type: 'answer', id: approval, allow })
+    if (!response.ok) throw new Error(`the server did not take the answer (${response.status})`)
+    pending.set(pending.getSnapshot().filter(p => p.id !== approval))
+  }
+  const subscribe = clientEventSubscription(client)
+  const source = subscribe ? undefined : new EventSource(`${control}?window=${id}&document=${documentHeader(document)}`)
+  const handlers = new Map<string, (data: string) => void>()
+  const on = <T>(event: string, handle: (data: T) => void) => {
+    const receive = (data: string) => {
+      try {
+        handle(JSON.parse(data) as T)
+      } catch (error) {
+        console.error(`[presmium] control channel: bad ${event} message`, error)
+      }
+    }
+    handlers.set(event, receive)
+    source?.addEventListener(event, message => receive((message as MessageEvent<string>).data))
+  }
+  on<PendingApproval>('approval', (approval) => {
+    if (!pending.getSnapshot().some(p => p.id === approval.id)) pending.set([...pending.getSnapshot(), approval])
+  })
+  on<{ id: string }>('settled', (settled) => {
+    pending.set(pending.getSnapshot().filter(p => p.id !== settled.id))
+  })
+  on<NavigationPosition>('go', position => navigation.go(position))
+  on<{ action: 'start' | 'end', name?: string }>('session', ({ action, name }) => {
+    const session = host.service(SESSION)
+    if (!session) return
+    void (action === 'start' ? session.create(name ?? '') : session.end()).catch((error: unknown) => {
+      console.error('[presmium] the classroom command failed', error)
+    })
+  })
+
+  let reported = ''
+  const report = () => {
+    const position = navigation.position.getSnapshot()
+    const summaries = Object.fromEntries(status.list().map((provider) => {
+      try {
+        return [provider.id, provider.read()]
+      } catch {
+        return [provider.id, null]
+      }
+    }))
+    const body = JSON.stringify({ position, role: roleOf(position), status: summaries })
+    if (body === reported) return
+    reported = body
+    void post({ type: 'report', ...JSON.parse(body) as Record<string, unknown> }).catch(() => undefined)
+  }
+  const opened = () => { reported = ''; report() }
+  source?.addEventListener('open', opened)
+  const stopEvents = subscribe?.({ topic: 'viewer-control', document, window: id }, message => {
+    if (message.type === 'open') opened()
+    else if (message.type === 'event') handlers.get(message.event)?.(message.data)
+  })
+  let soon: ReturnType<typeof setTimeout> | undefined
+  const stopWatch = navigation.position.subscribe(() => {
+    soon ??= setTimeout(() => {
+      soon = undefined
+      report()
+    }, 200)
+  })
+  const timer = setInterval(report, 1000)
+  return () => {
+    stopWatch()
+    clearTimeout(soon)
+    clearInterval(timer)
+    stopEvents?.(); source?.close()
+    pending.set([])
+  }
+}

package/src/design/appearance.ts

@@ -0,0 +1,16 @@
+import { useEffect } from 'react'
+import { createStore, useStore } from '../store.ts'
+import { useHost } from '../host.ts'
+export interface Appearance { readonly dark: boolean, setDark(dark: boolean): void, toggle(): void }
+const darkClass = createStore(false)
+let observer: MutationObserver | undefined
+function observe() { if (typeof document === 'undefined' || observer) return; const root = document.documentElement; const read = () => darkClass.set(root.classList.contains('dark')); read(); observer = new MutationObserver(read); observer.observe(root, { attributes: true, attributeFilter: ['class'] }) }
+export function useAppearance(): Appearance {
+  const host = useHost()
+  const observed = useStore(darkClass)
+  const own = host.useDarkMode?.()
+  useEffect(observe, [])
+  const dark = own?.[0] ?? observed
+  const setDark = (on: boolean) => { if (own) own[1](on); else document.documentElement.classList.toggle('dark', on) }
+  return { dark, setDark, toggle: () => setDark(!dark) }
+}

package/src/design/caption.ts

@@ -0,0 +1,31 @@
+import { createContext, createElement as h, useContext } from 'react'
+import type { HTMLAttributes, KeyboardEvent, ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+
+const CaptionContainer = createContext<HTMLElement | null>(null)
+
+/** The viewer supplies a stable caption surface on its scaled slide canvas. */
+export function PmCaptionProvider({ container, children }: { container: HTMLElement | null, children?: ReactNode }) {
+  return h(CaptionContainer.Provider, { value: container }, children)
+}
+
+export interface CaptionProps extends HTMLAttributes<HTMLElement> {
+  label: string
+  lines: readonly string[]
+  hint?: string
+  overlay?: boolean
+}
+
+/** Read-only caption text; its caller owns the source and playback position. */
+export function PmCaption({ label, lines, hint, overlay = false, className, onKeyDown, ...props }: CaptionProps) {
+  const container = useContext(CaptionContainer)
+  const keyDown = (event: KeyboardEvent<HTMLElement>) => {
+    onKeyDown?.(event)
+    if (overlay && !event.defaultPrevented && !event.nativeEvent.isComposing && !event.altKey && !event.ctrlKey && !event.metaKey
+      && ['Home', 'End', 'PageUp', 'PageDown', 'ArrowUp', 'ArrowDown', ' '].includes(event.key)) event.stopPropagation()
+  }
+  const caption = h('section', { ...props, onKeyDown: keyDown, className: ['pm-ui-caption', className].filter(Boolean).join(' '), 'data-overlay': overlay || undefined, 'aria-label': label, 'aria-live': 'polite', 'aria-atomic': true, tabIndex: overlay ? 0 : props.tabIndex },
+    hint ? h('p', { className: 'pm-ui-caption__hint' }, hint) : null,
+    lines.map((text, index) => h('p', { key: index, className: 'pm-ui-caption__line' }, text)))
+  return overlay ? container && createPortal(caption, container) : caption
+}