jsgui3-server 0.0.148 → 0.0.149

package/lab/screenshot-utils.js

@@ -0,0 +1,248 @@
+/**
+ * Screenshot Utilities for jsgui3-server
+ * 
+ * Reusable Puppeteer-based screenshot capture, extracted from
+ * tests/window-examples.puppeteer.test.js patterns.
+ * 
+ * Usage:
+ *   const { launch_browser, capture_page, close_browser } = require('./screenshot-utils');
+ *   await launch_browser();
+ *   const result = await capture_page('http://localhost:3600', {
+ *       output_path: './screenshots/full_page.png',
+ *       full_page: true
+ *   });
+ *   await close_browser();
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+let puppeteer;
+let browser;
+
+/**
+ * Launch a headless Puppeteer browser.
+ * @param {Object} [options]
+ * @param {boolean} [options.headless=true]
+ * @param {string} [options.executable_path] - Custom Chrome/Chromium path
+ * @returns {Promise<import('puppeteer').Browser>}
+ */
+const launch_browser = async (options = {}) => {
+    if (browser) return browser;
+
+    if (!puppeteer) {
+        puppeteer = require('puppeteer');
+    }
+
+    const launch_options = {
+        headless: options.headless !== false ? 'new' : false,
+        args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-gpu']
+    };
+
+    if (options.executable_path || process.env.PUPPETEER_EXECUTABLE_PATH) {
+        launch_options.executablePath = options.executable_path || process.env.PUPPETEER_EXECUTABLE_PATH;
+    }
+
+    browser = await puppeteer.launch(launch_options);
+    return browser;
+};
+
+/**
+ * Capture a screenshot of a URL.
+ * @param {string} url - URL to navigate to
+ * @param {Object} [options]
+ * @param {string} [options.output_path] - File path for the PNG
+ * @param {boolean} [options.full_page=true] - Capture full scrollable page
+ * @param {number} [options.width=1280] - Viewport width
+ * @param {number} [options.height=720] - Viewport height
+ * @param {number} [options.wait_ms=1000] - Wait time after load before capture
+ * @param {string} [options.wait_for_selector] - CSS selector to wait for
+ * @returns {Promise<{path: string, width: number, height: number, size_bytes: number}>}
+ */
+const capture_page = async (url, options = {}) => {
+    if (!browser) {
+        throw new Error('Browser not launched. Call launch_browser() first.');
+    }
+
+    const {
+        output_path,
+        full_page = true,
+        width = 1280,
+        height = 720,
+        wait_ms = 1000,
+        wait_for_selector
+    } = options;
+
+    const page = await browser.newPage();
+
+    try {
+        await page.setViewport({ width, height });
+        await page.goto(url, { waitUntil: 'networkidle0', timeout: 30000 });
+
+        if (wait_for_selector) {
+            await page.waitForSelector(wait_for_selector, { timeout: 10000 });
+        }
+
+        if (wait_ms > 0) {
+            await new Promise(r => setTimeout(r, wait_ms));
+        }
+
+        // Ensure output directory exists
+        if (output_path) {
+            fs.mkdirSync(path.dirname(output_path), { recursive: true });
+        }
+
+        const screenshot_path = output_path || path.join(process.cwd(), 'screenshot.png');
+        await page.screenshot({ path: screenshot_path, fullPage: full_page });
+
+        const stats = fs.statSync(screenshot_path);
+        const dimensions = await page.evaluate(() => ({
+            width: document.documentElement.scrollWidth,
+            height: document.documentElement.scrollHeight
+        }));
+
+        return {
+            path: screenshot_path,
+            width: dimensions.width,
+            height: dimensions.height,
+            size_bytes: stats.size
+        };
+    } finally {
+        await page.close();
+    }
+};
+
+/**
+ * Capture a screenshot of a specific element on a page.
+ * @param {string} url - URL to navigate to
+ * @param {string} selector - CSS selector for the element
+ * @param {Object} [options]
+ * @param {string} [options.output_path] - File path for the PNG
+ * @param {number} [options.width=1280] - Viewport width
+ * @param {number} [options.height=720] - Viewport height
+ * @param {number} [options.wait_ms=1000] - Wait time after load
+ * @returns {Promise<{path: string, width: number, height: number, size_bytes: number}>}
+ */
+const capture_element = async (url, selector, options = {}) => {
+    if (!browser) {
+        throw new Error('Browser not launched. Call launch_browser() first.');
+    }
+
+    const {
+        output_path,
+        width = 1280,
+        height = 720,
+        wait_ms = 1000
+    } = options;
+
+    const page = await browser.newPage();
+
+    try {
+        await page.setViewport({ width, height });
+        await page.goto(url, { waitUntil: 'networkidle0', timeout: 30000 });
+        await page.waitForSelector(selector, { timeout: 10000 });
+
+        if (wait_ms > 0) {
+            await new Promise(r => setTimeout(r, wait_ms));
+        }
+
+        if (output_path) {
+            fs.mkdirSync(path.dirname(output_path), { recursive: true });
+        }
+
+        const element = await page.$(selector);
+        if (!element) {
+            throw new Error(`Element not found: ${selector}`);
+        }
+
+        const screenshot_path = output_path || path.join(process.cwd(), 'element_screenshot.png');
+        await element.screenshot({ path: screenshot_path });
+
+        const stats = fs.statSync(screenshot_path);
+        const box = await element.boundingBox();
+
+        return {
+            path: screenshot_path,
+            width: Math.round(box.width),
+            height: Math.round(box.height),
+            size_bytes: stats.size
+        };
+    } finally {
+        await page.close();
+    }
+};
+
+/**
+ * Capture multiple screenshots from a single URL — full page + individual sections.
+ * @param {string} url - URL to screenshot
+ * @param {string} output_dir - Directory to save screenshots
+ * @param {Object} [options]
+ * @param {string[]} [options.section_selectors] - CSS selectors for individual section captures
+ * @param {string[]} [options.section_names] - Names for screenshot files (parallel to selectors)
+ * @param {number} [options.width=1280]
+ * @param {number} [options.height=720]
+ * @param {number} [options.wait_ms=1000]
+ * @returns {Promise<Array<{name: string, path: string, width: number, height: number, size_bytes: number}>>}
+ */
+const capture_url_screenshots = async (url, output_dir, options = {}) => {
+    const {
+        section_selectors = [],
+        section_names = [],
+        width = 1280,
+        height = 720,
+        wait_ms = 1000
+    } = options;
+
+    fs.mkdirSync(output_dir, { recursive: true });
+
+    const results = [];
+
+    // Full page capture
+    const full_result = await capture_page(url, {
+        output_path: path.join(output_dir, 'full_page.png'),
+        full_page: true,
+        width,
+        height,
+        wait_ms
+    });
+    results.push({ name: 'full_page', ...full_result });
+
+    // Section captures
+    for (let i = 0; i < section_selectors.length; i++) {
+        const selector = section_selectors[i];
+        const name = section_names[i] || `section_${i + 1}`;
+
+        try {
+            const section_result = await capture_element(url, selector, {
+                output_path: path.join(output_dir, `${name}.png`),
+                width,
+                height,
+                wait_ms: 500
+            });
+            results.push({ name, ...section_result });
+        } catch (err) {
+            console.warn(`  ⚠ Failed to capture "${name}" (${selector}): ${err.message}`);
+            results.push({ name, error: err.message });
+        }
+    }
+
+    return results;
+};
+
+/**
+ * Close the Puppeteer browser.
+ */
+const close_browser = async () => {
+    if (browser) {
+        await browser.close();
+        browser = null;
+    }
+};
+
+module.exports = {
+    launch_browser,
+    capture_page,
+    capture_element,
+    capture_url_screenshots,
+    close_browser
+};

package/module.js

@@ -16,10 +16,17 @@ jsgui.controls.Active_HTML_Document = require('./controls/Active_HTML_Document')
 
 //const Resource_Publisher = require('./publishing/http-resource-publisher');
 //jsgui.Resource_Publisher = Resource_Publisher;
-const Server = require('./server');
-jsgui.Server = Server;
-jsgui.serve = Server.serve;
-jsgui.fs2 = require('./fs2');
+const Server = require('./server');
+jsgui.Server = Server;
+jsgui.serve = Server.serve;
+jsgui.Process_Resource = Server.Process_Resource;
+jsgui.Remote_Process_Resource = Server.Remote_Process_Resource;
+jsgui.HTTP_SSE_Publisher = Server.HTTP_SSE_Publisher;
+if (jsgui.Resource) {
+    jsgui.Resource.Process = Server.Process_Resource;
+    jsgui.Resource.Remote_Process = Server.Remote_Process_Resource;
+}
+jsgui.fs2 = require('./fs2');
 
 // Port utilities for auto-port selection
 const port_utils = require('./port-utils');

package/package.json

@@ -43,7 +43,7 @@
     "type": "git",
     "url": "https://github.com/metabench/jsgui3-server.git"
   },
-  "version": "0.0.148",
+  "version": "0.0.149",
   "scripts": {
     "cli": "node cli.js",
     "serve": "node cli.js serve",
@@ -53,13 +53,23 @@
     "test:assigners": "node tests/test-runner.js --test=assigners.test.js",
     "test:publishers": "node tests/test-runner.js --test=publishers.test.js",
     "test:config": "node tests/test-runner.js --test=configuration-validation.test.js",
+    "test:admin-ui": "node tests/test-runner.js --test=admin-ui-render.test.js",
+    "test:serve": "node tests/test-runner.js --test=serve.test.js",
+    "test:serve:resources": "node tests/test-runner.js --test=serve-resources.test.js",
+    "test:resources:process": "node tests/test-runner.js --test=process-resource.test.js",
+    "test:resources:remote": "node tests/test-runner.js --test=remote-process-resource.test.js",
+    "test:resources:pool": "node tests/test-runner.js --test=server-resource-pool.test.js",
+    "test:sse": "node tests/test-runner.js --test=http-sse-publisher.test.js",
     "test:e2e": "node tests/test-runner.js --test=end-to-end.test.js",
     "test:content": "node tests/test-runner.js --test=content-analysis.test.js",
+    "test:bundler:cache": "node tests/test-runner.js --test=control-optimizer-cache-behavior.test.js",
     "test:performance": "node tests/test-runner.js --test=performance.test.js",
     "test:errors": "node tests/test-runner.js --test=error-handling.test.js",
     "test:examples:controls": "node tests/test-runner.js --test=examples-controls.e2e.test.js",
+    "test:puppeteer:bundling": "node tests/test-runner.js --test=bundling-default-control-elimination.puppeteer.test.js",
     "test:puppeteer:windows": "node tests/test-runner.js --test=window-examples.puppeteer.test.js",
+    "test:puppeteer:resources": "node tests/test-runner.js --test=window-resource-integration.puppeteer.test.js",
     "test:debug": "node tests/test-runner.js --debug",
     "test:verbose": "node tests/test-runner.js --verbose"
   }
-}
+}

package/publishers/Publishers.js

@@ -7,10 +7,11 @@ const Publishers = {
     'html': require('./http-html-publisher'),
     'jpeg': require('./http-jpeg-publisher'),
     'js': require('./http-js-publisher'),
-    'observable': require('./http-observable-publisher'),
-    'png': require('./http-png-publisher'),
+    'observable': require('./http-observable-publisher'),
+    'sse': require('./http-sse-publisher'),
+    'png': require('./http-png-publisher'),
     'resource': require('./http-resource-publisher'),
     'svg': require('./http-svg-publisher')
 }
 
-module.exports = Publishers;
+module.exports = Publishers;

package/publishers/helpers/assigners/static-compressed-response-buffers/Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner.js

@@ -65,11 +65,11 @@ class Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner
 
     async assign(arr_bundled_items) {
         // Get compression configuration with defaults
-        const enabled = this.compression_config.enabled !== false; // Default: true
-        const algorithms = this.compression_config.algorithms || ['gzip', 'br'];
-        const gzipLevel = this.compression_config.gzip?.level || 6;
-        const brotliQuality = this.compression_config.brotli?.quality || 6;
-        const threshold = this.compression_config.threshold || 1024;
+        const enabled = this.compression_config.enabled !== false; // Default: true
+        const algorithms = this.compression_config.algorithms || ['gzip', 'br'];
+        const gzipLevel = this.compression_config.gzip?.level ?? 6;
+        const brotliQuality = this.compression_config.brotli?.quality ?? 6;
+        const threshold = this.compression_config.threshold ?? 1024;
 
         if (!enabled) {
             console.log('Compression disabled, skipping compression assignment');

package/publishers/http-sse-publisher.js

@@ -0,0 +1,341 @@
+const HTTP_Publisher = require('./http-publisher');
+
+const default_keepalive_interval_ms = 15000;
+const default_event_history_size = 200;
+
+const to_data_string = (data_value) => {
+    if (data_value === undefined) {
+        return '';
+    }
+    if (typeof data_value === 'string') {
+        return data_value;
+    }
+    try {
+        return JSON.stringify(data_value);
+    } catch (error) {
+        return JSON.stringify({
+            error: 'non_serializable',
+            message: error instanceof Error ? error.message : String(error)
+        });
+    }
+};
+
+class HTTP_SSE_Publisher extends HTTP_Publisher {
+    constructor(spec = {}) {
+        super(spec);
+
+        this.name = spec.name || this.name || 'events';
+        this.keepalive_interval_ms = Number.isFinite(spec.keepaliveIntervalMs)
+            ? Number(spec.keepaliveIntervalMs)
+            : default_keepalive_interval_ms;
+        this.max_clients = Number.isFinite(spec.maxClients)
+            ? Number(spec.maxClients)
+            : Number.POSITIVE_INFINITY;
+        this.event_history_size = Number.isInteger(spec.eventHistorySize)
+            ? spec.eventHistorySize
+            : default_event_history_size;
+
+        this.clients = new Map();
+        this.event_history = [];
+        this.next_event_id = 0;
+
+        this._keepalive_timer = null;
+    }
+
+    get client_count() {
+        return this.clients.size;
+    }
+
+    _generate_client_id() {
+        return `sse_${Date.now()}_${Math.random().toString(16).slice(2, 10)}`;
+    }
+
+    _parse_connection_url(req) {
+        const host_header = req.headers.host || 'localhost';
+        return new URL(req.url || '/', `http://${host_header}`);
+    }
+
+    _extract_last_event_id(req, parsed_url) {
+        const query_value = parsed_url.searchParams.get('lastEventId')
+            || parsed_url.searchParams.get('last_event_id');
+        const header_value = req.headers['last-event-id'];
+        const raw_value = query_value || header_value;
+
+        if (raw_value === undefined || raw_value === null || raw_value === '') {
+            return null;
+        }
+
+        const parsed_value = Number.parseInt(String(raw_value), 10);
+        if (!Number.isFinite(parsed_value)) {
+            return null;
+        }
+        return parsed_value;
+    }
+
+    _ensure_keepalive_timer() {
+        if (this._keepalive_timer || !Number.isFinite(this.keepalive_interval_ms) || this.keepalive_interval_ms <= 0) {
+            return;
+        }
+
+        this._keepalive_timer = setInterval(() => {
+            this._broadcast_comment('keepalive');
+        }, this.keepalive_interval_ms);
+        this._keepalive_timer.unref?.();
+    }
+
+    _maybe_stop_keepalive_timer() {
+        if (this._keepalive_timer && this.clients.size === 0) {
+            clearInterval(this._keepalive_timer);
+            this._keepalive_timer = null;
+        }
+    }
+
+    _write_to_client(client_id, payload_text) {
+        const client_entry = this.clients.get(client_id);
+        if (!client_entry) {
+            return false;
+        }
+
+        const { res } = client_entry;
+        if (!res || res.destroyed || res.writableEnded) {
+            this._disconnect_client(client_id, 'write_failed');
+            return false;
+        }
+
+        try {
+            res.write(payload_text);
+            return true;
+        } catch {
+            this._disconnect_client(client_id, 'write_failed');
+            return false;
+        }
+    }
+
+    _format_event_payload(event_name, data_value, event_id) {
+        const payload_lines = [];
+        if (event_id !== undefined && event_id !== null) {
+            payload_lines.push(`id: ${event_id}`);
+        }
+
+        if (event_name) {
+            payload_lines.push(`event: ${event_name}`);
+        }
+
+        const data_text = to_data_string(data_value);
+        const data_lines = data_text.split(/\r?\n/);
+        if (data_lines.length === 0) {
+            payload_lines.push('data:');
+        } else {
+            for (const line of data_lines) {
+                payload_lines.push(`data: ${line}`);
+            }
+        }
+
+        payload_lines.push('');
+        payload_lines.push('');
+        return payload_lines.join('\n');
+    }
+
+    _record_event(event_record) {
+        this.event_history.push(event_record);
+        while (this.event_history.length > this.event_history_size) {
+            this.event_history.shift();
+        }
+    }
+
+    _broadcast_comment(comment_text) {
+        const payload = `:${comment_text}\n\n`;
+        const client_ids = Array.from(this.clients.keys());
+        for (const client_id of client_ids) {
+            this._write_to_client(client_id, payload);
+        }
+    }
+
+    _send_event_to_clients(client_ids, event_name, data_value) {
+        const event_id = ++this.next_event_id;
+        const payload_text = this._format_event_payload(event_name, data_value, event_id);
+
+        const delivered_client_ids = [];
+        for (const client_id of client_ids) {
+            const did_write = this._write_to_client(client_id, payload_text);
+            if (did_write) {
+                const client_entry = this.clients.get(client_id);
+                if (client_entry) {
+                    client_entry.last_event_id = event_id;
+                }
+                delivered_client_ids.push(client_id);
+            }
+        }
+
+        this._record_event({
+            id: event_id,
+            event: event_name,
+            data: data_value,
+            timestamp: Date.now()
+        });
+
+        return {
+            eventId: event_id,
+            deliveredClientIds: delivered_client_ids
+        };
+    }
+
+    _replay_events_since(client_id, last_event_id) {
+        if (last_event_id === null) {
+            return;
+        }
+
+        const replay_candidates = this.event_history.filter((entry) => entry.id > last_event_id);
+        for (const replay_event of replay_candidates) {
+            const payload_text = this._format_event_payload(replay_event.event, replay_event.data, replay_event.id);
+            const did_write = this._write_to_client(client_id, payload_text);
+            if (!did_write) {
+                break;
+            }
+        }
+    }
+
+    _disconnect_client(client_id, reason = 'disconnect') {
+        const client_entry = this.clients.get(client_id);
+        if (!client_entry) {
+            return;
+        }
+
+        this.clients.delete(client_id);
+        const { req, res } = client_entry;
+
+        if (req) {
+            req.removeAllListeners('close');
+        }
+
+        try {
+            if (res && !res.writableEnded) {
+                res.end();
+            }
+        } catch {
+            // Ignore disconnect write errors.
+        }
+
+        this.raise('client_disconnected', {
+            clientId: client_id,
+            reason,
+            timestamp: Date.now(),
+            connectedClients: this.client_count
+        });
+
+        this._maybe_stop_keepalive_timer();
+    }
+
+    handle_http(req, res) {
+        const request_method = String(req.method || 'GET').toUpperCase();
+        if (request_method !== 'GET') {
+            res.writeHead(405, {
+                'Content-Type': 'application/json'
+            });
+            res.end(JSON.stringify({
+                ok: false,
+                error: 'Method Not Allowed'
+            }));
+            return;
+        }
+
+        if (this.client_count >= this.max_clients) {
+            res.writeHead(503, {
+                'Content-Type': 'application/json'
+            });
+            res.end(JSON.stringify({
+                ok: false,
+                error: 'SSE client limit reached'
+            }));
+            return;
+        }
+
+        const parsed_url = this._parse_connection_url(req);
+        const requested_client_id = parsed_url.searchParams.get('clientId') || parsed_url.searchParams.get('client_id');
+        const client_id = requested_client_id || this._generate_client_id();
+        const last_event_id = this._extract_last_event_id(req, parsed_url);
+
+        if (this.clients.has(client_id)) {
+            this._disconnect_client(client_id, 'replaced');
+        }
+
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+            'Transfer-Encoding': 'chunked',
+            'X-Accel-Buffering': 'no'
+        });
+
+        res.write(`retry: 3000\n`);
+        res.write(':connected\n\n');
+
+        this.clients.set(client_id, {
+            client_id,
+            req,
+            res,
+            connected_at: Date.now(),
+            last_event_id
+        });
+
+        this._ensure_keepalive_timer();
+
+        this.raise('client_connected', {
+            clientId: client_id,
+            lastEventId: last_event_id,
+            timestamp: Date.now(),
+            connectedClients: this.client_count
+        });
+
+        this._replay_events_since(client_id, last_event_id);
+
+        const disconnect_handler = () => {
+            this._disconnect_client(client_id, 'closed');
+        };
+
+        req.on('close', disconnect_handler);
+        res.on('close', disconnect_handler);
+        res.on('finish', disconnect_handler);
+    }
+
+    broadcast(event_name, data_value) {
+        const target_client_ids = Array.from(this.clients.keys());
+        return this._send_event_to_clients(target_client_ids, event_name, data_value);
+    }
+
+    send(client_id, event_name, data_value) {
+        if (!this.clients.has(client_id)) {
+            return {
+                eventId: null,
+                deliveredClientIds: []
+            };
+        }
+
+        return this._send_event_to_clients([client_id], event_name, data_value);
+    }
+
+    stop(callback) {
+        const stop_promise = new Promise((resolve) => {
+            if (this._keepalive_timer) {
+                clearInterval(this._keepalive_timer);
+                this._keepalive_timer = null;
+            }
+
+            const connected_client_ids = Array.from(this.clients.keys());
+            for (const client_id of connected_client_ids) {
+                this._disconnect_client(client_id, 'stopped');
+            }
+
+            resolve(true);
+        });
+
+        if (typeof callback === 'function') {
+            stop_promise.then(() => callback(null, true), callback);
+            return;
+        }
+
+        return stop_promise;
+    }
+}
+
+module.exports = HTTP_SSE_Publisher;