@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.21

package/README.md

@@ -227,7 +227,7 @@ import { defineApiHandler, defineGroupHandler, eco } from '@ecopages/core';
 ```
 
 > [!NOTE]
-> `createApp` is the recommended entrypoint over `EcopagesApp`.
+> Use `createApp()` from `@ecopages/core/create-app` as the application entrypoint.
 
 ### Runtime Escape Hatches
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.21",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -13,11 +13,11 @@
   "sideEffects": false,
   "repository": {
     "type": "git",
-    "url": "https://github.com/ecopages/ecopages.git",
+    "url": "git+https://github.com/ecopages/ecopages.git",
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.2",
+    "@ecopages/file-system": "0.2.0-beta.21",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",
@@ -45,11 +45,27 @@
       "types": "./src/route-renderer/orchestration/integration-renderer.d.ts",
       "default": "./src/route-renderer/orchestration/integration-renderer.js"
     },
+    "./route-renderer/string-markup-renderer": {
+      "types": "./src/route-renderer/orchestration/string-markup-renderer.d.ts",
+      "default": "./src/route-renderer/orchestration/string-markup-renderer.js"
+    },
+    "./route-renderer/route-renderer": {
+      "types": "./src/route-renderer/route-renderer.d.ts",
+      "default": "./src/route-renderer/route-renderer.js"
+    },
     "./route-renderer/component-render-context": {
       "import": "./src/route-renderer/orchestration/component-render-context.js",
       "types": "./src/route-renderer/orchestration/component-render-context.d.ts",
       "default": "./src/route-renderer/orchestration/component-render-context.js"
     },
+    "./route-renderer/orchestration/foreign-subtree-execution.service": {
+      "types": "./src/route-renderer/orchestration/foreign-subtree-execution.service.d.ts",
+      "default": "./src/route-renderer/orchestration/foreign-subtree-execution.service.js"
+    },
+    "./route-renderer/orchestration/document-shell-render.service": {
+      "types": "./src/route-renderer/orchestration/document-shell-render.service.d.ts",
+      "default": "./src/route-renderer/orchestration/document-shell-render.service.js"
+    },
     "./router/navigation-coordinator": {
       "types": "./src/router/client/navigation-coordinator.d.ts",
       "default": "./src/router/client/navigation-coordinator.js"
@@ -58,11 +74,31 @@
       "types": "./src/router/client/link-intent.d.ts",
       "default": "./src/router/client/link-intent.js"
     },
+    "./router/link-navigation-policy": {
+      "types": "./src/router/client/link-navigation-policy.d.ts",
+      "default": "./src/router/client/link-navigation-policy.js"
+    },
+    "./client/scroll": {
+      "types": "./src/client/scroll.d.ts",
+      "default": "./src/client/scroll.js"
+    },
+    "./client/view-transitions": {
+      "types": "./src/client/view-transitions.d.ts",
+      "default": "./src/client/view-transitions.js"
+    },
+    "./client/navigation-scripts": {
+      "types": "./src/client/navigation-scripts/index.d.ts",
+      "default": "./src/client/navigation-scripts/index.js"
+    },
     "./eco": {
       "browser": "./src/eco/eco.browser.js",
       "types": "./src/eco/eco.d.ts",
       "default": "./src/eco/eco.js"
     },
+    "./eco/page-layout-normalization": {
+      "types": "./src/eco/page-layout-normalization.d.ts",
+      "default": "./src/eco/page-layout-normalization.js"
+    },
     "./declarations": {
       "types": "./src/declarations.d.ts"
     },
@@ -93,6 +129,18 @@
       "types": "./src/dev/host-runtime.d.ts",
       "default": "./src/dev/host-runtime.js"
     },
+    "./dev/client-bridge-registry": {
+      "types": "./src/dev/client-bridge-registry.d.ts",
+      "default": "./src/dev/client-bridge-registry.js"
+    },
+    "./dev/hmr-manager-registry": {
+      "types": "./src/dev/hmr-manager-registry.d.ts",
+      "default": "./src/dev/hmr-manager-registry.js"
+    },
+    "./dev/dev-client-ownership": {
+      "types": "./src/dev/dev-client-ownership.d.ts",
+      "default": "./src/dev/dev-client-ownership.js"
+    },
     "./services/asset-processing-service": {
       "types": "./src/services/assets/asset-processing-service/index.d.ts",
       "default": "./src/services/assets/asset-processing-service/index.js"
@@ -105,6 +153,10 @@
       "types": "./src/plugins/integration-plugin.d.ts",
       "default": "./src/plugins/integration-plugin.js"
     },
+    "./plugins/define-integration": {
+      "types": "./src/plugins/define-integration.d.ts",
+      "default": "./src/plugins/define-integration.js"
+    },
     "./plugins/source-transform": {
       "types": "./src/plugins/source-transform.d.ts",
       "default": "./src/plugins/source-transform.js"
@@ -117,6 +169,26 @@
       "types": "./src/build/build-adapter.d.ts",
       "default": "./src/build/build-adapter.js"
     },
+    "./build/runtime-build-executor": {
+      "types": "./src/build/runtime-build-executor.d.ts",
+      "default": "./src/build/runtime-build-executor.js"
+    },
+    "./build/build-runtime": {
+      "types": "./src/build/build-runtime.d.ts",
+      "default": "./src/build/build-runtime.js"
+    },
+    "./build/build-contracts": {
+      "types": "./src/build/build-contracts.d.ts",
+      "default": "./src/build/build-contracts.js"
+    },
+    "./build/production-build-cache": {
+      "types": "./src/build/production-build-cache.d.ts",
+      "default": "./src/build/production-build-cache.js"
+    },
+    "./build/server-entry-build-cache": {
+      "types": "./src/build/server-entry-build-cache.d.ts",
+      "default": "./src/build/server-entry-build-cache.js"
+    },
     "./build/runtime-build-output-normalizer": {
       "types": "./src/build/runtime-build-output-normalizer.d.ts",
       "default": "./src/build/runtime-build-output-normalizer.js"
@@ -129,6 +201,10 @@
       "types": "./src/build/browser-runtime-plugin.d.ts",
       "default": "./src/build/browser-runtime-plugin.js"
     },
+    "./build/jsx-ownership-plugins": {
+      "types": "./src/build/jsx-ownership-plugins.d.ts",
+      "default": "./src/build/jsx-ownership-plugins.js"
+    },
     "./cache": {
       "types": "./src/cache/index.d.ts",
       "default": "./src/cache/index.js"
@@ -137,6 +213,10 @@
       "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
       "default": "./src/plugins/foreign-jsx-override-plugin.js"
     },
+    "./plugins/jsx-import-source.utils": {
+      "types": "./src/plugins/jsx-import-source.utils.d.ts",
+      "default": "./src/plugins/jsx-import-source.utils.js"
+    },
     "./html": {
       "import": "./src/utils/html.js",
       "default": "./src/utils/html.js",
@@ -174,11 +254,27 @@
       "types": "./src/route-renderer/orchestration/integration-renderer.d.ts",
       "default": "./src/route-renderer/orchestration/integration-renderer.js"
     },
+    "./route-renderer/string-markup-renderer.ts": {
+      "types": "./src/route-renderer/orchestration/string-markup-renderer.d.ts",
+      "default": "./src/route-renderer/orchestration/string-markup-renderer.js"
+    },
+    "./route-renderer/route-renderer.ts": {
+      "types": "./src/route-renderer/route-renderer.d.ts",
+      "default": "./src/route-renderer/route-renderer.js"
+    },
     "./route-renderer/component-render-context.ts": {
       "import": "./src/route-renderer/orchestration/component-render-context.js",
       "types": "./src/route-renderer/orchestration/component-render-context.d.ts",
       "default": "./src/route-renderer/orchestration/component-render-context.js"
     },
+    "./route-renderer/orchestration/foreign-subtree-execution.service.ts": {
+      "types": "./src/route-renderer/orchestration/foreign-subtree-execution.service.d.ts",
+      "default": "./src/route-renderer/orchestration/foreign-subtree-execution.service.js"
+    },
+    "./route-renderer/orchestration/document-shell-render.service.ts": {
+      "types": "./src/route-renderer/orchestration/document-shell-render.service.d.ts",
+      "default": "./src/route-renderer/orchestration/document-shell-render.service.js"
+    },
     "./router/navigation-coordinator.ts": {
       "types": "./src/router/client/navigation-coordinator.d.ts",
       "default": "./src/router/client/navigation-coordinator.js"
@@ -187,11 +283,31 @@
       "types": "./src/router/client/link-intent.d.ts",
       "default": "./src/router/client/link-intent.js"
     },
+    "./router/link-navigation-policy.ts": {
+      "types": "./src/router/client/link-navigation-policy.d.ts",
+      "default": "./src/router/client/link-navigation-policy.js"
+    },
+    "./client/scroll.ts": {
+      "types": "./src/client/scroll.d.ts",
+      "default": "./src/client/scroll.js"
+    },
+    "./client/view-transitions.ts": {
+      "types": "./src/client/view-transitions.d.ts",
+      "default": "./src/client/view-transitions.js"
+    },
+    "./client/navigation-scripts.ts": {
+      "types": "./src/client/navigation-scripts/index.d.ts",
+      "default": "./src/client/navigation-scripts/index.js"
+    },
     "./eco.ts": {
       "browser": "./src/eco/eco.browser.js",
       "types": "./src/eco/eco.d.ts",
       "default": "./src/eco/eco.js"
     },
+    "./eco/page-layout-normalization.ts": {
+      "types": "./src/eco/page-layout-normalization.d.ts",
+      "default": "./src/eco/page-layout-normalization.js"
+    },
     "./declarations.ts": {
       "types": "./src/declarations.d.ts"
     },
@@ -222,6 +338,18 @@
       "types": "./src/dev/host-runtime.d.ts",
       "default": "./src/dev/host-runtime.js"
     },
+    "./dev/client-bridge-registry.ts": {
+      "types": "./src/dev/client-bridge-registry.d.ts",
+      "default": "./src/dev/client-bridge-registry.js"
+    },
+    "./dev/hmr-manager-registry.ts": {
+      "types": "./src/dev/hmr-manager-registry.d.ts",
+      "default": "./src/dev/hmr-manager-registry.js"
+    },
+    "./dev/dev-client-ownership.ts": {
+      "types": "./src/dev/dev-client-ownership.d.ts",
+      "default": "./src/dev/dev-client-ownership.js"
+    },
     "./services/asset-processing-service.ts": {
       "types": "./src/services/assets/asset-processing-service/index.d.ts",
       "default": "./src/services/assets/asset-processing-service/index.js"
@@ -234,6 +362,10 @@
       "types": "./src/plugins/integration-plugin.d.ts",
       "default": "./src/plugins/integration-plugin.js"
     },
+    "./plugins/define-integration.ts": {
+      "types": "./src/plugins/define-integration.d.ts",
+      "default": "./src/plugins/define-integration.js"
+    },
     "./plugins/source-transform.ts": {
       "types": "./src/plugins/source-transform.d.ts",
       "default": "./src/plugins/source-transform.js"
@@ -246,6 +378,26 @@
       "types": "./src/build/build-adapter.d.ts",
       "default": "./src/build/build-adapter.js"
     },
+    "./build/runtime-build-executor.ts": {
+      "types": "./src/build/runtime-build-executor.d.ts",
+      "default": "./src/build/runtime-build-executor.js"
+    },
+    "./build/build-runtime.ts": {
+      "types": "./src/build/build-runtime.d.ts",
+      "default": "./src/build/build-runtime.js"
+    },
+    "./build/build-contracts.ts": {
+      "types": "./src/build/build-contracts.d.ts",
+      "default": "./src/build/build-contracts.js"
+    },
+    "./build/production-build-cache.ts": {
+      "types": "./src/build/production-build-cache.d.ts",
+      "default": "./src/build/production-build-cache.js"
+    },
+    "./build/server-entry-build-cache.ts": {
+      "types": "./src/build/server-entry-build-cache.d.ts",
+      "default": "./src/build/server-entry-build-cache.js"
+    },
     "./build/runtime-build-output-normalizer.ts": {
       "types": "./src/build/runtime-build-output-normalizer.d.ts",
       "default": "./src/build/runtime-build-output-normalizer.js"
@@ -258,6 +410,10 @@
       "types": "./src/build/browser-runtime-plugin.d.ts",
       "default": "./src/build/browser-runtime-plugin.js"
     },
+    "./build/jsx-ownership-plugins.ts": {
+      "types": "./src/build/jsx-ownership-plugins.d.ts",
+      "default": "./src/build/jsx-ownership-plugins.js"
+    },
     "./cache.ts": {
       "types": "./src/cache/index.d.ts",
       "default": "./src/cache/index.js"
@@ -266,6 +422,10 @@
       "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
       "default": "./src/plugins/foreign-jsx-override-plugin.js"
     },
+    "./plugins/jsx-import-source.utils.ts": {
+      "types": "./src/plugins/jsx-import-source.utils.d.ts",
+      "default": "./src/plugins/jsx-import-source.utils.js"
+    },
     "./html.ts": {
       "import": "./src/utils/html.js",
       "default": "./src/utils/html.js",

package/src/adapters/abstract/application-adapter.d.ts

@@ -9,6 +9,8 @@
 import type { SourceModuleLoader } from '../../services/module-loading/module-loading-types.js';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { ApiHandler, ApiHandlerContext, ErrorHandler, Middleware, RouteOptions, StaticRoute, ViewLoader } from '../../types/public-types.js';
+import type { EcopagesWebSocketHandler } from '../../types/public-types.js';
+import { type EcopagesRuntimeLabel } from '../../dev/runtime-server-started-message.js';
 import { type ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
 /**
  * Runtime bootstrap options layered on top of the app config.
@@ -25,6 +27,21 @@ export interface ApplicationRuntimeOptions {
      * adapter auto-detects a host module loader from the global scope.
      */
     embedded?: boolean;
+    /**
+     * When true, full-page reload signaling is owned by the host dev server
+     * (for example Vite's `full-reload` websocket event) instead of the Ecopages
+     * client bridge.
+     *
+     * @deprecated Prefer `devClientOwner: 'host'`.
+     */
+    delegateBrowserReloadToHost?: boolean;
+    /**
+     * Selects which layer injects browser dev-client bootstrap (HMR runtime, reload).
+     *
+     * `host` disables core injection and reload signaling so embedded hosts like
+     * Vite own the full dev-client surface.
+     */
+    devClientOwner?: 'core' | 'host';
     /**
      * Explicit source module loader for request-time imports.
      *
@@ -33,6 +50,18 @@ export interface ApplicationRuntimeOptions {
      */
     hostModuleLoader?: SourceModuleLoader;
 }
+export interface AppStartInfo {
+    origin: string;
+}
+export type OnAppStartCallback = (info: AppStartInfo) => void;
+/** @deprecated Use {@link AppStartInfo}. */
+export type ApplicationListeningInfo = AppStartInfo;
+/** @deprecated Use {@link OnAppStartCallback}. */
+export type StartCallback = OnAppStartCallback;
+/** @deprecated Use {@link OnAppStartCallback}. */
+export type ListenCallback = OnAppStartCallback;
+/** @deprecated Use {@link OnAppStartCallback}. */
+export type ApplicationListeningCallback = OnAppStartCallback;
 /**
  * Configuration options for application adapters
  */
@@ -49,8 +78,12 @@ export interface ApplicationAdapterOptions {
 /**
  * Common interface for application adapters
  */
-export interface ApplicationAdapter<T = any> {
-    start(): Promise<T | void>;
+export interface ApplicationAdapter<T = any> extends AsyncDisposable {
+    /** Boot the server. Pass a callback to run when the runtime is ready (optional). */
+    start(onAppStart?: OnAppStartCallback): Promise<T | void>;
+    /** Invoked by embedded hosts once the app can take traffic. */
+    handleListening(origin: string): void;
+    stop(force?: boolean): Promise<void>;
 }
 /**
  * Handler function type for route handlers
@@ -72,7 +105,14 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
     protected apiHandlers: ApiHandler[];
     protected staticRoutes: StaticRoute[];
     protected errorHandler?: ErrorHandler;
-    constructor(options: TOptions);
+    /**
+     * App-level WebSocket handlers keyed by URL path pattern (e.g. '/ws/chat/:id').
+     * Both Bun and Node adapters read this map to register upgrade routes.
+     */
+    protected websocketHandlers: Map<string, EcopagesWebSocketHandler<any, any>>;
+    private onAppStartCallback?;
+    protected readonly runtimeLabel: EcopagesRuntimeLabel;
+    constructor(options: TOptions, runtimeLabel: EcopagesRuntimeLabel);
     private clearDistFolder;
     /**
      * Register a GET route handler.
@@ -160,6 +200,46 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
      * Get all registered static routes
      */
     getStaticRoutes(): StaticRoute[];
+    /**
+     * Register a WebSocket handler for the given path pattern.
+     *
+     * The runtime adapter handles the HTTP→WebSocket upgrade for this path
+     * and routes lifecycle events to `handler`.
+     *
+     * Supports dynamic segments via `:param` syntax. The handler receives
+     * typed `params` and `search` fields, and a typed `context` produced by
+     * the optional `context()` factory.
+     *
+     * One pattern registration matches infinite path variations. For example,
+     * `app.websocket('/ws/chat/:roomId', handler)` matches `/ws/chat/abc`,
+     * `/ws/chat/xyz`, etc. Each connection receives its own `params.roomId`.
+     *
+     * Works across both Bun and Node runtimes — no runtime-specific imports needed.
+     *
+     * @example
+     * ```typescript
+     * app.websocket<ChatContext, { roomId: string }>('/ws/chat/:roomId', {
+     *   async context({ params, search }) {
+     *     return { username: search.username ?? 'anonymous', roomId: params.roomId };
+     *   },
+     *   onConnect(socket) {
+     *     socket.send(`Welcome to room ${socket.context.roomId}`);
+     *   },
+     *   onMessage(socket, message) {
+     *     if (message.kind === 'text') {
+     *       socket.send(message.text);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    websocket<TContext = unknown, TParams extends Record<string, string> = Record<string, string>>(path: string, handler: EcopagesWebSocketHandler<TContext, TParams>): this;
+    /**
+     * Get the registered WebSocket handlers map.
+     *
+     * @returns The map of WebSocket route patterns to handlers
+     */
+    getWebsocketHandlers(): Map<string, EcopagesWebSocketHandler<any, any>>;
     /**
      * Register a global error handler for all routes.
      * Useful for logging, monitoring integration, and custom error formatting.
@@ -182,9 +262,28 @@ export declare abstract class AbstractApplicationAdapter<TOptions extends Applic
      */
     protected abstract initializeServerAdapter(): Promise<any>;
     /**
-     * Start the application server
+     * Boot the server. When `onAppStart` is passed, it runs once the runtime can take traffic.
+     * Embedded apps only register the callback — the host (for example Vite) boots the port.
+     */
+    start(onAppStart?: OnAppStartCallback): Promise<TServer | void>;
+    /** Runtime-specific server boot (dev, preview, build). */
+    protected abstract bootServer(): Promise<TServer | void>;
+    protected logServerStarted(origin: string): void;
+    /**
+     * Invoked by embedded hosts (for example Vite) once the app can take traffic.
+     */
+    handleListening(origin: string): void;
+    protected notifyListening(origin: string): void;
+    /**
+     * Stops the application server and releases runtime resources.
+     *
+     * @remarks
+     * Subclasses override this to shut down bound servers, watchers, and other
+     * dev-time resources. The default implementation is a no-op so embedded
+     * adapters that never call `start()` can still be used with `await using`.
      */
-    abstract start(): Promise<TServer | void>;
+    stop(_force?: boolean): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Handles a standard Web request without requiring a bound network server.
      * This is the primary interoperability surface for embedding Ecopages inside

package/src/adapters/abstract/application-adapter.js

@@ -6,6 +6,9 @@ import {
 import { getHostModuleLoader } from "../../services/module-loading/host-module-loader-registry.js";
 import { invariant } from "../../utils/invariant.js";
 import { fileSystem } from "@ecopages/file-system";
+import {
+  formatRuntimeServerStartedMessage
+} from "../../dev/runtime-server-started-message.js";
 import { parseCliArgs } from "../../utils/parse-cli-args.js";
 class AbstractApplicationAdapter {
   appConfig;
@@ -15,10 +18,24 @@ class AbstractApplicationAdapter {
   apiHandlers = [];
   staticRoutes = [];
   errorHandler;
-  constructor(options) {
+  /**
+   * App-level WebSocket handlers keyed by URL path pattern (e.g. '/ws/chat/:id').
+   * Both Bun and Node adapters read this map to register upgrade routes.
+   */
+  websocketHandlers = /* @__PURE__ */ new Map();
+  onAppStartCallback;
+  runtimeLabel;
+  constructor(options, runtimeLabel) {
+    this.runtimeLabel = runtimeLabel;
     this.appConfig = options.appConfig;
     this.serverOptions = options.serverOptions || {};
     this.runtimeOptions = options.runtime ?? {};
+    if (options.runtime) {
+      this.appConfig.runtime = {
+        ...this.appConfig.runtime ?? {},
+        ...options.runtime
+      };
+    }
     this.cliArgs = parseCliArgs({ embeddedRuntime: this.runtimeOptions.embedded });
     const hostModuleLoader = this.runtimeOptions.hostModuleLoader ?? (this.runtimeOptions.embedded ? getHostModuleLoader() : void 0);
     if (hostModuleLoader) {
@@ -93,6 +110,71 @@ class AbstractApplicationAdapter {
   getStaticRoutes() {
     return this.staticRoutes;
   }
+  /**
+   * Register a WebSocket handler for the given path pattern.
+   *
+   * The runtime adapter handles the HTTP→WebSocket upgrade for this path
+   * and routes lifecycle events to `handler`.
+   *
+   * Supports dynamic segments via `:param` syntax. The handler receives
+   * typed `params` and `search` fields, and a typed `context` produced by
+   * the optional `context()` factory.
+   *
+   * One pattern registration matches infinite path variations. For example,
+   * `app.websocket('/ws/chat/:roomId', handler)` matches `/ws/chat/abc`,
+   * `/ws/chat/xyz`, etc. Each connection receives its own `params.roomId`.
+   *
+   * Works across both Bun and Node runtimes — no runtime-specific imports needed.
+   *
+   * @example
+   * ```typescript
+   * app.websocket<ChatContext, { roomId: string }>('/ws/chat/:roomId', {
+   *   async context({ params, search }) {
+   *     return { username: search.username ?? 'anonymous', roomId: params.roomId };
+   *   },
+   *   onConnect(socket) {
+   *     socket.send(`Welcome to room ${socket.context.roomId}`);
+   *   },
+   *   onMessage(socket, message) {
+   *     if (message.kind === 'text') {
+   *       socket.send(message.text);
+   *     }
+   *   },
+   * });
+   * ```
+   */
+  websocket(path, handler) {
+    invariant(
+      typeof path === "string" && path.startsWith("/"),
+      `app.websocket(): path must be a string starting with "/", got "${path}".`
+    );
+    const segments = path.split("/").filter(Boolean);
+    const paramNames = /* @__PURE__ */ new Set();
+    for (const segment of segments) {
+      if (segment.startsWith(":")) {
+        const paramName = segment.slice(1);
+        invariant(
+          paramName.length > 0,
+          `app.websocket(): invalid pattern "${path}" \u2014 empty param name in segment ":${paramName}".`
+        );
+        invariant(
+          !paramNames.has(paramName),
+          `app.websocket(): invalid pattern "${path}" \u2014 duplicate param name ":${paramName}".`
+        );
+        paramNames.add(paramName);
+      }
+    }
+    this.websocketHandlers.set(path, handler);
+    return this;
+  }
+  /**
+   * Get the registered WebSocket handlers map.
+   *
+   * @returns The map of WebSocket route patterns to handlers
+   */
+  getWebsocketHandlers() {
+    return this.websocketHandlers;
+  }
   /**
    * Register a global error handler for all routes.
    * Useful for logging, monitoring integration, and custom error formatting.
@@ -115,6 +197,48 @@ class AbstractApplicationAdapter {
   getErrorHandler() {
     return this.errorHandler;
   }
+  /**
+   * Boot the server. When `onAppStart` is passed, it runs once the runtime can take traffic.
+   * Embedded apps only register the callback — the host (for example Vite) boots the port.
+   */
+  async start(onAppStart) {
+    if (onAppStart) {
+      this.onAppStartCallback = onAppStart;
+    }
+    if (this.runtimeOptions.embedded) {
+      return;
+    }
+    return this.bootServer();
+  }
+  logServerStarted(origin) {
+    appLogger.info(formatRuntimeServerStartedMessage(this.runtimeLabel, origin));
+  }
+  /**
+   * Invoked by embedded hosts (for example Vite) once the app can take traffic.
+   */
+  handleListening(origin) {
+    this.notifyListening(origin);
+  }
+  notifyListening(origin) {
+    const normalizedOrigin = origin.replace(/\/$/, "");
+    if (!this.onAppStartCallback) {
+      this.logServerStarted(normalizedOrigin);
+    }
+    this.onAppStartCallback?.({ origin: normalizedOrigin });
+  }
+  /**
+   * Stops the application server and releases runtime resources.
+   *
+   * @remarks
+   * Subclasses override this to shut down bound servers, watchers, and other
+   * dev-time resources. The default implementation is a no-op so embedded
+   * adapters that never call `start()` can still be used with `await using`.
+   */
+  async stop(_force = true) {
+  }
+  async [Symbol.asyncDispose]() {
+    await this.stop(true);
+  }
 }
 export {
   AbstractApplicationAdapter

package/src/adapters/abstract/server-adapter.d.ts

@@ -31,7 +31,10 @@ export interface ServerAdapterResult {
     }) => any;
     buildStatic: (options?: {
         preview?: boolean;
-    }) => Promise<void>;
+        force?: boolean;
+    }) => Promise<string | undefined>;
+    servePreviewOnly: () => Promise<string | undefined>;
+    dispose(): Promise<void>;
 }
 /**
  * Abstract base class for server adapters across different runtimes
@@ -57,7 +60,8 @@ export declare abstract class AbstractServerAdapter<TOptions extends ServerAdapt
      */
     abstract buildStatic(options?: {
         preview?: boolean;
-    }): Promise<void>;
+        force?: boolean;
+    }): Promise<string | undefined>;
     /**
      * Factory method to create a server adapter with runtime-specific functionality
      */