acrylblends 1.1.0 → 1.3.0

package/plugins/acryl-door/src/page/protocol.ts

@@ -60,6 +60,8 @@ export interface UiNode {
   readonly value?: string
   /** Heading level, when it is a heading. */
   readonly level?: number
+  /** The choices of a select, as `act select` takes them, when it is not sensitive. */
+  readonly options?: readonly string[]
 }
 
 export interface UiSnapshot {
@@ -88,6 +90,8 @@ export interface UiActionResult {
   readonly ok: true
   readonly target?: { readonly role: string; readonly name: string }
   readonly detail?: string
+  /** The act started a navigation (a link, a form that submits): this page is going away, and the Host waits for the next one. */
+  readonly leaving?: true
 }
 
 export type UiResult = UiSnapshot | UiActionResult

package/plugins/acryl-door/src/page/snapshot-text.ts

@@ -11,7 +11,8 @@ export function renderSnapshot(snapshot: UiSnapshot, more: (cursor: number) => s
     const level = node.level === undefined ? '' : ` level=${String(node.level)}`
     const states = node.states.length === 0 ? '' : ` [${node.states.join(', ')}]`
     const value = node.value === undefined ? '' : ` value=${JSON.stringify(node.value)}`
-    return `${'  '.repeat(Math.min(node.depth, 8))}- ${node.role}${node.name === '' ? '' : ` ${JSON.stringify(node.name)}`}${level}${states}${value} [ref=${node.ref}]`
+    const options = node.options === undefined ? '' : ` options=${JSON.stringify(node.options)}`
+    return `${'  '.repeat(Math.min(node.depth, 8))}- ${node.role}${node.name === '' ? '' : ` ${JSON.stringify(node.name)}`}${level}${states}${value}${options} [ref=${node.ref}]`
   })
   const rest = snapshot.nextCursor === undefined ? '' : `\n(${String(snapshot.total - snapshot.nextCursor)} more elements; ${more(snapshot.nextCursor)})`
   return `Page: ${snapshot.title || '(untitled)'}\nSnapshot ${String(snapshot.generation)}, ${String(snapshot.nodes.length)} of ${String(snapshot.total)} elements:\n${lines.join('\n')}${rest}`

package/plugins/acryl-node-server/src/adapter/listener.ts

@@ -14,6 +14,7 @@ import {
 } from './request.ts'
 import { defaultContentType, cacheKey, Response as LightweightResponse } from './response.ts'
 import type { InternalCache } from './response.ts'
+import { RAW_RESPONSE_HANDLED } from './raw.ts'
 import type { CustomErrorHandler, FetchCallback, HttpBindings } from './types.ts'
 import {
   readWithoutBlocking,
@@ -500,6 +501,9 @@ export const getRequestListener = (
       res = fetchCallback(req, { incoming, outgoing } as HttpBindings) as
         | Response
         | Promise<Response>
+        | typeof RAW_RESPONSE_HANDLED
+      // A raw handler (not a `Response`) owns the node response: it has written (or is writing) it, so the adapter writes nothing.
+      if (res === RAW_RESPONSE_HANDLED) return
       if (!isPromise(res) && isImmediateCacheableResponse(res)) {
         // Synchronous cacheable response — no close listener needed.
         // No I/O events can fire between fetchCallback returning and responseViaCache

package/plugins/acryl-node-server/src/adapter/raw.ts

@@ -0,0 +1,18 @@
+/**
+ * Raw HTTP handlers, outside the router: a host that must serve another server's node `(req, res)` handlers (a DSH compatibility port, the
+ * desktop shell's own endpoints) registers by path instead of building an `Acryl`. The adapter hands a matched request to the handler with the
+ * real `IncomingMessage`/`ServerResponse` and writes nothing itself; `RAW_RESPONSE_HANDLED` is how the fetch callback tells it so.
+ *
+ * Upgrades work the same way at the socket level: a registered path is claimed before the router's WebSocket handling, and the adapter's
+ * WebSocket setup leaves a request marked with `RAW_UPGRADE_HANDLED` alone.
+ */
+import type { IncomingMessage } from 'node:http'
+
+/** Returned by a raw-aware fetch callback: the node response is already owned, do not write. */
+export const RAW_RESPONSE_HANDLED: unique symbol = Symbol.for('acryl-node-server.raw-response')
+
+/** Set on an upgrade request a raw handler took over; the adapter's WebSocket setup skips it. */
+export const RAW_UPGRADE_HANDLED: unique symbol = Symbol.for('acryl-node-server.raw-upgrade')
+
+/** An upgrade request a raw handler took over. */
+export type RawUpgradeRequest = IncomingMessage & { [RAW_UPGRADE_HANDLED]?: true }

package/plugins/acryl-node-server/src/adapter/websocket.ts

@@ -3,6 +3,7 @@ import { defineWebSocketHelper } from 'acryl-router/helpers'
 import type { IncomingMessage } from 'node:http'
 import { STATUS_CODES } from 'node:http'
 import type { Duplex } from 'node:stream'
+import { RAW_UPGRADE_HANDLED, type RawUpgradeRequest } from './raw.ts'
 import type { FetchCallback } from './types.ts'
 import type { WebSocketData, WebSocketLike, WebSocketServerLike } from './websocket-types.ts'
 
@@ -144,6 +145,8 @@ const appendResponseHeaders = (headers: string[], responseHeaders?: Headers) =>
 }
 
 const rejectUpgradeRequest = (socket: Duplex, status: number, responseHeaders?: Headers) => {
+  // The socket already has its answer (a provider transition can route one upgrade to two handlers for a moment): never write a second one.
+  if (socket.destroyed || socket.writableEnded) return
   const responseLines = ['Connection: close', 'Content-Length: 0']
   appendResponseHeaders(responseLines, responseHeaders)
 
@@ -181,8 +184,13 @@ export const setupWebSocket = (options: {
   server: UpgradeSource
   fetchCallback: FetchCallback
   wss: WebSocketServerLike
+  /**
+   * Leave a request alone when a raw upgrade handler claimed it. Set by a transport that shares its upgrade source with raw claims (the node
+   * server's HTTP server); a hub fed by its own emitter (the Web adapter) must still answer its own upgrades, which arrive through a raw claim.
+   */
+  skipWhenRawUpgrade?: boolean
 }): void => {
-  const { server, fetchCallback, wss } = options
+  const { server, fetchCallback, wss, skipWhenRawUpgrade = false } = options
 
   const waiterMap = new Map<
     IncomingMessage,
@@ -216,9 +224,11 @@ export const setupWebSocket = (options: {
   }
 
   server.on('upgrade', async (request, socket: Duplex, head) => {
+    // A raw upgrade handler claimed this path before the WebSocket setup ran: the socket is (or will be) its own.
+    if (skipWhenRawUpgrade && (request as RawUpgradeRequest)[RAW_UPGRADE_HANDLED] === true) return
     if (request.headers.upgrade?.toLowerCase() !== 'websocket') {
-      // Nobody else listens: an upgrade to another protocol is answered, not left hanging.
-      if (server.listenerCount('upgrade') === 1) rejectUpgradeRequest(socket, 400)
+      // An upgrade to another protocol is answered, not left hanging (the transport's raw listener flags the ones it already answered).
+      rejectUpgradeRequest(socket, 400)
       return
     }
 
@@ -241,9 +251,7 @@ export const setupWebSocket = (options: {
         responseHeaders = response.headers
       }
     } catch {
-      if (server.listenerCount('upgrade') === 1) {
-        rejectUpgradeRequest(socket, 500)
-      }
+      rejectUpgradeRequest(socket, 500)
       return
     }
 
@@ -251,9 +259,7 @@ export const setupWebSocket = (options: {
 
     if (!waiter || waiter.connectionSymbol !== env[CONNECTION_SYMBOL_KEY]) {
       rejectWaiter(request)
-      if (server.listenerCount('upgrade') === 1) {
-        rejectUpgradeRequest(socket, status, responseHeaders)
-      }
+      rejectUpgradeRequest(socket, status, responseHeaders)
       return
     }
 

package/plugins/acryl-node-server/src/client-modules.ts

@@ -38,6 +38,12 @@ const DEFAULT_CACHE_BYTES = 16 * 1024 * 1024
 export interface ClientModulesOptions {
   /** The folder of client modules, absolute or relative to the working directory. */
   readonly root: string
+  /**
+   * The URL prefix the app is mounted at, when the caller knows it. A host can compose app plugins under its own router, and under a
+   * Host whose router is a different copy of this package the request's match result is not visible here, so `basePath(c)` throws; the
+   * explicit prefix is then the only reliable way to know where the mount starts. Omitted, the router's `basePath(c)` is used.
+   */
+  readonly mount?: string | undefined
   /** The folder {@link buildClientModules} wrote; with `NODE_ENV=production` it is served instead of compiling, which needs no `typescript`. */
   readonly compiled?: string | undefined
   /** At most this many bytes of compiled modules are kept in memory (least recently served first out); 16 MiB when not given. */
@@ -204,7 +210,7 @@ export function clientModules(options: ClientModulesOptions): Acryl {
 
   const app = new Acryl()
   app.get('/*', (c) => {
-    const requestPath = c.req.path.slice(basePath(c).length)
+    const requestPath = c.req.path.slice(options.mount === undefined ? basePath(c).length : options.mount.length)
     const runtime = /^\/@acrylblends\/([a-z-]+\.js)$/u.exec(requestPath)?.[1]
     const send = (code: string, etag: string): Response => {
       if (c.req.header('if-none-match') === etag) return c.body(null, 304, { etag, 'cache-control': 'no-cache' })

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

@@ -6,16 +6,19 @@
  * One adapter per runtime: a plugin keeps asking `ctx.inject(['routerHttp'], ...)` for a mount, which simply never fires here, because this
  * adapter serves the whole router.
  *
- * A configured port that is taken is followed by the next free one, at most `scan` further ports; port 0 lets the system choose. Disposal ends
- * open streams, closes every connection and returns once the port is free.
+ * A configured port that is taken is followed by the next free one, at most `scan` further ports; port 0 lets the system choose. A port a
+ * browser refuses to open (`RESTRICTED_PORTS`) is skipped like a taken one. Disposal ends open streams, closes every connection and returns
+ * once the port is free.
  */
 
-import type { Server } from 'node:http'
+import type { IncomingMessage, Server, ServerResponse } from 'node:http'
 import type { AddressInfo } from 'node:net'
+import type { Duplex } from 'node:stream'
 import { Context, Service } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
-import type {} from 'acryl-router'
+import type { ConnectionInfo, Router } from 'acryl-router'
 import { Request as AdapterRequest } from './adapter/request.ts'
+import { RAW_RESPONSE_HANDLED, RAW_UPGRADE_HANDLED, type RawUpgradeRequest } from './adapter/raw.ts'
 import { createAdaptorServer } from './adapter/server.ts'
 import { UpgradeHub, type UpgradeHubOptions } from './upgrade-hub.ts'
 import type { UpgradeWebSocket } from 'acryl-router/helpers'
@@ -30,6 +33,37 @@ export { UpgradeEmitter, UpgradeHub, type UpgradeHubOptions, type UpgradeRouter
 export const name = 'acryl-node-server'
 export const inject = ['router']
 
+/** A raw node handler: the request and response are the platform's, and the adapter writes nothing for them. */
+export interface RawRoute {
+  readonly kind: 'prefix' | 'exact'
+  readonly path: string
+  readonly handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+}
+
+/** A raw upgrade handler: the socket is the handler's once the path matches; the router never sees the upgrade. */
+export interface RawUpgradeRoute {
+  readonly path: string
+  readonly handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>
+}
+
+/**
+ * Answer a request before raw routes and the router, or pass it on with `undefined`. The callback runs synchronously, so a request no gate answers still
+ * reaches a raw route's sentinel synchronously; a gate that needs the router (a host keeping an app's URLs in scope under a prefix, the ACRYL frame's canvas)
+ * returns its promise, and the adapter handles that like the router's own answer. `connection` carries the socket facts, which a router mount needs to check
+ * the peer and the real port.
+ */
+export type RequestGate = (request: Request, connection: ConnectionInfo) => Response | Promise<Response> | undefined
+
+/** The pathname of a request target, for raw matching: a malformed one matches nothing (`'/'` matches only itself). */
+function pathnameOf(target: string | undefined): string {
+  if (target === undefined) return '/'
+  try {
+    return new URL(target, 'http://node-server.invalid').pathname
+  } catch {
+    return '/'
+  }
+}
+
 export interface Config {
   hostname: string
   port: number
@@ -41,8 +75,8 @@ export interface Config {
 /** Every field has a default, so a caller passes only what it changes: `ctx.plugin(plugin, { ... })` takes the partial shape. */
 export const Config: z<Partial<Config>, Config> = z.object({
   hostname: z.string().default('127.0.0.1').description('Address to bind. Loopback by default; binding elsewhere exposes the app to the network.'),
-  port: z.number().min(0).max(65535).default(0).description('Port to listen on; 0 lets the system choose. A taken port is followed by the next free one.'),
-  scan: z.number().min(0).default(20).description('How many further ports to try when the configured one is taken.'),
+  port: z.number().min(0).max(65535).default(0).description('Port to listen on; 0 lets the system choose. A taken port, or one a browser refuses, is followed by the next usable one.'),
+  scan: z.number().min(0).default(20).description('How many further ports to try when the configured one is taken or a browser refuses it.'),
   websocket: z
     .object({
       maxPayload: z.number().min(1).default(1024 * 1024).description('The largest WebSocket frame accepted, in bytes; a bigger one closes the socket with 1009.'),
@@ -58,31 +92,249 @@ declare module '@deepseek-ai/cordis' {
   }
 }
 
+/**
+ * Milliseconds a request already in flight, or an upgraded socket's own owner, may finish once the server stops taking new work. A save during a
+ * restart must not be cut; a stream that never ends must not hold the stop open.
+ */
+export const STOP_GRACE_MS = 2_000
+
 export class NodeServer extends Service {
   readonly hostname: string
   readonly config: Config
   private readonly server: Server
+  private readonly router: Router
   private hub: UpgradeHub | undefined
   private bound = 0
+  /** The one stop this server runs: a second call (the disposer after an explicit stop) waits on the same promise. */
+  private stopping: Promise<void> | undefined
+  /** Requests whose response has not finished yet: the stop waits for them before their sockets are cut. */
+  private active = 0
+  /** Upgraded sockets this server handed out (WebSockets): neither close() nor closeAllConnections() reaches them, so the stop tracks them itself. */
+  private readonly upgraded = new Set<Duplex>()
+  /** Raw routes registered by the host's compatibility layer (see {@link registerRaw}). */
+  private readonly rawExact = new Map<string, RawRoute['handler']>()
+  private readonly rawPrefix = new Map<string, RawRoute['handler']>()
+  private readonly rawUpgrades = new Map<string, RawUpgradeRoute['handler']>()
+  /** Gates registered by a host that maps an app's URLs (see {@link NodeServer.gate}); they run in the order they were added. */
+  private readonly gates: RequestGate[] = []
+  /** One raw dispatch per upgrade request: a second listener (or a re-added one) must never emit the same request again. */
+  private readonly rawUpgradeSeen = new WeakSet<IncomingMessage>()
 
   constructor(ctx: Context, config: Config) {
     super(ctx, 'nodeServer')
     this.config = config
     this.hostname = config.hostname
     const router = ctx.router
+    this.router = router
     // The handler sees the router's bindings (`c.env.connection`), not the raw `incoming`/`outgoing` pair. The global `Request` and
     // `Response` stay the platform's, because this adapter shares its process with the rest of the app; so the adapter's lightweight
     // request is made a real one (its signal still aborts when the client goes away) before the router re-creates it with its own signal.
     this.server = createAdaptorServer({
-      fetch: (request, { incoming }) => router.fetch(new AdapterRequest(request), { remoteAddress: incoming.socket.remoteAddress, localPort: incoming.socket.localPort }),
+      fetch: (request, bindings) => {
+        const { incoming, outgoing } = bindings as { incoming: IncomingMessage; outgoing: ServerResponse }
+        // One count of a request whose response has not finished: the stop (see the disposer below) lets these finish before their sockets are cut,
+        // which is what keeps a save made while the app restarts from being lost.
+        this.active += 1
+        let finished = false
+        const settle = (): void => {
+          if (finished) return
+          finished = true
+          this.active -= 1
+        }
+        outgoing.once('finish', settle)
+        outgoing.once('close', settle)
+        // A raw route owns the node response: start it and return the sentinel synchronously, so the adapter (which checks the
+        // sentinel before treating the result as a promise) writes nothing. The handler's own failure becomes a 500 here.
+        // An upgrade that reaches the HTTP fetch path has no WebSocket listener to claim it (a provider transition, or no hub at all): refuse it
+        // here, before any HTTP route (a raw prefix would otherwise answer it as a normal request), so it is never answered twice.
+        if (incoming.headers.upgrade !== undefined) {
+          const websocket = incoming.headers.upgrade.toLowerCase() === 'websocket'
+          return new Response('', {
+            status: websocket ? 503 : 400,
+            headers: { connection: 'close' },
+          })
+        }
+        // A gate decides before raw routes and the router (a host that keeps an app's URLs under a prefix answers a navigation the frame's root would
+        // otherwise claim, and sends the app's own sub-resources to the router so a raw prefix cannot answer for the app): its answer is the request's.
+        if (this.gates.length > 0) {
+          const requestLike = request as unknown as Request
+          const connection: ConnectionInfo = { remoteAddress: incoming.socket.remoteAddress, localPort: incoming.socket.localPort }
+          for (const gate of this.gates) {
+            const answer = gate(requestLike, connection)
+            if (answer !== undefined) return answer
+          }
+        }
+        const raw = this.rawFor(incoming)
+        if (raw !== undefined) {
+          void (async () => {
+            try {
+              await raw(incoming, outgoing)
+            } catch {
+              if (!outgoing.headersSent) {
+                outgoing.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' })
+                outgoing.end('internal error')
+              } else outgoing.destroy()
+            }
+          })()
+          return RAW_RESPONSE_HANDLED
+        }
+        return router.fetch(new AdapterRequest(request), { remoteAddress: incoming.socket.remoteAddress, localPort: incoming.socket.localPort })
+      },
       hostname: config.hostname,
       overrideGlobalObjects: false,
     }) as Server
-    ctx.effect(() => async () => {
-      await this.hub?.close()
+    // ONE raw upgrade listener for the server's lifetime, ahead of the router's WebSocket setups. It consults the registry, so a claim added or
+    // removed never adds or removes a listener; a request it dispatched once is never dispatched again (a guard beside the single ownership).
+    this.server.on('upgrade', (request: IncomingMessage, socket: Duplex, head: Buffer) => {
+      if (this.rawUpgradeSeen.has(request)) return
+      // Upgraded sockets leave the HTTP connection lifecycle: close() and closeAllConnections() never reach them (measured, not assumed), so the stop
+      // tracks them and waits for their owner's close frame before cutting what is left.
+      this.upgraded.add(socket)
+      socket.once('close', () => { this.upgraded.delete(socket) })
+      // Node drops the HTTP server's own error listener when it hands a socket to 'upgrade', and the route may still be deciding (a check that
+      // reads a store) when the client resets: without a listener of its own, that ECONNRESET would throw and stop the whole server. The socket
+      // is simply gone; its owner, if it has one yet, sees the close.
+      socket.on('error', () => { socket.destroy() })
+      const websocket = request.headers.upgrade?.toLowerCase() === 'websocket'
+      const handler = this.rawUpgrades.get(pathnameOf(request.url))
+      // A raw claim owns its path. A WebSocket upgrade nobody claimed is left to the router's hub when one is attached; with no hub, or for a
+      // protocol this server does not speak, the refusal is written here, cleanly, and never by a second handler.
+      if (handler === undefined) {
+        if (!websocket || this.hub !== undefined) return
+        if (socket.destroyed || socket.writableEnded) return
+        ;(request as RawUpgradeRequest)[RAW_UPGRADE_HANDLED] = true
+        socket.end('HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\nContent-Length: 0\r\n\r\n')
+        return
+      }
+      if (!websocket) {
+        if (socket.destroyed || socket.writableEnded) return
+        ;(request as RawUpgradeRequest)[RAW_UPGRADE_HANDLED] = true
+        socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 0\r\n\r\n')
+        return
+      }
+      this.rawUpgradeSeen.add(request)
+      ;(request as RawUpgradeRequest)[RAW_UPGRADE_HANDLED] = true
+      Promise.resolve(handler(request, socket, head)).catch(() => socket.destroy())
+    })
+    ctx.effect(() => () => this.stop(), 'acryl-node-server: close listener and open connections')
+  }
+
+  /**
+   * Stop serving, gracefully, and resolve once the port is free: no new connections; requests already in flight may finish (a stream that never ends is
+   * cut) within {@link STOP_GRACE_MS}; each upgraded socket's owner closes it with a close frame first, and what is left is destroyed. Idempotent - the
+   * disposer calls it.
+   *
+   * Calling this BEFORE the rest of the app is disposed is what makes the grace count: the router has its own disposal, and it aborts in-flight requests
+   * and ends their bodies by design, concurrently with every other disposer (Cordis runs them together). A launcher that disposes the context directly
+   * therefore cuts the request this drains; a launcher that stops the server first lets it answer, then disposes.
+   */
+  stop(): Promise<void> {
+    this.stopping ??= this.closeGracefully()
+    return this.stopping
+  }
+
+  private async closeGracefully(): Promise<void> {
+    // The hub's close runs beside the request grace rather than before it: the stop takes one grace, not two.
+    const upgrades = this.hub?.close()
+    if (!this.server.listening) {
+      await upgrades
+      return
+    }
+    const stopped = new Promise<void>(resolve => { this.server.close(() => { resolve() }) })
+    this.server.closeIdleConnections()
+    const settled = await this.settleStop(STOP_GRACE_MS)
+    // A response that finished exactly at the grace's end is written but not yet delivered: end its socket gracefully (a FIN behind the buffered body)
+    // instead of destroying it, which would answer the client with a reset and an empty body. A little flush window, then force what is left.
+    this.server.closeIdleConnections()
+    const drained = settled
+      ? await Promise.race([
+          stopped.then(() => true),
+          new Promise<boolean>(resolve => { setTimeout(() => { resolve(false) }, 300) }),
+        ])
+      : false
+    if (!drained) {
       this.server.closeAllConnections()
-      if (this.server.listening) await new Promise<void>(resolve => { this.server.close(() => { resolve() }) })
-    }, 'acryl-node-server: close listener and open connections')
+      // Upgraded sockets that outlived their owner's close: destroy them, or the server's own close never finishes.
+      for (const socket of this.upgraded) socket.destroy()
+      this.upgraded.clear()
+    }
+    await Promise.all([upgrades, stopped])
+  }
+
+  /**
+   * Wait, bounded, until no request is in flight and no upgraded socket is left; true when both reached zero inside the bound. Every pass sweeps idle
+   * keep-alive sockets again: the single sweep `close()` does misses one that becomes idle after its request finished, and such a socket would otherwise
+   * hold the stop to its deadline.
+   */
+  private async settleStop(ms: number): Promise<boolean> {
+    const deadline = Date.now() + ms
+    while (Date.now() < deadline) {
+      if (this.active === 0 && this.upgraded.size === 0) return true
+      this.server.closeIdleConnections()
+      await new Promise(resolve => setTimeout(resolve, 25))
+    }
+    return this.active === 0 && this.upgraded.size === 0
+  }
+
+  /**
+   * Serve a raw node handler at `path`, beside the router: `exact` matches the pathname only, `prefix` the path and everything below it. The
+   * handler gets the platform's `IncomingMessage`/`ServerResponse` and owns the response; the router is not run for it. A path already served
+   * throws. The returned remover restores the path (the server itself goes on serving the rest).
+   */
+  registerRaw(route: RawRoute): () => void {
+    const table = route.kind === 'exact' ? this.rawExact : this.rawPrefix
+    if (table.has(route.path)) throw new Error(`acryl-node-server: ${route.path} is already served`)
+    table.set(route.path, route.handler)
+    return () => {
+      if (table.get(route.path) === route.handler) table.delete(route.path)
+    }
+  }
+
+  /**
+   * Answer matching requests before raw routes and the router, so a host can keep an app's URLs in scope under a prefix (the frame's canvas). A gate runs
+   * synchronously and can answer with a promise (see {@link RequestGate}); gates run in the order they were added, and the returned remover takes this one back.
+   */
+  gate(handler: RequestGate): () => void {
+    this.gates.push(handler)
+    return () => {
+      const at = this.gates.indexOf(handler)
+      if (at !== -1) this.gates.splice(at, 1)
+    }
+  }
+
+  /**
+   * A gate's asynchronous answer: run the request it was given through the router, in the adapter's request form (a gate never makes one itself), with the
+   * socket facts. The raw routes do not run for that request.
+   */
+  throughRouter(request: Request, connection: ConnectionInfo = {}): Promise<Response> {
+    return this.router.fetch(new AdapterRequest(request), connection)
+  }
+
+  /**
+   * Claim an upgrade path for a raw node handler: the handler receives `(req, socket, head)` and from then on owns the socket. The router's
+   * WebSocket handling never sees a claimed upgrade. A path already claimed throws; the remover releases the claim. The transport's one raw
+   * listener exists for the server's whole lifetime and consults this registry, so claims coming and going never add or remove a listener.
+   */
+  registerRawUpgrade(route: RawUpgradeRoute): () => void {
+    if (this.rawUpgrades.has(route.path))
+      throw new Error(`acryl-node-server: the upgrade path ${route.path} is already claimed`)
+    this.rawUpgrades.set(route.path, route.handler)
+    return () => {
+      if (this.rawUpgrades.get(route.path) !== route.handler) return
+      this.rawUpgrades.delete(route.path)
+    }
+  }
+
+  /** The raw handler for a request: an exact path first, then the longest matching prefix. */
+  private rawFor(incoming: IncomingMessage): RawRoute['handler'] | undefined {
+    const path = pathnameOf(incoming.url)
+    const exact = this.rawExact.get(path)
+    if (exact !== undefined) return exact
+    let best: { length: number; handler: RawRoute['handler'] } | undefined
+    for (const [prefix, handler] of this.rawPrefix)
+      if ((path === prefix || path.startsWith(`${prefix}/`)) && (best === undefined || prefix.length > best.length))
+        best = { length: prefix.length, handler }
+    return best?.handler
   }
 
   /**
@@ -93,11 +345,16 @@ export class NodeServer extends Service {
   upgrades(): UpgradeWebSocket<WebSocketLike> {
     if (!this.hub) {
       this.hub = new UpgradeHub(this.config.websocket)
-      this.hub.attach(this.server, this.ctx.router)
+      this.hub.attach(this.server, this.ctx.router, { skipWhenRawUpgrade: true })
     }
     return this.hub.upgradeWebSocketFor(this.ctx)
   }
 
+  /** How many `upgrade` listeners the transport holds (raw plus router setups); a test asserts it does not grow across claim changes. */
+  get upgradeListenerCount(): number {
+    return this.server.listenerCount('upgrade')
+  }
+
   /** How many WebSocket connections are open now. */
   get sockets(): number {
     return this.hub?.size ?? 0
@@ -113,11 +370,11 @@ export class NodeServer extends Service {
     return `http://${this.hostname.includes(':') ? `[${this.hostname}]` : this.hostname}:${String(this.bound)}`
   }
 
-  /** Bind, scanning past taken ports. */
+  /** Bind, scanning past taken ports and past the ports a browser refuses. */
   async listen(): Promise<void> {
     const { port, scan, hostname } = this.config
-    const last = port === 0 ? 0 : Math.min(65535, port + scan)
-    for (let candidate = port; candidate <= last; candidate += 1) {
+    const last = port === 0 ? 0 : Math.min(65_535, port + scan)
+    for (const candidate of portCandidates(port, scan)) {
       try {
         await new Promise<void>((resolve, reject) => {
           const onError = (error: Error): void => { reject(error) }
@@ -130,8 +387,39 @@ export class NodeServer extends Service {
         if (!isPortUnavailable(error)) throw error
       }
     }
-    throw new Error(`acryl-node-server: no free port from ${String(port)} to ${String(last)} on ${hostname}`)
+    throw new Error(`acryl-node-server: no usable port from ${String(port)} to ${String(last)} on ${hostname}: each is taken, or one a browser refuses`)
+  }
+}
+
+/**
+ * The ports every Fetch client refuses to connect to: the Fetch standard's bad ports (https://fetch.spec.whatwg.org/#port-blocking). Chromium
+ * refuses a page on one (ERR_UNSAFE_PORT) and Node's fetch answers "bad port"; the list below is the one Node 24 reports, probed port by port
+ * on 2026-11-03 (82 ports, 1 to 10080). An app's stable port is hashed into 3100..3999, and 3659 is on the list: without this rule one app in
+ * 900 would come up on an address no browser may open, which the frame gate caught that day (verify-frame-token was refused at 3659).
+ */
+export const RESTRICTED_PORTS: ReadonlySet<number> = new Set([
+  1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, 95, 101, 102, 103, 104,
+  109, 110, 111, 113, 115, 117, 119, 123, 135, 137, 139, 143, 161, 179, 389, 427, 465, 512, 513, 514, 515,
+  526, 530, 531, 532, 540, 548, 554, 556, 563, 587, 601, 636, 989, 990, 993, 995, 1719, 1720, 1723, 2049,
+  3659, 4045, 4190, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668, 6669, 6679, 6697, 10080,
+])
+
+/** Whether a browser refuses to open this port. */
+export function isRestrictedPort(port: number): boolean {
+  return RESTRICTED_PORTS.has(port)
+}
+
+/**
+ * The ports `listen` may try, in order: `port` with at most `scan` further ones, without the ports a browser refuses. Port 0 stays alone: the
+ * system chooses it, and the ports it hands out are above the restricted range.
+ */
+export function portCandidates(port: number, scan: number): number[] {
+  const last = port === 0 ? 0 : Math.min(65_535, port + scan)
+  const candidates: number[] = []
+  for (let candidate = port; candidate <= last; candidate += 1) {
+    if (!isRestrictedPort(candidate)) candidates.push(candidate)
   }
+  return candidates
 }
 
 /**

package/plugins/acryl-node-server/src/upgrade-hub.ts

@@ -83,12 +83,12 @@ export class UpgradeHub {
    * Accept upgrades from `source` and answer them with `router`: the request runs through the router's middleware with the socket's peer address and local port as connection
    * facts (so the same loopback, origin and host checks work), and the upgrade bindings travel in `c.env` for `upgradeWebSocket`.
    */
-  attach(source: UpgradeSource, router: UpgradeRouter): void {
+  attach(source: UpgradeSource, router: UpgradeRouter, options: { skipWhenRawUpgrade?: boolean } = {}): void {
     const fetchCallback: FetchCallback = (request, env) => {
       const { incoming } = env as { incoming: { socket: { remoteAddress?: string; localPort?: number } } }
       return router.fetch(request, { remoteAddress: incoming.socket.remoteAddress, localPort: incoming.socket.localPort }, env)
     }
-    setupWebSocket({ server: source, fetchCallback, wss: this.server })
+    setupWebSocket({ server: source, fetchCallback, wss: this.server, ...options })
   }
 
   /** How many sockets are open. */

package/plugins/acryl-page/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "acryl-page",
+  "description": "The page of a framework-hosted app: our own minimal index (the ACRYL frame's document, not DSH's), its index taps applied per request, and the built client assets the client runtime boots from. Ours, served by acryl-web-server on the framework's node server.",
+  "requires": ["acryl-web-server"],
+  "inject": ["webServer"],
+  "provides": [],
+  "dependencies": {},
+  "mount": "mount it after acryl-web-server and the client rows: it serves '/' and '/assets/*' and applies the webServer index taps (the client modules' __DSH_BOOT__ and registration scripts) to its own document",
+  "entries": {
+    "": "src/index.ts"
+  }
+}