jsgui3-server 0.0.147 → 0.0.148

package/docs/books/admin-ui/03-controls.md

@@ -0,0 +1,194 @@
+# Chapter 3: Controls
+
+## Control Placement Strategy
+
+| Control | Location | Rationale |
+|---------|----------|-----------|
+| `Property_Viewer` | jsgui3-html | General-purpose read-only property display |
+| `Property_Editor` | jsgui3-html | Already exists - editing properties |
+| `Object_KVP_Viewer` | jsgui3-html | Already exists - key-value pairs |
+| `Object_KVP_Editor` | jsgui3-html | Already exists - editable KVP |
+| `Resource_Viewer` | jsgui3-html | General-purpose for any resource with name/type/status |
+| `Tree_View` | jsgui3-html | General-purpose hierarchical display |
+| `Admin_Page` | jsgui3-server | Server-specific admin shell |
+| `Resource_List` | jsgui3-server | Server-specific resource listing |
+| `Observables_List` | jsgui3-server | Server-specific observable listing |
+| `Observable_Monitor` | jsgui3-server | Server-specific real-time monitoring |
+| `Resource_Detail_Page` | jsgui3-server | Server-specific resource detail view |
+
+---
+
+## General-Purpose Controls (jsgui3-html)
+
+### Existing Controls to Leverage
+
+1. **`Property_Editor`** - Edits properties with type-specific inputs
+2. **`Object_KVP_Viewer`** - Displays object as key-value pairs
+3. **`Object_KVP_Editor`** - Editable key-value pairs
+
+### New Controls Needed in jsgui3-html
+
+#### Property_Viewer
+
+Read-only display of an object's properties in a clean table format.
+
+```javascript
+const viewer = new controls.Property_Viewer({
+    context,
+    data: { name: 'MyResource', type: 'observable', status: 'active' },
+    schema: {
+        name: { label: 'Name', type: 'string' },
+        type: { label: 'Type', type: 'badge' },
+        status: { label: 'Status', type: 'status-indicator' }
+    }
+});
+```
+
+#### Resource_Viewer
+
+Displays a resource with icon, name, type badge, and expandable details.
+
+```javascript
+const rv = new controls.Resource_Viewer({
+    context,
+    resource: {
+        name: '/api/tick-stream',
+        type: 'observable',
+        schema: { type: 'int' },
+        status: 'active',
+        connections: 3
+    }
+});
+```
+
+#### Tree_View
+
+Hierarchical tree with expand/collapse, icons, and selection.
+
+```javascript
+const tree = new controls.Tree_View({
+    context,
+    data: [
+        { label: 'Publishers', icon: '📡', children: [...] },
+        { label: 'Routes', icon: '🛤️', children: [...] }
+    ],
+    onSelect: (node) => console.log('Selected:', node)
+});
+```
+
+---
+
+## Server-Specific Controls (jsgui3-server/admin-ui)
+
+### 1. Admin_Page
+
+The main container control that serves as the Admin UI shell.
+
+```javascript
+class Admin_Page extends Active_HTML_Document {
+    // Renders sidebar + main panel + header
+}
+```
+
+**Layout:**
+- Left sidebar: `Resource_List` + `Observables_List`
+- Main panel: `Resource_Detail_Page` or selected content
+- Header: Server name, uptime, connection count
+
+### 2. Resource_List
+
+Displays all registered server resources using `Tree_View`.
+
+**Data Source:** `GET /api/admin/resources`
+
+**Structure:**
+```
+├── Routes
+│   ├── / (webpage)
+│   ├── /admin (admin-ui)
+│   └── /api/* (function)
+├── Publishers
+│   ├── HTTP_Website_Publisher
+│   └── HTTP_Observable_Publisher
+└── Resources
+    ├── Server Router
+    └── Resource Pool
+```
+
+### 3. Observables_List
+
+Lists all published observables with status indicators.
+
+**Data Source:** `GET /api/admin/observables`
+
+**Item Display:**
+- Route path
+- Schema type badge
+- Status indicator (active/paused/stopped)
+- Connection count
+
+### 4. Observable_Monitor
+
+Real-time display for a single observable using `Auto_Observable_UI`.
+
+**Features:**
+- Play/Pause controls
+- History buffer (last N values)
+- Schema display
+- Export to JSON
+
+### 5. Resource_Detail_Page
+
+Detail view for a selected resource.
+
+**Sections:**
+- **Header**: Name, type badge
+- **Properties**: Using `Property_Viewer`
+- **Actions**: Pause, resume, stop (for observables)
+- **Live View**: For observables, embedded monitor
+
+### 6. Config_Panel
+
+Form-based configuration editor using `Property_Editor`.
+
+**Features:**
+- Read-only by default (safety)
+- Unlock with confirmation for editing
+- Validation before save
+
+### 7. Metrics_Dashboard
+
+Displays server health metrics.
+
+**Metrics:**
+- Active connections
+- Requests/second
+- Memory usage
+- Observable subscription count
+
+---
+
+## Styling Approach
+
+All controls use CSS-in-JS via the static `.css` property:
+
+```javascript
+Admin_Page.css = `
+.admin-page {
+    display: grid;
+    grid-template-columns: 280px 1fr;
+    height: 100vh;
+    background: #1a1a2e;
+}
+.admin-sidebar { ... }
+.admin-main { ... }
+`;
+```
+
+## Extension Points
+
+Custom admin panels can be registered:
+
+```javascript
+server.admin.registerPanel('MyPanel', MyPanelControl);
+```

package/docs/books/admin-ui/04-implementation-plan.md

@@ -0,0 +1,62 @@
+# Chapter 4: Implementation Plan
+
+## Phase 1: Foundation
+
+### jsgui3-html (General-Purpose)
+- [ ] Implement `Property_Viewer` control
+- [ ] Implement `Resource_Viewer` control  
+- [ ] Implement `Tree_View` control
+
+### jsgui3-server (Admin-Specific)
+- [x] Create `admin-ui/client.js` with `Admin_Page`
+- [x] Create `admin-ui/server.js` with API routes
+- [x] Register `/admin` route in main server
+
+## Phase 2: Resource Browser
+
+- [ ] Implement `Resource_List` using `Tree_View`
+- [x] Add API: `GET /api/admin/resources`
+- [ ] Implement `Resource_Detail_Page`
+- [ ] Wire up selection → detail view
+
+## Phase 3: Observable Visibility
+
+- [ ] Implement `Observables_List` control
+- [x] Add API: `GET /api/admin/observables`
+- [ ] Implement `Observable_Monitor` with `Auto_Observable_UI`
+- [ ] Add play/pause/history features
+
+## Phase 4: Metrics & Config
+
+- [ ] Implement `Metrics_Dashboard`
+- [ ] Add API: `GET /api/admin/metrics` (SSE)
+- [ ] Implement `Config_Panel` using `Property_Editor`
+
+## Phase 5: Polish
+
+- [ ] Responsive design
+- [ ] Keyboard navigation
+- [ ] Export/import config
+- [ ] Documentation and examples
+
+## File Checklist
+
+| File | Location | Status |
+|------|----------|--------|
+| `Property_Viewer.js` | jsgui3-html | Planned |
+| `Resource_Viewer.js` | jsgui3-html | Planned |
+| `Tree_View.js` | jsgui3-html | Planned |
+| `admin-ui/client.js` | jsgui3-server | ✅ Done |
+| `admin-ui/server.js` | jsgui3-server | ✅ Done |
+| `admin-ui/controls/Resource_List.js` | jsgui3-server | Planned |
+| `admin-ui/controls/Observables_List.js` | jsgui3-server | Planned |
+| `admin-ui/controls/Observable_Monitor.js` | jsgui3-server | Planned |
+| `admin-ui/controls/Resource_Detail_Page.js` | jsgui3-server | Planned |
+
+## Success Criteria
+
+1. Navigate to `/admin` and see the Admin UI
+2. Browse all server resources in tree view
+3. Select a resource to see its properties
+4. View live observable streams with auto-generated UIs
+5. See basic metrics (connections, uptime)

package/docs/books/admin-ui/README.md

@@ -0,0 +1,26 @@
+# Admin UI Book
+
+This folder contains documentation for the `jsgui3-server` Admin UI system.
+
+## Chapters
+
+1. [Introduction](./01-introduction.md) - Vision and goals
+2. [Architecture](./02-architecture.md) - High-level design
+3. [Controls](./03-controls.md) - UI components
+4. [Implementation Plan](./04-implementation-plan.md) - Phases and tasks
+
+## Purpose
+
+The Admin UI provides a web-based interface to administer and monitor `jsgui3-server` instances. Key features include:
+
+- **Resource Viewer**: Browse server-side resources (publishers, routes, etc.)
+- **Observable Monitor**: Real-time visibility into observable server processes
+- **Configuration Editor**: Modify server settings
+- **Performance Dashboard**: View metrics and health
+
+## Design Principles
+
+1. **Dogfooding**: Built entirely with jsgui3 controls
+2. **Real-time**: Uses `Remote_Observable` for live updates
+3. **Extensible**: Plugin architecture for custom panels
+4. **Polished UX**: Modern dark theme, smooth transitions

package/examples/controls/19) window, auto observable ui/client.js

@@ -0,0 +1,125 @@
+const jsgui = require('jsgui3-client');
+const { controls, Control } = jsgui;
+const Auto_Observable_UI = require('../../../client/controls/auto-observable');
+controls.Auto_Observable_UI = Auto_Observable_UI;
+
+const Active_HTML_Document = require('../../../controls/Active_HTML_Document');
+
+class Demo_Page extends Active_HTML_Document {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'demo_page';
+        super(spec);
+        const { context } = this;
+
+        if (typeof this.body.add_class === 'function') {
+            this.body.add_class('demo-page');
+        }
+
+        const compose = () => {
+            const h1 = new controls.h1({ context });
+            h1.add('Auto Observable UI Demo');
+            this.body.add(h1);
+
+            const container = new controls.div({ context, class: 'params-container' });
+            this.body.add(container);
+
+            // 1. Tick Counter (Int)
+            const ui_tick = new Auto_Observable_UI({
+                context,
+                url: '/api/tick',
+                class: 'param-ui'
+            });
+            container.add(ui_tick);
+
+            // 2. CPU Load (Gauge)
+            const ui_cpu = new Auto_Observable_UI({
+                context,
+                url: '/api/cpu',
+                class: 'param-ui'
+            });
+            container.add(ui_cpu);
+
+            // 3. System Logs (Log)
+            const ui_log = new Auto_Observable_UI({
+                context,
+                url: '/api/logs',
+                class: 'param-ui span-2'
+            });
+            container.add(ui_log);
+        };
+
+        if (!spec.el) {
+            compose();
+        }
+    }
+}
+
+Demo_Page.css = `
+body {
+    background: #222;
+    color: #eee;
+    font-family: sans-serif;
+    padding: 20px;
+}
+.params-container {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 20px;
+    max-width: 800px;
+}
+.param-ui {
+    background: #333;
+    padding: 15px;
+    border-radius: 8px;
+    box-shadow: 0 2px 10px rgba(0,0,0,0.5);
+}
+.span-2 {
+    grid-column: span 2;
+}
+.value-display {
+    text-align: center;
+}
+.value-text {
+    font-size: 3em;
+    font-weight: bold;
+    color: #4facfe;
+}
+.progress-bg {
+    background: #444;
+    height: 20px;
+    border-radius: 10px;
+    overflow: hidden;
+    margin: 10px 0;
+}
+.progress-fill {
+    background: linear-gradient(90deg, #4facfe 0%, #00f2fe 100%);
+    height: 100%;
+    width: 0%;
+    transition: width 0.3s ease;
+}
+.log-area {
+    height: 150px;
+    background: #111;
+    overflow-y: auto;
+    text-align: left;
+    padding: 10px;
+    font-family: monospace;
+    font-size: 0.9em;
+    border: 1px solid #444;
+}
+.log-entry {
+    margin-bottom: 4px;
+    border-bottom: 1px solid #222;
+}
+.status-indicator {
+    font-size: 0.8em;
+    text-transform: uppercase;
+    margin-bottom: 5px;
+    color: #888;
+}
+.status-connected { color: #0f0; }
+.status-error { color: #f00; }
+`;
+
+module.exports = jsgui;
+controls.Demo_Page = Demo_Page;

package/examples/controls/19) window, auto observable ui/server.js

@@ -0,0 +1,64 @@
+const jsgui = require('./client');
+const Server = require('../../../server');
+const { Demo_Page } = jsgui.controls;
+const { observable } = require('fnl');
+
+if (require.main === module) {
+    const server = new Server({
+        Ctrl: Demo_Page,
+        src_path_client_js: require.resolve('./client.js')
+    });
+
+    server.on('ready', () => {
+        // 1. Tick Observable
+        const obs_tick = observable((next) => {
+            let i = 0;
+            const timer = setInterval(() => next(++i), 1000);
+            return () => clearInterval(timer);
+        });
+        // Attach schema manually (or could be done via helper)
+        obs_tick.schema = {
+            name: 'Uptime (Seconds)',
+            type: 'int'
+        };
+        server.publish_observable('/api/tick', obs_tick);
+
+        // 2. CPU Observable (Simulated)
+        const obs_cpu = observable((next) => {
+            const timer = setInterval(() => {
+                const load = 40 + Math.random() * 30;
+                next(Math.floor(load));
+            }, 500);
+            return () => clearInterval(timer);
+        });
+        obs_cpu.schema = {
+            name: 'CPU Load',
+            type: 'number',
+            min: 0,
+            max: 100
+        };
+        server.publish_observable('/api/cpu', obs_cpu);
+
+        // 3. Logs Observable
+        const obs_logs = observable((next) => {
+            const msgs = ['System check OK', 'Request received', 'Cache invalidated', 'User login', 'Background job started'];
+            const timer = setInterval(() => {
+                const msg = msgs[Math.floor(Math.random() * msgs.length)];
+                next({ message: msg, level: 'info' });
+            }, 2000);
+            return () => clearInterval(timer);
+        });
+        obs_logs.schema = {
+            name: 'Server Logs',
+            type: 'log'
+        };
+        server.publish_observable('/api/logs', obs_logs);
+
+        // Start
+        const port = 52100;
+        server.start(port, (err) => {
+            if (err) throw err;
+            console.log(`Demo running at http://localhost:${port}`);
+        });
+    });
+}

package/package.json

@@ -10,8 +10,8 @@
     "esbuild": "^0.27.1",
     "fnl": "^0.0.37",
     "fnlfs": "^0.0.34",
-    "jsgui3-client": "^0.0.128",
-    "jsgui3-html": "^0.0.179",
+    "jsgui3-client": "^0.0.129",
+    "jsgui3-html": "^0.0.180",
     "jsgui3-webpage": "^0.0.8",
     "jsgui3-website": "^0.0.8",
     "lang-tools": "^0.0.44",
@@ -43,7 +43,7 @@
     "type": "git",
     "url": "https://github.com/metabench/jsgui3-server.git"
   },
-  "version": "0.0.147",
+  "version": "0.0.148",
   "scripts": {
     "cli": "node cli.js",
     "serve": "node cli.js serve",

package/publishers/http-observable-publisher.js

@@ -27,6 +27,9 @@ class Observable_Publisher extends HTTP_Publisher {
         this.type = 'observable';
         this.obs = obs;
 
+        // Expose schema if provided (either in spec or on the observable itself)
+        this.schema = spec.schema || obs.schema || null;
+
         this.keep_alive_interval_ms = (spec && spec.keep_alive_interval_ms !== undefined)
             ? spec.keep_alive_interval_ms
             : default_keep_alive_interval_ms;
@@ -301,6 +304,11 @@ class Observable_Publisher extends HTTP_Publisher {
             this._write_sse(res, `event: paused\ndata: ${this._stringify_sse_data({ status: 'paused' })}\n\n`);
         }
 
+        // Send schema if available
+        if (this.schema) {
+            this._write_sse(res, `event: schema\ndata: ${this._stringify_sse_data(this.schema)}\n\n`);
+        }
+
         let removed = false;
         const remove_connection = () => {
             if (removed) return;

package/publishers/http-webpage-publisher.js

@@ -72,9 +72,19 @@ class HTTP_Webpage_Publisher extends HTTP_Webpageorsite_Publisher {
             bundler_config: this.bundler_config
         });
         (async () => {
-            const res_get_ready = await this.get_ready();
-            this.raise('ready', res_get_ready);
-
+            try {
+                const res_get_ready = await this.get_ready();
+                this.raise('ready', res_get_ready);
+            } catch (e) {
+                console.error('HTTP_Webpage_Publisher error: Failed to get ready (bundling or preparation failed).');
+                console.error(e);
+                // Can't just ignore it if it means the server won't handle requests correctly, 
+                // but at least it won't crash the whole process.
+                // We might want to emit an error event.
+                this.raise('error', e);
+                // Also raise 'ready' so the pool/server can continue starting up other things
+                this.raise('ready', {});
+            }
         })();
 
     }

package/publishers/http-webpageorsite-publisher.js

@@ -162,6 +162,24 @@ class HTTP_Webpageorsite_Publisher extends HTTP_Publisher {
 
         console.log('[HTTP_Webpageorsite_Publisher] get_ready called, src_path_client_js:', src_path_client_js);
 
+        // Defensive programming: Handle missing client JS path
+        if (!src_path_client_js) {
+            console.warn('[HTTP_Webpageorsite_Publisher] No src_path_client_js provided. Returning empty bundle.');
+            const bundle = new Bundle();
+            // Could add empty CSS/JS placeholders if needed to prevent errors downstream
+            bundle.push({
+                type: 'CSS',
+                extension: 'css',
+                text: '/* No client CSS - Server Start Mode */'
+            });
+            bundle.push({
+                type: 'JavaScript',
+                extension: 'js',
+                text: '/* No client JS - Server Start Mode */'
+            });
+            return bundle;
+        }
+
         // Skip bundling if no client.js path is provided
         // This allows Server.serve() to work with SSR-only controls
         if (!src_path_client_js) {