jsgui3-server 0.0.142 → 0.0.144

package/docs/comprehensive-documentation.md

@@ -284,11 +284,30 @@ body {
 }
 `;
 
-controls.MyControl = MyControl;
-module.exports = jsgui;
-```
-
-2. Create server:
+controls.MyControl = MyControl;
+module.exports = jsgui;
+```
+
+    SCSS/SASS: You can also set `MyControl.scss` or `MyControl.sass` using template literals. These are compiled to CSS during bundling and removed from the JS output, just like `.css`. CSS and SCSS blocks can be mixed in a control; the bundler preserves their order during compilation. If you mix indented `.sass` with `.scss`/`.css`, each block is compiled independently to preserve order. Inline CSS sourcemaps are emitted only when a single compilation pass is used; mixed syntax skips inline maps to keep them accurate.
+
+    To enable inline CSS sourcemaps for Sass/SCSS outputs, pass a `style` configuration:
+
+    ```javascript
+    Server.serve({
+        ctrl: MyControl,
+        src_path_client_js: require.resolve('./client.js'),
+        debug: true,
+        style: {
+            sourcemaps: {
+                enabled: true,
+                inline: true,
+                include_sources: true
+            }
+        }
+    });
+    ```
+
+2. Create server:
 
 ```javascript
 // server.js
@@ -1400,4 +1419,4 @@ MIT License - see LICENSE file for details.
 ---
 
 This documentation provides a comprehensive overview of JSGUI3 Server. For more detailed information about specific components, see the individual files in the `docs/` directory and the examples in `examples/`.</content>
-<parameter name="filePath">c:\\Users\\james\\Documents\\repos\\jsgui3-server\\docs\\comprehensive-documentation.md
+<parameter name="filePath">c:\\Users\\james\\Documents\\repos\\jsgui3-server\\docs\\comprehensive-documentation.md

package/docs/configuration-reference.md

@@ -198,16 +198,51 @@ Configuration values are resolved in this order (later sources override earlier
   });
   ```
 
-#### `config`
-- **Type:** `string`
-- **Description:** Path to configuration file
-- **Default:** `'jsgui.config.js'` (if exists)
-- **Example:**
-  ```javascript
-  Server.serve({
-      config: './my-config.js'
-  });
-  ```
+#### `config`
+- **Type:** `string`
+- **Description:** Path to configuration file
+- **Default:** `'jsgui.config.js'` (if exists)
+- **Example:**
+  ```javascript
+  Server.serve({
+      config: './my-config.js'
+  });
+  ```
+
+#### `style`
+- **Type:** `object`
+- **Description:** Style pipeline options for CSS/SCSS/Sass extraction and compilation.
+- **Default:** `{}` (inherits debug behavior for sourcemaps)
+- **Example:**
+  ```javascript
+  Server.serve({
+      ctrl: MyControl,
+      debug: true,
+      style: {
+          sourcemaps: {
+              enabled: true,
+              inline: true,
+              include_sources: true
+          },
+          load_paths: ['styles', 'controls'],
+          output_style: 'expanded',
+          quiet_dependencies: true,
+          compile_css_with_sass: true
+      }
+  });
+  ```
+
+**Style options:**
+- `sourcemaps.enabled` (`boolean`): Enable CSS sourcemaps. Defaults to `true` when `debug` is enabled.
+- `sourcemaps.inline` (`boolean`): Inline sourcemaps into compiled CSS (default `true`).
+- `sourcemaps.include_sources` (`boolean`): Embed sources content in the sourcemap (default `true`).
+- `load_paths` (`string[]`): Sass load paths for `@use`/`@import`.
+- `output_style` (`string`): Sass output style (e.g., `expanded`, `compressed`).
+- `quiet_dependencies` (`boolean`): Suppress dependency warnings during Sass compilation.
+- `compile_css_with_sass` (`boolean`): Compile `.css` blocks through Sass when mixing with SCSS (default `true`).
+- `scss_sources` / `sass_sources` (`string[]`): Extra Sass/SCSS sources appended during compilation.
+
+Inline CSS sourcemaps are emitted only when a single compilation pass is possible. Mixed `.sass` plus `.scss`/`.css` inputs skip inline maps to avoid inaccurate mappings.
 
 ## Environment Variables
 
@@ -805,4 +840,4 @@ Solution: port: 3000 instead of port: "3000"
 
 ---
 
-This configuration reference provides comprehensive coverage of all JSGUI3 Server configuration options. Remember that most options have sensible defaults, so you only need to specify what differs from the defaults for your use case.
+This configuration reference provides comprehensive coverage of all JSGUI3 Server configuration options. Remember that most options have sensible defaults, so you only need to specify what differs from the defaults for your use case.

package/docs/controls-development.md

@@ -74,23 +74,44 @@ class My_Custom_Control extends Active_HTML_Document {
 }
 
 // Static CSS definition
-My_Custom_Control.css = `
-* { margin: 0; padding: 0; }
-body {
-    overflow-x: hidden;
+My_Custom_Control.css = `
+* { margin: 0; padding: 0; }
+body {
+    overflow-x: hidden;
     overflow-y: hidden;
     background-color: #E0E0E0;
 }
 .my-custom-control {
     padding: 20px;
     background: #f0f0f0;
-}
-`;
-
-// Register control globally
-controls.My_Custom_Control = My_Custom_Control;
-module.exports = jsgui;
-```
+}
+`;
+
+// Register control globally
+controls.My_Custom_Control = My_Custom_Control;
+module.exports = jsgui;
+```
+
+Note: You can also define `My_Custom_Control.scss` or `My_Custom_Control.sass` using template literals. These are compiled to CSS during bundling and removed from the JS output, just like `.css`. CSS and SCSS blocks can be mixed in a control; the bundler preserves their order during compilation. If you mix indented `.sass` with `.scss`/`.css`, each block is compiled independently to preserve order. Inline CSS sourcemaps are emitted only when a single compilation pass is used; mixed syntax skips inline maps to keep them accurate.
+
+To enable inline CSS sourcemaps for Sass/SCSS outputs, pass a `style` configuration when serving:
+
+```javascript
+Server.serve({
+    ctrl: My_Custom_Control,
+    src_path_client_js: require.resolve('./client.js'),
+    debug: true,
+    style: {
+        sourcemaps: {
+            enabled: true,
+            inline: true,
+            include_sources: true
+        }
+    }
+});
+```
+
+E2E coverage for Sass/CSS controls (including sourcemaps) lives in `tests/sass-controls.e2e.test.js`.
 
 #### Control (Base)
 
@@ -114,20 +135,27 @@ module.exports = jsgui;
 - Child control containment
 - Positioning and sizing
 
-```javascript
-const window = new controls.Window({
-    context,
-    title: 'My Window',
-    pos: [100, 100],  // [x, y] position
-    size: [400, 300]  // [width, height]
-});
-
-// Add content to window
-window.inner.add(childControl);
-this.body.add(window);
-```
-
-#### Panel
+```javascript
+const window = new controls.Window({
+    context,
+    title: 'My Window',
+    pos: [100, 100],  // [x, y] position
+    size: [400, 300]  // [width, height]
+});
+
+// Add content to window
+window.inner.add(childControl);
+this.body.add(window);
+```
+
+Lab results (from `lab/results/window_examples_dom_audit.md`, generated 2025-12-19):
+
+- Window example renders one window, a title bar, and three control buttons.
+- Tabbed panel example renders two tabs with a default checked input.
+- Checkbox example renders one checkbox input with the expected label.
+- Date picker example renders a native date input on the server.
+
+#### Panel
 
 **Purpose:** Basic container for grouping controls.
 
@@ -983,4 +1011,4 @@ Use browser developer tools to:
 
 ---
 
-This guide provides the foundation for developing controls in JSGUI3. For specific control implementations, refer to the examples in the `examples/` directory and the base classes in `controls/`.
+This guide provides the foundation for developing controls in JSGUI3. For specific control implementations, refer to the examples in the `examples/` directory and the base classes in `controls/`.

package/docs/publishers-guide.md

@@ -104,16 +104,18 @@ const publisher = new HTTP_Function_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');
+**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
+- Connection cleanup on client disconnect
+- Optional `pause()`, `resume()`, `stop()` controls
+
+**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;
@@ -136,13 +138,28 @@ 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
+// Register with server router
+server.server_router.set_route('/api/stream', publisher, publisher.handle_http);
+
+// Optional: control the stream from server-side code
+publisher.pause();
+publisher.resume();
+publisher.stop();
+```
+
+**Optional Control (HTTP):**
+```javascript
+// From browser or any HTTP client:
+await fetch('/api/stream', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'pause' })   // 'resume' | 'stop' | 'status'
+});
+```
+
+**Client-Side Consumption:**
+```javascript
+// In browser, use EventSource API
 const eventSource = new EventSource('/api/stream');
 
 eventSource.onmessage = (event) => {
@@ -159,20 +176,19 @@ eventSource.onerror = () => {
 };
 ```
 
-**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"}
-```
+**SSE Protocol:**
+The publisher sends events in SSE format:
+```
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+Transfer-Encoding: chunked
+
+data: OK
+
+data: {"tick":1,"timestamp":1234567890,"message":"Server tick #1"}
+
+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.
 
@@ -386,4 +402,4 @@ Publishers provide comprehensive logging:
 
 ---
 
-This guide provides the foundation for understanding and extending the publisher system. For specific publisher implementations, refer to their individual source files in the `publishers/` directory.
+This guide provides the foundation for understanding and extending the publisher system. For specific publisher implementations, refer to their individual source files in the `publishers/` directory.

package/docs/troubleshooting.md

@@ -197,13 +197,14 @@ input.js:1:0: ERROR: Expected identifier but found "}"
 
 2. **Verify CSS definition:**
    ```javascript
-   MyControl.css = `
-   .my-control {
-       padding: 20px;
-       background: #f0f0f0;
-   }
-   `;
-   ```
+   MyControl.css = `
+   .my-control {
+       padding: 20px;
+       background: #f0f0f0;
+   }
+   `;
+   ```
+   You can also use `MyControl.scss` or `MyControl.sass` with template literals; these compile to CSS during bundling (ensure the `sass` dependency is installed). To see inline CSS sourcemaps in devtools, enable `style.sourcemaps` (or run with `debug: true`).
 
 3. **Check activation:**
    ```javascript
@@ -746,4 +747,4 @@ This minimal setup helps isolate whether the issue is with your specific code or
 
 ---
 
-Remember: Most issues can be resolved by carefully checking the console output, verifying file paths, and ensuring proper control lifecycle management. Start with the basics and work systematically through the possible causes.
+Remember: Most issues can be resolved by carefully checking the console output, verifying file paths, and ensuring proper control lifecycle management. Start with the basics and work systematically through the possible causes.

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

@@ -52,23 +52,35 @@ node server.js
 
 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..."}
-
-...
-```
+## The SSE Protocol
+
+Server-Sent Events use HTTP chunked transfer encoding:
+
+```
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+Transfer-Encoding: chunked
+
+data: OK
+
+data: {"progress": 10, "stage": "Loading..."}
+
+data: {"progress": 20, "stage": "Processing..."}
+
+...
+```
+
+## Optional Pause/Resume/Stop Control
+
+`HTTP_Observable_Publisher` also supports controlling the published observable:
+
+```javascript
+await fetch('/api/tick-stream', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ action: 'pause' })   // 'resume' | 'stop' | 'status'
+});
+```
 
 ## Observable Pattern Benefits
 

package/lab/README.md

@@ -0,0 +1,19 @@
+# Lab Experiments
+
+This directory collects small, targeted experiments that validate specific UI behaviors or markup assumptions.
+
+## Experiments
+
+- `lab/experiments/window_examples_dom_audit.js`
+  - Server-rendered DOM checks for selected window examples.
+  - Writes results to `lab/results/window_examples_dom_audit.json` and `.md`.
+
+## Running
+
+```bash
+node lab/experiments/window_examples_dom_audit.js
+```
+
+## Results
+
+Experiment outputs are stored under `lab/results/` for traceability and documentation updates.

package/lab/experiments/window_examples_dom_audit.js

@@ -0,0 +1,241 @@
+const fs = require('fs');
+const path = require('path');
+
+const Server_Page_Context = require('../../page-context');
+
+const repo_root_path = path.join(__dirname, '..', '..');
+const examples_controls_root_path = path.join(repo_root_path, 'examples', 'controls');
+const results_dir_path = path.join(repo_root_path, 'lab', 'results');
+
+const count_occurrences = (haystack, needle) => {
+    let idx = 0;
+    let count = 0;
+    while (true) {
+        idx = haystack.indexOf(needle, idx);
+        if (idx === -1) return count;
+        count++;
+        idx += needle.length;
+    }
+};
+
+const count_class_occurrences = (html, class_name) => {
+    const class_regex = new RegExp(`class="[^"]*\\b${class_name}\\b`, 'g');
+    const matches = html.match(class_regex);
+    return matches ? matches.length : 0;
+};
+
+const count_regex_occurrences = (html, regex) => {
+    const matches = html.match(regex);
+    return matches ? matches.length : 0;
+};
+
+const render_example_html = ({ dir_name, ctrl_name }) => {
+    const example_dir_path = path.join(examples_controls_root_path, dir_name);
+    const example_client_path = path.join(example_dir_path, 'client.js');
+
+    const jsgui = require(example_client_path);
+    const ctrl = jsgui.controls && jsgui.controls[ctrl_name];
+    if (!ctrl) {
+        throw new Error(`Missing exported control jsgui.controls.${ctrl_name} in ${example_client_path}`);
+    }
+
+    const context = new Server_Page_Context();
+    const ctrl_instance = new ctrl({ context });
+    if (typeof ctrl_instance.all_html_render === 'function') {
+        return ctrl_instance.all_html_render();
+    }
+
+    if (typeof ctrl_instance.render === 'function') {
+        return ctrl_instance.render();
+    }
+
+    throw new Error(`Control ${ctrl_name} does not expose render methods`);
+};
+
+const make_count_check = (html, id, description, needle, expected) => {
+    const actual = count_occurrences(html, needle);
+    return {
+        id,
+        description,
+        expected,
+        actual,
+        pass: actual === expected
+    };
+};
+
+const make_class_count_check = (html, id, description, class_name, expected) => {
+    const actual = count_class_occurrences(html, class_name);
+    return {
+        id,
+        description,
+        expected,
+        actual,
+        pass: actual === expected
+    };
+};
+
+const make_contains_check = (html, id, description, needle) => {
+    const actual = html.includes(needle);
+    return {
+        id,
+        description,
+        expected: true,
+        actual,
+        pass: actual === true
+    };
+};
+
+const make_regex_count_check = (html, id, description, regex, expected) => {
+    const actual = count_regex_occurrences(html, regex);
+    return {
+        id,
+        description,
+        expected,
+        actual,
+        pass: actual === expected
+    };
+};
+
+const examples = [
+    {
+        dir_name: '1) window',
+        ctrl_name: 'Demo_UI',
+        checks: (html) => [
+            make_count_check(html, 'window_count', 'Window control count', 'data-jsgui-type="window"', 1),
+            make_contains_check(html, 'window_title_text', 'Window title text present', 'jsgui3-html Window Control'),
+            make_count_check(html, 'window_button_count', 'Window button count', 'data-jsgui-type="button"', 3)
+        ]
+    },
+    {
+        dir_name: '4) window, tabbed panel',
+        ctrl_name: 'Demo_UI',
+        checks: (html) => [
+            make_class_count_check(html, 'tab_label_count', 'Tab label count', 'tab-label', 2),
+            make_contains_check(html, 'tab_label_one', 'Tab 1 label text present', 'tab 1'),
+            make_contains_check(html, 'tab_label_two', 'Tab 2 label text present', 'tab 2'),
+            make_count_check(html, 'tab_input_checked', 'Default checked tab input count', 'checked="checked"', 1)
+        ]
+    },
+    {
+        dir_name: '8) window, checkbox/a)',
+        ctrl_name: 'Demo_UI',
+        checks: (html) => [
+            make_regex_count_check(
+                html,
+                'checkbox_input_count',
+                'Checkbox input count',
+                /\stype="checkbox"/g,
+                1
+            ),
+            make_contains_check(html, 'checkbox_label_text', 'Checkbox label text present', 'A checkbox')
+        ]
+    },
+    {
+        dir_name: '9) window, date picker',
+        ctrl_name: 'Demo_UI',
+        checks: (html) => [
+            make_class_count_check(html, 'date_picker_present', 'Date picker container present', 'date-picker', 1),
+            make_regex_count_check(
+                html,
+                'date_input_count',
+                'Date input type count',
+                /\stype="date"/g,
+                1
+            )
+        ]
+    }
+];
+
+const build_results = () => {
+    const results = {
+        generated_at: new Date().toISOString(),
+        examples: []
+    };
+
+    for (const example of examples) {
+        const html = render_example_html(example);
+        const checks = example.checks(html);
+        const passed = checks.filter((check) => check.pass).length;
+        const failed = checks.length - passed;
+
+        results.examples.push({
+            dir_name: example.dir_name,
+            ctrl_name: example.ctrl_name,
+            checks,
+            summary: {
+                total: checks.length,
+                passed,
+                failed
+            }
+        });
+    }
+
+    results.summary = results.examples.reduce(
+        (acc, example) => {
+            acc.total += example.summary.total;
+            acc.passed += example.summary.passed;
+            acc.failed += example.summary.failed;
+            return acc;
+        },
+        { total: 0, passed: 0, failed: 0 }
+    );
+
+    return results;
+};
+
+const render_markdown = (results) => {
+    const lines = [];
+    lines.push('# Window Examples DOM Audit');
+    lines.push('');
+    lines.push(`Generated at: ${results.generated_at}`);
+    lines.push('');
+    lines.push(`Total checks: ${results.summary.total}`);
+    lines.push(`Passed: ${results.summary.passed}`);
+    lines.push(`Failed: ${results.summary.failed}`);
+    lines.push('');
+
+    for (const example of results.examples) {
+        lines.push(`## ${example.dir_name}`);
+        lines.push('');
+        lines.push(`Control: ${example.ctrl_name}`);
+        lines.push('');
+        lines.push('| Check | Expected | Actual | Pass |');
+        lines.push('| --- | --- | --- | --- |');
+        for (const check of example.checks) {
+            const expected = Array.isArray(check.expected) ? check.expected.join(', ') : String(check.expected);
+            const actual = Array.isArray(check.actual) ? check.actual.join(', ') : String(check.actual);
+            lines.push(`| ${check.description} | ${expected} | ${actual} | ${check.pass ? 'yes' : 'no'} |`);
+        }
+        lines.push('');
+    }
+
+    return lines.join('\n');
+};
+
+const write_results = (results) => {
+    fs.mkdirSync(results_dir_path, { recursive: true });
+    const json_path = path.join(results_dir_path, 'window_examples_dom_audit.json');
+    const md_path = path.join(results_dir_path, 'window_examples_dom_audit.md');
+
+    fs.writeFileSync(json_path, JSON.stringify(results, null, 2));
+    fs.writeFileSync(md_path, render_markdown(results));
+
+    return { json_path, md_path };
+};
+
+const main = () => {
+    const results = build_results();
+    const { json_path, md_path } = write_results(results);
+
+    console.log('Window examples DOM audit complete.');
+    console.log(`JSON: ${json_path}`);
+    console.log(`Markdown: ${md_path}`);
+
+    if (results.summary.failed > 0) {
+        process.exitCode = 1;
+    }
+};
+
+if (require.main === module) {
+    main();
+}