@orkestrel/router 0.0.1 → 0.0.3

package/dist/src/server/index.js

@@ -0,0 +1,207 @@
+import { createAbort } from "@orkestrel/abort";
+import { isRecord } from "@orkestrel/contract";
+//#region src/server/helpers.ts
+/**
+* Determine whether a `node:http` connection socket is TLS-encrypted — the
+* total, never-throwing narrow (AGENTS §14) `buildRequest` uses to pick the
+* derived scheme (`https` vs `http`).
+*
+* @param socket - The connection value to test (typically `message.socket`)
+* @returns `true` when `socket` carries a truthy `encrypted` property (a
+*   `tls.TLSSocket`), `false` for anything else (including `undefined`)
+*
+* @example
+* ```ts
+* import { isEncryptedSocket } from '@src/server'
+*
+* isEncryptedSocket({ encrypted: true }) // true
+* isEncryptedSocket({}) // false
+* ```
+*/
+function isEncryptedSocket(socket) {
+	return isRecord(socket) && socket.encrypted === true;
+}
+/**
+* Build a fetch-standard `Request` from a `node:http` `IncomingMessage` — the
+* server-adapter half of the §5.3 conversion seam.
+*
+* @remarks
+* - `method` is carried over verbatim (defaulting to `GET` when absent).
+* - The URL is built against `options.origin` when given, otherwise a scheme
+*   derived from the connection (`https` when {@link isEncryptedSocket}, else
+*   `http`) plus the `Host` header (absent `Host` ⇒ `localhost`).
+* - Every request header is copied; multi-value headers are joined per fetch
+*   semantics (`', '`-joined), except `set-cookie`, whose values are each
+*   appended individually (fetch `Headers` preserves multiple `set-cookie`
+*   entries distinctly).
+* - For a method that carries a body (anything but `GET`/`HEAD`), the message
+*   is pumped chunk by chunk into a DOM-compatible `ReadableStream<Uint8Array>`
+*   (reconciling the DOM + node type worlds under the root config), with
+*   `duplex: 'half'` set as Node's fetch implementation requires for a
+*   streamed request body.
+* - A fresh `@orkestrel/abort` handle backs `request.signal`: if the
+*   connection closes before the message finished (`!message.complete`), the
+*   handle aborts — so a handler awaiting `request.signal` observes a client
+*   disconnect the fetch-standard way, with zero router-specific API.
+*
+* @param message - The raw `node:http` request
+* @param options - Optional `origin` override (§5.3 {@link RequestOptions})
+* @returns A fetch `Request` whose `signal` fires on client disconnect
+*
+* @example
+* ```ts
+* import { buildRequest } from '@src/server'
+* import http from 'node:http'
+*
+* const server = http.createServer((incoming) => {
+* 	const request = buildRequest(incoming)
+* 	console.log(request.method, request.url)
+* })
+* ```
+*/
+function buildRequest(message, options) {
+	const method = message.method ?? "GET";
+	const host = message.headers.host ?? "localhost";
+	const scheme = isEncryptedSocket(message.socket) ? "https" : "http";
+	const origin = options?.origin ?? `${scheme}://${host}`;
+	const url = new URL(message.url ?? "/", origin);
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(message.headers)) {
+		if (value === void 0) continue;
+		if (name === "set-cookie") {
+			for (const cookie of Array.isArray(value) ? value : [value]) headers.append(name, cookie);
+			continue;
+		}
+		headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+	}
+	const abort = createAbort();
+	message.once("close", () => {
+		if (!message.complete) abort.abort(/* @__PURE__ */ new Error(`request to ${url.pathname} disconnected before completion`));
+	});
+	const carriesBody = method !== "GET" && method !== "HEAD";
+	const init = {
+		method,
+		headers,
+		signal: abort.signal
+	};
+	if (!carriesBody) return new Request(url, init);
+	const body = new ReadableStream({ async start(controller) {
+		try {
+			for await (const chunk of message) controller.enqueue(chunk);
+			controller.close();
+		} catch (error) {
+			controller.error(error);
+		}
+	} });
+	const streamed = {
+		...init,
+		body,
+		duplex: "half"
+	};
+	return new Request(url, streamed);
+}
+/**
+* Write a fetch-standard `Response` back to a `node:http` `ServerResponse` —
+* the reverse half of the §5.3 conversion seam.
+*
+* @remarks
+* Writes `status`/`statusText`, then every response header (`set-cookie`
+* written via {@link Headers.getSetCookie} so multiple cookies stay distinct
+* instead of collapsing into one comma-joined header), then streams the web
+* body to `target` chunk by chunk (`for await` over `response.body`), ending
+* `target` when the stream completes. A `null` body ends `target` immediately
+* with no further writes. Total error posture: if `target` is destroyed
+* mid-stream (the client disconnected), the write loop stops and `target` is
+* left as-is rather than throwing an unhandled rejection — a destroyed
+* target is not this function's error to surface.
+*
+* @param response - The fetch `Response` to write
+* @param target - The `node:http` response to write it to
+* @returns A promise that resolves once `target` has been ended (or the
+*   stream stopped because `target` was destroyed)
+*
+* @example
+* ```ts
+* import { sendResponse } from '@src/server'
+* import http from 'node:http'
+*
+* const server = http.createServer(async (_incoming, target) => {
+* 	await sendResponse(new Response('ok'), target)
+* })
+* ```
+*/
+async function sendResponse(response, target) {
+	target.statusCode = response.status;
+	target.statusMessage = response.statusText;
+	for (const [name, value] of response.headers) {
+		if (name === "set-cookie") continue;
+		target.setHeader(name, value);
+	}
+	const cookies = response.headers.getSetCookie();
+	if (cookies.length > 0) target.setHeader("set-cookie", cookies);
+	if (response.body === null) {
+		if (!target.destroyed) target.end();
+		return;
+	}
+	try {
+		for await (const chunk of response.body) {
+			if (target.destroyed) return;
+			target.write(chunk);
+		}
+		if (!target.destroyed) target.end();
+	} catch {
+		if (!target.destroyed) target.end();
+	}
+}
+/**
+* Create a `node:http` request listener over a core {@link DispatcherInterface} —
+* the whole server face's entry point (§5.3): convert the incoming message to
+* a fetch `Request`, hand it to the dispatcher with the consumer's per-request
+* `state`, and write the resulting `Response` back.
+*
+* @remarks
+* A rejected `dispatcher.handle` (a route handler throw — the dispatcher
+* never invents an error boundary, §5.1) is this listener's transport-level
+* LAST RESORT, distinct from an application error boundary: when nothing has
+* been sent yet, it destroys the connection with a bare `500` head (never
+* leaking a hanging socket); once headers are already sent, it destroys the
+* connection outright. The router still owns no error POLICY — a consumer
+* that wants mapped error responses installs its own boundary around
+* `dispatcher.handle` (the future `@orkestrel/server` seam, §7).
+*
+* @typeParam TState - The consumer's opaque per-request state type
+* @param dispatcher - The core dispatcher to run each converted request through
+* @param state - Derives the consumer's per-request `state` from the raw message
+* @returns A `(request, response) => void` listener, passable directly to
+*   `http.createServer`
+*
+* @example
+* ```ts
+* import { createListener } from '@src/server'
+* import { createDispatcher } from '@src/core'
+* import http from 'node:http'
+*
+* const dispatcher = createDispatcher()
+* dispatcher.add({ method: 'GET', path: '/health', handler: () => new Response('ok') })
+* http.createServer(createListener(dispatcher, () => undefined)).listen(0)
+* ```
+*/
+function createListener(dispatcher, state) {
+	return (request, response) => {
+		(async () => {
+			try {
+				const converted = buildRequest(request);
+				await sendResponse(await dispatcher.handle(converted, state(request)), response);
+			} catch (error) {
+				if (!response.headersSent && !response.destroyed) {
+					response.writeHead(500);
+					response.end();
+				} else if (!response.destroyed) response.destroy(error instanceof Error ? error : new Error(String(error)));
+			}
+		})();
+	};
+}
+//#endregion
+export { buildRequest, createListener, isEncryptedSocket, sendResponse };
+
+//# sourceMappingURL=index.js.map

package/dist/src/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/server/helpers.ts"],"sourcesContent":["// ============================================================================\n//  Pure conversion + glue between `node:http` and the fetch vocabulary the\n//  core `Dispatcher` speaks — no lifecycle, no listener ownership beyond the\n//  handler function `createListener` returns (§5.3). Every function is\n//  exported per AGENTS §5.\n// ============================================================================\n\nimport type { IncomingMessage, ServerResponse } from 'node:http'\nimport type { DispatcherInterface } from '@src/core'\nimport type { ListenerFunction, RequestOptions, StateFunction } from './types.js'\nimport { createAbort } from '@orkestrel/abort'\nimport { isRecord } from '@orkestrel/contract'\n\n/**\n * Determine whether a `node:http` connection socket is TLS-encrypted — the\n * total, never-throwing narrow (AGENTS §14) `buildRequest` uses to pick the\n * derived scheme (`https` vs `http`).\n *\n * @param socket - The connection value to test (typically `message.socket`)\n * @returns `true` when `socket` carries a truthy `encrypted` property (a\n *   `tls.TLSSocket`), `false` for anything else (including `undefined`)\n *\n * @example\n * ```ts\n * import { isEncryptedSocket } from '@src/server'\n *\n * isEncryptedSocket({ encrypted: true }) // true\n * isEncryptedSocket({}) // false\n * ```\n */\nexport function isEncryptedSocket(socket: unknown): socket is { readonly encrypted: true } {\n\treturn isRecord(socket) && socket.encrypted === true\n}\n\n/**\n * Build a fetch-standard `Request` from a `node:http` `IncomingMessage` — the\n * server-adapter half of the §5.3 conversion seam.\n *\n * @remarks\n * - `method` is carried over verbatim (defaulting to `GET` when absent).\n * - The URL is built against `options.origin` when given, otherwise a scheme\n *   derived from the connection (`https` when {@link isEncryptedSocket}, else\n *   `http`) plus the `Host` header (absent `Host` ⇒ `localhost`).\n * - Every request header is copied; multi-value headers are joined per fetch\n *   semantics (`', '`-joined), except `set-cookie`, whose values are each\n *   appended individually (fetch `Headers` preserves multiple `set-cookie`\n *   entries distinctly).\n * - For a method that carries a body (anything but `GET`/`HEAD`), the message\n *   is pumped chunk by chunk into a DOM-compatible `ReadableStream<Uint8Array>`\n *   (reconciling the DOM + node type worlds under the root config), with\n *   `duplex: 'half'` set as Node's fetch implementation requires for a\n *   streamed request body.\n * - A fresh `@orkestrel/abort` handle backs `request.signal`: if the\n *   connection closes before the message finished (`!message.complete`), the\n *   handle aborts — so a handler awaiting `request.signal` observes a client\n *   disconnect the fetch-standard way, with zero router-specific API.\n *\n * @param message - The raw `node:http` request\n * @param options - Optional `origin` override (§5.3 {@link RequestOptions})\n * @returns A fetch `Request` whose `signal` fires on client disconnect\n *\n * @example\n * ```ts\n * import { buildRequest } from '@src/server'\n * import http from 'node:http'\n *\n * const server = http.createServer((incoming) => {\n * \tconst request = buildRequest(incoming)\n * \tconsole.log(request.method, request.url)\n * })\n * ```\n */\nexport function buildRequest(message: IncomingMessage, options?: RequestOptions): Request {\n\tconst method = message.method ?? 'GET'\n\tconst host = message.headers.host ?? 'localhost'\n\tconst scheme = isEncryptedSocket(message.socket) ? 'https' : 'http'\n\tconst origin = options?.origin ?? `${scheme}://${host}`\n\tconst url = new URL(message.url ?? '/', origin)\n\n\tconst headers = new Headers()\n\tfor (const [name, value] of Object.entries(message.headers)) {\n\t\tif (value === undefined) continue\n\t\tif (name === 'set-cookie') {\n\t\t\tfor (const cookie of Array.isArray(value) ? value : [value]) headers.append(name, cookie)\n\t\t\tcontinue\n\t\t}\n\t\theaders.set(name, Array.isArray(value) ? value.join(', ') : value)\n\t}\n\n\tconst abort = createAbort()\n\tmessage.once('close', () => {\n\t\tif (!message.complete)\n\t\t\tabort.abort(new Error(`request to ${url.pathname} disconnected before completion`))\n\t})\n\n\tconst carriesBody = method !== 'GET' && method !== 'HEAD'\n\tconst init: RequestInit = { method, headers, signal: abort.signal }\n\tif (!carriesBody) return new Request(url, init)\n\n\tconst body = new ReadableStream<Uint8Array>({\n\t\tasync start(controller) {\n\t\t\ttry {\n\t\t\t\tfor await (const chunk of message) controller.enqueue(chunk)\n\t\t\t\tcontroller.close()\n\t\t\t} catch (error) {\n\t\t\t\tcontroller.error(error)\n\t\t\t}\n\t\t},\n\t})\n\tconst streamed: RequestInit & { readonly duplex: 'half' } = { ...init, body, duplex: 'half' }\n\treturn new Request(url, streamed)\n}\n\n/**\n * Write a fetch-standard `Response` back to a `node:http` `ServerResponse` —\n * the reverse half of the §5.3 conversion seam.\n *\n * @remarks\n * Writes `status`/`statusText`, then every response header (`set-cookie`\n * written via {@link Headers.getSetCookie} so multiple cookies stay distinct\n * instead of collapsing into one comma-joined header), then streams the web\n * body to `target` chunk by chunk (`for await` over `response.body`), ending\n * `target` when the stream completes. A `null` body ends `target` immediately\n * with no further writes. Total error posture: if `target` is destroyed\n * mid-stream (the client disconnected), the write loop stops and `target` is\n * left as-is rather than throwing an unhandled rejection — a destroyed\n * target is not this function's error to surface.\n *\n * @param response - The fetch `Response` to write\n * @param target - The `node:http` response to write it to\n * @returns A promise that resolves once `target` has been ended (or the\n *   stream stopped because `target` was destroyed)\n *\n * @example\n * ```ts\n * import { sendResponse } from '@src/server'\n * import http from 'node:http'\n *\n * const server = http.createServer(async (_incoming, target) => {\n * \tawait sendResponse(new Response('ok'), target)\n * })\n * ```\n */\nexport async function sendResponse(response: Response, target: ServerResponse): Promise<void> {\n\ttarget.statusCode = response.status\n\ttarget.statusMessage = response.statusText\n\tfor (const [name, value] of response.headers) {\n\t\tif (name === 'set-cookie') continue\n\t\ttarget.setHeader(name, value)\n\t}\n\tconst cookies = response.headers.getSetCookie()\n\tif (cookies.length > 0) target.setHeader('set-cookie', cookies)\n\n\tif (response.body === null) {\n\t\tif (!target.destroyed) target.end()\n\t\treturn\n\t}\n\ttry {\n\t\tfor await (const chunk of response.body) {\n\t\t\tif (target.destroyed) return\n\t\t\ttarget.write(chunk)\n\t\t}\n\t\tif (!target.destroyed) target.end()\n\t} catch {\n\t\tif (!target.destroyed) target.end()\n\t}\n}\n\n/**\n * Create a `node:http` request listener over a core {@link DispatcherInterface} —\n * the whole server face's entry point (§5.3): convert the incoming message to\n * a fetch `Request`, hand it to the dispatcher with the consumer's per-request\n * `state`, and write the resulting `Response` back.\n *\n * @remarks\n * A rejected `dispatcher.handle` (a route handler throw — the dispatcher\n * never invents an error boundary, §5.1) is this listener's transport-level\n * LAST RESORT, distinct from an application error boundary: when nothing has\n * been sent yet, it destroys the connection with a bare `500` head (never\n * leaking a hanging socket); once headers are already sent, it destroys the\n * connection outright. The router still owns no error POLICY — a consumer\n * that wants mapped error responses installs its own boundary around\n * `dispatcher.handle` (the future `@orkestrel/server` seam, §7).\n *\n * @typeParam TState - The consumer's opaque per-request state type\n * @param dispatcher - The core dispatcher to run each converted request through\n * @param state - Derives the consumer's per-request `state` from the raw message\n * @returns A `(request, response) => void` listener, passable directly to\n *   `http.createServer`\n *\n * @example\n * ```ts\n * import { createListener } from '@src/server'\n * import { createDispatcher } from '@src/core'\n * import http from 'node:http'\n *\n * const dispatcher = createDispatcher()\n * dispatcher.add({ method: 'GET', path: '/health', handler: () => new Response('ok') })\n * http.createServer(createListener(dispatcher, () => undefined)).listen(0)\n * ```\n */\nexport function createListener<TState>(\n\tdispatcher: DispatcherInterface<TState>,\n\tstate: StateFunction<TState>,\n): ListenerFunction {\n\treturn (request, response) => {\n\t\tvoid (async () => {\n\t\t\ttry {\n\t\t\t\tconst converted = buildRequest(request)\n\t\t\t\tconst result = await dispatcher.handle(converted, state(request))\n\t\t\t\tawait sendResponse(result, response)\n\t\t\t} catch (error) {\n\t\t\t\tif (!response.headersSent && !response.destroyed) {\n\t\t\t\t\tresponse.writeHead(500)\n\t\t\t\t\tresponse.end()\n\t\t\t\t} else if (!response.destroyed) {\n\t\t\t\t\tresponse.destroy(error instanceof Error ? error : new Error(String(error)))\n\t\t\t\t}\n\t\t\t}\n\t\t})()\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,kBAAkB,QAAyD;CAC1F,OAAO,SAAS,MAAM,KAAK,OAAO,cAAc;AACjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,aAAa,SAA0B,SAAmC;CACzF,MAAM,SAAS,QAAQ,UAAU;CACjC,MAAM,OAAO,QAAQ,QAAQ,QAAQ;CACrC,MAAM,SAAS,kBAAkB,QAAQ,MAAM,IAAI,UAAU;CAC7D,MAAM,SAAS,SAAS,UAAU,GAAG,OAAO,KAAK;CACjD,MAAM,MAAM,IAAI,IAAI,QAAQ,OAAO,KAAK,MAAM;CAE9C,MAAM,UAAU,IAAI,QAAQ;CAC5B,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,QAAQ,OAAO,GAAG;EAC5D,IAAI,UAAU,KAAA,GAAW;EACzB,IAAI,SAAS,cAAc;GAC1B,KAAK,MAAM,UAAU,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK,GAAG,QAAQ,OAAO,MAAM,MAAM;GACxF;EACD;EACA,QAAQ,IAAI,MAAM,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK;CAClE;CAEA,MAAM,QAAQ,YAAY;CAC1B,QAAQ,KAAK,eAAe;EAC3B,IAAI,CAAC,QAAQ,UACZ,MAAM,sBAAM,IAAI,MAAM,cAAc,IAAI,SAAS,gCAAgC,CAAC;CACpF,CAAC;CAED,MAAM,cAAc,WAAW,SAAS,WAAW;CACnD,MAAM,OAAoB;EAAE;EAAQ;EAAS,QAAQ,MAAM;CAAO;CAClE,IAAI,CAAC,aAAa,OAAO,IAAI,QAAQ,KAAK,IAAI;CAE9C,MAAM,OAAO,IAAI,eAA2B,EAC3C,MAAM,MAAM,YAAY;EACvB,IAAI;GACH,WAAW,MAAM,SAAS,SAAS,WAAW,QAAQ,KAAK;GAC3D,WAAW,MAAM;EAClB,SAAS,OAAO;GACf,WAAW,MAAM,KAAK;EACvB;CACD,EACD,CAAC;CACD,MAAM,WAAsD;EAAE,GAAG;EAAM;EAAM,QAAQ;CAAO;CAC5F,OAAO,IAAI,QAAQ,KAAK,QAAQ;AACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,eAAsB,aAAa,UAAoB,QAAuC;CAC7F,OAAO,aAAa,SAAS;CAC7B,OAAO,gBAAgB,SAAS;CAChC,KAAK,MAAM,CAAC,MAAM,UAAU,SAAS,SAAS;EAC7C,IAAI,SAAS,cAAc;EAC3B,OAAO,UAAU,MAAM,KAAK;CAC7B;CACA,MAAM,UAAU,SAAS,QAAQ,aAAa;CAC9C,IAAI,QAAQ,SAAS,GAAG,OAAO,UAAU,cAAc,OAAO;CAE9D,IAAI,SAAS,SAAS,MAAM;EAC3B,IAAI,CAAC,OAAO,WAAW,OAAO,IAAI;EAClC;CACD;CACA,IAAI;EACH,WAAW,MAAM,SAAS,SAAS,MAAM;GACxC,IAAI,OAAO,WAAW;GACtB,OAAO,MAAM,KAAK;EACnB;EACA,IAAI,CAAC,OAAO,WAAW,OAAO,IAAI;CACnC,QAAQ;EACP,IAAI,CAAC,OAAO,WAAW,OAAO,IAAI;CACnC;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,eACf,YACA,OACmB;CACnB,QAAQ,SAAS,aAAa;EAC7B,CAAM,YAAY;GACjB,IAAI;IACH,MAAM,YAAY,aAAa,OAAO;IAEtC,MAAM,aAAa,MADE,WAAW,OAAO,WAAW,MAAM,OAAO,CAAC,GACrC,QAAQ;GACpC,SAAS,OAAO;IACf,IAAI,CAAC,SAAS,eAAe,CAAC,SAAS,WAAW;KACjD,SAAS,UAAU,GAAG;KACtB,SAAS,IAAI;IACd,OAAO,IAAI,CAAC,SAAS,WACpB,SAAS,QAAQ,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC,CAAC;GAE5E;EACD,EAAA,CAAG;CACJ;AACD"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@orkestrel/router",
-	"version": "0.0.1",
+	"version": "0.0.3",
 	"description": "A typed request router for the @orkestrel line — server and browser environments. Part of the @orkestrel line.",
 	"keywords": [
 		"browser",
@@ -23,23 +23,34 @@
 	],
 	"type": "module",
 	"sideEffects": false,
-	"main": "./dist/src/core/index.js",
-	"types": "./dist/src/core/index.d.ts",
+	"main": "./dist/src/core/index.cjs",
+	"module": "./dist/src/core/index.js",
 	"exports": {
 		".": {
-			"types": "./dist/src/core/index.d.ts",
-			"import": "./dist/src/core/index.js",
-			"default": "./dist/src/core/index.js"
+			"import": {
+				"types": "./dist/src/core/index.d.ts",
+				"default": "./dist/src/core/index.js"
+			},
+			"require": {
+				"types": "./dist/src/core/index.d.cts",
+				"default": "./dist/src/core/index.cjs"
+			}
 		},
 		"./browser": {
-			"types": "./dist/src/browser/index.d.ts",
-			"import": "./dist/src/browser/index.js",
-			"default": "./dist/src/browser/index.js"
+			"import": {
+				"types": "./dist/src/browser/index.d.ts",
+				"default": "./dist/src/browser/index.js"
+			}
 		},
 		"./server": {
-			"types": "./dist/src/server/index.d.ts",
-			"require": "./dist/src/server/index.cjs",
-			"default": "./dist/src/server/index.cjs"
+			"import": {
+				"types": "./dist/src/server/index.d.ts",
+				"default": "./dist/src/server/index.js"
+			},
+			"require": {
+				"types": "./dist/src/server/index.d.cts",
+				"default": "./dist/src/server/index.cjs"
+			}
 		},
 		"./package.json": "./package.json"
 	},
@@ -51,7 +62,7 @@
 		"copy": "node -e \"const fs=require('node:fs'),p=require('node:path'),a=process.argv[1],b=process.argv[2];fs.mkdirSync(p.dirname(b),{recursive:true});fs.cpSync(a,b,{force:true});console.log('Copied: '+a+' to '+b)\"",
 		"tmp:txt": "node -e \"const fs=require('node:fs'),p=require('node:path');function walk(d){for(const e of fs.readdirSync(d,{withFileTypes:true})){const f=p.join(d,e.name);if(e.isDirectory()){walk(f)}else if(!e.name.endsWith('.md')&&!e.name.endsWith('.txt')){const t=f+'.txt';if(!fs.existsSync(t)){fs.renameSync(f,t)}else{console.warn('Skipping '+f+' — target exists: '+t)}}}}try{walk('tmp')}catch(e){if(e.code!=='ENOENT')throw e}\"",
 		"lint": "oxlint --config .oxlintrc.json --fix .",
-		"check": "tsc --noEmit --project tsconfig.json",
+		"check": "tsc --noEmit --project tsconfig.json && npm run check:src",
 		"check:src": "npm run check:src:core && npm run check:src:browser && npm run check:src:server",
 		"check:src:core": "tsc --noEmit -p configs/src/tsconfig.core.json",
 		"check:src:browser": "tsc --noEmit -p configs/src/tsconfig.browser.json",
@@ -67,27 +78,29 @@
 		"test:guides": "vitest run --config vite.config.ts --reporter=dot --project guides",
 		"build": "npm run clean && npm run build:src",
 		"build:src": "npm run build:src:core && npm run build:src:browser && npm run build:src:server",
-		"build:src:core": "vite build --config configs/src/vite.core.config.ts && tsc -p configs/src/tsconfig.core.json",
-		"build:src:browser": "vite build --config configs/src/vite.browser.config.ts && tsc -p configs/src/tsconfig.browser.json",
-		"build:src:server": "vite build --config configs/src/vite.server.config.ts && tsc -p configs/src/tsconfig.server.json",
-		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run check && npm run build && npm test"
+		"build:src:core": "vite build --config configs/src/vite.core.config.ts && npm run copy dist/src/core/index.d.ts dist/src/core/index.d.cts",
+		"build:src:browser": "vite build --config configs/src/vite.browser.config.ts",
+		"build:src:server": "vite build --config configs/src/vite.server.config.ts && npm run copy dist/src/server/index.d.ts dist/src/server/index.d.cts",
+		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test"
 	},
 	"dependencies": {
-		"@orkestrel/abort": "^0.0.1",
-		"@orkestrel/contract": "^0.0.1",
-		"@orkestrel/emitter": "^0.0.1"
+		"@orkestrel/abort": "^0.0.2",
+		"@orkestrel/contract": "^0.0.2",
+		"@orkestrel/emitter": "^0.0.2"
 	},
 	"devDependencies": {
-		"@orkestrel/guide": "^0.0.1",
+		"@microsoft/api-extractor": "^7.58.11",
+		"@orkestrel/guide": "^0.0.2",
 		"@types/node": "^26.1.1",
 		"@vitest/browser-playwright": "^4.1.10",
-		"oxfmt": "^0.58.0",
-		"oxlint": "^1.73.0",
+		"oxfmt": "^0.59.0",
+		"oxlint": "^1.74.0",
 		"typescript": "^6.0.3",
-		"vite": "^8.1.4",
+		"vite": "^8.1.5",
+		"vite-plugin-dts": "^5.0.3",
 		"vitest": "^4.1.10"
 	},
 	"engines": {
-		"node": ">=24"
+		"node": ">=22"
 	}
 }

package/dist/src/browser/Navigator.d.ts

@@ -1,62 +0,0 @@
-import type { NavigatorEventMap, NavigatorInterface, NavigatorOptions } from './types.js';
-import type { EmitterInterface } from '@orkestrel/emitter';
-import type { RouteEntry, RouterInterface, RouterMatch } from '@src/core';
-/**
- * The headless History/hash navigation entity — composes one core
- * `Router<RouteEntry<Meta>>`, resolving the current location on `start()` and
- * every subsequent navigation event, tracking `active`, and emitting
- * `navigate` through the core {@link Emitter} (AGENTS §13). No `render` /
- * `outlet` — the consumer owns rendering.
- *
- * @typeParam Meta - The opaque per-route payload a match carries back
- *
- * @remarks
- * - **One shared engine.** Each `route.path` is registered on the SAME
- *   `Router` machine the core `Dispatcher` composes, keyed for dedup by its
- *   {@link canonicalizePath} (last write wins, replace-in-place) — literal-
- *   over-param precedence, trailing-slash insensitivity, and
- *   `:param`/`*wildcard` extraction all come from that one engine (AGENTS
- *   §21).
- * - **Resolve pipeline.** Compute the `/`-prefixed pathname to match
- *   ({@link resolveLocationPath}) → {@link match} it → on a miss, match the
- *   `fallback` through the SAME engine → a fallback that ALSO matches nothing
- *   aborts any pending guarded navigation (a miss SUPERSEDES it, same as a
- *   newer navigation) and leaves `active` `undefined`, emitting nothing
- *   (§21-honest: no phantom match is fabricated) → the optional `guard` may
- *   veto → on a verdict, `active` is set and `navigate` emitted.
- * - **Supersede-safe guard.** Every navigation mints an `@orkestrel/abort`
- *   handle, aborting the PREVIOUS navigation's handle first; a guard verdict
- *   that resolves after its navigation was superseded (`signal.aborted`) is
- *   discarded, same as a `false`/rejected verdict. A guard throw routes to
- *   the `error` handler and vetoes. `stop()`/`destroy()` also abort the
- *   pending handle.
- * - **Hash vs history mode.** Hash mode (`history: false`, the default) binds
- *   `hashchange`; history mode (`history: true`) binds `popstate` and, when
- *   `intercept` is set, same-origin `<a>` click interception (a plain
- *   left-click with no modifier keys, `target`, or `download` attribute).
- *
- * @example
- * ```ts
- * const navigator = new Navigator<{ readonly title: string }>({
- * 	routes: [
- * 		{ path: '/users/:id', meta: { title: 'User' } },
- * 		{ path: '/tokens', meta: { title: 'Tokens' } },
- * 	],
- * })
- * navigator.emitter.on('navigate', (match) => (document.title = match.meta.title))
- * navigator.start() // resolves the current hash now, and on every hashchange
- * navigator.navigate('/tokens')
- * ```
- */
-export declare class Navigator<Meta> implements NavigatorInterface<Meta> {
-    #private;
-    constructor(options: NavigatorOptions<Meta>);
-    get router(): RouterInterface<RouteEntry<Meta>>;
-    get emitter(): EmitterInterface<NavigatorEventMap<Meta>>;
-    get active(): RouterMatch<Meta> | undefined;
-    start(): void;
-    stop(): void;
-    navigate(path: string): void;
-    match(path: string): RouterMatch<Meta> | undefined;
-    destroy(): void;
-}

package/dist/src/browser/factories.d.ts

@@ -1,33 +0,0 @@
-import type { NavigatorInterface, NavigatorOptions } from './types.js';
-/**
- * Create a {@link NavigatorInterface} — the headless History/hash navigation
- * entity composing one core `Router<RouteEntry<Meta>>`.
- *
- * @remarks
- * Prefer this over `new Navigator(...)` at call sites that only need the
- * interface.
- *
- * @typeParam Meta - The opaque per-route payload a match carries back
- * @param options - The `routes` to register, the `history` toggle (default
- *   `false`, hash mode), an optional `base` (history mode), an optional
- *   `fallback` path, an optional `guard` hook, opt-in link `intercept`
- *   (history mode), the `sensitive` case toggle, and the AGENTS §13 emitter
- *   `on`/`error` wiring
- * @returns A live {@link NavigatorInterface} handle — call `start()` to begin
- *   dispatching
- *
- * @example
- * ```ts
- * import { createNavigator } from '@src/browser'
- *
- * const navigator = createNavigator({
- * 	routes: [
- * 		{ path: '/users/:id', meta: { title: 'User' } },
- * 		{ path: '/tokens', meta: { title: 'Tokens' } },
- * 	],
- * 	on: { navigate: (match) => (document.title = match.meta.title) },
- * })
- * navigator.start()
- * ```
- */
-export declare function createNavigator<Meta>(options: NavigatorOptions<Meta>): NavigatorInterface<Meta>;

package/dist/src/browser/helpers.d.ts

@@ -1,76 +0,0 @@
-/**
- * Extract the `/`-prefixed pathname from a `location.hash` value — strip the
- * leading `#` (keeping the route's own leading `/`) and any `?query` suffix.
- *
- * @remarks
- * The grammar this package matches everywhere is `/`-prefixed (§4 path
- * grammar), so a hash-mode location's `'#/users/7?x'` becomes `'/users/7'`
- * — a hash pattern is expected to start `'#/'`; anything else (an empty hash,
- * or one that does not begin `'#/'`) yields `''` (the `Navigator` then falls
- * back). Total — never throws.
- *
- * @param hash - The raw `window.location.hash` value (e.g. `'#/users/7?x'`)
- * @returns The `/`-prefixed pathname to match, or `''` for an empty / non-`#/` hash
- *
- * @example
- * ```ts
- * extractHashPath('#/users/7?x') // '/users/7'
- * extractHashPath('#/tokens') // '/tokens'
- * extractHashPath('') // '' — the Navigator falls back
- * extractHashPath('#other') // '' — not a `#/` route hash
- * ```
- */
-export declare function extractHashPath(hash: string): string;
-/**
- * Resolve the `/`-prefixed pathname to match for the CURRENT location, in
- * either navigation mode — the one seam `extractHashPath` (hash mode) and
- * history-mode base-stripping share.
- *
- * @remarks
- * Hash mode (`history: false`) reads `location.hash` through
- * {@link extractHashPath}. History mode (`history: true`) reads
- * `location.pathname` and strips a leading `base` prefix when one is
- * configured: `base` itself maps to the root `'/'`; a pathname that is not
- * under `base` is returned unchanged (a base mismatch is not this helper's
- * concern — the `Navigator`'s match then simply misses). Total — never throws.
- *
- * @param location - The `hash` + `pathname` pair to resolve from (accepts a
- *   real `Location` or any object shaped the same, for pure unit testing)
- * @param history - The navigation substrate: `false` for hash mode, `true`
- *   for history mode
- * @param base - The history-mode path prefix to strip (ignored in hash mode;
- *   omit for no prefix)
- * @returns The `/`-prefixed pathname to match
- *
- * @example
- * ```ts
- * resolveLocationPath({ hash: '#/users/7', pathname: '/' }, false) // '/users/7'
- * resolveLocationPath({ hash: '', pathname: '/app/users/7' }, true, '/app') // '/users/7'
- * resolveLocationPath({ hash: '', pathname: '/app' }, true, '/app') // '/'
- * resolveLocationPath({ hash: '', pathname: '/other/users' }, true, '/app') // '/other/users'
- * ```
- */
-export declare function resolveLocationPath(location: Pick<Location, 'hash' | 'pathname'>, history: boolean, base?: string): string;
-/**
- * Find the nearest enclosing `<a>` element a DOM event originated from, by
- * walking its composed path — the pure lookup behind history-mode link
- * interception.
- *
- * @remarks
- * Uses `event.composedPath()` (not `event.target`) so a click on a styled
- * child INSIDE an anchor (an icon, a span) still resolves to the anchor.
- * Total — never throws; returns `undefined` when no anchor is found on the
- * path.
- *
- * @param event - The DOM event to search (typically a `click`)
- * @returns The nearest enclosing `HTMLAnchorElement`, or `undefined`
- *
- * @example
- * ```ts
- * document.addEventListener('click', (event) => {
- * 	const anchor = findAnchor(event)
- * 	if (anchor !== undefined) console.log(anchor.href)
- * })
- * ```
- */
-export declare function findAnchor(event: Event): HTMLAnchorElement | undefined;

package/dist/src/browser/types.d.ts

@@ -1,101 +0,0 @@
-import type { EmitterErrorHandler, EmitterHooks, EmitterInterface } from '@orkestrel/emitter';
-import type { RouteEntry, RouterInterface, RouterMatch } from '@src/core';
-/**
- * The `Navigator`'s event map (AGENTS §13) — the single `navigate` signal a
- * consumer observes.
- *
- * @typeParam Meta - The opaque per-route payload the resolved match carries
- *
- * @remarks
- * `navigate` fires once per successful resolution (start, hashchange/popstate,
- * `navigate()`, link interception) — never for a vetoed or superseded navigation
- * ({@link NavigatorOptions.guard}), and never when a miss's fallback also
- * misses (§21-honest: `active` is left `undefined`, nothing emitted).
- */
-export type NavigatorEventMap<Meta> = {
-    readonly navigate: readonly [match: RouterMatch<Meta>];
-};
-/**
- * Options for `createNavigator` — the `routes` to dispatch between, the
- * navigation substrate, the optional guard hook, and the AGENTS §13 emitter
- * wiring.
- *
- * @typeParam Meta - The opaque payload each route may carry
- *
- * @remarks
- * - `routes` — the route entries to register once with the shared core
- *   `Router` (each `path` compiled once); registration order does NOT decide
- *   precedence — specificity does (literal-over-param-over-wildcard).
- * - `history` — `false` (default, hash mode: `#/…` + `hashchange`, zero
- *   server configuration) or `true` (history mode: `pushState`/`popstate`).
- * - `base` — a history-mode path prefix stripped from `location.pathname`
- *   before matching, and prepended when navigating (`navigate`, link
- *   interception). Ignored unless `history` is set.
- * - `fallback` — the route PATTERN to resolve when the current location
- *   matches NOTHING. Omitted ⇒ the first route's path. A `fallback` that
- *   itself matches no registered route leaves `active` `undefined` and emits
- *   nothing (§21-honest: no phantom match is fabricated).
- * - `guard` — `(to, from, signal) => boolean | Promise<boolean>`, called
- *   before a navigation commits; a `false`/rejected verdict, or one arriving
- *   after the navigation was SUPERSEDED (`signal.aborted`), is discarded —
- *   `active` stays unchanged and nothing is emitted. `signal` fires when a
- *   NEWER navigation starts (or on `stop`/`destroy`), so a slow async guard
- *   can cancel its own work off it. A throw routes to the `error` handler
- *   below and vetoes the navigation.
- * - `intercept` — opt-in same-origin `<a>` click interception (history mode
- *   only): a plain left-click on a same-origin link with no modifier keys,
- *   no `target`, and no `download` attribute is intercepted into `navigate`.
- * - `sensitive` — forwarded to the underlying `Router` (default `true`).
- * - `on` — initial `NavigatorEventMap` listeners (AGENTS §8/§13).
- * - `error` — the emitter's listener-error handler (AGENTS §13); ALSO the
- *   handler a thrown {@link guard} routes to (the Navigator's own pipeline,
- *   not a listener throw, so it is surfaced through the same channel).
- */
-export interface NavigatorOptions<Meta> {
-    readonly routes: readonly RouteEntry<Meta>[];
-    readonly history?: boolean;
-    readonly base?: string;
-    readonly fallback?: string;
-    readonly guard?: (to: RouterMatch<Meta>, from: RouterMatch<Meta> | undefined, signal: AbortSignal) => boolean | Promise<boolean>;
-    readonly intercept?: boolean;
-    readonly sensitive?: boolean;
-    readonly on?: EmitterHooks<NavigatorEventMap<Meta>>;
-    readonly error?: EmitterErrorHandler;
-}
-/**
- * The headless History/hash navigation entity contract (the §4.5 behavioral-
- * interface role for the one-class-per-file `Navigator`). Composes a core
- * `Router<RouteEntry<Meta>>`, resolves the current location on `start()` and
- * on every subsequent navigation event, tracks `active`, and emits
- * `navigate` through the AGENTS §13 {@link EmitterInterface}.
- *
- * @typeParam Meta - The opaque per-route payload a match carries back
- *
- * @remarks
- * - `router` — the underlying registry, exposed READONLY for introspection
- *   (the same object routes were registered on).
- * - `emitter` — the AGENTS §13 observable surface for {@link NavigatorEventMap}.
- * - `active` — the currently-resolved {@link RouterMatch}, or `undefined`
- *   before the first resolve (or when a miss's fallback also misses).
- * - `start()` — begin listening (`hashchange` in hash mode; `popstate` +
- *   optional link interception in history mode) and resolve the current
- *   location now. Idempotent — a second call is a no-op.
- * - `stop()` — stop listening. Idempotent.
- * - `navigate(path)` — navigate programmatically: sets `location.hash` (hash
- *   mode) or calls `history.pushState` (history mode), then resolves. A
- *   no-op hash navigation (already the active hash) resolves directly, since
- *   no `hashchange` would otherwise fire.
- * - `match(path)` — a PURE lookup through the underlying `Router`: no
- *   location read, no fallback, no guard, no emit.
- * - `destroy()` — `stop()` plus tear down the `#emitter` (AGENTS §13).
- */
-export interface NavigatorInterface<Meta> {
-    readonly router: RouterInterface<RouteEntry<Meta>>;
-    readonly emitter: EmitterInterface<NavigatorEventMap<Meta>>;
-    readonly active: RouterMatch<Meta> | undefined;
-    start(): void;
-    stop(): void;
-    navigate(path: string): void;
-    match(path: string): RouterMatch<Meta> | undefined;
-    destroy(): void;
-}

package/dist/src/core/DispatchGroup.d.ts

@@ -1,32 +0,0 @@
-import type { DispatchGroupInterface, DispatcherInterface, RouteInput } from './types.js';
-/**
- * A prefix-scoped registration handle over a
- * {@link import('./Dispatcher.js').Dispatcher} — the method-dimensioned
- * counterpart of `Group` (`Group.ts`).
- *
- * @typeParam TState - The consumer's opaque per-request state type, matching
- *   the owning dispatcher
- *
- * @remarks
- * Every `add` composes `input.path` via {@link joinPaths} against
- * `this.prefix` and forwards to the OWNING dispatcher's `add` (its own §14
- * boundary guard still applies). Pure string composition (§4.2.2) — no
- * independent state or storage.
- *
- * @example
- * ```ts
- * import { Dispatcher } from '@src/core'
- *
- * const dispatcher = new Dispatcher()
- * const api = dispatcher.group('/api')
- * api.add({ method: 'GET', path: '/users', handler: () => new Response('ok') })
- * ```
- */
-export declare class DispatchGroup<TState> implements DispatchGroupInterface<TState> {
-    #private;
-    readonly prefix: string;
-    constructor(parent: DispatcherInterface<TState>, prefix: string);
-    add<Path extends string>(input: RouteInput<Path, TState>): void;
-    add(inputs: readonly RouteInput<string, TState>[]): void;
-    group(prefix: string): DispatchGroupInterface<TState>;
-}