@lincyaw/server 0.0.0-stage → 1.0.0-rc.0

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,18 @@
-# Temporary Holding Version
+# @lincyaw/server
 
-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.
+The server of `presmium dev` and `presmium serve`: plugin routes and proxies under `/__presmium/`, approvals, the control channel and the MCP endpoint. It listens on this machine only unless `presmium serve --host` is given.
+
+Part of [Presmium](https://github.com/Lincyaw/presmium), which turns lectures written in MyST Markdown into web pages, slides, Jupyter notebooks and narrated lectures.
+
+## Install
+
+It comes with `@lincyaw/cli`; you do not install it yourself. Its programming interface serves Presmium's own packages and is internal; plugins add routes through `PresmiumNodePlugin.server`.
+
+## Documentation
+
+- [Plugin guide](https://github.com/Lincyaw/presmium/blob/main/site/plugins/lecture.en.md): server routes
+- [Security and the trust model](https://github.com/Lincyaw/presmium/blob/main/SECURITY.md)
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@lincyaw/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.0",
+  "description": "The server of presmium dev and presmium serve: plugin routes and proxies, approvals, the control channel and MCP",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lincyaw/presmium.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/Lincyaw/presmium/tree/main/packages/server#readme",
+  "bugs": "https://github.com/Lincyaw/presmium/issues",
+  "keywords": [
+    "presmium",
+    "server"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@hono/node-server": "2.1.3",
+    "hono": "4.13.13",
+    "http-proxy-3": "2.0.1",
+    "@lincyaw/compiler": "1.0.0-rc.0",
+    "@lincyaw/kernel": "1.0.0-rc.0",
+    "@lincyaw/mcp": "1.0.0-rc.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.3.1"
+  }
 }

package/src/auth.ts

@@ -0,0 +1,40 @@
+import type { IncomingMessage } from 'node:http'
+import { hostname as machineName, networkInterfaces } from 'node:os'
+import type { Member } from '@lincyaw/kernel'
+import { header, hostname, isLoopback, originHost } from './http.ts'
+
+export const LOCAL_AUTHOR: Member = { id: 'local', name: 'local author', roles: ['owner'] }
+
+export interface Refusal {
+  status: number
+  message: string
+}
+
+export type MachineHosts = (host: string) => boolean
+
+export function anyAddress(host: string): boolean {
+  return ['0.0.0.0', '[::]'].includes(hostname(host))
+}
+
+export function networkAddresses(): string[] {
+  return Object.values(networkInterfaces()).flatMap(entries => entries ?? []).filter(entry => entry.family === 'IPv4' && !entry.internal).map(entry => entry.address)
+}
+
+export function machineHosts(listen: string): MachineHosts {
+  const own = hostname(listen)
+  if (isLoopback(own)) return isLoopback
+  const addresses = anyAddress(own)
+    ? Object.values(networkInterfaces()).flatMap(entries => entries ?? []).map(entry => hostname(entry.address.replace(/%.*$/, '')))
+    : [own]
+  const name = machineName().toLowerCase()
+  const names = new Set([...addresses, name, `${name}.local`])
+  return host => isLoopback(host) || names.has(host)
+}
+
+export function authenticate(req: IncomingMessage, local: MachineHosts = isLoopback): Member | Refusal {
+  const host = header(req.headers, 'host')
+  const origin = originHost(header(req.headers, 'origin'))
+  if (!local(hostname(host))) return { status: 403, message: `Host ${host ?? '(none)'} is not this machine` }
+  if (origin !== undefined && !local(origin)) return { status: 403, message: `Origin ${header(req.headers, 'origin')} is not this machine` }
+  return LOCAL_AUTHOR
+}

package/src/control.ts

@@ -0,0 +1,205 @@
+import { randomUUID } from 'node:crypto'
+import type { ApprovalKind, ApprovalRequest, Approvals, Member, MemberRole } from '@lincyaw/kernel'
+
+export type ApprovalPolicy = 'off' | 'ask' | 'allow'
+
+export const APPROVAL_TIMEOUT_MS = 50_000
+
+export interface WindowPosition {
+  slide: number
+  step: number
+  view?: string
+  section?: string
+  trail?: string[]
+}
+
+export interface WindowReport {
+  position?: WindowPosition
+  role?: string
+  status?: Record<string, unknown>
+  at: number
+}
+
+interface Window {
+  id: string
+  member: Member
+  document: string
+  report?: WindowReport
+  send(event: string, data: unknown): void
+  close(): void
+}
+
+interface Pending {
+  id: string
+  request: ApprovalRequest
+  document: string
+  settle(allow: boolean): void
+}
+
+function presents(window: { report?: WindowReport }): boolean {
+  return window.report?.role === 'presenter' || window.report?.role === 'audience'
+}
+
+export function hasRole(member: Member, role: MemberRole): boolean {
+  const rank: Record<MemberRole, number> = { reader: 0, editor: 1, owner: 2 }
+  return member.roles.some(own => rank[own] >= rank[role])
+}
+
+export interface ControlOptions {
+  policy: Partial<Record<ApprovalKind, ApprovalPolicy>>
+  timeoutMs?: number
+}
+
+export class Control {
+  readonly #windows = new Map<string, Window>()
+  readonly #pending = new Map<string, Pending>()
+  readonly #watchers = new Set<() => void>()
+  readonly #options: ControlOptions
+
+  constructor(options: ControlOptions) {
+    this.#options = options
+  }
+
+  readonly approvals: Approvals = {
+    request: (request, signal) => this.#request(request, signal),
+  }
+
+  open(id: string, member: Member, document: string): AsyncIterable<{ event: string, data: unknown }> & { close(): void } {
+    this.#windows.get(id)?.close()
+    const queue: { event: string, data: unknown }[] = []
+    let wake: (() => void) | undefined
+    let closed = false
+    const window: Window = {
+      id,
+      member,
+      document,
+      send(event, data) {
+        if (closed) return
+        queue.push({ event, data })
+        wake?.()
+      },
+      close: () => {
+        closed = true
+        if (this.#windows.get(id) === window) this.#windows.delete(id)
+        wake?.()
+      },
+    }
+    this.#windows.set(id, window)
+    window.send('ready', { window: id })
+    for (const pending of this.#pending.values()) {
+      if (this.#eligible(member, pending.request)) window.send('approval', { id: pending.id, request: pending.request })
+    }
+    const stream = {
+      close: window.close,
+      async* [Symbol.asyncIterator]() {
+        try {
+          while (!closed) {
+            while (queue.length > 0) yield queue.shift()!
+            if (closed) break
+            await new Promise<void>(resolve => wake = resolve)
+            wake = undefined
+          }
+        } finally {
+          window.close()
+        }
+      },
+    }
+    return stream
+  }
+
+  report(id: string, member: Member, report: Omit<WindowReport, 'at'>): boolean {
+    const window = this.#windows.get(id)
+    if (!window || window.member.id !== member.id) return false
+    const moved = JSON.stringify(report.position) !== JSON.stringify(window.report?.position)
+    window.report = { ...report, at: Date.now() }
+    if (moved) for (const listener of [...this.#watchers]) listener()
+    return true
+  }
+
+  watch(listener: () => void): () => void {
+    this.#watchers.add(listener)
+    return () => void this.#watchers.delete(listener)
+  }
+
+  policy(kind: ApprovalKind): ApprovalPolicy {
+    return this.#options.policy[kind] ?? 'ask'
+  }
+
+  answer(id: string, allow: boolean, member: Member): 200 | 403 | 404 {
+    const pending = this.#pending.get(id)
+    if (!pending) return 404
+    if (!this.#eligible(member, pending.request)) return 403
+    pending.settle(allow)
+    return 200
+  }
+
+  positions(member?: Member, document?: string, viewer?: Member): { window: string, member: string, roles: MemberRole[], document: string, report: WindowReport }[] {
+    const all = [...this.#windows.values()].filter(w => w.report?.position && (!member || w.member.id === member.id) && (document === undefined || w.document === document))
+    const trusted = (w: Window) => hasRole(w.member, 'editor') || w.member.id === viewer?.id
+    const rank = (w: Window) => (!trusted(w) ? 2 : presents(w) ? 0 : 1)
+    return all.sort((a, b) => rank(a) - rank(b) || b.report!.at - a.report!.at)
+      .map(w => ({ window: w.id, member: w.member.id, roles: w.member.roles, document: w.document, report: w.report! }))
+  }
+
+  go(position: WindowPosition, member?: Member, document?: string): number {
+    const windows = [...this.#windows.values()].filter(w => (!member || w.member.id === member.id) && (document === undefined || w.document === document))
+    const presenting = windows.filter(w => w.report?.role === 'presenter' || w.report?.role === 'audience')
+    const targets = presenting.length > 0 ? presenting : windows
+    for (const window of targets) window.send('go', position)
+    return targets.length
+  }
+
+  session(action: 'start' | 'end', name?: string, document?: string, member?: Member): number {
+    const windows = [...this.#windows.values()].filter(w => (!member || w.member.id === member.id) && (document === undefined || w.document === document) && (w.report?.role === 'presenter' || w.report?.role === 'audience'))
+    for (const window of windows) window.send('session', { action, name })
+    return windows.length
+  }
+
+  status(document?: string): Record<string, unknown> {
+    const out: Record<string, unknown> = {}
+    const rank = (w: Window) => (w.report?.role === 'presenter' ? 1 : 0)
+    const windows = [...this.#windows.values()]
+      .filter(w => w.report?.status && hasRole(w.member, 'editor') && (document === undefined || w.document === document))
+      .sort((a, b) => rank(a) - rank(b) || a.report!.at - b.report!.at)
+    for (const window of windows) Object.assign(out, window.report!.status)
+    return out
+  }
+
+  close(): void {
+    for (const pending of [...this.#pending.values()]) pending.settle(false)
+    for (const window of [...this.#windows.values()]) window.close()
+  }
+
+  #request(request: ApprovalRequest, signal?: AbortSignal): Promise<boolean> {
+    const policy = this.#options.policy[request.kind] ?? 'ask'
+    if (policy === 'allow') return Promise.resolve(true)
+    if (policy === 'off' || signal?.aborted) return Promise.resolve(false)
+    return new Promise<boolean>((resolve) => {
+      const id = randomUUID()
+      const timer = setTimeout(() => pending.settle(false), this.#options.timeoutMs ?? APPROVAL_TIMEOUT_MS)
+      const onAbort = () => pending.settle(false)
+      const pending: Pending = {
+        id,
+        request: { ...request, scope: request.scope ?? 'workspace' },
+        document: '',
+        settle: (allow) => {
+          if (!this.#pending.delete(id)) return
+          clearTimeout(timer)
+          signal?.removeEventListener('abort', onAbort)
+          for (const window of this.#windows.values()) window.send('settled', { id, allow })
+          resolve(allow)
+        },
+      }
+      signal?.addEventListener('abort', onAbort, { once: true })
+      this.#pending.set(id, pending)
+      for (const window of this.#windows.values()) {
+        if (this.#eligible(window.member, pending.request)) window.send('approval', { id, request: pending.request })
+      }
+    })
+  }
+
+  #eligible(member: Member, request: ApprovalRequest): boolean {
+    if ((request.scope ?? 'workspace') === 'workspace') return hasRole(member, 'owner')
+    return request.member ? member.id === request.member : hasRole(member, 'editor')
+  }
+}

package/src/focus.ts

@@ -0,0 +1,47 @@
+import { focusReport, resolveFocus } from '@lincyaw/mcp'
+import type { McpFocus } from '@lincyaw/mcp'
+import type { FocusReport, IRDocument } from '@lincyaw/kernel'
+
+const MAX_FOCUS = 50
+
+export class FocusStore {
+  readonly #latest = new Map<string, McpFocus>()
+  readonly #watchers = new Set<() => void>()
+
+  get(document?: string): McpFocus | undefined {
+    if (document !== undefined) return this.#latest.get(document)
+    let newest: McpFocus | undefined
+    for (const found of this.#latest.values()) if (!newest || found.at >= newest.at) newest = found
+    return newest
+  }
+
+  report(document: string, doc: IRDocument, reports: FocusReport[]): McpFocus {
+    const record = { document, focus: reports.map(report => resolveFocus(doc, document, report)), at: Date.now() }
+    this.#latest.set(document, record)
+    for (const watcher of this.#watchers) watcher()
+    return record
+  }
+
+  forget(document: string): void {
+    if (this.#latest.delete(document)) for (const watcher of this.#watchers) watcher()
+  }
+
+  watch(listener: () => void): () => void {
+    this.#watchers.add(listener)
+    return () => this.#watchers.delete(listener)
+  }
+}
+
+export function focusBody(body: unknown): { document: string, focus: FocusReport[] } | string {
+  if (!body || typeof body !== 'object') return 'a JSON object { document, focus: [...] }'
+  const { document, focus } = body as { document?: unknown, focus?: unknown }
+  if (typeof document !== 'string') return 'the document directory (relative to the workspace root) as `document`'
+  if (!Array.isArray(focus) || focus.length > MAX_FOCUS) return `focus is a list of at most ${MAX_FOCUS}`
+  const reports: FocusReport[] = []
+  for (const item of focus) {
+    const report = focusReport(item)
+    if (typeof report === 'string') return report
+    reports.push(report)
+  }
+  return { document, focus: reports }
+}

package/src/host.ts

@@ -0,0 +1,52 @@
+import type { Compilation } from '@lincyaw/compiler'
+import { pluginId } from '@lincyaw/compiler'
+import type { Finding, IRDocument, PresmiumNodePlugin, RunResult, ServiceToken } from '@lincyaw/kernel'
+
+export interface ServedPlugin {
+  id: string
+  plugin: PresmiumNodePlugin
+  config: Record<string, unknown>
+}
+
+export interface ServedDocument {
+  deckDir: string
+  workspaceRoot: string
+  lang?: string
+  plugins: ServedPlugin[]
+  service<T>(token: ServiceToken<T>): T | undefined
+  settings?: Record<string, Record<string, unknown>>
+  operatorDir?: string
+  home?: boolean
+}
+
+export function servedDocument(compilation: Compilation): ServedDocument {
+  const { presmium } = compilation.doc.config
+  return {
+    deckDir: compilation.deckDir,
+    workspaceRoot: compilation.workspaceRoot,
+    lang: compilation.doc.meta.lang,
+    plugins: compilation.plugins.flatMap((loaded) => {
+      if (!loaded.plugin) return []
+      const config = presmium[pluginId(loaded)]
+      return [{ id: pluginId(loaded), plugin: loaded.plugin, config: config !== null && typeof config === 'object' && !Array.isArray(config) ? config as Record<string, unknown> : {} }]
+    }),
+    service: compilation.service,
+    settings: compilation.settings,
+    ...compilation.operatorDir ? { operatorDir: compilation.operatorDir } : {},
+  }
+}
+
+export interface HostDocument {
+  dir: string
+  title: string
+  lang?: string
+  tags?: string[]
+}
+
+export interface ServerHost {
+  documents(): Promise<HostDocument[]>
+  compile(document: string): Promise<{ doc: IRDocument, diagnostics: Finding[] }>
+  check(document: string): Promise<Finding[]>
+  build(document: string, options?: { to?: string[] }): Promise<{ outputs: { renderer: string, outDir: string }[], findings: Finding[] }>
+  run(document: string, target: { section: string, block: string }, signal?: AbortSignal): Promise<RunResult>
+}

package/src/http.ts

@@ -0,0 +1,169 @@
+import { createServer } from 'node:http'
+import type { IncomingHttpHeaders, IncomingMessage, Server, ServerResponse } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import type { Duplex } from 'node:stream'
+import { getRequestListener } from '@hono/node-server'
+import { json, problem } from '@lincyaw/kernel'
+import { createProxyServer } from 'http-proxy-3'
+
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]'])
+
+export function hostname(host: string | null | undefined): string {
+  if (!host) return ''
+  const value = host.trim().toLowerCase()
+  if (value.startsWith('[')) return value.slice(0, value.indexOf(']') + 1)
+  if (value.indexOf(':') !== value.lastIndexOf(':')) return `[${value}]`
+  return value.replace(/:\d+$/, '')
+}
+
+export function isLoopback(host: string | null | undefined): boolean {
+  return LOOPBACK.has(hostname(host))
+}
+
+export function originHost(origin: string | null | undefined): string | undefined {
+  if (origin === null || origin === undefined) return undefined
+  try {
+    return hostname(new URL(origin).host)
+  } catch {
+    return ''
+  }
+}
+
+export function bearer(value: string | null | undefined): string | undefined {
+  const match = /^Bearer\s+(\S+)$/i.exec(value?.trim() ?? '')
+  return match?.[1]
+}
+
+export { json, problem }
+
+export async function limitBody(request: Request, limit: number): Promise<Request | Response> {
+  const tooLarge = () => json({ error: `the request body is larger than this route takes (${limit} bytes)` }, 413)
+  const declared = Number(request.headers.get('content-length') ?? Number.NaN)
+  if (declared > limit) return tooLarge()
+  if (!request.body) return request
+  const chunks: Uint8Array[] = []
+  let size = 0
+  const reader = request.body.getReader()
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    size += value.byteLength
+    if (size > limit) {
+      void drop(reader)
+      return tooLarge()
+    }
+    chunks.push(value)
+  }
+  const body = new Uint8Array(size)
+  let at = 0
+  for (const chunk of chunks) {
+    body.set(chunk, at)
+    at += chunk.byteLength
+  }
+  return new Request(request.url, { method: request.method, headers: request.headers, body, signal: request.signal })
+}
+
+async function drop(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void> {
+  try {
+    while (!(await reader.read()).done) {}
+  } catch {}
+}
+
+export function header(headers: IncomingHttpHeaders, name: string): string | undefined {
+  const value = headers[name.toLowerCase()]
+  return Array.isArray(value) ? value[0] : value
+}
+
+export async function send(res: ServerResponse, response: Response): Promise<void> {
+  res.writeHead(response.status, Object.fromEntries(response.headers))
+  res.end(Buffer.from(await response.arrayBuffer()))
+}
+
+export function refuseUpgrade(socket: Duplex, status: number): void {
+  socket.end(`HTTP/1.1 ${status} ${status === 401 ? 'Unauthorized' : status === 403 ? 'Forbidden' : 'Not Found'}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`)
+}
+
+export interface ProxyTarget {
+  target: string
+  path: string
+  headers?: Record<string, string>
+}
+
+export function createProxy() {
+  const proxy = createProxyServer({ ws: true, xfwd: false })
+  proxy.on('error', (error: Error, _req: unknown, res: unknown) => {
+    const response = res as ServerResponse | Duplex | undefined
+    if (response && 'writeHead' in response && !response.headersSent) {
+      response.writeHead(502, { 'Content-Type': 'text/plain; charset=utf-8' })
+      response.end(`proxy error: ${error.message}`)
+    } else {
+      response?.destroy?.()
+    }
+  })
+  return {
+    web(req: IncomingMessage, res: ServerResponse, to: ProxyTarget): void {
+      req.url = to.path
+      proxy.web(req, res, { target: to.target, headers: to.headers })
+    },
+    ws(req: IncomingMessage, socket: Duplex, head: Buffer, to: ProxyTarget): void {
+      req.url = to.path
+      proxy.ws(req, socket, head, { target: to.target, headers: to.headers })
+    },
+    close: () => proxy.close(),
+  }
+}
+
+export type Proxy = ReturnType<typeof createProxy>
+
+export type Decision =
+  | { kind: 'fetch' }
+  | { kind: 'proxy', to: ProxyTarget }
+  | { kind: 'answer', response: Response }
+
+export function nodeServer(options: {
+  decide(req: IncomingMessage): Promise<Decision>
+  decideUpgrade(req: IncomingMessage): Promise<{ to?: ProxyTarget, status?: number }>
+  fetch(request: Request, req: IncomingMessage): Promise<Response>
+  proxy: Proxy
+}): Server {
+  const listener = getRequestListener((request, env) => options.fetch(request, (env as { incoming: IncomingMessage }).incoming))
+  const server = createServer((req, res) => {
+    void options.decide(req).then((decision) => {
+      if (decision.kind === 'fetch') return listener(req, res)
+      if (decision.kind === 'proxy') return options.proxy.web(req, res, decision.to)
+      return send(res, decision.response)
+    }).catch((error: unknown) => {
+      if (!res.headersSent) res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' })
+      res.end(error instanceof Error ? error.message : String(error))
+    })
+  })
+  server.on('upgrade', (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+    void options.decideUpgrade(req).then(({ to, status }) => {
+      if (to) options.proxy.ws(req, socket, head, to)
+      else refuseUpgrade(socket, status ?? 404)
+    }, () => refuseUpgrade(socket, 500))
+  })
+  return server
+}
+
+export function listen(server: Server, port: number, host: string): Promise<number> {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(port, host, () => {
+      server.off('error', reject)
+      resolve((server.address() as AddressInfo).port)
+    })
+  })
+}
+
+export function closeServer(server: Server): Promise<void> {
+  return new Promise((resolve) => {
+    server.close(() => resolve())
+    server.closeAllConnections()
+  })
+}
+
+export function urlHost(host: string): string {
+  if (host === '0.0.0.0' || host === '::') return '127.0.0.1'
+  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { APPROVAL_TIMEOUT_MS, Control } from './control.ts'
+export type { ApprovalPolicy, WindowPosition, WindowReport } from './control.ts'
+export { servedDocument } from './host.ts'
+export type { HostDocument, ServedDocument, ServedPlugin, ServerHost } from './host.ts'
+export { anyAddress, networkAddresses } from './auth.ts'
+export { bearer, isLoopback, json, limitBody, problem } from './http.ts'
+export { LOCAL_AUTHOR, SERVER_PATH, startServer } from './server.ts'
+export type { PresmiumServer, ServerOptions } from './server.ts'

package/src/mcp.ts

@@ -0,0 +1,64 @@
+import type { AgentTool, Member, ServiceToken } from '@lincyaw/kernel'
+import type { McpHost, McpPluginTools, McpPosition } from '@lincyaw/mcp'
+import type { Control } from './control.ts'
+import type { FocusStore } from './focus.ts'
+import type { ServedDocument, ServerHost } from './host.ts'
+
+export interface McpHostOptions {
+  serverHost?: ServerHost
+  control: Control
+  command: 'dev' | 'serve'
+  mount(document: string): Promise<ServedDocument | undefined>
+  mounted(): Promise<ServedDocument[]>
+  service<T>(token: ServiceToken<T>): T | undefined
+  focus: FocusStore
+}
+
+function toolsOf(documents: ServedDocument[], own: McpHostOptions['service']): McpPluginTools {
+  const tools = new Map<string, AgentTool>()
+  for (const doc of documents) {
+    for (const { plugin } of doc.plugins) for (const tool of plugin.tools ?? []) if (!tools.has(tool.name)) tools.set(tool.name, tool)
+  }
+  const doc = documents[0]
+  return { tools: [...tools.values()], service: <T>(token: ServiceToken<T>) => own(token) ?? doc?.service(token) }
+}
+
+export function serverMcpHost(options: McpHostOptions): McpHost {
+  const { control } = options
+  const host = (): ServerHost => {
+    if (!options.serverHost) throw new Error('this server has no host operations')
+    return options.serverHost
+  }
+  const position = (entry: ReturnType<Control['positions']>[number]): McpPosition => {
+    const { report } = entry
+    const { slide, step, view, section, trail } = report.position!
+    return { document: entry.document, member: entry.member, slide, step, view, ...section === undefined ? {} : { section }, ...trail ? { trail } : {}, role: report.role, at: report.at }
+  }
+  return {
+    process: { command: options.command },
+    documents: () => host().documents(),
+    compile: document => host().compile(document),
+    check: document => host().check(document),
+    build: (document, build) => host().build(document, build),
+    run: (document, target, signal) => host().run(document, target, signal),
+    approve: (request, signal) => control.approvals.request(request, signal),
+    offers: kind => control.policy(kind) !== 'off',
+    approval: kind => control.policy(kind),
+    async tools(document) {
+      if (document === undefined) return toolsOf(await options.mounted(), options.service)
+      const doc = await options.mount(document)
+      return toolsOf(doc ? [doc] : [], options.service)
+    },
+    positions(document: string | undefined, member: Member) {
+      const all = control.positions(undefined, document, member)
+      const presenting = (w: typeof all[number]) => w.member === member.id && (w.report.role === 'presenter' || w.report.role === 'audience')
+      return [...all.filter(presenting), ...all.filter(w => !presenting(w))].map(position)
+    },
+    watchPositions: listener => control.watch(listener),
+    focus: document => options.focus.get(document),
+    watchFocus: listener => options.focus.watch(listener),
+    classroom: document => control.status(document),
+    navigate: (document, to, member) => control.go(to, member, document),
+    session: (document, action, name, member) => control.session(action, name, document, member),
+  }
+}

package/src/server.ts

@@ -0,0 +1,469 @@
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
+import { chmodSync, mkdirSync, writeFileSync } from 'node:fs'
+import type { IncomingMessage } from 'node:http'
+import { dirname } from 'node:path'
+import { APPROVALS, eventStream, isRecord, MAX_BODY, MCP_ENDPOINT, errorMessage, prefixed } from '@lincyaw/kernel'
+import type {
+  ApprovalKind,
+  Logger,
+  McpEndpoint,
+  Member,
+  ProxySpec,
+  Route,
+  ServerContext,
+  ServerContribution,
+  ServiceToken,
+} from '@lincyaw/kernel'
+import { pluginLogger } from '@lincyaw/compiler'
+import { createPresmiumMcp } from '@lincyaw/mcp'
+import type { McpCaller } from '@lincyaw/mcp'
+import { authenticate, LOCAL_AUTHOR, machineHosts } from './auth.ts'
+import type { Refusal } from './auth.ts'
+import { Control, hasRole } from './control.ts'
+import type { ApprovalPolicy, WindowPosition } from './control.ts'
+import { focusBody, FocusStore } from './focus.ts'
+import type { ServedDocument, ServerHost } from './host.ts'
+import { bearer, closeServer, createProxy, header, isLoopback, json, limitBody, listen, nodeServer, problem, urlHost } from './http.ts'
+import type { Decision, ProxyTarget } from './http.ts'
+import { serverMcpHost } from './mcp.ts'
+
+export { LOCAL_AUTHOR }
+
+export const SERVER_PATH = '/__presmium/presmium.server'
+
+function isMcp(path: string): boolean {
+  return path === '/mcp' || path.startsWith('/mcp/')
+}
+
+function endedBy(response: Response, signal: AbortSignal, done: () => void): Response {
+  if (!response.body) {
+    done()
+    return response
+  }
+  const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>()
+  void response.body.pipeTo(writable, { signal, preventAbort: true })
+    .catch(() => writable.close().catch(() => undefined))
+    .finally(done)
+  return new Response(readable, { status: response.status, statusText: response.statusText, headers: response.headers })
+}
+
+export interface ServerOptions {
+  mode: 'dev' | 'serve'
+  host?: string
+  port?: number
+  document(dir: string): Promise<ServedDocument | undefined>
+  serverHost?: ServerHost
+  settings?: Record<string, Record<string, unknown>>
+  approvals?: Partial<Record<ApprovalKind, ApprovalPolicy>>
+  forward?(): string | undefined
+  operatorDir?: string
+  stateFile?: string
+  mcp?(request: Request, access: McpCaller): Promise<Response>
+  env?: NodeJS.ProcessEnv
+  approvalTimeoutMs?: number
+  log?: Logger
+}
+
+export interface PresmiumServer {
+  url: string
+  port: number
+  token: string
+  services: [ServiceToken<unknown>, unknown][]
+  control: Control
+  serverHost?: ServerHost
+  unmount(dir: string): Promise<void>
+  close(): Promise<void>
+}
+
+interface Mounted {
+  doc: ServedDocument
+  contributions: Map<string, ServerContribution>
+}
+
+function pluginPath(pathname: string): { plugin: string, path: string, raw: string, plain: boolean } | undefined {
+  const match = /^\/__presmium\/([^/]+)\/?(.*)$/.exec(pathname)
+  if (!match) return undefined
+  const raw = match[2]!
+  let path = raw
+  let plain = !/%(?:2f|5c)/i.test(raw) && !raw.includes('\\')
+  try {
+    path = decodeURIComponent(raw)
+  } catch {
+    plain = false
+  }
+  if (path.split('/').some(part => part === '.' || part === '..')) plain = false
+  return { plugin: match[1]!, path, raw, plain }
+}
+
+function findRoute(routes: Record<string, Route> | undefined, path: string): { route: Route, rest: string, key: string } | undefined {
+  if (!routes) return undefined
+  if (routes[path] && !path.endsWith('/*')) return { route: routes[path]!, rest: '', key: path }
+  let best: { route: Route, rest: string, key: string } | undefined
+  for (const [key, route] of Object.entries(routes)) {
+    if (!key.endsWith('/*')) continue
+    const prefix = key.slice(0, -1)
+    const base = key.slice(0, -2)
+    if ((path.startsWith(prefix) || path === base) && (!best || key.length > best.key.length)) best = { route, rest: path.slice(prefix.length), key }
+  }
+  return best
+}
+
+function findProxy(proxies: ProxySpec[] | undefined, path: string): { spec: ProxySpec, rest: string } | undefined {
+  for (const spec of proxies ?? []) {
+    const base = spec.path.replace(/^\/+|\/+$/g, '')
+    if (path === base || path.startsWith(`${base}/`)) return { spec, rest: path.slice(base.length) }
+  }
+  return undefined
+}
+
+function documentOf(headers: IncomingMessage['headers'], url: URL): string {
+  const value = header(headers, 'presmium-document') ?? url.searchParams.get('document') ?? ''
+  try {
+    return decodeURIComponent(value).replace(/^\/+|\/+$/g, '')
+  } catch {
+    return value
+  }
+}
+
+function remoteHost(mode: ServerOptions['mode'], host: string, port: number | undefined): string | undefined {
+  if (mode === 'serve' || isLoopback(host)) return undefined
+  const at = port || 'its port'
+  return `presmium ${mode} listens on this machine only, not on ${host}: it serves the one user who runs it. To use it from another machine, forward its port over SSH (ssh -L ${at}:127.0.0.1:${at} <this machine>), or use presmium serve --host`
+}
+
+export async function startServer(options: ServerOptions): Promise<PresmiumServer> {
+  const env = options.env ?? process.env
+  const log = options.log ?? pluginLogger('presmium server')
+  const listenHost = options.host ?? '127.0.0.1'
+  const refused = remoteHost(options.mode, listenHost, options.port)
+  if (refused) throw new Error(refused)
+  const local = machineHosts(listenHost)
+
+  const control = new Control({
+    policy: options.approvals ?? {},
+    timeoutMs: options.approvalTimeoutMs,
+  })
+  const token = randomBytes(24).toString('base64url')
+  const mcpTokens = new Map<string, McpCaller>()
+  const mcpStreams = new Map<string, Set<AbortController>>()
+  let url = ''
+  const mcpEndpoint: McpEndpoint = {
+    issue(member, mode, issued = {}) {
+      const value = randomBytes(24).toString('base64url')
+      mcpTokens.set(value, { member, mode, ...issued.confirmed ? { confirmed: true } : {}, ...issued.document !== undefined ? { document: issued.document } : {} })
+      return {
+        url: `${url}/mcp`,
+        token: value,
+        revoke: () => {
+          mcpTokens.delete(value)
+          for (const stream of mcpStreams.get(value) ?? []) stream.abort()
+          mcpStreams.delete(value)
+        },
+      }
+    },
+  }
+  const services: [ServiceToken<unknown>, unknown][] = [[APPROVALS, control.approvals], [MCP_ENDPOINT, mcpEndpoint]]
+
+  const serviceToken = env.PRESMIUM_SERVICE_TOKEN || undefined
+  const fromHost = (request: Request) => {
+    const given = bearer(request.headers.get('authorization'))
+    if (!serviceToken || given === undefined || given.length !== serviceToken.length) return false
+    return timingSafeEqual(Buffer.from(given), Buffer.from(serviceToken))
+  }
+  const sessions = new Map<string, ReturnType<McpEndpoint['issue']>>()
+  const focus = new FocusStore()
+  const own = new Map(services.map(([token, impl]) => [token.id, impl]))
+
+  const mounted = new Map<string, Promise<Mounted | undefined>>()
+  const mount = (dir: string) => {
+    let known = mounted.get(dir)
+    if (!known) {
+      known = (async () => {
+        const doc = await options.document(dir)
+        if (!doc) return undefined
+        log.debug(`mounting the server contributions of ${dir || 'the deck'}: ${doc.plugins.filter(p => p.plugin.server).map(p => p.id).join(', ') || 'none'}`)
+        const contributions = new Map<string, ServerContribution>()
+        for (const { id, plugin, config } of doc.plugins) {
+          if (!plugin.server) continue
+          const operatorDir = options.operatorDir ?? doc.operatorDir
+          const ctx: ServerContext = {
+            deckDir: doc.deckDir,
+            workspaceRoot: doc.workspaceRoot,
+            config,
+            settings: (options.settings ?? doc.settings)?.[id] ?? {},
+            lang: doc.lang,
+            service: <T>(token: ServiceToken<T>) => (own.get(token.id) as T | undefined) ?? doc.service(token),
+            secret: name => env[name],
+            ...operatorDir ? { operatorDir } : {},
+            ...doc.home ? { home: true } : {},
+            log: prefixed(log, id),
+          }
+          try {
+            contributions.set(id, await plugin.server.call(plugin, ctx))
+          } catch (error) {
+            log.error(`plugin ${id} failed to make its server contribution: ${errorMessage(error)}`)
+          }
+        }
+        return { doc, contributions }
+      })()
+      const loading = known
+      loading.then((found) => {
+        if (!found && mounted.get(dir) === loading) mounted.delete(dir)
+      }, () => mounted.delete(dir))
+      mounted.set(dir, known)
+    }
+    return known
+  }
+
+  const mcp = options.mcp ? undefined : createPresmiumMcp(serverMcpHost({
+    serverHost: options.serverHost,
+    control,
+    command: options.mode,
+    mount: async dir => (await mount(dir))?.doc,
+    mounted: async () => (await Promise.all([...mounted.values()].map(known => known.catch(() => undefined)))).flatMap(m => (m ? [m.doc] : [])),
+    service: <T>(token: ServiceToken<T>) => own.get(token.id) as T | undefined,
+    focus,
+  }))
+
+  const members = new WeakMap<IncomingMessage, Member | Refusal>()
+  const memberOf = (req: IncomingMessage): Member | Refusal => {
+    let found = members.get(req)
+    if (!found) members.set(req, found = authenticate(req, local))
+    return found
+  }
+
+  const refuse = (refusal: Refusal): Decision => ({ kind: 'answer', response: problem(refusal.status, refusal.message) })
+
+  const decide = async (req: IncomingMessage): Promise<Decision> => {
+    const url = new URL(req.url ?? '/', 'http://presmium')
+    const path = url.pathname
+    const member = memberOf(req)
+    if ('status' in member) return refuse(member)
+    const target = pluginPath(path)
+    if (target && !target.plain) return refuse({ status: 400, message: 'a path with a . or .. part or an encoded separator' })
+    if (isMcp(path)) return { kind: 'fetch' }
+    if (target) {
+      if (target.plugin === 'presmium.server') return { kind: 'fetch' }
+      const proxy = await proxyOf(target, documentOf(req.headers, url), member, url.search)
+      return proxy ?? { kind: 'fetch' }
+    }
+    const forward = options.mode === 'serve' ? options.forward?.() : undefined
+    if (!forward) return { kind: 'answer', response: problem(404, 'not found') }
+    const site = new URL(forward)
+    const lan = !isLoopback(header(req.headers, 'host'))
+    const headers = lan ? { host: site.host, ...header(req.headers, 'origin') ? { origin: site.origin } : {} } : undefined
+    return { kind: 'proxy', to: { target: forward, path: req.url ?? '/', ...headers ? { headers } : {} } }
+  }
+
+  const proxyOf = async (target: { plugin: string, path: string, raw: string }, dir: string, member: Member, search: string): Promise<Decision | undefined> => {
+    const contribution = (await mount(dir))?.contributions.get(target.plugin)
+    const found = findProxy(contribution?.proxies, target.path)
+    if (!found) return undefined
+    const role = found.spec.role ?? 'editor'
+    if (!hasRole(member, role)) return refuse({ status: 403, message: `this proxy needs the role ${role}` })
+    const base = found.spec.path.split('/').filter(Boolean).length
+    const rest = target.raw.split('/').slice(base).join('/')
+    const path = `${rest ? `/${rest}` : found.rest || '/'}${search}`
+    return { kind: 'proxy', to: { target: found.spec.target, path, headers: found.spec.headers } }
+  }
+
+  const decideUpgrade = async (req: IncomingMessage): Promise<{ to?: ProxyTarget, status?: number }> => {
+    const decision = await decide(req)
+    if (decision.kind === 'proxy') return { to: decision.to }
+    return { status: decision.kind === 'answer' ? decision.response.status : 404 }
+  }
+
+  const serveMcp = async (request: Request): Promise<Response> => {
+    const given = bearer(request.headers.get('authorization'))
+    const access: McpCaller | undefined = given === undefined ? undefined : given === token ? { member: LOCAL_AUTHOR, mode: 'author' as const } : mcpTokens.get(given)
+    if (!access) return problem(401, 'MCP needs an Authorization: Bearer token')
+    const limited = await limitBody(request, MAX_BODY)
+    if (limited instanceof Response) return limited
+    request = limited
+    const response = await (options.mcp ? options.mcp(request, access) : mcp!.fetch(request, access))
+    if (given === token || !response.headers.get('content-type')?.startsWith('text/event-stream')) return response
+    if (!mcpTokens.has(given!)) return endedBy(response, AbortSignal.abort(), () => {})
+    const stream = new AbortController()
+    const open = mcpStreams.get(given!) ?? new Set()
+    mcpStreams.set(given!, open.add(stream))
+    return endedBy(response, stream.signal, () => open.delete(stream))
+  }
+
+  const handle = async (request: Request, req: IncomingMessage): Promise<Response> => {
+    const url = new URL(request.url)
+    const path = url.pathname
+    const member = memberOf(req)
+    if ('status' in member) return problem(member.status, member.message)
+    const document = documentOf(req.headers, url)
+    if (isMcp(path)) return serveMcp(request)
+    if (path.startsWith(`${SERVER_PATH}/`)) return await serverRoute(request, path.slice(SERVER_PATH.length + 1), member, document, req)
+    const target = pluginPath(path)
+    if (!target) return problem(404, 'not found')
+    return await pluginRoute(request, target, member, document)
+  }
+
+  const serverRoute = async (request: Request, route: string, member: Member, document: string, req: IncomingMessage): Promise<Response> => {
+    if (route === 'hello') return json({ member, document })
+    if (route === 'control') {
+      if (request.method === 'GET') {
+        const window = new URL(request.url).searchParams.get('window') || randomUUID()
+        const stream = control.open(window, member, document)
+        req.once('close', () => stream.close())
+        return eventStream(stream, request.signal)
+      }
+      if (request.method !== 'POST') return problem(405, 'GET or POST')
+      const limited = await limitBody(request, MAX_BODY)
+      if (limited instanceof Response) return limited
+      const body: unknown = await limited.json().catch(() => undefined)
+      if (!isRecord(body)) return problem(400, 'a JSON object')
+      if (body.type === 'answer' && typeof body.id === 'string') {
+        const status = control.answer(body.id, body.allow === true, member)
+        return status === 200 ? json({ ok: true }) : problem(status, status === 404 ? 'no such approval' : 'this member may not answer this approval')
+      }
+      if (body.type === 'report' && typeof body.window === 'string') {
+        const position = windowPosition(body.position)
+        const ok = control.report(body.window, member, { position, role: typeof body.role === 'string' ? body.role : undefined, status: isRecord(body.status) ? body.status : undefined })
+        return ok ? json({ ok: true }) : problem(404, 'unknown window')
+      }
+      return problem(400, 'unknown message')
+    }
+    if (route === 'tokens') return await tokensRoute(request)
+    if (route === 'focus') return await focusRoute(request)
+    return problem(404, 'not found')
+  }
+
+  const tokensRoute = async (request: Request): Promise<Response> => {
+    if (!serviceToken) return problem(403, 'session tokens are issued only to the host that started this service (PRESMIUM_SERVICE_TOKEN)')
+    if (!fromHost(request)) return problem(401, 'session tokens need Authorization: Bearer <the service token>')
+    const limited = await limitBody(request, MAX_BODY)
+    if (limited instanceof Response) return limited
+    const body: unknown = await limited.json().catch(() => ({}))
+    const session = isRecord(body) && typeof body.session === 'string' && body.session !== '' ? body.session : undefined
+    if (request.method === 'DELETE') {
+      const revoked = session === undefined ? [...sessions.keys()] : sessions.has(session) ? [session] : []
+      for (const id of revoked) {
+        sessions.get(id)!.revoke()
+        sessions.delete(id)
+      }
+      return json({ revoked: revoked.length })
+    }
+    if (request.method !== 'POST') return problem(405, 'POST or DELETE')
+    if (!isRecord(body) || typeof body.document !== 'string' || session === undefined) return problem(400, '{ document, session }')
+    const document = body.document
+    if (options.serverHost && !(await options.serverHost.documents()).some(doc => doc.dir === document)) return problem(404, `no document ${JSON.stringify(document)}`)
+    sessions.get(session)?.revoke()
+    const grant = mcpEndpoint.issue(LOCAL_AUTHOR, 'author', { confirmed: true, document })
+    sessions.set(session, grant)
+    return json({ url: grant.url, token: grant.token, document }, 201)
+  }
+
+  const focusRoute = async (request: Request): Promise<Response> => {
+    if (request.method === 'GET') {
+      const params = new URL(request.url).searchParams
+      const found = focus.get(params.has('document') ? params.get('document')! : undefined)
+      return json(found ? { document: found.document, focus: found.focus, reported: new Date(found.at).toISOString() } : { focus: null })
+    }
+    if (request.method !== 'POST') return problem(405, 'GET or POST')
+    if (serviceToken && !fromHost(request)) return problem(401, 'a focus report needs Authorization: Bearer <the service token>')
+    if (!options.serverHost) return problem(409, 'this server compiles no document')
+    const limited = await limitBody(request, MAX_BODY)
+    if (limited instanceof Response) return limited
+    const body = focusBody(await limited.json().catch(() => undefined))
+    if (typeof body === 'string') return problem(400, body)
+    if (!(await options.serverHost.documents()).some(doc => doc.dir === body.document)) return problem(404, `no document ${JSON.stringify(body.document)}`)
+    try {
+      const { doc } = await options.serverHost.compile(body.document)
+      const record = focus.report(body.document, doc, body.focus)
+      return json({ document: record.document, focus: record.focus, reported: new Date(record.at).toISOString() })
+    } catch (error) {
+      return problem(400, errorMessage(error))
+    }
+  }
+
+  const pluginRoute = async (request: Request, target: { plugin: string, path: string }, member: Member, document: string): Promise<Response> => {
+    const known = await mount(document)
+    if (!known) return problem(404, `no document ${JSON.stringify(document)}`)
+    const found = findRoute(known.contributions.get(target.plugin)?.routes, target.path)
+    if (!found) return problem(404, 'not found')
+    const role = found.route.role ?? 'editor'
+    if (!hasRole(member, role)) return problem(403, `this route needs the role ${role}`)
+    const limited = await limitBody(request, found.route.maxBody ?? MAX_BODY)
+    if (limited instanceof Response) return limited
+    try {
+      const response = await found.route.handle(limited, { member, document, rest: found.rest })
+      return response.headers.has('cache-control') ? response : withHeaders(response, { 'Cache-Control': 'no-store' })
+    } catch (error) {
+      log.error(`route ${target.plugin}/${target.path} failed: ${errorMessage(error)}`)
+      return problem(500, errorMessage(error))
+    }
+  }
+
+  const proxy = createProxy()
+  const server = nodeServer({ decide, decideUpgrade, fetch: handle, proxy })
+  const port = await listen(server, options.port ?? (options.mode === 'dev' ? 0 : 4310), listenHost)
+  url = `http://${urlHost(listenHost)}:${port}`
+  log.debug(`listening at ${url}`)
+  if (options.stateFile) {
+    mkdirSync(dirname(options.stateFile), { recursive: true })
+    writeFileSync(options.stateFile, `${JSON.stringify({ url, mcp: `${url}/mcp`, token, pid: process.pid }, null, 2)}\n`, { mode: 0o600 })
+    chmodSync(options.stateFile, 0o600)
+  }
+
+  const takeDown = async (known: Promise<Mounted | undefined>) => {
+    for (const [id, contribution] of (await known.catch(() => undefined))?.contributions ?? []) {
+      await Promise.resolve(contribution.close?.()).catch((error: unknown) => log.error(`the contribution of ${id} failed to close: ${errorMessage(error)}`))
+    }
+  }
+
+  return {
+    url,
+    port,
+    token,
+    services,
+    control,
+    serverHost: options.serverHost,
+    async unmount(dir) {
+      focus.forget(dir)
+      const known = mounted.get(dir)
+      mounted.delete(dir)
+      if (known) {
+        log.debug(`unmounting the server contributions of ${dir || 'the deck'}`)
+        await takeDown(known)
+      }
+    },
+    async close() {
+      for (const grant of sessions.values()) grant.revoke()
+      sessions.clear()
+      control.close()
+      await mcp?.close().catch((error: unknown) => log.error(`MCP failed to close: ${errorMessage(error)}`))
+      for (const known of mounted.values()) await takeDown(known)
+      proxy.close()
+      await closeServer(server)
+    },
+  }
+}
+
+function withHeaders(response: Response, headers: Record<string, string>): Response {
+  for (const [name, value] of Object.entries(headers)) {
+    try {
+      response.headers.set(name, value)
+    } catch {
+      const copy = new Response(response.body, response)
+      for (const [n, v] of Object.entries(headers)) copy.headers.set(n, v)
+      return copy
+    }
+  }
+  return response
+}
+
+function windowPosition(value: unknown): WindowPosition | undefined {
+  if (!isRecord(value) || typeof value.slide !== 'number' || typeof value.step !== 'number') return undefined
+  const { trail } = value
+  return {
+    slide: value.slide,
+    step: value.step,
+    ...typeof value.view === 'string' ? { view: value.view } : {},
+    ...typeof value.section === 'string' ? { section: value.section } : {},
+    ...Array.isArray(trail) && trail.length <= 10_000 && trail.every(key => typeof key === 'string') ? { trail: trail as string[] } : {},
+  }
+}