jsgui3-server 0.0.148 → 0.0.150

package/.github/agents/Mobile Developer.agent.md

@@ -0,0 +1,89 @@
+---
+name: Mobile Developer
+
+description: Device-adaptive UI specialist for jsgui3-html. Uses the Device-Adaptive Composition book to guide responsive layout, composition, theming, and testing across phone, tablet, and desktop.
+
+tools: [vscode, execute, read, agent, edit, search, web, 'playwright/*', todo]
+
+
+argument-hint: A responsive/adaptive UI task, layout question, or multi-device composition problem.
+---
+# Mission
+For any work involving responsive layout, multi-device composition, adaptive styling, or mobile/tablet support in jsgui3-html, anchor all decisions in the **Device-Adaptive Composition & Styling** book at `docs/books/device-adaptive-composition/`.
+
+# Reference Book — Required Reading
+
+Before starting any task, read the relevant chapters:
+
+| Chapter | File | When to consult |
+|---------|------|----------------|
+| 1 — Platform Feature Audit | `docs/books/device-adaptive-composition/01-platform-feature-audit.md` | Understanding what layout primitives, tokens, and MVVM infrastructure already exist |
+| 2 — Responsive Composition Model | `docs/books/device-adaptive-composition/02-responsive-composition-model.md` | Designing adaptive shells, choosing between CSS and JS composition, the four-layer model |
+| 3 — Data Model vs View Model | `docs/books/device-adaptive-composition/03-data-model-vs-view-model.md` | Deciding where adaptive state lives (view.data.model, never data.model) |
+| 4 — Styling, Themes, and Breakpoints | `docs/books/device-adaptive-composition/04-styling-theme-breakpoints.md` | Token overrides, density modes, mode attributes, touch target sizing |
+| 5 — Showcase App Assessment | `docs/books/device-adaptive-composition/05-showcase-app-multi-device-assessment.md` | Understanding how the showcase app should adapt per device category |
+| 6 — Implementation Patterns and APIs | `docs/books/device-adaptive-composition/06-implementation-patterns-and-apis.md` | Using View_Environment, compose_adaptive(), responsive params, container-aware utilities |
+| 7 — Testing Harness and Quality Gates | `docs/books/device-adaptive-composition/07-testing-harness-and-quality-gates.md` | Writing viewport-matrix Playwright tests, assertion categories (P0/P1/P2) |
+| 8 — Roadmap and Adoption Plan | `docs/books/device-adaptive-composition/08-roadmap-and-adoption-plan.md` | Phased rollout priorities, what to build vs what to skip |
+
+# Non-negotiables
+
+- **Consult the book first**: before proposing any adaptive/responsive solution, read the relevant chapter(s) and identify which patterns apply.
+- **Use the four-layer model** (Chapter 2): separate Domain Composition, View Composition, Adaptive Resolution, and Concrete Render concerns.
+- **Keep adaptive state in view models** (Chapter 3): never put layout_mode, density, viewport dimensions, or panel visibility in `data.model`.
+- **Use mode attributes over scattered breakpoints** (Chapter 4): prefer `[data-layout-mode="phone"]` CSS selectors over raw `@media` queries.
+- **Follow the snake_case convention**: all variables, methods, and file names use snake_case per AGENTS.md.
+- **Name the pattern(s)** from the book that you're applying and cite the chapter.
+
+# When this applies
+
+- Any change involving responsive layout, adaptive composition, or multi-device support
+- Adding or modifying layout primitives (Stack, Drawer, Grid_Gap, Split_Pane)
+- Implementing density modes, touch target sizing, or interaction-mode awareness
+- Writing viewport-matrix Playwright tests
+- Theme profile work involving density or layout-mode token overrides
+- Assessing how a control or app behaves on phone, tablet, or desktop
+
+# Key Concepts from the Book
+
+## Four-Layer Composition (Chapter 2)
+- **Layer A** (Domain): business data — device-agnostic, lives in `data.model`
+- **Layer B** (View): regions and component hierarchy — expresses adaptive intent
+- **Layer C** (Adaptive Resolution): environment service resolves mode from viewport/input/preferences
+- **Layer D** (Concrete Render): resolved CSS classes, token values, DOM attributes
+
+## Environment Contract (Chapters 2, 6)
+```js
+context.view_environment = {
+    viewport: { width, height, orientation },
+    layout_mode: 'phone' | 'tablet' | 'desktop',
+    density_mode: 'compact' | 'cozy' | 'comfortable',
+    interaction_mode: 'touch' | 'pointer' | 'hybrid',
+    motion_mode: 'normal' | 'reduced'
+};
+
+Composition Helper (Chapter 6)
+
+compose_adaptive(this, {
+    phone:   () => this.compose_phone_shell(),
+    tablet:  () => this.compose_tablet_shell(),
+    desktop: () => this.compose_desktop_shell()
+});
+
+Viewport Test Matrix (Chapter 7)
+Phone portrait (390×844), Phone landscape (844×390), Tablet portrait (768×1024), Tablet landscape (1024×768), Desktop narrow (1280×720), Desktop wide (1920×1080).
+
+If the book doesn't cover it, consult:
+AGENTS.md — project-wide naming conventions, testing patterns, coding style
+docs/accessibility_and_semantics.md — WCAG/ARIA guidance
+control_mixins/keyboard_navigation.js — orientation-aware keyboard handling
+css/jsgui-tokens.css — current token definitions
+controls/organised/AGENT.md — control creation and theming guide
+Output format for adaptive UI tasks
+Include:
+
+Book reference: which chapter(s) and pattern(s) apply
+Layer analysis: which of the four layers (A/B/C/D) are affected
+Model placement: what state goes in data.model vs view.data.model vs view.model
+Composition approach: CSS-only (continuous) vs JS composition (discrete) vs both
+Test coverage: which viewport profiles to test, which assertion categories (P0/P1/P2)

package/.github/workflows/control-scan-manifest-check.yml

@@ -0,0 +1,31 @@
+name: Control Scan Manifest Check
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+
+jobs:
+  control-scan-manifest:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Strict manifest regression test
+        run: node tests/test-runner.js --test=control-scan-manifest-regression.test.js
+
+      - name: Small controls bundle check
+        run: node tests/test-runner.js --test=small-controls-bundle-size.test.js

package/AGENTS.md

@@ -36,6 +36,9 @@
 - **[docs/agent-development-guide.md](docs/agent-development-guide.md)** - Guide for AI agents working on this codebase
 - **[docs/broken-functionality-tracker.md](docs/broken-functionality-tracker.md)** - Tracker for broken/incomplete functionality
 
+### Admin UI
+- **[docs/admin-extension-guide.md](docs/admin-extension-guide.md)** - Admin UI extension API: custom sections, endpoints, plugins, exported classes
+
 ### Review and Maintenance
 - **[docs/documentation-review/CURRENT_REVIEW.md](docs/documentation-review/CURRENT_REVIEW.md)** - Current documentation review status and known issues
 
@@ -58,6 +61,7 @@
 - **Custom control development** → `docs/controls-development.md`
 - **Publisher system** → `docs/publishers-guide.md`
 - **Resource management** → `docs/resources-guide.md`
+- **Admin UI extensions** → `docs/admin-extension-guide.md`
 
 ### Agent Development
 - **Agentic workflow patterns** → `docs/GUIDE_TO_AGENTIC_WORKFLOWS_BY_GROK.md`

package/README.md

@@ -8,7 +8,7 @@ This is the primary entry point for understanding the JSGUI3 Server project. Rea
 - You're looking for quick start guides and basic usage examples
 - You need to understand the project's capabilities and limitations
 
-**Note:** For detailed API documentation, see [docs/comprehensive-documentation.md](docs/comprehensive-documentation.md). For advanced server API design, see [docs/simple-server-api-design.md](docs/simple-server-api-design.md).
+**Note:** For detailed API documentation, see [docs/comprehensive-documentation.md](docs/comprehensive-documentation.md). For advanced server API design, see [docs/simple-server-api-design.md](docs/simple-server-api-design.md). For dense internals focused on startup, resources, SSE, and E2E verification, see [docs/core/jsgui3-server-core-book/00-table-of-contents.md](docs/core/jsgui3-server-core-book/00-table-of-contents.md). For deep bundling research and lightweight-bundle strategy, see [docs/books/jsgui3-bundling-research-book/README.md](docs/books/jsgui3-bundling-research-book/README.md).
 
 # Jsgui3 Server
 
@@ -72,6 +72,66 @@ Server.serve({
 });
 ```
 
+### Managed Resources (In-Process, Direct Process, Remote Process)
+
+```javascript
+const Server = require('jsgui3-server');
+const { Resource } = require('jsgui3-server');
+
+class In_Process_Cache_Resource extends Resource {
+    constructor(spec = {}) {
+        super(spec);
+        this.cache = new Map();
+    }
+    start(callback) { callback(null, true); }
+    stop(callback) { this.cache.clear(); callback(null, true); }
+}
+
+const server = await Server.serve({
+    port: 3000,
+    api: {
+        'resources/summary': () => server.resource_pool.summary
+    },
+    resources: {
+        // Existing in-process resource instance
+        cache: new In_Process_Cache_Resource({ name: 'cache' }),
+
+        // Local child process (default process_manager is direct)
+        worker_direct: {
+            type: 'process',
+            command: process.execPath,
+            args: ['worker.js'],
+            autoRestart: true
+        },
+
+        // Local process managed by PM2 (pm2Path is optional)
+        worker_pm2: {
+            type: 'process',
+            processManager: {
+                type: 'pm2'
+            },
+            command: process.execPath,
+            args: ['worker.js']
+        },
+
+        // Remote process controlled over HTTP
+        remote_worker: {
+            type: 'remote',
+            host: '127.0.0.1',
+            port: 3400
+        }
+    },
+    events: true // creates /events SSE endpoint and forwards pool resource lifecycle events
+});
+```
+
+All process-style resources expose a consistent API:
+- `start()`
+- `stop()`
+- `restart()`
+- `status` (includes `state`, `pid`, `uptime`, `restartCount`, `lastHealthCheck`, `memoryUsage`, `processManager`)
+- `get_abstract()`
+
 ### Real-time SSE Streams
 
 ```javascript
@@ -83,13 +143,161 @@ const obs = observable(next => {
 
 // Start server and publish stream
 const server = await Server.serve(MyControl);
-server.publish_observable('/api/stream', obs);
-// Server publishes SSE stream at http://localhost:3000/api/stream
+
+// Simple name - auto-prefixes /api/
+server.publish_observable('stream', obs);
+// Server publishes SSE stream at http://localhost:8080/api/stream
+
+// Or use full route path for custom routes
+server.publish_observable('/custom/events', obs);
+// Server publishes SSE stream at http://localhost:8080/custom/events
+
 // Client connects via EventSource or Remote_Observable
 ```
 
+### General SSE Publisher
+
+```javascript
+const HTTP_SSE_Publisher = require('jsgui3-server/publishers/http-sse-publisher');
+
+const sse_publisher = new HTTP_SSE_Publisher({ name: 'events' });
+server.server_router.set_route('/events', sse_publisher, sse_publisher.handle_http);
+
+sse_publisher.broadcast('resource_update', { running: 3, total: 5 });
+```
+
 > **Note:** The new `Server.serve()` API is the recommended approach for most use cases. See [Simple Server API Design](docs/simple-server-api-design.md) for complete documentation and advanced features.
 
+## 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`.
+
+### Disabling the Admin UI
+
+```javascript
+Server.serve({ Ctrl: MyControl, admin: false });
+
+// or
+Server.serve({ Ctrl: MyControl, admin: { enabled: false } });
+```
+
+### Adding Custom Sections
+
+Custom sections appear in the admin sidebar. When clicked, the shell fetches data from the section's API endpoint and auto-renders it as a table (arrays) or key-value panel (objects).
+
+```javascript
+const server = await Server.serve(MyControl);
+
+server.admin_v1.add_section({
+    id: 'crawlers',
+    label: 'Crawlers',
+    icon: '\uD83D\uDD77\uFE0F',
+    api_path: '/api/admin/v1/crawlers',
+    handler: (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify([
+            { name: 'Site A', status: 'running', pages: 1234 },
+            { name: 'Site B', status: 'idle',    pages: 0 }
+        ]));
+    }
+});
+```
+
+### Adding Custom Protected Endpoints
+
+```javascript
+server.admin_v1.add_endpoint({
+    path: '/api/admin/v1/crawlers/start',
+    role: 'admin_write',
+    handler: (req, res) => {
+        // start crawler logic
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+    }
+});
+```
+
+### Plugin Pattern
+
+```javascript
+server.admin_v1.use((admin) => {
+    admin.add_section({
+        id: 'logs',
+        label: 'Logs',
+        icon: '\uD83D\uDCDC',
+        api_path: '/api/admin/v1/logs',
+        handler: (req, res) => {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ recent: ['log1', 'log2'] }));
+        }
+    });
+});
+```
+
+### Admin UI Regression Test
+
+```bash
+node tests/test-runner.js --test=admin-ui-jsgui-controls.test.js
+```
+
+### Declarative Configuration via `Server.serve()`
+
+Custom sections and endpoints can also be declared in the `Server.serve()` call:
+
+```javascript
+Server.serve({
+    Ctrl: MyControl,
+    port: 8080,
+    admin: {
+        sections: [
+            {
+                id: 'jobs',
+                label: 'Jobs',
+                icon: '\u2699\uFE0F',
+                api_path: '/api/admin/v1/jobs',
+                handler: (req, res) => {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify([{ name: 'nightly-sync', status: 'complete' }]));
+                }
+            }
+        ],
+        endpoints: [
+            {
+                path: '/api/admin/v1/jobs/run',
+                role: 'admin_write',
+                handler: (req, res) => {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true }));
+                }
+            }
+        ]
+    }
+});
+```
+
+### Exported Admin Classes
+
+For advanced customisation, the admin classes are exported from the package:
+
+```javascript
+const Server = require('jsgui3-server');
+
+// Available on the Server constructor:
+Server.Admin_Module_V1    // Admin adapter (sections, endpoints, auth, SSE)
+Server.Admin_Auth_Service // Session management, cookie handling, role checking
+Server.Admin_User_Store   // In-memory user credential store (scrypt)
+
+// Also available from the npm module entry:
+const jsgui = require('jsgui3-server');
+jsgui.Admin_Module_V1
+jsgui.Admin_Auth_Service
+jsgui.Admin_User_Store
+```
+
+See [Admin Extension Guide](docs/admin-extension-guide.md) for detailed API reference.
+
 ## Architecture Overview
 
 The server operates as a bridge between server-side JavaScript applications and browser clients, offering:
@@ -909,11 +1117,15 @@ Minimal example:
 ```javascript
 // Inside your server bootstrap (after constructing Server)
 server.on('ready', () => {
+  // Simple name - auto-prefixes /api/
   // Returns text/plain at GET/POST /api/hello
   server.publish('hello', name => `Hello ${name || 'world'}`);
 
   // Returns application/json at GET/POST /api/sum
   server.publish('sum', ({ a, b }) => ({ sum: a + b }));
+  
+  // Full route path for custom routes (no auto-prefix)
+  server.publish('/custom/endpoint', () => ({ custom: true }));
 });
 ```
 

package/admin-ui/client.js

@@ -2,15 +2,19 @@ const jsgui = require('jsgui3-client');
 const { controls, Control, mixins } = jsgui;
 const Active_HTML_Document = require('../controls/Active_HTML_Document');
 
-class Admin_Page extends Active_HTML_Document {
-    constructor(spec = {}) {
-        spec.__type_name = spec.__type_name || 'admin_page';
-        super(spec);
-        const { context } = this;
-
-        if (typeof this.body.add_class === 'function') {
-            this.body.add_class('admin-page');
-        }
+class Admin_Page extends Active_HTML_Document {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'admin_page';
+        super(spec);
+        const { context } = this;
+
+        this._menu_items = [];
+        this._section_labels = Object.create(null);
+        this._active_section = 'overview';
+
+        if (typeof this.body.add_class === 'function') {
+            this.body.add_class('admin-page');
+        }
 
         const compose = () => {
             // Sidebar
@@ -50,9 +54,9 @@ class Admin_Page extends Active_HTML_Document {
             top_bar.add(this.page_title);
 
             // Content Panel
-            const content = new controls.div({ context, class: 'admin-content' });
-            main.add(content);
-            this.content = content;
+            const content_panel = new controls.div({ context, class: 'admin-content' });
+            main.add(content_panel);
+            this.content_panel = content_panel;
 
             // Default content (Overview)
             this._render_overview();
@@ -63,53 +67,79 @@ class Admin_Page extends Active_HTML_Document {
         }
     }
 
-    _add_menu_item(label, id, active = false) {
-        const item = new controls.div({
-            context: this.context,
-            class: `menu-item ${active ? 'active' : ''}`
-        });
-        item.dom.attributes['data-id'] = id;
-        item.add(label);
-        this.menu.add(item);
-        return item;
-    }
+    _add_menu_item(label, id, active = false) {
+        const item = new controls.div({
+            context: this.context,
+            class: `menu-item ${active ? 'active' : ''}`
+        });
+        item.dom.attributes['data-id'] = id;
+        item.add(label);
+        this.menu.add(item);
+
+        this._section_labels[id] = label;
+        this._menu_items.push({
+            id,
+            label,
+            control: item
+        });
+
+        item.on('click', () => {
+            this._activate_menu_item(id);
+        });
+
+        return item;
+    }
+
+    _set_control_text(control, text) {
+        if (!control) return;
+        if (typeof control.clear === 'function') {
+            control.clear();
+        }
+        if (typeof control.add === 'function') {
+            control.add(String(text == null ? '' : text));
+        }
+    }
+
+    _set_active_menu_item(id) {
+        this._menu_items.forEach((menu_item) => {
+            if (!menu_item.control) return;
+            if (menu_item.id === id) {
+                menu_item.control.add_class('active');
+            } else {
+                menu_item.control.remove_class('active');
+            }
+        });
+    }
+
+    _activate_menu_item(id) {
+        this._active_section = id;
+        this._set_active_menu_item(id);
+
+        const label = this._section_labels[id] || id;
+        this._set_control_text(this.page_title, label);
+
+        // Placeholder navigation logic
+        console.log('Navigate to:', id);
+    }
 
     _render_overview() {
-        // Clear main content area (this.content is the admin-content div)
-        if (this.content && this.content.content && typeof this.content.content.clear === 'function') {
-            this.content.content.clear();
-        }
+        // Clear main content area (content_panel is the admin-content div)
+        if (this.content_panel && this.content_panel.content && typeof this.content_panel.content.clear === 'function') {
+            this.content_panel.content.clear();
+        }
 
         const welcome = new controls.div({ context: this.context, class: 'welcome-card' });
         welcome.add(new controls.h3({ context: this.context }).add('Welcome directly to jsgui3-server Admin'));
         welcome.add(new controls.p({ context: this.context }).add('Select a resource from the sidebar to inspect.'));
-        this.content.add(welcome);
+        this.content_panel.add(welcome);
     }
 
-    activate() {
-        if (!this.__active) {
-            super.activate();
-
-            // Handle menu clicks
-            const menu_items = document.querySelectorAll('.menu-item');
-            menu_items.forEach(el => {
-                el.addEventListener('click', () => {
-                    // Update Active State
-                    menu_items.forEach(i => i.classList.remove('active'));
-                    el.classList.add('active');
-
-                    // Update Title
-                    const id = el.getAttribute('data-id');
-                    const label = el.innerText;
-                    document.querySelector('.page-title').innerText = label;
-
-                    // Placeholder navigation logic
-                    console.log('Navigate to:', id);
-                });
-            });
-        }
-    }
-}
+    activate() {
+        if (!this.__active) {
+            super.activate();
+        }
+    }
+}
 
 Admin_Page.css = `
 * { box-sizing: border-box; margin: 0; padding: 0; }