@noego/wood 0.6.2 → 0.7.0

package/dist/testing/test_wood_config.js

@@ -1,9 +1,25 @@
+import { FETCH_RUNTIME } from "@noego/runtime/fetch";
+import { createTestFetch, defineFetchRoutes } from "@noego/testing/fetch";
 import { disposeControllerLifecycle, guardControllerLifecycleOnce } from "../controller/controller_lifecycle.js";
 import path from "node:path";
-import { ExecutionContext, flattenModule } from "@noego/ioc";
-import { testIoc, ENV_REGISTRY } from "@noego/testing";
+import { LoadAs } from "@noego/ioc";
+import { ExecutionContext } from "@noego/ioc";
+import {
+  applyTestBindings,
+  createTestExecutables,
+  describeTestBindings,
+  ENV_REGISTRY,
+  resolveTestOverlays,
+  testIoc,
+  TestStub,
+  testStub,
+  stubEntries
+} from "@noego/testing";
 import { installWoodRuntime, WoodRouter } from "../runtime/runtime_module.js";
+import { assertDataLoader } from "../loader/loader_orchestration.js";
+import { MiddlewareResolver } from "../middleware/middleware_resolver.js";
 import { Navigation } from "../navigation/index.js";
+import { createOperationApi, RouterBridgeEvents } from "./create_router_bridge.js";
 import { TestWoodError, WOOD_FRONTEND_BRIDGE } from "./test_wood.js";
 import {
   defaultImporter,
@@ -11,9 +27,10 @@ import {
   loadWoodConfigSource
 } from "./wood_config_source.js";
 import {
+  DECLARED_OWNERS,
   resolveSelection,
-  selectCatalog,
-  selectOperations
+  selectOperations,
+  selectRendererCatalog
 } from "./wood_test_selection.js";
 import {
   buildRendererTier
@@ -24,6 +41,7 @@ import {
   RegistrationOnlyRoot,
   TestWoodCleanupError
 } from "./registration_only_root.js";
+import { LazyRuntimeStage, lazyMember } from "./wood_lazy_runtime.js";
 const CONTAINER_REGISTRY_SYMBOL = /* @__PURE__ */ Symbol.for("@noego/wood.container.registry");
 function globalRegistrySize() {
   const registry = globalThis[CONTAINER_REGISTRY_SYMBOL];
@@ -34,126 +52,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 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 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(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 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 TestWoodError(
-      `Unknown ${method} replacement ${tokenLabel(token)} in the selected roots; register it with .main() or .renderer()`
-    );
-  }
-  if (ownsMain && ownsRenderer) {
-    throw new 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 importDefaultExport(
@@ -218,6 +116,7 @@ function assertNoGlobalContainerLeak(before, source) {
 }
 function createComposeContext(source, state, selection, operations, live) {
   return {
+    events: new RouterBridgeEvents(),
     configPath: source.configPath,
     configDir: source.configDir,
     config: source.config,
@@ -225,10 +124,10 @@ 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 TestWoodError("compose context call() is available from start() onward, not during compose");
       }
-      const router = live.router;
+      const router = live.router ?? (await live.runtime.main.acquire()).router;
       return await ExecutionContext.run(
         live.env.root,
         () => router.dispatch(operation, input)
@@ -236,34 +135,49 @@ function createComposeContext(source, state, selection, operations, live) {
     }
   };
 }
-function createAssemblyDisposer(live, mainRegistrations, rendererRegistrations, controllerScopes) {
+function createAssemblyDisposer(live, mainRegistrations, rendererRegistrations, controllerScopes, network) {
   let closing = null;
-  return () => closing ?? (closing = 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 = 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 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) {
   installWoodRuntime(inputs.mainRegistrations.root, {
@@ -275,14 +189,66 @@ 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 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 TestWoodError(`data loader ${reference.identity} (${reference.file}) has no default export`);
+      }
+      try {
+        loaders.set(reference.identity, assertDataLoader(mod.default, `data loader ${reference.identity}`));
+      } catch (error) {
+        throw new 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(Navigation);
-  registrations.declare(WOOD_FRONTEND_BRIDGE);
+  registrations.root.registerFunction(FETCH_RUNTIME, () => inputs.network, { owned: false, loadAs: LoadAs.Singleton });
+  registrations.declareBinding(Navigation, "singleton");
+  registrations.declareBinding(WOOD_FRONTEND_BRIDGE, "singleton");
+  const composePath = inputs.source.hookModule(inputs.source.config.renderer.compose);
+  if (composePath) {
+    const composeRenderer = await importDefaultExport(
+      inputs.state.importer,
+      composePath,
+      "renderer.compose"
+    );
+    if (typeof composeRenderer !== "function") {
+      throw new TestWoodError(`renderer.compose default export must be a function (${composePath})`);
+    }
+    await ExecutionContext.run(registrations.root, () => composeRenderer(registrations.root));
+  }
   await ExecutionContext.run(
     registrations.root,
     () => inputs.live.composed?.configureRendererRoot?.(registrations.root)
@@ -299,62 +265,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(testIoc(), explicitMain))
-  ]);
-  const rendererOwners = /* @__PURE__ */ new Set([
-    ...inputs.rendererRegistrations?.owners ?? [],
-    ...ownerTokens(applyCalls(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: describeTestBindings(testIoc().use(inputs.mainRegistrations.module()), [...controllers.main.values()]),
+    middleware: selectedMiddleware(inputs.operations),
+    loaders: []
+  }];
+  if (inputs.rendererRegistrations && inputs.catalog) {
+    catalogs.push({
+      owner: "renderer",
+      bindings: describeTestBindings(testIoc().use(inputs.rendererRegistrations.module()), [...controllers.renderer.values()]),
+      middleware: [],
+      loaders: rendererLoaderReferences(controllers.loaders)
+    });
+  }
+  const overlays = resolveTestOverlays(inputs.state.overlays, catalogs);
+  const mainPlan = applyTestBindings(testIoc(), overlays, "main");
+  const rendererPlan = applyTestBindings(testIoc(), overlays, "renderer");
   return {
-    main: applyCalls(testIoc(), routedMain),
-    renderer: applyCalls(testIoc(), [...inputs.state.rendererCalls, ...routedRenderer])
+    main: mainPlan.builder,
+    mainBorrowed: mainPlan.buildOptions.borrowedTokens ?? [],
+    renderer: rendererPlan.builder,
+    rendererBorrowed: rendererPlan.buildOptions.borrowedTokens ?? [],
+    overlays,
+    executables: {
+      main: createTestExecutables(overlays, "main"),
+      renderer: 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 TestWoodError(`this testWood environment was disposed before its ${stage} runtime was used`);
+  }
+}
+function assertRuntimeMayContinue(inputs, stage) {
+  if (inputs.live.disposed) {
+    throw new 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(
+    ExecutionContext.run(root, () => root.get(WoodRouter))
+  );
+  inputs.live.router = router;
+  assertRuntimeMayContinue(inputs, "main");
+  await 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 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 LazyRuntimeStage(() => initializeMainRuntime(inputs), rollback);
+  const rendererStage = renderer ? new LazyRuntimeStage(() => initializeRendererRuntime(inputs, main, renderer), rollback) : null;
+  return { main, renderer: rendererStage };
+}
 async function materializeEnvironment(inputs) {
+  inputs.mainRegistrations.root.registerFunction(FETCH_RUNTIME, () => inputs.network, { owned: false, loadAs: 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 buildRecordedEnvironment(ioc.main, inputs.mainRegistrations, "main");
+  const ioc = buildAssemblyIoc(inputs, controllers);
+  inputs.live.executables = ioc.executables;
+  inputs.live.env = await buildRecordedEnvironment(ioc.main, inputs.mainRegistrations, "main", ioc.mainBorrowed);
   const root = inputs.live.env.root;
-  inputs.live.router = await Promise.resolve(
-    ExecutionContext.run(root, () => root.get(WoodRouter))
-  );
-  await ExecutionContext.run(root, () => inputs.live.composed?.start?.());
-  assertNoGlobalContainerLeak(inputs.registryBefore, inputs.source);
-  if (inputs.catalog && inputs.rendererRegistrations) {
-    inputs.live.renderer = await 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) {
@@ -362,35 +415,48 @@ async function rollbackEnvironment(error, dispose) {
       ...error instanceof TestWoodCleanupError ? error.failures : [],
       ...cleanupError instanceof TestWoodCleanupError ? cleanupError.failures : [{ owner: "build rollback", error: cleanupError }]
     ];
-    throw new TestWoodCleanupError("testWood build failed and rollback failed", failures, error);
+    throw new TestWoodCleanupError(message, failures, error);
   }
   throw error;
 }
-async function assembleEnvironment(state, selection) {
+async function assembleEnvironment(state, selected) {
   const source = loadWoodConfigSource(state.configPath);
+  let selection = selected ?? resolveSelection(
+    Object.fromEntries(DECLARED_OWNERS.filter((owner) => source.config[owner]).map((owner) => [owner, {}]))
+  );
   const operations = selectOperations(source.operations, selection.main);
-  const catalog = selection.pages ? selectCatalog(source.views(), selection.pages) : null;
-  if (!catalog && state.rendererCalls.length) {
-    throw new TestWoodError(".renderer() composition requires a selected pages tier");
+  const catalog = selectRendererCatalog(source.views, selection);
+  if (state.browserHost && !catalog) {
+    throw new TestWoodError("browser() requires a selected renderer owner; add renderer to select()");
   }
+  if (state.browserHost && stubEntries(state.overlays).some((entry) => entry.kind === "load" || entry.owner === "renderer")) {
+    throw new 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 = createTestFetch(state.fetchConfigurations.flatMap(defineFetchRoutes));
   const registryBefore = globalRegistrySize();
-  const mainRegistrations = new RegistrationOnlyRoot("main.testing.compose");
-  const rendererRegistrations = catalog ? new RegistrationOnlyRoot("configureRendererRoot") : null;
+  const mainRegistrations = new RegistrationOnlyRoot("main.testing.compose", source.configPath);
+  const rendererRegistrations = catalog && !state.browserHost ? new 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,
@@ -410,24 +476,52 @@ 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 = lazyMember(
+    "router",
+    runtime.main.map((main) => main.router),
+    ["dispatch"],
+    "await call()/get()/controller() first"
+  );
+  const frontend = runtime.renderer ? lazyMember(
+    "frontend",
+    runtime.renderer.map((tier) => tier.frontend),
+    ["open", "act", "settle", "dispose"],
+    OPEN_FIRST
+  ) : null;
+  const rendererRoot = runtime.renderer ? lazyMember(
+    "rendererRoot",
+    runtime.renderer.map((tier) => tier.rendererRoot),
+    ["get", "dispose"],
+    OPEN_FIRST
+  ) : null;
+  const dispatchOperation = async (operation, input) => {
+    if (!operations.has(operation)) {
+      throw new TestWoodError(
+        `operation "${operation}" is not in the selected aperture; available operations:
+  ${[...operations.keys()].join("\n  ")}`
+      );
+    }
+    const { router: live } = await runtime.main.acquire();
+    return await ExecutionContext.run(root, () => live.dispatch(operation, input));
+  };
+  const api = createOperationApi(allOperations.keys(), dispatchOperation);
   return {
     root,
     router,
     operations,
-    call: async (operation, input) => {
-      if (!operations.has(operation)) {
-        throw new TestWoodError(
-          `operation "${operation}" is not in the selected aperture; available operations:
-  ${[...operations.keys()].join("\n  ")}`
-        );
-      }
-      return await 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;
@@ -442,41 +536,54 @@ function environmentSurface(parts) {
       guardControllerLifecycleOnce(instance);
       return instance;
     },
-    get: async (token) => await root.get(token),
+    get: async (token) => {
+      await runtime.main.acquire();
+      return await 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 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 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  ")
         );
       }
     },
@@ -495,60 +602,79 @@ class TestWoodBuilder {
     return new TestWoodBuilder({
       configPath: path.resolve(configPath),
       selection: null,
-      mainCalls: [],
-      rendererCalls: [],
-      importer: defaultImporter
+      browserHost: null,
+      fetchConfigurations: [],
+      importer: defaultImporter,
+      overlays: 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 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) {
-    resolveSelection(selection);
-    return this.derive({ selection });
+    const resolved = 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 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 TestStub)) throw new 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 TestWoodError("select() a tier before build(): { main }, { pages }, or both");
-    }
-    return assembleEnvironment(this.state, 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(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 ? resolveSelection(this.state.selection) : null);
   }
   derive(patch) {
     return new TestWoodBuilder({ ...this.state, ...patch });