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

package/src/plugins/tsconfig-import-resolver.js

@@ -1,159 +1,235 @@
-import { existsSync, readFileSync, realpathSync } from "node:fs";
-import path from "node:path";
-import { ResolverFactory } from "oxc-resolver";
-const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mdx"];
-const resolverCache = /* @__PURE__ */ new Map();
-const pathPrefixCache = /* @__PURE__ */ new Map();
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { ResolverFactory } from 'oxc-resolver';
+const RESOLVABLE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mdx'];
+const resolverCache = new Map();
+const pathPrefixCache = new Map();
 function stripJsonComments(source) {
-  return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+    return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
 }
 function findTsconfigPath(projectRoot) {
-  const candidate = path.join(projectRoot, "tsconfig.json");
-  return existsSync(candidate) ? candidate : void 0;
+    const candidate = path.join(projectRoot, 'tsconfig.json');
+    return existsSync(candidate) ? candidate : undefined;
 }
 function readJsonFile(filePath) {
-  const source = readFileSync(filePath, "utf8");
-  try {
-    return JSON.parse(source);
-  } catch {
-    return JSON.parse(stripJsonComments(source));
-  }
-}
-function loadTsconfigPathPrefixes(projectRoot) {
-  const cached = pathPrefixCache.get(projectRoot);
-  if (cached) {
-    return cached;
-  }
-  const tsconfigPath = findTsconfigPath(projectRoot);
-  if (!tsconfigPath) {
-    pathPrefixCache.set(projectRoot, []);
-    return [];
-  }
-  const prefixes = /* @__PURE__ */ new Set();
-  const visited = /* @__PURE__ */ new Set();
-  const collectFromConfig = (configPath) => {
-    const normalized = path.resolve(configPath);
-    if (visited.has(normalized)) {
-      return;
-    }
-    visited.add(normalized);
-    let config;
+    const source = readFileSync(filePath, 'utf8');
     try {
-      config = readJsonFile(normalized);
-    } catch {
-      return;
-    }
-    if (typeof config.extends === "string") {
-      const parentPath = path.resolve(path.dirname(normalized), config.extends);
-      collectFromConfig(parentPath);
-    }
-    for (const key of Object.keys(config.compilerOptions?.paths ?? {})) {
-      if (key.endsWith("/*")) {
-        prefixes.add(key.slice(0, -1));
-        continue;
-      }
-      if (key.endsWith("*")) {
-        prefixes.add(key.slice(0, -1));
-        continue;
-      }
-      prefixes.add(key);
-    }
-  };
-  collectFromConfig(tsconfigPath);
-  const resolvedPrefixes = [...prefixes];
-  pathPrefixCache.set(projectRoot, resolvedPrefixes);
-  return resolvedPrefixes;
+        return JSON.parse(source);
+    }
+    catch {
+        return JSON.parse(stripJsonComments(source));
+    }
 }
-function matchesTsconfigPathPrefix(specifier, prefixes) {
-  return prefixes.some((prefix) => {
-    if (prefix.endsWith("/")) {
-      return specifier.startsWith(prefix);
+/**
+ * Loads `compilerOptions.paths` keys from tsconfig, following `extends` recursively.
+ */
+export function loadTsconfigPathPrefixes(projectRoot) {
+    const cached = pathPrefixCache.get(projectRoot);
+    if (cached) {
+        return cached;
+    }
+    const tsconfigPath = findTsconfigPath(projectRoot);
+    if (!tsconfigPath) {
+        pathPrefixCache.set(projectRoot, []);
+        return [];
     }
-    return specifier === prefix || specifier.startsWith(`${prefix}/`);
-  });
+    const prefixes = new Set();
+    const visited = new Set();
+    const collectFromConfig = (configPath) => {
+        const normalized = path.resolve(configPath);
+        if (visited.has(normalized)) {
+            return;
+        }
+        visited.add(normalized);
+        let config;
+        try {
+            config = readJsonFile(normalized);
+        }
+        catch {
+            return;
+        }
+        if (typeof config.extends === 'string') {
+            const parentPath = path.resolve(path.dirname(normalized), config.extends);
+            collectFromConfig(parentPath);
+        }
+        for (const key of Object.keys(config.compilerOptions?.paths ?? {})) {
+            if (key.endsWith('/*')) {
+                prefixes.add(key.slice(0, -1));
+                continue;
+            }
+            if (key.endsWith('*')) {
+                prefixes.add(key.slice(0, -1));
+                continue;
+            }
+            prefixes.add(key);
+        }
+    };
+    collectFromConfig(tsconfigPath);
+    const resolvedPrefixes = [...prefixes];
+    pathPrefixCache.set(projectRoot, resolvedPrefixes);
+    return resolvedPrefixes;
 }
-function isBarePackageImportSpecifier(specifier, projectRoot) {
-  if (specifier.startsWith(".") || path.isAbsolute(specifier) || specifier.startsWith("/")) {
-    return false;
-  }
-  if (specifier.startsWith("node:") || specifier.startsWith("#") || specifier.includes(":")) {
-    return false;
-  }
-  if (projectRoot && matchesTsconfigPathPrefix(specifier, loadTsconfigPathPrefixes(projectRoot))) {
-    return false;
-  }
-  return true;
+export function matchesTsconfigPathPrefix(specifier, prefixes) {
+    return prefixes.some((prefix) => {
+        if (prefix.endsWith('/')) {
+            return specifier.startsWith(prefix);
+        }
+        return specifier === prefix || specifier.startsWith(`${prefix}/`);
+    });
+}
+/**
+ * Returns true when `specifier` looks like a bare npm package import rather than
+ * a relative path, absolute path, node built-in, tsconfig alias, or `#` import map.
+ */
+export function isBarePackageImportSpecifier(specifier, projectRoot) {
+    if (specifier.startsWith('.') || path.isAbsolute(specifier) || specifier.startsWith('/')) {
+        return false;
+    }
+    if (specifier.startsWith('node:') || specifier.startsWith('#') || specifier.includes(':')) {
+        return false;
+    }
+    if (projectRoot && matchesTsconfigPathPrefix(specifier, loadTsconfigPathPrefixes(projectRoot))) {
+        return false;
+    }
+    return true;
 }
 function getResolverFactory(projectRoot) {
-  const cached = resolverCache.get(projectRoot);
-  if (cached) {
-    return cached;
-  }
-  const tsconfigPath = findTsconfigPath(projectRoot);
-  if (!tsconfigPath) {
-    return void 0;
-  }
-  const resolver = new ResolverFactory({
-    tsconfig: {
-      configFile: tsconfigPath
-    },
-    extensions: [...RESOLVABLE_EXTENSIONS]
-  });
-  resolverCache.set(projectRoot, resolver);
-  return resolver;
+    const cached = resolverCache.get(projectRoot);
+    if (cached) {
+        return cached;
+    }
+    const tsconfigPath = findTsconfigPath(projectRoot);
+    if (!tsconfigPath) {
+        return undefined;
+    }
+    const resolver = new ResolverFactory({
+        tsconfig: {
+            configFile: tsconfigPath,
+        },
+        extensions: [...RESOLVABLE_EXTENSIONS],
+    });
+    resolverCache.set(projectRoot, resolver);
+    return resolver;
+}
+const BROWSER_PACKAGE_CONDITION_NAMES = ['browser', 'module', 'import', 'default'];
+const BROWSER_PACKAGE_MAIN_FIELDS = ['browser', 'module', 'main'];
+const browserPackageResolvers = new Map();
+function getBrowserPackageResolver(projectRoot) {
+    const normalizedRoot = path.resolve(projectRoot);
+    const cached = browserPackageResolvers.get(normalizedRoot);
+    if (cached) {
+        return cached;
+    }
+    const resolver = new ResolverFactory({
+        conditionNames: [...BROWSER_PACKAGE_CONDITION_NAMES],
+        mainFields: [...BROWSER_PACKAGE_MAIN_FIELDS],
+        extensions: [...RESOLVABLE_EXTENSIONS],
+    });
+    browserPackageResolvers.set(normalizedRoot, resolver);
+    return resolver;
+}
+/**
+ * Resolves a bare npm package entry for browser vendor prebundles.
+ *
+ * @remarks
+ * Prefer package `"browser"` / `"exports.browser"` over Node `"import"` entries.
+ * `createRequire().resolve()` is wrong here — it selects the server facade for
+ * dual packages such as `@ecopages/core`.
+ */
+export function resolveBarePackageBrowserEntry(projectRoot, specifier) {
+    const result = getBrowserPackageResolver(projectRoot).sync(projectRoot, specifier);
+    if (result.error || !result.path) {
+        return undefined;
+    }
+    try {
+        return realpathSync(result.path);
+    }
+    catch {
+        return result.path;
+    }
 }
 function resolveAliasedBarrelTarget(resolvedPath) {
-  if (!path.basename(resolvedPath).startsWith("index.")) {
-    return resolvedPath;
-  }
-  const source = readFileSync(resolvedPath, "utf8").trim();
-  const match = source.match(/^export\s+\*\s+from\s+['"]([^'"]+)['"]\s*;?$/);
-  if (!match?.[1]?.startsWith(".")) {
+    if (!path.basename(resolvedPath).startsWith('index.')) {
+        return resolvedPath;
+    }
+    const source = readFileSync(resolvedPath, 'utf8').trim();
+    const match = source.match(/^export\s+\*\s+from\s+['"]([^'"]+)['"]\s*;?$/);
+    if (!match?.[1]?.startsWith('.')) {
+        return resolvedPath;
+    }
+    const targetDir = path.dirname(resolvedPath);
+    const targetBase = path.resolve(targetDir, match[1]);
+    for (const extension of RESOLVABLE_EXTENSIONS) {
+        const candidate = `${targetBase}${extension}`;
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    for (const extension of RESOLVABLE_EXTENSIONS) {
+        const candidate = path.join(targetBase, `index${extension}`);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
     return resolvedPath;
-  }
-  const targetDir = path.dirname(resolvedPath);
-  const targetBase = path.resolve(targetDir, match[1]);
-  for (const extension of RESOLVABLE_EXTENSIONS) {
-    const candidate = `${targetBase}${extension}`;
-    if (existsSync(candidate)) {
-      return candidate;
-    }
-  }
-  for (const extension of RESOLVABLE_EXTENSIONS) {
-    const candidate = path.join(targetBase, `index${extension}`);
-    if (existsSync(candidate)) {
-      return candidate;
-    }
-  }
-  return resolvedPath;
 }
-function resolveProjectModulePath(projectRoot, fromFile, specifier) {
-  const prefixes = loadTsconfigPathPrefixes(projectRoot);
-  const isRelative = specifier.startsWith(".");
-  const isPathAlias = matchesTsconfigPathPrefix(specifier, prefixes);
-  if (!isRelative && !isPathAlias) {
-    return void 0;
-  }
-  const resolver = getResolverFactory(projectRoot);
-  if (!resolver) {
-    return void 0;
-  }
-  const result = resolver.sync(path.dirname(fromFile), specifier);
-  if (!result.path) {
-    return void 0;
-  }
-  return resolveAliasedBarrelTarget(realpathSync(result.path));
+/**
+ * Resolves a relative import against the filesystem without requiring tsconfig.
+ *
+ * @remarks
+ * Used when oxc-resolver has no tsconfig (minimal fixtures / apps without paths)
+ * and as a fallback when the resolver cannot locate a relative specifier.
+ */
+export function resolveRelativeModulePath(fromFile, specifier) {
+    if (!specifier.startsWith('.')) {
+        return undefined;
+    }
+    const targetBase = path.resolve(path.dirname(fromFile), specifier);
+    if (existsSync(targetBase)) {
+        return path.resolve(targetBase);
+    }
+    for (const candidateExtension of RESOLVABLE_EXTENSIONS) {
+        const candidate = `${targetBase}${candidateExtension}`;
+        if (existsSync(candidate)) {
+            return path.resolve(candidate);
+        }
+    }
+    for (const candidateExtension of RESOLVABLE_EXTENSIONS) {
+        const candidate = path.join(targetBase, `index${candidateExtension}`);
+        if (existsSync(candidate)) {
+            return path.resolve(candidate);
+        }
+    }
+    return undefined;
 }
-function resolveProjectImportPath(projectRoot, fromFile, specifier) {
-  if (!matchesTsconfigPathPrefix(specifier, loadTsconfigPathPrefixes(projectRoot))) {
-    return void 0;
-  }
-  return resolveProjectModulePath(projectRoot, fromFile, specifier);
+/**
+ * Resolves a relative or tsconfig path alias import (via oxc-resolver).
+ */
+export function resolveProjectModulePath(projectRoot, fromFile, specifier) {
+    const prefixes = loadTsconfigPathPrefixes(projectRoot);
+    const isRelative = specifier.startsWith('.');
+    const isPathAlias = matchesTsconfigPathPrefix(specifier, prefixes);
+    if (!isRelative && !isPathAlias) {
+        return undefined;
+    }
+    const resolver = getResolverFactory(projectRoot);
+    if (resolver) {
+        const result = resolver.sync(path.dirname(fromFile), specifier);
+        if (result.path) {
+            return resolveAliasedBarrelTarget(realpathSync(result.path));
+        }
+    }
+    if (isRelative) {
+        return resolveRelativeModulePath(fromFile, specifier);
+    }
+    return undefined;
+}
+/**
+ * Resolves a TS path alias import using the app's tsconfig `paths` (via oxc-resolver).
+ */
+export function resolveProjectImportPath(projectRoot, fromFile, specifier) {
+    if (!matchesTsconfigPathPrefix(specifier, loadTsconfigPathPrefixes(projectRoot))) {
+        return undefined;
+    }
+    return resolveProjectModulePath(projectRoot, fromFile, specifier);
 }
-export {
-  isBarePackageImportSpecifier,
-  loadTsconfigPathPrefixes,
-  matchesTsconfigPathPrefix,
-  resolveProjectImportPath,
-  resolveProjectModulePath
-};

package/src/route-renderer/README.md

@@ -41,6 +41,10 @@ Mixed-integration apps use two separate mechanisms:
 
 See [`../build/README.md`](../build/README.md) for the JSX ownership helper split.
 
+## Document shell composition
+
+`composeDocumentShell` in core is the single string-shell primitive for wrapping a primary component with optional layout tiers and an Html template. Integrations may supply an optional `composeChildren` hook to replace sequential string wrapping with a unified tree (for example React element children) while still delegating foreign subtrees through `renderComponentWithForeignChildren`.
+
 ## Main Files
 
 ### `route-renderer.ts`
@@ -63,6 +67,12 @@ Domain folders:
 - `route-pipeline/`: route preparation, final HTML capture, marker-artifact enforcement
 - `page-browser-graph/`: browser asset graph build, session cache, and injector assets
 
+**Page Browser Graph session behavior:**
+
+- In development, each Page Browser Graph is built on first request, cached in `page-browser-graph-session` with generation-safe commits, and invalidated when a tracked dependency changes. Hosts call `prepareHmrFileChange()` before HMR dispatch and defer client broadcasts when no browser subscribers are connected.
+- Production static export prebuilds browser graphs from the finalized route list into the in-memory `page-browser-graph-session` via `production-page-browser-graph-prebuild.ts`. Failed exports clear staged production session records so retries cannot reuse partial graph output.
+- Integrations activate lazily on first render or graph prebuild via `ensureIntegrationRuntimeReady()`. Processors and loaders still initialize eagerly during `setupAppRuntimePlugins()`.
+
 ### `page-loading/`
 
 - `page-module-loader.ts`: imports page modules and normalizes page exports
@@ -115,7 +125,8 @@ Not every integration needs queue-based handoff.
 ## React Island Notes
 
 - React islands are emitted without synthetic wrapper elements.
-- The React integration attaches `data-eco-component-id` to the SSR root when a single root exists.
+- The React integration attaches island host attributes (`data-eco-island`, `data-eco-component-id`, `data-eco-component-key`, `data-eco-props`) to the SSR root when a single root exists.
+- Other integrations call `finalizeIslandComponentRender()` from core when a component instance ships client scripts. See `packages/core/src/islands/README.md`.
 - The island bootstrap mounts with `createRoot()` into that SSR root.
 - Hydration bootstraps listen for `eco:after-swap` so islands hydrate after client-side navigation.