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

package/src/messages.ts

@@ -0,0 +1,66 @@
+import type { PluginStatus } from '@lincyaw/kernel/contracts'
+import type { Catalog } from './locale.ts'
+
+export interface HostMessages {
+  panels: string
+  startReport: string
+  starting: string
+  noPlugins: string
+  status: Record<PluginStatus, string>
+  because: string
+  unnamedPlugin: string
+  componentError(component: string, message: string): string
+  problems(count: number): string
+  approvals(count: number): string
+  approvalsTitle: string
+  allow: string
+  deny: string
+  answerFailed: string
+  close: string
+  from(who: string): string
+  origins: Record<string, string>
+  otherOrigin: string
+}
+
+export const HOST_MESSAGES: Catalog<HostMessages> = {
+  'zh-CN': {
+    panels: '课堂与工具',
+    startReport: '启动报告',
+    starting: '正在启动…',
+    noPlugins: '没有注册插件。',
+    status: { started: '已启动', degraded: '部分可用', disabled: '已禁用', failed: '启动失败' },
+    because: '：',
+    unnamedPlugin: '其他插件',
+    componentError: (component, message) => `${component} 出错：${message}`,
+    problems: count => `${count} 个问题`,
+    approvals: count => `待确认 ${count}`,
+    approvalsTitle: '待确认的操作',
+    allow: '允许',
+    deny: '拒绝',
+    answerFailed: '无法发送答复。请重试。',
+    close: '关闭',
+    from: who => `来自${/^[A-Za-z0-9]/.test(who) ? ' ' : ''}${who}`,
+    origins: { 'presmium.mcp': '外部 AI 工具' },
+    otherOrigin: '其他程序',
+  },
+  'en': {
+    panels: 'Classroom and Tools',
+    startReport: 'Startup Report',
+    starting: 'Starting…',
+    noPlugins: 'No plugins registered.',
+    status: { started: 'Started', degraded: 'Partly available', disabled: 'Disabled', failed: 'Failed to start' },
+    because: ': ',
+    unnamedPlugin: 'Other plugin',
+    componentError: (component, message) => `${component} failed: ${message}`,
+    problems: count => `${count} ${count === 1 ? 'problem' : 'problems'}`,
+    approvals: count => `Pending Approvals (${count})`,
+    approvalsTitle: 'Pending Approvals',
+    allow: 'Allow',
+    deny: 'Deny',
+    answerFailed: 'Couldn’t send the answer. Please try again.',
+    close: 'Close',
+    from: who => `From ${who}`,
+    origins: { 'presmium.mcp': 'an external AI tool' },
+    otherOrigin: 'another program',
+  },
+}

package/src/operations.ts

@@ -0,0 +1,60 @@
+import type { Operation, Unsubscribe } from '@lincyaw/kernel/contracts'
+import { createStore } from './store.ts'
+import type { Operations, ReplayHandler } from './contracts.ts'
+
+export function createOperations(): Operations {
+  const listeners = new Set<(operation: Operation) => void>()
+  const handlers = new Map<string, ReplayHandler>()
+  const replaying = createStore(false)
+  let unsettled = 0
+  return {
+    report(operation) {
+      if (replaying.getSnapshot()) return
+      for (const listener of [...listeners]) {
+        try {
+          listener(operation)
+        } catch (error) {
+          console.error('[presmium] an operations subscriber failed', error)
+        }
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    onReplay(type, handler): Unsubscribe {
+      handlers.set(type, handler)
+      return () => {
+        if (handlers.get(type) === handler) handlers.delete(type)
+      }
+    },
+    replay(operation, seeking = false) {
+      const handler = handlers.get(operation.type)
+      if (!handler) return false
+      unsettled++
+      replaying.set(true)
+      try {
+        handler.apply(operation.data, seeking)
+      } catch (error) {
+        console.error(`[presmium] the replay of ${operation.type} failed`, error)
+      } finally {
+        setTimeout(() => {
+          if (--unsettled === 0) replaying.set(false)
+        }, 0)
+      }
+      return true
+    },
+    clear() {
+      for (const [type, handler] of handlers) {
+        try {
+          handler.clear?.()
+        } catch (error) {
+          console.error(`[presmium] clearing ${type} failed`, error)
+        }
+      }
+    },
+    replaying,
+  }
+}

package/src/panels.ts

@@ -0,0 +1,28 @@
+import { createElement as h, useEffect, useState } from 'react'
+import { createPortal } from 'react-dom'
+import type { ComponentType } from 'react'
+import { PRESENTER_PANELS } from '@lincyaw/kernel'
+import type { PresenterPanel } from '@lincyaw/kernel'
+import { TOOLBAR } from './contracts.ts'
+import type { ToolbarItem, ToolbarPlacement } from './contracts.ts'
+import { useService, useStartReport } from './host.ts'
+import { useMessages } from './locale.ts'
+import { componentErrors, componentErrorRevision } from './error-boundary.ts'
+import { useStore } from './store.ts'
+import { HOST_MESSAGES } from './messages.ts'
+import { ToolbarPlacementContext } from './design/components.ts'
+export function PmToolbar({ filter = (item: ToolbarItem) => !item.slot || item.slot === 'tools' || item.slot === 'settings', placement = 'bar', className }: { className?: string, filter?: (item: ToolbarItem) => boolean, placement?: ToolbarPlacement }) {
+  const service = useService(TOOLBAR); const [items, setItems] = useState<ToolbarItem[]>([])
+  useEffect(() => { const update = () => setItems(service?.list() ?? []); update(); return service?.subscribe(update) }, [service])
+  return h(ToolbarPlacementContext.Provider, { value: placement }, h('span', { className: `pm-toolbar${className ? ` ${className}` : ''}`, 'data-placement': placement }, items.filter(filter).map(item => h(item.component as ComponentType, { key: item.id, 'data-toolbar-item': item.id } as any))))
+}
+export function PmPresenterPanels({ to = 'body', docked = false }: { to?: string, docked?: boolean }) {
+  const t = useMessages(HOST_MESSAGES); const service = useService(PRESENTER_PANELS); const [panels, setPanels] = useState<PresenterPanel[]>([])
+  useEffect(() => { const update = () => setPanels(service?.list() ?? []); update(); return service?.subscribe(update) }, [service])
+  const [target, setTarget] = useState<Element | null>(null)
+  useEffect(() => { setTarget(document.querySelector(to)) }, [to])
+  const report = useStartReport(); useStore(componentErrorRevision)
+  const problems = (report?.plugins.filter(plugin => plugin.status === 'failed' || plugin.status === 'disabled').length ?? 0) + componentErrors().length
+  const content = service ? h('details', { className: `pm-presenter-panels${docked ? ' pm-presenter-panels--docked' : ''}` }, h('summary', {}, t.panels, problems ? h('span', { className: 'pm-presenter-panels__badge', title: t.problems(problems) }, problems) : null), panels.map(panel => h('section', { key: panel.id, 'data-panel': panel.id }, h('h3', {}, panel.title), h(panel.component as ComponentType)))) : null
+  return target ? createPortal(content, target) : null
+}

package/src/playback-control.ts

@@ -0,0 +1,67 @@
+import type { PlaybackControl, PlaybackLease } from './contracts.ts'
+
+interface Participant {
+  pause(): void
+  cancel(): void
+}
+
+/** Coordinates starts and cancellation without owning time, media or a second player. */
+export function createPlaybackControl(): PlaybackControl {
+  const participants = new Set<Participant>()
+  let gate: { authorize(signal: AbortSignal): Promise<void> } | undefined
+  const pause = () => {
+    for (const participant of [...participants]) {
+      participant.cancel()
+      participant.pause()
+    }
+  }
+  return {
+    pause,
+    setGate(authorize) {
+      pause()
+      const installed = { authorize }
+      gate = installed
+      return () => {
+        if (gate !== installed) return
+        gate = undefined
+        pause()
+      }
+    },
+    register(stop) {
+      let active: AbortController | undefined
+      let disposed = false
+      const cancel = () => { active?.abort(); active = undefined }
+      const participant = { pause: stop, cancel }
+      participants.add(participant)
+      const lease: PlaybackLease = {
+        async requestStart() {
+          cancel()
+          if (disposed) return false
+          for (const other of [...participants]) if (other !== participant) {
+            other.cancel()
+            other.pause()
+          }
+          const request = new AbortController()
+          active = request
+          const requestedGate = gate
+          try {
+            await requestedGate?.authorize(request.signal)
+            return !disposed && active === request && !request.signal.aborted && gate === requestedGate
+          } catch (error) {
+            if (request.signal.aborted || error instanceof Error && error.name === 'AbortError') return false
+            throw error
+          }
+        },
+        cancel,
+        dispose() {
+          if (disposed) return
+          disposed = true
+          cancel()
+          participants.delete(participant)
+          stop()
+        },
+      }
+      return lease
+    },
+  }
+}

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

@@ -0,0 +1,36 @@
+import type { PreviewEventSubscription } from '@lincyaw/kernel/contracts'
+import type { Member } from '@lincyaw/kernel/contracts'
+import { currentLocale } from './locale.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: 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 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 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,
+    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(`${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
+}

package/src/session.ts

@@ -0,0 +1,10 @@
+import { useEffect, useState } from 'react'
+import { SESSION } from '@lincyaw/kernel'
+import type { SessionSnapshot } from '@lincyaw/kernel'
+import { useService } from './host.ts'
+export function useSessionSnapshot() {
+  const session = useService(SESSION)
+  const [snapshot, setSnapshot] = useState<SessionSnapshot>()
+  useEffect(() => { setSnapshot(session?.snapshot()); return session?.subscribe(setSnapshot) }, [session])
+  return { session, snapshot }
+}

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