jsgui3-server 0.0.140 → 0.0.141

package/docs/publishers-guide.md

@@ -100,6 +100,82 @@ const publisher = new HTTP_Function_Publisher({
 - Support for common image formats (JPEG, PNG, SVG, etc.)
 - Efficient streaming for large files
 
+### HTTP_Observable_Publisher
+
+**Purpose:** Streams observable data to clients using Server-Sent Events (SSE).
+
+**Key Features:**
+- Real-time streaming of observable events
+- SSE protocol support (`text/event-stream`)
+- Chunked transfer encoding for long-running connections
+- Integration with `fnl` observables
+
+**Usage:**
+```javascript
+const { observable } = require('fnl');
+const Observable_Publisher = require('jsgui3-server/publishers/http-observable-publisher');
+
+// Create a hot observable that emits continuously
+let tick_count = 0;
+const tick_stream = observable((next, complete, error) => {
+    const interval = setInterval(() => {
+        tick_count++;
+        next({
+            tick: tick_count,
+            timestamp: Date.now(),
+            message: `Server tick #${tick_count}`
+        });
+    }, 1000);
+    
+    // Return cleanup function
+    return [() => clearInterval(interval)];
+});
+
+// Create the SSE publisher
+const publisher = new Observable_Publisher({
+    obs: tick_stream
+});
+
+// Register with server router
+server.server_router.set_route('/api/stream', publisher, publisher.handle_http);
+```
+
+**Client-Side Consumption:**
+```javascript
+// In browser, use EventSource API
+const eventSource = new EventSource('/api/stream');
+
+eventSource.onmessage = (event) => {
+    if (event.data === 'OK') {
+        console.log('SSE handshake complete');
+        return;
+    }
+    const data = JSON.parse(event.data);
+    console.log('Received:', data);
+};
+
+eventSource.onerror = () => {
+    eventSource.close();
+};
+```
+
+**SSE Protocol:**
+The publisher sends events in SSE format:
+```
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+Transfer-Encoding: chunked
+
+OK
+event: message
+data:{"tick":1,"timestamp":1234567890,"message":"Server tick #1"}
+
+event: message
+data:{"tick":2,"timestamp":1234567891,"message":"Server tick #2"}
+```
+
+**See Also:** [Observable SSE Demo](../examples/controls/15)%20window,%20observable%20SSE/) for a complete working example.
+
 ## Publisher Architecture
 
 ### Base Publisher Class

package/docs/troubleshooting.md

@@ -216,6 +216,57 @@ input.js:1:0: ERROR: Expected identifier but found "}"
    }
    ```
 
+### Text Content Not Rendering
+
+**Symptoms:**
+- HTML elements appear but are empty
+- Buttons have text but divs, spans, h2 don't
+- Server-side rendered HTML shows empty tags
+
+**Cause:** Using `text` property instead of `.add()` method for HTML elements.
+
+**Solutions:**
+
+1. **Use `.add()` for HTML elements (div, span, h2, etc.):**
+   ```javascript
+   // ❌ WRONG - text won't render
+   const title = new controls.h2({ context, text: 'My Title' });
+   
+   // ❌ WRONG - text property won't render
+   const div = new controls.div({ context });
+   div.text = 'Content';
+   
+   // ✅ CORRECT - use .add() method
+   const title = new controls.h2({ context });
+   title.add('My Title');
+   
+   const div = new controls.div({ context });
+   div.add('Content');
+   ```
+
+2. **Composite controls (Button, Checkbox) DO support text property:**
+   ```javascript
+   // ✅ CORRECT - Button handles text internally
+   const button = new controls.Button({ context, text: 'Click Me' });
+   ```
+
+3. **Test rendering without server:**
+   Create a `check.js` file to verify text renders:
+   ```javascript
+   const jsgui = require('./client');
+   const { MyControl } = jsgui.controls;
+   const Server_Page_Context = require('jsgui3-server/page-context');
+   
+   const context = new Server_Page_Context();
+   const control = new MyControl({ context });
+   const html = control.all_html_render();
+   
+   // Check if expected text is in HTML
+   console.log(html.includes('Expected Text') ? 'PASS' : 'FAIL');
+   ```
+
+**Why this happens:** HTML element controls (`div`, `h2`, `span`) are thin wrappers around DOM elements. Text is a child node, not a property. Composite controls like `Button` have explicit code to handle the `text` property.
+
 ### CSS Not Loading
 
 **Symptoms:**

package/examples/controls/15) window, observable SSE/README.md

@@ -0,0 +1,125 @@
+# Observable SSE Demo
+
+This example demonstrates the **HTTP_Observable_Publisher** with Server-Sent Events (SSE), showing how jsgui3-server's observable-first architecture enables real-time streaming from server to client.
+
+![Demo showing real-time tick counter updating via SSE](../../.playwright-mcp/page-2025-11-29T23-39-31-903Z.png)
+
+## Quick Start
+
+```bash
+cd "examples/controls/15) window, observable SSE"
+node server.js
+# Open http://localhost:52015
+```
+
+## What This Demonstrates
+
+### Server Side (`server.js`)
+
+1. **Observable Creation** with `fnl`:
+   ```javascript
+   const {obs} = require('fnl');
+   
+   const progress_observable = obs((next, complete, error) => {
+       // next(data) - emit intermediate values
+       // complete(result) - signal completion
+       // error(err) - signal failure
+       return [cleanup_fn]; // cleanup functions
+   });
+   ```
+
+2. **HTTP_Observable_Publisher** setup:
+   ```javascript
+   const Observable_Publisher = require('jsgui3-server/publishers/http-observable-publisher');
+   
+   const publisher = new Observable_Publisher({ obs: progress_observable });
+   server.server_router.set_route('/api/progress-stream', publisher, publisher.handle_http);
+   ```
+
+3. **SSE Transport**: The publisher automatically serves `text/event-stream` content type with chunked transfer encoding.
+
+### Client Side (`client.js`)
+
+1. **EventSource API** for consuming SSE:
+   ```javascript
+   const event_source = new EventSource('/api/progress-stream');
+   
+   event_source.onmessage = (event) => {
+       const data = JSON.parse(event.data);
+       update_ui(data);
+   };
+   ```
+
+2. **Reactive UI Updates**: The `Observable_Demo_UI` control updates progress bars, status text, and log entries in real-time as events arrive.
+
+## The SSE Protocol
+
+Server-Sent Events use HTTP chunked transfer encoding:
+
+```
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+Transfer-Encoding: chunked
+
+event: message
+data: {"progress": 10, "stage": "Loading..."}
+
+event: message
+data: {"progress": 20, "stage": "Processing..."}
+
+...
+```
+
+## Observable Pattern Benefits
+
+| Approach | When to Use |
+|----------|-------------|
+| **Observable + SSE** | Long-running operations, real-time progress, streaming data |
+| **Promise** | Single async result (most API calls) |
+| **Sync return** | Immediate data, no I/O |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Server                                                      │
+│  ┌──────────────────┐    ┌────────────────────────────────┐ │
+│  │ Observable       │───►│ HTTP_Observable_Publisher      │ │
+│  │ obs((next,...)=>{│    │ • Sets text/event-stream       │ │
+│  │   next(progress) │    │ • Writes SSE format            │ │
+│  │ })               │    │ • Keeps connection open        │ │
+│  └──────────────────┘    └───────────────┬────────────────┘ │
+└──────────────────────────────────────────┼──────────────────┘
+                                           │ HTTP
+                                           ▼
+┌──────────────────────────────────────────┴──────────────────┐
+│  Browser                                                     │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ EventSource('/api/progress-stream')                    │ │
+│  │   .onmessage = (event) => {                            │ │
+│  │       update_ui(JSON.parse(event.data));               │ │
+│  │   }                                                    │ │
+│  └────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Files
+
+- `client.js` - Control with SSE consumer and reactive UI
+- `server.js` - Server with observable publisher setup
+- `README.md` - This documentation
+
+## Future Direction
+
+The strategic goal is to auto-detect observable returns in function publishers:
+
+```javascript
+// Future: This should "just work" with SSE transport
+server.publish('/api/progress', () => {
+    return obs((next, complete, error) => {
+        // Long-running operation...
+    });
+});
+```
+
+See `.github/agents/jsgui3-server.agent.md` for the full observable-first strategy.

package/examples/controls/15) window, observable SSE/check.js

@@ -0,0 +1,144 @@
+/**
+ * check.js - Verify that all text renders properly in the Observable SSE Demo control
+ * 
+ * This script instantiates the control server-side and checks that all expected
+ * text content is present in the rendered HTML output. No server required.
+ * 
+ * Run with: node check.js
+ */
+
+const jsgui = require('./client');
+const {Observable_Demo_UI} = jsgui.controls;
+
+// Create a server-side page context for rendering
+const Server_Page_Context = require('../../../page-context');
+const context = new Server_Page_Context();
+
+console.log('Observable SSE Demo - Text Rendering Check');
+console.log('='.repeat(50));
+console.log('');
+
+// Instantiate the control (no spec.el, so compose() will run)
+const demo_ui = new Observable_Demo_UI({
+    context: context
+});
+
+// Render to HTML
+const html = demo_ui.all_html_render();
+
+// Define all expected text content
+const expected_texts = [
+    // Header
+    { text: 'Observable SSE Demo - Real-Time Tick Stream', description: 'Page title (h2)' },
+    
+    // Status section
+    { text: 'Status: Not connected', description: 'Initial status text' },
+    
+    // Tick display
+    { text: '--', description: 'Initial tick count placeholder' },
+    { text: 'Server Ticks', description: 'Tick label' },
+    
+    // Event log label
+    { text: 'Event Log (SSE messages):', description: 'Log section label' },
+    
+    // Buttons
+    { text: 'Connect to SSE', description: 'Connect button text' },
+    { text: 'Disconnect', description: 'Disconnect button text' },
+    { text: 'Clear Log', description: 'Clear Log button text' },
+];
+
+// Check each expected text
+let pass_count = 0;
+let fail_count = 0;
+
+console.log('Checking rendered HTML for expected text content:');
+console.log('');
+
+for (const {text, description} of expected_texts) {
+    const found = html.includes(text);
+    const status = found ? '✓ PASS' : '✗ FAIL';
+    const color = found ? '\x1b[32m' : '\x1b[31m';
+    const reset = '\x1b[0m';
+    
+    console.log(`  ${color}${status}${reset}  "${text}"`);
+    console.log(`         └─ ${description}`);
+    
+    if (found) {
+        pass_count++;
+    } else {
+        fail_count++;
+    }
+}
+
+console.log('');
+console.log('-'.repeat(50));
+console.log(`Results: ${pass_count} passed, ${fail_count} failed`);
+console.log('');
+
+// Also check for important HTML structure
+console.log('Additional structural checks:');
+console.log('');
+
+const structural_checks = [
+    { pattern: 'id="status-label"', description: 'Status label has ID' },
+    { pattern: 'id="tick-count"', description: 'Tick count has ID' },
+    { pattern: 'id="event-log"', description: 'Event log has ID' },
+    { pattern: 'id="connect-btn"', description: 'Connect button has ID' },
+    { pattern: 'id="disconnect-btn"', description: 'Disconnect button has ID' },
+    { pattern: 'id="clear-btn"', description: 'Clear button has ID' },
+    { pattern: '<button', description: 'Button elements present' },
+    { pattern: '<h2', description: 'H2 heading present' },
+    { pattern: 'class="sse-container"', description: 'SSE container class' },
+    { pattern: 'class="tick-display"', description: 'Tick display class' },
+    { pattern: 'class="button-container"', description: 'Button container class' },
+];
+
+let struct_pass = 0;
+let struct_fail = 0;
+
+for (const {pattern, description} of structural_checks) {
+    const found = html.includes(pattern);
+    const status = found ? '✓ PASS' : '✗ FAIL';
+    const color = found ? '\x1b[32m' : '\x1b[31m';
+    const reset = '\x1b[0m';
+    
+    console.log(`  ${color}${status}${reset}  ${pattern}`);
+    console.log(`         └─ ${description}`);
+    
+    if (found) {
+        struct_pass++;
+    } else {
+        struct_fail++;
+    }
+}
+
+console.log('');
+console.log('-'.repeat(50));
+console.log(`Structural: ${struct_pass} passed, ${struct_fail} failed`);
+console.log('');
+
+// Final summary
+const total_pass = pass_count + struct_pass;
+const total_fail = fail_count + struct_fail;
+const total = total_pass + total_fail;
+
+console.log('='.repeat(50));
+if (total_fail === 0) {
+    console.log('\x1b[32m✓ ALL CHECKS PASSED\x1b[0m');
+    console.log(`  ${total_pass}/${total} checks successful`);
+} else {
+    console.log('\x1b[31m✗ SOME CHECKS FAILED\x1b[0m');
+    console.log(`  ${total_pass}/${total} checks passed, ${total_fail} failed`);
+}
+console.log('='.repeat(50));
+
+// Optionally output the full HTML for debugging
+if (process.argv.includes('--html') || process.argv.includes('-h')) {
+    console.log('');
+    console.log('Rendered HTML:');
+    console.log('-'.repeat(50));
+    console.log(html);
+}
+
+// Exit with appropriate code
+process.exit(total_fail > 0 ? 1 : 0);