jsgui3-server 0.0.140 → 0.0.141

package/.github/instructions/copilot.instructions.md

@@ -0,0 +1,180 @@
+---
+description: "GitHub Copilot instructions for jsgui3-server development"
+applyTo: "**"
+---
+
+# GitHub Copilot — jsgui3-server Playbook
+
+## Primary References
+
+- **`AGENTS.md`** — Root agent guidance with documentation index
+- **`.github/agents/jsgui3-server.agent.md`** — Detailed patterns and anti-patterns
+- **`docs/agent-development-guide.md`** — Broken functionality tracker (CHECK FIRST)
+
+## Core Conventions
+
+### Naming (Non-Negotiable)
+```javascript
+// Variables, functions → snake_case
+const my_variable = 'value';
+function process_data() {}
+
+// Classes → PascalCase
+class My_Control extends Active_HTML_Document {}
+```
+
+### Control Lifecycle (The Canonical Pattern)
+```javascript
+class My_Control extends Active_HTML_Document {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'my_control';
+        super(spec);
+        const { context } = this;
+        
+        const compose = () => {
+            // Build UI here
+        };
+        
+        if (!spec.el) { compose(); }  // Conditional compose!
+    }
+    
+    activate() {
+        if (!this.__active) {        // Guard against double activation!
+            super.activate();
+            // Event bindings here
+        }
+    }
+}
+
+My_Control.css = `/* styles */`;     // CSS as static property!
+```
+
+## Quick Commands
+
+```bash
+# Run example
+cd examples/controls/001_demo_page && node server.js
+
+# Tests
+npm test                  # All
+npm run test:bundlers     # Bundler tests
+npm run test:publishers   # Publisher tests
+
+# Debug mode
+JSGUI_DEBUG=1 node server.js
+```
+
+## Before You Code
+
+1. **Check known issues**: `docs/agent-development-guide.md` has the broken functionality tracker
+2. **Find patterns**: Look at `examples/controls/` for reference implementations
+3. **Update docs**: If you find something broken, document it immediately
+
+## Anti-Patterns to Avoid
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| `document.getElementById()` | `this.body.add.div({ id: 'x' })` |
+| Always compose in constructor | `if (!spec.el) { compose(); }` |
+| `activate()` without guard | `if (!this.__active) { super.activate(); }` |
+| `server.start()` immediately | `server.on('ready', () => server.start())` |
+| `new controls.h2({ text: 'Hi' })` | `h2.add('Hi')` — Use `.add()` for text! |
+| `controls.button` (lowercase) | `controls.Button` (PascalCase for composites) |
+
+## ⚠️ Critical: Text Content in Controls
+
+**HTML elements** (div, span, h2) use `.add()` for text:
+```javascript
+const title = new controls.h2({ context });
+title.add('My Title');  // ✅ Correct
+
+// ❌ WRONG: text property won't render for HTML elements
+const title = new controls.h2({ context, text: 'My Title' });  // Empty!
+```
+
+**Composite controls** (Button, Checkbox) DO support `text` property:
+```javascript
+const button = new controls.Button({ context, text: 'Click' });  // ✅ Works
+```
+
+**Control naming:**
+- HTML elements: lowercase (`controls.div`, `controls.h2`)
+- Composites: PascalCase (`controls.Button`, `controls.Window`)
+
+**Set IDs via:** `control.dom.attributes.id = 'my-id'`
+
+## Key Architectural Facts
+
+- **Isomorphic**: Controls render server-side, activate client-side
+- **ESBuild**: JavaScript bundling handled by ESBuild
+- **CSS extraction**: CSS comes from static `.css` property on control classes
+- **Publishers**: Different content types (webpage, function, css) have dedicated publishers
+- **Context**: Central runtime object - extract with `const { context } = this;`
+
+## When Creating Controls
+
+1. Set `__type_name` before `super()`
+2. Extract `context` after `super()`
+3. Define `compose()` function for UI building
+4. Use `if (!spec.el) { compose(); }` for conditional composition
+5. Guard `activate()` with `if (!this.__active)`
+6. Put CSS on static `.css` property
+
+## Server Startup
+
+```javascript
+// Recommended: Server.serve() API
+const Server = require('jsgui3-server');
+Server.serve({ 
+    Ctrl: My_Control, 
+    src_path_client_js: __dirname + '/client.js',
+    port: 8080 
+});
+
+// Auto-port selection (avoids conflicts)
+Server.serve({ 
+    Ctrl: My_Control, 
+    src_path_client_js,
+    port: 'auto'  // or port: 0
+});
+
+// Manual: Wait for 'ready' event
+const server = new Server({ Ctrl, src_path_client_js });
+server.on('ready', () => server.start(8080));
+```
+
+## Port Utilities
+
+```javascript
+const { get_free_port, is_port_available } = require('jsgui3-server');
+
+const port = await get_free_port();  // Find any free port
+const available = await is_port_available(8080);  // Check specific port
+```
+
+## Data Binding
+
+```javascript
+const { Data_Object, field } = require('obext');
+
+const model = new Data_Object({
+    count: field(0)
+});
+
+model.on('change.count', (e) => {
+    // React to changes
+});
+
+model.count++;  // Triggers change event
+```
+
+## Documentation When Stuck
+
+| Topic | File |
+|-------|------|
+| Architecture overview | `README.md` |
+| Comprehensive API | `docs/comprehensive-documentation.md` |
+| Control development | `docs/controls-development.md` |
+| Publisher system | `docs/publishers-guide.md` |
+| Troubleshooting | `docs/troubleshooting.md` |
+| **Broken stuff** | `docs/agent-development-guide.md` |

package/docs/agent-development-guide.md

@@ -106,6 +106,20 @@ jsgui3-server/
 - [x] Data binding with observable models
 - [x] CSS as static properties
 
+#### Port Utilities (NEW)
+- [x] `get_free_port()` - Find available port
+- [x] `is_port_available()` - Check if port is free
+- [x] `get_free_ports()` - Find multiple ports
+- [x] `get_port_or_free()` - Prefer port or find free
+- [x] `port: 'auto'` option in Server.serve()
+- [x] Documented in api-reference.md
+
+#### Observable Publisher (Documented)
+- [x] HTTP_Observable_Publisher for SSE streaming
+- [x] Integration with `fnl` observables
+- [x] Working example in `examples/controls/15) window, observable SSE/`
+- [x] Documented in publishers-guide.md
+
 ### 🚧 In Progress / Partially Complete
 
 #### Website Publisher
@@ -192,6 +206,7 @@ jsgui3-server/
    - Emit single clear "Server ready" message
    - Ensure all publishers are ready before signaling
    - Update CLI to wait for proper ready signal
+   - **Note**: Currently emits "ready" twice, causing port conflicts in tests
 
 4. **Default Holding Page**
    - Serve simple HTML when no content configured
@@ -199,22 +214,28 @@ jsgui3-server/
    - Allow configuration override
 
 ### Medium Priority
-5. **File Manager Interface**
+5. **Observable API Integration**
+   - Detect observable returns in HTTP_Function_Publisher
+   - Auto-switch to SSE transport for observable endpoints
+   - Add client-side `context.subscribe()` for consuming streams
+   - Document observable publishing patterns
+
+6. **File Manager Interface**
    - Create admin UI for browsing/serving directories
    - Integrate with file system resource
    - Add upload/download capabilities
 
-6. **CSS Bundling Cleanup**
+7. **CSS Bundling Cleanup**
    - Remove legacy bundle paths
    - Consolidate CSS extraction logic
    - Ensure reliable CSS bundling
 
-7. **Configuration File Support**
+8. **Configuration File Support**
    - Add `jsgui.config.js` support
    - Implement `--config` CLI option
    - Document configuration patterns
 
-8. **Graceful Shutdown**
+9. **Graceful Shutdown**
    - Handle SIGINT/SIGTERM signals
    - Clean up resources properly
    - Print shutdown confirmation
@@ -232,6 +253,45 @@ jsgui3-server/
 
 ## Development Patterns
 
+### Observable Pattern (Core to jsgui3-server)
+
+The `fnl` module provides observables used throughout for async operations with intermediate results:
+
+```javascript
+const {obs} = require('fnl');
+
+// Creating an observable
+const my_async_operation = obs((next, complete, error) => {
+    // Emit progress/intermediate values
+    next({ stage: 'parsing', progress: 25 });
+    next({ stage: 'bundling', progress: 75 });
+    
+    // Complete with final result (acts like promise resolution)
+    complete({ bundle: compiled_code });
+    
+    // Or error (acts like promise rejection)
+    // error(new Error('compilation failed'));
+    
+    // Return cleanup functions (optional)
+    return [() => cleanup_resources()];
+});
+
+// Consuming an observable
+my_async_operation.on('next', data => console.log('Progress:', data));
+my_async_operation.on('complete', result => console.log('Done:', result));
+my_async_operation.on('error', err => console.error('Failed:', err));
+```
+
+**Key locations using observables:**
+- `publishers/http-observable-publisher.js` — SSE streaming to clients
+- `resources/processors/bundlers/*.js` — All bundling operations
+- `publishers/http-website-publisher.js` — Website build pipeline
+
+**Observable vs Promise:**
+- Use **observable** when operation has meaningful intermediate states (bundling progress, streaming data)
+- Use **promise** for simple async one-shot operations
+- The `http-function-publisher.js` already detects promises; extend to detect observables
+
 ### Control Creation Pattern
 ```javascript
 class MyControl extends Active_HTML_Document {
@@ -264,6 +324,41 @@ class MyControl extends Active_HTML_Document {
 MyControl.css = `/* CSS styles */`;
 ```
 
+### ⚠️ Critical Pattern: Text Content in Controls
+
+**This is a common pitfall!** HTML element controls and composite controls handle text differently:
+
+```javascript
+// ❌ WRONG: text property/assignment doesn't work for HTML elements
+const title = new controls.h2({ context, text: 'My Title' });  // Won't render!
+const div = new controls.div({ context });
+div.text = 'Content';  // Won't render!
+
+// ✅ CORRECT: Use .add() for HTML elements (div, span, h2, etc.)
+const title = new controls.h2({ context });
+title.add('My Title');  // ✅ Renders correctly
+
+const div = new controls.div({ context });
+div.add('Content');  // ✅ Renders correctly
+
+// ✅ Composite controls (Button, Checkbox) DO support text property
+const button = new controls.Button({ context, text: 'Click Me' });  // ✅ Works
+```
+
+**Why?** HTML elements are thin wrappers where text is a child node. Composite controls like `Button` have internal `compose_button()` that calls `this.add(this.text)`.
+
+**Control Naming:**
+| Type | Naming | Examples |
+|------|--------|----------|
+| HTML elements | lowercase | `controls.div`, `controls.span`, `controls.h2` |
+| Composite controls | PascalCase | `controls.Button`, `controls.Window`, `controls.Checkbox` |
+
+**Setting Element IDs:**
+```javascript
+const div = new controls.div({ context });
+div.dom.attributes.id = 'my-id';  // ✅ Correct way to set ID
+```
+
 ### Publisher Creation Pattern
 ```javascript
 class CustomPublisher extends HTTP_Publisher {
@@ -321,9 +416,18 @@ class CustomResource extends Resource {
 
 ### Architecture Insights
 - **Event-Driven Design**: Heavy use of Evented_Class and observable patterns
+- **Observable-First Async**: `fnl` observables used for all multi-stage operations (bundling, compilation)
 - **Resource Pool Pattern**: Centralized resource management
 - **Publisher Abstraction**: Clean separation of content types
 - **Context System**: Runtime environment management
+- **SSE Infrastructure**: `HTTP_Observable_Publisher` already implements Server-Sent Events for streaming
+
+### Observable Pattern (Strategic Differentiator)
+The `obs()` factory from `fnl` is used throughout for operations with intermediate results:
+- Bundlers emit progress updates during compilation
+- Website publisher streams build status
+- Can be exposed at API level for real-time client updates
+- `HTTP_Observable_Publisher` already handles SSE transport
 
 ### Complexity Areas
 - **Bundling System**: Multi-stage CSS/JS processing

package/docs/api-reference.md

@@ -99,6 +99,122 @@ server.use(middleware: Function): void
 **Parameters:**
 - `middleware` (Function): Express-style middleware function
 
+## Port Utilities
+
+The `port-utils` module provides automatic port selection to avoid conflicts.
+
+### get_free_port(options)
+
+Find a free port on the system.
+
+**Signature:**
+```javascript
+get_free_port(options?: PortOptions): Promise<number>
+```
+
+**Parameters:**
+- `options.host` (string, optional): Host to check (default: '127.0.0.1')
+- `options.startPort` (number, optional): Starting port to try (default: 0 = OS chooses)
+- `options.endPort` (number, optional): Maximum port to try (default: 65535)
+
+**Returns:** Promise resolving to an available port number
+
+**Example:**
+```javascript
+const { get_free_port } = require('jsgui3-server');
+
+const port = await get_free_port();
+console.log(`Using port: ${port}`);
+
+// Or with options
+const port = await get_free_port({ startPort: 8080 });
+```
+
+### is_port_available(port, host)
+
+Check if a specific port is available.
+
+**Signature:**
+```javascript
+is_port_available(port: number, host?: string): Promise<boolean>
+```
+
+**Parameters:**
+- `port` (number): Port to check
+- `host` (string, optional): Host to check (default: '127.0.0.1')
+
+**Returns:** Promise resolving to `true` if available, `false` if in use
+
+**Example:**
+```javascript
+const { is_port_available } = require('jsgui3-server');
+
+if (await is_port_available(8080)) {
+    console.log('Port 8080 is free');
+}
+```
+
+### get_free_ports(count, options)
+
+Find multiple free ports.
+
+**Signature:**
+```javascript
+get_free_ports(count: number, options?: PortOptions): Promise<number[]>
+```
+
+**Parameters:**
+- `count` (number): Number of ports to find
+- `options` (PortOptions, optional): Same as `get_free_port`
+
+**Returns:** Promise resolving to array of available port numbers
+
+### get_port_or_free(preferred_port, host)
+
+Get a specific port if available, otherwise find a free one.
+
+**Signature:**
+```javascript
+get_port_or_free(preferred_port: number, host?: string): Promise<number>
+```
+
+**Parameters:**
+- `preferred_port` (number): Preferred port (0 = auto-select)
+- `host` (string, optional): Host to check (default: '127.0.0.1')
+
+**Returns:** Promise resolving to the preferred port if available, or a free port
+
+**Example:**
+```javascript
+const { get_port_or_free } = require('jsgui3-server');
+
+// Try 8080, fall back to any free port
+const port = await get_port_or_free(8080);
+```
+
+### Auto-Port in Server.serve()
+
+The `Server.serve()` API supports automatic port selection:
+
+```javascript
+const Server = require('jsgui3-server');
+
+// Auto-select a free port
+Server.serve({
+    Ctrl: MyControl,
+    port: 'auto'  // or port: 0
+}).then(server => {
+    console.log(`Running on port ${server.port}`);
+});
+
+// Or use autoPort option
+Server.serve({
+    Ctrl: MyControl,
+    autoPort: true,
+    port: 8080  // Will fall back to free port if 8080 is in use
+});
+```
+
 ## Control Classes
 
 ### Active_HTML_Document

package/docs/controls-development.md

@@ -155,6 +155,24 @@ const button = new controls.Button({
 });
 ```
 
+> **⚠️ Important: Text Content Patterns**
+>
+> Different controls handle text content differently:
+>
+> **Composite controls** (Button, Checkbox, etc.) accept `text` in spec:
+> ```javascript
+> const button = new controls.Button({ context, text: 'Click Me' });  // ✅ Works
+> ```
+>
+> **HTML element controls** (div, span, h2, etc.) require `.add()` method:
+> ```javascript
+> const title = new controls.h2({ context });
+> title.add('My Heading');  // ✅ Correct
+> // title.text = 'My Heading';  // ❌ Won't render
+> ```
+>
+> See [Text Content](#text-content-in-controls) section for details.
+
 #### Text_Input
 
 **Purpose:** Text input field control.
@@ -408,6 +426,115 @@ if (this.body.has_class('active')) {
 }
 ```
 
+## Text Content in Controls
+
+### The `.add()` Method (For HTML Elements)
+
+For basic HTML element controls (`div`, `span`, `h2`, `p`, etc.), use the `.add()` method to add text content:
+
+```javascript
+// ✅ Correct: Use .add() for HTML elements
+const title = new controls.h2({ context });
+title.add('My Page Title');
+container.add(title);
+
+const paragraph = new controls.div({ context, 'class': 'content' });
+paragraph.add('This is the text content.');
+container.add(paragraph);
+
+const label = new controls.span({ context });
+label.add('Label: ');
+container.add(label);
+```
+
+### The `text` Property (For Composite Controls)
+
+Some composite controls like `Button`, `Checkbox`, and custom controls explicitly handle the `text` property:
+
+```javascript
+// ✅ Correct: Button handles text property
+const button = new controls.Button({
+    context,
+    text: 'Submit Form'
+});
+
+// ✅ Checkbox uses label.text
+const checkbox = new controls.Checkbox({
+    context,
+    label: { text: 'Accept terms' }
+});
+```
+
+### Common Mistake: Text Not Rendering
+
+```javascript
+// ❌ WRONG: text property won't render for div/h2/span
+const title = new controls.h2({
+    context,
+    text: 'This will NOT appear'  // Won't render!
+});
+
+// ❌ WRONG: .text assignment won't render
+const div = new controls.div({ context });
+div.text = 'This also won\'t appear';  // Won't render!
+
+// ✅ CORRECT: Use .add() method
+const title = new controls.h2({ context });
+title.add('This WILL appear');  // ✅ Renders correctly
+```
+
+### Why This Pattern Exists
+
+JSGUI3 follows the DOM model where text is a child node, not a property. The `.add()` method creates a `Text_Node` child that renders properly both server-side and client-side.
+
+Composite controls like `Button` have a `compose_button()` method that internally calls `this.add(this.text)`, which is why they work differently.
+
+### Setting Element IDs
+
+To set an element's ID attribute for client-side access:
+
+```javascript
+// ✅ Correct: Use dom.attributes.id
+const status_div = new controls.div({ context });
+status_div.dom.attributes.id = 'status-display';
+status_div.add('Ready');
+container.add(status_div);
+
+// In activate(), access via getElementById:
+activate() {
+    if (!this.__active) {
+        super.activate();
+        const status = document.getElementById('status-display');
+        status.textContent = 'Active';  // Update via DOM
+    }
+}
+```
+
+### Control Naming Conventions
+
+JSGUI3 controls follow specific naming patterns:
+
+| Type | Naming | Examples |
+|------|--------|----------|
+| HTML elements | lowercase | `controls.div`, `controls.span`, `controls.h2`, `controls.button` (native) |
+| Composite controls | PascalCase | `controls.Button`, `controls.Window`, `controls.Checkbox`, `controls.Panel` |
+| Custom controls | PascalCase | `controls.My_Custom_Control`, `controls.Dashboard` |
+
+```javascript
+// HTML elements (lowercase)
+const div = new controls.div({ context });
+const span = new controls.span({ context });
+const h1 = new controls.h1({ context });
+
+// Composite controls (PascalCase)
+const button = new controls.Button({ context, text: 'Click' });
+const window = new controls.Window({ context, title: 'My Window' });
+const checkbox = new controls.Checkbox({ context });
+```
+
+> **Note:** `controls.button` (lowercase) creates a native `<button>` element without Button class features.
+> `controls.Button` (PascalCase) creates the full Button control with text handling and styling.
+
 ### CSS Extraction and Bundling
 
 CSS is automatically extracted from control classes and bundled by the server: