jsgui3-server 0.0.149 → 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/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

@@ -168,6 +168,136 @@ 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:

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
@@ -63,16 +67,60 @@ 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 (content_panel is the admin-content div)
@@ -86,30 +134,12 @@ class Admin_Page extends Active_HTML_Document {
         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; }

package/admin-ui/v1/admin_auth_service.js

@@ -0,0 +1,197 @@
+'use strict';
+
+const crypto = require('crypto');
+
+class Admin_Auth_Service {
+    constructor(spec = {}) {
+        this.user_store = spec.user_store;
+        this.session_ttl_ms = Number.isFinite(spec.session_ttl_ms) ? spec.session_ttl_ms : (8 * 60 * 60 * 1000);
+        this.cookie_name = spec.cookie_name || 'jsgui_admin_v1_sid';
+        this.sessions = new Map();
+    }
+
+    _read_json_body(req) {
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            req.on('data', (chunk) => chunks.push(chunk));
+            req.on('end', () => {
+                if (chunks.length === 0) return resolve({});
+                try {
+                    const text = Buffer.concat(chunks).toString('utf8');
+                    resolve(text ? JSON.parse(text) : {});
+                } catch (error) {
+                    reject(error);
+                }
+            });
+            req.on('error', reject);
+        });
+    }
+
+    _parse_cookies(req) {
+        const cookies = {};
+        const header = req && req.headers ? req.headers.cookie : '';
+        if (!header) return cookies;
+
+        const parts = header.split(';');
+        parts.forEach((part) => {
+            const idx = part.indexOf('=');
+            if (idx === -1) return;
+            const key = part.slice(0, idx).trim();
+            const value = part.slice(idx + 1).trim();
+            cookies[key] = decodeURIComponent(value);
+        });
+        return cookies;
+    }
+
+    _set_session_cookie(res, session_id) {
+        const secure = process.env.NODE_ENV === 'production' ? '; Secure' : '';
+        const cookie_value = this.cookie_name + '=' + encodeURIComponent(session_id) + '; Path=/; HttpOnly; SameSite=Lax; Max-Age=' + Math.floor(this.session_ttl_ms / 1000) + secure;
+        res.setHeader('Set-Cookie', cookie_value);
+    }
+
+    _clear_session_cookie(res) {
+        const secure = process.env.NODE_ENV === 'production' ? '; Secure' : '';
+        res.setHeader('Set-Cookie', this.cookie_name + '=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0' + secure);
+    }
+
+    _new_session_id() {
+        return crypto.randomBytes(24).toString('hex');
+    }
+
+    _cleanup_expired() {
+        const now = Date.now();
+        for (const [id, session] of this.sessions.entries()) {
+            if (!session || session.expires_at <= now) {
+                this.sessions.delete(id);
+            }
+        }
+    }
+
+    get_session(req) {
+        this._cleanup_expired();
+        const cookies = this._parse_cookies(req);
+        const sid = cookies[this.cookie_name];
+        if (!sid) return null;
+
+        const session = this.sessions.get(sid);
+        if (!session) return null;
+        if (session.expires_at <= Date.now()) {
+            this.sessions.delete(sid);
+            return null;
+        }
+        return {
+            session_id: sid,
+            user: session.user,
+            expires_at: session.expires_at
+        };
+    }
+
+    is_authenticated(req) {
+        return !!this.get_session(req);
+    }
+
+    has_role(req, role_name) {
+        const session = this.get_session(req);
+        if (!session || !session.user) return false;
+        const roles = Array.isArray(session.user.roles) ? session.user.roles : [];
+        return roles.includes(role_name);
+    }
+
+    has_any_role(req, role_names) {
+        const session = this.get_session(req);
+        if (!session || !session.user) return false;
+        const roles = Array.isArray(session.user.roles) ? session.user.roles : [];
+        if (!Array.isArray(role_names) || role_names.length === 0) return false;
+        return role_names.some((role_name) => roles.includes(role_name));
+    }
+
+    create_session(user, res) {
+        const session_id = this._new_session_id();
+        const expires_at = Date.now() + this.session_ttl_ms;
+        this.sessions.set(session_id, {
+            user,
+            created_at: Date.now(),
+            expires_at
+        });
+        this._set_session_cookie(res, session_id);
+        return { session_id, expires_at, user };
+    }
+
+    destroy_session(req, res) {
+        const cookies = this._parse_cookies(req);
+        const sid = cookies[this.cookie_name];
+        if (sid) this.sessions.delete(sid);
+        this._clear_session_cookie(res);
+    }
+
+    async handle_login(req, res) {
+        if (String(req.method || 'GET').toUpperCase() !== 'POST') {
+            res.writeHead(405, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: false, error: 'Method Not Allowed' }));
+            return;
+        }
+
+        let body;
+        try {
+            body = await this._read_json_body(req);
+        } catch (error) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: false, error: 'Invalid JSON body' }));
+            return;
+        }
+
+        const username = body.username;
+        const password = body.password;
+        const user = this.user_store.verify_credentials(username, password);
+        if (!user) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: false, error: 'Invalid credentials' }));
+            return;
+        }
+
+        const session = this.create_session(user, res);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            ok: true,
+            user: session.user,
+            expires_at: session.expires_at
+        }));
+    }
+
+    handle_logout(req, res) {
+        if (String(req.method || 'GET').toUpperCase() !== 'POST') {
+            res.writeHead(405, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: false, error: 'Method Not Allowed' }));
+            return;
+        }
+
+        this.destroy_session(req, res);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+    }
+
+    handle_session(req, res) {
+        if (String(req.method || 'GET').toUpperCase() !== 'GET') {
+            res.writeHead(405, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: false, error: 'Method Not Allowed' }));
+            return;
+        }
+
+        const session = this.get_session(req);
+        if (!session) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, authenticated: false }));
+            return;
+        }
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            ok: true,
+            authenticated: true,
+            user: session.user,
+            expires_at: session.expires_at
+        }));
+    }
+}
+
+module.exports = Admin_Auth_Service;

package/admin-ui/v1/admin_user_store.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const crypto = require('crypto');
+
+class Admin_User_Store {
+    constructor(spec = {}) {
+        this._users = new Map();
+        this._scrypt_cost = spec.scrypt_cost || 16384;
+    }
+
+    _hash_password(password, salt) {
+        const key = crypto.scryptSync(password, salt, 64, { N: this._scrypt_cost });
+        return key.toString('hex');
+    }
+
+    add_user(spec = {}) {
+        const username = String(spec.username || '').trim();
+        const password = String(spec.password || '');
+        const roles = Array.isArray(spec.roles) ? spec.roles : ['admin_read'];
+
+        if (!username) throw new Error('username is required');
+        if (!password) throw new Error('password is required');
+
+        const salt = crypto.randomBytes(16).toString('hex');
+        const password_hash = this._hash_password(password, salt);
+
+        this._users.set(username, {
+            username,
+            salt,
+            password_hash,
+            roles,
+            created_at: Date.now()
+        });
+
+        return { username, roles: roles.slice() };
+    }
+
+    has_user(username) {
+        return this._users.has(username);
+    }
+
+    get_user(username) {
+        const user = this._users.get(username);
+        if (!user) return null;
+        return {
+            username: user.username,
+            roles: user.roles.slice(),
+            created_at: user.created_at
+        };
+    }
+
+    verify_credentials(username, password) {
+        const user = this._users.get(String(username || ''));
+        if (!user) return null;
+
+        const attempted_hash = this._hash_password(String(password || ''), user.salt);
+        const expected = Buffer.from(user.password_hash, 'hex');
+        const attempted = Buffer.from(attempted_hash, 'hex');
+
+        if (expected.length !== attempted.length) return null;
+        const ok = crypto.timingSafeEqual(expected, attempted);
+        if (!ok) return null;
+
+        return {
+            username: user.username,
+            roles: user.roles.slice()
+        };
+    }
+}
+
+module.exports = Admin_User_Store;

package/admin-ui/v1/client.js

@@ -0,0 +1,17 @@
+'use strict';
+
+/**
+ * Admin UI v1 — client entry point.
+ *
+ * This file is the ESBuild entry point that the HTTP_Webpage_Publisher
+ * bundles and serves. It imports the Admin_Shell control (which
+ * transitively pulls in Group_Box and Stat_Card) and exports the
+ * jsgui module with Admin_Shell registered on controls.
+ */
+const jsgui = require('./controls/admin_shell');
+
+// The require above already registers controls.Admin_Shell,
+// controls.Stat_Card, and controls.Group_Box on the jsgui
+// controls namespace.
+
+module.exports = jsgui;