0.0.151 - Add middleware support with built-in compression and documentation

Author: metabench

.github/instructions/copilot.instructions.md

@@ -176,5 +176,6 @@ model.count++;  // Triggers change event
 | Comprehensive API | `docs/comprehensive-documentation.md` |
 | Control development | `docs/controls-development.md` |
 | Publisher system | `docs/publishers-guide.md` |
+| Middleware & compression | `docs/middleware-guide.md` |
 | Troubleshooting | `docs/troubleshooting.md` |
 | **Broken stuff** | `docs/agent-development-guide.md` |

AGENTS.md

@@ -19,6 +19,7 @@
 - **[docs/controls-development.md](docs/controls-development.md)** - Guide for developing custom JSGUI3 controls
 - **[docs/publishers-guide.md](docs/publishers-guide.md)** - Guide for publishers and content serving
 - **[docs/resources-guide.md](docs/resources-guide.md)** - Guide for resources and data abstraction
+- **[docs/middleware-guide.md](docs/middleware-guide.md)** - Middleware pipeline and built-in compression middleware
 
 ### Specialized Documentation
 - **[docs/GUIDE_TO_AGENTIC_WORKFLOWS_BY_GROK.md](docs/GUIDE_TO_AGENTIC_WORKFLOWS_BY_GROK.md)** - Comprehensive guide to agentic workflows and autonomous task execution
@@ -61,6 +62,7 @@
 - **Custom control development** → `docs/controls-development.md`
 - **Publisher system** → `docs/publishers-guide.md`
 - **Resource management** → `docs/resources-guide.md`
+- **Middleware and compression** → `docs/middleware-guide.md`
 - **Admin UI extensions** → `docs/admin-extension-guide.md`
 
 ### Agent Development

README.md

@@ -298,6 +298,61 @@ jsgui.Admin_User_Store
 
 See [Admin Extension Guide](docs/admin-extension-guide.md) for detailed API reference.
 
+## Middleware
+
+jsgui3-server includes an Express-style `server.use()` middleware pipeline. Middleware runs before every request reaches the router.
+
+### Built-in Compression
+
+Enable gzip/deflate/brotli compression for JSON, HTML, CSS, and JS responses:
+
+```javascript
+const { compression } = require('jsgui3-server/middleware');
+
+const server = new Server({ Ctrl: MyControl, src_path_client_js: __dirname + '/client.js' });
+server.use(compression());
+server.on('ready', () => server.start(8080));
+```
+
+Or via `Server.serve()`:
+
+```javascript
+Server.serve({
+    Ctrl: MyControl,
+    compression: true,   // enable with defaults
+    port: 8080
+});
+
+// With options:
+Server.serve({
+    Ctrl: MyControl,
+    compression: { threshold: 512 },
+    port: 8080
+});
+```
+
+### Custom Middleware
+
+```javascript
+// Request logger
+server.use((req, res, next) => {
+    console.log(`${req.method} ${req.url}`);
+    next();
+});
+
+// Multiple middleware via Server.serve()
+Server.serve({
+    Ctrl: MyControl,
+    middleware: [
+        (req, res, next) => { console.log(req.url); next(); },
+        compression({ threshold: 512 })
+    ],
+    port: 8080
+});
+```
+
+See [Middleware Guide](docs/middleware-guide.md) for the full API reference and response-wrapping patterns.
+
 ## Architecture Overview
 
 The server operates as a bridge between server-side JavaScript applications and browser clients, offering:

docs/api-reference.md

@@ -151,17 +151,91 @@ server.close(callback?: (err?: Error | null) => void): void
 - Stops `sse_publisher` when present
 - Closes all HTTP listeners
 
-### server.use(middleware)
+### server.use(fn)
 
-Adds middleware to the server.
+Register middleware to run before every request is routed. Middleware is executed
+in registration order. The chain runs to completion before the router processes
+the request.
 
 **Signature:**
 ```javascript
-server.use(middleware: Function): void
+server.use(fn: Function): Server   // returns `this` for chaining
 ```
 
 **Parameters:**
-- `middleware` (Function): Express-style middleware function
+- `fn` (Function): Middleware function with signature `(req, res, next) => void`
+  - `req` — Node.js `http.IncomingMessage`
+  - `res` — Node.js `http.ServerResponse`
+  - `next` — Call `next()` to continue to the next middleware / router.
+    Call `next(err)` to skip remaining middleware and trigger the error handler
+    (500 response).
+
+**Returns:** The server instance (for chaining).
+
+**Throws:** `Error` if `fn` is not a function.
+
+**Example:**
+```javascript
+const { compression } = require('jsgui3-server/middleware');
+
+server
+    .use((req, res, next) => {
+        console.log(`${req.method} ${req.url}`);
+        next();
+    })
+    .use(compression());
+```
+
+**Execution order:**
+```
+HTTP Request → middleware[0] → middleware[1] → … → router
+```
+
+If no middleware is registered, the router is called directly with zero overhead.
+
+**See also:** [Middleware Guide](middleware-guide.md) for response-wrapping
+patterns, custom middleware examples, and the built-in compression reference.
+
+---
+
+### Built-in Middleware
+
+#### `compression([options])`
+
+Response-compression middleware. Transparently compresses response bodies
+(gzip / deflate / brotli) when the client supports it and the content type
+is compressible.
+
+```javascript
+const { compression } = require('jsgui3-server/middleware');
+server.use(compression());                    // defaults
+server.use(compression({ threshold: 512 }));  // lower threshold
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|-----------|--------|---------------------------|-------------------------------------------|
+| `threshold` | number | `1024` | Minimum body size in bytes to compress |
+| `level` | number | `Z_DEFAULT_COMPRESSION` | zlib compression level (1–9, or -1) |
+
+**Encoding priority:** gzip → deflate → brotli
+
+**Compressible types:** `application/json`, `text/html`, `text/plain`,
+`text/css`, `text/xml`, `text/csv`, `text/javascript`,
+`application/javascript`, `application/xml`, `application/xhtml+xml`,
+`application/manifest+json`, `image/svg+xml`.
+
+**Not compressed:** bodies below threshold, binary content types, responses
+with an existing `Content-Encoding`, and streaming responses (`res.write()`
+before `res.end()` — e.g. SSE).
+
+**Access paths:**
+```javascript
+require('jsgui3-server/middleware').compression   // direct
+require('jsgui3-server').middleware.compression    // via module
+Server.middleware.compression                      // via class
+```
 
 ## Port Utilities
 
@@ -928,10 +1002,16 @@ interface ServerOptions {
   api?: Record<string, Function>;
   static?: Record<string, string>;
 
+  // Middleware & compression
+  middleware?: Function | Function[];   // (req, res, next) middleware functions
+  compression?: boolean | {             // Enable built-in compression middleware
+      threshold?: number;               //   Min body size to compress (default 1024)
+      level?: number;                   //   zlib level (default Z_DEFAULT_COMPRESSION)
+  };
+
   // Advanced options
   cors?: CorsConfig;
   https?: HttpsConfig;
-  middleware?: Function[];
   publishers?: Record<string, Publisher>;
   resources?: ResourceEntries;
   events?: boolean | EventsOptions;

docs/comprehensive-documentation.md

@@ -1110,7 +1110,7 @@ const server = Server.serve({
     debug: false,  // Disable for production
     // Additional production settings
     max_age: 86400,  // Cache static assets for 24 hours
-    compress: true    // Enable gzip compression
+    compression: true    // Enable gzip/deflate/brotli compression
 });
 ```
 
@@ -1300,8 +1300,8 @@ Server.serve({
     src_path_client_js: require.resolve('./client.js'),
     // Cache static assets
     max_age: 86400,  // 24 hours
-    // Enable compression
-    compress: true,
+    // Enable compression (gzip/deflate/brotli via built-in middleware)
+    compression: true,
     // Optimize bundling
     debug: false
 });

docs/configuration-reference.md

@@ -486,16 +486,16 @@ Server.serve({
 });
 ```
 
-### Middleware
+### `middleware`
+- **Type:** `Function | Function[]`
+- **Description:** One or more Express-style middleware functions `(req, res, next)` to run before every request reaches the router. Middleware is executed in array order.
 
 ```javascript
-const express = require('express');
-const compression = require('compression');
+const { compression } = require('jsgui3-server/middleware');
 
 Server.serve({
     middleware: [
-        compression(),
-        express.json({ limit: '10mb' }),
+        compression({ threshold: 512 }),
         (req, res, next) => {
             console.log(`${req.method} ${req.url}`);
             next();
@@ -504,6 +504,29 @@ Server.serve({
 });
 ```
 
+### `compression`
+- **Type:** `boolean | Object`
+- **Description:** Convenience shorthand that enables the built-in response-compression middleware. Pass `true` for defaults or an options object.
+- **Default:** Disabled (no compression)
+
+| Sub-option | Type | Default | Description |
+|------------|--------|---------------------------|--------------------------------------------|
+| `threshold` | number | `1024` | Minimum body size (bytes) to compress |
+| `level` | number | `Z_DEFAULT_COMPRESSION` | zlib compression level (1–9, or -1 for default) |
+
+```javascript
+// Enable with defaults (1024 byte threshold, gzip preferred)
+Server.serve({ compression: true });
+
+// Enable with custom options
+Server.serve({ compression: { threshold: 256, level: 6 } });
+```
+
+> **Note:** `compression` and `middleware` can be used together. The `middleware` array runs first (in order), then the compression middleware is appended.
+
+See [Middleware Guide](middleware-guide.md) for the full API, response-wrapping patterns, and custom middleware examples.
+```
+
 ## Configuration Validation
 
 ### Type Checking