jsgui3-server 0.0.150 → 0.0.152

package/.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` |

package/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

package/README.md

@@ -33,6 +33,27 @@ Server.serve(MyControl);
 Server.serve(MyControl, { port: 3000 });
 ```
 
+### Port Conflict Fallback
+
+```javascript
+Server.serve({
+  Ctrl: MyControl,
+  port: 52000,
+  on_port_conflict: 'auto-loopback' // retry on 127.0.0.1 with a free port
+});
+```
+
+With manual `server.start(...)`, you can print the effective endpoint:
+
+```javascript
+server.start(52000, (err) => {
+  if (err) throw err;
+  server.print_endpoints({ include_index: true });
+}, {
+  on_port_conflict: 'auto-loopback'
+});
+```
+
 ### Single Page with Metadata
 
 ```javascript
@@ -170,9 +191,9 @@ sse_publisher.broadcast('resource_update', { running: 3, total: 5 });
 
 ## Admin UI Dashboard
 
-Every jsgui3-server instance includes a built-in admin dashboard at `/admin/v1` with live stats, resource inspection, route listing, and SSE-driven heartbeat updates. The dashboard is session-authenticated (default dev credentials: `admin` / `admin`).
-
-The admin shell is implemented with jsgui controls for navigation and dynamic panel rendering (control-first composition), and is covered by the interaction regression suite in `tests/admin-ui-jsgui-controls.test.js`.
+Every jsgui3-server instance includes a built-in admin dashboard at `/admin/v1` with live stats, resource inspection, route listing, and SSE-driven heartbeat updates. The dashboard is session-authenticated (default dev credentials: `admin` / `admin`).
+
+The admin shell is implemented with jsgui controls for navigation and dynamic panel rendering (control-first composition), and is covered by the interaction regression suite in `tests/admin-ui-jsgui-controls.test.js`.
 
 ### Disabling the Admin UI
 
@@ -219,10 +240,10 @@ server.admin_v1.add_endpoint({
 });
 ```
 
-### Plugin Pattern
+### Plugin Pattern
 
 ```javascript
-server.admin_v1.use((admin) => {
+server.admin_v1.use((admin) => {
     admin.add_section({
         id: 'logs',
         label: 'Logs',
@@ -233,14 +254,14 @@ server.admin_v1.use((admin) => {
             res.end(JSON.stringify({ recent: ['log1', 'log2'] }));
         }
     });
-});
-```
-
-### Admin UI Regression Test
-
-```bash
-node tests/test-runner.js --test=admin-ui-jsgui-controls.test.js
-```
+});
+```
+
+### Admin UI Regression Test
+
+```bash
+node tests/test-runner.js --test=admin-ui-jsgui-controls.test.js
+```
 
 ### Declarative Configuration via `Server.serve()`
 
@@ -298,6 +319,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: