redweb 0.13.5 → 0.15.0

package/examples/live-html/components.js

@@ -1,113 +1,114 @@
-"use strict";
-var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
-    var useValue = arguments.length > 2;
-    for (var i = 0; i < initializers.length; i++) {
-        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
-    }
-    return useValue ? value : void 0;
-};
-var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
-    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
-    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
-    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
-    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
-    var _, done = false;
-    for (var i = decorators.length - 1; i >= 0; i--) {
-        var context = {};
-        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
-        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
-        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
-        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
-        if (kind === "accessor") {
-            if (result === void 0) continue;
-            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
-            if (_ = accept(result.get)) descriptor.get = _;
-            if (_ = accept(result.set)) descriptor.set = _;
-            if (_ = accept(result.init)) initializers.unshift(_);
-        }
-        else if (_ = accept(result)) {
-            if (kind === "field") initializers.unshift(_);
-            else descriptor[key] = _;
-        }
-    }
-    if (target) Object.defineProperty(target, contextIn.name, descriptor);
-    done = true;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ComponentsPage = exports.CounterComponent = void 0;
-const redweb_1 = require('../..');
-let CounterComponent = (() => {
-    let _classDecorators = [(0, redweb_1.component)()];
-    let _classDescriptor;
-    let _classExtraInitializers = [];
-    let _classThis;
-    let _instanceExtraInitializers = [];
-    let _count_decorators;
-    let _count_initializers = [];
-    let _count_extraInitializers = [];
-    let _increment_decorators;
-    var CounterComponent = class {
-        static { _classThis = this; }
-        static {
-            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
-            _count_decorators = [(0, redweb_1.state)()];
-            _increment_decorators = [(0, redweb_1.action)()];
-            __esDecorate(this, null, _increment_decorators, { kind: "method", name: "increment", static: false, private: false, access: { has: obj => "increment" in obj, get: obj => obj.increment }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(null, null, _count_decorators, { kind: "field", name: "count", static: false, private: false, access: { has: obj => "count" in obj, get: obj => obj.count, set: (obj, value) => { obj.count = value; } }, metadata: _metadata }, _count_initializers, _count_extraInitializers);
-            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
-            CounterComponent = _classThis = _classDescriptor.value;
-            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
-            __runInitializers(_classThis, _classExtraInitializers);
-        }
-        label = __runInitializers(this, _instanceExtraInitializers);
-        count = __runInitializers(this, _count_initializers, 0);
-        constructor(label) {
-            __runInitializers(this, _count_extraInitializers);
-            this.label = label;
-        }
-        increment() {
-            this.count += 1;
-        }
-        render() {
+"use strict";
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComponentsPage = exports.CounterComponent = void 0;
+const redweb_1 = require('../..');
+let CounterComponent = (() => {
+    let _classDecorators = [(0, redweb_1.component)()];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    let _instanceExtraInitializers = [];
+    let _count_decorators;
+    let _count_initializers = [];
+    let _count_extraInitializers = [];
+    let _increment_decorators;
+    var CounterComponent = class {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _count_decorators = [(0, redweb_1.state)()];
+            _increment_decorators = [(0, redweb_1.action)()];
+            __esDecorate(this, null, _increment_decorators, { kind: "method", name: "increment", static: false, private: false, access: { has: obj => "increment" in obj, get: obj => obj.increment }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(null, null, _count_decorators, { kind: "field", name: "count", static: false, private: false, access: { has: obj => "count" in obj, get: obj => obj.count, set: (obj, value) => { obj.count = value; } }, metadata: _metadata }, _count_initializers, _count_extraInitializers);
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            CounterComponent = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        label = __runInitializers(this, _instanceExtraInitializers);
+        count = __runInitializers(this, _count_initializers, 0);
+        constructor(label) {
+            __runInitializers(this, _count_extraInitializers);
+            this.label = label;
+        }
+        increment() {
+            this.count += 1;
+        }
+        render() {
             return (0, redweb_1.html) `
             <article class="counter-card">
                 <h2>${this.label}</h2>
                 <output data-rw-state="count">${this.count}</output>
                 <button type="button" rw-click="increment">Increment on the server</button>
             </article>
-        `;
-        }
-    };
-    return CounterComponent = _classThis;
-})();
-exports.CounterComponent = CounterComponent;
-let ComponentsPage = (() => {
-    let _classDecorators = [(0, redweb_1.page)('/', { css: 'components.css' })];
-    let _classDescriptor;
-    let _classExtraInitializers = [];
-    let _classThis;
-    var ComponentsPage = class {
-        static { _classThis = this; }
-        static {
-            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
-            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
-            ComponentsPage = _classThis = _classDescriptor.value;
-            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
-            __runInitializers(_classThis, _classExtraInitializers);
-        }
-        primary = new CounterComponent('Primary counter');
-        secondary = new CounterComponent('Independent counter');
-        render() {
+        `;
+        }
+    };
+    return CounterComponent = _classThis;
+})();
+exports.CounterComponent = CounterComponent;
+let ComponentsPage = (() => {
+    let _classDecorators = [(0, redweb_1.page)('/', { css: 'components.css' })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    var ComponentsPage = class {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            ComponentsPage = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        primary = new CounterComponent('Primary counter');
+        secondary = new CounterComponent('Independent counter');
+        render() {
             return (0, redweb_1.html) `
             <main>
                 <h1>Reusable server components</h1>
                 <section class="counter-grid">${this.primary}${this.secondary}</section>
             </main>
-        `;
-        }
-    };
-    return ComponentsPage = _classThis;
-})();
-exports.ComponentsPage = ComponentsPage;
-if (require.main === module)
-    (0, redweb_1.start)(ComponentsPage, { port: 8080 });
+        `;
+        }
+    };
+    return ComponentsPage = _classThis;
+})();
+exports.ComponentsPage = ComponentsPage;
+if (require.main === module)
+    void (0, redweb_1.defineApp)({ pages: [ComponentsPage], port: 8080 }).run()
+        .catch(error => { console.error(error); process.exitCode = 1; });

package/examples/live-html/components.ts

@@ -1,4 +1,4 @@
-import { action, component, html, page, start, state } from 'redweb';
+import { action, component, defineApp, html, page, state } from 'redweb';
 
 @component()
 export class CounterComponent {
@@ -38,4 +38,5 @@ export class ComponentsPage {
     }
 }
 
-if (require.main === module) start(ComponentsPage, { port: 8080 });
+if (require.main === module) void defineApp({ pages: [ComponentsPage], port: 8080 }).run()
+    .catch(error => { console.error(error); process.exitCode = 1; });

package/examples/live-html/counter.js

@@ -1,73 +1,74 @@
-"use strict";
-var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
-    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
-    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
-    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
-    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
-    var _, done = false;
-    for (var i = decorators.length - 1; i >= 0; i--) {
-        var context = {};
-        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
-        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
-        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
-        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
-        if (kind === "accessor") {
-            if (result === void 0) continue;
-            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
-            if (_ = accept(result.get)) descriptor.get = _;
-            if (_ = accept(result.set)) descriptor.set = _;
-            if (_ = accept(result.init)) initializers.unshift(_);
-        }
-        else if (_ = accept(result)) {
-            if (kind === "field") initializers.unshift(_);
-            else descriptor[key] = _;
-        }
-    }
-    if (target) Object.defineProperty(target, contextIn.name, descriptor);
-    done = true;
-};
-var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
-    var useValue = arguments.length > 2;
-    for (var i = 0; i < initializers.length; i++) {
-        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
-    }
-    return useValue ? value : void 0;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CounterPage = void 0;
-const redweb_1 = require('../..');
-let CounterPage = (() => {
-    let _classDecorators = [(0, redweb_1.page)('/', { template: 'counter.html', css: 'counter.css' })];
-    let _classDescriptor;
-    let _classExtraInitializers = [];
-    let _classThis;
-    let _count_decorators;
-    let _count_initializers = [];
-    let _count_extraInitializers = [];
-    var CounterPage = class {
-        static { _classThis = this; }
-        static {
-            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
-            _count_decorators = [(0, redweb_1.state)()];
-            __esDecorate(null, null, _count_decorators, { kind: "field", name: "count", static: false, private: false, access: { has: obj => "count" in obj, get: obj => obj.count, set: (obj, value) => { obj.count = value; } }, metadata: _metadata }, _count_initializers, _count_extraInitializers);
-            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
-            CounterPage = _classThis = _classDescriptor.value;
-            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
-            __runInitializers(_classThis, _classExtraInitializers);
-        }
-        count = __runInitializers(this, _count_initializers, 0);
-        ticker = (__runInitializers(this, _count_extraInitializers), null);
-        connected() {
-            this.ticker = setInterval(() => { this.count += 1; }, 1000);
-        }
-        disconnected() {
-            if (this.ticker)
-                clearInterval(this.ticker);
-            this.ticker = null;
-        }
-    };
-    return CounterPage = _classThis;
-})();
-exports.CounterPage = CounterPage;
-if (require.main === module)
-    (0, redweb_1.start)(CounterPage, { port: 8080 });
+"use strict";
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CounterPage = void 0;
+const redweb_1 = require('../..');
+let CounterPage = (() => {
+    let _classDecorators = [(0, redweb_1.page)('/', { template: 'counter.html', css: 'counter.css' })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    let _count_decorators;
+    let _count_initializers = [];
+    let _count_extraInitializers = [];
+    var CounterPage = class {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _count_decorators = [(0, redweb_1.state)()];
+            __esDecorate(null, null, _count_decorators, { kind: "field", name: "count", static: false, private: false, access: { has: obj => "count" in obj, get: obj => obj.count, set: (obj, value) => { obj.count = value; } }, metadata: _metadata }, _count_initializers, _count_extraInitializers);
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            CounterPage = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        count = __runInitializers(this, _count_initializers, 0);
+        ticker = (__runInitializers(this, _count_extraInitializers), null);
+        connected() {
+            this.ticker = setInterval(() => { this.count += 1; }, 1000);
+        }
+        disconnected() {
+            if (this.ticker)
+                clearInterval(this.ticker);
+            this.ticker = null;
+        }
+    };
+    return CounterPage = _classThis;
+})();
+exports.CounterPage = CounterPage;
+if (require.main === module)
+    void (0, redweb_1.defineApp)({ pages: [CounterPage], port: 8080 }).run()
+        .catch(error => { console.error(error); process.exitCode = 1; });

package/examples/live-html/counter.ts

@@ -1,4 +1,4 @@
-import { page, start, state } from 'redweb';
+import { defineApp, page, state } from 'redweb';
 
 @page('/', { template: 'counter.html', css: 'counter.css' })
 export class CounterPage {
@@ -18,4 +18,5 @@ export class CounterPage {
 
 }
 
-if (require.main === module) start(CounterPage, { port: 8080 });
+if (require.main === module) void defineApp({ pages: [CounterPage], port: 8080 }).run()
+    .catch(error => { console.error(error); process.exitCode = 1; });

package/examples/live-html/jsx-page.js

@@ -78,4 +78,5 @@ let JsxPage = (() => {
 })();
 exports.JsxPage = JsxPage;
 if (require.main === module)
-    (0, redweb_1.start)(JsxPage, { port: 8181 });
+    void (0, redweb_1.defineApp)({ pages: [JsxPage], port: 8181 }).run()
+        .catch(error => { console.error(error); process.exitCode = 1; });

package/examples/live-html/jsx-page.tsx

@@ -1,4 +1,4 @@
-import { LivePage, action, component, page, start, state } from 'redweb';
+import { LivePage, action, component, defineApp, page, state } from 'redweb';
 import type { Child } from 'redweb/jsx-runtime';
 
 interface CardProperties {
@@ -38,4 +38,5 @@ export class JsxPage extends LivePage {
     }
 }
 
-if (require.main === module) start(JsxPage, { port: 8181 });
+if (require.main === module) void defineApp({ pages: [JsxPage], port: 8181 }).run()
+    .catch(error => { console.error(error); process.exitCode = 1; });

package/index.d.ts

@@ -1,7 +1,7 @@
 declare module 'redweb' {
     export { defineSocketContract } from 'redweb/contract';
     export type { SocketContract, ContractClient, SocketSchema, ContractInput, ContractOutput, ContractMessage } from 'redweb/contract';
-    import { Application, RequestHandler } from 'express';
+    import { Application as ExpressApplication, RequestHandler } from 'express';
     import { CorsOptions } from 'cors';
     import { Server as NodeHttpServer } from 'http';
     import { Server as NodeHttpsServer } from 'https';
@@ -22,7 +22,7 @@ declare module 'redweb' {
         listenCallback?: () => void;
         encoding?: RedWebEncoding;
         ssl?: { key: string; cert: string };
-        server?: Application;
+        server?: ExpressApplication;
         corsOptions?: CorsOptions | false;
         exposeErrors?: boolean;
         logger?: RedWebLogger | null;
@@ -35,7 +35,9 @@ declare module 'redweb' {
         isAssigned: boolean;
         sendJson(data: unknown): boolean;
         broadcast(data: unknown): number;
-        context?: RedWebConnectionContext;
+        context?: RedWebConnectionContext;
+        /** Present on an attached page connection; checks the actual page class and connection lifetime. */
+        page?<Page extends object>(PageClass: new () => Page): Page;
         joinRoom?(roomId: string): boolean;
         /** Bounded permission check followed by atomic membership insertion. */
         enterRoom?(roomId: string): Promise<boolean>;
@@ -287,7 +289,10 @@ declare module 'redweb' {
         handlers: Array<new () => BaseHandler>;
         services?: Array<new () => SocketService>;
         allowDuplicateConnections?: boolean;
-        websocketOptions?: Omit<ServerOptions, 'noServer' | 'path' | 'server' | 'port'>;
+        websocketOptions?: Omit<ServerOptions, 'noServer' | 'path' | 'server' | 'port'> & {
+            /** Closing-handshake deadline in milliseconds (1..2147483647). Default: 5000. Not an idle timeout. */
+            closeTimeout?: number;
+        };
         trustProxy?: boolean;
         getClientKey?: (request: import('http').IncomingMessage) => string;
         exposeErrors?: boolean;
@@ -477,7 +482,7 @@ declare module 'redweb' {
     }
 
     export class BaseHttpServer {
-        app: Application;
+        app: ExpressApplication;
         server?: NodeHttpServer;
         constructor(options?: RedWebOptions);
         shutdown?(): Promise<void>;
@@ -551,7 +556,9 @@ declare module 'redweb' {
         dispose(): Promise<boolean>;
     }
 
-    export type PageOptions = {
+    export type PageOptions = {
+        /** Use a registered custom route for this private live page's typed TSX commands and rendering. */
+        socket?: new () => SocketRoute;
         template?: string;
         css?: string | readonly string[];
         live?: boolean;
@@ -653,6 +660,8 @@ declare module 'redweb' {
     export type LivePageClass = new () => object;
 
     export interface LiveHtmlServerBaseOptions extends Omit<RedWebOptions, 'enableHtmxRendering'> {
+        /** Custom routes share the live-page SocketServer; paths must be unique. */
+        socketRoutes?: Array<new () => SocketRoute>;
         development?: LiveDevelopmentOptions;
         pages: readonly LivePageClass[];
         templateRoot?: string;
@@ -682,7 +691,7 @@ declare module 'redweb' {
     export type LiveHtmlStartOptions = Omit<LiveHtmlServerBaseOptions, 'pages'> & LiveHtmlAuthentication;
 
     export class LiveHtmlServer {
-        app: Application;
+        app: ExpressApplication;
         server: NodeHttpServer | NodeHttpsServer;
         http: HttpServer | HttpsServer;
         sockets: SocketServer | null;
@@ -699,6 +708,49 @@ declare module 'redweb' {
         options?: LiveHtmlStartOptions
     ): LiveHtmlServer;
 
+    export interface ApplicationContext {
+        app: ExpressApplication;
+        server: NodeHttpServer | NodeHttpsServer;
+        http: HttpServer | HttpsServer;
+        sockets: SocketServer | null;
+        services: ApplicationService[];
+    }
+
+    /** Application-wide resources; route-specific SocketService classes stay on their routes. */
+    export interface ApplicationService {
+        onInit(app: ApplicationContext, signal: AbortSignal): void | Promise<void>;
+        onShutdown(): void | Promise<void>;
+    }
+
+    export type ApplicationOptions = Omit<LiveHtmlServerBaseOptions, 'pages' | 'services' | 'listen' | 'socketRoutes'> & LiveHtmlAuthentication & {
+        pages?: readonly LivePageClass[];
+        sockets?: ReadonlyArray<new () => SocketRoute>;
+        services?: ReadonlyArray<new () => ApplicationService>;
+        httpServices?: RedWebOptions['services'];
+        startupTimeoutMs?: number;
+        /** Install process signal handlers only when run() is called; defaults to true. */
+        signals?: boolean;
+    };
+
+    export class Application {
+        constructor(options?: ApplicationOptions);
+        /** Copied definition; use {...app.options, port: 0} to define an independent test instance. */
+        readonly options: Readonly<ApplicationOptions>;
+        readonly app: ExpressApplication | null;
+        readonly server: NodeHttpServer | NodeHttpsServer | null;
+        readonly http: HttpServer | HttpsServer | null;
+        readonly sockets: SocketServer | null;
+        readonly services: ApplicationService[];
+        /** Resolves after services initialize and the single HTTP/WS listener is ready. Cannot restart after shutdown. */
+        run(): Promise<Application & ApplicationContext>;
+        shutdown(): Promise<void>;
+        revoke(principal: string | number | bigint | true): Promise<number>;
+        inspect(): DevelopmentSnapshot | null;
+    }
+
+    /** Inert until run(); repeated run calls share startup until shutdown; shutdown is idempotent. */
+    export function defineApp(options?: ApplicationOptions): Application;
+
     export interface StaticExportOptions {
         outDir: string;
         templateRoot?: string;

package/index.js

@@ -15,10 +15,13 @@ const {
 } = require('./src/ws');
 const { BaseHandler } = require('./src/ws/BaseHandler');
 const { defineSocketContract } = require('./contract');
+const { Application, defineApp } = require('./src/Application');
 const HttpServer = require('./src/http/HttpServer');
 const HttpsServer = require('./src/http/HttpsServer');
 const { action, attribute, codeBlock, component, defineSite, each, exportStatic, html, HtmlRenderer, LiveHtmlServer, LivePage, page, start, state, url, view } = require('./src/htmx');
 module.exports = {
+    Application,
+    defineApp,
     HttpServer,
     HttpsServer,
     BaseHttpServer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redweb",
-  "version": "0.13.5",
+  "version": "0.15.0",
   "description": "A small Node.js foundation for HTTP, WebSockets, multiplayer services, and server-rendered HTML",
   "main": "index.js",
   "types": "index.d.ts",
@@ -93,8 +93,8 @@
     "verify:client:source-coverage": "node node_modules/jest/bin/jest.js tests/unit/client-source-coverage.unit.test.js tests/integration/client-source-preflight.integration.test.js tests/integration/command-report.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/lib/ClientSourceCoverage.js --collectCoverageFrom=scripts/lib/reportCommand.js --coverageDirectory=coverage/client-source-collector && node --test tests/integration/client-worker-retention.integration.test.cjs && node scripts/verify-client-source-coverage.js",
     "verify:development:browser": "node scripts/verify-development-refresh-browser.js",
     "verify:development:coverage": "node node_modules/jest/bin/jest.js tests/unit/development-refresh-cleanup.unit.test.js tests/unit/development-refresh-boundaries.unit.test.js tests/integration/development-refresh-verifier.integration.test.js --runInBand --coverage --collectCoverageFrom=scripts/verify-development-refresh-browser.js --coverageDirectory=coverage/development-coordinator",
-    "verify:starters:lifecycle": "node scripts/verify-starter-lifecycle.js",
-    "verify:starters:lifecycle:coverage": "node node_modules/jest/bin/jest.js tests/unit/starter-lifecycle-command.unit.test.js tests/integration/starter-lifecycle-coverage.integration.test.js --runInBand --silent --coverage --collectCoverageFrom=scripts/verify-starter-lifecycle.js --coverageDirectory=coverage/starter-lifecycle-coordinator",
+    "verify:starters:lifecycle": "node node_modules/jest/bin/jest.js tests/integration/define-app-process.integration.test.js --runInBand --coverage=false",
+    "verify:starters:lifecycle:coverage": "node node_modules/jest/bin/jest.js tests/unit/define-app.unit.test.js tests/unit/define-app-process.unit.test.js tests/unit/startup-cleanup.unit.test.js tests/integration/define-app.integration.test.js tests/integration/define-app-process.integration.test.js --runInBand --coverage --collectCoverageFrom=src/Application.js --collectCoverageFrom=src/StartupCleanup.js --coverageDirectory=coverage/application-lifecycle",
     "measure:starters:coverage": "node scripts/measure-starter-coverage.js",
     "verify:starter-coordinators:coverage": "node node_modules/jest/bin/jest.js tests/unit/starter-coordinators.unit.test.js tests/integration/verification-summary.integration.test.js tests/integration/starter-coordinator-input.integration.test.js --runInBand --silent --coverage --collectCoverageFrom=scripts/measure-starter-coverage.js --collectCoverageFrom=scripts/verify-starter-source-coverage.js --collectCoverageFrom=scripts/lib/finishVerificationSummary.js --coverageDirectory=coverage/starter-coordinators",
     "verify:starters:source-coverage": "node node_modules/jest/bin/jest.js tests/unit/application-coverage.unit.test.js --runInBand --coverage --collectCoverageFrom=scripts/lib/ApplicationCoverage.js --collectCoverageFrom=scripts/lib/assertCoverageFile.js --coverageDirectory=coverage/application-collector && node scripts/verify-starter-source-coverage.js",
@@ -159,10 +159,13 @@
     "@types/ws": "^8.18.1",
     "cors": "^2.8.5",
     "express": "^4.22.2",
-    "redweb-client": "^0.2.0",
+    "redweb-client": "^0.3.0",
     "ws": "^8.21.3"
   },
-  "devDependencies": {
+  "overrides": {
+    "express": { "qs": "6.16.0" }
+  },
+  "devDependencies": {
     "@types/jest": "^29.5.12",
     "c8": "^10.1.3",
     "expect": "29.7.0",

package/recipes/chat/app.test.cjs

@@ -1,8 +1,10 @@
 const test = require('node:test');
 const { once } = require('node:events');
 const assert = require('node:assert/strict');
-const { listen, live, connect } = require('./network.cjs');
+const { listen: listenApp, live, connect } = require('./network.cjs');
 const { createChatroomPage, chatInputs } = require('../dist/chatroom.js');
+// Each test gets an independent room rather than the default module-level room.
+const listen = t => listenApp(t, { pages: [createChatroomPage()] });
 
 test('the standalone canonical chat reports an occupied default port', { timeout: 10000 }, async t => {
     const net = require('node:net');

package/recipes/chat/app.tsx

@@ -1,9 +1,6 @@
-import { start, type LiveHtmlStartOptions } from 'redweb';
-import { createChatroomPage } from './chatroom';
-import { runApp } from './run-app';
+import { defineApp } from 'redweb';
+import { ChatroomPage } from './chatroom';
 
-export function createApp(options: LiveHtmlStartOptions = {}) {
-    return start(createChatroomPage(), { port: Number(process.env.PORT ?? 8181), templateRoot: __dirname, ...options });
-}
+export const app = defineApp({ pages: [ChatroomPage], port: Number(process.env.PORT ?? 8181), templateRoot: __dirname });
 
-if (require.main === module) runApp(createApp);
+if (require.main === module) void app.run().catch(error => { console.error(error); process.exitCode = 1; });