@ecopages/core 0.2.0-beta.3 → 0.2.0-beta.30

package/src/diagnostics/startup-trace.js

@@ -0,0 +1,253 @@
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { availableParallelism } from "node:os";
+import { fileSystem } from "@ecopages/file-system";
+const LOG_PREFIX = "[ecopages:startup-trace]";
+function isStartupTraceEnabled() {
+  return process.env.ECOPAGES_STARTUP_TRACE === "true" || process.env.ECOPAGES_LOGGER_DEBUG === "true";
+}
+function wallMsSinceProcessStart() {
+  return Math.round(process.uptime() * 1e3);
+}
+function resolveTraceBuildParallelism() {
+  const fromEnv = process.env.ECOPAGES_DEV_BUILD_PARALLELISM ?? process.env.ECOPAGES_DEV_HMR_PARALLELISM;
+  if (fromEnv) {
+    return fromEnv;
+  }
+  return String(Math.max(1, availableParallelism()));
+}
+function writeTraceLine(message) {
+  process.stderr.write(`${LOG_PREFIX} ${message}
+`);
+}
+function resolveStartupTraceJsonPath() {
+  const configured = process.env.ECOPAGES_STARTUP_TRACE_JSON?.trim();
+  return configured && configured.length > 0 ? configured : void 0;
+}
+class StartupTrace {
+  phaseNesting = /* @__PURE__ */ new Map();
+  phases = /* @__PURE__ */ new Map();
+  firstRequestPending = true;
+  firstRequestPath;
+  firstRequestBundleCount = 0;
+  firstRequestClientBytes = 0;
+  firstRequestGraphBuildCount = 0;
+  summaryEmitted = false;
+  firstPageBrowserGraphEmitted = false;
+  clientRequestCount = 0;
+  clientTransferredBytes = 0;
+  hmrConnected = false;
+  hydrationReadyMs = null;
+  isEnabled() {
+    return isStartupTraceEnabled();
+  }
+  markPhaseStart(phase) {
+    if (!isStartupTraceEnabled() || this.phases.has(phase)) {
+      return;
+    }
+    const nesting = this.phaseNesting.get(phase);
+    if (!nesting) {
+      this.phaseNesting.set(phase, { outerStart: performance.now(), depth: 1 });
+      return;
+    }
+    nesting.depth += 1;
+  }
+  markPhaseEnd(phase) {
+    if (!isStartupTraceEnabled() || this.phases.has(phase)) {
+      return;
+    }
+    const nesting = this.phaseNesting.get(phase);
+    if (!nesting) {
+      return;
+    }
+    nesting.depth -= 1;
+    if (nesting.depth > 0) {
+      return;
+    }
+    const durationMs = Math.round(performance.now() - nesting.outerStart);
+    const record = {
+      durationMs,
+      wallMs: wallMsSinceProcessStart()
+    };
+    this.phases.set(phase, record);
+    this.phaseNesting.delete(phase);
+    writeTraceLine(`phase=${phase} durationMs=${durationMs} wallMs=${record.wallMs}`);
+    this.writeJsonReport();
+  }
+  markConfigReady() {
+    if (!isStartupTraceEnabled() || this.phases.has("config-ready")) {
+      return;
+    }
+    const record = {
+      durationMs: 0,
+      wallMs: wallMsSinceProcessStart()
+    };
+    this.phases.set("config-ready", record);
+    writeTraceLine(`phase=config-ready wallMs=${record.wallMs} buildParallelism=${resolveTraceBuildParallelism()}`);
+    this.writeJsonReport();
+  }
+  markServerListening() {
+    this.markPhaseEnd("server-listen");
+  }
+  beginServerListen() {
+    this.markPhaseStart("server-listen");
+  }
+  markFirstByte() {
+    if (!isStartupTraceEnabled() || this.phases.has("first-byte")) {
+      return;
+    }
+    this.markPhaseEnd("first-byte");
+  }
+  beginFirstByte() {
+    this.markPhaseStart("first-byte");
+  }
+  markFirstPageBrowserGraphReady(graphBuildCount) {
+    if (!isStartupTraceEnabled() || this.firstPageBrowserGraphEmitted) {
+      return;
+    }
+    if (typeof graphBuildCount === "number") {
+      this.firstRequestGraphBuildCount = graphBuildCount;
+    }
+    this.firstPageBrowserGraphEmitted = true;
+    this.markPhaseEnd("first-page-browser-graph");
+  }
+  recordBrowserBundle(outputs) {
+    if (!isStartupTraceEnabled() || !this.firstRequestPending) {
+      return;
+    }
+    this.firstRequestBundleCount += 1;
+    for (const output of outputs) {
+      try {
+        if (fileSystem.exists(output.path)) {
+          this.firstRequestClientBytes += statSync(output.path).size;
+        }
+      } catch {
+      }
+    }
+  }
+  recordClientTransfer(requestCount, transferredBytes) {
+    if (!isStartupTraceEnabled()) {
+      return;
+    }
+    this.clientRequestCount = requestCount;
+    this.clientTransferredBytes = transferredBytes;
+    this.markPhaseEnd("client-transfer");
+  }
+  beginClientTransfer() {
+    this.markPhaseStart("client-transfer");
+  }
+  recordClientHydration(durationMs) {
+    if (!isStartupTraceEnabled()) {
+      return;
+    }
+    this.hydrationReadyMs = durationMs;
+    this.markPhaseEnd("client-hydration");
+  }
+  beginClientHydration() {
+    this.markPhaseStart("client-hydration");
+  }
+  recordHmrConnected() {
+    if (!isStartupTraceEnabled()) {
+      return;
+    }
+    this.hmrConnected = true;
+  }
+  async traceFirstRequest(request, handler) {
+    if (!isStartupTraceEnabled() || !this.firstRequestPending) {
+      return handler();
+    }
+    this.firstRequestPath = new URL(request.url).pathname;
+    this.markPhaseStart("first-page-browser-graph");
+    this.markPhaseStart("first-request-ssr");
+    try {
+      return await handler();
+    } finally {
+      this.markPhaseEnd("first-request-ssr");
+      this.emitFirstRequestSummary();
+      this.firstRequestPending = false;
+      this.writeJsonReport();
+    }
+  }
+  emitFirstRequestSummary() {
+    if (!isStartupTraceEnabled() || this.summaryEmitted) {
+      return;
+    }
+    this.summaryEmitted = true;
+    writeTraceLine(
+      [
+        "summary",
+        `path=${this.firstRequestPath ?? "unknown"}`,
+        `bundleCount=${this.firstRequestBundleCount}`,
+        `clientBundleBytes=${this.firstRequestClientBytes}`,
+        `graphBuildCount=${this.firstRequestGraphBuildCount}`,
+        `wallMs=${wallMsSinceProcessStart()}`
+      ].join(" ")
+    );
+  }
+  writeJsonReport() {
+    const outputPath = resolveStartupTraceJsonPath();
+    if (!outputPath) {
+      return;
+    }
+    const report = this.createReport();
+    mkdirSync(path.dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, JSON.stringify(report, null, 2), "utf-8");
+  }
+  createReport() {
+    const phases = {};
+    for (const [phase, record] of this.phases) {
+      phases[phase] = record;
+    }
+    return {
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      runtime: typeof Bun !== "undefined" ? `bun ${Bun.version}` : `node ${process.version}`,
+      platform: process.platform,
+      phases,
+      firstRequest: this.firstRequestPath ? {
+        path: this.firstRequestPath,
+        bundleCount: this.firstRequestBundleCount,
+        clientBundleBytes: this.firstRequestClientBytes,
+        graphBuildCount: this.firstRequestGraphBuildCount,
+        wallMs: wallMsSinceProcessStart()
+      } : void 0,
+      client: this.clientRequestCount > 0 || this.hydrationReadyMs !== null ? {
+        requestCount: this.clientRequestCount,
+        transferredBytes: this.clientTransferredBytes,
+        hmrConnected: this.hmrConnected,
+        hydrationReadyMs: this.hydrationReadyMs
+      } : void 0
+    };
+  }
+  /** Resets mutable trace state for unit tests. */
+  resetForTests() {
+    this.phaseNesting.clear();
+    this.phases.clear();
+    this.firstRequestPending = true;
+    this.firstRequestPath = void 0;
+    this.firstRequestBundleCount = 0;
+    this.firstRequestClientBytes = 0;
+    this.firstRequestGraphBuildCount = 0;
+    this.summaryEmitted = false;
+    this.firstPageBrowserGraphEmitted = false;
+    this.clientRequestCount = 0;
+    this.clientTransferredBytes = 0;
+    this.hmrConnected = false;
+    this.hydrationReadyMs = null;
+  }
+  /**
+   * Resets only the first-request bundle counters.
+   *
+   * @remarks
+   * Used by tests that need to re-measure first-request browser bundle work
+   * without clearing earlier startup phase records.
+   */
+  resetFirstRequestCounters() {
+    this.firstRequestBundleCount = 0;
+    this.firstRequestClientBytes = 0;
+    this.firstRequestGraphBuildCount = 0;
+  }
+}
+const startupTrace = new StartupTrace();
+export {
+  startupTrace
+};

package/src/eco/README.md

@@ -279,6 +279,17 @@ export default eco.page({
 });
 ```
 
+**Nested layouts (outer → inner):**
+
+```tsx
+export default eco.page({
+	layout: [MarketingShell, DocsShell],
+	render: () => <h1>Hello</h1>,
+});
+```
+
+A single layout remains equivalent to a one-element array. Normalization stores the stack on `config.layouts` and `config.layoutEntries` at factory time.
+
 ### `eco.component()`
 
 Define a reusable component with dependencies.

package/src/eco/eco-declared-component.d.ts

@@ -0,0 +1,14 @@
+import type { EcoDeclaredComponent } from '../types/public-types.js';
+export { getUndeclaredComponentDependencyMessage } from '../errors/undeclared-component-dependency-error.js';
+/**
+ * @remarks
+ * Declared components are produced by `eco.component()`, `eco.layout()`, and
+ * `eco.html()` after the component-meta plugin injects `config.__eco`.
+ */
+export declare function isEcoDeclaredComponent(component: unknown): component is EcoDeclaredComponent;
+/**
+ * @throws {UndeclaredComponentDependencyError} When the value lacks `config.__eco`.
+ */
+export declare function assertEcoDeclaredComponent(component: unknown, context?: {
+    parentComponentFile?: string;
+}): asserts component is EcoDeclaredComponent;

package/src/eco/eco-declared-component.js

@@ -0,0 +1,16 @@
+import { UndeclaredComponentDependencyError } from "../errors/undeclared-component-dependency-error.js";
+import { getUndeclaredComponentDependencyMessage } from "../errors/undeclared-component-dependency-error.js";
+function isEcoDeclaredComponent(component) {
+  return typeof component === "function" && typeof component.config?.__eco?.file === "string" && typeof component.config?.__eco?.integration === "string";
+}
+function assertEcoDeclaredComponent(component, context = {}) {
+  if (isEcoDeclaredComponent(component)) {
+    return;
+  }
+  throw new UndeclaredComponentDependencyError(context.parentComponentFile);
+}
+export {
+  assertEcoDeclaredComponent,
+  getUndeclaredComponentDependencyMessage,
+  isEcoDeclaredComponent
+};

package/src/eco/eco.browser.js

@@ -1,3 +1,4 @@
+import { applyPageLayoutConfig, mergeLayoutDependencies, normalizePageLayouts } from "./page-layout-normalization.js";
 function createComponentFactory(options) {
   const component2 = ((props) => options.render(props));
   component2.config = {
@@ -32,17 +33,15 @@ function page(options) {
     requires,
     middleware
   } = options;
+  const layoutEntries = normalizePageLayouts(pageLayout);
   const pageComponent = createComponentFactory({
     __eco: options.__eco,
     integration: options.integration,
-    dependencies: pageLayout ? {
-      ...dependencies,
-      components: [...dependencies?.components ?? [], pageLayout]
-    } : dependencies,
+    dependencies: mergeLayoutDependencies(dependencies, layoutEntries),
     render
   });
-  if (pageLayout && pageComponent.config) {
-    pageComponent.config.layout = pageLayout;
+  if (pageComponent.config) {
+    applyPageLayoutConfig(pageComponent.config, layoutEntries);
   }
   if (staticPaths2) {
     pageComponent.staticPaths = staticPaths2;

package/src/eco/eco.js

@@ -2,8 +2,9 @@ import {
   finalizeComponentRender,
   getComponentRenderContext,
   interceptForeignChild
-} from "../route-renderer/orchestration/component-render-context.js";
-import { isThenable } from "../route-renderer/orchestration/render-output.utils.js";
+} from "../route-renderer/orchestration/foreign-child/component-render-context.js";
+import { isThenable } from "../route-renderer/orchestration/foreign-child/foreign-child-output.utils.js";
+import { applyPageLayoutConfig, mergeLayoutDependencies, normalizePageLayouts } from "./page-layout-normalization.js";
 function createComponentFactory(options) {
   const integrationName = options.integration ?? options.__eco?.integration;
   const comp = ((props) => {
@@ -74,18 +75,16 @@ function layout(options) {
 }
 function page(options) {
   const { layout: layout2, dependencies, render, staticPaths: staticPaths2, staticProps: staticProps2, metadata: metadata2, cache, requires, middleware } = options;
+  const layoutEntries = normalizePageLayouts(layout2);
   const componentOptions = {
     __eco: options.__eco,
     integration: options.integration,
-    dependencies: layout2 ? {
-      ...dependencies,
-      components: [...dependencies?.components || [], layout2]
-    } : dependencies,
+    dependencies: mergeLayoutDependencies(dependencies, layoutEntries),
     render
   };
   const pageComponent = createComponentFactory(componentOptions);
-  if (layout2 && pageComponent.config) {
-    pageComponent.config.layout = layout2;
+  if (pageComponent.config) {
+    applyPageLayoutConfig(pageComponent.config, layoutEntries);
   }
   if (staticPaths2) pageComponent.staticPaths = staticPaths2;
   if (staticProps2) pageComponent.staticProps = staticProps2;

package/src/eco/eco.types.d.ts

@@ -2,7 +2,7 @@
  * Type definitions for the eco namespace API
  * @module
  */
-import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayoutComponent, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext } from '../types/public-types.js';
+import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayouts, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext } from '../types/public-types.js';
 import type { CacheStrategy } from '../services/cache/cache.types.js';
 /**
  * Extracts the props type from one eco component.
@@ -72,7 +72,18 @@ export interface ComponentOptions<P, E = EcoPagesElement> {
     render: (props: P) => E | Promise<E>;
 }
 export type HtmlOptions<E = EcoPagesElement> = ComponentOptions<HtmlTemplateProps, E>;
-export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E>;
+export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E> & {
+    /**
+     * Marks this layout as mounting shared client runtime state such as React context
+     * providers or query clients.
+     *
+     * @remarks
+     * When any layout in the app sets this flag, only flagged layouts participate in
+     * React auto-vendoring discovery. This keeps shell-only layouts out of provider
+     * scans while persisted SPA navigation stays on one shared vendor instance.
+     */
+    runtimeProvider?: boolean;
+};
 /**
  * Base options shared by all page variants
  */
@@ -81,7 +92,7 @@ export interface PageOptionsBase<T, E = EcoPagesElement> {
     __eco?: EcoInjectedMeta;
     integration?: string;
     dependencies?: EcoComponentDependencies;
-    layout?: EcoPageLayoutComponent<E>;
+    layout?: EcoPageLayouts<E>;
     /**
      * Define static paths for dynamic routes (e.g., [slug].tsx).
      * Returns all possible paths that should be pre-rendered at build time.

package/src/eco/eco.utils.d.ts

@@ -1 +1 @@
-export { addTriggerAttribute, isThenable, wrapWithScriptsInjector, } from '../route-renderer/orchestration/render-output.utils.js';
+export { addTriggerAttribute, isThenable, wrapWithScriptsInjector, } from '../route-renderer/orchestration/foreign-child/foreign-child-output.utils.js';

package/src/eco/eco.utils.js

@@ -2,7 +2,7 @@ import {
   addTriggerAttribute,
   isThenable,
   wrapWithScriptsInjector
-} from "../route-renderer/orchestration/render-output.utils.js";
+} from "../route-renderer/orchestration/foreign-child/foreign-child-output.utils.js";
 export {
   addTriggerAttribute,
   isThenable,

package/src/eco/page-layout-normalization.d.ts

@@ -0,0 +1,21 @@
+import type { EcoComponentConfig, EcoComponentDependencies, EcoPageLayoutEntry, EcoPageLayouts } from '../types/public-types.js';
+/**
+ * Normalizes `layout` page options to an outer→inner stack of layout entries.
+ */
+export declare function normalizePageLayouts<E>(layout?: EcoPageLayouts<E>): EcoPageLayoutEntry<E>[];
+/**
+ * Merges layout components into `dependencies.components` without duplicates.
+ */
+export declare function mergeLayoutDependencies(dependencies: EcoComponentDependencies | undefined, layoutEntries: EcoPageLayoutEntry[]): EcoComponentDependencies | undefined;
+/**
+ * Writes normalized layout metadata onto a page `config`.
+ */
+export declare function applyPageLayoutConfig(pageConfig: EcoComponentConfig, layoutEntries: EcoPageLayoutEntry[]): void;
+/**
+ * Migrates MDX-exported `config.layout` values onto normalized layout metadata.
+ *
+ * @remarks
+ * `eco.page({ layout })` already normalizes at factory time. MDX modules that
+ * export `config.layout` directly still need this import-time migration.
+ */
+export declare function ensurePageConfigLayouts(config: EcoComponentConfig | undefined): EcoComponentConfig | undefined;

package/src/eco/page-layout-normalization.js

@@ -0,0 +1,59 @@
+function isLayoutSpecObject(spec) {
+  return typeof spec === "object" && spec !== null && "component" in spec;
+}
+function normalizePageLayouts(layout) {
+  if (!layout) {
+    return [];
+  }
+  const specs = Array.isArray(layout) ? layout : [layout];
+  return specs.map((spec) => {
+    if (isLayoutSpecObject(spec)) {
+      return {
+        component: spec.component,
+        props: spec.props
+      };
+    }
+    return {
+      component: spec
+    };
+  });
+}
+function mergeLayoutDependencies(dependencies, layoutEntries) {
+  if (layoutEntries.length === 0) {
+    return dependencies;
+  }
+  const mergedComponents = [...dependencies?.components ?? []];
+  for (const entry of layoutEntries) {
+    if (!mergedComponents.includes(entry.component)) {
+      mergedComponents.push(entry.component);
+    }
+  }
+  return {
+    ...dependencies,
+    components: mergedComponents
+  };
+}
+function applyPageLayoutConfig(pageConfig, layoutEntries) {
+  if (layoutEntries.length === 0) {
+    return;
+  }
+  pageConfig.layouts = layoutEntries.map((entry) => entry.component);
+  pageConfig.layoutEntries = layoutEntries;
+}
+function ensurePageConfigLayouts(config) {
+  if (!config || config.layouts && config.layouts.length > 0) {
+    return config;
+  }
+  const legacyLayout = config.layout;
+  if (!legacyLayout) {
+    return config;
+  }
+  applyPageLayoutConfig(config, normalizePageLayouts(legacyLayout));
+  return config;
+}
+export {
+  applyPageLayoutConfig,
+  ensurePageConfigLayouts,
+  mergeLayoutDependencies,
+  normalizePageLayouts
+};

package/src/env.d.ts

@@ -3,6 +3,8 @@ interface EcopagesEnv {
 	ECOPAGES_HOSTNAME: string;
 	ECOPAGES_PORT: string;
 	ECOPAGES_LOGGER_DEBUG: 'true' | 'false';
+	/** When `true`, emits startup phase timings to stderr. Also enabled when `ECOPAGES_LOGGER_DEBUG=true`. */
+	ECOPAGES_STARTUP_TRACE?: 'true' | 'false';
 }
 
 declare global {

package/src/errors/index.d.ts

@@ -1,3 +1,4 @@
 export { HttpError } from './http-error.js';
 export type { HttpErrorDetails, HttpErrorJson } from './http-error.js';
 export { LocalsAccessError } from './locals-access-error.js';
+export { UndeclaredComponentDependencyError, getUndeclaredComponentDependencyMessage, } from './undeclared-component-dependency-error.js';

package/src/errors/index.js

@@ -1,6 +1,12 @@
 import { HttpError } from "./http-error.js";
 import { LocalsAccessError } from "./locals-access-error.js";
+import {
+  UndeclaredComponentDependencyError,
+  getUndeclaredComponentDependencyMessage
+} from "./undeclared-component-dependency-error.js";
 export {
   HttpError,
-  LocalsAccessError
+  LocalsAccessError,
+  UndeclaredComponentDependencyError,
+  getUndeclaredComponentDependencyMessage
 };

package/src/errors/undeclared-component-dependency-error.d.ts

@@ -0,0 +1,11 @@
+export declare function getUndeclaredComponentDependencyMessage(parentComponentFile?: string): string;
+/**
+ * Thrown when `dependencies.components` contains a plain function or component
+ * without plugin-injected `config.__eco` metadata.
+ */
+export declare class UndeclaredComponentDependencyError extends Error {
+    name: string;
+    /** Parent component file path when the invalid entry was declared. */
+    readonly parentComponentFile?: string;
+    constructor(parentComponentFile?: string);
+}

package/src/errors/undeclared-component-dependency-error.js

@@ -0,0 +1,17 @@
+function getUndeclaredComponentDependencyMessage(parentComponentFile) {
+  const parentHint = parentComponentFile ? ` (declared by ${parentComponentFile})` : "";
+  return `[ecopages] dependencies.components entries must be eco.component(), eco.layout(), or eco.html() components with __eco metadata${parentHint}. Plain functions and untyped components are not valid dependency entries.`;
+}
+class UndeclaredComponentDependencyError extends Error {
+  name = "UndeclaredComponentDependencyError";
+  /** Parent component file path when the invalid entry was declared. */
+  parentComponentFile;
+  constructor(parentComponentFile) {
+    super(getUndeclaredComponentDependencyMessage(parentComponentFile));
+    this.parentComponentFile = parentComponentFile;
+  }
+}
+export {
+  UndeclaredComponentDependencyError,
+  getUndeclaredComponentDependencyMessage
+};

package/src/hmr/client/hmr-runtime.js

@@ -12,7 +12,7 @@ import { getEcoNavigationRuntime } from "../../router/client/navigation-coordina
     socket.addEventListener("message", async (event) => {
       try {
         const payload = JSON.parse(event.data);
-        handleMessage(payload);
+        await handleMessage(payload);
       } catch (e) {
         console.error("[ecopages] Invalid HMR message:", e);
       }
@@ -29,12 +29,15 @@ import { getEcoNavigationRuntime } from "../../router/client/navigation-coordina
     switch (payload.type) {
       case "reload":
         await waitForNavigationToSettle(navigationRuntime);
+        if (window.__ECOPAGES_HOST_OWNS_RELOAD__) {
+          break;
+        }
         location.reload();
         break;
       case "layout-update": {
         await waitForNavigationToSettle(navigationRuntime);
         if (await navigationRuntime.reloadCurrentPage({ clearCache: true, moduleUrl: getActiveHmrModuleUrl() })) {
-        } else {
+        } else if (!window.__ECOPAGES_HOST_OWNS_RELOAD__) {
           location.reload();
         }
         break;
@@ -65,7 +68,7 @@ import { getEcoNavigationRuntime } from "../../router/client/navigation-coordina
         return;
       }
       await import(url);
-      if (await navigationRuntime.reloadCurrentPage({ clearCache: false })) {
+      if (await navigationRuntime.reloadCurrentPage({ clearCache: false, moduleUrl: url })) {
       }
     } catch (e) {
       console.error("[ecopages] Failed to apply HMR update:", e);
@@ -85,7 +88,7 @@ import { getEcoNavigationRuntime } from "../../router/client/navigation-coordina
     }
     await new Promise((resolve) => {
       const startedAt = performance.now();
-      const timeoutMs = 2e3;
+      const timeoutMs = 5e3;
       const poll = () => {
         if (!navigationRuntime.hasPendingNavigationTransaction()) {
           resolve();

package/src/hmr/hmr-entrypoint-output.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Verified HMR entrypoint artifact produced by registration.
+ */
+export interface ResolvedHmrEntrypoint {
+    sourcePath: string;
+    outputPath: string;
+    outputUrl: string;
+}
+/**
+ * Returns whether a source path is a registered client script HMR entrypoint.
+ */
+export declare function isRegisteredScriptEntrypoint(registered: ReadonlyMap<string, unknown>, filePath: string): boolean;
+/**
+ * Returns whether a registered script entrypoint is browser-only and must not be
+ * server-imported during HMR invalidation.
+ *
+ * @remarks
+ * Declared `*.script.ts` modules run only in the browser bundle. Re-importing them
+ * on the server during `prepareRegisteredScriptChange()` executes DOM globals and
+ * aborts the watcher before the client artifact rebuilds. Radiant `*.script.tsx`
+ * entrypoints are server-rendered and remain on the invalidation path.
+ */
+export declare function isBrowserOnlyRegisteredScriptEntrypoint(filePath: string): boolean;
+export declare function encodeHmrDynamicSegments(filepath: string): string;
+/**
+ * Resolves the on-disk and browser URL targets for one HMR script entrypoint.
+ */
+export declare function resolveHmrEntrypointOutputPaths(srcDir: string, distDir: string, entrypointPath: string): {
+    outputPath: string;
+    outputUrl: string;
+};
+/**
+ * @remarks
+ * Rebuilds must delete the previous artifact so browser-hmr does not reuse a
+ * stale bundle when the source file changed.
+ */
+export declare function removeStaleHmrEntrypointOutput(outputPath: string, scope: string): void;
+/**
+ * @remarks
+ * Guards against broadcasting reload/update before the bundler has flushed a
+ * fresher artifact than the edited source file.
+ */
+export declare function isHmrOutputFresh(outputPath: string, sourcePath: string): boolean;
+/**
+ * @remarks
+ * Missing output is treated as a benign rebuild race. This helper isolates the
+ * post-build case where a bundle exists but is still older than its source.
+ */
+export declare function isHmrOutputOlderThanSource(outputPath: string, sourcePath: string): boolean;