@ecopages/react 0.2.0-alpha.5 → 0.2.0-alpha.51

package/src/utils/hydration-scripts.test.browser.js

@@ -0,0 +1,198 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createHydrationScript } from "./hydration-scripts.js";
+const routerAdapter = {
+  name: "eco-router",
+  bundle: {
+    importPath: "/assets/router.js",
+    outputName: "router",
+    externals: []
+  },
+  components: {
+    router: "EcoRouter",
+    pageContent: "PageContent"
+  },
+  getRouterProps: (page, props) => `{ page: ${page}, pageProps: ${props} }`
+};
+function createModuleUrl(source) {
+  return `data:text/javascript;base64,${btoa(source)}`;
+}
+async function importModule(moduleUrl, scriptId) {
+  let marker;
+  if (scriptId) {
+    marker = document.createElement("script");
+    marker.setAttribute("data-eco-script-id", scriptId);
+    document.head.appendChild(marker);
+  }
+  await import(
+    /* @vite-ignore */
+    moduleUrl
+  );
+  marker?.remove();
+}
+function createRuntimeModules() {
+  const reactImportPath = createModuleUrl("export const createElement = (...args) => ({ args });");
+  const reactDomClientImportPath = createModuleUrl(`
+export const hydrateRoot = (container, tree, options) => {
+  const runtime = window.__ECO_REACT_HYDRATION_TEST__;
+  runtime.hydrateCalls.push({
+    containerTag: container.tagName,
+    hasRecoverableErrorHandler: typeof options?.onRecoverableError === "function",
+    tree,
+  });
+
+  return {
+    render() {},
+    unmount() {
+      runtime.unmountCount += 1;
+    },
+  };
+};
+`);
+  const importPath = createModuleUrl("export default function Page() { return null; }");
+  const routerImportPath = createModuleUrl(`
+export function EcoRouter(props) {
+  return props;
+}
+
+export function PageContent() {
+  return null;
+}
+`);
+  return {
+    importPath,
+    reactImportPath,
+    reactDomClientImportPath,
+    routerImportPath
+  };
+}
+describe("createHydrationScript browser execution", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    const testWindow = window;
+    delete testWindow.__ECO_PAGES__;
+    delete testWindow.__ECO_REACT_HYDRATION_TEST__;
+  });
+  it("registers router ownership and cleanup when the browser hydration bootstrap runs", async () => {
+    const runtimeModules = createRuntimeModules();
+    const testWindow = window;
+    testWindow.__ECO_REACT_HYDRATION_TEST__ = {
+      hydrateCalls: [],
+      renderCalls: [],
+      claimedOwners: [],
+      releasedOwners: [],
+      registrations: [],
+      unmountCount: 0
+    };
+    testWindow.__ECO_PAGES__ = {
+      navigation: {
+        getOwnerState: () => ({
+          owner: "html",
+          canHandleSpaNavigation: false
+        }),
+        register: (registration) => {
+          testWindow.__ECO_REACT_HYDRATION_TEST__?.registrations.push(registration);
+        },
+        claimOwnership: (owner) => {
+          testWindow.__ECO_REACT_HYDRATION_TEST__?.claimedOwners.push(owner);
+        },
+        releaseOwnership: (owner) => {
+          testWindow.__ECO_REACT_HYDRATION_TEST__?.releasedOwners.push(owner);
+        }
+      }
+    };
+    document.body.innerHTML = `<script id="__ECO_PAGE_DATA__" type="application/json">${JSON.stringify({
+      title: "Hello React",
+      locals: { theme: "dark" }
+    })}<\/script>`;
+    const script = createHydrationScript({
+      ...runtimeModules,
+      scriptId: "ecopages-react-page",
+      isDevelopment: true,
+      isMdx: false,
+      router: routerAdapter
+    });
+    const moduleUrl = createModuleUrl(script);
+    await importModule(moduleUrl, "ecopages-react-page");
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.hydrateCalls).toHaveLength(1);
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.hydrateCalls[0]?.containerTag).toBe("BODY");
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.hydrateCalls[0]?.hasRecoverableErrorHandler).toBe(true);
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.claimedOwners).toEqual(["react-router"]);
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.registrations).toHaveLength(1);
+    expect(typeof testWindow.__ECO_PAGES__?.react?.cleanupPageRoot).toBe("function");
+    expect(testWindow.__ECO_PAGES__?.page).toEqual({
+      module: moduleUrl,
+      props: {
+        title: "Hello React",
+        locals: { theme: "dark" }
+      }
+    });
+    await testWindow.__ECO_PAGES__?.react?.cleanupPageRoot?.();
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.unmountCount).toBe(1);
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.releasedOwners).toEqual(["react-router"]);
+    expect(testWindow.__ECO_PAGES__?.page).toBeUndefined();
+    expect(testWindow.__ECO_PAGES__?.react?.pageRoot).toBeNull();
+  });
+  it("reuses an existing router-owned page root during rerun bootstrap execution", async () => {
+    const runtimeModules = createRuntimeModules();
+    const testWindow = window;
+    testWindow.__ECO_REACT_HYDRATION_TEST__ = {
+      hydrateCalls: [],
+      renderCalls: [],
+      claimedOwners: [],
+      releasedOwners: [],
+      registrations: [],
+      unmountCount: 0
+    };
+    const existingRoot = {
+      render: (tree) => {
+        testWindow.__ECO_REACT_HYDRATION_TEST__?.renderCalls.push(tree);
+      },
+      unmount: () => {
+        testWindow.__ECO_REACT_HYDRATION_TEST__.unmountCount += 1;
+      }
+    };
+    testWindow.__ECO_PAGES__ = {
+      navigation: {
+        getOwnerState: () => ({
+          owner: "react-router",
+          canHandleSpaNavigation: true
+        }),
+        register: (registration) => {
+          testWindow.__ECO_REACT_HYDRATION_TEST__?.registrations.push(registration);
+        },
+        claimOwnership: (owner) => {
+          testWindow.__ECO_REACT_HYDRATION_TEST__?.claimedOwners.push(owner);
+        },
+        releaseOwnership: (owner) => {
+          testWindow.__ECO_REACT_HYDRATION_TEST__?.releasedOwners.push(owner);
+        }
+      },
+      react: {
+        pageRoot: existingRoot
+      }
+    };
+    document.body.innerHTML = `<script id="__ECO_PAGE_DATA__" type="application/json">${JSON.stringify({
+      title: "Rerun"
+    })}<\/script>`;
+    const script = createHydrationScript({
+      ...runtimeModules,
+      scriptId: "ecopages-react-page-rerun",
+      isDevelopment: true,
+      isMdx: false,
+      router: routerAdapter
+    });
+    const moduleUrl = createModuleUrl(script);
+    await importModule(moduleUrl, "ecopages-react-page-rerun");
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.hydrateCalls).toHaveLength(0);
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.renderCalls).toHaveLength(0);
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.claimedOwners).toHaveLength(0);
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.registrations).toHaveLength(0);
+    expect(testWindow.__ECO_PAGES__?.react?.pageRoot).toBe(existingRoot);
+    expect(testWindow.__ECO_PAGES__?.page).toEqual({
+      module: moduleUrl,
+      props: {
+        title: "Rerun"
+      }
+    });
+  });
+});

package/src/utils/react-dom-runtime-interop-plugin.d.ts

@@ -0,0 +1,5 @@
+import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
+export declare function createReactDomRuntimeInteropPlugin(options?: {
+    name?: string;
+    reactSpecifier?: string;
+}): EcoBuildPlugin;

package/src/utils/react-dom-runtime-interop-plugin.js

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import path from "node:path";
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function createReactDomRuntimeInteropPlugin(options) {
+  const reactDomFileFilter = /[\\/]react-dom[\\/].*\.js$/;
+  const reactRequirePattern = /\brequire\((['"])react\1\)/g;
+  const reactSpecifier = options?.reactSpecifier ?? "react";
+  return {
+    name: options?.name ?? "react-dom-runtime-interop",
+    setup(build) {
+      if (reactSpecifier.startsWith("/")) {
+        build.onResolve({ filter: new RegExp(`^${escapeRegExp(reactSpecifier)}$`) }, (args) => ({
+          path: args.path,
+          external: true
+        }));
+      }
+      build.onLoad({ filter: reactDomFileFilter }, (args) => {
+        const content = fs.readFileSync(args.path, "utf-8");
+        if (!reactRequirePattern.test(content)) {
+          return void 0;
+        }
+        reactRequirePattern.lastIndex = 0;
+        const rewritten = content.replace(reactRequirePattern, "__ecopages_react_runtime");
+        return {
+          contents: `import * as __ecopages_react_runtime from '${reactSpecifier}';
+${rewritten}`,
+          loader: "js",
+          resolveDir: path.dirname(args.path)
+        };
+      });
+    }
+  };
+}
+export {
+  createReactDomRuntimeInteropPlugin
+};

package/src/utils/react-mdx-loader-plugin.d.ts

@@ -1,3 +1,3 @@
-import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
 import { type CompileOptions } from '@mdx-js/mdx';
 export declare function createReactMdxLoaderPlugin(compilerOptions?: CompileOptions): EcoBuildPlugin;

package/src/utils/react-mdx-loader-plugin.js

@@ -1,11 +1,18 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { compile } from "@mdx-js/mdx";
-import { SourceMapGenerator } from "source-map";
+import sourceMap from "source-map";
 import { VFile } from "vfile";
+function resolveCompileFormat(filePath, compilerOptions) {
+  const configuredFormat = compilerOptions?.format;
+  if (configuredFormat && configuredFormat !== "detect") {
+    return configuredFormat;
+  }
+  return path.extname(filePath).toLowerCase() === ".md" ? "mdx" : configuredFormat;
+}
 function createReactMdxLoaderPlugin(compilerOptions) {
   const mdxExtensions = compilerOptions?.mdxExtensions ?? [".mdx"];
-  const mdExtensions = compilerOptions?.mdExtensions ?? [".md"];
+  const mdExtensions = compilerOptions?.mdExtensions ?? [];
   const allExtensions = [...mdxExtensions, ...mdExtensions];
   const escapedExts = allExtensions.map((ext) => ext.replace(".", "\\."));
   const filter = new RegExp(`(${escapedExts.join("|")})(\\?.*)?$`);
@@ -18,13 +25,14 @@ function createReactMdxLoaderPlugin(compilerOptions) {
         const file = new VFile({ path: filePath, value: source });
         const compiled = await compile(file, {
           ...compilerOptions,
-          SourceMapGenerator
+          format: resolveCompileFormat(filePath, compilerOptions),
+          SourceMapGenerator: sourceMap.SourceMapGenerator
         });
-        const sourceMap = compiled.map ? `
+        const inlineSourceMap = compiled.map ? `
 //# sourceMappingURL=data:application/json;base64,${Buffer.from(JSON.stringify(compiled.map)).toString("base64")}
 ` : "";
         return {
-          contents: `${String(compiled.value)}${sourceMap}`,
+          contents: `${String(compiled.value)}${inlineSourceMap}`,
           loader: compilerOptions?.jsx ? "jsx" : "js",
           resolveDir: path.dirname(args.path)
         };

package/src/utils/react-runtime-alias-map.d.ts

@@ -0,0 +1,8 @@
+import type { ReactRouterAdapter } from '../router-adapter.js';
+import type { ReactRuntimeImports } from '../services/react-runtime-bundle.service.js';
+import { type BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
+export declare const REACT_RUNTIME_SPECIFIERS: readonly ["react", "react-dom", "react/jsx-runtime", "react/jsx-dev-runtime", "react-dom/client"];
+export declare function buildReactRuntimeAliasMap(runtimeImports: ReactRuntimeImports): Record<string, string>;
+export declare function buildReactRuntimeManifest(runtimeImports: ReactRuntimeImports): BrowserRuntimeManifest;
+export declare function getReactRuntimeExternalSpecifiers(): string[];
+export declare function getReactClientGraphAllowSpecifiers(runtimeSpecifiers: Iterable<string>, routerAdapter?: ReactRouterAdapter): string[];

package/src/utils/react-runtime-alias-map.js

@@ -0,0 +1,90 @@
+import {
+  createBrowserRuntimeManifest,
+  getBrowserRuntimeSpecifierMap
+} from "@ecopages/core/build/browser-runtime-manifest";
+const REACT_RUNTIME_SPECIFIERS = [
+  "react",
+  "react-dom",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-dom/client"
+];
+function buildReactRuntimeAliasMap(runtimeImports) {
+  return Object.fromEntries(getBrowserRuntimeSpecifierMap(buildReactRuntimeManifest(runtimeImports)));
+}
+function buildReactRuntimeManifest(runtimeImports) {
+  return createBrowserRuntimeManifest([
+    {
+      specifier: "react",
+      owner: "@ecopages/react",
+      importPath: "react",
+      publicPath: runtimeImports.react
+    },
+    {
+      specifier: "react/jsx-runtime",
+      owner: "@ecopages/react",
+      importPath: "react/jsx-runtime",
+      publicPath: runtimeImports.reactJsxRuntime
+    },
+    {
+      specifier: "react/jsx-dev-runtime",
+      owner: "@ecopages/react",
+      importPath: "react/jsx-dev-runtime",
+      publicPath: runtimeImports.reactJsxDevRuntime
+    },
+    {
+      specifier: "react-dom",
+      owner: "@ecopages/react",
+      importPath: "react-dom",
+      publicPath: runtimeImports.reactDom
+    },
+    {
+      specifier: "react-dom/client",
+      owner: "@ecopages/react",
+      importPath: "react-dom/client",
+      publicPath: runtimeImports.reactDomClient
+    },
+    {
+      specifier: "use-sync-external-store/shim",
+      owner: "@ecopages/react",
+      importPath: "use-sync-external-store/shim",
+      publicPath: runtimeImports.react
+    },
+    {
+      specifier: "use-sync-external-store/shim/index.js",
+      owner: "@ecopages/react",
+      importPath: "use-sync-external-store/shim/index.js",
+      publicPath: runtimeImports.react
+    },
+    {
+      specifier: "use-sync-external-store/shim/with-selector",
+      owner: "@ecopages/react",
+      importPath: "use-sync-external-store/shim/with-selector",
+      publicPath: runtimeImports.useSyncExternalStoreWithSelector
+    },
+    {
+      specifier: "use-sync-external-store/shim/with-selector.js",
+      owner: "@ecopages/react",
+      importPath: "use-sync-external-store/shim/with-selector.js",
+      publicPath: runtimeImports.useSyncExternalStoreWithSelector
+    }
+  ]);
+}
+function getReactRuntimeExternalSpecifiers() {
+  return [...REACT_RUNTIME_SPECIFIERS];
+}
+function getReactClientGraphAllowSpecifiers(runtimeSpecifiers, routerAdapter) {
+  return [
+    "@ecopages/core",
+    ...REACT_RUNTIME_SPECIFIERS,
+    ...routerAdapter ? [routerAdapter.bundle.importPath] : [],
+    ...Array.from(runtimeSpecifiers)
+  ];
+}
+export {
+  REACT_RUNTIME_SPECIFIERS,
+  buildReactRuntimeAliasMap,
+  buildReactRuntimeManifest,
+  getReactClientGraphAllowSpecifiers,
+  getReactRuntimeExternalSpecifiers
+};

package/CHANGELOG.md

@@ -1,67 +0,0 @@
-# Changelog
-
-All notable changes to `@ecopages/react` are documented here.
-
-> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
-
-## [UNRELEASED] — TBD
-
-### Features
-
-#### Render Reachability Analysis
-
-- **Client render graph (Phase 1)** — Introduces a static reachability analysis step that builds an explicit graph of which components are rendered client-side (`cdfbd69e`).
-- **OXC-powered reachability analyzer** — `reachability-analyzer.ts` uses OXC to parse and walk component ASTs, building a `ClientRenderGraph` that maps exported components to their client-side reach (`5412df6b`).
-- **Explicit client graph boundaries** — Components must now declare explicit boundaries; the analyser enforces these to prevent over-hydration (`2912d6bd`).
-- **Declared modules utility** — `declared-modules.ts` tracks which modules are declared as client boundaries.
-
-#### Service Architecture Refactor
-
-- **`ReactRuntimeBundleService`** — Manages runtime assets and specifier mapping for the React integration (`cfd3cb05`).
-- **`ReactHydrationAssetService`** — Creates and manages hydration assets for client-side rendering (`cfd3cb05`).
-- **`ReactBundleService`** — Handles esbuild bundle configuration for React components (`cfd3cb05`).
-- **`ReactPageModuleService`** — Loads and compiles MDX/TSX page modules, including config resolution (`cfd3cb05`).
-- The integration no longer builds a monolithic renderer — each concern is handled by a focused service.
-
-#### HMR Improvements
-
-- **HMR page metadata caching** — Page metadata is now cached between HMR refreshes, preventing unnecessary re-fetches during Fast Refresh (`a663788c`).
-- **Stale temp module race fix** — HMR no longer incorrectly reads a stale temporary module during rapid refresh cycles (`b2cf8466`).
-- **Client graph HMR stability** — HMR reloads now correctly respect client graph boundaries to avoid partial hydration mismatches (`2912d6bd`).
-
-#### HTML Boundary Utilities
-
-- **`html-boundary.ts`** — New utility that wraps rendered output in explicit boundary markers for the cross-integration boundary rendering policy (`ec1e4d66`).
-- **`hydration-scripts.ts`** — Expanded with new helpers for generating and injecting hydration entry scripts.
-
-### Refactoring
-
-- Aligned React renderer to full orchestration mode — removed legacy rendering path (`fc07bdb0`).
-- Ambient module declarations cleaned up (`5f46ecc5`).
-- Client graph boundaries and runtime dependency wiring corrected (`4b6cd32e`).
-- Updated test suite for esbuild adapter and Node.js runtime compatibility (`31a44458`).
-
-### Bug Fixes
-
-- Inlined the React MDX loader so React apps no longer need to install `@ecopages/mdx` when enabling React MDX support (`unreleased`).
-- Fixed stale temp module race during Fast Refresh cycles (`b2cf8466`).
-- Fixed client graph boundary wiring for runtime dependencies (`4b6cd32e`).
-- Fixed shared React barrel handling so client-reachable server-only re-exports now fail the build instead of being silently pruned (`unreleased`).
-
-### Documentation
-
-- Documented the React integration server/client graph contract for shared modules and barrel exports (`unreleased`).
-
-### Tests
-
-- Added `html-boundary.test.ts` covering boundary wrapping utilities.
-- Added `hydration-scripts.test.ts` with hydration script generation coverage.
-- Added `reachability-analyzer.test.ts` (187 lines) covering export declaration reachability.
-- Updated integration tests for esbuild adapter compatibility (`31a44458`).
-
----
-
-## Migration Notes
-
-- The React integration now requires explicit client boundary declarations. Components that should be hydrated client-side must be marked at a boundary entry point.
-- The internal service layer (`ReactRuntimeBundleService`, `ReactBundleService`, etc.) is not part of the public API and may change between releases.