redweb 0.12.0 → 0.13.0

package/src/cli/run.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const path = require('path');
+const ProjectInitializer = require('./ProjectInitializer');
+const { ProjectDoctor } = require('./ProjectDoctor');
+const { ProjectAddition } = require('./ProjectAddition');
+const formatCommand = require('./formatCommand');
+const { parseArguments, USAGE } = require('./arguments');
+
+async function run(args, cwd, version) {
+    try {
+        const options = parseArguments(args);
+        if (options.command === '--version') return { exitCode: 0, stdout: `${version}\n`, stderr: '' };
+        if (options.command === '--help' || options.command === '-h') return { exitCode: 0, stdout: USAGE, stderr: '' };
+        const root = path.resolve(cwd, options.target);
+        if (options.command === 'doctor') {
+            const report = await new ProjectDoctor(version).inspect(root, options.port);
+            const output = options.json ? JSON.stringify(report) : [
+                `Redweb doctor: ${report.ok ? 'passed selected checks' : 'issues found'}`,
+                ...report.issues.map(value => `${value.severity} ${value.code}${value.file ? ` (${value.file}${value.line ? `:${value.line}:${value.column}` : ''})` : ''}: ${value.message}\n  ${value.suggestion}`),
+            ].join('\n');
+            return { exitCode: report.ok ? 0 : 1, stdout: `${output}\n`, stderr: '' };
+        }
+        if (options.command === 'add') {
+            const result = new ProjectAddition().add(root, options);
+            const report = { schemaVersion: 1, operation: 'add', dryRun: options.dryRun, ...result };
+            const output = options.json ? JSON.stringify(report) : [
+                `${options.dryRun ? 'Planned addition' : 'Files created'} in ${result.root}`,
+                `Files: ${result.planned.join(', ')}`,
+                `Registration pending: ${result.registration.instruction}`,
+                `Import (adjust relative path from your entry point): ${result.registration.importFromProjectRoot}`,
+                `Build: ${formatCommand(result.verification.build)}`,
+                `Test: ${formatCommand(result.verification.test)}`,
+                result.verification.note,
+            ].join('\n');
+            return { exitCode: 0, stdout: `${output}\n`, stderr: '' };
+        }
+        const result = new ProjectInitializer(version).initialize(root, options);
+        const report = { schemaVersion: 1, operation: 'init', dryRun: options.dryRun, ...result };
+        const output = options.json ? JSON.stringify(report) : [
+            `${options.dryRun ? 'Planned initialization' : 'Initialization complete'} in ${result.root}`,
+            `Created: ${result.created.join(', ')}`,
+            `Kept existing: ${result.skipped.join(', ')}`,
+            `Planned: ${result.planned.join(', ')}`,
+            'Existing files were not validated or changed. Run redweb doctor to check configuration.',
+            options.existing ? 'No application or package files were generated.' : 'Next (published releases): npm install && npm run dev. Unreleased builds: install the matching Redweb tarball first (see README.md), then npm run dev.',
+        ].join('\n');
+        return { exitCode: 0, stdout: `${output}\n`, stderr: '' };
+    } catch (error) {
+        const output = args.includes('--json')
+            ? JSON.stringify({ schemaVersion: 1, ok: false, error: { code: 'CLI_FAILED', message: error.message } })
+            : `${error.message}\nRun redweb --help for usage.`;
+        return { exitCode: 1, stdout: '', stderr: `${output}\n` };
+    }
+}
+
+module.exports = { run };

package/src/cli/templates.js

@@ -1,87 +1,86 @@
-'use strict';
-
-const TYPESCRIPT_CONFIG = `${JSON.stringify({
-    extends: 'redweb/tsconfig.json',
-    compilerOptions: { rootDir: 'src', outDir: 'dist' },
-    include: ['src/**/*.ts', 'src/**/*.tsx'],
-}, null, 2)}\n`;
-
-const APP_SOURCE = `import path from 'node:path';
-import { page, start } from 'redweb';
-
-@page('/', { css: 'app.css', live: false })
-class HomePage {
-  render() {
-    return (
-      <main class="home">
-        <span class="eyebrow">Redweb</span>
-        <h1>Your server-rendered app is ready.</h1>
-        <p>Edit <code>src/app.tsx</code>, then build again.</p>
-      </main>
-    );
-  }
-}
-
-start(HomePage, {
-  port: Number(process.env.PORT ?? 8181),
-  templateRoot: path.resolve('src'),
-});
-`;
-
-const APP_STYLES = `:root {
-  color-scheme: dark;
-  font-family: Inter, ui-sans-serif, system-ui, sans-serif;
-  background: #08090d;
-  color: #fff;
-}
-
-body { margin: 0; }
-
-.home {
-  width: min(42rem, calc(100% - 2rem));
-  margin: 18vh auto 0;
-}
-
-.eyebrow {
-  color: #ff5064;
-  font-size: 0.75rem;
-  font-weight: 800;
-  letter-spacing: 0.18em;
-  text-transform: uppercase;
-}
-
-h1 {
-  margin: 0.75rem 0;
-  font-size: clamp(2.5rem, 8vw, 5rem);
-  line-height: 0.98;
-}
-
-p { color: rgb(255 255 255 / 65%); }
-code { color: #ff8795; }
-`;
-
-function projectManifest(version) {
-    return `${JSON.stringify({
-        name: 'redweb-app',
-        private: true,
-        version: '0.0.0',
-        scripts: {
-            build: 'tsc',
-            start: 'node dist/app.js',
-            dev: 'npm run build && npm start',
-        },
-        dependencies: { redweb: `^${version}` },
-        devDependencies: { typescript: '^5.9.3' },
-    }, null, 2)}\n`;
-}
-
-function projectFiles(version) {
-    return Object.freeze([
-        Object.freeze({ path: 'package.json', content: projectManifest(version) }),
-        Object.freeze({ path: 'tsconfig.json', content: TYPESCRIPT_CONFIG }),
-        Object.freeze({ path: 'src/app.tsx', content: APP_SOURCE }),
-        Object.freeze({ path: 'src/app.css', content: APP_STYLES }),
-    ]);
-}
-
-module.exports = { projectFiles };
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const json = value => `${JSON.stringify(value, null, 2)}\n`;
+const TEMPLATES = Object.freeze(['realtime', 'chat', 'site', 'socket', 'dashboard', 'http-ws']);
+
+function projectFiles(version, template = 'realtime', root = path.resolve(__dirname, '../..')) {
+    if (!TEMPLATES.includes(template)) throw new Error('Unknown starter template.');
+    const { devDependencies, dependencies } = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    const read = relative => fs.readFileSync(path.join(root, 'recipes', relative), 'utf8');
+    const manifest = {
+        name: 'redweb-app', private: true, version: '0.0.0',
+        scripts: {
+            build: 'tsc && node scripts/copy-assets.cjs',
+            start: 'node dist/app.js',
+            dev: 'nodemon',
+            test: 'npm run build && node --test test/app.test.cjs test/run-app.test.cjs',
+            'test:coverage': 'npm run build && c8 --all --src=dist --include=dist/** --reporter=text --reporter=json node --test test/app.test.cjs test/run-app.test.cjs',
+        },
+        dependencies: {
+            redweb: `^${version}`,
+            ...(['chat', 'socket', 'dashboard'].includes(template) ? { zod: devDependencies.zod } : {}),
+            ...(template === 'dashboard' ? { express: dependencies.express } : {}),
+        },
+        devDependencies: {
+            typescript: devDependencies.typescript, nodemon: devDependencies.nodemon, ws: dependencies.ws, c8: devDependencies.c8,
+            ...(template === 'dashboard' ? {
+                '@types/node': devDependencies['redweb-dashboard-types'].replace('npm:@types/node@', ''),
+                '@types/express': dependencies['@types/express'],
+            } : {}),
+        },
+        nodemonConfig: {
+            env: { REDWEB_DEV_REFRESH: '1' },
+            watch: ['src', 'tsconfig.json'],
+            ext: 'ts,tsx,css,html,json',
+            exec: 'npm run build && npm start || exit 1',
+            delay: 200,
+        },
+    };
+    if (template === 'dashboard') {
+        manifest.engines = { node: '>=22.13.0' };
+        manifest.scripts['add-user'] = 'npm run build && node dist/admin.js';
+        manifest.scripts['test:coverage'] += ' test/rate-window.test.cjs';
+    }
+    const files = [
+        { path: 'package.json', content: json(manifest) },
+        { path: 'tsconfig.json', content: json({
+            extends: 'redweb/tsconfig.json',
+            compilerOptions: { rootDir: 'src', outDir: 'dist', sourceMap: true },
+            include: ['src/**/*.ts', 'src/**/*.tsx'],
+        }) },
+        { path: 'src/app.tsx', content: read(`${template}/app.tsx`) },
+        { path: 'src/run-app.ts', content: read('shared/run-app.ts') },
+        { path: 'src/app.css', content: read(`${template === 'dashboard' ? template : 'shared'}/app.css`) },
+        { path: 'scripts/copy-assets.cjs', content: read('shared/copy-assets.cjs') },
+        { path: 'test/network.cjs', content: read('shared/network.cjs') },
+        { path: 'test/app.test.cjs', content: read(`${template}/app.test.cjs`) },
+        { path: 'test/run-app.test.cjs', content: read('shared/run-app.test.cjs') },
+        { path: 'README.md', content: `${read('shared/README.md')}\n${read(`${template}/README.md`)}` },
+        { path: '.gitignore', content: 'node_modules/\ndist/\ncoverage/\n.env\ndata/\n*.sqlite\n*.sqlite-wal\n*.sqlite-shm\n' },
+    ];
+    if (template === 'chat') {
+        // The canonical component example is also the starter: one implementation to maintain.
+        const examples = path.join(root, 'examples/live-html');
+        for (const name of ['chatroom.tsx', 'chatroom.css']) {
+            files.push({ path: `src/${name}`, content: fs.readFileSync(path.join(examples, name), 'utf8') });
+        }
+    }
+    if (template === 'socket') {
+        for (const name of ['contract.ts', 'handlers.ts']) {
+            files.push({ path: `src/${name}`, content: read(`socket/${name}`) });
+        }
+    }
+    if (template === 'dashboard') {
+        files.push({ path: '.npmrc', content: 'engine-strict=true\n' });
+        files.push({ path: 'test/rate-window.test.cjs', content: read('dashboard/rate-window.test.cjs') });
+        for (const name of ['store.ts', 'auth.ts', 'cards.tsx', 'admin.ts']) {
+            files.push({ path: `src/${name}`, content: read(`dashboard/${name}`) });
+        }
+    }
+    return Object.freeze(files.map(Object.freeze));
+}
+
+module.exports = { projectFiles, TEMPLATES };

package/src/context/RequestSnapshot.js

@@ -0,0 +1,41 @@
+'use strict';
+
+/** Retain only portable request data, never an Express response/socket graph. */
+function requestSnapshot(request) {
+    let bytes = 0;
+    const copy = (value, depth = 0) => {
+        if (depth > 16) throw new TypeError('Page request data exceeds the nesting limit.');
+        bytes += 8;
+        if (bytes > 65536) throw new TypeError('Page request data exceeds 64 KiB.');
+        if (value === undefined || value === null || typeof value === 'boolean') return value;
+        if (typeof value === 'string') {
+            bytes += Buffer.byteLength(value);
+            if (bytes > 65536) throw new TypeError('Page request data exceeds 64 KiB.');
+            return value;
+        }
+        if (typeof value === 'number' && Number.isFinite(value)) return value;
+        if (typeof value !== 'object' || (!Array.isArray(value) && Object.getPrototypeOf(value) !== null && Object.getPrototypeOf(Object.getPrototypeOf(value)) !== null)) {
+            throw new TypeError('Page request data must contain only JSON-compatible values.');
+        }
+        if (Array.isArray(value)) {
+            if (value.length > 8192) throw new TypeError('Page request data exceeds 64 KiB.');
+            return Object.freeze(value.map(item => copy(item, depth + 1)));
+        }
+        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [copy(key, depth + 1), copy(item, depth + 1)])));
+    };
+    const url = new URL(request.url || '/', 'http://redweb.invalid');
+    const query = Object.create(null);
+    for (const [key, value] of url.searchParams) {
+        query[key] = Object.hasOwn(query, key) ? [].concat(query[key], value) : value;
+    }
+    const data = copy({
+        path: request.path || url.pathname, url: request.url || '/', method: request.method || 'GET',
+        headers: request.headers || {}, params: request.params || {}, query: request.query || query, body: request.body,
+    });
+    return Object.freeze({ ...data, get(name) {
+        const value = Object.hasOwn(data.headers, name.toLowerCase()) ? data.headers[name.toLowerCase()] : undefined;
+        return Array.isArray(value) ? value.join(', ') : value;
+    } });
+}
+
+module.exports = requestSnapshot;

package/src/dataProperty.js

@@ -0,0 +1,11 @@
+'use strict';
+
+/** Read a data descriptor, never an application accessor. Not a Proxy sandbox. */
+function dataProperty(object, name) {
+    for (let current = object; current && (typeof current === 'object' || typeof current === 'function'); current = Object.getPrototypeOf(current)) {
+        const descriptor = Object.getOwnPropertyDescriptor(current, name);
+        if (descriptor) return Object.prototype.hasOwnProperty.call(descriptor, 'value') ? descriptor.value : undefined;
+    }
+}
+
+module.exports = dataProperty;

package/src/development/DevelopmentPageManager.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const { randomUUID } = require('crypto');
+const { PageManager } = require('../htmx/PageManager');
+const TemplateRenderer = require('../htmx/TemplateRenderer');
+const loopbackRequest = require('./loopbackRequest');
+const refreshBrowser = require('./refreshBrowser');
+
+const PATHS = Object.freeze({ developmentRevision: '/__redweb/development', developmentRuntime: '/__redweb/development.js', developmentStyles: '/__redweb/development.css' });
+
+class DevelopmentPageManager extends PageManager {
+    constructor(options) {
+        super(options, PATHS);
+        this.revision = randomUUID();
+    }
+
+    mount(app) {
+        const serve = (type, content) => (request, response) => {
+            response.set('Cache-Control', 'private, no-store').set('X-Content-Type-Options', 'nosniff');
+            response.removeHeader('Access-Control-Allow-Origin');
+            if (!loopbackRequest(request)) { response.status(404).end(); return; }
+            response.type(type).end(content);
+        };
+        app.get(PATHS.developmentRevision, serve('application/json', JSON.stringify({ revision: this.revision })));
+        app.get(PATHS.developmentRuntime, serve('text/javascript', refreshBrowser()));
+        app.get(PATHS.developmentStyles, serve('text/css', require('./refreshStyles')));
+        super.mount(app);
+    }
+
+    createDocument(record, request) {
+        const document = super.createDocument(record, request);
+        if (!loopbackRequest(request)) return document;
+        // Capture only a declaration string, never the HTTP request or credentials.
+        const bootstrap = `<rw-dev-refresh id="__redweb_dev"></rw-dev-refresh><script type="module" src="${PATHS.developmentRuntime}?revision=${this.revision}"></script>`;
+        return (markup, config) => {
+            const html = document(markup, config);
+            const body = TemplateRenderer.closingTag(html, 'body');
+            return body < 0 ? html + bootstrap : html.slice(0, body) + bootstrap + html.slice(body);
+        };
+    }
+
+    respond(record, request, response, markup) {
+        if (!loopbackRequest(request)) return super.respond(record, request, response, markup);
+        response.set('Cache-Control', 'private, no-store').type('html').end(markup);
+    }
+}
+
+module.exports = DevelopmentPageManager;

package/src/development/Inspection.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const LivePage = require('../htmx/LivePage');
+const { list, text, members, freeze, mapSize } = require('./description');
+const dataProperty = require('../dataProperty');
+const { observedRenderer, rendererRoute } = require('./ObservedRenderer');
+const developmentSettings = require('./settings');
+const HISTORY_LIMIT = 256;
+
+function createInspection(options) {
+    return developmentSettings(options).inspect ? new Inspection() : null;
+}
+
+class Inspection {
+    constructor() {
+        this.events = [];
+        this.sequence = 0;
+        this.identifiers = new WeakMap();
+        this.nextIdentifier = 0;
+        this.Renderer = observedRenderer(this);
+    }
+
+    id(object) {
+        let identifier = this.identifiers.get(object);
+        if (!identifier) {
+            identifier = ++this.nextIdentifier;
+            this.identifiers.set(object, identifier);
+        }
+        return identifier;
+    }
+
+    record(renderer, kind, details) {
+        // Inspector failures must not change application behavior or disclose errors.
+        try {
+            const event = freeze({ sequence: ++this.sequence, render: this.id(renderer), route: rendererRoute(renderer), kind, ...details });
+            if (this.events.length === HISTORY_LIMIT) this.events.shift();
+            this.events.push(event);
+        } catch { /* Inspection is best effort, never an application error path. */ }
+    }
+
+    snapshot(server) {
+        const manager = server.manager;
+        const sockets = manager ? server.sockets : server;
+        const budget = { remaining: 1000 };
+        const limited = (values, describe) => list(values, describe, budget);
+        const describe = read => {
+            try { return { available: true, ...read() }; }
+            catch { return { available: false }; }
+        };
+        return freeze({
+            schemaVersion: 1,
+            mode: 'development',
+            pages: describe(() => manager ? this.pages(manager, limited) : { registrations: limited([]), sessions: limited([]) }),
+            sockets: describe(() => ({ routes: limited(sockets ? dataProperty(sockets, 'routes') : [], route => {
+                const rooms = dataProperty(route, 'rooms'), sessions = dataProperty(route, 'sessions');
+                return {
+                    path: text(dataProperty(route, 'path')), handlers: limited(dataProperty(route, 'handlers'), handler => text(dataProperty(handler, 'name'))),
+                    registeredConnections: mapSize(dataProperty(route, 'clients')), draining: dataProperty(route, 'draining') === true,
+                    rooms: rooms === null ? 0 : mapSize(dataProperty(rooms, 'rooms')),
+                    sessions: sessions === null ? 0 : mapSize(dataProperty(sessions, 'sessions')),
+                };
+            }), pendingUpgrades: sockets ? mapSize(dataProperty(sockets, 'pendingUpgrades')) : 0, draining: dataProperty(sockets, 'draining') === true })),
+            history: { items: [...this.events], total: this.sequence, truncated: this.sequence > this.events.length,
+                limit: HISTORY_LIMIT },
+        });
+    }
+
+    pages(manager, limited) {
+        const sessions = new Set([...manager.pending.values(), ...manager.active.values()]);
+        const connections = { connected: 0, detaching: 0, pending: 0, retained: 0 };
+        const instances = new Map();
+        const remember = (record, instance) => {
+            if (!instances.has(record)) instances.set(record, new Set());
+            instances.get(record).add(instance);
+        };
+        for (const session of sessions) {
+            remember(session.record, session.page);
+            connections[sessionStatus(manager, session)]++;
+        }
+        for (const record of manager.records.values()) if (record.shared) remember(record, record.shared);
+        return {
+            closing: manager.closing, rendering: manager.rendering, connections,
+            registrations: limited(manager.records.values(), record => ({
+                path: text(record.metadata.path), live: record.metadata.live !== false, shared: record.metadata.scope === 'shared',
+                ...members(dataProperty(record, 'PageClass'), limited),
+                instanceMetadata: instances.has(record) ? 'observed' : 'unobserved',
+                instances: limited(instances.get(record) || [], instance => ({ id: this.id(instance), ...LivePage.describe(instance, limited) })),
+            })),
+            sessions: limited(sessions, session => ({
+                render: this.id(session.renderLifetime), instance: this.id(session.page), route: text(session.record.metadata.path),
+                status: sessionStatus(manager, session),
+                reactive: Boolean(session.renderer),
+            })),
+        };
+    }
+}
+
+function sessionStatus(manager, session) {
+    if (session.detaching) return 'detaching';
+    if (session.socket) return session.socket.readyState === 1 ? 'connected' : 'detaching';
+    return manager.pending.has(session.id) ? 'pending' : 'retained';
+}
+
+module.exports = { Inspection, createInspection };

package/src/development/ObservedRenderer.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const { performance } = require('perf_hooks');
+const ReactiveRenderer = require('../htmx/ReactiveRenderer');
+const { getPageMetadata } = require('../htmx/metadata');
+const { list, text } = require('./description');
+const dataProperty = require('../dataProperty');
+
+// A separate implementation is selected once for inspected servers. No observer
+// checks, callbacks or extra data structures enter the ordinary update path.
+function observedRenderer(inspection) {
+    return class ObservedRenderer extends ReactiveRenderer {
+        invalidate(owner, name, payload) {
+            if (!this.disposed) inspection.record(this, 'state-invalidated', {
+                state: text(name), component: text(payload.component || 'root'),
+                affectedOwners: list([...this.nodes.values()].filter(node => node.dependencies.get(owner)?.has(name)), node => text(node.id)),
+            });
+            return super.invalidate(owner, name, payload);
+        }
+
+        async performFlush() {
+            const started = performance.now();
+            const generation = this.generation;
+            inspection.record(this, 'flush-started', { snapshot: this.snapshot === true, dirtyOwners: list(this.dirty) });
+            try {
+                await super.performFlush();
+                inspection.record(this, this.disposed || generation !== this.generation ? 'flush-superseded' : 'flush-completed', {
+                    durationMs: performance.now() - started,
+                });
+            } catch (error) {
+                inspection.record(this, 'flush-failed', { durationMs: performance.now() - started });
+                throw error;
+            }
+        }
+    };
+}
+
+function rendererRoute(renderer) {
+    return text(getPageMetadata(dataProperty(dataProperty(renderer, 'page'), 'constructor'))?.path);
+}
+
+module.exports = { observedRenderer, rendererRoute };

package/src/development/description.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const { getActionMetadata, getStateMetadata } = require('../htmx/metadata');
+const dataProperty = require('../dataProperty');
+const LIMIT = 100;
+const text = value => typeof value === 'string' ? value.slice(0, 128) : '[unavailable]';
+
+function list(values, describe = text, budget) {
+    const items = [];
+    let total = 0;
+    for (const value of values) {
+        if (total++ < LIMIT && (!budget || budget.remaining > 0)) {
+            if (budget) budget.remaining--;
+            items.push(describe(value));
+        }
+    }
+    return { items, total, truncated: total > items.length };
+}
+
+function members(Class, describeList = list) {
+    return { className: text(dataProperty(Class, 'name')), actions: describeList(typeof Class === 'function' ? getActionMetadata(Class) : []),
+        states: describeList(typeof Class === 'function' ? getStateMetadata(Class).keys() : []) };
+}
+
+const mapSize = map => Object.getOwnPropertyDescriptor(Map.prototype, 'size').get.call(map);
+
+function freeze(value) {
+    if (value && typeof value === 'object') {
+        Object.values(value).forEach(freeze);
+        Object.freeze(value);
+    }
+    return value;
+}
+
+module.exports = { list, text, members, freeze, mapSize };

package/src/development/loopbackRequest.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const { isIP } = require('net');
+
+function loopback(address) {
+    if (typeof address !== 'string') return false;
+    if (address === '::1') return true;
+    const ipv4 = address.startsWith('::ffff:') ? address.slice(7) : address;
+    return isIP(ipv4) === 4 && ipv4.startsWith('127.');
+}
+
+function loopbackRequest(request) {
+    if (!loopback(request.socket?.remoteAddress)) return false;
+    const host = request.headers?.host;
+    if (typeof host !== 'string') return false;
+    const match = /^(localhost|127\.\d+\.\d+\.\d+|\[::1\])(?::(\d+))?$/i.exec(host);
+    if (!match || (match[1].startsWith('127.') && !loopback(match[1]))) return false;
+    const secure = Boolean(request.socket.encrypted);
+    const defaultPort = secure ? 443 : 80;
+    const port = match[2] === undefined ? defaultPort : Number(match[2]);
+    if (port !== request.socket.localPort) return false;
+    const origin = `${secure ? 'https' : 'http'}://${match[1].toLowerCase()}${port === defaultPort ? '' : `:${port}`}`;
+    if (request.headers.origin !== undefined && request.headers.origin !== origin) return false;
+    return request.headers['sec-fetch-site'] === undefined || ['same-origin', 'none'].includes(request.headers['sec-fetch-site']);
+}
+
+module.exports = loopbackRequest;

package/src/development/refreshBrowser.js

@@ -0,0 +1,96 @@
+'use strict';
+
+function refreshBrowser() {
+    return `
+const source = new URL(import.meta.url);
+const initialRevision = source.searchParams.get('revision');
+const endpoint = new URL('./development', source);
+const host = document.getElementById('__redweb_dev');
+const validRevision = value => typeof value === 'string' && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(value);
+if (host && validRevision(initialRevision)) {
+    const editable = target => target instanceof Element && Boolean(target.closest('input:not([type="hidden"]), textarea, select, [contenteditable]:not([contenteditable="false"])'));
+    const selectionChanged = select => {
+        const form = document.createElement('form');
+        const baseline = select.cloneNode(true);
+        baseline.removeAttribute('form');
+        form.append(baseline);
+        HTMLFormElement.prototype.reset.call(form);
+        return [...select.options].some((option, index) => option.selected !== baseline.options[index].selected);
+    };
+    // A conservative guard, not an autosave or a precise unsaved-change detector.
+    let edited = editable(document.activeElement) || [...document.querySelectorAll('input, textarea, select, [contenteditable]')].some(node =>
+        node.isContentEditable || (node.localName === 'select' ? selectionChanged(node) :
+        node.type === 'file' ? node.files.length > 0 : node.type === 'checkbox' || node.type === 'radio' ? node.checked !== node.defaultChecked :
+        node.type !== 'hidden' && node.value !== node.defaultValue));
+    const markEdited = event => { if (event.composedPath().some(editable)) edited = true; };
+    document.addEventListener('input', markEdited, true);
+    document.addEventListener('change', markEdited, true);
+    const shadow = host.attachShadow({ mode: 'open' });
+    let stopped = false, restartDetected = false, lifetime = 0, timer, request;
+    const cleanup = () => {
+        stopped = true;
+        lifetime += 1;
+        clearTimeout(timer);
+        request?.abort();
+        request = null;
+        document.removeEventListener('input', markEdited, true);
+        document.removeEventListener('change', markEdited, true);
+    };
+    const confirmReload = () => {
+        const stylesheet = document.createElement('link');
+        stylesheet.rel = 'stylesheet';
+        stylesheet.href = new URL('./development.css', source).href;
+        const notice = document.createElement('aside');
+        notice.setAttribute('role', 'status');
+        notice.setAttribute('aria-label', 'Redweb development refresh');
+        const message = document.createElement('p');
+        message.textContent = 'Development server restarted. Your current document is kept because edits were detected. Reloading resets these drafts and server memory may have changed.';
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.textContent = 'Reload and discard drafts';
+        button.addEventListener('click', () => location.reload());
+        notice.append(message, button);
+        shadow.append(stylesheet, notice);
+    };
+    const poll = async () => {
+        if (stopped) return;
+        const generation = lifetime;
+        const controller = new AbortController();
+        request = controller;
+        const timeout = setTimeout(() => controller.abort(), 2000);
+        try {
+            const response = await fetch(endpoint, { cache: 'no-store', credentials: 'omit', redirect: 'error', signal: controller.signal });
+            if (response.ok && response.headers.get('content-type')?.startsWith('application/json')) {
+                const result = await response.json();
+                if (!stopped && generation === lifetime && validRevision(result.revision) && result.revision !== initialRevision) {
+                    restartDetected = true;
+                    cleanup();
+                    if (edited) confirmReload();
+                    else location.reload();
+                }
+            }
+        } catch { /* Outage, rebuild failure or malformed response is not a new revision. */ }
+        finally {
+            clearTimeout(timeout);
+            if (generation === lifetime) {
+                request = null;
+                // cleanup always advances lifetime before stopping this generation.
+                timer = setTimeout(poll, 1000);
+            }
+        }
+    };
+    window.addEventListener('pagehide', cleanup);
+    window.addEventListener('pageshow', event => {
+        if (event.persisted && !restartDetected) {
+            stopped = false;
+            document.addEventListener('input', markEdited, true);
+            document.addEventListener('change', markEdited, true);
+            poll();
+        }
+    });
+    poll();
+}
+`;
+}
+
+module.exports = refreshBrowser;