@davidsouther/jiffies 2026.24.0 → 2026.24.2

package/lib/esm/server/http/apps.js

@@ -0,0 +1,23 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { fileResponse } from "./response.js";
+/**
+ * Searches up the request path until the first index is found.
+ */
+export const findIndex = async ({ root }) => async (req) => {
+    let filename = path.join(root, req.url ?? "");
+    if (path.basename(filename).match(/\.[a-z]{1,3}$/)) {
+        return undefined;
+    }
+    while (filename.startsWith(root)) {
+        const index = path.join(filename, "index.html");
+        try {
+            const stat = await fs.stat(index);
+            return fileResponse(index, stat);
+        }
+        catch (_e) {
+            filename = path.dirname(filename);
+        }
+    }
+    return undefined;
+};

package/lib/esm/server/http/css.d.ts

@@ -0,0 +1,5 @@
+import type { MiddlewareFactory } from "./index.ts";
+/**
+ * Serves .css files statically. Finds .sass files and transpiles them to css.
+ */
+export declare const cssFileServer: MiddlewareFactory;

package/lib/esm/server/http/css.js

@@ -0,0 +1,43 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { contentResponse } from "./response.js";
+function render(source) {
+    // Replace `from "@scope` with `from "/@scope`, for browsers
+    // source = source
+    //   .replaceAll(`from "@`, 'from "/@')
+    //   .replaceAll(`import("@`, 'import("/@');
+    return contentResponse(source, "text/css");
+}
+/**
+ * Serves .css files statically. Finds .sass files and transpiles them to css.
+ */
+export const cssFileServer = async ({ root, scopes = {} }) => async (req) => {
+    const Url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    if (Url.pathname.endsWith(".css")) {
+        const scope = Object.entries(scopes).find(([s]) => Url.pathname.startsWith(`/${s}`));
+        // Expand url with found scope
+        Url.protocol = "file";
+        const url = scope
+            ? Url.pathname.replace(scope[0], scope[1])
+            : Url.pathname;
+        let filename = path.join(root, url);
+        try {
+            const stat = await fs.stat(filename);
+            if (stat.isFile()) {
+                const css = (await fs.readFile(filename)).toString("utf-8");
+                return render(css);
+            }
+        }
+        catch { }
+        filename = filename.replace(/\.css$/, ".scss");
+        try {
+            const stat = await fs.stat(filename);
+            if (stat.isFile()) {
+                const css = (await fs.readFile(filename)).toString();
+                return render(css);
+            }
+        }
+        catch { }
+    }
+    return undefined;
+};

package/lib/esm/server/http/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { type IncomingMessage, type ServerResponse } from "node:http";
+export interface StaticResponse {
+    status: 200 | 404 | 500;
+    content: Buffer;
+    contentType: string;
+    contentLength?: number;
+    headers?: Map<string, string>;
+}
+export interface ServerConfig {
+    root: string;
+    scopes?: Record<`@${string}`, string>;
+}
+export type MiddlewareFactory = (config: ServerConfig) => Promise<StaticMiddleware>;
+export type StaticMiddleware = (req: IncomingMessage) => Promise<undefined | (() => Promise<StaticResponse>)>;
+export declare const makeServer: (config: ServerConfig, middlewares?: MiddlewareFactory[]) => Promise<import("http").Server<typeof IncomingMessage, typeof ServerResponse>>;

package/lib/esm/server/http/index.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { createServer, } from "node:http";
+import * as path from "node:path";
+import { info } from "../../log.js";
+import { findIndex } from "./apps.js";
+import { cssFileServer } from "./css.js";
+import { fileResponse } from "./response.js";
+import { sitemap } from "./sitemap.js";
+import { staticFileServer } from "./static.js";
+import { tsFileServer } from "./typescript.js";
+const notFound = async ({ root }) => async () => fileResponse(
+// path.join(path.dirname(FLAGS.argv0), "404.html"),
+path.join(root, "404.html"), undefined, 404);
+const BASE_MIDDLEWARES = [
+    sitemap,
+    tsFileServer,
+    cssFileServer,
+    staticFileServer,
+    findIndex,
+    notFound,
+];
+const error = (res, message) => {
+    console.error(message);
+    res.statusCode = 500;
+    res.write(message);
+    res.end();
+    return true;
+};
+const sendContent = async (res, { content, contentType, contentLength, headers }) => {
+    res.setHeader("Content-Length", `${contentLength}`);
+    res.setHeader("Content-Type", contentType);
+    if (headers) {
+        for (const [header, value] of headers.entries()) {
+            res.setHeader(header.toLowerCase(), value);
+        }
+    }
+    await res.write(content);
+    res.end();
+    return true;
+};
+const log = (req) => {
+    const when = new Date().toISOString();
+    const who = req.socket.remoteAddress;
+    const what = req.url;
+    const how = `${req.method} ${what}`;
+    info("Request", { when, who, how });
+};
+export const makeServer = async (config, middlewares = []) => {
+    const handlers = await Promise.all([...middlewares, ...BASE_MIDDLEWARES].map(async (m) => m(config)));
+    const middlewareHandler = async (req, res) => {
+        log(req);
+        let handler;
+        try {
+            for (const middleware of handlers) {
+                handler = await middleware(req);
+                if (handler !== undefined) {
+                    break;
+                }
+            }
+            if (handler) {
+                sendContent(res, await handler());
+            }
+            else {
+                res.end();
+            }
+        }
+        catch (e) {
+            error(res, `${e.message}\n${e.stack}`);
+        }
+    };
+    // TODO(https)
+    const server = createServer(middlewareHandler);
+    server.on("listening", () => {
+        const { address, port } = server.address();
+        info("Server listening", { address: `http://${address}:${port}` });
+    });
+    return server;
+};

package/lib/esm/server/http/response.d.ts

@@ -0,0 +1,4 @@
+import type { Stats } from "node:fs";
+import type { StaticResponse } from ".";
+export declare const fileResponse: (filename: string, stat?: Stats, status?: 200 | 404 | 500) => () => Promise<StaticResponse>;
+export declare const contentResponse: (content: string, contentType: string, status?: 200 | 404 | 500, headers?: Map<string, string>) => () => Promise<StaticResponse>;

package/lib/esm/server/http/response.js

@@ -0,0 +1,43 @@
+import * as fs from "node:fs/promises";
+const MIME_TYPES = {
+    js: "text/javascript",
+    ts: "text/javascript",
+    json: "text/javascript",
+    css: "text/css",
+    html: "text/html",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    svg: "image/svg+xml",
+    eot: "application/vnd.ms-fontobject",
+    ttf: "application/font-ttf",
+    woff: "application/font-woff",
+    woff2: "application/font-woff2",
+};
+const mime = (basename) => {
+    const extension = basename
+        .substring(basename.lastIndexOf(".") + 1)
+        .toLowerCase();
+    return (MIME_TYPES[extension] ??
+        "application/octet-stream");
+};
+export const fileResponse = (filename, stat, status = 200) => async () => {
+    if (!stat) {
+        stat = await fs.stat(filename);
+    }
+    const content = await fs.readFile(filename);
+    const contentType = mime(filename);
+    const contentLength = stat.size;
+    return { status, contentType, contentLength, content };
+};
+const CHARSET = "utf-8";
+export const contentResponse = (content, contentType, status = 200, headers = new Map()) => async () => {
+    const contentBuffer = Buffer.from(content, CHARSET);
+    return {
+        content: contentBuffer,
+        contentType: `${contentType.split(";")[0]}; charset=${CHARSET}`,
+        status,
+        contentLength: contentBuffer.length,
+        headers,
+    };
+};

package/lib/esm/server/http/sitemap.d.ts

@@ -0,0 +1,2 @@
+import type { MiddlewareFactory } from "./index.ts";
+export declare const sitemap: MiddlewareFactory;

package/lib/esm/server/http/sitemap.js

@@ -0,0 +1,22 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { info } from "../../log.js";
+import { contentResponse } from "./response.js";
+export const sitemap = async ({ root }) => {
+    const apps = [];
+    for await (const file of fs.glob("**/index.html", {
+        cwd: root,
+        withFileTypes: false,
+        exclude: (name) => name === "node_modules",
+    })) {
+        const index = `/${file.replaceAll(path.sep, "/")}`;
+        info("Adding to sitemap", { index });
+        apps.push(index);
+    }
+    return async (req) => {
+        if ((req.url ?? "").endsWith("sitemap.json")) {
+            return contentResponse(JSON.stringify(apps), "application/json");
+        }
+        return undefined;
+    };
+};

package/lib/esm/server/http/static.d.ts

@@ -0,0 +1,2 @@
+import type { MiddlewareFactory } from "./index.ts";
+export declare const staticFileServer: MiddlewareFactory;

package/lib/esm/server/http/static.js

@@ -0,0 +1,22 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { fileResponse } from "./response.js";
+export const staticFileServer = async ({ root, scopes = {} }) => async (req) => {
+    const scope = Object.entries(scopes).find(([s]) => req.url?.startsWith(`/${s}`));
+    const url = new URL(req.url ?? "", "http://localhost");
+    const pathname = scope
+        ? url.pathname.replace(scope[0], scope[1])
+        : url.pathname;
+    const filename = path.join(root, pathname);
+    try {
+        const stat = await fs.stat(filename);
+        return stat.isDirectory() ? undefined : fileResponse(filename, stat);
+    }
+    catch (e) {
+        if (e.code === "ENOENT") {
+            return fileResponse(filename, undefined, 404);
+        }
+        console.error(e);
+        return undefined;
+    }
+};

package/lib/esm/server/http/typescript.d.ts

@@ -0,0 +1,5 @@
+import type { MiddlewareFactory } from "./index.ts";
+/**
+ * Serves .js files statically. Finds .ts files and transpiles them to JS.
+ */
+export declare const tsFileServer: MiddlewareFactory;

package/lib/esm/server/http/typescript.js

@@ -0,0 +1,40 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { transpile } from "../../transpile.mjs";
+import { contentResponse } from "./response.js";
+function render(source, headers) {
+    // Replace `from "@scope` with `from "/@scope`, for browsers
+    source = source
+        .replaceAll(`from "@`, 'from "/@')
+        .replaceAll(`import("@`, 'import("/@');
+    return contentResponse(source, "application/javascript", 200, headers);
+}
+/**
+ * Serves .js files statically. Finds .ts files and transpiles them to JS.
+ */
+export const tsFileServer = async ({ root, scopes = {} }) => async (req) => {
+    if (req.url?.endsWith(".js") || req.url?.endsWith(".ts")) {
+        const scope = Object.entries(scopes).find(([s]) => req.url?.startsWith(`/${s}`));
+        // Expand url with found scope
+        const url = scope ? req.url.replace(scope[0], scope[1]) : req.url;
+        let filename = path.join(root, url);
+        const stat = await fs.stat(filename);
+        if (stat.isFile()) {
+            let js;
+            const headers = new Map();
+            if (filename.endsWith(".ts")) {
+                js = await transpile(filename, () => fs.readFile(filename));
+                headers.set("SourceMap", `${url}.map`);
+                js += `\n//# sourceURL=${url}`;
+            }
+            else {
+                if (url.endsWith(".ts.map")) {
+                    filename = filename.replace(/\.map$/, "");
+                }
+                js = (await fs.readFile(filename)).toString("utf-8");
+            }
+            return render(js, headers);
+        }
+    }
+    return undefined;
+};

package/lib/esm/server/live-reload.d.ts

@@ -0,0 +1,46 @@
+import { type MiddlewareFactory } from "./http/index.ts";
+export declare function webSocketReloadClient(path: string): string;
+export declare const htmlInjector: (snippet: string) => MiddlewareFactory;
+export declare const ignoreDefault: (file: string) => boolean;
+export declare function watchTree(dirs: string[], onChange: () => void, { debounceMs, ignore, }?: {
+    debounceMs?: number;
+    ignore?: (file: string) => boolean;
+}): {
+    close: () => void;
+};
+export declare function createRebuilder(rebuild: () => Promise<boolean>, onBuilt?: () => void): {
+    run: () => Promise<void>;
+    trigger: () => void;
+};
+export interface WatchServerOptions {
+    root: string;
+    watchDirs: string[];
+    rebuild: () => Promise<boolean>;
+    debounceMs?: number;
+    ignore?: (file: string) => boolean;
+    port?: number;
+    host?: string;
+    reloadPath?: string;
+}
+export declare function startWatchServer(opts: WatchServerOptions): Promise<{
+    port: number;
+    close: () => Promise<void>;
+}>;
+export interface JiffiesArgsParams {
+    port?: string;
+    host?: string;
+}
+export declare function jiffiesArgs(params?: JiffiesArgsParams): {
+    port: {
+        type: "string";
+        default: string;
+    };
+    host: {
+        type: "string";
+        default: string;
+    };
+    watch: {
+        type: "boolean";
+        default: false;
+    };
+};

package/lib/esm/server/live-reload.js

@@ -0,0 +1,161 @@
+import { watch } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { makeServer } from "./http/index.js";
+import { contentResponse } from "./http/response.js";
+import { attachWebSocketServer } from "./ws/index.js";
+// Live-reload feature for a (optionally watched) jiffies static dev server.
+// Shaped as stock jiffies middlewares + a generic watcher composed with the
+// ws/ transport, so a downstream server adds `--port`/`--host`/`--watch` via
+// jiffiesArgs and injects only its own build command and watched paths.
+// See .agents/developer/2026-06-10-A-upstream-livereload-client/design.md.
+// The injected client snippet opens a WebSocket to `path` and reloads the page
+// on any pushed message. On close it reconnects with a short fixed backoff,
+// which recovers from a server restart or a socket dropped during a rebuild.
+// Errors are swallowed; the close handler drives the reconnect. `path` is a
+// parameter so the caller owns the reload route.
+export function webSocketReloadClient(path) {
+    return `<script>(function(){function connect(){var ws=new WebSocket((location.protocol==="https:"?"wss://":"ws://")+location.host+${JSON.stringify(path)});ws.onmessage=function(){location.reload();};ws.onerror=function(){};ws.onclose=function(){setTimeout(connect,1000);};}connect();})();</script>`;
+}
+// Injects the reload snippet into HTML navigations. Mirrors jiffies findIndex
+// (walk up for index.html) for extensionless paths; serves .html directly.
+// Asset/CSS/TS requests fall through to the base middlewares.
+export const htmlInjector = (snippet) => async ({ root }) => async (req) => {
+    const { pathname } = new URL(req.url ?? "/", "http://localhost");
+    const decoded = decodeURIComponent(pathname);
+    const ext = path.extname(decoded);
+    let target;
+    if (ext === ".html") {
+        target = path.join(root, decoded);
+    }
+    else if (ext === "") {
+        let dir = path.join(root, decoded);
+        while (dir.startsWith(root)) {
+            const idx = path.join(dir, "index.html");
+            try {
+                if ((await fs.stat(idx)).isFile()) {
+                    target = idx;
+                    break;
+                }
+            }
+            catch { }
+            dir = path.dirname(dir);
+        }
+    }
+    if (!target)
+        return undefined;
+    try {
+        if (!(await fs.stat(target)).isFile())
+            return undefined;
+        const html = await fs.readFile(target, "utf-8");
+        const injected = html.includes("</body>")
+            ? html.replace("</body>", `${snippet}</body>`)
+            : html + snippet;
+        return contentResponse(injected, "text/html");
+    }
+    catch {
+        return undefined;
+    }
+};
+// Ignores dotfiles and node_modules. The argument is the full resolved path, so
+// callers can compose this with project-specific generated-output paths.
+export const ignoreDefault = (file) => /(^|[\\/])\./.test(file) || file.includes("node_modules");
+// Watches dirs recursively, coalescing bursts into a single trailing call. The
+// ignore predicate receives the resolved absolute path of each changed file, so
+// it can exclude build outputs written back into a watched dir (which would
+// otherwise retrigger the build endlessly).
+export function watchTree(dirs, onChange, { debounceMs = 150, ignore = ignoreDefault, } = {}) {
+    let timer;
+    const watchers = [];
+    for (const dir of dirs) {
+        try {
+            watchers.push(watch(dir, { recursive: true }, (_event, filename) => {
+                if (!filename)
+                    return;
+                if (ignore(path.join(dir, filename.toString())))
+                    return;
+                if (timer)
+                    clearTimeout(timer);
+                timer = setTimeout(onChange, debounceMs);
+            }));
+        }
+        catch {
+            // Directory may not exist; skip it.
+        }
+    }
+    return {
+        close: () => {
+            if (timer)
+                clearTimeout(timer);
+            for (const w of watchers)
+                w.close();
+        },
+    };
+}
+// Serializes rebuilds: a change during a build sets a dirty flag that triggers
+// exactly one more rebuild afterward. `onBuilt` runs once per successful rebuild
+// (each time the inner rebuild resolves true), letting the caller broadcast a
+// reload without the client needing a queryable build id.
+export function createRebuilder(rebuild, onBuilt) {
+    let building = false;
+    let dirty = false;
+    const run = async () => {
+        if (building) {
+            dirty = true;
+            return;
+        }
+        building = true;
+        try {
+            do {
+                dirty = false;
+                if (await rebuild())
+                    onBuilt?.();
+            } while (dirty);
+        }
+        finally {
+            building = false;
+        }
+    };
+    return { run, trigger: () => void run() };
+}
+// Initial build, then serve `root` with the injector middleware, attach a
+// WebSocket hub at reloadPath, and watch `watchDirs`. Each successful rebuild
+// broadcasts "reload" to connected clients. Returns the bound port and a
+// close() for clean shutdown. The hub is late-bound: the initial build runs
+// before it exists, so its onBuilt broadcast is a no-op (no clients yet).
+export async function startWatchServer(opts) {
+    const reloadPath = opts.reloadPath ?? "/__livereload";
+    let hub;
+    const rebuilder = createRebuilder(opts.rebuild, () => hub?.broadcast("reload"));
+    await rebuilder.run();
+    const snippet = webSocketReloadClient(reloadPath);
+    const server = await makeServer({ root: opts.root }, [htmlInjector(snippet)]);
+    const watchOpts = {};
+    if (opts.debounceMs !== undefined)
+        watchOpts.debounceMs = opts.debounceMs;
+    if (opts.ignore !== undefined)
+        watchOpts.ignore = opts.ignore;
+    const watcher = watchTree(opts.watchDirs, rebuilder.trigger, watchOpts);
+    await new Promise((resolve) => server.listen(opts.port ?? 8080, opts.host ?? "127.0.0.1", resolve));
+    hub = attachWebSocketServer(server, { path: reloadPath });
+    const address = server.address();
+    return {
+        port: address.port,
+        close: () => new Promise((resolve) => {
+            hub?.close();
+            watcher.close();
+            server.close(() => resolve());
+        }),
+    };
+}
+// A parseArgs `options` fragment for launching a (optionally watched) jiffies
+// static server. Spread into a downstream's parseArgs options so it owns the
+// entrypoint and the `values.watch` branch. `params` overrides the port/host
+// defaults; `watch` defaults to false.
+export function jiffiesArgs(params) {
+    return {
+        port: { type: "string", default: params?.port ?? "8080" },
+        host: { type: "string", default: params?.host ?? "0.0.0.0" },
+        watch: { type: "boolean", default: false },
+    };
+}

package/lib/esm/server/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/{src/server/main.ts → lib/esm/server/main.js}

@@ -1,30 +1,23 @@
 #!/usr/bin/env node
 import * as process from "node:process";
-
-import { info } from "../log.ts";
-
+import { info } from "../log.js";
 info("Starting server", { cwd: process.cwd() });
-
 import { parseArgs } from "node:util";
-
 // Declared up front so an unknown flag fails fast: parseArgs defaults to
 // strict: true, which throws on undeclared options. The throw happens at module
 // top level (before main() listens), so a malformed invocation exits non-zero
 // and never reaches the listening state. With no flags the defaults reproduce
 // the prior bind target (0.0.0.0:8080).
 const { values } = parseArgs({
-  options: {
-    port: { type: "string", default: "8080" },
-    host: { type: "string", default: "0.0.0.0" },
-  },
+    options: {
+        port: { type: "string", default: "8080" },
+        host: { type: "string", default: "0.0.0.0" },
+    },
 });
-
 import * as path from "node:path";
-import { makeServer } from "./http/index.ts";
-
+import { makeServer } from "./http/index.js";
 async function main() {
-  const server = await makeServer({ root: path.join(process.cwd(), "src") });
-  server.listen(Number.parseInt(values.port, 10), values.host);
+    const server = await makeServer({ root: path.join(process.cwd(), "src") });
+    server.listen(Number.parseInt(values.port, 10), values.host);
 }
-
 main();

package/lib/esm/server/ws/frame.d.ts

@@ -0,0 +1,2 @@
+export declare function encodeTextFrame(text: string): Buffer;
+export declare function readOpcode(buffer: Buffer): number | undefined;

package/lib/esm/server/ws/frame.js

@@ -0,0 +1,35 @@
+// Encodes `text` as a single unmasked server->client WebSocket text frame:
+// FIN set + opcode 0x1 => first byte 0x81; mask bit clear; 7-bit / 16-bit /
+// 64-bit extended payload-length selection by utf8 byte count. Server-to-client
+// frames are never masked (RFC 6455).
+export function encodeTextFrame(text) {
+    const payload = Buffer.from(text, "utf-8");
+    const length = payload.length;
+    const fin = 0x81; // FIN set, opcode 0x1 (text).
+    let header;
+    if (length < 126) {
+        header = Buffer.from([fin, length]);
+    }
+    else if (length <= 0xffff) {
+        header = Buffer.alloc(4);
+        header[0] = fin;
+        header[1] = 0x7e;
+        header.writeUInt16BE(length, 2);
+    }
+    else {
+        header = Buffer.alloc(10);
+        header[0] = fin;
+        header[1] = 0x7f;
+        header.writeBigUInt64BE(BigInt(length), 2);
+    }
+    return Buffer.concat([header, payload]);
+}
+// Reads the opcode nibble of an inbound (client, masked) frame for control-frame
+// handling: 0x1 text, 0x8 close, 0x9 ping, 0xA pong, etc. Returns undefined for a
+// partial/unreadable buffer. Does NOT decode the masked payload.
+export function readOpcode(buffer) {
+    if (buffer.length === 0) {
+        return undefined;
+    }
+    return buffer[0] & 0x0f;
+}

package/lib/esm/server/ws/handshake.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+export declare function acceptKey(secWebSocketKey: string): string;
+export declare function completeHandshake(req: IncomingMessage, socket: Duplex): boolean;

package/lib/esm/server/ws/handshake.js

@@ -0,0 +1,32 @@
+import { createHash } from "node:crypto";
+// The fixed GUID concatenated to the client key before hashing, per RFC 6455.
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+// base64( SHA-1( key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11" ) ), per RFC 6455.
+// Pure function of the client's Sec-WebSocket-Key.
+export function acceptKey(secWebSocketKey) {
+    return createHash("sha1")
+        .update(secWebSocketKey + WS_GUID)
+        .digest("base64");
+}
+// Validates the upgrade request, writes the "101 Switching Protocols" response
+// (Upgrade: websocket, Connection: Upgrade, Sec-WebSocket-Accept: acceptKey(...))
+// to the raw socket, and returns true. Returns false WITHOUT writing on a
+// malformed upgrade (missing/non-"websocket" Upgrade header or missing
+// Sec-WebSocket-Key), leaving the socket for the caller to destroy.
+export function completeHandshake(req, socket) {
+    const key = req.headers["sec-websocket-key"];
+    const upgrade = req.headers.upgrade;
+    if (typeof key !== "string" || key.length === 0) {
+        return false;
+    }
+    if (typeof upgrade !== "string" || upgrade.toLowerCase() !== "websocket") {
+        return false;
+    }
+    const response = "HTTP/1.1 101 Switching Protocols\r\n" +
+        "Upgrade: websocket\r\n" +
+        "Connection: Upgrade\r\n" +
+        `Sec-WebSocket-Accept: ${acceptKey(key)}\r\n` +
+        "\r\n";
+    socket.write(response);
+    return true;
+}

package/lib/esm/server/ws/index.d.ts

@@ -0,0 +1,14 @@
+import type { Server } from "node:http";
+import type { Duplex } from "node:stream";
+export interface WebSocketHub {
+    broadcast(text: string): void;
+    readonly size: number;
+    close(): void;
+}
+export interface AttachOptions {
+    path: string;
+    onConnection?: (socket: Duplex) => void;
+}
+export declare function attachWebSocketServer(server: Server, options: AttachOptions): WebSocketHub;
+export { encodeTextFrame, readOpcode } from "./frame.ts";
+export { acceptKey, completeHandshake } from "./handshake.ts";