acrylblends 1.1.0 → 1.3.0

package/plugins/acryl-page/src/index.ts

@@ -0,0 +1,163 @@
+/**
+ * The page of a framework-hosted app. The document is ours: a minimal index (doctype, title, the root div) with the index taps applied per request,
+ * which is where the client-module row inserts `window.__DSH_BOOT__` and its registration scripts. DSH's built frontend is used only as the client
+ * runtime library the frame's client plugins load through: its own index is read for the entry script and stylesheet tags it genuinely needs, and its
+ * `dist/assets/` files are served beside our document. No DSH web server, web runtime or web-startup row is involved.
+ */
+import { readFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, extname, join, normalize, sep } from 'node:path'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from 'acryl-web-server'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-page'
+
+/** The page is served through the host's webServer port. */
+export const inject = ['webServer']
+
+export interface Config {
+  /** The document's title. */
+  title: string
+}
+
+const CONTENT_TYPES: Readonly<Record<string, string>> = {
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.webmanifest': 'application/manifest+json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.wasm': 'application/wasm',
+}
+
+/** The frontend package's `dist` directory: anchored on its manifest, as DSH itself does. */
+export function frontendDist(): string {
+  const require = createRequire(import.meta.url)
+  return join(dirname(require.resolve('@deepseek-ai/dsh-web-frontend/package.json')), 'dist')
+}
+
+/** The tags the built client runtime genuinely needs from the frontend's own index: the entry script, its preloads and its stylesheets. */
+export function clientAssetTags(indexHtml: string): string {
+  const tags = [...indexHtml.matchAll(/<(?:script|link)\b[^>]*>/gu)]
+    .map((match) => match[0])
+    .filter(
+      (tag) =>
+        /^<script\b[^>]*\bsrc=/u.test(tag) ||
+        /^<link\b[^>]*\brel="(?:stylesheet|modulepreload)"/u.test(tag),
+    )
+  // A copied `<script src>` without its closing tag turns every tag after it (the stylesheet links) into its text: DSH's component stylesheet then never
+  // loads, and the frame draws its dialogs, buttons and inputs with browser defaults instead of the product's. The frontend's own script tags are empty,
+  // so the closing tag is this side's to add.
+  return tags.map((tag) => (tag.startsWith('<script') ? `${tag}</script>` : tag)).join('\n    ')
+}
+
+/** Our document: minimal on purpose; the frame renders into `#root`, and the taps add the boot wire before `</head>`. */
+export function pageDocument(tags: string, title: string, taps: (html: string) => string): string {
+  const document = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${title}</title>
+    ${tags}
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>
+`
+  return taps(document)
+}
+
+/** The slice of the chat driver's connection the page needs: the process-token exchange that sets the browser's session cookie. */
+interface ConnectionPort {
+  /** True when the caller may serve the index; false when it already answered (a token redirect or 401). */
+  authorizeIndex(req: IncomingMessage, res: ServerResponse): boolean
+}
+
+/** Answer with a file under `root`, or 404: a path that escapes `root` and a missing file both 404. */
+async function serveFile(root: string, target: string, response: ServerResponse, method: string): Promise<void> {
+  const path = normalize(join(root, target))
+  if (path !== root && !path.startsWith(root + sep)) {
+    response.writeHead(404).end('not found')
+    return
+  }
+  try {
+    const bytes = await readFile(path)
+    response.writeHead(200, {
+      'content-type': CONTENT_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream',
+      'content-length': String(bytes.byteLength),
+      'cache-control': 'no-cache',
+    })
+    response.end(method === 'HEAD' ? undefined : bytes)
+  } catch {
+    response.writeHead(404).end('not found')
+  }
+}
+
+/** Serve `/` (our document), `/index.html`, the built assets and the root files the index names. */
+export function apply(ctx: Context, config: Partial<Config> = {}): void {
+  const title = config.title ?? 'ACRYL'
+  const dist = frontendDist()
+  const assets = join(dist, 'assets')
+  ctx.webServer.register({
+    kind: 'exact',
+    path: '/',
+    handler: async (req, res) => {
+      // The chat's remote RPC is authenticated by the connection's process token: the page's root request is where the token is exchanged
+      // for the session cookie. A composition without the driver has no connection and serves the page directly.
+      const connection = (ctx as unknown as { get(name: string): unknown }).get('connection') as ConnectionPort | undefined
+      if (connection !== undefined && !connection.authorizeIndex(req, res)) return
+      const index = await readFile(join(dist, 'index.html'), 'utf8')
+      const document = pageDocument(clientAssetTags(index), title, (html) => ctx.webServer.index(html))
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' })
+      res.end(req.method === 'HEAD' ? undefined : document)
+    },
+  })
+  ctx.webServer.register({
+    kind: 'exact',
+    path: '/index.html',
+    handler: async (req, res) => {
+      const index = await readFile(join(dist, 'index.html'), 'utf8')
+      const document = pageDocument(clientAssetTags(index), title, (html) => ctx.webServer.index(html))
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' })
+      res.end(req.method === 'HEAD' ? undefined : document)
+    },
+  })
+  ctx.webServer.register({
+    kind: 'prefix',
+    path: '/assets',
+    handler: async (req: IncomingMessage, res: ServerResponse) => {
+      const pathname = new URL(req.url ?? '/', 'http://page.invalid').pathname
+      await serveFile(assets, pathname.slice('/assets'.length), res, req.method ?? 'GET')
+    },
+  })
+  // Browsers ask for /favicon.ico unconditionally; the built light icon answers it.
+  ctx.webServer.register({
+    kind: 'exact',
+    path: '/favicon.ico',
+    handler: async (req: IncomingMessage, res: ServerResponse) => {
+      await serveFile(dist, 'favicon.svg', res, req.method ?? 'GET')
+    },
+  })
+  for (const file of ['favicon.svg', 'favicon-dark.svg', 'manifest.webmanifest']) {
+    ctx.webServer.register({
+      kind: 'exact',
+      path: `/${file}`,
+      handler: async (req: IncomingMessage, res: ServerResponse) => {
+        await serveFile(dist, file, res, req.method ?? 'GET')
+      },
+    })
+  }
+}

package/plugins/acryl-router/src/service.ts

@@ -7,6 +7,8 @@
  * response body still streaming and waits for all of it to settle.
  */
 
+import { appendFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { Context, Service } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import type { ConnectionInfo, RouterBindings } from './connection.ts'
@@ -21,6 +23,27 @@ import type { ErrorHandler, H, NotFoundHandler } from './core/types.ts'
 
 const DEFAULT_DISPOSE_GRACE_MS = 2000
 
+/** How long disposal waits for the flights it had to abort after the drain, before it continues without them. */
+const ABORT_SETTLE_MS = 300
+
+/** Set by ACRYL_ROUTER_TRACE=1: append request-signal lifecycle lines to ACRYL_ROUTER_TRACE_FILE (the CI artifact) - diagnostics for the abort-reaches-handler defect. */
+const traceFile = (): string => process.env.ACRYL_ROUTER_TRACE_FILE ?? `${tmpdir()}/acryl-router-trace.log`
+const trace = (line: string): void => {
+  if (process.env.ACRYL_ROUTER_TRACE !== '1') return
+  try { appendFileSync(traceFile(), `${String(Date.now())} [${String(process.pid)}] ${line}\n`) } catch { /* tracing never affects a request */ }
+}
+let flightSeq = 0
+const SIGNAL_TAG = Symbol.for('acryl.router.signalTag')
+const tagOf = (signal: AbortSignal | undefined): string => {
+  if (signal === undefined) return 'none'
+  const tag = (signal as unknown as Record<symbol, unknown>)[SIGNAL_TAG]
+  return typeof tag === 'string' ? tag : 'untagged'
+}
+const tagSignal = (signal: AbortSignal, tag: string): void => {
+  try { (signal as unknown as Record<symbol, unknown>)[SIGNAL_TAG] = tag } catch { /* a frozen signal keeps no tag */ }
+}
+
+
 /** How a trailing slash is read: `strict` keeps `/a` and `/a/` distinct, `ignore` treats them as one path. */
 export type TrailingSlash = 'strict' | 'ignore'
 
@@ -105,6 +128,10 @@ interface RouterState {
 
 interface Flight {
   readonly controller: AbortController
+  /** The request the handlers run on (the caller's request with the flight's signal): held strongly for the flight's lifetime, so its signal cannot be collected under a listener. */
+  readonly inner: Request
+  /** Names the flight in the ACRYL_ROUTER_TRACE diagnostics. */
+  readonly tag: string
   /** How many of each mount's handlers are running for this request right now (a middleware counts until its `next()` returns). */
   readonly running: Map<Mount, number>
   /** The mount whose handler produced the response; its body is that mount's code still running. */
@@ -150,8 +177,8 @@ export class Router extends Service {
     }
     ctx.effect(() => async () => {
       this.state.closing = true
-      await this.end([...this.flights], 'disposal')
-    }, 'acryl-router: abort and settle in-flight requests')
+      await this.drain()
+    }, 'acryl-router: drain in-flight requests, then abort what is left')
   }
 
   /** Registrations currently held (mounts, and the router-wide error and not-found handlers); a leak check for reload tests. */
@@ -168,12 +195,16 @@ export class Router extends Service {
     const mount = this.snapshot(path, app)
     this.state.mounts.add(mount)
     this.state.composed = undefined
-    // Removing a mount ends the requests its code is still serving: their signals abort, a body it produced is cancelled, and the
-    // plugin's unload waits for them (bounded by `disposeGraceMs`), so nothing a plugin started outlives it.
+    // Removing a mount ends the requests its code is still serving: they get the grace to finish first (a save being written when its plugin unloads,
+    // or when the whole app stops and every plugin unloads together, must not be cut), and only then are their signals aborted, their bodies cancelled
+    // and their settle awaited, so nothing a plugin started outlives it by more than that bounded grace.
     const remove = (): Promise<void> => {
       if (!this.state.mounts.delete(mount)) return Promise.resolve()
       this.state.composed = undefined
-      return this.end([...this.flights].filter(flight => (flight.running.get(mount) ?? 0) > 0 || flight.producer === mount), `removing ${path}`)
+      return this.drainFlights(
+        [...this.flights].filter(flight => (flight.running.get(mount) ?? 0) > 0 || flight.producer === mount),
+        `removing ${path}`,
+      )
     }
     // Each route the mount serves is a child effect of it, labeled on its own, so the inspector can report routes without asking the
     // router and no label grows with the size of the app (`ALL` is middleware or `all`). The children hold nothing: the mount does.
@@ -215,6 +246,7 @@ export class Router extends Service {
       const handler: H = async (c, next) => {
         const flight = this.flightOf.get(c.req.raw)
         if (flight === undefined) return inner(c, next)
+        trace(`handler ${flight.tag} requestTag=${tagOf(c.req.raw.signal)} innerTag=${tagOf(flight.inner.signal)} sameSignal=${String(c.req.raw.signal === flight.inner.signal)} aborted=${String(c.req.raw.signal.aborted)}`)
         let calledNext = false
         flight.running.set(mount, (flight.running.get(mount) ?? 0) + 1)
         try {
@@ -234,18 +266,46 @@ export class Router extends Service {
     return mount
   }
 
-  /** Abort `flights`, cut their bodies short and wait for them to settle, at most `disposeGraceMs`. */
-  private async end(flights: readonly Flight[], why: string): Promise<void> {
+  /**
+   * The router's own disposal: let the flights already in flight finish within `disposeGraceMs` - a save being written when the app stops must not be cut
+   * by the router beneath it - then abort what is left and settle it for a moment, so disposal does not wait a second full grace on code that ignores
+   * its abort signal.
+   */
+  private async drain(): Promise<void> {
+    await this.drainFlights([...this.flights], 'disposal')
+  }
+
+  /** The one draining rule: let `flights` finish inside the grace, then abort and settle what is left. */
+  private async drainFlights(flights: readonly Flight[], why: string): Promise<void> {
+    trace(`drain ${why} chosen=[${flights.map(flight => flight.tag).join(', ')}]`)
+    if (flights.length === 0) return
+    if (await this.settledWithin(flights, this.graceMs)) { trace(`drain ${why} settled inside the grace`); return }
+    const left = flights.filter(flight => this.flights.has(flight))
+    trace(`drain ${why} grace over left=[${left.map(flight => flight.tag).join(', ')}]`)
+    if (left.length > 0) await this.end(left, why, ABORT_SETTLE_MS)
+  }
+
+  /** Resolve true when every flight settled inside `ms`, false at the deadline. */
+  private async settledWithin(flights: readonly Flight[], ms: number): Promise<boolean> {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const gaveUp = new Promise<false>(resolve => { timer = setTimeout(() => { resolve(false) }, ms) })
+    const outcome = await Promise.race([Promise.allSettled(flights.map(flight => flight.settled)).then(() => true as const), gaveUp])
+    clearTimeout(timer)
+    return outcome
+  }
+
+  /** Abort `flights`, cut their bodies short and wait for them to settle, at most `settleMs`. */
+  private async end(flights: readonly Flight[], why: string, settleMs: number = this.graceMs): Promise<void> {
     if (flights.length === 0) return
     for (const flight of flights) {
+      trace(`abort ${flight.tag} before=${String(flight.controller.signal.aborted)}`)
       flight.controller.abort()
+      trace(`abort ${flight.tag} after=${String(flight.controller.signal.aborted)} innerAborted=${String(flight.inner.signal.aborted)}`)
+      queueMicrotask(() => { trace(`post-abort ${flight.tag} innerAborted=${String(flight.inner.signal.aborted)}`) })
       flight.endBody()
     }
-    let timer: ReturnType<typeof setTimeout> | undefined
-    const gaveUp = new Promise<'gave-up'>(resolve => { timer = setTimeout(() => { resolve('gave-up') }, this.graceMs) })
-    const outcome = await Promise.race([Promise.allSettled(flights.map(flight => flight.settled)).then(() => 'settled' as const), gaveUp])
-    clearTimeout(timer)
-    if (outcome === 'gave-up') this.ctx.logger.warn(`acryl-router: ${String(flights.length)} request(s) did not finish ${String(this.graceMs)} ms after abort (${why}); continued without them`)
+    if (await this.settledWithin(flights, settleMs)) return
+    this.ctx.logger.warn(`acryl-router: ${String(flights.length)} request(s) did not finish ${String(settleMs)} ms after abort (${why}); continued without them`)
   }
 
   /** Turn errors no mounted app handled into responses. One handler per router; the calling plugin owns it. */
@@ -292,7 +352,7 @@ export class Router extends Service {
    * `bindings` is an object an adapter hands to the handler as `c.env` (an upgrade request's socket hooks, for `upgradeWebSocket`); `connection` is added to it.
    */
   fetch(request: Request, connection: ConnectionInfo = {}, bindings?: object): Promise<Response> {
-    if (this.state.closing) return Promise.resolve(new Response('Service Unavailable', { status: 503 }))
+    if (this.state.closing) return Promise.resolve(new Response('Service Unavailable', { status: 503, headers: { connection: 'close' } }))
     const controller = new AbortController()
     const forward = (): void => controller.abort()
     if (request.signal.aborted) controller.abort()
@@ -308,8 +368,11 @@ export class Router extends Service {
     let bodyDone: Promise<void> = Promise.resolve()
     let endBody = (): void => {}
     let resolveSettled!: (value: Promise<unknown>) => void
-    const flight: Flight = { controller, running: new Map(), producer: undefined, endBody: () => { endBody() }, settled: new Promise(resolve => { resolveSettled = resolve }) }
+    const tag = `f${String(++flightSeq)}`
     const inner = new Request(request, { signal: controller.signal })
+    tagSignal(inner.signal, tag)
+    const flight: Flight = { controller, inner, tag, running: new Map(), producer: undefined, endBody: () => { endBody() }, settled: new Promise(resolve => { resolveSettled = resolve }) }
+    trace(`create ${tag} ${request.method} ${new URL(request.url).pathname}`)
     this.flightOf.set(inner, flight)
     // The caller gets the Response the moment the handler returns it; the flight lasts until its body ends and every waitUntil task settles.
     const response = this.dispatch(inner, env, executionCtx).then(raw => {

package/plugins/acryl-router-http/src/index.ts

@@ -41,6 +41,10 @@ export class RouterHttp extends Service implements RouterHttpService {
   private readonly router: Context['router']
   private readonly web: WebServerPort
   private hub: UpgradeHub | undefined
+  /** One upgrade helper per calling context: a fresh wrapper per call made every service event look like an owner change. */
+  private readonly upgradeHelpers = new WeakMap<object, UpgradeWebSocket>()
+  /** A stable identity for this service instance's hub: a caller that must recognize the same owner across calls keys on this, not on a helper. */
+  private readonly hubIdentity: object = {}
   /** The adapter's own context: the hub lives as long as the adapter, whichever plugin asked for it first (`this.ctx` is the caller's). */
   private readonly home: Context
   private readonly upgradesIn = new UpgradeEmitter()
@@ -99,8 +103,18 @@ export class RouterHttp extends Service implements RouterHttpService {
    * `upgradeWebSocket` for the calling plugin: the sockets its routes accept are closed with 1001 when it unloads. Needs the `ws` package.
    * The route must be on a path the plugin mounted with `upgrade: [path]`.
    */
+  /** Stable for this service's lifetime; a re-provided adapter has a new one, which is how a caller sees a new owner. */
+  hubToken(): object {
+    return this.hubIdentity
+  }
+
   upgrades(): UpgradeWebSocket {
-    return this.ensureHub().upgradeWebSocketFor(this.ctx) as unknown as UpgradeWebSocket
+    const owner = this.ctx
+    const cached = this.upgradeHelpers.get(owner)
+    if (cached !== undefined) return cached
+    const created = this.ensureHub().upgradeWebSocketFor(owner) as unknown as UpgradeWebSocket
+    this.upgradeHelpers.set(owner, created)
+    return created
   }
 
   /** How many WebSocket connections are open now. */

package/plugins/acryl-router-http/src/serve.ts

@@ -6,6 +6,35 @@ export interface FetchRouter {
   fetch(request: Request, connection?: { readonly remoteAddress?: string | undefined, readonly localPort?: number | undefined }): Promise<Response>
 }
 
+/** How long a refusal waits for a request body the handler never read. */
+export const REQUEST_BODY_SETTLE_MS = 1_000
+
+/**
+ * Read and discard a request body the handler left unread (a guard's 403, a 415, a body over its limit), so the client can finish sending and
+ * read the answer. Ending a response while request data is still arriving makes Node close the socket with that data pending, and the peer sees a
+ * reset instead of the answer: reliably on Windows (the workspace git worktree test's read ECONNRESET) and on other systems under load. Bounded:
+ * a client that stops sending waits at most `ms`, then loses the socket as before.
+ */
+export function settleRequestBody(req: IncomingMessage, ms: number = REQUEST_BODY_SETTLE_MS): Promise<void> {
+  if (req.readableEnded || req.destroyed) return Promise.resolve()
+  return new Promise<void>((resolve) => {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const done = (): void => {
+      if (timer !== undefined) clearTimeout(timer)
+      req.off('end', done)
+      req.off('close', done)
+      req.off('error', done)
+      resolve()
+    }
+    timer = setTimeout(done, ms)
+    timer.unref?.()
+    req.once('end', done)
+    req.once('close', done)
+    req.once('error', done)
+    req.resume()
+  })
+}
+
 /**
  * Serve one node request through the router and write the result. The request's abort signal fires when the client
  * disconnects before the response finished; the socket's peer address and local port travel as connection info, never in the request.
@@ -20,5 +49,7 @@ export async function serve(router: FetchRouter, req: IncomingMessage, res: Serv
   } catch {
     response = new Response('Internal Server Error', { status: 500 })
   }
+  // The handler may have answered without reading the body; let the client finish sending before the answer ends the connection.
+  if (method !== 'GET' && method !== 'HEAD') await settleRequestBody(req)
   await sendResponse(res, response, method)
 }

package/plugins/acryl-web-server/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "acryl-web-server",
+  "description": "The webServer port of a framework-hosted app: the node request/upgrade interface DSH's driver rows register on, backed by acryl-node-server's raw routes. Ours, so the chat driver's connection and gateway run on our host without DSH's web server.",
+  "requires": ["acryl-node-server"],
+  "inject": ["nodeServer"],
+  "provides": ["webServer"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "mount": "mount it before the DSH driver rows that inject webServer (the chat connection and its gateway); the framework's page serving applies its index taps",
+  "entries": {
+    "": "src/index.ts"
+  }
+}

package/plugins/acryl-web-server/src/index.ts

@@ -0,0 +1,164 @@
+/**
+ * The `webServer` port for a framework-hosted app. DSH's driver rows (the chat's connection and its remote gateway) register node handlers with
+ * `webServer.register` and `webServer.registerUpgrade`; this plugin serves them on the framework's own node server, so those rows run unchanged
+ * while the HTTP host, the page and the client-module serving stay ours.
+ *
+ * It is the inverse of `acryl-router-http`: there the Host's web server serves a router prefix; here our node server presents the web-server
+ * interface a DSH row expects. The surface is deliberately small: `host` and `port` (what `acryl-web` reads), `register` (exact or prefix),
+ * `registerUpgrade` (one exact path), and the index taps the page serving applies. A row that needs more of DSH's interface gets the extra
+ * method here, named with the row that needs it - so this seam can shrink when a row goes away.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Duplex } from 'node:stream'
+import { Context, Service } from '@deepseek-ai/cordis'
+import type { NodeServer, RawRoute, RawUpgradeRoute } from 'acryl-node-server'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-web-server'
+
+/** Hard requirement: the node server whose raw routes carry these handlers. */
+export const inject = ['nodeServer']
+
+/** A node handler at a path `exact` (the pathname itself) or a `prefix` (the path and everything below it). */
+export interface WebServerRoute {
+  readonly kind: 'prefix' | 'exact'
+  readonly path: string
+  readonly handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+}
+
+/** One exact-path upgrade handler; the socket belongs to the handler once its path matches. */
+export interface WebServerUpgradeRoute {
+  readonly path: string
+  readonly handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>
+}
+
+/** Transforms the served index document, in registration order. */
+export type IndexTap = (html: string) => string
+
+/** What a driver row (or `acryl-web`) reads from `webServer`. */
+export interface WebServerService {
+  /** The address the node server bound. */
+  readonly host: string
+  readonly port: number
+  /** Serve `route` until the returned remover runs or the calling plugin unloads. A path already served throws. */
+  register(route: WebServerRoute): () => void
+  /** Claim `route.path` for an upgrade until the returned remover runs or the calling plugin unloads. */
+  registerUpgrade(route: WebServerUpgradeRoute): () => void
+  /** Transform the served index document while the caller lives; returns its remover. */
+  tapIndex(transform: IndexTap): () => void
+  /** The document with the structured injection rows (the client modules' boot wire) and then every live tap applied. */
+  index(html: string): string
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    webServer: WebServerService
+  }
+}
+
+/** One structured index-injection row (DSH's contract): the kinds the client modules and a door script use. */
+interface IndexRow {
+  readonly kind?: string
+  readonly placement?: 'head' | 'body'
+  readonly text?: string
+  readonly src?: string
+  readonly name?: string
+  readonly value?: unknown
+}
+
+/** The boot-readiness tail the client shell waits for, as DSH renders it. */
+const READY_MARKUP = '<script>(globalThis.__DSH_BOOT_READY__ ??= Promise.withResolvers()).resolve()</script>'
+
+/** A JSON literal safe inside a `<script>`: a sequence like `</script>` must not end it. */
+const scriptJson = (value: unknown): string => JSON.stringify(value).replaceAll('</', '<\\/')
+
+/** Render one row; an unknown kind is skipped rather than emitted as broken markup. */
+function rowMarkup(row: IndexRow): string {
+  if (row.kind === 'script') return `<script>${row.text ?? ''}</script>`
+  if (row.kind === 'script-src') return `<script type="module" crossorigin src="${row.src ?? ''}"></script>`
+  if (row.kind === 'script-preload') return `<link rel="modulepreload" crossorigin href="${row.src ?? ''}" />`
+  if (row.kind === 'global') return `<script>globalThis[${scriptJson(row.name ?? '')}] = ${scriptJson(row.value)}</script>`
+  return ''
+}
+
+/** Insert each group after its opening tag, as DSH's served index does; a document without the tag gets the group first. */
+export function renderIndexRows(html: string, rows: readonly IndexRow[]): string {
+  let head = ''
+  let body = ''
+  for (const row of rows) {
+    const markup = rowMarkup(row)
+    if (markup === '') continue
+    if (row.placement === 'body') body += markup
+    else head += markup
+  }
+  body += READY_MARKUP
+  let document = html
+  const headOpen = /<head(?:\s[^>]*)?>/iu.exec(document)
+  if (head !== '') {
+    const at = headOpen === null ? 0 : headOpen.index + headOpen[0].length
+    document = `${document.slice(0, at)}${head}${document.slice(at)}`
+  }
+  const bodyOpen = /<body(?:\s[^>]*)?>/iu.exec(document)
+  if (body !== '') {
+    const at = bodyOpen === null ? document.length : bodyOpen.index + bodyOpen[0].length
+    document = `${document.slice(0, at)}${body}${document.slice(at)}`
+  }
+  return document
+}
+
+/** The port, backed by `nodeServer`'s raw routes; every registration belongs to the plugin that made it. */
+export class WebServer extends Service implements WebServerService {
+  private readonly taps: IndexTap[] = []
+
+  constructor(ctx: Context) {
+    super(ctx, 'webServer')
+  }
+
+  get host(): string {
+    return this.ctx.nodeServer.hostname
+  }
+
+  get port(): number {
+    return this.ctx.nodeServer.port
+  }
+
+  register(route: WebServerRoute): () => void {
+    const remove = this.ctx.nodeServer.registerRaw(route as RawRoute)
+    this.ctx.effect(() => () => { remove() }, `acryl-web-server: ${route.kind} ${route.path}`)
+    return remove
+  }
+
+  registerUpgrade(route: WebServerUpgradeRoute): () => void {
+    const remove = this.ctx.nodeServer.registerRawUpgrade(route as RawUpgradeRoute)
+    this.ctx.effect(() => () => { remove() }, `acryl-web-server: upgrade ${route.path}`)
+    return remove
+  }
+
+  tapIndex(transform: IndexTap): () => void {
+    this.taps.push(transform)
+    const remove = (): void => {
+      const at = this.taps.indexOf(transform)
+      if (at >= 0) this.taps.splice(at, 1)
+    }
+    this.ctx.effect(() => () => { remove() }, 'acryl-web-server: index tap')
+    return remove
+  }
+
+  index(html: string): string {
+    // The rows are DSH's index-injection contract (`webserver/index-inject`): the client-module row pushes its boot wire there. The rows render
+    // first, the string taps after, the same order DSH's own web server uses.
+    const rows: IndexRow[] = []
+    ;(this.ctx as unknown as { emit(name: string, table: IndexRow[]): void }).emit('webserver/index-inject', rows)
+    let document = renderIndexRows(html, rows)
+    for (const tap of [...this.taps]) document = tap(document)
+    return document
+  }
+}
+
+/** Provide `webServer` on this context; the node server must already be up (the plugin injects it). */
+export function apply(ctx: Context): void {
+  new WebServer(ctx)
+}
+
+/** Re-exported for callers that shape their own routes: the raw types the port is built on. */
+export type { NodeServer, RawRoute, RawUpgradeRoute }