@noego/wood 0.6.2 → 0.7.0

package/dist/testing/test_wood_config.cjs

@@ -32,17 +32,24 @@ __export(test_wood_config_exports, {
   testWood: () => testWood
 });
 module.exports = __toCommonJS(test_wood_config_exports);
+var import_fetch = require("@noego/runtime/fetch");
+var import_fetch2 = require("@noego/testing/fetch");
 var import_controller_lifecycle = require("../controller/controller_lifecycle.js");
 var import_node_path = __toESM(require("node:path"), 1);
 var import_ioc = require("@noego/ioc");
+var import_ioc2 = require("@noego/ioc");
 var import_testing = require("@noego/testing");
 var import_runtime_module = require("../runtime/runtime_module.js");
+var import_loader_orchestration = require("../loader/loader_orchestration.js");
+var import_middleware_resolver = require("../middleware/middleware_resolver.js");
 var import_navigation = require("../navigation/index.js");
+var import_create_router_bridge = require("./create_router_bridge.js");
 var import_test_wood = require("./test_wood.cjs");
 var import_wood_config_source = require("./wood_config_source.cjs");
 var import_wood_test_selection = require("./wood_test_selection.cjs");
 var import_wood_env_renderer = require("./wood_env_renderer.cjs");
 var import_registration_only_root = require("./registration_only_root.cjs");
+var import_wood_lazy_runtime = require("./wood_lazy_runtime.cjs");
 const CONTAINER_REGISTRY_SYMBOL = /* @__PURE__ */ Symbol.for("@noego/wood.container.registry");
 function globalRegistrySize() {
   const registry = globalThis[CONTAINER_REGISTRY_SYMBOL];
@@ -53,126 +60,6 @@ function tierMissing(tier, member) {
     `the ${member} is not available: this environment was built without { ${tier} } \u2014 add it to select()`
   );
 }
-function recordComposer(compose) {
-  if (typeof compose !== "function") throw new import_test_wood.TestWoodError("owner composition expects a callback");
-  const calls = [];
-  const root = {
-    use: (preset) => {
-      calls.push({ method: "use", args: [preset], flat: false });
-      return root;
-    },
-    classes: (config) => {
-      calls.push({ method: "classes", args: [config], flat: false });
-      return root;
-    },
-    functions: (config) => {
-      calls.push({ method: "functions", args: [config], flat: false });
-      return root;
-    },
-    values: (config) => {
-      calls.push({ method: "values", args: [config], flat: false });
-      return root;
-    },
-    methods: (config) => {
-      calls.push({ method: "methods", args: [config], flat: false });
-      return root;
-    }
-  };
-  compose(root);
-  return calls;
-}
-function applyCalls(builder, calls) {
-  let next = builder;
-  for (const call of [...calls].sort((a, b) => a.order - b.order)) {
-    next = next[call.method](...call.args);
-  }
-  return next;
-}
-function ownerTokens(builder) {
-  const tokens = /* @__PURE__ */ new Set();
-  const visit = (token) => {
-    if (tokens.has(token)) return;
-    tokens.add(token);
-    if (typeof token !== "function") return;
-    const injected = Reflect.getMetadata?.(/* @__PURE__ */ Symbol.for("ioc:inject:tokens"), token);
-    const design = Reflect.getMetadata?.("design:paramtypes", token) ?? [];
-    const indices = /* @__PURE__ */ new Set([...design.keys(), ...injected?.keys() ?? []]);
-    for (const index of indices) visit(injected?.has(index) ? injected.get(index) : design[index]);
-  };
-  for (const write of builder.writes) {
-    if (write.op === "use") {
-      for (const registration of (0, import_ioc.flattenModule)(write.module)) {
-        visit(registration.token);
-        if (registration.kind === "class") visit(registration.implementation);
-        for (const dependency of registration.dependencies) visit(dependency);
-      }
-    } else if (write.op !== "methods") {
-      visit(write.key);
-      if (write.op === "classes") visit(write.implementation);
-    }
-  }
-  return tokens;
-}
-function tokenLabel(token) {
-  if (typeof token === "function" && token.name) return token.name;
-  return String(token);
-}
-function callEntries(call) {
-  applyCalls((0, import_testing.testIoc)(), [{ ...call, order: 0 }]);
-  const config = call.args[0];
-  if (Array.isArray(config) || config instanceof Map) return [...config];
-  return Reflect.ownKeys(config).map((key) => [key, config[key]]);
-}
-function resolveOwnerToken(key, exact, main, renderer, method) {
-  let token = key;
-  if (!exact && typeof key === "string") {
-    const matches = [.../* @__PURE__ */ new Set([...main, ...renderer])].filter(
-      (candidate) => candidate === key || typeof candidate === "function" && candidate.name === key
-    );
-    if (matches.length > 1) {
-      throw new import_test_wood.TestWoodError(`Ambiguous ${method} replacement name "${key}"; use an exact token`);
-    }
-    token = matches[0] ?? key;
-  }
-  const ownsMain = main.has(token);
-  const ownsRenderer = renderer.has(token);
-  if (!ownsMain && !ownsRenderer) {
-    throw new import_test_wood.TestWoodError(
-      `Unknown ${method} replacement ${tokenLabel(token)} in the selected roots; register it with .main() or .renderer()`
-    );
-  }
-  if (ownsMain && ownsRenderer) {
-    throw new import_test_wood.TestWoodError(
-      `Ambiguous ${method} replacement ${tokenLabel(token)} belongs to main and renderer; target .main() or .renderer() explicitly`
-    );
-  }
-  return { token, owner: ownsMain ? "main" : "renderer" };
-}
-function routeCalls(calls, main, renderer, target) {
-  for (const call of calls) {
-    if (!call.flat || call.method !== "classes") continue;
-    const exact = Array.isArray(call.args[0]) || call.args[0] instanceof Map;
-    for (const [key, implementation] of callEntries(call)) {
-      const routed = resolveOwnerToken(key, exact || typeof key !== "string", main, renderer, call.method);
-      (routed.owner === "main" ? main : renderer).add(implementation);
-    }
-  }
-  const result = [];
-  for (const call of calls) {
-    if (!call.flat) {
-      if (target === "main") result.push(call);
-      continue;
-    }
-    const exact = Array.isArray(call.args[0]) || call.args[0] instanceof Map;
-    for (const [key, value] of callEntries(call)) {
-      const routed = resolveOwnerToken(key, exact || typeof key !== "string", main, renderer, call.method);
-      if (routed.owner === target) {
-        result.push({ ...call, flat: false, args: [[[routed.token, value]]] });
-      }
-    }
-  }
-  return result;
-}
 async function loadController(source, importer, reference, owner) {
   const file = owner === "main" ? source.mainControllerFile(reference) : source.rendererControllerFile(reference);
   const controller = await (0, import_wood_config_source.importDefaultExport)(
@@ -213,11 +100,11 @@ async function runCompose(root, source, context) {
   if (typeof compose !== "function") {
     throw new import_test_wood.TestWoodError(`main.testing.compose default export must be a function (${composePath})`);
   }
-  return await import_ioc.ExecutionContext.run(root, () => compose(root, context)) ?? null;
+  return await import_ioc2.ExecutionContext.run(root, () => compose(root, context)) ?? null;
 }
 async function disposeRoot(env) {
   try {
-    await import_ioc.ExecutionContext.run(env.root, () => env.dispose());
+    await import_ioc2.ExecutionContext.run(env.root, () => env.dispose());
   } catch (error) {
     const failures = error.failures;
     if (!Array.isArray(failures)) throw error;
@@ -237,6 +124,7 @@ function assertNoGlobalContainerLeak(before, source) {
 }
 function createComposeContext(source, state, selection, operations, live) {
   return {
+    events: new import_create_router_bridge.RouterBridgeEvents(),
     configPath: source.configPath,
     configDir: source.configDir,
     config: source.config,
@@ -244,45 +132,60 @@ function createComposeContext(source, state, selection, operations, live) {
     operations,
     importer: state.importer,
     call: async (operation, input) => {
-      if (!live.router || !live.env) {
+      if (!live.env || !live.router && !live.runtime) {
         throw new import_test_wood.TestWoodError("compose context call() is available from start() onward, not during compose");
       }
-      const router = live.router;
-      return await import_ioc.ExecutionContext.run(
+      const router = live.router ?? (await live.runtime.main.acquire()).router;
+      return await import_ioc2.ExecutionContext.run(
         live.env.root,
         () => router.dispatch(operation, input)
       );
     }
   };
 }
-function createAssemblyDisposer(live, mainRegistrations, rendererRegistrations, controllerScopes) {
+function createAssemblyDisposer(live, mainRegistrations, rendererRegistrations, controllerScopes, network) {
   let closing = null;
-  return () => closing ?? (closing = (0, import_registration_only_root.cleanupAll)("testWood cleanup failed", [
-    ["renderer", async () => {
-      if (live.renderer) await live.renderer.dispose();
-    }],
-    ...[...controllerScopes].reverse().map(
-      (scope, index) => [`controller scope ${controllerScopes.length - index}`, () => scope.dispose()]
-    ),
-    ["compose drain", async () => {
-      await live.composed?.drain?.();
-    }],
-    ["main root", async () => {
-      if (live.env) await disposeRoot(live.env);
-      else await mainRegistrations.actualRoot.dispose();
-    }],
-    ["unbuilt renderer root", async () => {
-      if (!live.renderer && rendererRegistrations) await rendererRegistrations.actualRoot.dispose();
-    }],
-    ["compose external dispose", async () => {
-      await live.composed?.dispose?.();
-    }]
-  ]));
+  return () => {
+    live.disposed = true;
+    return closing ?? (closing = (0, import_registration_only_root.cleanupAll)("testWood cleanup failed", [
+      // An initialization racing this dispose finishes first (it refuses to
+      // complete once `disposed` is set) so every resource it created late is
+      // released below. A rollback-triggered dispose skips this: its own
+      // stage has already finished and waiting would be a self-await.
+      ["runtime settle", async () => {
+        if (live.rolledBack || !live.runtime) return;
+        await live.runtime.main.settled();
+        await live.runtime.renderer?.settled();
+      }],
+      ["renderer", async () => {
+        if (live.renderer) await live.renderer.dispose();
+      }],
+      ...[...controllerScopes].reverse().map(
+        (scope, index) => [`controller scope ${controllerScopes.length - index}`, () => scope.dispose()]
+      ),
+      ["compose drain", async () => {
+        const root = live.env?.root ?? mainRegistrations.actualRoot;
+        if (!root.isDisposed()) await import_ioc2.ExecutionContext.run(root, () => live.composed?.drain?.());
+      }],
+      ["main root", async () => {
+        if (live.env) await disposeRoot(live.env);
+        else await mainRegistrations.actualRoot.dispose();
+      }],
+      ["unbuilt renderer root", async () => {
+        if (!live.renderer && rendererRegistrations) await rendererRegistrations.actualRoot.dispose();
+      }],
+      ["compose external dispose", async () => {
+        await live.composed?.dispose?.();
+      }],
+      ["external fetch", () => network.dispose()]
+    ]));
+  };
 }
 async function loadAssemblyControllers(inputs) {
   const main = await loadMainControllers(inputs.source, inputs.operations, inputs.state.importer);
-  const renderer = inputs.catalog ? await loadRendererControllers(inputs.source, inputs.catalog.all(), inputs.state.importer) : /* @__PURE__ */ new Map();
-  return { main, renderer };
+  const renderer = inputs.catalog && !inputs.state.browserHost ? await loadRendererControllers(inputs.source, inputs.catalog.all(), inputs.state.importer) : /* @__PURE__ */ new Map();
+  const loaders = inputs.catalog && !inputs.state.browserHost ? await loadRendererLoaders(inputs.source, inputs.catalog.all(), inputs.state.importer) : /* @__PURE__ */ new Map();
+  return { main, renderer, loaders };
 }
 function installAssemblyRuntime(inputs, mainControllers) {
   (0, import_runtime_module.installWoodRuntime)(inputs.mainRegistrations.root, {
@@ -294,15 +197,67 @@ function installAssemblyRuntime(inputs, mainControllers) {
         configuredRouter.registerControllerLoader(identity, () => Promise.resolve({ default: controller }));
       }
       configuredRouter.loadOperations(inputs.operations);
+      registerMiddlewareSeams(inputs, configuredRouter);
     }
   });
 }
+function registerMiddlewareSeams(inputs, configuredRouter) {
+  const executables = inputs.live.executables;
+  if (!executables || !executables.middleware.size) return;
+  const sourceResolver = new import_middleware_resolver.MiddlewareResolver(inputs.source.mainMiddlewareDir);
+  for (const spec of executables.middleware) {
+    configuredRouter.registerMiddleware(spec, async (context) => {
+      const original = await sourceResolver.resolve(spec);
+      return executables.main.replace("middleware", spec, original)(context);
+    });
+  }
+}
+function selectedMiddleware(operations) {
+  const identities = /* @__PURE__ */ new Set();
+  for (const operation of operations.values()) for (const spec of operation.middleware) identities.add(spec);
+  return [...identities];
+}
+async function loadRendererLoaders(source, views, importer) {
+  const loaders = /* @__PURE__ */ new Map();
+  for (const view of views) {
+    for (const viewPath of [...view.layouts, view.viewPath]) {
+      const reference = source.rendererLoaderReference(viewPath);
+      if (!reference || loaders.has(reference.identity)) continue;
+      const mod = await importer(reference.file);
+      if (mod.default === void 0) {
+        throw new import_test_wood.TestWoodError(`data loader ${reference.identity} (${reference.file}) has no default export`);
+      }
+      try {
+        loaders.set(reference.identity, (0, import_loader_orchestration.assertDataLoader)(mod.default, `data loader ${reference.identity}`));
+      } catch (error) {
+        throw new import_test_wood.TestWoodError(error instanceof Error ? error.message : String(error));
+      }
+    }
+  }
+  return loaders;
+}
+function rendererLoaderReferences(loaders) {
+  return [...loaders.keys()].map((identity) => Object.freeze({ path: identity, export: "default" }));
+}
 async function configureRendererRegistrations(inputs) {
   const registrations = inputs.rendererRegistrations;
   if (!registrations) return;
-  registrations.declare(import_navigation.Navigation);
-  registrations.declare(import_test_wood.WOOD_FRONTEND_BRIDGE);
-  await import_ioc.ExecutionContext.run(
+  registrations.root.registerFunction(import_fetch.FETCH_RUNTIME, () => inputs.network, { owned: false, loadAs: import_ioc.LoadAs.Singleton });
+  registrations.declareBinding(import_navigation.Navigation, "singleton");
+  registrations.declareBinding(import_test_wood.WOOD_FRONTEND_BRIDGE, "singleton");
+  const composePath = inputs.source.hookModule(inputs.source.config.renderer.compose);
+  if (composePath) {
+    const composeRenderer = await (0, import_wood_config_source.importDefaultExport)(
+      inputs.state.importer,
+      composePath,
+      "renderer.compose"
+    );
+    if (typeof composeRenderer !== "function") {
+      throw new import_test_wood.TestWoodError(`renderer.compose default export must be a function (${composePath})`);
+    }
+    await import_ioc2.ExecutionContext.run(registrations.root, () => composeRenderer(registrations.root));
+  }
+  await import_ioc2.ExecutionContext.run(
     registrations.root,
     () => inputs.live.composed?.configureRendererRoot?.(registrations.root)
   );
@@ -318,62 +273,149 @@ function registerControllersBeforeOverlays(inputs, mainControllers, rendererCont
     inputs.rendererRegistrations?.declare(controller);
   }
 }
-function buildAssemblyIoc(inputs) {
-  const explicitMain = inputs.state.mainCalls.filter((call) => !call.flat);
-  const mainOwners = /* @__PURE__ */ new Set([
-    ...inputs.mainRegistrations.owners,
-    ...ownerTokens(applyCalls((0, import_testing.testIoc)(), explicitMain))
-  ]);
-  const rendererOwners = /* @__PURE__ */ new Set([
-    ...inputs.rendererRegistrations?.owners ?? [],
-    ...ownerTokens(applyCalls((0, import_testing.testIoc)(), inputs.state.rendererCalls))
-  ]);
-  const routedMain = routeCalls(inputs.state.mainCalls, mainOwners, rendererOwners, "main");
-  const routedRenderer = routeCalls(inputs.state.mainCalls, mainOwners, rendererOwners, "renderer");
+function buildAssemblyIoc(inputs, controllers) {
+  const catalogs = [{
+    owner: "main",
+    bindings: (0, import_testing.describeTestBindings)((0, import_testing.testIoc)().use(inputs.mainRegistrations.module()), [...controllers.main.values()]),
+    middleware: selectedMiddleware(inputs.operations),
+    loaders: []
+  }];
+  if (inputs.rendererRegistrations && inputs.catalog) {
+    catalogs.push({
+      owner: "renderer",
+      bindings: (0, import_testing.describeTestBindings)((0, import_testing.testIoc)().use(inputs.rendererRegistrations.module()), [...controllers.renderer.values()]),
+      middleware: [],
+      loaders: rendererLoaderReferences(controllers.loaders)
+    });
+  }
+  const overlays = (0, import_testing.resolveTestOverlays)(inputs.state.overlays, catalogs);
+  const mainPlan = (0, import_testing.applyTestBindings)((0, import_testing.testIoc)(), overlays, "main");
+  const rendererPlan = (0, import_testing.applyTestBindings)((0, import_testing.testIoc)(), overlays, "renderer");
   return {
-    main: applyCalls((0, import_testing.testIoc)(), routedMain),
-    renderer: applyCalls((0, import_testing.testIoc)(), [...inputs.state.rendererCalls, ...routedRenderer])
+    main: mainPlan.builder,
+    mainBorrowed: mainPlan.buildOptions.borrowedTokens ?? [],
+    renderer: rendererPlan.builder,
+    rendererBorrowed: rendererPlan.buildOptions.borrowedTokens ?? [],
+    overlays,
+    executables: {
+      main: (0, import_testing.createTestExecutables)(overlays, "main"),
+      renderer: (0, import_testing.createTestExecutables)(overlays, "renderer"),
+      middleware: new Set(overlays.filter((overlay) => overlay.owner === "main" && overlay.entry.kind === "middleware").map((overlay) => overlay.entry.target))
+    }
   };
 }
+function createRuntimeRollback(inputs) {
+  return (error) => {
+    if (inputs.live.rolledBack || inputs.live.disposed) return Promise.reject(error);
+    inputs.live.rolledBack = true;
+    return rollbackEnvironment(error, inputs.dispose, "testWood runtime initialization failed and rollback failed");
+  };
+}
+function assertRuntimeMayStart(inputs, stage) {
+  if (inputs.live.disposed) {
+    throw new import_test_wood.TestWoodError(`this testWood environment was disposed before its ${stage} runtime was used`);
+  }
+}
+function assertRuntimeMayContinue(inputs, stage) {
+  if (inputs.live.disposed) {
+    throw new import_test_wood.TestWoodError(`this testWood environment was disposed while its ${stage} runtime was initializing`);
+  }
+}
+async function initializeMainRuntime(inputs) {
+  assertRuntimeMayStart(inputs, "main");
+  const root = inputs.live.env.root;
+  const router = await Promise.resolve(
+    import_ioc2.ExecutionContext.run(root, () => root.get(import_runtime_module.WoodRouter))
+  );
+  inputs.live.router = router;
+  assertRuntimeMayContinue(inputs, "main");
+  await import_ioc2.ExecutionContext.run(root, () => inputs.live.composed?.start?.());
+  assertRuntimeMayContinue(inputs, "main");
+  assertNoGlobalContainerLeak(inputs.registryBefore, inputs.source);
+  return { router };
+}
+async function initializeRendererRuntime(inputs, main, renderer) {
+  const { router } = await main.acquire();
+  assertRuntimeMayStart(inputs, "renderer");
+  const composed = inputs.live.composed;
+  const configurePageScope = composed?.configurePageScope?.bind(composed);
+  const hooks = {
+    events: renderer.events,
+    ...configurePageScope ? { configurePageScope } : {}
+  };
+  const tier = await (0, import_wood_env_renderer.buildRendererTier)({
+    source: inputs.source,
+    router,
+    catalog: inputs.catalog,
+    operations: inputs.operations,
+    importer: inputs.state.importer,
+    hooks,
+    dom: null,
+    ioc: renderer.ioc,
+    borrowedTokens: renderer.borrowedTokens,
+    registrations: inputs.rendererRegistrations,
+    controllerClasses: renderer.controllerClasses,
+    loaders: renderer.loaders,
+    loaderModules: renderer.loaderModules
+  });
+  inputs.live.renderer = tier;
+  assertRuntimeMayContinue(inputs, "renderer");
+  return tier;
+}
+function createAssemblyRuntime(inputs, renderer) {
+  const rollback = createRuntimeRollback(inputs);
+  const main = new import_wood_lazy_runtime.LazyRuntimeStage(() => initializeMainRuntime(inputs), rollback);
+  const rendererStage = renderer ? new import_wood_lazy_runtime.LazyRuntimeStage(() => initializeRendererRuntime(inputs, main, renderer), rollback) : null;
+  return { main, renderer: rendererStage };
+}
 async function materializeEnvironment(inputs) {
+  inputs.mainRegistrations.root.registerFunction(import_fetch.FETCH_RUNTIME, () => inputs.network, { owned: false, loadAs: import_ioc.LoadAs.Singleton });
   const controllers = await loadAssemblyControllers(inputs);
   inputs.live.composed = await runCompose(inputs.mainRegistrations.root, inputs.source, inputs.context);
+  assertNoGlobalContainerLeak(inputs.registryBefore, inputs.source);
   installAssemblyRuntime(inputs, controllers.main);
   await configureRendererRegistrations(inputs);
   registerControllersBeforeOverlays(inputs, controllers.main, controllers.renderer);
-  const ioc = buildAssemblyIoc(inputs);
-  inputs.live.env = await (0, import_registration_only_root.buildRecordedEnvironment)(ioc.main, inputs.mainRegistrations, "main");
+  const ioc = buildAssemblyIoc(inputs, controllers);
+  inputs.live.executables = ioc.executables;
+  inputs.live.env = await (0, import_registration_only_root.buildRecordedEnvironment)(ioc.main, inputs.mainRegistrations, "main", ioc.mainBorrowed);
   const root = inputs.live.env.root;
-  inputs.live.router = await Promise.resolve(
-    import_ioc.ExecutionContext.run(root, () => root.get(import_runtime_module.WoodRouter))
-  );
-  await import_ioc.ExecutionContext.run(root, () => inputs.live.composed?.start?.());
-  assertNoGlobalContainerLeak(inputs.registryBefore, inputs.source);
-  if (inputs.catalog && inputs.rendererRegistrations) {
-    inputs.live.renderer = await (0, import_wood_env_renderer.buildRendererTier)({
-      source: inputs.source,
-      router: inputs.live.router,
-      catalog: inputs.catalog,
-      operations: inputs.operations,
-      importer: inputs.state.importer,
-      hooks: inputs.live.composed,
-      dom: inputs.selection.dom,
-      ioc: ioc.renderer,
-      registrations: inputs.rendererRegistrations,
-      controllerClasses: controllers.renderer
-    });
-  }
-  return environmentSurface({
+  const renderer = inputs.catalog && inputs.rendererRegistrations ? {
+    ioc: ioc.renderer,
+    borrowedTokens: ioc.rendererBorrowed,
+    controllerClasses: controllers.renderer,
+    events: inputs.live.composed?.events ?? inputs.context.events,
+    loaders: ioc.executables.renderer,
+    loaderModules: controllers.loaders
+  } : null;
+  const runtime = createAssemblyRuntime(inputs, renderer);
+  inputs.live.runtime = runtime;
+  const environment = environmentSurface({
     root,
+    network: inputs.network,
     env: inputs.live.env,
-    router: inputs.live.router,
     operations: inputs.operations,
-    renderer: inputs.live.renderer,
+    runtime,
+    allOperations: inputs.source.operations,
+    events: renderer?.events ?? inputs.live.composed?.events ?? inputs.context.events,
+    dom: false,
     controllerScopes: inputs.controllerScopes,
+    executables: ioc.executables,
     dispose: inputs.dispose
   });
+  if (inputs.state.browserHost) {
+    const { createNativeBrowserEnvironment } = await import("./native_browser/native_browser_environment.js");
+    return createNativeBrowserEnvironment({
+      source: inputs.source,
+      views: inputs.catalog.all(),
+      environment,
+      network: inputs.network,
+      events: () => inputs.live.composed?.events ?? inputs.context.events
+    }, inputs.state.browserHost);
+  }
+  return environment;
 }
-async function rollbackEnvironment(error, dispose) {
+async function rollbackEnvironment(error, dispose, message = "testWood build failed and rollback failed") {
   try {
     await dispose();
   } catch (cleanupError) {
@@ -381,35 +423,48 @@ async function rollbackEnvironment(error, dispose) {
       ...error instanceof import_registration_only_root.TestWoodCleanupError ? error.failures : [],
       ...cleanupError instanceof import_registration_only_root.TestWoodCleanupError ? cleanupError.failures : [{ owner: "build rollback", error: cleanupError }]
     ];
-    throw new import_registration_only_root.TestWoodCleanupError("testWood build failed and rollback failed", failures, error);
+    throw new import_registration_only_root.TestWoodCleanupError(message, failures, error);
   }
   throw error;
 }
-async function assembleEnvironment(state, selection) {
+async function assembleEnvironment(state, selected) {
   const source = (0, import_wood_config_source.loadWoodConfigSource)(state.configPath);
+  let selection = selected ?? (0, import_wood_test_selection.resolveSelection)(
+    Object.fromEntries(import_wood_test_selection.DECLARED_OWNERS.filter((owner) => source.config[owner]).map((owner) => [owner, {}]))
+  );
   const operations = (0, import_wood_test_selection.selectOperations)(source.operations, selection.main);
-  const catalog = selection.pages ? (0, import_wood_test_selection.selectCatalog)(source.views(), selection.pages) : null;
-  if (!catalog && state.rendererCalls.length) {
-    throw new import_test_wood.TestWoodError(".renderer() composition requires a selected pages tier");
+  const catalog = (0, import_wood_test_selection.selectRendererCatalog)(source.views, selection);
+  if (state.browserHost && !catalog) {
+    throw new import_test_wood.TestWoodError("browser() requires a selected renderer owner; add renderer to select()");
+  }
+  if (state.browserHost && (0, import_testing.stubEntries)(state.overlays).some((entry) => entry.kind === "load" || entry.owner === "renderer")) {
+    throw new import_test_wood.TestWoodError("Native browser renderer replacements are not supported yet: renderer code executes in its own realm. Keep main-process seams, or use the existing in-process renderer test environment for renderer .class/.method/.value/.load seams.");
   }
+  const network = (0, import_fetch2.createTestFetch)(state.fetchConfigurations.flatMap(import_fetch2.defineFetchRoutes));
   const registryBefore = globalRegistrySize();
-  const mainRegistrations = new import_registration_only_root.RegistrationOnlyRoot("main.testing.compose");
-  const rendererRegistrations = catalog ? new import_registration_only_root.RegistrationOnlyRoot("configureRendererRoot") : null;
+  const mainRegistrations = new import_registration_only_root.RegistrationOnlyRoot("main.testing.compose", source.configPath);
+  const rendererRegistrations = catalog && !state.browserHost ? new import_registration_only_root.RegistrationOnlyRoot("configureRendererRoot", source.configPath) : null;
   const controllerScopes = [];
   const live = {
     composed: null,
     env: null,
     renderer: null,
-    router: null
+    router: null,
+    executables: null,
+    runtime: null,
+    disposed: false,
+    rolledBack: false
   };
   const context = createComposeContext(source, state, selection, operations, live);
   const dispose = createAssemblyDisposer(
     live,
     mainRegistrations,
     rendererRegistrations,
-    controllerScopes
+    controllerScopes,
+    network
   );
   const inputs = {
+    network,
     state,
     selection,
     source,
@@ -429,73 +484,114 @@ async function assembleEnvironment(state, selection) {
     return rollbackEnvironment(error, dispose);
   }
 }
+const OPEN_FIRST = "await open(page) (or another renderer call) first";
 function environmentSurface(parts) {
-  const { root, env, router, operations, renderer, controllerScopes, dispose } = parts;
-  const dom = () => renderer?.dom ?? tierMissing("dom", "dom driver");
-  const pages = () => renderer ?? tierMissing("pages", "renderer");
+  const { root, env, operations, allOperations, runtime, events, dom: domSelected, controllerScopes, executables, dispose } = parts;
+  const pages = () => runtime.renderer ?? tierMissing("pages", "renderer");
+  const dom = async () => {
+    if (!domSelected) tierMissing("dom", "dom driver");
+    return (await pages().acquire()).dom;
+  };
+  const router = (0, import_wood_lazy_runtime.lazyMember)(
+    "router",
+    runtime.main.map((main) => main.router),
+    ["dispatch"],
+    "await call()/get()/controller() first"
+  );
+  const frontend = runtime.renderer ? (0, import_wood_lazy_runtime.lazyMember)(
+    "frontend",
+    runtime.renderer.map((tier) => tier.frontend),
+    ["open", "act", "settle", "dispose"],
+    OPEN_FIRST
+  ) : null;
+  const rendererRoot = runtime.renderer ? (0, import_wood_lazy_runtime.lazyMember)(
+    "rendererRoot",
+    runtime.renderer.map((tier) => tier.rendererRoot),
+    ["get", "dispose"],
+    OPEN_FIRST
+  ) : null;
+  const dispatchOperation = async (operation, input) => {
+    if (!operations.has(operation)) {
+      throw new import_test_wood.TestWoodError(
+        `operation "${operation}" is not in the selected aperture; available operations:
+  ${[...operations.keys()].join("\n  ")}`
+      );
+    }
+    const { router: live } = await runtime.main.acquire();
+    return await import_ioc2.ExecutionContext.run(root, () => live.dispatch(operation, input));
+  };
+  const api = (0, import_create_router_bridge.createOperationApi)(allOperations.keys(), dispatchOperation);
   return {
     root,
     router,
     operations,
-    call: async (operation, input) => {
-      if (!operations.has(operation)) {
-        throw new import_test_wood.TestWoodError(
-          `operation "${operation}" is not in the selected aperture; available operations:
-  ${[...operations.keys()].join("\n  ")}`
-        );
-      }
-      return await import_ioc.ExecutionContext.run(root, () => router.dispatch(operation, input));
-    },
+    api,
+    rawApi: api,
+    call: dispatchOperation,
     controller: async (controller) => {
+      await runtime.main.acquire();
       const scope = root.extend();
       const ownsController = !root.isRegistered(controller);
       let instance;
-      controllerScopes.push({ dispose: () => import_ioc.ExecutionContext.run(scope, () => (0, import_registration_only_root.cleanupAll)("controller cleanup failed", [
+      controllerScopes.push({ dispose: () => import_ioc2.ExecutionContext.run(scope, () => (0, import_registration_only_root.cleanupAll)("controller cleanup failed", [
         ["controller", async () => {
           if (ownsController) await (0, import_controller_lifecycle.disposeControllerLifecycle)(instance);
         }],
         ["scope", () => scope.dispose()]
       ])) });
       if (!scope.isRegistered(controller)) scope.registerClass(controller);
-      instance = await import_ioc.ExecutionContext.run(scope, () => scope.get(controller));
+      instance = await import_ioc2.ExecutionContext.run(scope, () => scope.get(controller));
       (0, import_controller_lifecycle.guardControllerLifecycleOnce)(instance);
       return instance;
     },
-    get: async (token) => await root.get(token),
+    get: async (token) => {
+      await runtime.main.acquire();
+      return await import_ioc2.ExecutionContext.run(root, () => root.get(token));
+    },
     get frontend() {
-      return pages().frontend;
+      return frontend ?? tierMissing("pages", "renderer");
     },
     get events() {
-      return pages().events;
+      return events ?? tierMissing("pages", "renderer");
     },
     get rendererRoot() {
-      return pages().rendererRoot;
+      return rendererRoot ?? tierMissing("pages", "renderer");
+    },
+    open: async (page, params, query) => (await pages().acquire()).open(page, params, query),
+    navigate: async (page, params, query) => (await pages().acquire()).navigate(page, params, query),
+    current: () => pages().current?.current() ?? null,
+    settle: async () => {
+      await parts.network.settle();
+      if (runtime.main.requested) await (await runtime.main.acquire()).router.drain();
+      if (runtime.renderer?.requested) await (await runtime.renderer.acquire()).settle();
     },
-    open: async (page, params, query) => pages().open(page, params, query),
-    navigate: async (page, params, query) => pages().navigate(page, params, query),
-    current: () => pages().current(),
-    settle: async () => pages().settle(),
     get target() {
-      return dom().target;
+      if (!domSelected) tierMissing("dom", "dom driver");
+      const tier = pages().current;
+      if (!tier) throw new import_test_wood.TestWoodError("no page is mounted; open(page) first");
+      return tier.dom.target;
     },
-    click: async (selector) => dom().click(selector),
-    type: async (selector, text) => dom().type(selector, text),
-    submit: async (selector) => dom().submit(selector),
-    text: async (selector) => dom().text(selector),
-    exists: async (selector) => dom().exists(selector),
+    click: async (selector) => (await dom()).click(selector),
+    type: async (selector, text) => (await dom()).type(selector, text),
+    submit: async (selector) => (await dom()).submit(selector),
+    text: async (selector) => (await dom()).text(selector),
+    exists: async (selector) => (await dom()).exists(selector),
     // Method expectations only: `settle()` is the completion contract for
     // owned renderer work, and a test may legitimately verify while a
     // deliberately deferred stream is still in flight.
     verify: async () => {
       const failures = [];
       await env.verify().catch((error) => failures.push({ owner: "main", error }));
+      await executables.main.verify().catch((error) => failures.push({ owner: "main middleware", error }));
+      const renderer = runtime.renderer?.current ?? null;
       if (renderer) {
         await renderer.verify().catch((error) => failures.push({ owner: "renderer", error }));
       }
+      await executables.renderer.verify().catch((error) => failures.push({ owner: "renderer loaders", error }));
       if (failures.length === 1) throw failures[0].error;
       if (failures.length) {
         throw new import_test_wood.TestWoodError(
-          "testWood verification failed in both roots:\n  " + failures.map(({ owner, error }) => `${owner}: ${error instanceof Error ? error.message : String(error)}`).join("\n  ")
+          "testWood verification failed in several owners:\n  " + failures.map(({ owner, error }) => `${owner}: ${error instanceof Error ? error.message : String(error)}`).join("\n  ")
         );
       }
     },
@@ -514,60 +610,79 @@ class TestWoodBuilder {
     return new TestWoodBuilder({
       configPath: import_node_path.default.resolve(configPath),
       selection: null,
-      mainCalls: [],
-      rendererCalls: [],
-      importer: import_wood_config_source.defaultImporter
+      browserHost: null,
+      fetchConfigurations: [],
+      importer: import_wood_config_source.defaultImporter,
+      overlays: (0, import_testing.testStub)()
     });
   }
-  /** Declare which tiers exist: `main`, `pages`, `dom`. Replaces any earlier selection. */
+  fetch(configure) {
+    if (typeof configure !== "function") throw new TypeError("fetch() requires a route configuration callback");
+    return this.derive({ fetchConfigurations: Object.freeze([...this.state.fetchConfigurations, configure]) });
+  }
+  browser(host = "playwright") {
+    if (host !== "playwright" && host !== "happy_dom") throw new import_test_wood.TestWoodError("browser() accepts playwright or happy_dom");
+    return new TestWoodBuilder({ ...this.state, browserHost: host });
+  }
+  /** Declare selected tiers, snapshotting the source selector at call time. */
   select(selection) {
-    (0, import_wood_test_selection.resolveSelection)(selection);
-    return this.derive({ selection });
+    const resolved = (0, import_wood_test_selection.resolveSelection)(selection);
+    return this.derive({ selection: Object.freeze({
+      ...resolved.main !== null ? { main: resolved.main } : {},
+      ...resolved.renderer !== null ? { renderer: resolved.renderer } : {}
+    }) });
   }
   /** Route hook/controller imports through a caller-owned importer (escape hatch). */
   importer(importer) {
     if (typeof importer !== "function") throw new import_test_wood.TestWoodError("importer() expects a function");
     return this.derive({ importer });
   }
-  /** Explicitly compose or replace dependencies on the main-process root. */
-  main(compose) {
-    return this.append("main", recordComposer(compose));
-  }
-  /** Explicitly compose or replace dependencies on the renderer root. */
-  renderer(compose) {
-    return this.append("renderer", recordComposer(compose));
-  }
-  /** Reusable presets retain the historical main-root default. */
+  /** Compose a reusable canonical testStub() replacement description. */
   use(preset) {
-    return this.append("main", [{ method: "use", args: [preset], flat: false }]);
-  }
-  /** Exact-token replacement routed to the sole declared selected owner. */
-  classes(config) {
-    return this.append("main", [{ method: "classes", args: [config], flat: true }]);
-  }
-  /** Exact-token replacement routed to the sole declared selected owner. */
-  functions(config) {
-    return this.append("main", [{ method: "functions", args: [config], flat: true }]);
-  }
-  /** Exact-token replacement routed to the sole declared selected owner. */
-  values(config) {
-    return this.append("main", [{ method: "values", args: [config], flat: true }]);
-  }
-  /** Exact-token method seams routed to the sole declared selected owner. */
-  methods(config) {
-    return this.append("main", [{ method: "methods", args: [config], flat: true }]);
-  }
+    if (!(preset instanceof import_testing.TestStub)) throw new import_test_wood.TestWoodError("use() requires testStub()");
+    return this.derive({ overlays: this.state.overlays.use(preset) });
+  }
+  /* -- canonical singular replacements (shared @noego/testing engine) ------ */
+  /** Replace the class bound to an exact declared token; the declared lifetime is kept. */
+  class(target, replacement, options) {
+    return this.derive({ overlays: this.state.overlays.class(target, replacement, options) });
+  }
+  /** Replace a declared factory/provider (dependencies and lifetime kept) or a callable value. */
+  function(target, replacement, options) {
+    return this.derive({ overlays: this.state.overlays.function(target, replacement, options) });
+  }
+  /** A test.* method seam on the FINAL binding of an exact declared token. */
+  method(target, method, replacement, options) {
+    return this.derive({ overlays: this.state.overlays.method(target, method, replacement, options) });
+  }
+  /** Provide a caller-owned value for an exact declared token (never disposed by the app). */
+  value(target, replacement, options) {
+    return this.derive({ overlays: this.state.overlays.value(target, replacement, options) });
+  }
+  /**
+   * Replace the executable satisfying a production middleware identity
+   * (`file.path:selector` as written in the operations source). Membership,
+   * order and inheritance always come from the source.
+   */
+  middleware(identity, replacement, options) {
+    return this.derive({ overlays: this.state.overlays.middleware(identity, replacement, options) });
+  }
+  /**
+   * Replace the DATA LOADER behind a selected page/layout: the companion
+   * `.load` source of a view (`pages/chat.svelte` → `pages/chat.load.ts`).
+   * The identity is the config-relative source path (`ui/pages/chat.load.ts`),
+   * export `default`; the executable receives the loader `RequestData`
+   * (`url` = page identity, `params`, `query`) and yields the data the
+   * controller's `initialize({ params, query, data })` receives. A source
+   * with no companion loader is not a declared identity (build error).
+   * Controllers are replaced with `.class`, never here.
+   */
+  load(identity, replacement, options) {
+    return this.derive({ overlays: this.state.overlays.load(identity, replacement, options) });
+  }
+  /** Build; without `select()`, every owner the config declares is selected whole. */
   async build() {
-    if (!this.state.selection) {
-      throw new import_test_wood.TestWoodError("select() a tier before build(): { main }, { pages }, or both");
-    }
-    return assembleEnvironment(this.state, (0, import_wood_test_selection.resolveSelection)(this.state.selection));
-  }
-  append(owner, calls) {
-    const start = this.state.mainCalls.length + this.state.rendererCalls.length;
-    const ordered = calls.map((call, index) => ({ ...call, order: start + index }));
-    applyCalls((0, import_testing.testIoc)(), ordered);
-    return owner === "main" ? this.derive({ mainCalls: [...this.state.mainCalls, ...ordered] }) : this.derive({ rendererCalls: [...this.state.rendererCalls, ...ordered] });
+    return await assembleEnvironment(this.state, this.state.selection ? (0, import_wood_test_selection.resolveSelection)(this.state.selection) : null);
   }
   derive(patch) {
     return new TestWoodBuilder({ ...this.state, ...patch });