@ecopages/react 0.2.0-alpha.1

package/src/utils/declared-modules.js

@@ -0,0 +1,56 @@
+function parseDeclaredModuleSource(value) {
+  const source = value.trim();
+  if (source.length === 0) return void 0;
+  const openBraceIndex = source.indexOf("{");
+  if (openBraceIndex < 0) return source;
+  const from = source.slice(0, openBraceIndex).trim();
+  return from.length > 0 ? from : void 0;
+}
+function normalizeDeclaredModuleSources(modules) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const declaration of modules ?? []) {
+    const from = parseDeclaredModuleSource(declaration);
+    if (from) {
+      seen.add(from);
+    }
+  }
+  return Array.from(seen);
+}
+function collectDeclaredModulesInConfig(config, visited = /* @__PURE__ */ new Set()) {
+  if (!config || visited.has(config)) {
+    return [];
+  }
+  visited.add(config);
+  const declarations = normalizeDeclaredModuleSources(config.dependencies?.modules);
+  if (config.layout?.config) {
+    declarations.push(...collectDeclaredModulesInConfig(config.layout.config, visited));
+  }
+  for (const component of config.dependencies?.components ?? []) {
+    if (component.config) {
+      declarations.push(...collectDeclaredModulesInConfig(component.config, visited));
+    }
+  }
+  return declarations;
+}
+function collectPageDeclaredModulesFromModule(pageModule) {
+  const declarations = [
+    ...collectDeclaredModulesInConfig(pageModule.default?.config),
+    ...collectDeclaredModulesInConfig(pageModule.config)
+  ];
+  return Array.from(new Set(declarations));
+}
+async function collectPageDeclaredModules(pagePath) {
+  try {
+    const pageModule = await import(pagePath);
+    return collectPageDeclaredModulesFromModule(pageModule);
+  } catch {
+    return [];
+  }
+}
+export {
+  collectDeclaredModulesInConfig,
+  collectPageDeclaredModules,
+  collectPageDeclaredModulesFromModule,
+  normalizeDeclaredModuleSources,
+  parseDeclaredModuleSource
+};

package/src/utils/declared-modules.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared utilities for collecting declared module sources from component configs.
+ * Used by both the production ReactRenderer and the HMR strategy to ensure
+ * the client-graph-boundary plugin receives a consistent set of allowed modules.
+ *
+ * @module
+ */
+
+import type { EcoComponentConfig } from '@ecopages/core';
+
+type PageConfigModule = {
+	default?: { config?: EcoComponentConfig };
+	config?: EcoComponentConfig;
+};
+
+/**
+ * Extracts the module source (package name) from a declared module string,
+ * stripping any `{namedImport,...}` grammar.
+ *
+ * @example
+ * parseDeclaredModuleSource('@ecopages/image-processor/component/react{EcoImage}')
+ * // → '@ecopages/image-processor/component/react'
+ */
+export function parseDeclaredModuleSource(value: string): string | undefined {
+	const source = value.trim();
+	if (source.length === 0) return undefined;
+	const openBraceIndex = source.indexOf('{');
+	if (openBraceIndex < 0) return source;
+	const from = source.slice(0, openBraceIndex).trim();
+	return from.length > 0 ? from : undefined;
+}
+
+/**
+ * Normalizes an array of declared module strings into unique source paths.
+ */
+export function normalizeDeclaredModuleSources(modules?: string[]): string[] {
+	const seen = new Set<string>();
+	for (const declaration of modules ?? []) {
+		const from = parseDeclaredModuleSource(declaration);
+		if (from) {
+			seen.add(from);
+		}
+	}
+	return Array.from(seen);
+}
+
+/**
+ * Recursively walks a component config tree (including layouts and nested
+ * `dependencies.components`) to collect all declared module sources.
+ */
+export function collectDeclaredModulesInConfig(
+	config: EcoComponentConfig | undefined,
+	visited = new Set<EcoComponentConfig>(),
+): string[] {
+	if (!config || visited.has(config)) {
+		return [];
+	}
+
+	visited.add(config);
+
+	const declarations = normalizeDeclaredModuleSources(config.dependencies?.modules);
+
+	if (config.layout?.config) {
+		declarations.push(...collectDeclaredModulesInConfig(config.layout.config, visited));
+	}
+
+	for (const component of config.dependencies?.components ?? []) {
+		if (component.config) {
+			declarations.push(...collectDeclaredModulesInConfig(component.config, visited));
+		}
+	}
+
+	return declarations;
+}
+
+/**
+ * Collects declared module sources from an already imported page module.
+ */
+export function collectPageDeclaredModulesFromModule(pageModule: PageConfigModule): string[] {
+	const declarations = [
+		...collectDeclaredModulesInConfig(pageModule.default?.config),
+		...collectDeclaredModulesInConfig(pageModule.config),
+	];
+
+	return Array.from(new Set(declarations));
+}
+
+/**
+ * Imports a page entrypoint and collects all transitively declared module sources
+ * from its config, layout config, and nested component configs.
+ */
+export async function collectPageDeclaredModules(pagePath: string): Promise<string[]> {
+	try {
+		const pageModule = (await import(pagePath)) as PageConfigModule;
+		return collectPageDeclaredModulesFromModule(pageModule);
+	} catch {
+		return [];
+	}
+}

package/src/utils/dynamic.d.ts

@@ -0,0 +1,15 @@
+import { type ComponentType, type LazyExoticComponent } from 'react';
+/**
+ * Dynamically loads a React component with optional SSR support.
+ *
+ * @param importFn - Function returning a promise that resolves to a React component.
+ * @param options - Options for SSR behavior.
+ * @returns Lazy loaded component or a null fallback for non-client environments.
+ */
+type DynamicLoaderOptions = {
+    ssr?: boolean;
+};
+export declare function dynamic(importFn: () => Promise<{
+    default: ComponentType<any>;
+}>, options?: DynamicLoaderOptions): LazyExoticComponent<ComponentType<any>> | ComponentType;
+export {};

package/src/utils/dynamic.js

@@ -0,0 +1,12 @@
+import { lazy } from "react";
+const NullComponent = () => null;
+function dynamic(importFn, options = {}) {
+  const { ssr = false } = options;
+  if (ssr || typeof window !== "undefined") {
+    return lazy(importFn);
+  }
+  return NullComponent;
+}
+export {
+  dynamic
+};

package/src/utils/dynamic.ts

@@ -0,0 +1,27 @@
+import { type ComponentType, type LazyExoticComponent, lazy } from 'react';
+
+/**
+ * Dynamically loads a React component with optional SSR support.
+ *
+ * @param importFn - Function returning a promise that resolves to a React component.
+ * @param options - Options for SSR behavior.
+ * @returns Lazy loaded component or a null fallback for non-client environments.
+ */
+type DynamicLoaderOptions = {
+	ssr?: boolean;
+};
+
+const NullComponent: ComponentType = () => null;
+
+export function dynamic(
+	importFn: () => Promise<{ default: ComponentType<any> }>,
+	options: DynamicLoaderOptions = {},
+): LazyExoticComponent<ComponentType<any>> | ComponentType {
+	const { ssr = false } = options;
+
+	if (ssr || typeof window !== 'undefined') {
+		return lazy(importFn);
+	}
+
+	return NullComponent;
+}

package/src/utils/hmr-scripts.d.ts

@@ -0,0 +1,18 @@
+/**
+ * HMR script utilities for React components.
+ * @module
+ */
+/**
+ * Checks if code has already been processed with HMR marker.
+ * @param code - The bundled code to check
+ * @returns True if the code already contains the HMR marker
+ */
+export declare function hasHmrMarker(code: string): boolean;
+/**
+ * Injects HMR acceptance handler into bundled code.
+ * When a module with React exports changes, it triggers a full invalidation
+ * to ensure the parent module re-imports and re-renders with the updated component.
+ * @param code - The bundled code to wrap
+ * @returns Code with HMR handler injected
+ */
+export declare function injectHmrHandler(code: string): string;

package/src/utils/hmr-scripts.js

@@ -0,0 +1,31 @@
+const HMR_MARKER = "/* [ecopages] react-hmr */";
+function hasHmrMarker(code) {
+  return code.includes(HMR_MARKER);
+}
+function injectHmrHandler(code) {
+  return `${HMR_MARKER}
+${code}
+if (import.meta.hot) {
+  import.meta.hot.accept((newModule) => {
+    if (newModule) {
+      const exports = Object.keys(newModule);
+      const hasReactExport = exports.some(key => {
+        const value = newModule[key];
+        return value && (
+          typeof value === 'function' ||
+          (typeof value === 'object' && value.$$typeof)
+        );
+      });
+      
+      if (hasReactExport) {
+        import.meta.hot.invalidate();
+      }
+    }
+  });
+}
+`;
+}
+export {
+  hasHmrMarker,
+  injectHmrHandler
+};

package/src/utils/hmr-scripts.ts

@@ -0,0 +1,47 @@
+/**
+ * HMR script utilities for React components.
+ * @module
+ */
+
+/** Marker comment to identify already-processed HMR code */
+const HMR_MARKER = '/* [ecopages] react-hmr */';
+
+/**
+ * Checks if code has already been processed with HMR marker.
+ * @param code - The bundled code to check
+ * @returns True if the code already contains the HMR marker
+ */
+export function hasHmrMarker(code: string): boolean {
+	return code.includes(HMR_MARKER);
+}
+
+/**
+ * Injects HMR acceptance handler into bundled code.
+ * When a module with React exports changes, it triggers a full invalidation
+ * to ensure the parent module re-imports and re-renders with the updated component.
+ * @param code - The bundled code to wrap
+ * @returns Code with HMR handler injected
+ */
+export function injectHmrHandler(code: string): string {
+	return `${HMR_MARKER}
+${code}
+if (import.meta.hot) {
+  import.meta.hot.accept((newModule) => {
+    if (newModule) {
+      const exports = Object.keys(newModule);
+      const hasReactExport = exports.some(key => {
+        const value = newModule[key];
+        return value && (
+          typeof value === 'function' ||
+          (typeof value === 'object' && value.$$typeof)
+        );
+      });
+      
+      if (hasReactExport) {
+        import.meta.hot.invalidate();
+      }
+    }
+  });
+}
+`;
+}

package/src/utils/html-boundary.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns true when HTML contains exactly one root element node.
+ *
+ * Used by component-level React rendering to decide whether root attributes can
+ * be attached safely without introducing synthetic wrapper nodes.
+ */
+export declare function hasSingleRootElement(html: string): boolean;

package/src/utils/html-boundary.js

@@ -0,0 +1,55 @@
+const VOID_TAGS = /* @__PURE__ */ new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+]);
+function hasSingleRootElement(html) {
+  const firstTagMatch = html.match(/^\s*<([a-zA-Z][a-zA-Z0-9:-]*)\b[^>]*>/);
+  if (!firstTagMatch) {
+    return false;
+  }
+  const firstTag = firstTagMatch[1].toLowerCase();
+  const firstTagText = firstTagMatch[0];
+  const firstTagStart = firstTagMatch.index ?? 0;
+  const firstTagEnd = firstTagStart + firstTagText.length;
+  const isSelfClosing = /\/\s*>$/.test(firstTagText);
+  if (isSelfClosing || VOID_TAGS.has(firstTag)) {
+    return html.slice(firstTagEnd).trim().length === 0;
+  }
+  const tokenRegex = /<\/?([a-zA-Z][a-zA-Z0-9:-]*)\b[^>]*>/g;
+  tokenRegex.lastIndex = firstTagEnd;
+  let depth = 1;
+  for (let token = tokenRegex.exec(html); token; token = tokenRegex.exec(html)) {
+    const tagText = token[0];
+    const tagName = token[1].toLowerCase();
+    const isClosing = tagText.startsWith("</");
+    const tokenSelfClosing = /\/\s*>$/.test(tagText);
+    if (VOID_TAGS.has(tagName) || tokenSelfClosing) {
+      continue;
+    }
+    if (isClosing) {
+      depth--;
+      if (depth === 0) {
+        const afterRoot = html.slice(token.index + token[0].length).trim();
+        return afterRoot.length === 0;
+      }
+    } else {
+      depth++;
+    }
+  }
+  return false;
+}
+export {
+  hasSingleRootElement
+};

package/src/utils/html-boundary.ts

@@ -0,0 +1,66 @@
+const VOID_TAGS = new Set([
+	'area',
+	'base',
+	'br',
+	'col',
+	'embed',
+	'hr',
+	'img',
+	'input',
+	'link',
+	'meta',
+	'param',
+	'source',
+	'track',
+	'wbr',
+]);
+
+/**
+ * Returns true when HTML contains exactly one root element node.
+ *
+ * Used by component-level React rendering to decide whether root attributes can
+ * be attached safely without introducing synthetic wrapper nodes.
+ */
+export function hasSingleRootElement(html: string): boolean {
+	const firstTagMatch = html.match(/^\s*<([a-zA-Z][a-zA-Z0-9:-]*)\b[^>]*>/);
+	if (!firstTagMatch) {
+		return false;
+	}
+
+	const firstTag = firstTagMatch[1].toLowerCase();
+	const firstTagText = firstTagMatch[0];
+	const firstTagStart = firstTagMatch.index ?? 0;
+	const firstTagEnd = firstTagStart + firstTagText.length;
+	const isSelfClosing = /\/\s*>$/.test(firstTagText);
+
+	if (isSelfClosing || VOID_TAGS.has(firstTag)) {
+		return html.slice(firstTagEnd).trim().length === 0;
+	}
+
+	const tokenRegex = /<\/?([a-zA-Z][a-zA-Z0-9:-]*)\b[^>]*>/g;
+	tokenRegex.lastIndex = firstTagEnd;
+	let depth = 1;
+
+	for (let token = tokenRegex.exec(html); token; token = tokenRegex.exec(html)) {
+		const tagText = token[0];
+		const tagName = token[1].toLowerCase();
+		const isClosing = tagText.startsWith('</');
+		const tokenSelfClosing = /\/\s*>$/.test(tagText);
+
+		if (VOID_TAGS.has(tagName) || tokenSelfClosing) {
+			continue;
+		}
+
+		if (isClosing) {
+			depth--;
+			if (depth === 0) {
+				const afterRoot = html.slice(token.index + token[0].length).trim();
+				return afterRoot.length === 0;
+			}
+		} else {
+			depth++;
+		}
+	}
+
+	return false;
+}

package/src/utils/hydration-scripts.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Hydration script generators for React pages.
+ * These functions create the client-side scripts that hydrate React components.
+ * @module
+ */
+import type { ReactRouterAdapter } from '../router-adapter.js';
+/**
+ * Options for generating a hydration script.
+ */
+export type HydrationScriptOptions = {
+    /** The import path for the bundled page component */
+    importPath: string;
+    /** Direct import path for React runtime module */
+    reactImportPath: string;
+    /** Direct import path for react-dom/client runtime module */
+    reactDomClientImportPath: string;
+    /** Direct import path for router runtime module */
+    routerImportPath?: string;
+    /** Whether running in development mode with HMR support */
+    isDevelopment: boolean;
+    /** Whether the source file is an MDX file */
+    isMdx: boolean;
+    /** Optional router adapter for SPA navigation */
+    router?: ReactRouterAdapter;
+};
+export type IslandHydrationScriptOptions = {
+    /** Bundled browser module path for the island component. */
+    importPath: string;
+    /** Browser import path for React runtime. */
+    reactImportPath: string;
+    /** Browser import path for react-dom/client runtime. */
+    reactDomClientImportPath: string;
+    /** Selector that resolves to the SSR root element for this island instance. */
+    targetSelector: string;
+    /** Serialized component props emitted at render time. */
+    props: Record<string, unknown>;
+    /** Optional stable component id used to resolve named exports reliably. */
+    componentRef?: string;
+    /** Optional source file hint used as fallback for component resolution. */
+    componentFile?: string;
+    /** Enables development-oriented non-minified output. */
+    isDevelopment: boolean;
+};
+/**
+ * Creates a hydration script for client-side React hydration.
+ * Generates appropriate script based on environment and router configuration.
+ * @param options - Configuration options for script generation
+ * @returns The generated hydration script as a string
+ */
+export declare function createHydrationScript(options: HydrationScriptOptions): string;
+/**
+ * Creates the client bootstrap for component-level React islands.
+ *
+ * The island runtime intentionally uses `createRoot()` (not `hydrateRoot()`) and
+ * mounts into the SSR element identified by `targetSelector`.
+ *
+ * Rationale:
+ * - No synthetic wrapper element is introduced in SSR output.
+ * - DOM structure remains identical to authored component markup.
+ * - Runtime ownership is isolated per island instance.
+ *
+ * Generated script behavior:
+ * - resolves the component export by metadata (`componentRef`, `componentFile`)
+ *   before falling back to default/first function export
+ * - selects island root using `targetSelector`
+ * - creates a fresh React root and renders with serialized `props`
+ *
+ * @param options Island script generation options.
+ * @returns Browser-executable JavaScript module source.
+ */
+export declare function createIslandHydrationScript(options: IslandHydrationScriptOptions): string;