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

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

package/src/design/components.ts

@@ -0,0 +1,143 @@
+import { createContext, createElement as h, forwardRef, useContext, useEffect, useId, useRef } from 'react'
+import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode } from 'react'
+import * as Dialog from '@radix-ui/react-dialog'
+import * as Popover from '@radix-ui/react-popover'
+import * as Dropdown from '@radix-ui/react-dropdown-menu'
+import * as Tabs from '@radix-ui/react-tabs'
+import * as Tooltip from '@radix-ui/react-tooltip'
+import * as RadioGroup from '@radix-ui/react-radio-group'
+import { useLocale } from '../locale.ts'
+import { HOST_MESSAGES } from '../messages.ts'
+import { ICONS } from '@lincyaw/design'
+import type { IconName } from '@lincyaw/design'
+import type { ToolbarPlacement } from '../contracts.ts'
+export type ButtonVariant = 'default' | 'primary' | 'accent' | 'ghost' | 'danger'
+export type ControlDensity = 'compact' | 'regular' | 'touch'
+export type Tone = 'neutral' | 'accent' | 'ok' | 'warn' | 'danger' | 'outline'
+export type PopoverPlacement = 'below-end' | 'below-start' | 'above-end' | 'above-start' | 'above' | 'below'
+export interface Choice { value: string, label: string, icon?: IconName, disabled?: boolean }
+export interface MenuItem { id: string, label: string, icon?: IconName, danger?: boolean, disabled?: boolean, shortcut?: string, checked?: boolean, separator?: boolean }
+const cls = (...values: (string | false | undefined)[]) => values.filter(Boolean).join(' ')
+export function PmIcon({ name, size: _size, strokeWidth = 1.7, ...attrs }: { name: IconName, size?: number | string, strokeWidth?: number } & HTMLAttributes<SVGElement>) {
+  return h('svg', { ...attrs, className: cls('pm-ui-icon', attrs.className), viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth, strokeLinecap: 'round', strokeLinejoin: 'round', 'aria-hidden': true, focusable: false }, ICONS[name]?.map(([tag, attributes], key) => h(tag, { ...attributes, key })))
+}
+type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & { variant?: ButtonVariant, small?: boolean, icon?: IconName, density?: ControlDensity, loading?: boolean }
+export const PmButton = forwardRef<HTMLButtonElement, ButtonProps>(function PmButton({ variant = 'default', small, density = small ? 'compact' : 'regular', loading, icon, className, children, disabled, ...rest }, ref) {
+  return h('button', { ...rest, ref, type: rest.type ?? 'button', 'data-density': density, 'aria-busy': loading || undefined, disabled: disabled || loading || rest['aria-disabled'] === true || rest['aria-disabled'] === 'true', className: cls('pm-ui-button', variant !== 'default' && `pm-ui-button--${variant}`, className) },
+    h('span', { className: cls('pm-ui-button__content', !icon && loading !== undefined && 'pm-ui-button__content--loading-text') },
+      icon || loading !== undefined ? h('span', { className: 'pm-ui-button__icon', 'aria-hidden': true }, loading ? h(PmIcon, { name: 'loading', className: 'pm-ui-loading' }) : icon ? h(PmIcon, { name: icon }) : null) : null,
+      children))
+})
+export function PmTooltip({ label, shortcut, children }: { label: string, shortcut?: string, children: ReactNode }) {
+  return h(Tooltip.Provider, { delayDuration: 300, skipDelayDuration: 0, children:
+    h(Tooltip.Root, {}, h(Tooltip.Trigger, { asChild: true }, children), h(Tooltip.Portal, {},
+      h(Tooltip.Content, { className: 'pm-ui-tooltip pm-ui', side: 'top', sideOffset: 6, collisionPadding: 8 }, label, shortcut ? h('kbd', { className: 'pm-ui-shortcut' }, shortcut) : null))) })
+}
+export const PmIconButton = forwardRef<HTMLButtonElement, ButtonProps & { icon: IconName, label: string, hint?: string, shortcut?: string }>(function PmIconButton({ icon, label, hint, shortcut, small, density = small ? 'compact' : 'regular', loading, className, disabled, ...rest }, ref) {
+  const button = h('button', { ...rest, ref, type: 'button', 'data-density': density, 'aria-label': label, 'aria-busy': loading || undefined, disabled: disabled || loading || rest['aria-disabled'] === true || rest['aria-disabled'] === 'true', className: cls('pm-ui-icon-button', className) }, h(PmIcon, { name: loading ? 'loading' : icon, className: loading ? 'pm-ui-loading' : undefined }))
+  return h(PmTooltip, { label: hint ?? label, shortcut, children: button })
+})
+export function PmBadge({ tone = 'neutral', pill, children, className, ...rest }: HTMLAttributes<HTMLSpanElement> & { tone?: Tone, pill?: boolean }) { return h('span', { ...rest, className: cls('pm-ui-badge', tone !== 'neutral' && `pm-ui-badge--${tone}`, pill && 'pm-ui-badge--pill', className) }, children) }
+export function PmCard({ variant = 'default', className, children, ...rest }: HTMLAttributes<HTMLDivElement> & { variant?: string }) { return h('div', { ...rest, className: cls('pm-ui-card', variant !== 'default' && `pm-ui-card--${variant}`, className) }, children) }
+export function PmField({ label, inline, group, children }: { label: string, inline?: boolean, group?: boolean, children?: ReactNode }) { return h(group ? 'div' : 'label', { className: cls('pm-ui-field', inline && 'pm-ui-field--inline'), ...(group ? { role: 'group', 'aria-label': label } : {}) }, h('span', { className: 'pm-ui-field__label' }, label), children) }
+interface OverlayProps {
+  open: boolean
+  label: string
+  closeLabel?: string
+  name?: string
+  children?: ReactNode
+  trigger?: ReactNode
+  actions?: ReactNode
+  description?: string
+  footer?: ReactNode
+  busy?: boolean
+  onOpenChange?(open: boolean): void
+  onClose?(): void
+  onOpenAutoFocus?(event: Event): void
+  onCloseAutoFocus?(event: Event): void
+}
+function DialogSurface({ open, label, closeLabel, name, children, actions, trigger, description, footer, busy, onOpenChange, onClose, onOpenAutoFocus, onCloseAutoFocus, drawer = false }: OverlayProps & { drawer?: boolean }) {
+  const kind = drawer ? 'pm-ui-drawer' : 'pm-ui-dialog'
+  const locale = useLocale()
+  const id = useId()
+  const focusTarget = useRef<HTMLElement | null>(typeof document === 'undefined' ? null : document.activeElement as HTMLElement)
+  useEffect(() => {
+    if (open) return
+    const remember = (event: FocusEvent) => {
+      if (event.target instanceof HTMLElement && event.target !== document.body && event.target.closest('[data-pm-dialog]')?.getAttribute('data-pm-dialog') !== id) focusTarget.current = event.target
+    }
+    document.addEventListener('focusin', remember, true)
+    return () => document.removeEventListener('focusin', remember, true)
+  }, [id, open])
+  return h(Dialog.Root, { open, modal: true, onOpenChange: next => { if (!next && busy) return; onOpenChange?.(next); if (!next) onClose?.() } },
+    trigger ? h(Dialog.Trigger, { asChild: true }, trigger) : null,
+    h(Dialog.Portal, {}, h(Dialog.Overlay, { className: 'pm-ui-dialog-overlay' }),
+      h(Dialog.Content, {
+        className: cls(kind, 'pm-ui', name && `${name}__panel`), ...{ 'data-density': 'regular', 'data-pm-dialog': id }, 'aria-busy': busy || undefined,
+        ...description ? {} : { 'aria-describedby': undefined },
+        onInteractOutside: event => event.preventDefault(),
+        onEscapeKeyDown: event => { event.stopPropagation(); if (busy) event.preventDefault() },
+        onOpenAutoFocus: event => {
+          onOpenAutoFocus?.(event)
+          if (event.defaultPrevented || !(event.target instanceof HTMLElement)) return
+          const panel = event.target
+          if (panel.contains(document.activeElement)) { event.preventDefault(); return }
+          const target = [...panel.querySelectorAll<HTMLElement>(`.${kind}__body :is(button, input, textarea, select, a[href], [tabindex]), .pm-ui-dialog__footer :is(button, input, textarea, select, a[href], [tabindex])`)].find(element => element.tabIndex >= 0 && !element.closest('[inert], [hidden]') && !element.matches(':disabled, [aria-disabled="true"]') && element.getClientRects().length && getComputedStyle(element).visibility === 'visible')
+          if (target) { event.preventDefault(); target.focus() }
+        },
+        onCloseAutoFocus: event => {
+          onCloseAutoFocus?.(event)
+          if (event.defaultPrevented) return
+          event.preventDefault()
+          const available = (element: HTMLElement | null): element is HTMLElement => Boolean(element?.isConnected && element !== document.body && !element.closest(`[data-pm-dialog="${id}"], [inert], [hidden]`) && !element.matches(':disabled, [aria-disabled="true"]') && element.getClientRects().length && getComputedStyle(element).visibility === 'visible')
+          const target = available(focusTarget.current) ? focusTarget.current : [...document.querySelectorAll<HTMLElement>('[role="toolbar"] button, main button')].find(available)
+          target?.focus()
+        },
+      }, h('div', { className: `${kind}__header` },
+        h(Dialog.Title, { className: `${kind}__title` }, label), actions,
+        h(Dialog.Close, { asChild: true }, h(PmIconButton, { icon: 'close', label: closeLabel ?? HOST_MESSAGES[locale].close, small: true, disabled: busy }))),
+      description ? h(Dialog.Description, { className: 'pm-ui-dialog__description' }, description) : null,
+      h('div', { className: `${kind}__body` }, children),
+      footer ? h('div', { className: 'pm-ui-dialog__footer' }, footer) : null)))
+}
+export function PmDialog(props: OverlayProps) { return h(DialogSurface, props) }
+export function PmDrawer(props: OverlayProps) { return h(DialogSurface, { ...props, drawer: true }) }
+const placement = (value: PopoverPlacement) => ({ side: value.startsWith('above') ? 'top' as const : 'bottom' as const, align: value.endsWith('start') ? 'start' as const : 'end' as const })
+export function PmPopover({ open, label, name, children, trigger, placement: place = 'below-end', onOpenChange }: OverlayProps & { placement?: PopoverPlacement }) { return h(Popover.Root, { open, onOpenChange }, trigger ? h(Popover.Trigger, { asChild: true }, trigger) : null, h(Popover.Portal, {}, h(Popover.Content, { ...placement(place), className: cls('pm-ui-popover pm-ui-floating pm-ui', name), 'aria-label': label, onEscapeKeyDown: event => event.stopPropagation() }, children))) }
+export function PmMenu({ label, items, icon = 'more', placement: place = 'below-end', onSelect }: { label: string, items: MenuItem[], icon?: IconName, placement?: PopoverPlacement, onSelect?(id: string): void }) {
+  return h(Dropdown.Root, {},
+    h(Dropdown.Trigger, { asChild: true }, h(PmIconButton, { icon, label, small: true })),
+    h(Dropdown.Portal, {}, h(Dropdown.Content, { ...placement(place), className: 'pm-ui-menu pm-ui-floating pm-ui', ...{ 'data-density': 'compact' }, 'aria-label': label, onEscapeKeyDown: event => event.stopPropagation() },
+      items.map(item => h(Dropdown.Group, { key: item.id }, item.separator ? h(Dropdown.Separator, { className: 'pm-ui-menu__separator' }) : null,
+        item.checked === undefined ? h(Dropdown.Item, { disabled: item.disabled, textValue: item.label, className: cls('pm-ui-menu__item', item.danger && 'pm-ui-menu__item--danger'), onSelect: () => onSelect?.(item.id) },
+          item.icon ? h(PmIcon, { name: item.icon }) : null, item.label, item.shortcut ? h('kbd', { className: 'pm-ui-shortcut' }, item.shortcut) : null)
+        : h(Dropdown.CheckboxItem, { checked: item.checked, disabled: item.disabled, textValue: item.label, className: cls('pm-ui-menu__item', item.danger && 'pm-ui-menu__item--danger'), onSelect: () => onSelect?.(item.id) },
+          h(Dropdown.ItemIndicator, {}, h(PmIcon, { name: 'check' })), item.label))))))
+}
+export function PmTabs({ value, modelValue, tabs, label, children, onValueChange, iconOnly, density = 'compact' }: { value?: string, modelValue?: string, tabs: Choice[], label: string, children?: ReactNode, iconOnly?: boolean, density?: ControlDensity, onValueChange?(value: string): void }) {
+  return h(Tabs.Root, { value: value ?? modelValue, onValueChange, activationMode: 'manual', className: 'pm-ui-tabs-root', ...{ 'data-density': density } },
+    h(Tabs.List, { className: 'pm-ui-tabs', 'aria-label': label }, tabs.map(tab => {
+      const trigger = h(Tabs.Trigger, { key: tab.value, value: tab.value, className: 'pm-ui-tab', disabled: tab.disabled, 'aria-label': tab.label, ...{ 'data-icon-only': iconOnly || undefined } }, tab.icon ? h(PmIcon, { name: tab.icon }) : null, iconOnly ? null : tab.label)
+      return iconOnly ? h(PmTooltip, { key: tab.value, label: tab.label, children: trigger }) : trigger
+    })), children)
+}
+export function PmTabPanel({ value, children, forceMount, hidden }: { value: string, children?: ReactNode, forceMount?: true, hidden?: boolean }) { return h(Tabs.Content, { value, forceMount, hidden, className: 'pm-ui-tab-panel' }, children) }
+export function PmSegmented({ value, modelValue, choices, items, label, onValueChange, density = 'compact', disabled }: { value?: string, modelValue?: string, choices?: Choice[], items?: Choice[], label: string, density?: ControlDensity, disabled?: boolean, onValueChange?(value: string): void }) {
+  return h(RadioGroup.Root, { className: 'pm-ui-segmented', 'aria-label': label, value: value ?? modelValue, onValueChange, orientation: 'horizontal', ...{ 'data-density': density }, disabled },
+    (choices ?? items ?? []).map(item => h(RadioGroup.Item, { key: item.value, value: item.value, className: 'pm-ui-segmented__option', disabled: item.disabled }, item.icon ? h(PmIcon, { name: item.icon }) : null, item.label)))
+}
+export function PmNotice({ tone = 'neutral', children, className, ...rest }: HTMLAttributes<HTMLDivElement> & { tone?: Tone }) { return h('div', { ...rest, className: cls('pm-ui-notice', tone !== 'neutral' && `pm-ui-notice--${tone}`, className), role: tone === 'danger' ? 'alert' : 'status' }, children) }
+export function PmEmpty({ title, icon, action, children }: { title?: string, icon?: IconName, action?: ReactNode, children?: ReactNode }) { return h('div', { className: 'pm-ui-empty' }, icon ? h(PmIcon, { name: icon }) : null, title ? h('p', { className: 'pm-ui-empty__title' }, title) : null, children, action) }
+/** Loading in the shape of the content: `document` headings and paragraphs, `list` rows, `preview` a slide-shaped area. */
+export function PmSkeleton({ label, shape = 'document' }: { label: string, shape?: 'document' | 'list' | 'preview' }) {
+  const bar = (kind?: string, key?: number) => h('span', { key, className: 'pm-ui-skeleton__bar', 'data-kind': kind })
+  const paragraph = (lines: number, key: number) => h('span', { key, className: 'pm-ui-skeleton__group' }, Array.from({ length: lines }, (_, index) => bar(undefined, index)))
+  const bars = shape === 'list' ? Array.from({ length: 5 }, (_, index) => bar('row', index))
+    : shape === 'preview' ? [bar('media', 0), paragraph(2, 1)]
+      : [bar('heading', 0), paragraph(4, 1), paragraph(3, 2), bar('heading', 3), paragraph(4, 4)]
+  return h('div', { className: 'pm-ui-skeleton', 'data-shape': shape, role: 'status', 'aria-busy': 'true' }, h('span', { className: 'pm-ui-sr-only' }, label), h('span', { className: 'pm-ui-skeleton', 'aria-hidden': 'true' }, bars))
+}
+export const ToolbarPlacementContext = createContext<ToolbarPlacement>('bar')
+export const provideToolbarPlacement = ToolbarPlacementContext.Provider
+export function useToolbarPlacement() { return useContext(ToolbarPlacementContext) }
+export function PmToolbarEntry({ title, label = title ?? '', name, icon = 'more', open = false, onOpenChange, children }: { title?: string, name?: string, label?: string, closeLabel?: string, icon?: IconName, open?: boolean, onOpenChange?(open: boolean): void, children?: ReactNode }) { const where = useToolbarPlacement(); return h(PmPopover, { open, onOpenChange, name, label, placement: where === 'status' ? 'above-start' : 'below-end', trigger: h(PmIconButton, { icon, label, small: true, className: name && `${name}__toggle`, 'aria-expanded': open }) }, children) }

package/src/design/design.css

@@ -0,0 +1,9 @@
+@import '@lincyaw/design/design.css';
+
+.pm-toolbar { display: inline-flex; align-items: center; gap: var(--pm-space-2); }
+.pm-toolbar[data-placement='status'] { gap: var(--pm-space-4); }
+.pm-presenter-panels { position: fixed; right: var(--pm-space-2); bottom: var(--pm-overlay-bar, var(--pm-space-12)); z-index: var(--pm-z-overlay-view); max-width: var(--pm-aside-width); max-height: 50vh; overflow: auto; padding: var(--pm-space-1) var(--pm-space-3); border: var(--pm-size-hairline) solid var(--pm-color-line); border-radius: var(--pm-radius-small); background: var(--pm-color-surface); color: var(--pm-color-ink); font-size: var(--pm-text-sm); box-shadow: var(--pm-shadow-float); }
+.pm-presenter-panels--docked { position: static; max-width: none; max-height: none; margin-top: var(--pm-space-4); box-shadow: none; }
+.pm-presenter-panels summary { cursor: pointer; font-weight: 600; }
+.pm-presenter-panels__badge { display: inline-block; padding: 0 var(--pm-space-1); border-radius: var(--pm-radius-pill); background: var(--pm-color-danger); color: var(--pm-color-surface); text-align: center; }
+.pm-presenter-panels h3 { margin: var(--pm-space-2) 0 var(--pm-space-1); font-size: var(--pm-text-md); }

package/src/design/layout.ts

@@ -0,0 +1,28 @@
+import { Children, createElement as h, useState } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+import { PmTabs, PmTabPanel } from './components.ts'
+
+export interface ContentLayoutProps { title?: string, children?: ReactNode }
+export interface ColumnsLayoutProps extends ContentLayoutProps { columnWidths?: number[] }
+const heading = (title?: string) => title ? h('h3', { className: 'pm-layout__title' }, title) : null
+
+/** Authored column proportions are content geometry; narrow surfaces stack the same children. */
+export function PmColumns({ title, columnWidths, children }: ColumnsLayoutProps) {
+  const items = Children.toArray(children)
+  const columns = items.map((_, index) => `minmax(0, ${Number.isFinite(columnWidths?.[index]) && columnWidths![index]! > 0 ? columnWidths![index] : 1}fr)`).join(' ')
+  const style: CSSProperties & { '--pm-layout-columns': string } = { '--pm-layout-columns': columns || 'minmax(0, 1fr)' }
+  return h('div', { className: 'pm-layout-columns', style }, heading(title), items.map((item, index) => h('div', { className: 'pm-layout__item', key: index }, item)))
+}
+export function PmStack({ title, children }: ContentLayoutProps) {
+  return h('div', { className: 'pm-layout-stack' }, heading(title), children)
+}
+export interface TabLayoutEntry { id: string, title: string, content: ReactNode, visible?: boolean }
+export function PmTabGroup({ title, label, tabs, staticView = false }: { title?: string, label: string, tabs: TabLayoutEntry[], staticView?: boolean }) {
+  const [chosen, setChosen] = useState<string>()
+  if (staticView) return h('div', { className: 'pm-layout-stack', 'data-layout-static': 'tabs' }, heading(title), tabs.map(tab => h('section', { key: tab.id, className: 'pm-layout-stack' }, h('h4', { className: 'pm-layout__title' }, tab.title), tab.content)))
+  const visible = tabs.filter(tab => tab.visible !== false)
+  const active = visible.find(tab => tab.id === chosen)?.id ?? visible[0]?.id ?? ''
+  return h('div', { className: 'pm-layout-stack' }, heading(title), h(PmTabs, {
+    label: title || label, value: active, tabs: visible.map(tab => ({ value: tab.id, label: tab.title })), onValueChange: setChosen,
+  }, tabs.map(tab => h(PmTabPanel, { key: tab.id, value: tab.id, forceMount: true, hidden: tab.id !== active || tab.visible === false }, tab.content))))
+}

package/src/env.d.ts

@@ -0,0 +1,7 @@
+interface ImportMetaEnv {
+  BASE_URL: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

package/src/error-boundary.ts

@@ -0,0 +1,18 @@
+import { Component, createElement as h } from 'react'
+import type { ReactNode, ErrorInfo } from 'react'
+import { errorMessage } from '@lincyaw/kernel'
+import { createStore } from './store.ts'
+import { HOST_MESSAGES } from './messages.ts'
+import { currentLocale } from './locale.ts'
+export interface ComponentError { component: string, message: string }
+export const componentErrorRevision = createStore(0)
+const errors = new Map<object, ComponentError>()
+export function componentErrors(): readonly ComponentError[] { return [...errors.values()] }
+export class PmBoundary extends Component<{ name?: string, resetKey?: unknown, children?: ReactNode }, { error?: ComponentError }> {
+  state: { error?: ComponentError } = {}
+  static getDerivedStateFromError(error: unknown) { return { error: { component: 'component', message: errorMessage(error) } } }
+  componentDidCatch(error: unknown, _info: ErrorInfo) { const problem = { component: this.props.name ?? 'component', message: errorMessage(error) }; errors.set(this, problem); componentErrorRevision.set(n => n + 1); this.setState({ error: problem }); console.error(`[presmium] ${problem.component} failed`, error) }
+  componentDidUpdate(before: Readonly<{ name?: string, resetKey?: unknown }>) { if (before.resetKey !== this.props.resetKey && this.state.error) { errors.delete(this); componentErrorRevision.set(n => n + 1); this.setState({ error: undefined }) } }
+  componentWillUnmount() { if (errors.delete(this)) componentErrorRevision.set(n => n + 1) }
+  render() { const error = this.state.error; return error ? h('div', { className: 'pm-boundary-error', role: 'alert', 'data-pm-error': error.component }, HOST_MESSAGES[currentLocale()].componentError(error.component, error.message)) : this.props.children }
+}

package/src/host-key.ts

@@ -0,0 +1,4 @@
+import { createContext } from 'react'
+import type { HostAdapter } from './contracts.ts'
+export const HOST = createContext<HostAdapter | undefined>(undefined)
+export const installed: { adapter?: HostAdapter } = {}

package/src/host.ts

@@ -0,0 +1,47 @@
+import { createElement, useContext, useEffect, useState } from 'react'
+import type { ReactNode } from 'react'
+import { stepStateAt } from '@lincyaw/kernel'
+import type { ServiceToken, StepRange, StepState } from '@lincyaw/kernel/contracts'
+import { HOST, installed } from './host-key.ts'
+import type { HostAdapter, SharedStateScope } from './contracts.ts'
+import { useStepScope } from './step-scope.ts'
+import { runtimeRevision } from './runtime.ts'
+import { createStore, useStore } from './store.ts'
+import type { Store } from './store.ts'
+import { PmBoundary } from './error-boundary.ts'
+
+export function installHost(adapter: HostAdapter): void { installed.adapter = adapter }
+export function HostProvider({ adapter, children }: { adapter: HostAdapter, children?: ReactNode }) {
+  return createElement(HOST.Provider, { value: adapter }, children)
+}
+export function useHost(): HostAdapter {
+  const host = useContext(HOST) ?? installed.adapter
+  if (!host) throw new Error('[presmium] no host installed')
+  return host
+}
+export function useDoc() { const host = useHost(); if (!host.useDoc) throw new Error("[presmium] this host has no document"); return host.useDoc() }
+export function useStep(): number { return useHost().useStep() }
+export function useStepState(range: StepRange): StepState { const step = useStep(); const scope = useStepScope(); return stepStateAt(range, scope.localStepAt(step)) }
+export function useCursor() { return useHost().useCursor() }
+export function useViewRole() { return useHost().useViewRole() }
+export function usePresentationMode() { const host = useHost(); host.useViewRole(); return host.mode }
+export function useService<T>(token: ServiceToken<T>): T | undefined { useStore(runtimeRevision); return useHost().getService(token) }
+export function useStartReport() { useStore(runtimeRevision); return useHost().startReport() }
+export function useStaticRender() { return useHost().useStaticRender() }
+export function useSectionConfig(pluginId: string) { return useHost().useSectionConfig(pluginId) }
+export interface SharedStateOptions { scope?: SharedStateScope }
+export function useSharedState<T>(key: string, initial: T, options: SharedStateOptions = {}) { return useHost().useSharedState(key, initial, options.scope ?? 'local') }
+export function usePrefersReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(() => typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches)
+  useEffect(() => { const query = matchMedia('(prefers-reduced-motion: reduce)'); const update = () => setReduced(query.matches); update(); query.addEventListener('change', update); return () => query.removeEventListener('change', update) }, [])
+  return reduced
+}
+
+const detachedShared = new Map<string, Store<unknown>>()
+export function getSharedStateStore<T>(key: string, initial: T, options: SharedStateOptions = {}): Store<T> {
+  const scope = options.scope ?? 'local'
+  if (installed.adapter?.sharedStateStore) return installed.adapter.sharedStateStore(key, initial, scope)
+  const id = `${scope}:${key}`
+  let store = detachedShared.get(id); if (!store) { store = createStore<unknown>(initial); detachedShared.set(id, store) }
+  return store as Store<T>
+}

package/src/index.ts

@@ -0,0 +1,114 @@
+/// <reference path="./styles.d.ts" />
+import './design/design.css'
+
+export { useActions } from './actions.ts'
+export type { ActionOptions, ComponentAction } from './actions.ts'
+export { blockAt, blockElement, blockKey, codeLines, lineNumbers, linesText, splitBlockKey } from './blocks.ts'
+export type { BlockPoint } from './blocks.ts'
+export { componentErrors, componentErrorRevision, PmBoundary } from './error-boundary.ts'
+export type { ComponentError } from './error-boundary.ts'
+export {
+  PmBadge,
+  PmButton,
+  PmCard,
+  PmDialog,
+  PmDrawer,
+  PmEmpty,
+  PmSkeleton,
+  PmField,
+  PmIcon,
+  PmIconButton,
+  PmMenu,
+  PmNotice,
+  PmPopover,
+  PmSegmented,
+  PmTabs,
+  PmTabPanel,
+  PmTooltip,
+  PmToolbarEntry,
+  provideToolbarPlacement,
+  useToolbarPlacement,
+} from './design/components.ts'
+export type { ButtonVariant, Choice, ControlDensity, MenuItem, PopoverPlacement, Tone } from './design/components.ts'
+export { PmColumns, PmStack, PmTabGroup } from './design/layout.ts'
+export { PmCaption, PmCaptionProvider } from './design/caption.ts'
+export type { CaptionProps } from './design/caption.ts'
+export type { ContentLayoutProps, ColumnsLayoutProps, TabLayoutEntry } from './design/layout.ts'
+export { iconMarkup, ICONS } from '@lincyaw/design'
+export type { IconName } from '@lincyaw/design'
+export { useAppearance } from './design/appearance.ts'
+export type { Appearance } from './design/appearance.ts'
+export {
+  installHost,
+  HostProvider,
+  useStep,
+  useDoc,
+  useCursor,
+  useHost,
+  usePrefersReducedMotion,
+  usePresentationMode,
+  useSectionConfig,
+  useService,
+  useSharedState,
+  getSharedStateStore,
+  useStartReport,
+  useStaticRender,
+  useStepState,
+  useViewRole,
+} from './host.ts'
+export type { SharedStateOptions } from './host.ts'
+export { pluginsOf, presmiumReport, presmiumService, registerPresmiumPlugin, reportPluginFailure, setHostActive, startHost, stopHost } from './runtime.ts'
+export type { HostStart } from './runtime.ts'
+export { currentLocale, useLocale, useMessages } from './locale.ts'
+export type { Catalog } from './locale.ts'
+export { PmApprovals } from './approvals.ts'
+export { claimFirst } from './claim-first.ts'
+export { createServerClient, pluginRoutePath, provideServer, useServer, serverClient } from './server.ts'
+export { PmPresenterPanels } from './panels.ts'
+export { useStepTime } from './step-clock.ts'
+export type { StepTimeOptions } from './step-clock.ts'
+export { StepScope, useBlockStepRange, useStepScope } from './step-scope.ts'
+export { useSessionSnapshot } from './session.ts'
+export type { StepScope as StepScopeValue } from './step-scope.ts'
+export { createSharedStates } from './shared-state.ts'
+export type { SharedStates } from './shared-state.ts'
+export { PmToolbar } from './panels.ts'
+export { NAVIGATION, OPERATIONS, PLAYBACK_CONTROL, PRODUCTION_PLAYBACK, STATUS, STEP_CLOCK, SYNC_TRANSPORTS, TIMED_CAPTIONS, TOOLBAR } from './contracts.ts'
+export type { TimedCaptions } from './contracts.ts'
+export { joinWindows } from './windows.ts'
+export { setSiteBase, siteBase } from './site.ts'
+export type { WindowChannel } from './windows.ts'
+export type {
+  HostAdapter,
+  Navigation,
+  NavigationPosition,
+  Operations,
+  PlaybackControl,
+  PlaybackLease,
+  ProductionPlayback,
+  ReplayHandler,
+  ServerClient,
+  SharedStateScope,
+  StatusProvider,
+  StatusRegistry,
+  StepClock,
+  StepClockDriver,
+  SyncPublish,
+  SyncTransport,
+  SyncTransports,
+  Toolbar,
+  ToolbarItem,
+  ToolbarPlacement,
+  ToolbarSlot,
+  ViewRole,
+} from './contracts.ts'
+export { localeOf } from '@lincyaw/kernel'
+export type { Locale } from '@lincyaw/kernel/contracts'
+export { codeLinesBox } from './code-lines-box.ts'
+export { createResidentWorker } from './resident-worker.ts'
+export type { ResidentWorker, ResidentWorkerFailure, ResidentWorkerOptions, ResidentWorkerOutcome } from './resident-worker.ts'
+
+export { createStore, useStore, observe } from './store.ts'
+export type { Store } from './store.ts'
+
+export { runtimeRevision } from "./runtime.ts"

package/src/locale.ts

@@ -0,0 +1,20 @@
+import { useEffect } from 'react'
+import { localeOf } from '@lincyaw/kernel'
+import type { Locale } from '@lincyaw/kernel/contracts'
+import { installed } from './host-key.ts'
+import { createStore, useStore } from './store.ts'
+export type Catalog<T> = Record<Locale, T>
+const language = createStore<string | undefined>(undefined)
+let observer: MutationObserver | undefined
+function observeLanguage() {
+  if (typeof document === 'undefined' || observer) return
+  language.set(document.documentElement.lang)
+  observer = new MutationObserver(() => language.set(document.documentElement.lang))
+  observer.observe(document.documentElement, { attributes: true, attributeFilter: ['lang'] })
+}
+export function currentLocale(): Locale {
+  const lang = typeof document === 'undefined' ? undefined : document.documentElement.lang
+  return localeOf(lang || installed.adapter?.lang) ?? localeOf(typeof navigator === 'undefined' ? undefined : navigator.language) ?? 'en'
+}
+export function useLocale(): Locale { useStore(language); useEffect(observeLanguage, []); return currentLocale() }
+export function useMessages<T>(catalog: Catalog<T>): T { return catalog[useLocale()] }