feat!: single entry point and add examples

- Remove subpath exports from package.json, keeping only the root @panmdaa/server entry
- Update all docs and README imports to use the root entry
- Restrict tsup to the root entry
- Add self-contained, runnable examples grouped by directory

Author: kkokotero

CONTRIBUTING.md

@@ -12,7 +12,7 @@ Thank you for considering contributing to `@panmdaa/server`.
 - `docs/` — architecture, usage, and subsystem documentation.
 - `.github/workflows/` — CI and release automation.
 
-Public entry points use subpath exports — `@panmdaa/server/http`, `@panmdaa/server/router`, `@panmdaa/server/ws`, `@panmdaa/server/middleware`, `@panmdaa/server/error` — with the root `@panmdaa/server` re-exporting everything.
+The package exposes a single entry point — `@panmdaa/server` — which re-exports everything (`error`, `http`, `middleware`, `router`, `ws`).
 
 ## Ways To Contribute
 
@@ -30,7 +30,7 @@ For larger changes, open an issue first so we can align on scope, API design, an
 
 Changes that should usually be discussed first:
 
-- new public exports or subpath imports
+- new public exports
 - changes to core internal algorithms or data structures
 - changes to public function signatures or return types
 - adding runtime dependencies

README.md

@@ -32,10 +32,9 @@ npm install @panmdaa/server
 ## Quick look
 
 ```ts
-import { Server } from "@panmdaa/server/http";
-import { Router } from "@panmdaa/server/router";
-import { cors, securityHeaders } from "@panmdaa/server/middleware";
-import { NotFound } from "@panmdaa/server/error";
+import {
+  Server, Router, cors, securityHeaders, NotFound,
+} from "@panmdaa/server";
 
 // Compose routers, mount them on a server
 const users = new Router();
@@ -68,14 +67,14 @@ server.ws("/live", ({ socket }) => {
 server.listen(3000);
 ```
 
-> **Modular imports**: each domain has its own subpath — `@panmdaa/server/http`, `@panmdaa/server/router`, `@panmdaa/server/middleware`, `@panmdaa/server/error`, `@panmdaa/server/ws` — and the root `@panmdaa/server` re-exports everything. See [Development](docs/development/tooling.md).
+> **Single entry point**: everything — `Server`, `Router`, middleware, errors, WebSocket helpers — is exported from `@panmdaa/server`. See [Development](docs/development/tooling.md).
 
 ## Routing
 
 Verbs, params, wildcards and composition — all type-checked at compile time:
 
 ```ts
-import { Server } from "@panmdaa/server/http";
+import { Server } from "@panmdaa/server";
 
 const server = new Server();
 
@@ -117,8 +116,7 @@ Optional segments are expanded into concrete routes at registration; matching ne
 Middleware is compiled into a single function per route — conditional `await`, shared `next`, short-circuit. It's baked into each route **at registration time**:
 
 ```ts
-import { Server } from "@panmdaa/server/http";
-import { cors, securityHeaders } from "@panmdaa/server/middleware";
+import { Server, cors, securityHeaders } from "@panmdaa/server";
 
 const server = new Server();
 
@@ -146,8 +144,7 @@ Two contracts make the chain work (see [handler compilation](docs/http/handler-c
 Path-only matching in a separate tree — `server.ws("/*")` never shadows HTTP routes. Zero-alloc parsing, zero-copy writes, `cork`'d coalescing:
 
 ```ts
-import { Server } from "@panmdaa/server/http";
-import { createWebSocketHeartbeat, CloseCode } from "@panmdaa/server/ws";
+import { Server, createWebSocketHeartbeat, CloseCode } from "@panmdaa/server";
 
 const heartbeat = createWebSocketHeartbeat({ intervalMs: 30_000, timeoutMs: 10_000 });
 
@@ -178,7 +175,7 @@ One code path for HTTP/1, HTTP/2 and WebSocket-over-HTTP/2:
 
 ```ts
 import { readFileSync } from "node:fs";
-import { Server } from "@panmdaa/server/http";
+import { Server } from "@panmdaa/server";
 
 const server = new Server({
   http2: true,                                    // h2c, or with tls → ALPN
@@ -198,7 +195,7 @@ Throw typed errors, get mapped responses — unknown errors become 500 automatic
 import {
   HttpError, NotFound, BadRequest,
   MethodNotAllowed, PayloadTooLarge, UnsupportedMediaType,
-} from "@panmdaa/server/error";
+} from "@panmdaa/server";
 
 server.get("/user/:id", ({ params }) => {
   throw new NotFound();
@@ -230,7 +227,7 @@ server.post("/api/echo", async ({ body, response }) => {
 
 ## API
 
-> **Modular imports**: `Server`, contexts and handler compilation live in `@panmdaa/server/http`; `Router`/`RadixTree` in `@panmdaa/server/router`; the WebSocket stack in `@panmdaa/server/ws`; errors in `@panmdaa/server/error`; middleware in `@panmdaa/server/middleware`. The root `@panmdaa/server` re-exports everything.
+> **Single entry point**: everything — `Server`, contexts, handler compilation, `Router`/`RadixTree`, the WebSocket stack, errors, middleware — is exported from `@panmdaa/server`.
 
 | Member | Description |
 |--------|-------------|

docs/architecture/overview.md

@@ -79,21 +79,14 @@ Both engines follow the same allocation discipline:
 - No logging, no cluster, no static file server (files are streamed with `pipeline`, but there is no middleware doing directory listing).
 - No room/channel management for WebSockets — that is app-level.
 
-## Public entry points
+## Public entry point
 
-The package exposes **modular subpath imports** (`package.json` `exports`): each domain is importable on its own, and the root barrel re-exports everything.
-
-| Import | Surface |
-|--------|---------|
-| `@panmdaa/server` | everything (root barrel, `src/index.ts`) |
-| `@panmdaa/server/error` | `HttpError`, `isHttpError`, status classes |
-| `@panmdaa/server/router` | `Router`, `RadixTree`, `Path` types |
-| `@panmdaa/server/http` | `Server`, contexts, `compileHandler`, `ResponseContext` |
-| `@panmdaa/server/ws` | `WebSocketConnection`, handshake, frame, compression, heartbeat |
-| `@panmdaa/server/middleware` | `cors`, `securityHeaders` |
+The package exposes a **single entry point** (`package.json` `exports`): `@panmdaa/server`, a root barrel (`src/index.ts`) re-exporting every domain.
 
 ```ts
-import { Server } from "@panmdaa/server/http";
-import { cors } from "@panmdaa/server/middleware";
-import { NotFound } from "@panmdaa/server/error";
+import {
+  Server, Router, cors, NotFound,
+} from "@panmdaa/server";
 ```
+
+The `error`, `http`, `middleware`, `router` and `ws` barrels are internal and reachable only through the root export.

docs/development/tooling.md

@@ -25,24 +25,19 @@ Run it via `npm run build` (or `node scripts/run-all.mjs`).
 
 ## Build
 
-- `tsup.config.ts`: entry `src/**/*.ts`, `esnext`, **ESM only**, `minify: true`, `bundle: true`, `treeshake: true`, `clean: true`. tsup preserves the `src/` directory structure in `dist/`, which is what the subpath exports rely on.
+- `tsup.config.ts`: entry `src/**/*.ts`, `esnext`, **ESM only**, `minify: true`, `bundle: true`, `treeshake: true`, `clean: true`. tsup preserves the `src/` directory structure in `dist/`.
 - `tsconfig.build.json`: `emitDeclarationOnly`, `outDir: dist`, `rootDir: src` — tsup emits JS, tsc emits `.d.ts` with the same structure.
 
-## Public entry points (modular imports)
+## Public entry point
 
-`package.json` `exports` defines the public surface. Each domain is a subpath; the root re-exports everything:
+`package.json` `exports` defines the public surface — a **single entry point** that re-exports every domain:
 
-| Subpath | `dist/` target | Surface |
-|---------|----------------|---------|
+| Export | `dist/` target | Surface |
+|--------|----------------|---------|
 | `.` | `index.js` / `index.d.ts` | root barrel (`export *` from all sub-barrels) |
-| `./error` | `error/index.js` | errors |
-| `./http` | `http/index.js` | contexts, handler, server |
-| `./middleware` | `middleware/index.js` | cors, securityHeaders |
-| `./router` | `router/index.js` | router, radix-tree |
-| `./ws` | `ws/index.js` | WebSocket stack |
 | `./package.json` | `package.json` | tooling convenience |
 
-Adding a new public module means: (1) create its `src/<name>/index.ts` barrel, (2) add a matching `exports` entry in `package.json`, (3) `export *` it from `src/index.ts` if it should also be in the root barrel.
+Adding a new public module means: (1) create its `src/<name>/index.ts` barrel, (2) `export *` it from `src/index.ts`.
 
 > `src/index.ts` is a clean barrel — it must **never** contain executable code (no `new Server()`, no `listen()`), or importing the package would boot a server.
 

docs/usage/README.md

@@ -19,7 +19,7 @@ For the internals (why things work this way, what runs when), see the [architect
 ## Key concepts in one minute
 
 ```ts
-import { Server } from "@panmdaa/server/http";
+import { Server } from "@panmdaa/server";
 
 const server = new Server();
 
@@ -37,4 +37,4 @@ server.listen(3000);
 - `ctx.body` (JSON, form, raw, stream) is available only on body-capable routes (`POST/PUT/PATCH/DELETE/QUERY`).
 - WebSockets live in their own tree: `server.ws("/path", handler)`.
 
-**Imports are modular**: each domain has its own subpath — `@panmdaa/server/http` (Server, contexts), `@panmdaa/server/router`, `@panmdaa/server/ws`, `@panmdaa/server/middleware`, `@panmdaa/server/error` — and the root `@panmdaa/server` re-exports everything. See [Development](../development/tooling.md).
+**One entry point**: everything — `Server`, `Router`, middleware, WebSockets, errors — is exported from `@panmdaa/server`. See [Development](../development/tooling.md).

docs/usage/best-practices.md

@@ -6,19 +6,19 @@ How to structure a real app with `@panmdaa/server` the way it was designed to be
 
 ```ts
 // routes/users.ts
-import { Router } from "@panmdaa/server/router";
+import { Router } from "@panmdaa/server";
 export const users = new Router();
 users.get("/", listUsers);
 users.get("/:id", getUser);
 users.post("/", createUser);
 
 // routes/chat.ts
-import { Router } from "@panmdaa/server/router";
+import { Router } from "@panmdaa/server";
 export const chat = new Router();
 chat.ws("/live", chatHandler);
 
 // app.ts
-import { Server } from "@panmdaa/server/http";
+import { Server } from "@panmdaa/server";
 import { users } from "./routes/users";
 import { chat } from "./routes/chat";
 
@@ -66,7 +66,7 @@ server.get("/me", ({ state, response }) => {
 ## 5. Throw typed errors, don't hand-build 500s
 
 ```ts
-import { NotFound, BadRequest } from "@panmdaa/server/error";
+import { NotFound, BadRequest } from "@panmdaa/server";
 
 server.get("/user/:id", async ({ params, response }) => {
   const user = await db.findUser(params.id);
@@ -100,7 +100,7 @@ Don't parse the body in middleware for routes that don't need it — parsing is
 ## 7. WebSocket: track, broadcast, close
 
 ```ts
-import { createWebSocketHeartbeat } from "@panmdaa/server/ws";
+import { createWebSocketHeartbeat } from "@panmdaa/server";
 
 const clients = new Set();
 const heartbeat = createWebSocketHeartbeat();

docs/usage/getting-started.md

@@ -13,7 +13,7 @@ Requires Node.js >= 18 (`package.json` `engines`). Pure ESM — use `import`, no
 ## Your first server
 
 ```ts
-import { Server } from "@panmdaa/server/http";
+import { Server } from "@panmdaa/server";
 
 const server = new Server();
 
@@ -76,7 +76,7 @@ WebSocket routes match by **path only** and live in a separate tree — `/*` won
 Throw `HttpError` subclasses (or build your own) and the server maps them:
 
 ```ts
-import { NotFound } from "@panmdaa/server/error";
+import { NotFound } from "@panmdaa/server";
 
 server.get("/teapot", () => {
   throw new NotFound();

docs/usage/http.md

@@ -165,7 +165,7 @@ server.get("/old", ({ response }) => {
 ## Errors
 
 ```ts
-import { NotFound, BadRequest } from "@panmdaa/server/error";
+import { NotFound, BadRequest } from "@panmdaa/server";
 
 server.get("/nope", () => {
   throw new NotFound();

docs/usage/http2.md

@@ -4,7 +4,7 @@
 
 ```ts
 import { readFileSync } from "node:fs";
-import { Server } from "@panmdaa/server/http";
+import { Server } from "@panmdaa/server";
 
 const server = new Server({
   tls: {

docs/usage/websockets.md

@@ -86,7 +86,7 @@ const server = new Server({
 Dead connections (dropped network, powered-off clients) never send a close frame. Track sockets to close them after a timeout:
 
 ```ts
-import { createWebSocketHeartbeat } from "@panmdaa/server/ws";
+import { createWebSocketHeartbeat } from "@panmdaa/server";
 
 const heartbeat = createWebSocketHeartbeat({ intervalMs: 30_000, timeoutMs: 10_000 });