redweb 0.16.2 → 0.16.4

package/recipes/shared/README.md

@@ -40,10 +40,10 @@ and application-specific rate limits. These starters are demonstrations, not a h
 Never commit secrets; `.env` is ignored but is not loaded automatically.
 
 `npx --no-install redweb doctor --json` reports configuration problems without changing your files.
-## Dependency security
-
-This starter includes an application-root npm override for Express 4's `qs`
-dependency, selecting patched `qs@6.16.0`. Keep the override when merging this
-starter into an existing application, refresh its lockfile and run `npm audit`.
-Overrides in Redweb's own package do not apply to installed consumers. Recheck
-upstream Express/body-parser releases before removing this temporary mitigation.
+## Dependency security
+
+This starter includes an application-root npm override for Express 4's `qs`
+dependency, selecting patched `qs@6.16.0`. Keep the override when merging this
+starter into an existing application, refresh its lockfile and run `npm audit`.
+Overrides in Redweb's own package do not apply to installed consumers. Recheck
+upstream Express/body-parser releases before removing this temporary mitigation.

package/src/Application.js

@@ -37,7 +37,7 @@ function bounded(operation, milliseconds, label, signal) {
 class Application {
     constructor(options = {}) {
         if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Application options must be an object.');
-        const { pages = [], sockets = [], services = [], port = 8181, bind = '0.0.0.0',
+        const { pages = [], sockets = [], services = [], providers = {}, port = 8181, bind = '0.0.0.0',
             startupTimeoutMs = 5000, shutdownTimeoutMs = 5000, signals = true, ...rest } = options;
         if ('static' in rest) throw new TypeError('Use exportStatic() for static output; defineApp() owns a live HTTP listener.');
         for (const name of ['listen', 'routes', 'socketRoutes', 'closeServerOnShutdown']) {
@@ -49,7 +49,7 @@ class Application {
         }
         if (typeof signals !== 'boolean') throw new TypeError('`signals` must be a boolean.');
         this.options = { ...rest, pages: classes(pages, 'pages'), sockets: classes(sockets, 'sockets'),
-            services: classes(services, 'services'), port, bind, startupTimeoutMs, shutdownTimeoutMs, signals };
+            services: classes(services, 'services'), providers, port, bind, startupTimeoutMs, shutdownTimeoutMs, signals };
         if (this.options.services.some(Type => Type === SocketService || Type.prototype instanceof SocketService)) {
             throw new TypeError('SocketService belongs to a socket route, not application services.');
         }
@@ -98,14 +98,14 @@ class Application {
     }
 
     async _start() {
-        const { pages, sockets, services, startupTimeoutMs, shutdownTimeoutMs, signals, httpServices = [], ...options } = this.options;
+        const { pages, sockets, services, providers, startupTimeoutMs, shutdownTimeoutMs, signals, httpServices = [], ...options } = this.options;
         if (signals) {
             process.on('SIGINT', this._onSignal);
             process.on('SIGTERM', this._onSignal);
         }
         const httpOptions = { ...options, services: httpServices, listen: false, shutdownTimeoutMs };
         if (pages.length) {
-            this._live = new LiveHtmlServer({ ...httpOptions, pages, socketRoutes: sockets });
+            this._live = new LiveHtmlServer({ ...httpOptions, pages, providers, socketRoutes: sockets });
             this.http = this._live.http;
             this.sockets = this._live.sockets;
             this._owner = this._live._ownedServer;

package/src/access/failure-codes.json

@@ -19,6 +19,10 @@
   "ACCESS_CAPACITY": { "status": 503, "message": "Authorization capacity reached. The operation was not run." },
   "PAGE_FAILED": { "status": 500, "message": "Page request failed." },
   "PAGE_CAPACITY": { "status": 503, "message": "Page session capacity reached." },
+  "UPLOAD_TOO_LARGE": { "status": 413, "message": "The uploaded file exceeds this action's size limit." },
+  "UPLOAD_TYPE_REJECTED": { "status": 415, "message": "This action does not accept that file type." },
+  "UPLOAD_TIMEOUT": { "status": 408, "message": "The uploaded file took too long to arrive." },
+  "UPLOAD_FAILED": { "status": 500, "message": "File upload failed." },
   "ACTION_INVALID_INPUT": { "status": 400, "message": "Action input is invalid. Check the form values and try again." },
   "ACTION_VALIDATION_TIMEOUT": { "status": 503, "message": "Action input validation timed out. The action was not run." },
   "ACTION_CANCELLED": { "status": 503, "message": "The connection closed before input validation completed. The action was not run." }

package/src/cli/ProjectInitializer.js

@@ -11,7 +11,7 @@ class ProjectInitializer {
 
     initialize(target, options = {}) {
         const root = path.resolve(target);
-        const templateFiles = projectFiles(this.version, options.template ?? null, undefined, options);
+        const templateFiles = projectFiles(this.version, options.template ?? null, undefined, options);
         const files = options.existing ? templateFiles.filter(file => file.path === 'tsconfig.json') : templateFiles;
         return new FilePlan(root, files).write({ dryRun: options.dryRun });
     }

package/src/cli/arguments.js

@@ -1,17 +1,17 @@
 'use strict';
 
-const { CAPABILITIES, TEMPLATES } = require('./templates');
+const { CAPABILITIES, TEMPLATES } = require('./templates');
 const { KINDS } = require('./ProjectAddition');
 
 const USAGE = [
-    `Usage: redweb init [directory] [--with ${CAPABILITIES.join(',')}] [--template ${TEMPLATES.join('|')}] [--bare] [--existing] [--dry-run] [--json]`,
+    `Usage: redweb init [directory] [--with ${CAPABILITIES.join(',')}] [--template ${TEMPLATES.join('|')}] [--bare] [--existing] [--dry-run] [--json]`,
     '       redweb doctor [directory] [--port number] [--json]',
     `       redweb add <${KINDS.join('|')}> <name> [directory] [--config file] [--source-dir dir] [--test-dir dir] [--dry-run] [--json]`,
     '       redweb --help | --version',
     '',
-    '--existing creates only a missing tsconfig.json; no starter or package changes.',
-    '--with adds neutral capability dependencies without generating example-domain code.',
-    '--bare omits generated tests; templates remain explicit examples.',
+    '--existing creates only a missing tsconfig.json; no starter or package changes.',
+    '--with adds neutral capability dependencies without generating example-domain code.',
+    '--bare omits generated tests; templates remain explicit examples.',
     '--dry-run reports planned files without writing anything.',
     'doctor inspects configuration without executing application code or repairing files.',
 ].join('\n') + '\n';
@@ -20,7 +20,7 @@ function parseArguments(args) {
     const [command = '--help', ...rest] = args;
     if (['--help', '-h', '--version'].includes(command) && !rest.length) return { command };
     if (!['init', 'doctor', 'add'].includes(command)) throw new Error('Unknown command. Run redweb --help.');
-    const result = { command, target: '.', existing: false, dryRun: false, json: false, port: null };
+    const result = { command, target: '.', existing: false, dryRun: false, json: false, port: null };
     if (command === 'add') {
         result.kind = rest.shift();
         result.name = rest.shift();
@@ -39,35 +39,35 @@ function parseArguments(args) {
         if (seen.has(value)) throw new Error(`Duplicate option: ${value}`);
         seen.add(value);
         if (value === '--json') result.json = true;
-        else if (value === '--existing' && command === 'init') result.existing = true;
-        else if (value === '--bare' && command === 'init') result.bare = true;
+        else if (value === '--existing' && command === 'init') result.existing = true;
+        else if (value === '--bare' && command === 'init') result.bare = true;
         else if (value === '--dry-run' && ['init', 'add'].includes(command)) result.dryRun = true;
         else if (command === 'add' && ['--config', '--source-dir', '--test-dir'].includes(value)) {
             const argument = rest[++i];
             if (!argument || argument.startsWith('-')) throw new Error(`${value} requires a path.`);
             result[{ '--config': 'configFile', '--source-dir': 'sourceDir', '--test-dir': 'testDir' }[value]] = argument;
         }
-        else if (value === '--template' && command === 'init') {
+        else if (value === '--template' && command === 'init') {
             const template = rest[++i];
             if (!TEMPLATES.includes(template)) throw new Error(`--template must be one of: ${TEMPLATES.join(', ')}.`);
-            result.template = template;
-        }
-        else if (value === '--with' && command === 'init') {
-            const raw = rest[++i];
-            if (!raw || raw.startsWith('-')) throw new Error('--with requires a comma-separated capability list.');
-            const capabilities = raw.split(',');
-            if (capabilities.some(capability => !CAPABILITIES.includes(capability)) || new Set(capabilities).size !== capabilities.length) {
-                throw new Error(`--with must contain unique capabilities from: ${CAPABILITIES.join(', ')}.`);
-            }
-            result.with = capabilities;
-        }
+            result.template = template;
+        }
+        else if (value === '--with' && command === 'init') {
+            const raw = rest[++i];
+            if (!raw || raw.startsWith('-')) throw new Error('--with requires a comma-separated capability list.');
+            const capabilities = raw.split(',');
+            if (capabilities.some(capability => !CAPABILITIES.includes(capability)) || new Set(capabilities).size !== capabilities.length) {
+                throw new Error(`--with must contain unique capabilities from: ${CAPABILITIES.join(', ')}.`);
+            }
+            result.with = capabilities;
+        }
         else if (value === '--port' && command === 'doctor') {
             const port = rest[++i];
             if (!/^\d+$/.test(port) || Number(port) > 65535) throw new Error('--port must be an integer from 0 through 65535.');
             result.port = Number(port);
         } else throw new Error(`Unknown option for ${command}: ${value}`);
     }
-    if (result.existing && (result.template || result.with || result.bare)) throw new Error('--existing cannot be combined with --template, --with, or --bare.');
+    if (result.existing && (result.template || result.with || result.bare)) throw new Error('--existing cannot be combined with --template, --with, or --bare.');
     return result;
 }
 

package/src/cli/run.js

@@ -36,18 +36,18 @@ async function run(args, cwd, version) {
             return { exitCode: 0, stdout: `${output}\n`, stderr: '' };
         }
         const result = new ProjectInitializer(version).initialize(root, options);
-        const report = {
-            schemaVersion: 1,
-            operation: 'init',
-            dryRun: options.dryRun,
-            foundation: options.template ?? 'default',
-            capabilities: options.with ?? [],
-            tests: !options.bare,
-            ...result,
-        };
-        const output = options.json ? JSON.stringify(report) : [
-            `${options.dryRun ? 'Planned initialization' : 'Initialization complete'} in ${result.root}`,
-            `Foundation: ${options.template ? `example template "${options.template}"` : 'neutral default'}; capabilities: ${options.with?.join(', ') || 'base'}; tests: ${options.bare ? 'omitted' : 'included'}.`,
+        const report = {
+            schemaVersion: 1,
+            operation: 'init',
+            dryRun: options.dryRun,
+            foundation: options.template ?? 'default',
+            capabilities: options.with ?? [],
+            tests: !options.bare,
+            ...result,
+        };
+        const output = options.json ? JSON.stringify(report) : [
+            `${options.dryRun ? 'Planned initialization' : 'Initialization complete'} in ${result.root}`,
+            `Foundation: ${options.template ? `example template "${options.template}"` : 'neutral default'}; capabilities: ${options.with?.join(', ') || 'base'}; tests: ${options.bare ? 'omitted' : 'included'}.`,
             `Created: ${result.created.join(', ')}`,
             `Kept existing: ${result.skipped.join(', ')}`,
             `Planned: ${result.planned.join(', ')}`,

package/src/cli/templates.js

@@ -3,19 +3,19 @@
 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']);
-const CAPABILITIES = Object.freeze(['auth', 'multiplayer']);
-
-function projectFiles(version, template = null, root = path.resolve(__dirname, '../..'), options = {}) {
-    if (template !== null && !TEMPLATES.includes(template)) throw new Error('Unknown starter template.');
-    if (options.with !== undefined && !Array.isArray(options.with)) throw new TypeError('Initializer capabilities must be an array.');
-    const capabilities = new Set(options.with || []);
-    if ([...capabilities].some(capability => !CAPABILITIES.includes(capability))) throw new Error('Unknown initializer capability.');
-    const selected = template ?? 'foundation';
-    const authenticated = template === 'dashboard' || capabilities.has('auth');
-    const multiplayer = capabilities.has('multiplayer');
-    const { devDependencies, dependencies, overrides } = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+const json = value => `${JSON.stringify(value, null, 2)}\n`;
+const TEMPLATES = Object.freeze(['realtime', 'chat', 'site', 'socket', 'dashboard', 'http-ws']);
+const CAPABILITIES = Object.freeze(['auth', 'multiplayer']);
+
+function projectFiles(version, template = null, root = path.resolve(__dirname, '../..'), options = {}) {
+    if (template !== null && !TEMPLATES.includes(template)) throw new Error('Unknown starter template.');
+    if (options.with !== undefined && !Array.isArray(options.with)) throw new TypeError('Initializer capabilities must be an array.');
+    const capabilities = new Set(options.with || []);
+    if ([...capabilities].some(capability => !CAPABILITIES.includes(capability))) throw new Error('Unknown initializer capability.');
+    const selected = template ?? 'foundation';
+    const authenticated = template === 'dashboard' || capabilities.has('auth');
+    const multiplayer = capabilities.has('multiplayer');
+    const { devDependencies, dependencies, overrides } = 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',
@@ -23,22 +23,22 @@ function projectFiles(version, template = null, root = path.resolve(__dirname, '
             build: 'tsc && node scripts/copy-assets.cjs',
             start: 'node dist/app.js',
             dev: 'nodemon',
-            ...(!options.bare ? {
-                test: 'npm run build && node --test test/app.test.cjs test/lifecycle.test.cjs',
-                'test:coverage': 'npm run build && c8 --all --src=dist --include=dist/** --reporter=text --reporter=json node --test test/app.test.cjs test/lifecycle.test.cjs',
-            } : {}),
+            ...(!options.bare ? {
+                test: 'npm run build && node --test test/app.test.cjs test/lifecycle.test.cjs',
+                'test:coverage': 'npm run build && c8 --all --src=dist --include=dist/** --reporter=text --reporter=json node --test test/app.test.cjs test/lifecycle.test.cjs',
+            } : {}),
         },
         dependencies: {
             redweb: `^${version}`,
-            ...(['chat', 'socket', 'dashboard'].includes(template) || authenticated || multiplayer ? { zod: devDependencies.zod } : {}),
-            ...(authenticated ? { express: dependencies.express } : {}),
-            ...(multiplayer ? { 'redweb-client': dependencies['redweb-client'] } : {}),
+            ...(['chat', 'socket', 'dashboard'].includes(template) || authenticated || multiplayer ? { zod: devDependencies.zod } : {}),
+            ...(authenticated ? { express: dependencies.express } : {}),
+            ...(multiplayer ? { 'redweb-client': dependencies['redweb-client'] } : {}),
         },
-        overrides,
-        devDependencies: {
-            typescript: devDependencies.typescript, nodemon: devDependencies.nodemon, ws: dependencies.ws,
-            ...(!options.bare ? { c8: devDependencies.c8 } : {}),
-            ...(authenticated ? {
+        overrides,
+        devDependencies: {
+            typescript: devDependencies.typescript, nodemon: devDependencies.nodemon, ws: dependencies.ws,
+            ...(!options.bare ? { c8: devDependencies.c8 } : {}),
+            ...(authenticated ? {
                 '@types/node': devDependencies['redweb-dashboard-types'].replace('npm:@types/node@', ''),
                 '@types/express': dependencies['@types/express'],
             } : {}),
@@ -51,10 +51,10 @@ function projectFiles(version, template = null, root = path.resolve(__dirname, '
             delay: 200,
         },
     };
-    if (authenticated) manifest.engines = { node: '>=22.13.0' };
-    if (template === 'dashboard') {
-        manifest.scripts['add-user'] = 'npm run build && node dist/admin.js';
-        if (!options.bare) manifest.scripts['test:coverage'] += ' test/rate-window.test.cjs';
+    if (authenticated) manifest.engines = { node: '>=22.13.0' };
+    if (template === 'dashboard') {
+        manifest.scripts['add-user'] = 'npm run build && node dist/admin.js';
+        if (!options.bare) manifest.scripts['test:coverage'] += ' test/rate-window.test.cjs';
     }
     const files = [
         { path: 'package.json', content: json(manifest) },
@@ -63,15 +63,15 @@ function projectFiles(version, template = null, root = path.resolve(__dirname, '
             compilerOptions: { rootDir: 'src', outDir: 'dist', sourceMap: true },
             include: ['src/**/*.ts', 'src/**/*.tsx'],
         }) },
-        { path: 'src/app.tsx', content: read(`${selected}/app.tsx`) },
-        { path: 'src/app.css', content: read(`${selected === 'dashboard' ? selected : 'shared'}/app.css`) },
-        { path: 'scripts/copy-assets.cjs', content: read('shared/copy-assets.cjs') },
-        ...(!options.bare ? [
-            { path: 'test/network.cjs', content: read('shared/network.cjs') },
-            { path: 'test/app.test.cjs', content: read(`${selected}/app.test.cjs`) },
-            { path: 'test/lifecycle.test.cjs', content: read('shared/lifecycle.test.cjs') },
-        ] : []),
-        { path: 'README.md', content: `${read('shared/README.md')}\n${read(`${selected}/README.md`)}` },
+        { path: 'src/app.tsx', content: read(`${selected}/app.tsx`) },
+        { path: 'src/app.css', content: read(`${selected === 'dashboard' ? selected : 'shared'}/app.css`) },
+        { path: 'scripts/copy-assets.cjs', content: read('shared/copy-assets.cjs') },
+        ...(!options.bare ? [
+            { path: 'test/network.cjs', content: read('shared/network.cjs') },
+            { path: 'test/app.test.cjs', content: read(`${selected}/app.test.cjs`) },
+            { path: 'test/lifecycle.test.cjs', content: read('shared/lifecycle.test.cjs') },
+        ] : []),
+        { path: 'README.md', content: `${read('shared/README.md')}\n${read(`${selected}/README.md`)}` },
         { path: '.gitignore', content: 'node_modules/\ndist/\ncoverage/\n.env\ndata/\n*.sqlite\n*.sqlite-wal\n*.sqlite-shm\n' },
     ];
     if (template === 'chat') {
@@ -88,7 +88,7 @@ function projectFiles(version, template = null, root = path.resolve(__dirname, '
     }
     if (template === 'dashboard') {
         files.push({ path: '.npmrc', content: 'engine-strict=true\n' });
-        if (!options.bare) files.push({ path: 'test/rate-window.test.cjs', content: read('dashboard/rate-window.test.cjs') });
+        if (!options.bare) 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}`) });
         }
@@ -96,4 +96,4 @@ function projectFiles(version, template = null, root = path.resolve(__dirname, '
     return Object.freeze(files.map(Object.freeze));
 }
 
-module.exports = { projectFiles, CAPABILITIES, TEMPLATES };
+module.exports = { projectFiles, CAPABILITIES, TEMPLATES };

package/src/docs/Documentation.js

@@ -77,8 +77,8 @@ class Documentation {
             : `> 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.');
+    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'
             ? [
@@ -86,18 +86,18 @@ class Documentation {
                 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');
-    }
-
-    foundationSetup() {
-        return this.channel === 'unreleased'
-            ? [
-                'Replace `TARBALL` with the absolute path to the matching Redweb tarball produced by `npm pack` (quoted if it contains spaces):',
-                fence('npx --yes --package TARBALL redweb init my-app\ncd my-app\nnpm install --save-exact TARBALL\nnpm test\nnpm run dev', 'sh'),
-                'This prerelease Redweb artifact is development-only until its release checks finish.',
-            ].join('\n\n')
-            : fence(`npx --yes redweb@${this.channel} init my-app\ncd my-app\nnpm install --save-exact redweb@${this.channel}\nnpm test\nnpm run dev`, 'sh');
-    }
+            : fence(`npx --yes redweb@${this.channel} init my-${template} --template ${template}\ncd my-${template}\nnpm install --save-exact redweb@${this.channel}\n${acceptance}`, 'sh');
+    }
+
+    foundationSetup() {
+        return this.channel === 'unreleased'
+            ? [
+                'Replace `TARBALL` with the absolute path to the matching Redweb tarball produced by `npm pack` (quoted if it contains spaces):',
+                fence('npx --yes --package TARBALL redweb init my-app\ncd my-app\nnpm install --save-exact TARBALL\nnpm test\nnpm run dev', 'sh'),
+                'This prerelease Redweb artifact is development-only until its release checks finish.',
+            ].join('\n\n')
+            : fence(`npx --yes redweb@${this.channel} init my-app\ncd my-app\nnpm install --save-exact redweb@${this.channel}\nnpm test\nnpm run dev`, 'sh');
+    }
 
     recipe(template) {
         const files = projectFiles(this.manifest.version, template, this.root).map(file => ({ ...file, content: normalize(file.content) }));
@@ -114,28 +114,28 @@ class Documentation {
         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) {
+    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);
-    }
-
-    code(entry, field) {
-        return entry.recipe ? this.recipeCode(entry.recipe) : entry.codeSource ? this.read(entry.codeSource) : entry[field];
-    }
+        return normalize(file.content);
+    }
+
+    code(entry, field) {
+        return entry.recipe ? this.recipeCode(entry.recipe) : entry.codeSource ? this.read(entry.codeSource) : entry[field];
+    }
 
     topic(topic) {
-        let markdown = `${this.notice()}\n\n${this.links(this.read(topic.source), topic.source)}`;
-        markdown = markdown.replace(/<!-- source: ([\w./-]+) -->/g,
-            (_match, file) => fence(this.read(file), language(file)));
+        let markdown = `${this.notice()}\n\n${this.links(this.read(topic.source), topic.source)}`;
+        markdown = markdown.replace(/<!-- source: ([\w./-]+) -->/g,
+            (_match, file) => fence(this.read(file), language(file)));
         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.`,
-                ...(topic.codeSource ? [] : [`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))]),
+                `The [complete ${template} recipe](${this.basePath}/recipes/${template}.md) contains every generated file, its real acceptance tests, and deployment instructions.`,
+                ...(topic.codeSource ? [] : [`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 };
@@ -145,8 +145,8 @@ class Documentation {
         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: this.code(section, 'usage') }));
-        const examples = reference.examples.map(example => ({ ...example, code: this.code(example, 'code') }));
+        const api = reference.api.map(section => ({ ...section, usage: this.code(section, 'usage') }));
+        const examples = reference.examples.map(example => ({ ...example, code: this.code(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,

package/src/htmx/CodeHighlight.js

@@ -0,0 +1,98 @@
+const KEYWORDS = new Set([
+    'async', 'await', 'break', 'case', 'catch', 'class', 'const', 'continue',
+    'default', 'delete', 'do', 'else', 'export', 'extends', 'finally', 'for',
+    'from', 'function', 'if', 'import', 'in', 'instanceof', 'let', 'new',
+    'of', 'return', 'static', 'super', 'switch', 'throw', 'try', 'typeof',
+    'var', 'while', 'yield',
+]);
+const LITERALS = new Set(['false', 'null', 'true', 'undefined']);
+const LANGUAGES = new Set(['js', 'javascript', 'ts', 'typescript', 'tsx']);
+const identifierStart = character => /[A-Za-z_$]/.test(character);
+const identifierPart = character => /[A-Za-z0-9_$]/.test(character);
+
+function actionAttributeBefore(source, brace) {
+    let index = brace - 1;
+    while (index >= 0 && /\s/.test(source[index])) index -= 1;
+    if (source[index] !== '=') return false;
+    index -= 1;
+    while (index >= 0 && /\s/.test(source[index])) index -= 1;
+    const end = index + 1;
+    while (index >= 0 && /[\w-]/.test(source[index])) index -= 1;
+    return /^rw-[\w-]+$/.test(source.slice(index + 1, end));
+}
+
+function quotedEnd(source, start) {
+    const quote = source[start];
+    let index = start + 1;
+    while (index < source.length) {
+        if (source[index] === '\\') index += 2;
+        else if (source[index++] === quote) break;
+    }
+    return index;
+}
+
+function tokens(source) {
+    const result = [];
+    let index = 0;
+    let actionDepth = 0;
+    const push = (kind, end) => {
+        result.push({ kind, value: source.slice(index, end) });
+        index = end;
+    };
+    while (index < source.length) {
+        if (source.startsWith('//', index)) {
+            const newline = source.indexOf('\n', index);
+            push('comment', newline < 0 ? source.length : newline);
+            continue;
+        }
+        if (source.startsWith('/*', index)) {
+            const close = source.indexOf('*/', index + 2);
+            push('comment', close < 0 ? source.length : close + 2);
+            continue;
+        }
+        const character = source[index];
+        if (character === '{') {
+            if (actionDepth) actionDepth += 1;
+            else if (actionAttributeBefore(source, index)) actionDepth = 1;
+            push('plain', index + 1);
+            continue;
+        }
+        if (character === '}') {
+            if (actionDepth) actionDepth -= 1;
+            push('plain', index + 1);
+            continue;
+        }
+        if (character === "'" || character === '"' || character === '`') {
+            push('string', quotedEnd(source, index));
+            continue;
+        }
+        if (/\d/.test(character)) {
+            const match = /^(?:0[xob][\da-f]+|\d+(?:\.\d+)?(?:e[+-]?\d+)?)/i.exec(source.slice(index));
+            push('number', index + match[0].length);
+            continue;
+        }
+        if (identifierStart(character)) {
+            let end = index + 1;
+            while (end < source.length && identifierPart(source[end])) end += 1;
+            const value = source.slice(index, end);
+            push(KEYWORDS.has(value) ? 'keyword' : LITERALS.has(value) ? 'literal' : actionDepth ? 'reference' : 'plain', end);
+            continue;
+        }
+        let end = index + 1;
+        while (end < source.length && !source.startsWith('//', end) && !source.startsWith('/*', end)
+            && !['{', '}', "'", '"', '`'].includes(source[end]) && !/\d/.test(source[end])
+            && !identifierStart(source[end])) end += 1;
+        push('plain', end);
+    }
+    return result;
+}
+
+function highlightCode(source, language) {
+    const { html } = require('./Html');
+    if (!LANGUAGES.has(language)) return html`${source}`;
+    return html`${tokens(source).map(token => token.kind === 'plain'
+        ? html`${token.value}`
+        : html`<span class="${`token-${token.kind}`}">${token.value}</span>`)}`;
+}
+
+module.exports = { highlightCode };

package/src/htmx/Html.js

@@ -123,12 +123,13 @@ function codeBlock(code, options = {}) {
         throw new TypeError('codeBlock() language must be a safe name of at most 32 characters.');
     }
     if (typeof label !== 'string') throw new TypeError('codeBlock() label must be a string.');
-    if (highlight !== undefined && typeof highlight !== 'function') throw new TypeError('codeBlock() highlight must be a function.');
+    if (highlight !== undefined && highlight !== false && typeof highlight !== 'function') throw new TypeError('codeBlock() highlight must be a function or false.');
     const caption = label ? html`<figcaption>${label}</figcaption>` : html``;
     let content = isHtml(code) ? code : String(code ?? '');
-    if (highlight) {
+    const highlighter = highlight === false ? undefined : highlight ?? (isHtml(code) ? undefined : require('./CodeHighlight').highlightCode);
+    if (highlighter) {
         if (isHtml(code)) throw new TypeError('codeBlock() cannot highlight an HtmlFragment.');
-        content = synchronous(highlight(content, language), 'codeBlock() highlight must render synchronously.');
+        content = synchronous(highlighter(content, language), 'codeBlock() highlight must render synchronously.');
         if (!isHtml(content)) throw new TypeError('codeBlock() highlight must return an HtmlFragment.');
     }
     return html`<figure class="redweb-code">${caption}<pre><code class="${attribute(`language-${language}`)}">${content}</code></pre></figure>`;

package/src/htmx/Jsx.js

@@ -83,13 +83,13 @@ function renderComponent(Component, properties) {
 
 function createElement(type, properties, key) {
     const reactive = ReactiveRenderer.jsx();
-    const props = properties == null ? {} : properties;
+    const props = properties == null ? {} : properties;
     if (!props || typeof props !== 'object' || Array.isArray(props)) {
         throw new TypeError('JSX properties must be an object.');
     }
     let result;
     if (type === Fragment) result = trustedHtml(renderChild(props.children));
-    else if (typeof type === 'string') result = renderIntrinsic(type, require('./SocketAction').attributes(props));
+    else if (typeof type === 'string') result = renderIntrinsic(type, require('./SocketAction').attributes(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;

package/src/htmx/LiveHtmlServer.js

@@ -28,10 +28,12 @@ class LiveHtmlServer {
             maxSessions,
             maxConcurrentRenders,
             shutdownTimeoutMs = 1000,
+            uploadTimeoutMs,
             heartbeat,
             authenticate,
             authenticationTimeoutMs,
             origins,
+            providers,
             development,
             server: suppliedApp,
             ...httpOptions
@@ -54,10 +56,12 @@ class LiveHtmlServer {
             maxSessions,
             maxConcurrentRenders,
             shutdownTimeoutMs,
+            uploadTimeoutMs,
             heartbeat,
             authenticate,
             authenticationTimeoutMs,
             origins,
+            providers,
             logger: httpOptions.logger,
         });
         if (this._inspection) this.manager.Renderer = this._inspection.Renderer;
@@ -71,7 +75,7 @@ class LiveHtmlServer {
             if (this.manager.hasLivePages || socketRoutes.length) {
                 this.sockets = new SocketServer({
                     server: this.http.server,
-                    routes: [...(this.manager.hasLivePages ? [this.manager.route()] : []), ...require('./PageSocketRoute').bindRoutes(this.manager, socketRoutes)],
+                    routes: [...(this.manager.hasLivePages ? [this.manager.route()] : []), ...require('./PageSocketRoute').bindRoutes(this.manager, socketRoutes)],
                     listen,
                     port: this.http.port,
                     bind: this.http.bind,

package/src/htmx/LivePage.js

@@ -5,7 +5,8 @@ const ReactiveRenderer = require('./ReactiveRenderer');
 const dataProperty = require('../dataProperty');
 const { ActionInputError } = require('./ActionDefinition');
 const { isHtml, markHtml, renderValue } = require('./Html');
-const { forEachState, getActionImplementation, getActionDefinition, getStateConfig, isComponentClass } = require('./metadata');
+const { forEachState, getActionImplementation, getActionDefinition, getResourceMetadata, getStateConfig, isComponentClass } = require('./metadata');
+const { LiveResource } = require('./LiveResource');
 
 const RUNTIME = new WeakMap();
 const COMPONENT_RENDER_CONTEXT = new AsyncLocalStorage();
@@ -159,6 +160,7 @@ class LivePage {
             });
         });
         internal.stateActive = true;
+        getResourceMetadata(this.constructor).forEach((config, name) => config.resource.bind(this, name, config.select));
         Object.keys(this).forEach(name => {
             const value = this[name];
             if (isComponentClass(value?.constructor) && getStateConfig(this.constructor, name)) {
@@ -226,6 +228,7 @@ class LivePage {
 
     _stateChanged(name, value) {
         if (!getStateConfig(this.constructor, name)) return false;
+        LiveResource.refresh(this);
         const payload = LivePage.statePayload(this, name, value, true);
         runtime(this).connections.forEach(socket => {
             const session = socket.__redwebPageSession;
@@ -261,6 +264,7 @@ class LivePage {
         const internal = runtime(this);
         if (internal.disposePromise) return internal.disposePromise;
         internal.disposed = true;
+        LiveResource.release(this);
         internal.connections.clear();
         internal.disposePromise = Promise.resolve().then(async () => {
             const tasks = [...internal.children.values()].map(component => LivePage.dispose(component));