@b9g/platform 0.1.13 → 0.1.14-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/platform",
-  "version": "0.1.13",
+  "version": "0.1.14-beta.0",
   "description": "The portable meta-framework built on web standards.",
   "keywords": [
     "service-worker",
@@ -20,15 +20,15 @@
   "dependencies": {
     "@b9g/async-context": "^0.2.0-beta.0",
     "@b9g/cache": "^0.2.0-beta.0",
-    "@b9g/filesystem": "^0.1.7",
+    "@b9g/filesystem": "^0.1.8",
     "@b9g/zen": "^0.1.6",
     "@logtape/logtape": "^1.2.0"
   },
   "devDependencies": {
     "@b9g/libuild": "^0.1.20",
     "@b9g/node-webworker": "^0.2.0-beta.1",
-    "@b9g/platform-bun": "^0.1.10",
-    "@b9g/platform-node": "^0.1.12"
+    "@b9g/platform-bun": "^0.1.12-beta.0",
+    "@b9g/platform-node": "^0.1.14-beta.0"
   },
   "peerDependencies": {
     "@logtape/file": "^1.0.0",

package/src/index.d.ts

@@ -8,11 +8,10 @@
  *
  * This module contains:
  * - Platform interface and base classes
- * - SingleThreadedRuntime for main-thread execution
  * - ServiceWorkerPool for multi-worker execution
  */
 import type { DirectoryStorage } from "@b9g/filesystem";
-import { CustomLoggerStorage, type LoggerStorage, type DatabaseStorage } from "./runtime.js";
+import { CustomLoggerStorage, type LoggerStorage } from "./runtime.js";
 export { validateConfig, ConfigValidationError } from "./config.js";
 /**
  * Platform configuration
@@ -28,6 +27,8 @@ export interface ServerOptions {
     port?: number;
     /** Host to bind to */
     host?: string;
+    /** Enable SO_REUSEPORT for multi-worker deployments (Bun only) */
+    reusePort?: boolean;
 }
 /**
  * Request handler function (Web Fetch API compatible)
@@ -80,21 +81,14 @@ export interface ServiceWorkerInstance {
     dispose(): Promise<void>;
 }
 /**
- * Options for getEntryWrapper()
+ * Production entry points returned by getProductionEntryPoints().
+ * Each key is the output filename (without .js), value is the code.
+ *
+ * Examples:
+ * - Cloudflare: { "worker": "<code>" } - single worker file
+ * - Node/Bun: { "index": "<supervisor>", "worker": "<worker>" } - two files
  */
-export interface EntryWrapperOptions {
-    /**
-     * Type of entry wrapper to generate:
-     * - "production": Production server entry (default) - runs the server directly
-     * - "worker": Worker entry for ServiceWorkerPool - sets up runtime and message loop
-     */
-    type?: "production" | "worker";
-    /**
-     * Output directory for the build. Used to generate absolute paths for
-     * directory defaults (server, public). Required for "worker" type.
-     */
-    outDir?: string;
-}
+export type ProductionEntryPoints = Record<string, string>;
 /**
  * ESBuild configuration subset that platforms can customize
  */
@@ -107,16 +101,6 @@ export interface PlatformESBuildConfig {
     external?: string[];
     /** Compile-time defines */
     define?: Record<string, string>;
-    /**
-     * Whether the entry wrapper imports user code inline (bundled together)
-     * or references it as a separate file (loaded at runtime).
-     *
-     * - true: User code is imported inline (e.g., Cloudflare: `import "user-entry"`)
-     * - false: User code is loaded separately (e.g., Node/Bun: `loadServiceWorker("./server.js")`)
-     *
-     * Default: false (separate build)
-     */
-    bundlesUserCodeInline?: boolean;
 }
 /**
  * Default resource configuration for a named resource (cache, directory, etc.)
@@ -141,6 +125,19 @@ export interface PlatformDefaults {
     /** Default cache configuration (e.g., memory cache) */
     caches?: Record<string, ResourceDefault>;
 }
+/**
+ * Extended ServiceWorkerContainer with internal methods for hot reload
+ */
+export interface ShovelServiceWorkerContainer extends ServiceWorkerContainer {
+    /** Internal: Get the worker pool for request handling */
+    readonly pool?: {
+        handleRequest(request: Request): Promise<Response>;
+    };
+    /** Internal: Terminate all workers */
+    terminate(): Promise<void>;
+    /** Internal: Reload workers (for hot reload) */
+    reloadWorkers(entrypoint: string): Promise<void>;
+}
 /**
  * Platform interface - ServiceWorker entrypoint loader for JavaScript runtimes
  *
@@ -152,29 +149,38 @@ export interface Platform {
      */
     readonly name: string;
     /**
-     * Load and run a ServiceWorker-style entrypoint
-     * This is where all the platform-specific complexity lives
+     * ServiceWorkerContainer for managing registrations (Node/Bun only)
+     * Similar to navigator.serviceWorker in browsers
+     */
+    readonly serviceWorker: ShovelServiceWorkerContainer;
+    /**
+     * Start HTTP server and route requests to ServiceWorker (Node/Bun only)
+     * Must call serviceWorker.register() first
      */
-    loadServiceWorker(entrypoint: string, options?: ServiceWorkerOptions): Promise<ServiceWorkerInstance>;
+    listen(): Promise<Server>;
+    /**
+     * Close server and terminate workers (Node/Bun only)
+     */
+    close(): Promise<void>;
     /**
      * SUPPORTING UTILITY - Create server instance for this platform
      */
     createServer(handler: Handler, options?: ServerOptions): Server;
     /**
-     * BUILD SUPPORT - Get virtual entry wrapper template for user code
+     * BUILD SUPPORT - Get production entry points for bundling
+     *
+     * Returns a map of output filenames to their source code.
+     * The build system creates one output file per entry point.
      *
-     * Returns a JavaScript/TypeScript string that:
-     * 1. Initializes platform-specific runtime (polyfills, globals)
-     * 2. Imports the user's entrypoint
-     * 3. Exports any required handlers (e.g., ES module export for Cloudflare)
+     * Platform determines the structure:
+     * - Cloudflare: { "worker": "<code>" } - single worker file
+     * - Node/Bun: { "index": "<supervisor>", "worker": "<runtime + user code>" }
      *
-     * The CLI uses this to create a virtual entry point for bundling.
-     * Every platform must provide a wrapper - there is no "raw user code" mode.
+     * The user's entrypoint code is statically imported into the appropriate file.
      *
-     * @param entryPath - Absolute path to user's entrypoint file
-     * @param options - Additional options
+     * @param userEntryPath - Path to user's entrypoint (will be imported)
      */
-    getEntryWrapper(entryPath: string, options?: EntryWrapperOptions): string;
+    getProductionEntryPoints(userEntryPath: string): ProductionEntryPoints;
     /**
      * BUILD SUPPORT - Get platform-specific esbuild configuration
      *
@@ -205,6 +211,15 @@ export interface Platform {
      * Uses platform-specific defaults, overridable via shovel.json config
      */
     createLoggers(): Promise<LoggerStorage>;
+    /**
+     * Dispose of platform resources (worker pools, connections, etc.)
+     */
+    dispose(): Promise<void>;
+    /**
+     * HOT RELOAD - Reload workers with a new entrypoint (development only)
+     * Optional - only Node and Bun platforms implement this
+     */
+    reloadWorkers?(entrypoint: string): Promise<void>;
 }
 /**
  * Platform registry - internal implementation
@@ -253,7 +268,7 @@ export declare function resolvePlatform(options: {
 /**
  * Create platform instance based on name
  */
-export declare function createPlatform(platformName: string, options?: any): Promise<any>;
+export declare function createPlatform(platformName: string, options?: any): Promise<Platform>;
 /**
  * Base platform class with shared adapter loading logic
  * Platform implementations extend this and provide platform-specific methods
@@ -262,13 +277,15 @@ export declare abstract class BasePlatform implements Platform {
     config: PlatformConfig;
     constructor(config?: PlatformConfig);
     abstract readonly name: string;
-    abstract loadServiceWorker(entrypoint: string, options?: any): Promise<any>;
+    abstract readonly serviceWorker: ShovelServiceWorkerContainer;
+    abstract listen(): Promise<Server>;
+    abstract close(): Promise<void>;
     abstract createServer(handler: any, options?: any): any;
     /**
-     * Get virtual entry wrapper template for user code
-     * Subclasses must override to provide platform-specific wrappers
+     * Get production entry points for bundling
+     * Subclasses must override to provide platform-specific entry points
      */
-    abstract getEntryWrapper(entryPath: string, options?: EntryWrapperOptions): string;
+    abstract getProductionEntryPoints(userEntryPath: string): ProductionEntryPoints;
     /**
      * Get platform-specific esbuild configuration
      * Subclasses should override to provide platform-specific config
@@ -294,7 +311,23 @@ export declare abstract class BasePlatform implements Platform {
      * Subclasses must override to provide platform-specific implementation
      */
     abstract createLoggers(): Promise<LoggerStorage>;
+    /**
+     * Dispose of platform resources
+     * Subclasses should override to clean up worker pools, connections, etc.
+     */
+    dispose(): Promise<void>;
 }
+/**
+ * Merge platform defaults with user config
+ *
+ * Deep merges each entry so user can override specific options without
+ * losing the platform's default implementation class.
+ *
+ * @param defaults - Platform's runtime defaults (with actual class refs)
+ * @param userConfig - User's config from shovel.json (may be partial)
+ * @returns Merged config with all entries
+ */
+export declare function mergeConfigWithDefaults(defaults: Record<string, Record<string, unknown>>, userConfig: Record<string, Record<string, unknown>> | undefined): Record<string, Record<string, unknown>>;
 /**
  * Global platform registry
  */
@@ -328,52 +361,6 @@ export interface ServiceWorkerRuntime {
     readonly workerCount: number;
     readonly ready: boolean;
 }
-export interface SingleThreadedRuntimeOptions {
-    /** Cache storage for the runtime */
-    caches: CacheStorage;
-    /** Directory storage for the runtime */
-    directories: DirectoryStorage;
-    /** Database storage for the runtime */
-    databases?: DatabaseStorage;
-    /** Logger storage for the runtime */
-    loggers: LoggerStorage;
-}
-/**
- * Single-threaded ServiceWorker runtime
- *
- * Runs ServiceWorker code directly in the main thread.
- * Implements ServiceWorkerRuntime interface for interchangeability with ServiceWorkerPool.
- */
-export declare class SingleThreadedRuntime implements ServiceWorkerRuntime {
-    #private;
-    constructor(options: SingleThreadedRuntimeOptions);
-    /**
-     * Initialize the runtime (install ServiceWorker globals)
-     */
-    init(): Promise<void>;
-    /**
-     * Load (or reload) a ServiceWorker entrypoint
-     * @param entrypoint - Path to the entrypoint file (content-hashed filename)
-     */
-    load(entrypoint: string): Promise<void>;
-    /**
-     * Handle an HTTP request
-     * This is the key method - direct call, no postMessage!
-     */
-    handleRequest(request: Request): Promise<Response>;
-    /**
-     * Graceful shutdown
-     */
-    terminate(): Promise<void>;
-    /**
-     * Get the number of workers (always 1 for single-threaded)
-     */
-    get workerCount(): number;
-    /**
-     * Check if ready to handle requests
-     */
-    get ready(): boolean;
-}
 /**
  * Worker pool options
  */
@@ -384,6 +371,8 @@ export interface WorkerPoolOptions {
     requestTimeout?: number;
     /** Working directory for file resolution */
     cwd?: string;
+    /** Custom worker factory (if not provided, uses createWebWorker) */
+    createWorker?: (entrypoint: string) => Worker | Promise<Worker>;
 }
 export interface WorkerMessage {
     type: string;

package/src/index.js

@@ -1,12 +1,7 @@
 /// <reference types="./index.d.ts" />
 // src/index.ts
 import { getLogger } from "@logtape/logtape";
-import {
-  ServiceWorkerGlobals,
-  ShovelServiceWorkerRegistration,
-  ShovelFetchEvent,
-  CustomLoggerStorage
-} from "./runtime.js";
+import { CustomLoggerStorage } from "./runtime.js";
 import { validateConfig, ConfigValidationError } from "./config.js";
 import {
   CustomDatabaseStorage,
@@ -85,7 +80,22 @@ var BasePlatform = class {
   constructor(config = {}) {
     this.config = config;
   }
+  /**
+   * Dispose of platform resources
+   * Subclasses should override to clean up worker pools, connections, etc.
+   */
+  async dispose() {
+  }
 };
+function mergeConfigWithDefaults(defaults, userConfig) {
+  const user = userConfig ?? {};
+  const allNames = /* @__PURE__ */ new Set([...Object.keys(defaults), ...Object.keys(user)]);
+  const merged = {};
+  for (const name of allNames) {
+    merged[name] = { ...defaults[name], ...user[name] };
+  }
+  return merged;
+}
 var DefaultPlatformRegistry = class {
   #platforms;
   constructor() {
@@ -142,86 +152,6 @@ async function getPlatformAsync(name) {
   }
   return platform;
 }
-var SingleThreadedRuntime = class {
-  #registration;
-  #scope;
-  #ready;
-  #entrypoint;
-  constructor(options) {
-    this.#ready = false;
-    this.#registration = new ShovelServiceWorkerRegistration();
-    this.#scope = new ServiceWorkerGlobals({
-      registration: this.#registration,
-      caches: options.caches,
-      directories: options.directories,
-      databases: options.databases,
-      loggers: options.loggers
-    });
-    logger.debug("SingleThreadedRuntime created");
-  }
-  /**
-   * Initialize the runtime (install ServiceWorker globals)
-   */
-  async init() {
-    this.#scope.install();
-    logger.debug("SingleThreadedRuntime initialized - globals installed");
-  }
-  /**
-   * Load (or reload) a ServiceWorker entrypoint
-   * @param entrypoint - Path to the entrypoint file (content-hashed filename)
-   */
-  async load(entrypoint) {
-    const isReload = this.#entrypoint !== void 0;
-    if (isReload) {
-      logger.debug("Reloading ServiceWorker", {
-        oldEntrypoint: this.#entrypoint,
-        newEntrypoint: entrypoint
-      });
-      this.#registration._serviceWorker._setState("parsed");
-    } else {
-      logger.debug("Loading ServiceWorker entrypoint", { entrypoint });
-    }
-    this.#entrypoint = entrypoint;
-    this.#ready = false;
-    await import(entrypoint);
-    await this.#registration.install();
-    await this.#registration.activate();
-    this.#ready = true;
-    logger.debug("ServiceWorker loaded and activated", { entrypoint });
-  }
-  /**
-   * Handle an HTTP request
-   * This is the key method - direct call, no postMessage!
-   */
-  async handleRequest(request) {
-    if (!this.#ready) {
-      throw new Error(
-        "SingleThreadedRuntime not ready - ServiceWorker not loaded"
-      );
-    }
-    const event = new ShovelFetchEvent(request);
-    return this.#registration.handleRequest(event);
-  }
-  /**
-   * Graceful shutdown
-   */
-  async terminate() {
-    this.#ready = false;
-    logger.debug("SingleThreadedRuntime terminated");
-  }
-  /**
-   * Get the number of workers (always 1 for single-threaded)
-   */
-  get workerCount() {
-    return 1;
-  }
-  /**
-   * Check if ready to handle requests
-   */
-  get ready() {
-    return this.#ready;
-  }
-};
 async function createWebWorker(workerScript) {
   if (typeof Worker !== "undefined") {
     return new Worker(workerScript, { type: "module" });
@@ -306,7 +236,7 @@ var ServiceWorkerPool = class {
    * The bundle self-initializes and sends "ready" when done
    */
   async #createWorker(entrypoint) {
-    const worker = await createWebWorker(entrypoint);
+    const worker = this.#options.createWorker ? await this.#options.createWorker(entrypoint) : await createWebWorker(entrypoint);
     const readyPromise = new Promise((resolve, reject) => {
       const timeoutId = setTimeout(() => {
         this.#pendingWorkerReady.delete(worker);
@@ -595,7 +525,6 @@ export {
   CustomDatabaseStorage,
   CustomLoggerStorage,
   ServiceWorkerPool,
-  SingleThreadedRuntime,
   createDatabaseFactory,
   createPlatform,
   detectDeploymentPlatform,
@@ -603,6 +532,7 @@ export {
   detectRuntime,
   getPlatform,
   getPlatformAsync,
+  mergeConfigWithDefaults,
   platformRegistry,
   resolvePlatform,
   validateConfig

package/src/runtime.d.ts

@@ -354,6 +354,14 @@ export declare class ShovelNavigationPreloadManager implements NavigationPreload
     }>;
     setHeaderValue(_value: string): Promise<void>;
 }
+/** @internal Symbol for accessing the internal ServiceWorker instance */
+export declare const kServiceWorker: unique symbol;
+/** @internal Symbol for dispatching the install lifecycle event */
+export declare const kDispatchInstall: unique symbol;
+/** @internal Symbol for dispatching the activate lifecycle event */
+export declare const kDispatchActivate: unique symbol;
+/** @internal Symbol for handling fetch requests */
+declare const kHandleRequest: unique symbol;
 /**
  * ShovelServiceWorkerRegistration - Internal implementation of ServiceWorkerRegistration
  * This is also the Shovel ServiceWorker runtime - they are unified into one class
@@ -363,7 +371,7 @@ export declare class ShovelServiceWorkerRegistration extends EventTarget impleme
     readonly scope: string;
     readonly updateViaCache: "imports" | "all" | "none";
     readonly navigationPreload: NavigationPreloadManager;
-    _serviceWorker: ShovelServiceWorker;
+    [kServiceWorker]: ShovelServiceWorker;
     readonly cookies: any;
     readonly pushManager: any;
     onupdatefound: ((ev: Event) => any) | null;
@@ -377,27 +385,71 @@ export declare class ShovelServiceWorkerRegistration extends EventTarget impleme
     unregister(): Promise<boolean>;
     update(): Promise<ServiceWorkerRegistration>;
     /**
-     * Install the ServiceWorker (Shovel extension)
+     * Dispatch the install lifecycle event
+     * @internal Use runLifecycle() instead of calling this directly
      */
-    install(): Promise<void>;
+    [kDispatchInstall](): Promise<void>;
     /**
-     * Activate the ServiceWorker (Shovel extension)
+     * Dispatch the activate lifecycle event
+     * @internal Use runLifecycle() instead of calling this directly
      */
-    activate(): Promise<void>;
+    [kDispatchActivate](): Promise<void>;
     /**
-     * Handle a fetch request (Shovel extension)
+     * Handle a fetch request
+     * @internal Use the kHandleRequest symbol to access this method
      *
      * Platforms create a ShovelFetchEvent (or subclass) with platform-specific
      * properties and hooks, then pass it to this method for dispatching.
      *
      * @param event - The fetch event to handle (created by platform adapter)
      */
-    handleRequest(event: ShovelFetchEvent): Promise<Response>;
+    [kHandleRequest](event: ShovelFetchEvent): Promise<Response>;
     /**
      * Check if ready to handle requests (Shovel extension)
      */
     get ready(): boolean;
 }
+/**
+ * Run ServiceWorker lifecycle events on a registration.
+ *
+ * This is the proper way to trigger lifecycle events in Shovel's server-side runtime.
+ * Unlike browsers where lifecycle is automatic, server-side code must explicitly
+ * trigger these events after registering event handlers.
+ *
+ * @param registration - The ServiceWorkerRegistration to run lifecycle on
+ * @param stage - Which lifecycle stage to run:
+ *   - "install": Run only the install event
+ *   - "activate": Run install then activate (default)
+ *
+ * @example
+ * ```typescript
+ * const {registration} = await initWorkerRuntime({config});
+ * await import("./server.js"); // Register event handlers
+ * await runLifecycle(registration); // Runs install + activate
+ * ```
+ */
+export declare function runLifecycle(registration: ShovelServiceWorkerRegistration, stage?: "install" | "activate"): Promise<void>;
+/**
+ * Dispatch a fetch request to a ServiceWorker registration.
+ *
+ * This is the proper way to dispatch requests in Shovel's server-side runtime.
+ * Platforms should use this function rather than accessing internal methods directly.
+ *
+ * @param registration - The ServiceWorkerRegistration to dispatch to
+ * @param requestOrEvent - The Request to dispatch, or a pre-constructed ShovelFetchEvent
+ * @returns The Response from the ServiceWorker
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with a Request
+ * const response = await dispatchRequest(registration, request);
+ *
+ * // Platform-specific usage with a custom FetchEvent subclass
+ * const event = new CloudflareFetchEvent(request, {env, platformWaitUntil});
+ * const response = await dispatchRequest(registration, event);
+ * ```
+ */
+export declare function dispatchRequest(registration: ShovelServiceWorkerRegistration, requestOrEvent: Request | ShovelFetchEvent): Promise<Response>;
 /**
  * ShovelServiceWorkerContainer - Internal implementation of ServiceWorkerContainer
  * This is the registry that manages multiple ServiceWorkerRegistrations by scope
@@ -431,10 +483,6 @@ export declare class ShovelServiceWorkerContainer extends EventTarget implements
      * Unregister a ServiceWorker registration
      */
     unregister(scope: string): Promise<boolean>;
-    /**
-     * Route a request to the appropriate registration based on scope matching
-     */
-    handleRequest(request: Request): Promise<Response | null>;
     /**
      * Install and activate all registrations
      */
@@ -759,16 +807,15 @@ export interface InitWorkerRuntimeResult {
  * @example
  * ```typescript
  * import {config} from "shovel:config";
- * import {initWorkerRuntime, startWorkerMessageLoop} from "@b9g/platform/runtime";
+ * import {initWorkerRuntime, runLifecycle, startWorkerMessageLoop} from "@b9g/platform/runtime";
  *
  * const {registration} = await initWorkerRuntime({config});
  *
  * // Import user code (registers event handlers)
- * import "./server.js";
+ * await import("./server.js");
  *
  * // Run lifecycle and start message loop
- * await registration.install();
- * await registration.activate();
+ * await runLifecycle(registration);
  * startWorkerMessageLoop(registration);
  * ```
  */

package/src/runtime.js

@@ -568,12 +568,16 @@ var ShovelNavigationPreloadManager = class {
   async setHeaderValue(_value) {
   }
 };
+var kServiceWorker = /* @__PURE__ */ Symbol("serviceWorker");
+var kDispatchInstall = /* @__PURE__ */ Symbol("dispatchInstall");
+var kDispatchActivate = /* @__PURE__ */ Symbol("dispatchActivate");
+var kHandleRequest = /* @__PURE__ */ Symbol("handleRequest");
 var ShovelServiceWorkerRegistration = class extends EventTarget {
   scope;
   updateViaCache;
   navigationPreload;
-  // ServiceWorker instances representing different lifecycle states
-  _serviceWorker;
+  // Internal ServiceWorker instance (accessed via symbol for lifecycle management)
+  [kServiceWorker];
   // Web API properties (not supported in server context, but required by interface)
   cookies;
   pushManager;
@@ -583,20 +587,20 @@ var ShovelServiceWorkerRegistration = class extends EventTarget {
     this.scope = scope;
     this.updateViaCache = "imports";
     this.navigationPreload = new ShovelNavigationPreloadManager();
-    this._serviceWorker = new ShovelServiceWorker(scriptURL, "parsed");
+    this[kServiceWorker] = new ShovelServiceWorker(scriptURL, "parsed");
     this.cookies = null;
     this.pushManager = null;
     this.onupdatefound = null;
   }
   // Standard ServiceWorkerRegistration properties
   get active() {
-    return this._serviceWorker.state === "activated" ? this._serviceWorker : null;
+    return this[kServiceWorker].state === "activated" ? this[kServiceWorker] : null;
   }
   get installing() {
-    return this._serviceWorker.state === "installing" ? this._serviceWorker : null;
+    return this[kServiceWorker].state === "installing" ? this[kServiceWorker] : null;
   }
   get waiting() {
-    return this._serviceWorker.state === "installed" ? this._serviceWorker : null;
+    return this[kServiceWorker].state === "installed" ? this[kServiceWorker] : null;
   }
   // Standard ServiceWorkerRegistration methods
   async getNotifications(_options) {
@@ -613,13 +617,14 @@ var ShovelServiceWorkerRegistration = class extends EventTarget {
   async update() {
     return this;
   }
-  // Shovel runtime extensions (non-standard but needed for platforms)
+  // Internal lifecycle methods (accessed via symbols by runLifecycle)
   /**
-   * Install the ServiceWorker (Shovel extension)
+   * Dispatch the install lifecycle event
+   * @internal Use runLifecycle() instead of calling this directly
    */
-  async install() {
-    if (this._serviceWorker.state !== "parsed") return;
-    this._serviceWorker._setState("installing");
+  async [kDispatchInstall]() {
+    if (this[kServiceWorker].state !== "parsed") return;
+    this[kServiceWorker]._setState("installing");
     return new Promise((resolve, reject) => {
       const event = new ShovelInstallEvent();
       process.nextTick(() => {
@@ -632,7 +637,7 @@ var ShovelServiceWorkerRegistration = class extends EventTarget {
         }
         const promises = event.getPromises();
         if (promises.length === 0) {
-          this._serviceWorker._setState("installed");
+          this[kServiceWorker]._setState("installed");
           resolve();
         } else {
           promiseWithTimeout(
@@ -640,7 +645,7 @@ var ShovelServiceWorkerRegistration = class extends EventTarget {
             3e4,
             "ServiceWorker install event timed out after 30s - waitUntil promises did not resolve"
           ).then(() => {
-            this._serviceWorker._setState("installed");
+            this[kServiceWorker]._setState("installed");
             resolve();
           }).catch(reject);
         }
@@ -648,13 +653,14 @@ var ShovelServiceWorkerRegistration = class extends EventTarget {
     });
   }
   /**
-   * Activate the ServiceWorker (Shovel extension)
+   * Dispatch the activate lifecycle event
+   * @internal Use runLifecycle() instead of calling this directly
    */
-  async activate() {
-    if (this._serviceWorker.state !== "installed") {
+  async [kDispatchActivate]() {
+    if (this[kServiceWorker].state !== "installed") {
       throw new Error("ServiceWorker must be installed before activation");
     }
-    this._serviceWorker._setState("activating");
+    this[kServiceWorker]._setState("activating");
     return new Promise((resolve, reject) => {
       const event = new ShovelActivateEvent();
       process.nextTick(() => {
@@ -667,7 +673,7 @@ var ShovelServiceWorkerRegistration = class extends EventTarget {
         }
         const promises = event.getPromises();
         if (promises.length === 0) {
-          this._serviceWorker._setState("activated");
+          this[kServiceWorker]._setState("activated");
           resolve();
         } else {
           promiseWithTimeout(
@@ -675,7 +681,7 @@ var ShovelServiceWorkerRegistration = class extends EventTarget {
             3e4,
             "ServiceWorker activate event timed out after 30s - waitUntil promises did not resolve"
           ).then(() => {
-            this._serviceWorker._setState("activated");
+            this[kServiceWorker]._setState("activated");
             resolve();
           }).catch(reject);
         }
@@ -683,15 +689,16 @@ var ShovelServiceWorkerRegistration = class extends EventTarget {
     });
   }
   /**
-   * Handle a fetch request (Shovel extension)
+   * Handle a fetch request
+   * @internal Use the kHandleRequest symbol to access this method
    *
    * Platforms create a ShovelFetchEvent (or subclass) with platform-specific
    * properties and hooks, then pass it to this method for dispatching.
    *
    * @param event - The fetch event to handle (created by platform adapter)
    */
-  async handleRequest(event) {
-    if (this._serviceWorker.state !== "activated") {
+  async [kHandleRequest](event) {
+    if (this[kServiceWorker].state !== "activated") {
       throw new Error("ServiceWorker not activated");
     }
     return cookieStoreStorage.run(event.cookieStore, async () => {
@@ -722,10 +729,20 @@ var ShovelServiceWorkerRegistration = class extends EventTarget {
    * Check if ready to handle requests (Shovel extension)
    */
   get ready() {
-    return this._serviceWorker.state === "activated";
+    return this[kServiceWorker].state === "activated";
   }
   // Events: updatefound (standard), plus Shovel lifecycle events
 };
+async function runLifecycle(registration, stage = "activate") {
+  await registration[kDispatchInstall]();
+  if (stage === "activate") {
+    await registration[kDispatchActivate]();
+  }
+}
+async function dispatchRequest(registration, requestOrEvent) {
+  const event = requestOrEvent instanceof ShovelFetchEvent ? requestOrEvent : new ShovelFetchEvent(requestOrEvent);
+  return registration[kHandleRequest](event);
+}
 var ShovelServiceWorkerContainer = class extends EventTarget {
   #registrations;
   controller;
@@ -765,8 +782,8 @@ var ShovelServiceWorkerContainer = class extends EventTarget {
     const scope = this.#normalizeScope(options?.scope || "/");
     let registration = this.#registrations.get(scope);
     if (registration) {
-      registration._serviceWorker.scriptURL = url;
-      registration._serviceWorker._setState("parsed");
+      registration[kServiceWorker].scriptURL = url;
+      registration[kServiceWorker]._setState("parsed");
     } else {
       registration = new ShovelServiceWorkerRegistration(scope, url);
       this.#registrations.set(scope, registration);
@@ -786,30 +803,13 @@ var ShovelServiceWorkerContainer = class extends EventTarget {
     }
     return false;
   }
-  /**
-   * Route a request to the appropriate registration based on scope matching
-   */
-  async handleRequest(request) {
-    const url = new URL(request.url);
-    const pathname = url.pathname;
-    const matchingScope = this.#findMatchingScope(pathname);
-    if (matchingScope) {
-      const registration = this.#registrations.get(matchingScope);
-      if (registration && registration.ready) {
-        const event = new ShovelFetchEvent(request);
-        return await registration.handleRequest(event);
-      }
-    }
-    return null;
-  }
   /**
    * Install and activate all registrations
    */
   async installAll() {
     const installations = Array.from(this.#registrations.values()).map(
       async (registration) => {
-        await registration.install();
-        await registration.activate();
+        await runLifecycle(registration);
       }
     );
     await promiseWithTimeout(
@@ -838,19 +838,6 @@ var ShovelServiceWorkerContainer = class extends EventTarget {
     }
     return scope;
   }
-  /**
-   * Find the most specific scope that matches a pathname
-   */
-  #findMatchingScope(pathname) {
-    const scopes = Array.from(this.#registrations.keys());
-    scopes.sort((a, b) => b.length - a.length);
-    for (const scope of scopes) {
-      if (pathname.startsWith(scope === "/" ? "/" : scope)) {
-        return scope;
-      }
-    }
-    return null;
-  }
   // Events: controllerchange, message, messageerror, updatefound
 };
 var Notification = class extends EventTarget {
@@ -1035,8 +1022,10 @@ var ServiceWorkerGlobals = class {
     }
     const request = new Request(new URL(urlString, "http://localhost"), init);
     return fetchDepthStorage.run(currentDepth + 1, () => {
-      const event = new ShovelFetchEvent(request);
-      return this.registration.handleRequest(event);
+      return dispatchRequest(
+        this.registration,
+        request
+      );
     });
   }
   queueMicrotask(callback) {
@@ -1121,9 +1110,9 @@ var ServiceWorkerGlobals = class {
    * Allows the ServiceWorker to activate immediately
    */
   async skipWaiting() {
-    getLogger(["shovel", "platform"]).info("skipWaiting() called");
+    getLogger(["shovel", "platform"]).debug("skipWaiting() called");
     if (!this.#isDevelopment) {
-      getLogger(["shovel", "platform"]).info(
+      getLogger(["shovel", "platform"]).debug(
         "skipWaiting() - production graceful restart not implemented"
       );
     }
@@ -1320,8 +1309,7 @@ function startWorkerMessageLoop(options) {
         headers: message.request.headers,
         body: message.request.body
       });
-      const event = new ShovelFetchEvent(request);
-      const response = await registration.handleRequest(event);
+      const response = await dispatchRequest(registration, request);
       const body = await response.arrayBuffer();
       const headers = Object.fromEntries(response.headers.entries());
       if (!headers["Content-Type"] && !headers["content-type"]) {
@@ -1492,9 +1480,14 @@ export {
   createCacheFactory,
   createDatabaseFactory,
   createDirectoryFactory,
+  dispatchRequest,
   initWorkerRuntime,
+  kDispatchActivate,
+  kDispatchInstall,
+  kServiceWorker,
   parseCookieHeader,
   parseSetCookieHeader,
+  runLifecycle,
   serializeCookie,
   startWorkerMessageLoop
 };