redweb 0.12.0 → 0.13.0

package/src/development/refreshStyles.js

@@ -0,0 +1,9 @@
+'use strict';
+
+module.exports = `
+:host { position: fixed; inset: auto 1rem 1rem auto; z-index: 2147483647; max-width: min(28rem, calc(100vw - 2rem)); font: 14px/1.5 system-ui, sans-serif; }
+aside { background: #17202b; color: #fff; border: 1px solid #718198; border-radius: 8px; padding: 16px; box-shadow: 0 4px 24px #0006; }
+p { margin: 0 0 12px; }
+button { background: #fff; color: #17202b; border: 2px solid #fff; border-radius: 4px; font: inherit; padding: 6px 12px; cursor: pointer; }
+button:focus-visible { outline: 3px solid #6edcff; outline-offset: 3px; }
+`;

package/src/development/settings.js

@@ -0,0 +1,17 @@
+'use strict';
+
+function developmentSettings(options, names = ['inspect'], defaults = {}) {
+    if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options) ||
+        Object.keys(options).some(key => !names.includes(key)) ||
+        Object.values(options).some(value => value !== undefined && typeof value !== 'boolean'))) {
+        throw new TypeError(`development must contain only optional boolean ${names.join('/')} options.`);
+    }
+    const settings = { ...defaults };
+    for (const [name, value] of Object.entries(options || {})) if (value !== undefined) settings[name] = value;
+    if (process.env.NODE_ENV === 'production' && Object.values(settings).some(Boolean)) {
+        throw new Error('Development features cannot be enabled in production.');
+    }
+    return settings;
+}
+
+module.exports = developmentSettings;

package/src/docs/Documentation.js

@@ -0,0 +1,182 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createHash } = require('crypto');
+const { projectFiles, TEMPLATES } = require('../cli/templates');
+
+const normalize = text => text.replace(/\r\n/g, '\n');
+const hash = text => createHash('sha256').update(text).digest('hex');
+const fence = (text, language) => {
+    const runs = text.match(/`+/g) || [];
+    const delimiter = '`'.repeat(Math.max(3, ...runs.map(run => run.length + 1)));
+    return `${delimiter}${language}\n${text.trimEnd()}\n${delimiter}`;
+};
+
+/** Build-time content only. Loading Redweb's runtime does not load documentation. */
+class Documentation {
+    constructor(root, channel = 'unreleased') {
+        this.root = root;
+        this.manifest = JSON.parse(this.read('package.json'));
+        if (!/^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/.test(this.manifest.version)) {
+            throw new Error('Documentation requires a valid package version.');
+        }
+        if (channel !== 'unreleased' && channel !== this.manifest.version) {
+            throw new Error('Documentation channel must be unreleased or the exact package version.');
+        }
+        if (channel !== 'unreleased' && /^## Unreleased\s*\n([\s\S]*?)(?=^## |$(?![\s\S]))/m.exec(this.read('CHANGELOG.md'))?.[1].trim()) {
+            throw new Error('Move unreleased changes into the versioned changelog before building release documentation.');
+        }
+        if (channel !== 'unreleased' && !this.read('CHANGELOG.md').split('\n').includes(`## ${channel}`)) {
+            throw new Error('Release documentation requires its versioned changelog section.');
+        }
+        this.channel = channel;
+        this.basePath = `/docs/reference/${channel}`;
+        this.topics = JSON.parse(this.read('docs/topics.json'));
+        this.reference = JSON.parse(this.read('docs/reference.json'));
+        this.sourceLinks = new Map(this.topics.map(topic => [topic.source, `${this.basePath}/${topic.id}.md`]));
+        for (const example of this.reference.examples) {
+            if (example.codeSource) this.sourceLinks.set(example.codeSource, `${this.basePath}/examples/${example.id}.md`);
+        }
+        for (const template of TEMPLATES) {
+            for (const file of projectFiles(this.manifest.version, template, this.root)) {
+                const source = file.path === 'test/app.test.cjs' ? 'app.test.cjs' : file.path.replace(/^src\//, '');
+                this.sourceLinks.set(`recipes/${template}/${source}`, `${this.basePath}/recipes/${template}/files/${file.path}`);
+            }
+            this.sourceLinks.set(`recipes/${template}/README.md`, `${this.basePath}/recipes/${template}.md`);
+        }
+    }
+
+    read(file) { return normalize(fs.readFileSync(path.join(this.root, file), 'utf8')); }
+
+    links(markdown, source) {
+        // Canonical Markdown links are rewritten outside code fences only.
+        let delimiter = '';
+        return markdown.split('\n').map(line => {
+            const marker = /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
+            if (marker) {
+                if (!delimiter) delimiter = marker;
+                else if (marker[0] === delimiter[0] && marker.length >= delimiter.length) delimiter = '';
+                return line;
+            }
+            if (delimiter) return line;
+            return line.replace(/\]\(([^\s)]+)\)/g, (match, target) => {
+                if (/^(?:[a-z]+:|\/|#)/i.test(target)) return match;
+                const [file, anchor = ''] = target.split('#');
+                const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(source), file));
+                const destination = this.sourceLinks.get(resolved);
+                if (!destination) throw new Error(`Undocumented link target: ${source} -> ${target}`);
+                return `](${destination}${anchor ? `#${anchor}` : ''})`;
+            });
+        }).join('\n');
+    }
+
+    notice() {
+        return this.channel === 'unreleased'
+            ? `> Unreleased development documentation. Package metadata is ${this.manifest.version}, but these features are not claimed to be published in that npm version. Use the matching Redweb tarball described in the recipe setup; its published client dependency installs automatically. Do not install latest and assume compatibility.`
+            : `> Documentation for Redweb ${this.channel}. Install that exact version when following these examples.`;
+    }
+
+    setup(template) {
+        if (!TEMPLATES.includes(template)) throw new Error('Unknown starter template.');
+        const acceptance = `${template === 'dashboard' ? 'npm run add-user -- alice\n' : ''}npm test\nnpm run dev`;
+        return this.channel === 'unreleased'
+            ? [
+                'Replace `TARBALL` with the absolute path to the matching Redweb tarball produced by `npm pack` (quoted if it contains spaces). This is an explicit prerequisite, not an npm package name. Both commands must use the same tarball. The published redweb-client dependency installs automatically; no separate client checkout or linking is required:',
+                fence(`npx --yes --package TARBALL redweb init my-${template} --template ${template}\ncd my-${template}\nnpm install --save-exact TARBALL\n${acceptance}`, 'sh'),
+                'This prerelease Redweb artifact is development-only until its release checks finish. For released applications, use an available versioned release guide.',
+            ].join('\n\n')
+            : fence(`npx --yes redweb@${this.channel} init my-${template} --template ${template}\ncd my-${template}\nnpm install --save-exact redweb@${this.channel}\n${acceptance}`, 'sh');
+    }
+
+    recipe(template) {
+        const files = projectFiles(this.manifest.version, template, this.root).map(file => ({ ...file, content: normalize(file.content) }));
+        const source = `recipes/${template}/README.md`;
+        const explanation = this.links(this.read(source), source);
+        const markdown = [
+            `# ${template[0].toUpperCase()}${template.slice(1)}: complete application`, this.notice(),
+            explanation, '## Setup and acceptance', this.setup(template),
+            this.read('recipes/shared/README.md').replace(/^# Your Redweb application\n/, ''),
+            '## Exact generated files',
+            'These files come from the initializer itself. The tests below run real listeners; they are not illustrative pseudocode. The generated manifest uses the package metadata version; the installation step above pins the matching artifact or release.',
+            ...files.map(file => `### ${file.path}\n\n${fence(file.content, language(file.path))}`),
+        ].join('\n\n') + '\n';
+        return { id: `recipes/${template}`, title: `${template[0].toUpperCase()}${template.slice(1)} starter`, summary: explanation.split('\n').find(line => line && !line.startsWith('#')), source, markdown, files };
+    }
+
+    recipeCode(entry) {
+        const files = projectFiles(this.manifest.version, entry.template, this.root);
+        const file = files.find(file => file.path === entry.file);
+        if (!file) throw new Error(`Unknown documentation recipe file: ${entry.template}/${entry.file}`);
+        return normalize(file.content);
+    }
+
+    topic(topic) {
+        let markdown = `${this.notice()}\n\n${this.links(this.read(topic.source), topic.source)}`;
+        if (topic.recipe) {
+            const { template, file } = topic.recipe;
+            markdown += [
+                '\n## Build and run the complete application', this.setup(template),
+                `The [complete ${template} recipe](${this.basePath}/recipes/${template}.md) contains every generated file, its real acceptance tests, and deployment instructions. The source below is one of those files, not a standalone program; initialize the whole project before modifying it.`,
+                `## Source walkthrough: ${file}`, fence(this.recipeCode(topic.recipe), language(file)),
+            ].join('\n\n') + '\n';
+        }
+        return { ...topic, markdown };
+    }
+
+    build() {
+        const pages = this.topics.map(topic => this.topic(topic));
+        pages.push(...TEMPLATES.map(template => this.recipe(template)));
+        const reference = this.reference;
+        const api = reference.api.map(section => ({ ...section, usage: section.recipe ? this.recipeCode(section.recipe) : section.usage }));
+        const examples = reference.examples.map(example => ({ ...example, code: example.recipe ? this.recipeCode(example.recipe) : example.codeSource ? this.read(example.codeSource) : example.code }));
+        for (const example of examples) {
+            pages.push({ id: `examples/${example.id}`, title: example.title, summary: example.summary, source: 'docs/reference.json', markdown: [
+                `# ${example.title}`, this.notice(), example.summary,
+                example.recipe ? `Use the [complete ${example.recipe.template} recipe](${this.basePath}/recipes/${example.recipe.template}.md) for setup, files, and tests.` : 'This pattern demonstrates one API area. Application-specific names, credentials, assets, and policies may need to be supplied. Complete starter recipes include all required application files.',
+                fence(example.code, example.language || 'js'),
+                '## Notes and boundaries', example.notes.map(note => `- ${note}`).join('\n'),
+            ].join('\n\n') + '\n' });
+        }
+        for (const section of api) {
+            const article = section.article;
+            pages.push({ id: `api/${section.id}`, title: section.name, summary: section.summary, source: 'docs/reference.json', markdown: [
+                `# ${section.name}`, this.notice(), section.summary,
+                '## Explain it like I\u2019m five', article.eli5,
+                '## When should I use it?', article.useWhen,
+                '## Follow the example',
+                section.recipe ? `This source is part of the [complete ${section.recipe.template} recipe](${this.basePath}/recipes/${section.recipe.template}.md). Follow its setup and tests.` : 'This API pattern illustrates the named surface; it may require application-owned classes, credentials, or assets. Start from a complete recipe for a runnable application.',
+                fence(section.usage, section.language || (section.type === 'Live HTML' ? 'tsx' : 'js')),
+                article.walkthrough.map((step, index) => `${index + 1}. ${step}`).join('\n'),
+                ...(section.options ? ['## Options', section.options.map(option => `- ${option}`).join('\n')] : []),
+                '## Methods and members', section.methods.map(method => `### ${method.name}\n\n${method.detail}`).join('\n\n'),
+                '## What should I watch for?', article.watchFor,
+            ].join('\n\n') + '\n' });
+        }
+        const apiFiles = ['index.d.ts', 'client.d.ts', 'contract.d.ts', 'jsx-runtime.d.ts', 'jsx-dev-runtime.d.ts'];
+        pages.push({ id: 'api-types', title: 'Complete public TypeScript declarations', summary: 'Exact shipped signatures, options, and public types; not standalone application snippets.', source: 'index.d.ts', markdown: [
+            '# Public TypeScript API', this.notice(),
+            ...apiFiles.map(file => `## ${file}\n\n${fence(this.read(file), 'ts')}`),
+        ].join('\n\n') + '\n' });
+        for (const page of pages) {
+            page.url = `${this.basePath}/${page.id}.md`;
+            page.sha256 = hash(page.markdown);
+        }
+        const llms = [
+            '# Redweb',
+            '> Server-rendered TypeScript/TSX sites with server-owned state/actions and routed WebSockets on Node.js.',
+            this.notice(),
+            'TSX is not React. State is assignment-driven. Shared memory is not durable storage. Socket routes select services; message types select handlers. Applications own identity, authorization, persistence, and delivery reconciliation.',
+            '## Guides and complete recipes',
+            ...pages.map(page => `- [${page.title}](${page.url}): ${page.summary}`),
+        ].join('\n\n') + '\n';
+        return { schemaVersion: 1, packageVersion: this.manifest.version, channel: this.channel, basePath: this.basePath, llms, pages, api, examples };
+    }
+}
+
+function language(file) {
+    const extension = path.extname(file);
+    return ({ '.json': 'json', '.tsx': 'tsx', '.ts': 'ts', '.cjs': 'js', '.css': 'css', '.md': 'md' })[extension] || 'text';
+}
+
+module.exports = { Documentation, fence };

package/src/htmx/ActionDefinition.js

@@ -0,0 +1,44 @@
+const { SchemaValidator } = require('../validation/SchemaValidator');
+const { AccessPolicy } = require('../access/AccessPolicy');
+const ActionInputError = require('../validation/ActionInputError');
+
+class ActionDefinition {
+    constructor(options = {}) {
+        if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Action options must be an object.');
+        if (Object.keys(options).some(key => !['input', 'validationTimeoutMs', 'authorize', 'authorizationTimeoutMs'].includes(key))) throw new TypeError('Unknown action option.');
+        if (options.input === undefined && options.validationTimeoutMs !== undefined) throw new TypeError('Action validationTimeoutMs requires an input schema.');
+        this.validator = options.input === undefined ? null : new SchemaValidator(options.input, options.validationTimeoutMs);
+        this.authorization = new AccessPolicy(options.authorize, options.authorizationTimeoutMs);
+        Object.freeze(this);
+    }
+
+    async arguments(args, context) {
+        if (!this.validator && !this.authorization.authorize) return args;
+        if (this.validator ? args.length !== 1 : args.length > 1) throw new ActionInputError();
+        const controller = new AbortController();
+        const signal = context?.signal;
+        const socket = context?.socket;
+        const abort = () => controller.abort();
+        socket?.once('close', abort);
+        signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted || (socket && socket.readyState !== 1)) abort();
+        try {
+            let input = args[0];
+            if (this.validator) input = await this.validator.parse(input, controller.signal);
+            await this.authorization.check(Object.freeze({ ...context, signal: controller.signal }), input);
+            return [input];
+        } catch (error) {
+            if (error.reason === 'input') throw new ActionInputError();
+            if (error.reason === 'timeout') throw new ActionInputError('ACTION_VALIDATION_TIMEOUT');
+            if (error.reason === 'cancelled') throw new ActionInputError('ACTION_CANCELLED');
+            // ValidationFailure is already sanitized; policy failures preserve their own boundary.
+            if (error.reason === 'validator') throw new Error('Action input validator failed.');
+            throw error;
+        } finally {
+            socket?.off('close', abort);
+            signal?.removeEventListener('abort', abort);
+        }
+    }
+}
+
+module.exports = { ActionDefinition, ActionInputError };

package/src/htmx/Jsx.js

@@ -2,8 +2,10 @@
 
 const { isHtml, renderAttributeValue, renderValue, trustedHtml } = require('./Html');
 const synchronous = require('./synchronous');
+const ReactiveRenderer = require('./ReactiveRenderer');
 
 const Fragment = Symbol('redweb.Fragment');
+const KEYS = new WeakMap();
 const NAME = /^[A-Za-z][A-Za-z0-9:._-]*$/;
 const VOID_ELEMENTS = new Set([
     'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link',
@@ -14,10 +16,17 @@ const TERMINAL_ELEMENTS = new Set(['plaintext']);
 const BOOLEAN_VALUE_ATTRIBUTES = new Set(['contenteditable', 'draggable', 'spellcheck', 'writingsuggestions']);
 const ATTRIBUTE_ALIASES = Object.freeze({ className: 'class', htmlFor: 'for' });
 
-function renderChild(value) {
+function renderChild(value, keys = new Set()) {
     if (value === null || value === undefined || typeof value === 'boolean') return '';
-    if (Array.isArray(value)) return value.map(renderChild).join('');
-    if (isHtml(value)) return renderValue(value);
+    if (Array.isArray(value)) return value.map(child => renderChild(child, keys)).join('');
+    if (isHtml(value)) {
+        const key = KEYS.get(value);
+        if (key !== undefined) {
+            if (keys.has(key)) throw new Error('Duplicate JSX sibling key.');
+            keys.add(key);
+        }
+        return renderValue(value);
+    }
     if (['string', 'number', 'bigint'].includes(typeof value)) return renderValue(value);
     throw new TypeError('JSX children must be text, numbers, HtmlFragment values, or arrays of those values.');
 }
@@ -72,15 +81,22 @@ function renderComponent(Component, properties) {
     return Array.isArray(result) ? trustedHtml(renderValue(result)) : result;
 }
 
-function createElement(type, properties) {
+function createElement(type, properties, key) {
+    const reactive = ReactiveRenderer.jsx();
     const props = properties == null ? {} : properties;
     if (!props || typeof props !== 'object' || Array.isArray(props)) {
         throw new TypeError('JSX properties must be an object.');
     }
-    if (type === Fragment) return trustedHtml(renderChild(props.children));
-    if (typeof type === 'string') return renderIntrinsic(type, props);
-    if (typeof type === 'function') return renderComponent(type, props);
-    throw new TypeError('JSX element types must be intrinsic names or function components.');
+    let result;
+    if (type === Fragment) result = trustedHtml(renderChild(props.children));
+    else if (typeof type === 'string') result = renderIntrinsic(type, props);
+    else if (typeof type === 'function') result = renderComponent(type, props);
+    else throw new TypeError('JSX element types must be intrinsic names or function components.');
+    const elementKey = key ?? props.key;
+    if (!reactive || elementKey === undefined) return result;
+    const keyed = trustedHtml(ReactiveRenderer.key(renderValue(result), elementKey));
+    if (elementKey !== null) KEYS.set(keyed, String(elementKey));
+    return keyed;
 }
 
 module.exports = { Fragment, createElement, renderChild };

package/src/htmx/LiveHtmlServer.js

@@ -3,6 +3,10 @@ const HttpServer = require('../http/HttpServer');
 const HttpsServer = require('../http/HttpsServer');
 const SocketServer = require('../ws/SocketServer');
 const { PageManager } = require('./PageManager');
+const { createInspection } = require('../development/Inspection');
+const developmentSettings = require('../development/settings');
+const OwnedServerLifecycle = require('../OwnedServerLifecycle');
+const { listenServer, validateListenerOptions } = require('../serverLifecycle');
 
 class LiveHtmlServer {
     constructor(options = {}) {
@@ -19,15 +23,20 @@ class LiveHtmlServer {
             shutdownTimeoutMs = 1000,
             heartbeat,
             authenticate,
+            authenticationTimeoutMs,
             origins,
+            development,
             server: suppliedApp,
             ...httpOptions
         } = options;
+        const settings = developmentSettings(development, ['inspect', 'refresh'], { refresh: process.env.REDWEB_DEV_REFRESH === '1' });
+        this._inspection = createInspection({ inspect: settings.inspect });
         const app = suppliedApp === undefined ? express() : suppliedApp;
         if (!app || typeof app.get !== 'function' || typeof app.use !== 'function') {
             throw new TypeError('`server` must be an Express-compatible application.');
         }
-        this.manager = new PageManager({
+        const Manager = settings.refresh ? require('../development/DevelopmentPageManager') : PageManager;
+        this.manager = new Manager({
             pages,
             templateRoot,
             paths: livePaths,
@@ -37,33 +46,47 @@ class LiveHtmlServer {
             shutdownTimeoutMs,
             heartbeat,
             authenticate,
+            authenticationTimeoutMs,
             origins,
             logger: httpOptions.logger,
         });
+        if (this._inspection) this.manager.Renderer = this._inspection.Renderer;
         this.manager.mount(app);
         const listen = httpOptions.listen ?? true;
         const ServerClass = httpOptions.ssl ? HttpsServer : HttpServer;
-        this.http = new ServerClass({ ...httpOptions, server: app, listen: this.manager.hasLivePages ? false : listen });
-        if (this.manager.hasLivePages) {
-            const Route = this.manager.route();
-            this.sockets = new SocketServer({
-                server: this.http.server,
-                routes: [Route],
-                listen,
-                port: this.http.port,
-                bind: this.http.bind,
-                listenCallback: this.http.listenCallback,
-                logger: this.http.logger,
-                closeServerOnShutdown: false,
-            });
-        } else {
-            this.sockets = null;
-        }
+        this.http = new ServerClass({ ...httpOptions, server: app, listen: false });
+        validateListenerOptions({ ...this.http, listen });
+        this._ownedServer = new OwnedServerLifecycle(this.http.server);
+        try {
+            if (this.manager.hasLivePages) {
+                const Route = this.manager.route();
+                this.sockets = new SocketServer({
+                    server: this.http.server,
+                    routes: [Route],
+                    listen,
+                    port: this.http.port,
+                    bind: this.http.bind,
+                    listenCallback: this.http.listenCallback,
+                    logger: this.http.logger,
+                    closeServerOnShutdown: false,
+                });
+            } else {
+                this.sockets = null;
+                if (listen) listenServer(this.http.server, {
+                    port: this.http.port, bind: this.http.bind, callback: this.http.listenCallback,
+                    logger: this.http.logger, name: httpOptions.ssl ? 'HttpsServer' : 'HttpServer',
+                });
+            }
+        } catch (error) { this._ownedServer.dispose(); throw error; }
         this.app = this.http.app;
         this.server = this.http.server;
         this._shutdownPromise = null;
     }
 
+    revoke(principal) { return this.manager.revoke(principal); }
+
+    inspect() { return this._inspection ? this._inspection.snapshot(this) : null; }
+
     shutdown() {
         if (!this._shutdownPromise) {
             this._shutdownPromise = this.performShutdown();
@@ -80,9 +103,8 @@ class LiveHtmlServer {
         try { await this.manager.shutdown(); }
         catch (error) {
             errors.push(error);
-            if (error?.code === 'LIVE_HTML_SHUTDOWN_TIMEOUT') this.server.closeAllConnections?.();
         }
-        try { await this.http.shutdown(); }
+        try { await this._ownedServer.close(this.manager.shutdownTimeoutMs, () => this.http.shutdown()); }
         catch (error) { errors.push(error); }
         if (errors.length) throw new AggregateError(errors, 'Live HTML shutdown failed.');
     }

package/src/htmx/LivePage.js

@@ -1,8 +1,11 @@
 const { AsyncLocalStorage } = require('async_hooks');
 const HtmlRenderer = require('./HtmlRenderer');
 const TemplateRenderer = require('./TemplateRenderer');
+const ReactiveRenderer = require('./ReactiveRenderer');
+const dataProperty = require('../dataProperty');
+const { ActionInputError } = require('./ActionDefinition');
 const { isHtml, markHtml, renderValue } = require('./Html');
-const { forEachState, getActionImplementation, getStateConfig, isComponentClass } = require('./metadata');
+const { forEachState, getActionImplementation, getActionDefinition, getStateConfig, isComponentClass } = require('./metadata');
 
 const RUNTIME = new WeakMap();
 const COMPONENT_RENDER_CONTEXT = new AsyncLocalStorage();
@@ -67,12 +70,29 @@ class LivePage {
     static attach(page, socket, context) { return LivePage.prototype._attach.call(page, socket, context); }
     static detach(page, socket, context) { return LivePage.prototype._detach.call(page, socket, context); }
     static dispose(page) { return LivePage.prototype.dispose.call(page); }
-    static invoke(page, name, args, context) { return LivePage.prototype._invoke.call(page, name, args, context); }
+    static invoke(page, name, args, context, beforeInvoke) { return LivePage.prototype._invoke.call(page, name, args, context, beforeInvoke); }
     static loadComponents(page, context) { return LivePage.prototype._loadComponents.call(page, context); }
     static setFromClient(page, name, value) { return LivePage.prototype._setFromClient.call(page, name, value); }
 
-    static statePayload(page, name, value) {
+    // Read owned runtime structure only: no application fields or state values.
+    static describe(page, describeList) {
+        const { list, members } = require('../development/description');
+        const limited = describeList || list;
         const internal = runtime(page);
+        return { disposed: internal.disposed, components: limited(internal.components, ([id, component]) => ({ id, ...members(dataProperty(component, 'constructor'), limited) })) };
+    }
+
+    static statePayload(page, name, value, lazy = false) {
+        const internal = runtime(page);
+        if (lazy) {
+            let payload;
+            const materialize = () => payload ||= LivePage.statePayload(page, name, value);
+            return {
+                name, component: internal.componentId || undefined,
+                get value() { return materialize().value; },
+                get html() { return materialize().html; },
+            };
+        }
         const payload = HtmlRenderer.statePayload(name, value, page);
         if (!internal.componentId) return payload;
         payload.component = internal.componentId;
@@ -80,6 +100,13 @@ class LivePage {
         return payload;
     }
 
+    static snapshots(page, lazy = false) {
+        const values = [];
+        forEachState(page.constructor, (_options, name) => values.push(LivePage.statePayload(page, name, page[name], lazy)));
+        for (const child of runtime(page).children.values()) values.push(...LivePage.snapshots(child, lazy));
+        return values;
+    }
+
     static withRenderContext(context, render) {
         return COMPONENT_RENDER_CONTEXT.run(context, render);
     }
@@ -119,8 +146,12 @@ class LivePage {
             Object.defineProperty(this, name, {
                 configurable: true,
                 enumerable: true,
-                get: () => internal.stateValues.get(name),
+                get: () => {
+                    ReactiveRenderer.read(this, name);
+                    return internal.stateValues.get(name);
+                },
                 set: value => {
+                    ReactiveRenderer.assertWritable();
                     const previous = internal.stateValues.get(name);
                     internal.stateValues.set(name, value);
                     if (previous !== value) LivePage.prototype._stateChanged.call(this, name, value);
@@ -141,11 +172,13 @@ class LivePage {
     _renderComponent() {
         const internal = runtime(this);
         if (!internal.componentId) throw new Error('Components must be owned by a page field before rendering.');
-        const source = this.render?.(COMPONENT_RENDER_CONTEXT.getStore());
-        if (source && typeof source.then === 'function') throw new TypeError('Component render() must be synchronous.');
-        if (source === undefined) throw new Error(`${this.constructor.name || 'Component'} must provide render().`);
-        const markup = isHtml(source) ? renderValue(source) : HtmlRenderer.render(source.toString(), this);
-        return TemplateRenderer.component(markup, internal.componentId);
+        return ReactiveRenderer.component(this, internal.componentId, () => {
+            const source = this.render?.(COMPONENT_RENDER_CONTEXT.getStore());
+            if (source && typeof source.then === 'function') throw new TypeError('Component render() must be synchronous.');
+            if (source === undefined) throw new Error(`${this.constructor.name || 'Component'} must provide render().`);
+            const markup = isHtml(source) ? renderValue(source) : HtmlRenderer.render(source.toString(), this);
+            return TemplateRenderer.component(markup, internal.componentId);
+        });
     }
 
     _component(id) {
@@ -154,6 +187,7 @@ class LivePage {
 
     async _loadComponents(context) {
         for (const component of runtime(this).children.values()) {
+            if (runtime(this).disposed || context?.signal?.aborted) return;
             await component.loading?.(context);
             await LivePage.loadComponents(component, context);
         }
@@ -162,14 +196,17 @@ class LivePage {
     _attach(socket, context) {
         const internal = runtime(this);
         if (internal.disposed) throw new Error('Cannot connect a disposed page.');
+        if (context?.signal?.aborted) throw new ActionInputError('ACTION_CANCELLED');
         internal.connections.add(socket);
         forEachState(this.constructor, (_options, name) => {
+            if (socket.__redwebPageSession?.renderer) return;
             const payload = LivePage.statePayload(this, name, this[name]);
             socket.sendEvent?.('redweb:state', payload);
         });
         const connected = this.connected?.(context);
         return Promise.resolve(connected).then(async result => {
             for (const component of internal.children.values()) {
+                if (internal.disposed || context?.signal?.aborted || !internal.connections.has(socket)) return false;
                 await LivePage.attach(component, socket, context);
             }
             return result;
@@ -189,8 +226,14 @@ class LivePage {
 
     _stateChanged(name, value) {
         if (!getStateConfig(this.constructor, name)) return false;
-        const payload = LivePage.statePayload(this, name, value);
-        runtime(this).connections.forEach(socket => socket.sendEvent?.('redweb:state', payload));
+        const payload = LivePage.statePayload(this, name, value, true);
+        runtime(this).connections.forEach(socket => {
+            const session = socket.__redwebPageSession;
+            if (session?.lifetime?.revoked) return;
+            const renderer = session?.renderer;
+            if (renderer) renderer.invalidate(this, name, payload);
+            else socket.sendEvent?.('redweb:state', payload);
+        });
         return true;
     }
 
@@ -200,11 +243,18 @@ class LivePage {
         this[name] = value;
     }
 
-    async _invoke(name, args, context) {
+    async _invoke(name, args, context, beforeInvoke) {
         const implementation = getActionImplementation(this.constructor, name);
         if (!implementation || this[name] !== implementation) throw new Error(`Unknown page action "${name}".`);
         if (!Array.isArray(args)) throw new TypeError('Action arguments must be an array.');
-        return implementation.call(this, ...args, context);
+        const definition = getActionDefinition(this.constructor, name);
+        const validated = await definition.arguments(args, context);
+        if (beforeInvoke) await beforeInvoke();
+        if (runtime(this).disposed || context?.signal?.aborted || (context?.socket?.readyState !== undefined && context.socket.readyState !== 1)) {
+            throw new ActionInputError('ACTION_CANCELLED');
+        }
+        if (this[name] !== implementation) throw new Error(`Unknown page action "${name}".`);
+        return implementation.call(this, ...validated, context);
     }
 
     async dispose() {

package/src/htmx/PageIdentity.js

@@ -0,0 +1,32 @@
+'use strict';
+const { BoundedOperation, OperationInterrupted } = require('../async/BoundedOperation');
+const AuthenticationFailure = require('../access/AuthenticationFailure');
+
+function isPrincipal(value) {
+    return typeof value === 'string' || typeof value === 'bigint' || value === true || (typeof value === 'number' && Number.isFinite(value));
+}
+
+/** Bounded identity lookup; application code owns credential storage and revocation. */
+class PageIdentity {
+    constructor(authenticate, timeoutMs) {
+        if (authenticate !== undefined && typeof authenticate !== 'function') throw new TypeError('`authenticate` must be a function.');
+        if (authenticate === undefined && timeoutMs !== undefined) throw new TypeError('authenticationTimeoutMs requires authenticate.');
+        this.authenticate = authenticate;
+        this.boundary = new BoundedOperation(timeoutMs);
+    }
+
+    async resolve(request, signal) {
+        if (!this.authenticate) return undefined;
+        try {
+            const principal = await this.boundary.run(() => this.authenticate(request), signal);
+            if (!isPrincipal(principal)) throw new AuthenticationFailure();
+            return principal;
+        } catch (error) {
+            if (error instanceof AuthenticationFailure) throw new AuthenticationFailure(error.code);
+            if (error instanceof OperationInterrupted) throw new AuthenticationFailure(error.reason === 'timeout' ? 'AUTHENTICATION_TIMEOUT' : 'AUTHENTICATION_CANCELLED');
+            throw new AuthenticationFailure('AUTHENTICATION_FAILED');
+        }
+    }
+}
+
+module.exports = { PageIdentity, AuthenticationFailure, isPrincipal };

package/src/htmx/PageLifetime.js

@@ -0,0 +1,37 @@
+'use strict';
+const { AccessDenied } = require('../access/AccessPolicy');
+
+/** Cancellation shared by HTTP work, reconnectable sessions, and individual connections. */
+class PageLifetime {
+    constructor(parent) {
+        this.controller = new AbortController();
+        this.parent = parent;
+        this.abort = () => {
+            this.revoked = true;
+            this.controller.abort();
+            parent.removeEventListener('abort', this.abort);
+        };
+        parent.addEventListener('abort', this.abort, { once: true });
+        if (parent.aborted) this.abort();
+    }
+
+    get signal() { return this.controller.signal; }
+    check() { if (this.revoked) throw new AccessDenied('ACCESS_CANCELLED'); }
+
+    async wait(operation) {
+        this.check();
+        let abort;
+        try {
+            const cancelled = new Promise((_, reject) => {
+                abort = () => reject(new AccessDenied('ACCESS_CANCELLED'));
+                this.signal.addEventListener('abort', abort, { once: true });
+            });
+            const work = Promise.resolve().then(() => { this.check(); return operation(); });
+            const result = await Promise.race([work, cancelled]);
+            this.check();
+            return result;
+        } finally { this.signal.removeEventListener('abort', abort); }
+    }
+}
+
+module.exports = PageLifetime;