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

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

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

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@lincyaw/host",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.1",
+  "description": "Presmium's host interface for plugin components in every form: step state, services, interface text, and the design system (tokens, components, fonts)",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lincyaw/presmium.git",
+    "directory": "packages/host"
+  },
+  "homepage": "https://github.com/Lincyaw/presmium/tree/main/packages/host#readme",
+  "bugs": "https://github.com/Lincyaw/presmium/issues",
+  "keywords": [
+    "presmium",
+    "react",
+    "design-system"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./design.css": "./src/design/design.css"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@fontsource/ibm-plex-mono": "5.3.0",
+    "@fontsource/ibm-plex-sans": "5.3.0",
+    "@fontsource/source-serif-4": "5.3.1",
+    "@radix-ui/react-dialog": "^1.3.1",
+    "@radix-ui/react-dropdown-menu": "^2.2.1",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-radio-group": "^1.5.1",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "@lincyaw/design": "1.0.0-rc.1",
+    "@lincyaw/kernel": "1.0.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/react": "18.3.28",
+    "@types/react-dom": "18.3.7"
+  }
 }

package/src/actions.ts

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

package/src/approvals.ts

@@ -0,0 +1,12 @@
+import { createElement as h, useState } from 'react'
+import { PmButton, PmNotice, PmPopover } from './design/components.ts'
+import { useMessages } from './locale.ts'
+import { HOST_MESSAGES } from './messages.ts'
+import { approvals } from './control.ts'
+import { useStore } from './store.ts'
+export function PmApprovals({ placement = 'below' }: { placement?: 'below' | 'above' }) {
+  const t = useMessages(HOST_MESSAGES); const [open, setOpen] = useState(false); const [failed, setFailed] = useState<string>(); const pending = useStore(approvals.pending)
+  if (!pending.length) return null
+  const answer = (id: string, allow: boolean) => { setFailed(undefined); void approvals.answer(id, allow).catch(() => setFailed(t.answerFailed)) }
+  return h(PmPopover, { open, label: t.approvalsTitle, name: 'pm-approvals', placement: placement === 'above' ? 'above-end' : 'below-end', onOpenChange: setOpen, trigger: h(PmButton, { variant: 'accent', small: true }, t.approvals(pending.length)) }, pending.map(({ id, request }) => h('div', { key: id, 'data-approval': id }, h('p', {}, request.title), h('p', {}, t.from(t.origins[request.from] ?? t.otherOrigin)), ...(request.detail ?? '').split('\n').filter(Boolean).map((line, key) => h('p', { key }, line)), h(PmButton, { small: true, variant: 'primary', onClick: () => answer(id, true) }, t.allow), h(PmButton, { small: true, onClick: () => answer(id, false) }, t.deny))), failed ? h(PmNotice, { tone: 'danger' }, failed) : null)
+}

package/src/blocks.ts

@@ -0,0 +1,81 @@
+const UNSEEN = '[inert], .pm-hidden'
+
+export function blockKey(section: string, block: string): string {
+  return `${section}/${block}`
+}
+
+export function splitBlockKey(key: string): [section: string, block: string] | undefined {
+  const cut = key.lastIndexOf('/')
+  return cut > 0 && cut < key.length - 1 ? [key.slice(0, cut), key.slice(cut + 1)] : undefined
+}
+
+function seen(element: Element): boolean {
+  return !element.closest(UNSEEN) && element.getClientRects().length > 0
+}
+
+export function blockElement(key: string): HTMLElement | undefined {
+  const parts = splitBlockKey(key)
+  if (!parts || typeof document === 'undefined') return undefined
+  const found = document.querySelectorAll<HTMLElement>(`[data-section="${CSS.escape(parts[0])}"] .pm-block[data-block="${CSS.escape(parts[1])}"]`)
+  for (const element of found) if (seen(element)) return element
+  return undefined
+}
+
+export interface BlockPoint {
+  key: string
+  element: HTMLElement
+  x: number
+  y: number
+  line?: number
+}
+
+export function codeLines(block: Element): HTMLElement[] {
+  return [...block.querySelectorAll<HTMLElement>('.pm-code .line')]
+}
+
+/** The `<section>/<block>` key of a block's element (`.pm-block[data-block]`). */
+export function blockKeyOf(block: HTMLElement): string | undefined {
+  const section = block.closest<HTMLElement>('[data-section]')?.dataset.section
+  return section ? blockKey(section, block.dataset.block!) : undefined
+}
+
+export function blockAt(x: number, y: number, options: { skip?: Element, within?: string } = {}): BlockPoint | undefined {
+  if (typeof document === 'undefined') return undefined
+  const { skip, within } = options
+  const hit = document.elementsFromPoint(x, y).find(el => el !== skip && !skip?.contains(el))
+  const element = hit?.closest<HTMLElement>(`${within ? `${within} ` : ''}.pm-block[data-block]`)
+  const key = element && blockKeyOf(element)
+  if (!element || !key || !seen(element)) return undefined
+  const box = element.getBoundingClientRect()
+  if (!box.width || !box.height) return undefined
+  const index = codeLines(element).findIndex((line) => {
+    const r = line.getBoundingClientRect()
+    return y >= r.top && y < r.bottom
+  })
+  return {
+    key,
+    element,
+    x: (x - box.left) / box.width,
+    y: (y - box.top) / box.height,
+    ...index >= 0 ? { line: index + 1 } : {},
+  }
+}
+
+export function lineNumbers(lines: string): number[] {
+  return lines.split(/[\s,]+/).flatMap((part) => {
+    const [from, to = from] = part.split('-').map(Number)
+    return Number.isInteger(from) && Number.isInteger(to) && from! > 0 ? Array.from({ length: Math.max(0, to! - from! + 1) }, (_, k) => from! + k) : []
+  })
+}
+
+export function linesText(numbers: number[]): string {
+  const sorted = [...new Set(numbers)].sort((a, b) => a - b)
+  const runs: string[] = []
+  for (let i = 0; i < sorted.length;) {
+    let j = i
+    while (j + 1 < sorted.length && sorted[j + 1] === sorted[j]! + 1) j++
+    runs.push(i === j ? String(sorted[i]) : `${sorted[i]}-${sorted[j]}`)
+    i = j + 1
+  }
+  return runs.join(',')
+}

package/src/claim-first.ts

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

package/src/code-lines-box.ts

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

package/src/contracts.ts

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