jsgui3-server 0.0.146 → 0.0.148

package/README.md

@@ -72,6 +72,22 @@ Server.serve({
 });
 ```
 
+### Real-time SSE Streams
+
+```javascript
+const { observable } = require('fnl');
+// Create an infinite stream that ticks every second
+const obs = observable(next => {
+    setInterval(() => next({ tick: Date.now() }), 1000);
+});
+
+// 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
+// Client connects via EventSource or Remote_Observable
+```
+
 > **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.
 
 ## Architecture Overview

package/admin-ui/client.js

@@ -0,0 +1,213 @@
+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');
+        }
+
+        const compose = () => {
+            // Sidebar
+            const sidebar = new controls.div({ context, class: 'admin-sidebar' });
+            this.body.add(sidebar);
+            this.sidebar = sidebar;
+
+            // Sidebar Header
+            const brand = new controls.div({ context, class: 'admin-brand' });
+            brand.add(new controls.span({ context, class: 'brand-icon' }).add('⚙️'));
+            brand.add(new controls.span({ context, class: 'brand-text' }).add('jsgui3 Admin'));
+            sidebar.add(brand);
+
+            // Menu Container (Placeholder for Resource_List and Observables_List)
+            const menu = new controls.div({ context, class: 'admin-menu' });
+            sidebar.add(menu);
+            this.menu = menu;
+
+            this._add_menu_item('Overview', 'overview', true);
+            this._add_menu_item('Resources', 'resources');
+            this._add_menu_item('Observables', 'observables');
+            this._add_menu_item('Settings', 'settings');
+
+
+            // Main Content Area
+            const main = new controls.div({ context, class: 'admin-main' });
+            this.body.add(main);
+            this.main = main;
+
+            // Top Bar
+            const top_bar = new controls.div({ context, class: 'admin-top-bar' });
+            main.add(top_bar);
+
+            // Breadcrumbs / Title
+            this.page_title = new controls.h2({ context, class: 'page-title' });
+            this.page_title.add('Overview');
+            top_bar.add(this.page_title);
+
+            // Content Panel
+            const content = new controls.div({ context, class: 'admin-content' });
+            main.add(content);
+            this.content = content;
+
+            // Default content (Overview)
+            this._render_overview();
+        };
+
+        if (!spec.el) {
+            compose();
+        }
+    }
+
+    _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;
+    }
+
+    _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();
+        }
+
+        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);
+    }
+
+    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);
+                });
+            });
+        }
+    }
+}
+
+Admin_Page.css = `
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { 
+    background: #1a1a2e; 
+    color: #e0e0e0; 
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    height: 100vh;
+    overflow: hidden;
+}
+.admin-page {
+    display: grid;
+    grid-template-columns: 260px 1fr;
+    height: 100%;
+}
+
+/* Sidebar */
+.admin-sidebar {
+    background: #16213e;
+    border-right: 1px solid #2a2a4a;
+    display: flex;
+    flex-direction: column;
+}
+.admin-brand {
+    padding: 20px;
+    font-size: 1.2rem;
+    font-weight: bold;
+    color: #fff;
+    border-bottom: 1px solid #2a2a4a;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+.brand-icon { filter: drop-shadow(0 0 5px rgba(255,255,255,0.3)); }
+
+.admin-menu {
+    flex: 1;
+    padding: 20px 0;
+    overflow-y: auto;
+}
+.menu-item {
+    padding: 12px 24px;
+    cursor: pointer;
+    border-left: 3px solid transparent;
+    transition: all 0.2s;
+    color: #a0a0b0;
+}
+.menu-item:hover {
+    background: rgba(255,255,255,0.05);
+    color: #fff;
+}
+.menu-item.active {
+    background: rgba(79, 172, 254, 0.1);
+    color: #4facfe;
+    border-left-color: #4facfe;
+}
+
+/* Main Area */
+.admin-main {
+    display: flex;
+    flex-direction: column;
+    background: #1a1a2e;
+}
+.admin-top-bar {
+    height: 64px;
+    border-bottom: 1px solid #2a2a4a;
+    display: flex;
+    align-items: center;
+    padding: 0 30px;
+    background: #16213e;
+}
+.page-title {
+    font-size: 1.2rem;
+    font-weight: 500;
+    color: #fff;
+}
+
+.admin-content {
+    flex: 1;
+    overflow-y: auto;
+    padding: 30px;
+    position: relative;
+}
+
+/* Cards */
+.welcome-card {
+    background: #2a2a4a;
+    padding: 40px;
+    border-radius: 12px;
+    text-align: center;
+    max-width: 600px;
+    margin: 40px auto;
+    border: 1px solid #3a3a5a;
+    box-shadow: 0 4px 20px rgba(0,0,0,0.2);
+}
+.welcome-card h3 { color: #fff; margin-bottom: 15px; }
+.welcome-card p { color: #a0a0b0; }
+`;
+
+controls.Admin_Page = Admin_Page;
+module.exports = jsgui;

package/admin-ui/server.js

@@ -0,0 +1,104 @@
+const jsgui = require('./client');
+const { Admin_Page } = jsgui.controls;
+const { each } = jsgui;
+
+class Admin_Module {
+    constructor(server) {
+        this.server = server;
+        this.setup_routes();
+    }
+
+    setup_routes() {
+        const { server } = this;
+
+        // 1. Main Admin Page Route
+        // Using a custom Website_Resource for the admin app
+        // We register Admin_Page as the content control
+
+        // Manual route setup to render the page
+        // (Similar to how examples work, but integrated)
+
+        // We'll expose a 'setup' method that the main server calls
+        // Or we can attach directly if we have access to the router
+    }
+
+    // Called by the main server to attach admin functionality
+    attach_to_router(router) {
+        console.log('[Admin_Module] Attaching /admin routes...');
+
+        // API: List Resources
+        // GET /api/admin/resources
+        router.set_route('/api/admin/resources', (req, res) => {
+            const resources_data = this.get_resources_tree();
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(resources_data));
+        });
+
+        // API: List Observables
+        // GET /api/admin/observables
+        router.set_route('/api/admin/observables', (req, res) => {
+            const observables = this.get_observables_list();
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(observables));
+        });
+    }
+
+    get_resources_tree() {
+        const pool = this.server.resource_pool;
+        const tree = {
+            name: 'Root',
+            type: 'pool',
+            children: []
+        };
+
+        if (pool && pool.resources) {
+            // Need to iterate pool resources safely
+            // resource_pool.resources is likely a Collection or array
+            const resources = pool.resources._arr || []; // Assuming Data_Structures.Collection
+
+            resources.forEach(res => {
+                tree.children.push({
+                    name: res.name || 'Unnamed Resource',
+                    type: res.constructor.name
+                });
+            });
+        }
+        return tree;
+    }
+
+    get_observables_list() {
+        // We need a way to track all published observables
+        // Ideally, HTTP_Observable_Publisher instances are stored in the resource pool or a specific list
+
+        // For now, we'll scan the router for observable publishers
+        // This relies on the server exposing its router/routes map
+        const observables = [];
+
+        // Implementation detail: server.router doesn't expose a simple list of routes easily in standard Router
+        // We might need to track them when publish_observable is called.
+        // But we can look at server.resource_pool for publishers
+
+        const pool = this.server.resource_pool;
+        if (pool && pool.resources) {
+            const resources = pool.resources._arr || [];
+            resources.forEach(res => {
+                // Check if it's an observable publisher
+                // Robust check: does it have 'obs' property and handle_http? 
+                // Or check constructor name if available
+                if (res.constructor.name === 'Observable_Publisher' || (res.obs && res.handle_http)) {
+                    observables.push({
+                        name: res.name || 'Observable',
+                        route: '?', // Route might not be stored on the resource itself, but on the router
+                        schema: res.schema,
+                        status: res.is_paused ? 'paused' : 'active',
+                        connections: res.active_sse_connections ? res.active_sse_connections.size : 0
+                    });
+                }
+            });
+        }
+
+        return observables;
+    }
+}
+
+module.exports = Admin_Module;

package/client/controls/auto-observable.js

@@ -0,0 +1,207 @@
+const jsgui = require('jsgui3-client');
+const { Control, controls } = jsgui;
+
+class Auto_Observable_UI extends Control {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'auto_observable_ui';
+        super(spec);
+        this.add_class('auto-observable-ui');
+
+        this.url = spec.url;
+        this.obs = spec.obs;
+
+        // Container for the dynamic content
+        this.content_container = new controls.div({
+            context: this.context,
+            class: 'content-container'
+        });
+        this.add(this.content_container);
+
+        // Status indicator
+        this.status_indicator = new controls.div({
+            context: this.context,
+            class: 'status-indicator status-connecting'
+        });
+        this.add(this.status_indicator);
+    }
+
+    activate() {
+        if (!this.__active) {
+            super.activate();
+            this._connect();
+        }
+    }
+
+    _connect() {
+        let obs = this.obs;
+        if (!obs && this.url) {
+            obs = new jsgui.Remote_Observable({ url: this.url });
+            this.obs = obs;
+        }
+
+        if (!obs) return;
+
+        obs.on('connect', () => {
+            this.status_indicator.remove_class('status-connecting');
+            this.status_indicator.add_class('status-connected');
+            this.status_indicator.dom.innerText = 'Connected';
+        });
+
+        obs.on('schema', (schema) => {
+            console.log('Schema received:', schema);
+            this._build_ui_from_schema(schema);
+        });
+
+        obs.on('next', (data) => {
+            // If we haven't received a schema yet, maybe infer it or just display raw?
+            // For now, if we built the UI, we update it.
+            if (this._update_handler) {
+                this._update_handler(data);
+            } else if (!this._ui_built) {
+                // Infer simple schema if not provided?
+                // Or just show raw JSON
+                this._build_default_ui(data);
+                this._ui_built = true;
+                if (this._update_handler) this._update_handler(data);
+            }
+        });
+
+        obs.on('error', (err) => {
+            this.status_indicator.add_class('status-error');
+            this.status_indicator.dom.innerText = 'Error: ' + err.message;
+        });
+
+        obs.connect();
+    }
+
+    _build_ui_from_schema(schema) {
+        if (this._ui_built) return; // Don't rebuild for now
+        this._ui_built = true;
+
+        this.content_container.content.clear();
+
+        const type = schema.type || (schema.output_type ? schema.output_type : 'unknown');
+
+        if (type === 'int' || type === 'number') {
+            this._build_number_ui(schema);
+        } else if (type === 'text' || type === 'log') {
+            this._build_log_ui(schema);
+        } else if (type === 'percentage' || (type === 'number' && schema.min !== undefined && schema.max !== undefined)) {
+            this._build_gauge_ui(schema);
+        } else {
+            this._build_json_ui(schema);
+        }
+    }
+
+    _build_default_ui(first_data) {
+        if (typeof first_data === 'number') {
+            this._build_number_ui({ type: 'number' });
+        } else if (typeof first_data === 'string') {
+            this._build_log_ui({ type: 'text' });
+        } else {
+            this._build_json_ui({ type: 'object' });
+        }
+    }
+
+    _build_number_ui(schema) {
+        const val_div = new controls.div({
+            context: this.context,
+            class: 'value-display number-display'
+        });
+        this.content_container.add(val_div);
+
+        const label = new controls.h3({ context: this.context });
+        label.add(schema.name || 'Value');
+        val_div.add(label);
+
+        const value_text = new controls.div({ context: this.context, class: 'value-text' });
+        value_text.add('--');
+        val_div.add(value_text);
+
+        this._update_handler = (data) => {
+            let val = data;
+            if (typeof data === 'object' && data.value !== undefined) val = data.value;
+            value_text.dom.innerText = String(val);
+        };
+    }
+
+    _build_log_ui(schema) {
+        const log_container = new controls.div({
+            context: this.context,
+            class: 'value-display log-display'
+        });
+        this.content_container.add(log_container);
+
+        const label = new controls.h3({ context: this.context });
+        label.add(schema.name || 'Log');
+        log_container.add(label);
+
+        const log_area = new controls.div({ context: this.context, class: 'log-area' });
+        log_container.add(log_area);
+
+        this._update_handler = (data) => {
+            const entry = document.createElement('div');
+            entry.className = 'log-entry';
+            let msg = data;
+            if (typeof data === 'object') msg = data.message || JSON.stringify(data);
+
+            entry.innerText = `[${new Date().toLocaleTimeString()}] ${msg}`;
+            log_area.dom.appendChild(entry);
+            log_area.dom.scrollTop = log_area.dom.scrollHeight;
+        };
+    }
+
+    _build_gauge_ui(schema) {
+        // Simple progress bar for now
+        const container = new controls.div({
+            context: this.context,
+            class: 'value-display gauge-display'
+        });
+        this.content_container.add(container);
+
+        const label = new controls.h3({ context: this.context });
+        label.add(schema.name || 'Gauge');
+        container.add(label);
+
+        const bar_bg = new controls.div({ context: this.context, class: 'progress-bg' });
+        const bar_fill = new controls.div({ context: this.context, class: 'progress-fill' });
+        bar_bg.add(bar_fill);
+        container.add(bar_bg);
+
+        const value_text = new controls.div({ context: this.context, class: 'value-text-small' });
+        container.add(value_text);
+
+        const min = schema.min || 0;
+        const max = schema.max || 100;
+
+        this._update_handler = (data) => {
+            let val = data;
+            if (typeof data === 'object' && data.value !== undefined) val = data.value;
+
+            const pct = Math.max(0, Math.min(100, ((val - min) / (max - min)) * 100));
+            bar_fill.dom.style.width = pct + '%';
+            value_text.dom.innerText = `${val} / ${max}`;
+        }
+    }
+
+    _build_json_ui(schema) {
+        const container = new controls.div({
+            context: this.context,
+            class: 'value-display json-display'
+        });
+        this.content_container.add(container);
+
+        const label = new controls.h3({ context: this.context });
+        label.add(schema.name || 'Data');
+        container.add(label);
+
+        const pre = new controls.pre({ context: this.context });
+        container.add(pre);
+
+        this._update_handler = (data) => {
+            pre.dom.innerText = JSON.stringify(data, null, 2);
+        }
+    }
+}
+
+module.exports = Auto_Observable_UI;

package/docs/agent-development-guide.md

@@ -26,14 +26,97 @@ This document is specifically for AI agents working on the JSGUI3 Server codebas
 - Include comprehensive error handling and logging
 - Add JSDoc comments for public APIs
 
-### Development Workflow
-1. **Analyze the task** and understand requirements
-2. **Check existing code** for patterns and conventions
-3. **Implement changes** following established patterns
-4. **Test thoroughly** and document any issues found
-5. **Update documentation** including this guide
-
-## Codebase Structure Overview
+### Development Workflow
+1. **Analyze the task** and understand requirements
+2. **Check existing code** for patterns and conventions
+3. **Implement changes** following established patterns
+4. **Test thoroughly** and document any issues found
+5. **Update documentation** including this guide
+
+## Quick Start for AI Agents (Low Thinking Time)
+
+Use this section when you need to act fast with minimal deliberation. It is a short, repeatable workflow designed to reduce cognitive overhead.
+
+### Fast Lane Checklist (5 Minutes)
+1. **Read the task** and extract the target file, example, or subsystem.
+2. **Locate the target** with `rg` or `rg --files`.
+3. **Open the closest reference doc** from the map below.
+4. **Make a minimal, reversible change** that addresses the task.
+5. **Run the narrowest test** that validates the change.
+6. **Log any gaps** in "Known Issues" below if you find a blocker.
+
+### Quick Doc Map
+- **Repo overview**: `README.md`
+- **Testing workflow**: `tests/README.md`
+- **Bundling & assets**: `docs/bundling-system-deep-dive.md`
+- **Server publishing**: `docs/publishers-guide.md`
+- **Troubleshooting**: `docs/troubleshooting.md`
+- **MVVM + full-stack controls**: `docs/books/jsgui3-mvvm-fullstack/README.md`
+- **Agent workflow depth**: `docs/GUIDE_TO_AGENTIC_WORKFLOWS_BY_GROK.md`
+
+### Common Task Playbooks
+
+#### 1) Fix an Example or Control
+**Goal**: Example renders correctly with expected controls.
+1. Open `examples/.../client.js` and check for `Active_HTML_Document`.
+2. Ensure composition is inside `if (!spec.el)`.
+3. Confirm the control is exported: `controls.Demo_UI = Demo_UI`.
+4. Run the focused test: `node tests/test-runner.js --test=examples-controls.e2e.test.js`.
+5. If the error is render-time, reproduce with `Server_Static_Page_Context`.
+
+**Quick probe**:
+```js
+const Server_Static_Page_Context = require('./static-page-context');
+const jsgui = require('./examples/controls/1) window/client.js');
+const Ctrl = jsgui.controls.Demo_UI;
+const ctrl = new Ctrl({ context: new Server_Static_Page_Context() });
+const html = ctrl.all_html_render();
+```
+
+#### 2) Investigate a Bundling Failure
+**Goal**: Bundler completes and emits JS/CSS routes.
+1. Find bundler class in `resources/processors/bundlers`.
+2. Verify `complete(...)` is called on success and error paths.
+3. Run: `node tests/test-runner.js --test=bundlers.test.js`.
+4. If compression fails, check `docs/troubleshooting.md`.
+
+#### 3) Add or Extend Tests
+**Goal**: Increase coverage without breaking existing flows.
+1. Add new tests under `tests/` with smallest scope.
+2. Use snake_case names and minimal fixtures.
+3. Run only the new test: `node tests/test-runner.js --test=your-test-file.test.js`.
+4. Update `tests/README.md` if workflow changes.
+
+#### 4) Update or Add Documentation
+**Goal**: Keep agents and developers aligned on current behavior.
+1. Add short, high-signal sections (avoid large rewrites).
+2. Include commands and file paths.
+3. For broken behavior, add a "Known Issues" entry here.
+
+#### 5) MVVM Binding and Full-Stack Control Usage
+**Goal**: Wire data models to controls and serve them end to end.
+1. Build controls under `client.js` using `Active_HTML_Document`.
+2. Compose controls only when `!spec.el`.
+3. Use `this.data.model` and `this.view.data.model` plus `watch` and `computed`.
+4. Render server-side with `Server_Static_Page_Context` for quick validation.
+5. Serve with `Server.serve` and run `examples-controls.e2e.test.js`.
+
+### Rapid Triage Checklist (When Tests Fail)
+1. Identify whether the failure is **render**, **bundle**, **runtime**, or **assertion**.
+2. If render: instantiate with `Server_Static_Page_Context`.
+3. If bundle: inspect esbuild logs and `resources/processors/bundlers/...`.
+4. If runtime: open the example in a browser or puppeteer.
+5. If assertion: validate expected output and update fixtures.
+
+### Suggested Minimal Command Set
+```bash
+rg -n "needle" path/
+rg --files path/
+node tests/test-runner.js --test=examples-controls.e2e.test.js
+node tests/test-runner.js --test=window-examples.puppeteer.test.js
+```
+
+## Codebase Structure Overview
 
 ### Core Architecture
 
@@ -487,4 +570,4 @@ If you discover critical issues:
 
 ---
 
-**Remember**: This guide is the central place for agents to document broken functionality and implementation gaps. If you find something broken or incomplete, document it here immediately with details about location, impact, and status.
+**Remember**: This guide is the central place for agents to document broken functionality and implementation gaps. If you find something broken or incomplete, document it here immediately with details about location, impact, and status.

package/docs/books/admin-ui/01-introduction.md

@@ -0,0 +1,32 @@
+# Chapter 1: Introduction
+
+## Vision
+
+The Admin UI is the **go-to interface** for developers and operators to administer `jsgui3-server` instances. It should be:
+
+- **Instantaneous**: Zero setup required; just navigate to `/admin`
+- **Insightful**: Surface the internal state of the server in real-time
+- **Actionable**: Allow common admin tasks directly from the UI
+
+## Goals
+
+1. **Visibility into Observables**: If a server publishes an observable (e.g., for crawl progress, metrics), the Admin UI should display it automatically with an appropriate control.
+2. **Resource Browser**: List all registered resources (routes, publishers, static paths) with introspection.
+3. **Configuration Panel**: View and modify server configuration (where safe).
+4. **Performance Metrics**: Display throughput, active connections, memory usage.
+
+## Inspiration
+
+The design is inspired by:
+- Database admin tools (pgAdmin, phpMyAdmin)
+- Monitoring dashboards (Grafana, Kibana)
+- The jsgui3 Window control aesthetic
+
+## Target Experience
+
+A developer starts a jsgui3-server, then navigates to `http://localhost:PORT/admin`. They immediately see:
+- A sidebar listing all resources
+- A main panel showing the selected resource's details
+- Real-time updates for any observables
+
+No extra code required—the Admin UI is built into jsgui3-server and activates automatically.