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

package/src/registries.ts

@@ -0,0 +1,86 @@
+import type { PresenterPanel, PresenterPanels, Unsubscribe } from '@lincyaw/kernel'
+import { currentLocale } from './locale.ts'
+import { HOST_MESSAGES } from './messages.ts'
+import StartReportPanel from './start-report-panel.ts'
+import type { StatusProvider, StatusRegistry, TimedCaptions, Toolbar, ToolbarItem } from './contracts.ts'
+import { createStore } from './store.ts'
+
+export function createTimedCaptions(): TimedCaptions {
+  const owners = new Set<symbol>(), active = createStore(false)
+  return { active, claim() {
+    const owner = Symbol()
+    owners.add(owner); active.set(true)
+    return () => { if (owners.delete(owner)) active.set(owners.size > 0) }
+  } }
+}
+
+interface Item {
+  id: string
+  order?: number
+}
+
+interface Registry<T extends Item> {
+  register(item: T): Unsubscribe
+  list(): T[]
+  subscribe(listener: () => void): Unsubscribe
+}
+
+function createRegistry<T extends Item>(kind: string): Registry<T> {
+  const items = new Map<string, T>()
+  const listeners = new Set<() => void>()
+  const notify = () => listeners.forEach(listener => listener())
+  return {
+    register(item) {
+      if (items.has(item.id)) throw new Error(`${kind} ${item.id} is already registered`)
+      items.set(item.id, item)
+      notify()
+      return () => {
+        if (items.get(item.id) !== item) return
+        items.delete(item.id)
+        notify()
+      }
+    },
+    list() {
+      return [...items.values()].sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+  }
+}
+
+export function createPresenterPanels(): PresenterPanels {
+  const service = createRegistry<PresenterPanel>('presenter panel')
+  service.register({
+    id: 'presmium.core.start-report',
+    get title() {
+      return HOST_MESSAGES[currentLocale()].startReport
+    },
+    component: StartReportPanel,
+    order: -1,
+  })
+  return service
+}
+
+export function createToolbar(): Toolbar {
+  return createRegistry<ToolbarItem>('toolbar item')
+}
+
+export function createStatusRegistry(onChange?: () => void): StatusRegistry {
+  const providers = new Map<string, StatusProvider>()
+  return {
+    register(provider) {
+      providers.set(provider.id, provider)
+      onChange?.()
+      return () => {
+        if (providers.get(provider.id) !== provider) return
+        providers.delete(provider.id)
+        onChange?.()
+      }
+    },
+    list: () => [...providers.values()],
+  }
+}

package/src/resident-worker.ts

@@ -0,0 +1,84 @@
+export interface ResidentWorkerOptions {
+  start(): Worker
+  loadTimeoutMs: number
+}
+
+export type ResidentWorkerFailure = 'cancelled' | 'load-timeout' | 'run-timeout' | 'crashed'
+
+export type ResidentWorkerOutcome<Reply> =
+  | { reply: Reply, elapsedMs: number }
+  | { failure: ResidentWorkerFailure, error?: string, elapsedMs: number }
+
+export interface ResidentWorker<Request extends { id: number }, Reply extends { id: number, type: string }> {
+  send(request: Omit<Request, 'id'>, options: { timeoutMs: number, signal?: AbortSignal }): Promise<ResidentWorkerOutcome<Exclude<Reply, { type: 'started' }>>>
+  hasWorker(): boolean
+  dispose(): void
+}
+
+/**
+ * A dedicated Worker kept between requests, which it takes one at a time. Until the worker replies `started` the load
+ * timeout runs, then the request's own; a timeout, an abort or a crash ends the worker, and the next request starts another.
+ */
+export function createResidentWorker<Request extends { id: number }, Reply extends { id: number, type: string }>(options: ResidentWorkerOptions): ResidentWorker<Request, Reply> {
+  type Outcome = ResidentWorkerOutcome<Exclude<Reply, { type: 'started' }>>
+  let worker: Worker | undefined
+  let queue: Promise<unknown> = Promise.resolve()
+  let ids = 0
+  let cancel: (() => void) | undefined
+  let disposed = false
+
+  return {
+    send(request, { timeoutMs, signal }) {
+      const job = () => new Promise<Outcome>((resolve) => {
+        if (disposed || signal?.aborted) return resolve({ failure: 'cancelled', elapsedMs: 0 })
+        const target = worker ??= options.start()
+        const id = ++ids
+        let started = 0
+        const elapsed = () => (started ? Math.round(performance.now() - started) : 0)
+        const finish = (outcome: Outcome) => {
+          clearTimeout(timer)
+          cancel = undefined
+          target.removeEventListener('message', onMessage)
+          target.removeEventListener('error', onError)
+          signal?.removeEventListener('abort', onAbort)
+          resolve(outcome)
+        }
+        const stop = (failure: ResidentWorkerFailure, error?: string) => {
+          target.terminate()
+          if (worker === target) worker = undefined
+          finish({ failure, ...error === undefined ? {} : { error }, elapsedMs: elapsed() })
+        }
+        const onMessage = ({ data }: MessageEvent<Reply>) => {
+          if (data.id !== id) return
+          if (data.type === 'started') {
+            clearTimeout(timer)
+            started = performance.now()
+            timer = setTimeout(() => stop('run-timeout'), timeoutMs)
+          } else {
+            finish({ reply: data as Exclude<Reply, { type: 'started' }>, elapsedMs: elapsed() })
+          }
+        }
+        const onError = (event: ErrorEvent) => stop('crashed', event.message)
+        const onAbort = () => stop('cancelled')
+        cancel = onAbort
+        target.addEventListener('message', onMessage)
+        target.addEventListener('error', onError)
+        signal?.addEventListener('abort', onAbort)
+        let timer = setTimeout(() => stop('load-timeout'), options.loadTimeoutMs)
+        target.postMessage({ ...request, id })
+      })
+      const outcome = queue.then(job)
+      queue = outcome.catch(() => undefined)
+      return outcome
+    },
+    hasWorker: () => worker !== undefined,
+    dispose() {
+      if (disposed) return
+      disposed = true
+      cancel?.()
+      worker?.terminate()
+      worker = undefined
+      queue = Promise.resolve()
+    },
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,187 @@
+import { Kernel, PRESENTER_PANELS } from '@lincyaw/kernel'
+import type { EnvironmentSpec, Logger, PluginDefinition, PluginReport, PresentationMode, ServiceToken, StartReport } from '@lincyaw/kernel'
+import { createStore } from './store.ts'
+import { connectActions } from './actions.ts'
+import { PmApprovals } from './approvals.ts'
+import { NAVIGATION, OPERATIONS, PLAYBACK_CONTROL, STATUS, STEP_CLOCK, SYNC_TRANSPORTS, TIMED_CAPTIONS, TOOLBAR } from './contracts.ts'
+import type { Navigation, ServerClient, SyncTransports } from './contracts.ts'
+import { connectControl } from './control.ts'
+import { componentErrors } from './error-boundary.ts'
+import { currentLocale } from './locale.ts'
+import { HOST_MESSAGES } from './messages.ts'
+import { createOperations } from './operations.ts'
+import { createPlaybackControl } from './playback-control.ts'
+import { createPresenterPanels, createStatusRegistry, createTimedCaptions, createToolbar } from './registries.ts'
+import { provideServer } from './server.ts'
+import { createStepClock } from './step-clock.ts'
+
+export const runtimeRevision = createStore(0)
+
+const registered: PluginDefinition[] = []
+const running = createStore<Kernel | undefined>(undefined)
+let starting: Promise<StartReport> | undefined
+interface RuntimeOwner { kernel: Kernel, releases: (() => void)[], started?: Promise<StartReport> }
+let runtime: RuntimeOwner | undefined
+let lifecycle: Promise<unknown> = Promise.resolve()
+const failures = createStore<PluginReport[]>([])
+let resumeHost: (() => Promise<StartReport>) | undefined
+let hostActive = true
+let resumePage: (() => void) | undefined
+let watchingPage = false
+
+export function registerPresmiumPlugin(plugin: PluginDefinition): void {
+  const { id } = plugin.manifest
+  if (starting) console.error(`[presmium] ${id} was registered after the kernel started; ignored`)
+  else if (registered.some(p => p.manifest.id === id)) console.error(`[presmium] plugin ${id} is already registered; ignored`)
+  else registered.push(plugin)
+}
+
+function isPluginDefinition(value: unknown): value is PluginDefinition {
+  const plugin = value as Partial<PluginDefinition> | null
+  return typeof plugin === 'object' && plugin !== null && typeof plugin.setup === 'function' && typeof plugin.manifest?.id === 'string'
+}
+
+export function pluginsOf(module: unknown): PluginDefinition[] {
+  const values = Object.values((module ?? {}) as Record<string, unknown>).flatMap(v => (Array.isArray(v) ? v : [v]))
+  return [...new Set(values.filter(isPluginDefinition))]
+}
+
+interface StartOptions {
+  mode: PresentationMode
+  config?: Record<string, unknown>
+  beforeStart?(kernel: Kernel, release: (stop: () => void) => void): void
+  log?: Logger
+  environments?: Record<string, EnvironmentSpec>
+}
+
+function transition<T>(change: () => Promise<T>): Promise<T> {
+  const next = lifecycle.then(change)
+  lifecycle = next.catch(() => undefined)
+  return next
+}
+
+function startKernel(options: StartOptions): Promise<StartReport> {
+  starting = transition(async () => {
+    if (runtime) return runtime.started!
+    const owner: RuntimeOwner = { kernel: new Kernel({ mode: options.mode, config: options.config, log: options.log, environments: options.environments }), releases: [] }
+    runtime = owner
+    owner.started = (async () => {
+      options.beforeStart?.(owner.kernel, stop => owner.releases.push(stop))
+      for (const plugin of registered) owner.kernel.register(plugin)
+      const report = await owner.kernel.start()
+      running.set(owner.kernel); runtimeRevision.set(n => n + 1)
+      return report
+    })()
+    return owner.started
+  })
+  return starting
+}
+
+/** Stops the kernel and disposes the plugins; `startHost` or `setHostActive(true)` starts it again. */
+export function stopHost(): Promise<void> {
+  const requested = starting
+  return transition(async () => {
+    const owner = runtime
+    try {
+      if (!owner) return
+      if (running.getSnapshot() === owner.kernel) {
+        running.set(undefined); runtimeRevision.set(n => n + 1)
+      }
+      const results = await Promise.allSettled([
+        ...owner.releases.splice(0).reverse().map(async release => release()),
+        owner.kernel.dispose(),
+      ])
+      const failed = results.find(result => result.status === 'rejected')
+      if (failed?.status === 'rejected') throw failed.reason
+    } finally {
+      if (runtime === owner) runtime = undefined
+      if (starting === requested) starting = undefined
+    }
+  })
+}
+
+function stopOnPageHide(start: () => void): void {
+  resumePage = start
+  if (watchingPage) return
+  watchingPage = true
+  window.addEventListener('pagehide', () => void stopHost())
+  window.addEventListener('pageshow', (event) => {
+    if (event.persisted && hostActive) resumePage?.()
+  })
+}
+
+export async function setHostActive(active: boolean): Promise<void> {
+  hostActive = active
+  if (active) await resumeHost?.()
+  else await stopHost()
+}
+
+export function presmiumService<T>(token: ServiceToken<T>): T | undefined {
+  return running.getSnapshot()?.getService(token)
+}
+
+export function reportPluginFailure(id: string, reason: string): void {
+  failures.set([...failures.getSnapshot().filter(report => report.id !== id), { id, status: 'failed', reason }]); runtimeRevision.set(n => n + 1)
+}
+
+export function presmiumReport(): StartReport | undefined {
+  const report = running.getSnapshot()?.report()
+  return report && failures.getSnapshot().length ? { ...report, plugins: [...report.plugins, ...failures.getSnapshot()] } : report
+}
+
+export interface HostStart {
+  mode: PresentationMode
+  config: Record<string, unknown>
+  navigation: Navigation
+  transports: SyncTransports
+  environments?: Record<string, EnvironmentSpec>
+  server?: ServerClient
+}
+
+export function startHost(options: HostStart): Promise<StartReport> {
+  if (options.server) provideServer(options.server)
+  const start = () => startKernel({
+    mode: options.mode,
+    config: options.config,
+    environments: options.environments,
+    beforeStart(kernel, release) {
+      const toolbar = createToolbar()
+      const status = createStatusRegistry()
+      kernel.provide(PRESENTER_PANELS, createPresenterPanels())
+      kernel.provide(SYNC_TRANSPORTS, options.transports)
+      kernel.provide(NAVIGATION, options.navigation)
+      kernel.provide(TOOLBAR, toolbar)
+      const operations = createOperations()
+      connectActions(operations)
+      kernel.provide(OPERATIONS, operations)
+      kernel.provide(PLAYBACK_CONTROL, createPlaybackControl())
+      kernel.provide(TIMED_CAPTIONS, createTimedCaptions())
+      const stepClock = createStepClock(options.navigation)
+      release(stepClock.stop)
+      kernel.provide(STEP_CLOCK, stepClock.clock)
+      kernel.provide(STATUS, status)
+      status.register({
+        id: 'presmium.runtime',
+        read: () => ({
+          plugins: (presmiumReport()?.plugins ?? []).slice(-40).map(plugin => ({ id: plugin.id, status: plugin.status, ...plugin.reason ? { reason: plugin.reason.slice(0, 2000) } : {} })),
+          errors: componentErrors().slice(-20).map(error => ({ component: error.component, message: error.message.slice(0, 2000) })),
+        }),
+      })
+      const { server } = options
+      if (!server?.available) return
+      toolbar.register({
+        id: 'presmium.approvals',
+        get title() {
+          return HOST_MESSAGES[currentLocale()].approvalsTitle
+        },
+        component: PmApprovals,
+        order: 1000,
+      })
+      release(connectControl(server, { navigation: options.navigation, status, service: token => kernel.getService(token) }))
+    },
+  })
+  resumeHost = start
+  hostActive = true
+  stopOnPageHide(() => void setHostActive(true))
+  return start()
+}

package/src/server.ts

@@ -1,173 +1,36 @@
-import { SESSION } from '@lincyaw/kernel/contracts'
-import type { ApprovalRequest, Member, ServiceToken, Unsubscribe } from '@lincyaw/kernel/contracts'
-import type { Ref } from 'vue'
-import { computed, shallowRef, watch } from 'vue'
+import type { PreviewEventSubscription } from '@lincyaw/kernel/contracts'
+import type { Member } from '@lincyaw/kernel/contracts'
 import { currentLocale } from './locale.ts'
-import type { Navigation, NavigationPosition, ServerClient, StatusRegistry, ViewRole } from './types.ts'
-
+import type { ServerClient } from './contracts.ts'
+import { createStore, useStore } from './store.ts'
 export const SERVER_PATH = '/__presmium/presmium.server'
-
-const UNAVAILABLE: ServerClient = {
-  available: false,
-  member: computed(() => undefined),
-  fetch: () => Promise.reject(new Error('no Presmium server serves this page')),
-  events() {
-    throw new Error('no Presmium server serves this page')
-  },
-}
-
-const current = shallowRef<ServerClient>(UNAVAILABLE)
+const UNAVAILABLE: ServerClient = { available: false, member: createStore<Member | undefined>(undefined), fetch: () => Promise.reject(new Error('no Presmium server serves this page')), events() { throw new Error('no Presmium server serves this page') } }
+const current = createStore<ServerClient>(UNAVAILABLE)
 const documents = new WeakMap<ServerClient, string>()
-
-const facade: ServerClient = {
-  get available() {
-    return current.value.available
-  },
-  get member() {
-    return current.value.member
-  },
-  fetch: (plugin, path, init) => current.value.fetch(plugin, path, init),
-  events: (plugin, path) => current.value.events(plugin, path),
-}
-
-export function useServer(): ServerClient {
-  return facade
-}
-
-export function provideServer(client: ServerClient | undefined): void {
-  current.value = client ?? UNAVAILABLE
-}
-
-function documentHeader(document: string): string {
-  return encodeURIComponent(document)
-}
-
-export function createServerClient(options: { document?: string } = {}): ServerClient {
+const subscriptions = new WeakMap<ServerClient, PreviewEventSubscription>()
+const roots = new WeakMap<ServerClient, string>()
+/** The path a plugin's own server routes are below on this page: `<root>__presmium/<plugin>/`. */
+export function pluginRoutePath(client: ServerClient, plugin: string): string { return `${roots.get(client) ?? '/'}__presmium/${plugin}/` }
+export function clientEventSubscription(client: ServerClient): PreviewEventSubscription | undefined { return subscriptions.get(client) }
+export function clientDocument(client: ServerClient): string { return documents.get(client) ?? '' }
+export function serverClient(): ServerClient { return current.getSnapshot() }
+export function useServer(): ServerClient { return useStore(current) }
+export function provideServer(client: ServerClient | undefined): void { current.set(client ?? UNAVAILABLE) }
+export function documentHeader(document: string): string { return encodeURIComponent(document) }
+/** `root`: the path the server's routes are below (`/user/a/preview/` behind a proxy that forwards a path); `/` by default. */
+export function createServerClient(options: { document?: string, root?: string, subscribeEvents?: PreviewEventSubscription } = {}): ServerClient {
   const document = options.document ?? ''
-  const member = shallowRef<Member>()
-  const url = (plugin: string, path: string) => `/__presmium/${plugin}/${path.replace(/^\//, '')}`
+  const root = (options.root ?? '/').replace(/\/?$/, '/')
+  const member = createStore<Member | undefined>(undefined)
+  const url = (plugin: string, path: string) => `${root}__presmium/${plugin}/${path.replace(/^\//, '')}`
   const client: ServerClient = {
-    available: true,
-    member: computed(() => member.value),
-    fetch(plugin, path, init = {}) {
-      const headers = new Headers(init.headers)
-      headers.set('Presmium-Document', documentHeader(document))
-      if (!headers.has('Accept-Language')) headers.set('Accept-Language', currentLocale())
-      return fetch(url(plugin, path), { ...init, headers })
-    },
-    events(plugin, path) {
-      const target = url(plugin, path)
-      return new EventSource(`${target}${target.includes('?') ? '&' : '?'}document=${documentHeader(document)}`)
-    },
+    available: true, member,
+    fetch(plugin, path, init = {}) { const headers = new Headers(init.headers); headers.set('Presmium-Document', documentHeader(document)); if (!headers.has('Accept-Language')) headers.set('Accept-Language', currentLocale()); return fetch(url(plugin, path), { ...init, headers }) },
+    events(plugin, path) { const target = url(plugin, path); return new EventSource(`${target}${target.includes('?') ? '&' : '?'}document=${documentHeader(document)}`) },
   }
-  void fetch(`${SERVER_PATH}/hello`, { headers: { 'Presmium-Document': documentHeader(document) } })
-    .then(response => (response.ok ? response.json() : response.text().then(() => undefined)))
-    .then((hello: { member?: Member } | undefined) => {
-      member.value = hello?.member
-    })
-    .catch(() => undefined)
+  void fetch(`${root}${SERVER_PATH.slice(1)}/hello`, { headers: { 'Presmium-Document': documentHeader(document) } }).then(response => response.ok ? response.json() : undefined).then((hello: { member?: Member } | undefined) => member.set(hello?.member)).catch(() => undefined)
   documents.set(client, document)
+  roots.set(client, root)
+  if (options.subscribeEvents) subscriptions.set(client, options.subscribeEvents)
   return client
 }
-
-export interface PendingApproval {
-  id: string
-  request: ApprovalRequest
-}
-
-export interface ApprovalState {
-  pending: Ref<PendingApproval[]>
-  answer(id: string, allow: boolean): Promise<void>
-}
-
-const pending = shallowRef<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 = documents.get(client) ?? ''
-  const id = Math.random().toString(36).slice(2, 12)
-  const post = (body: Record<string, unknown>) => fetch(`${SERVER_PATH}/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.value = pending.value.filter(p => p.id !== approval)
-  }
-  const source = new EventSource(`${SERVER_PATH}/control?window=${id}&document=${documentHeader(document)}`)
-  const on = <T>(event: string, handle: (data: T) => void) => source.addEventListener(event, (message) => {
-    try {
-      handle(JSON.parse((message as MessageEvent<string>).data) as T)
-    } catch (error) {
-      console.error(`[presmium] control channel: bad ${event} message`, error)
-    }
-  })
-  on<PendingApproval>('approval', (approval) => {
-    if (!pending.value.some(p => p.id === approval.id)) pending.value = [...pending.value, approval]
-  })
-  on<{ id: string }>('settled', (settled) => {
-    pending.value = pending.value.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.value
-    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)
-  }
-  source.addEventListener('open', () => {
-    reported = ''
-    report()
-  })
-  let soon: ReturnType<typeof setTimeout> | undefined
-  const stopWatch = watch(() => navigation.position.value, () => {
-    soon ??= setTimeout(() => {
-      soon = undefined
-      report()
-    }, 200)
-  }, { deep: true })
-  const timer = setInterval(report, 1000)
-  return () => {
-    stopWatch()
-    clearTimeout(soon)
-    clearInterval(timer)
-    source.close()
-    pending.value = []
-  }
-}

package/src/session.ts

@@ -1,34 +1,10 @@
+import { useEffect, useState } from 'react'
 import { SESSION } from '@lincyaw/kernel'
-import type { SessionService, SessionSnapshot } from '@lincyaw/kernel'
-import type { ComputedRef, Ref } from 'vue'
-import { computed, getCurrentScope, onScopeDispose, shallowRef, watchEffect } from 'vue'
+import type { SessionSnapshot } from '@lincyaw/kernel'
 import { useService } from './host.ts'
-
-export function useSessionSnapshot(): { session: ComputedRef<SessionService | undefined>, snapshot: Readonly<Ref<SessionSnapshot | undefined>> } {
+export function useSessionSnapshot() {
   const session = useService(SESSION)
-  const snapshot = shallowRef<SessionSnapshot>()
-  watchEffect((onCleanup) => {
-    const current = session.value
-    snapshot.value = current?.snapshot()
-    if (current) onCleanup(current.subscribe(next => snapshot.value = next))
-  })
+  const [snapshot, setSnapshot] = useState<SessionSnapshot>()
+  useEffect(() => { setSnapshot(session?.snapshot()); return session?.subscribe(setSnapshot) }, [session])
   return { session, snapshot }
 }
-
-const groups = new Map<string, Ref<symbol[]>>()
-
-export function claimFirst(group: string): { owns: Readonly<Ref<boolean>>, release(): void } {
-  let owners = groups.get(group)
-  if (!owners) {
-    owners = shallowRef<symbol[]>([])
-    groups.set(group, owners)
-  }
-  const list = owners
-  const token = Symbol(group)
-  list.value = [...list.value, token]
-  const release = () => {
-    list.value = list.value.filter(t => t !== token)
-  }
-  if (getCurrentScope()) onScopeDispose(release)
-  return { owns: computed(() => list.value[0] === token), release }
-}

package/src/shared-state.ts

@@ -0,0 +1,30 @@
+import type { SharedStateScope, SyncPublish, SyncTransport, SyncTransports } from './contracts.ts'
+import { createStore } from './store.ts'
+import type { Store } from './store.ts'
+import { joinWindows } from './windows.ts'
+interface Channel { name: string, receive(patch: Record<string, unknown>): void, value(): unknown, publishers: Map<SyncTransport, SyncPublish> }
+export interface SharedStates { sharedState<T>(key: string, initial: T, scope: SharedStateScope): Store<T>, transports: SyncTransports }
+const plain = (value: unknown): unknown => value === undefined ? undefined : JSON.parse(JSON.stringify(value))
+export function createSharedStates(deck: string): SharedStates {
+  const states = new Map<string, Store<unknown>>()
+  const channels = new Map<string, Channel>()
+  const transports = new Set<SyncTransport>()
+  const connect = (transport: SyncTransport, channel: Channel) => { const publish = transport.connect(channel.name, channel.receive, { value: channel.value() }, false); if (publish) channel.publishers.set(transport, publish) }
+  function make(id: string, initial: unknown, scope: SharedStateScope): Store<unknown> {
+    const state = createStore(plain(initial))
+    if (scope === 'view') return state
+    const name = `presmium.shared:${deck}:${id}`
+    let from: 'window' | 'remote' | undefined
+    let changed = false
+    const apply = (value: unknown, source: 'window' | 'remote') => { from = source; state.set(value); from = undefined }
+    const windows = joinWindows(name, value => apply(value, 'window'), () => changed ? plain(state.getSnapshot()) : undefined)
+    const channel: Channel = { name, receive(patch) { if ('value' in patch) apply(patch.value, 'remote') }, value: () => plain(state.getSnapshot()), publishers: new Map() }
+    state.subscribe(() => { changed = true; const value = plain(state.getSnapshot()); if (!from) windows?.send(value); channel.publishers.forEach(publish => publish({ value }, from !== undefined)) })
+    if (scope === 'remote') { channels.set(id, channel); transports.forEach(transport => connect(transport, channel)) }
+    return state
+  }
+  return {
+    sharedState<T>(key: string, initial: T, scope: SharedStateScope) { const id = `${scope}:${key}`; let state = states.get(id); if (!state) { state = make(id, initial, scope); states.set(id, state) } return state as Store<T> },
+    transports: { add(transport) { transports.add(transport); channels.forEach(channel => connect(transport, channel)); return () => { transports.delete(transport); channels.forEach(channel => channel.publishers.delete(transport)) } } },
+  }
+}

package/src/site.ts

@@ -0,0 +1,14 @@
+// The document's site path: where its published files and its plugins' run-time files are. The prebuilt viewer that
+// shows every document is built at no site path of its own, so the page's shell tells it; the slides form's build is
+// at the document's path, which Vite gives.
+let base: string | undefined
+
+/** Sets the document's site path (ending with `/`), as the page's shell knows it. */
+export function setSiteBase(value: string): void {
+  base = value.endsWith('/') ? value : `${value}/`
+}
+
+/** The document's site path, ending with `/`: below it are `media/` and the plugins' run-time files (`pyodide/`). */
+export function siteBase(): string {
+  return base ?? import.meta.env?.BASE_URL ?? '/'
+}

package/src/start-report-panel.ts

@@ -0,0 +1,8 @@
+import { createElement as h } from 'react'
+import { useStartReport } from './host.ts'
+import { useLocale, useMessages } from './locale.ts'
+import { HOST_MESSAGES } from './messages.ts'
+import { useStore } from './store.ts'
+import { componentErrors, componentErrorRevision } from './error-boundary.ts'
+// Plugins by the names they declare; a reason the kernel gives (service ids, error text) stays in the console, where it logs it.
+export default function StartReportPanel() { const t = useMessages(HOST_MESSAGES); const locale = useLocale(); const report = useStartReport(); useStore(componentErrorRevision); return h('div', { className: 'pm-start-report' }, report === undefined ? h('p', {}, t.starting) : report.plugins.length ? h('ul', {}, report.plugins.map(plugin => h('li', { key: plugin.id, 'data-plugin': plugin.id, 'data-status': plugin.status }, `${plugin.name?.[locale] ?? t.unnamedPlugin}${t.because}${t.status[plugin.status]}`))) : h('p', {}, t.noPlugins), componentErrors().map((error, key) => h('p', { key, role: 'alert' }, t.componentError(error.component, error.message)))) }