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

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

package/src/step-clock.ts

@@ -0,0 +1,49 @@
+import { useEffect, useRef } from 'react'
+import type { Unsubscribe } from '@lincyaw/kernel/contracts'
+import type { Navigation, NavigationPosition, StepClock, StepClockDriver } from './contracts.ts'
+import { useHost, usePrefersReducedMotion } from './host.ts'
+import { createStore, observe, useStore } from './store.ts'
+interface StepChange { slide: number, step: number, at: number, forward: boolean }
+const driver = createStore<StepClockDriver | undefined>(undefined)
+const change = createStore<StepChange | undefined>(undefined)
+const now = createStore(0)
+const live = new Set<() => boolean>()
+let frame = 0
+const clockNow = () => typeof performance === 'undefined' ? 0 : performance.now()
+function tick() { frame = 0; now.set(clockNow()); if ([...live].some(running => running())) frame = requestAnimationFrame(tick) }
+function ensureTicking() { if (frame || typeof requestAnimationFrame === 'undefined') return; now.set(clockNow()); frame = requestAnimationFrame(tick) }
+function isForward(to: NavigationPosition, from: StepChange | undefined) { return !from || to.slide > from.slide || (to.slide === from.slide && to.step > from.step) }
+const nextFrame = () => new Promise<void>(done => typeof requestAnimationFrame === 'undefined' ? setTimeout(done, 0) : requestAnimationFrame(() => done()))
+function handOff(elapsed: number) { const at = change.getSnapshot(); if (at) change.set({ ...at, at: clockNow() - elapsed, forward: true }); ensureTicking() }
+export function createStepClock(navigation: Navigation): { clock: StepClock, stop: Unsubscribe } {
+  const pending = new Set<Promise<unknown>>()
+  let failure: { error: unknown } | undefined
+  let stopped = false
+  const rethrow = () => { const failed = failure; failure = undefined; if (failed) throw failed.error }
+  const stop = observe(navigation.position, position => { const before = change.getSnapshot(); if (before && before.slide === position.slide && before.step === position.step) return; change.set({ slide: position.slide, step: position.step, at: clockNow(), forward: isForward(position, before) }); ensureTicking() }, true)
+  let unfollow: Unsubscribe | undefined
+  const clock: StepClock = {
+    drive(next) {
+      unfollow?.(); driver.set(next)
+      unfollow = observe(next.elapsed, (now, before) => { if (now === undefined && before !== undefined) handOff(before) })
+      return () => { if (driver.getSnapshot() !== next) return; const last = next.elapsed.getSnapshot(); unfollow?.(); unfollow = undefined; driver.set(undefined); if (last !== undefined) handOff(last) }
+    },
+    wait(work) { if (!stopped) pending.add(work); void work.catch(error => { if (!stopped) failure ??= { error } }).finally(() => pending.delete(work)) },
+    async settled() { let waited = false; for (let round = 0; round < 100; round++) { if (stopped) return; if (!pending.size) { if (waited) { waited = false; await nextFrame() } if (!pending.size) return rethrow() } await Promise.allSettled([...pending]); waited = true } throw new Error('the page kept preparing its picture: settled() stopped waiting after 100 rounds') },
+  }
+  return { clock, stop() { if (stopped) return; stopped = true; stop(); unfollow?.(); driver.set(undefined); change.set(undefined); pending.clear(); failure = undefined } }
+}
+export interface StepTimeOptions { until?: number }
+const settle = (time: number, until: number | undefined) => until !== undefined && time >= until ? Infinity : Math.max(0, time)
+export function useStepTime(options: StepTimeOptions = {}): number {
+  const host = useHost(); const step = host.useStep(); const cursor = host.useCursor(); const reduced = usePrefersReducedMotion()
+  const at = useStore(change); const player = useStore(driver); const elapsed = useStore(player?.elapsed); const currentTime = useStore(now)
+  let time = Infinity
+  if (Number.isFinite(step) && at && at.step === step && at.slide === cursor.slide) {
+    if (player && elapsed !== undefined) time = reduced && !player.recording ? Infinity : settle(elapsed, options.until)
+    else if (!reduced && at.forward) time = settle(currentTime - at.at, options.until)
+  }
+  const renderedTime = useRef(time); renderedTime.current = time
+  useEffect(() => { const running = () => Number.isFinite(renderedTime.current) && driver.getSnapshot()?.elapsed.getSnapshot() === undefined; live.add(running); ensureTicking(); return () => { live.delete(running) } }, [step, cursor.slide, player, options.until, reduced])
+  return time
+}

package/src/step-scope.ts

@@ -0,0 +1,38 @@
+import { createContext, createElement, useContext, useMemo } from 'react'
+import type { ReactNode } from 'react'
+import type { StepRange } from '@lincyaw/kernel/contracts'
+import type { IRBlock } from '@lincyaw/kernel'
+type States = NonNullable<IRBlock['stepStates']>
+interface Scope extends StepRange { states?: States, current?: number, localPreview?: boolean }
+export const STEP_SCOPE = createContext<Scope>({ from: 0 })
+const stateAt = (states: States, step: number) => states[Math.max(0, Math.min(states.length - 1, Number.isFinite(step) ? Math.floor(step) : states.length - 1))]
+export function StepScope({ at, until, states, step, localPreview, children }: { at: number, until?: number, states?: States, step?: number, localPreview?: boolean, children?: ReactNode }) {
+  const parent = useContext(STEP_SCOPE)
+  const end = until === undefined ? parent.to : parent.to === undefined ? until : Math.min(until, parent.to)
+  const value = useMemo(() => ({ from: states ? at : Math.max(at, parent.from), to: end, states, current: step, localPreview: localPreview ?? parent.localPreview }), [at, states, step, localPreview, parent.localPreview, parent.from, end])
+  return createElement(STEP_SCOPE.Provider, { value }, children)
+}
+export interface StepScope {
+  readonly at: number
+  readonly state?: string
+  readonly parameters?: Record<string, unknown>
+  /** A standalone reading widget keeps its local controls while selecting finite teaching steps. */
+  readonly localPreview?: boolean
+  localStepAt(globalStep: number): number
+  /** First authored visible occurrence; -1 when this local state is not in the section. */
+  step(k: number): number
+  /** First authored visible snapshot of an implementation's local step. */
+  stateAt(k: number): Pick<NonNullable<IRBlock['stepStates']>[number], 'state' | 'parameters'> | undefined
+}
+export function useStepScope(): StepScope {
+  const { from, states, current, localPreview } = useContext(STEP_SCOPE)
+  const selected = states && stateAt(states, current ?? Infinity)
+  return { at: from, state: selected?.state, parameters: selected?.parameters, localPreview,
+    localStepAt: k => !Number.isFinite(k) ? k : states ? stateAt(states, k)?.localStep ?? 0 : k - from,
+    step: k => states ? states.findIndex(value => value.visible && value.localStep === k) : from + k,
+    stateAt: k => states?.find(value => value.visible && value.localStep === k) }
+}
+export function useBlockStepRange(): StepRange {
+  const { from, to, states } = useContext(STEP_SCOPE)
+  return { from: 0, to: states ? Math.max(0, ...states.map(state => state.localStep)) : to === undefined ? undefined : to - from }
+}

package/src/store.ts

@@ -0,0 +1,33 @@
+import { useSyncExternalStore } from 'react'
+import type { Dispatch, SetStateAction } from 'react'
+import type { Unsubscribe } from '@lincyaw/kernel/contracts'
+
+/** Framework-independent, synchronous state shared by playback, the viewer and React bindings. */
+export interface Store<T> {
+  getSnapshot(): T
+  subscribe(listener: () => void): Unsubscribe
+  set: Dispatch<SetStateAction<T>>
+}
+export function createStore<T>(initial: T): Store<T> {
+  let value = initial
+  const listeners = new Set<() => void>()
+  return {
+    getSnapshot: () => value,
+    subscribe(listener) { listeners.add(listener); return () => { listeners.delete(listener) } },
+    set(next) {
+      const changed = typeof next === 'function' ? (next as (before: T) => T)(value) : next
+      if (Object.is(changed, value)) return
+      value = changed
+      for (const listener of [...listeners]) listener()
+    },
+  }
+}
+const idleSubscribe = () => () => {}
+export function useStore<T>(store: Store<T> | undefined, fallback?: T): T {
+  return useSyncExternalStore(store?.subscribe ?? idleSubscribe, store?.getSnapshot ?? (() => fallback as T), store?.getSnapshot ?? (() => fallback as T))
+}
+export function observe<T>(store: Store<T>, listener: (value: T, before: T) => void, immediate = false): Unsubscribe {
+  let before = store.getSnapshot()
+  if (immediate) listener(before, before)
+  return store.subscribe(() => { const value = store.getSnapshot(); const previous = before; before = value; listener(value, previous) })
+}

package/src/styles.d.ts

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

package/src/windows.ts

@@ -0,0 +1,30 @@
+import { siteBase } from './site.ts'
+
+type Message = { join: true } | { value: unknown }
+
+export interface WindowChannel {
+  send(value: unknown): void
+  close(): void
+}
+
+function deckChannel(name: string): string {
+  return `${name} @ ${siteBase()}`
+}
+
+export function joinWindows(name: string, receive: (value: unknown) => void, known: () => unknown): WindowChannel | undefined {
+  if (typeof window === 'undefined' || typeof BroadcastChannel === 'undefined') return undefined
+  const channel = new BroadcastChannel(deckChannel(name))
+  channel.onmessage = ({ data }: MessageEvent<Message>) => {
+    if ('value' in data) {
+      receive(data.value)
+      return
+    }
+    const value = known()
+    if (value !== undefined) channel.postMessage({ value } satisfies Message)
+  }
+  channel.postMessage({ join: true } satisfies Message)
+  return {
+    send: value => channel.postMessage({ value } satisfies Message),
+    close: () => channel.close(),
+  }
+}