@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.41

package/src/plugins/source-transform.js

@@ -1,71 +1,123 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-function normalizeTransformId(id) {
-  const queryIndex = id.indexOf("?");
-  const hashIndex = id.indexOf("#");
-  const endIndex = [queryIndex, hashIndex].filter((index) => index >= 0).sort((left, right) => left - right)[0];
-  return endIndex === void 0 ? id : id.slice(0, endIndex);
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+/**
+ * Normalizes bundler module ids so one transform can serve Ecopages loaders,
+ * Vite, and future bundler adapters.
+ */
+export function normalizeTransformId(id) {
+    const queryIndex = id.indexOf('?');
+    const hashIndex = id.indexOf('#');
+    const endIndex = [queryIndex, hashIndex].filter((index) => index >= 0).sort((left, right) => left - right)[0];
+    return endIndex === undefined ? id : id.slice(0, endIndex);
 }
-function applySourceTransform(transform, code, id) {
-  const normalizedId = normalizeTransformId(id);
-  if (!transform.filter.test(normalizedId)) {
-    return void 0;
-  }
-  return transform.transform(code, normalizedId);
+/**
+ * Applies one source transform if the normalized id matches its filter.
+ */
+export function applySourceTransform(transform, code, id) {
+    const normalizedId = normalizeTransformId(id);
+    if (!transform.filter.test(normalizedId)) {
+        return undefined;
+    }
+    return transform.transform(code, normalizedId);
 }
-function inferLoaderFromPath(filePath) {
-  const extension = path.extname(filePath).toLowerCase();
-  switch (extension) {
-    case ".ts":
-      return "ts";
-    case ".tsx":
-      return "tsx";
-    case ".jsx":
-      return "jsx";
-    default:
-      return "js";
-  }
+const SOURCE_TRANSFORM_ENFORCE_ORDER = {
+    pre: 0,
+    default: 1,
+    post: 2,
+};
+function getSourceTransformEnforceOrder(transform) {
+    return SOURCE_TRANSFORM_ENFORCE_ORDER[transform.enforce ?? 'default'];
 }
-function createEcoBuildPluginFromSourceTransform(transform) {
-  return {
-    name: transform.name,
-    setup(build) {
-      build.onLoad({ filter: transform.filter }, (args) => {
-        const filePath = normalizeTransformId(args.path);
-        const code = fileSystem.readFileSync(filePath);
-        const result = applySourceTransform(transform, code, filePath);
+/**
+ * Applies app-owned source transforms in deterministic `pre` → default → `post` order.
+ *
+ * @remarks
+ * Used by the Rolldown plugin bridge after `onLoad` plugins produce final module
+ * contents. Transforms that do not match `filter` are skipped; matching transforms
+ * are chained left-to-right on the current source string.
+ *
+ * @param transforms - App-owned transforms, usually from {@link getAppSourceTransforms}.
+ * @param code - Current module source.
+ * @param id - Module id forwarded to each transform after query/hash normalization.
+ * @returns The transformed source, or the original `code` when no transform matches.
+ */
+export function applySourceTransforms(transforms, code, id) {
+    let current = code;
+    for (const transform of [...transforms].sort((left, right) => getSourceTransformEnforceOrder(left) - getSourceTransformEnforceOrder(right))) {
+        const result = applySourceTransform(transform, current, id);
         if (!result) {
-          return void 0;
+            continue;
         }
-        return {
-          contents: typeof result === "string" ? result : result.code,
-          loader: inferLoaderFromPath(filePath),
-          resolveDir: path.dirname(filePath)
-        };
-      });
+        current = typeof result === 'string' ? result : result.code;
     }
-  };
+    return current;
 }
-function createVitePluginFromSourceTransform(transform) {
-  return {
-    name: transform.name,
-    enforce: transform.enforce,
-    transform(code, id) {
-      return applySourceTransform(transform, code, id);
+function inferLoaderFromPath(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    switch (extension) {
+        case '.ts':
+            return 'ts';
+        case '.tsx':
+            return 'tsx';
+        case '.jsx':
+            return 'jsx';
+        default:
+            return 'js';
     }
-  };
 }
-function getAppSourceTransforms(appConfig) {
-  return Array.from(appConfig.sourceTransforms.values());
+/**
+ * Adapts a source transform into the existing Ecopages build-plugin contract.
+ *
+ * @remarks
+ * Server-oriented builds and loader registration still use this adapter.
+ * Browser/HMR builds should register the transform in `appConfig.sourceTransforms`
+ * instead so the Rolldown bridge can run it after competing `onLoad` plugins.
+ */
+export function createEcoBuildPluginFromSourceTransform(transform) {
+    return {
+        name: transform.name,
+        setup(build) {
+            build.onLoad({ filter: transform.filter }, (args) => {
+                const filePath = normalizeTransformId(args.path);
+                const code = fileSystem.readFileSync(filePath);
+                const result = applySourceTransform(transform, code, filePath);
+                if (!result) {
+                    return undefined;
+                }
+                return {
+                    contents: typeof result === 'string' ? result : result.code,
+                    loader: inferLoaderFromPath(filePath),
+                    resolveDir: path.dirname(filePath),
+                };
+            });
+        },
+    };
 }
-function createVitePluginsFromAppSourceTransforms(appConfig) {
-  return getAppSourceTransforms(appConfig).map((transform) => createVitePluginFromSourceTransform(transform));
+/**
+ * Adapts a source transform into a Vite-compatible plugin object.
+ *
+ * @remarks
+ * This intentionally returns a plain object shape so core does not need a hard
+ * dependency on `vite` just to author transform primitives.
+ */
+export function createVitePluginFromSourceTransform(transform) {
+    return {
+        name: transform.name,
+        enforce: transform.enforce,
+        transform(code, id) {
+            return applySourceTransform(transform, code, id);
+        },
+    };
+}
+/**
+ * Returns the app-owned source transforms in stable registration order.
+ */
+export function getAppSourceTransforms(appConfig) {
+    return appConfig.sourceTransforms ? Array.from(appConfig.sourceTransforms.values()) : [];
+}
+/**
+ * Adapts the app-owned source transforms into Vite-compatible plugin objects.
+ */
+export function createVitePluginsFromAppSourceTransforms(appConfig) {
+    return getAppSourceTransforms(appConfig).map((transform) => createVitePluginFromSourceTransform(transform));
 }
-export {
-  applySourceTransform,
-  createEcoBuildPluginFromSourceTransform,
-  createVitePluginFromSourceTransform,
-  createVitePluginsFromAppSourceTransforms,
-  getAppSourceTransforms,
-  normalizeTransformId
-};

package/src/plugins/tsconfig-import-resolver.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Loads `compilerOptions.paths` keys from tsconfig, following `extends` recursively.
+ */
+export declare function loadTsconfigPathPrefixes(projectRoot: string): string[];
+export declare function matchesTsconfigPathPrefix(specifier: string, prefixes: readonly string[]): boolean;
+/**
+ * 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 declare function isBarePackageImportSpecifier(specifier: string, projectRoot?: string): boolean;
+/**
+ * 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 declare function resolveBarePackageBrowserEntry(projectRoot: string, specifier: string): string | undefined;
+/**
+ * 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 declare function resolveRelativeModulePath(fromFile: string, specifier: string): string | undefined;
+/**
+ * Resolves a relative or tsconfig path alias import (via oxc-resolver).
+ */
+export declare function resolveProjectModulePath(projectRoot: string, fromFile: string, specifier: string): string | undefined;
+/**
+ * Resolves a TS path alias import using the app's tsconfig `paths` (via oxc-resolver).
+ */
+export declare function resolveProjectImportPath(projectRoot: string, fromFile: string, specifier: string): string | undefined;

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

@@ -0,0 +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 = new Map();
+const pathPrefixCache = new Map();
+function stripJsonComments(source) {
+    return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+}
+function findTsconfigPath(projectRoot) {
+    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));
+    }
+}
+/**
+ * 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 [];
+    }
+    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;
+}
+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 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('.')) {
+        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;
+}
+/**
+ * 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;
+}
+/**
+ * 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);
+}

package/src/route-renderer/GRAPH.md

@@ -33,32 +33,26 @@ flowchart TD
 
 ## 2) Route Render Flow
 
-`IntegrationRenderer.execute()` delegates shared route orchestration to `RouteRenderFlow`.
+`IntegrationRenderer.execute()` delegates shared route orchestration to `RouteRenderOrchestrator`.
 
 ```mermaid
 flowchart TD
-  A[IntegrationRenderer.execute] --> B[RouteRenderFlow.prepareRenderOptions]
+  A[IntegrationRenderer.execute] --> B[RouteRenderOrchestrator.prepareRenderOptions]
   B --> C[resolvePageModule]
   C --> D[ownershipValidationService.validate]
   D --> E[resolvePageData]
-  E --> F[ownershipPlanningService.buildPlan]
-  F --> G[resolveDependencies]
-  G --> H[buildPageBrowserGraph]
-  H --> I{shouldRenderPageComponent?}
-  I -- Yes --> J[renderPageComponent]
-  I -- No --> K[skip page-root render]
-  J --> L[merge component assets]
-  K --> L
-  L --> M[collect injector and eager SSR lazy assets]
-  M --> N[build pagePackage and prepared render options]
-  N --> O[callbacks.render]
-  O --> P[capture rendered body as html]
-  P --> Q[inspect unresolved marker artifacts]
-  Q --> R{unresolved eco-marker remains?}
-  R -- Yes --> S[throw unresolved artifact error]
-  R -- No --> T[stamp root or document attributes when needed]
-  T --> U[htmlTransformer transform]
-  U --> V[final body and cache strategy]
+  E --> F[ownershipValidationService.validate + throwIfOwnershipInvalid]
+  F --> G[resolveDependencies + buildPageBrowserGraph]
+  G --> H[collect injector and eager SSR lazy assets]
+  H --> I[build pagePackage and prepared render options]
+  I --> J[IntegrationRenderer.render via document shell]
+  J --> K[capture rendered body as html]
+  K --> L[inspect unresolved marker artifacts]
+  L --> M{unresolved eco-marker remains?}
+  M -- Yes --> N[throw unresolved artifact error]
+  M -- No --> O[stamp document attributes when needed]
+  O --> P[htmlTransformer transform]
+  P --> Q[final body and cache strategy]
 ```
 
 ## 3) Mixed-Integration Render Model
@@ -77,7 +71,7 @@ flowchart TD
   D -- Yes --> E[render inline]
   D -- No --> F[delegate to owning renderer]
   F --> G[owning renderer renderComponentWithForeignChildren]
-  G --> H[owning renderer renderForeignSubtree when payload form is needed]
+  G --> H[owning renderer renderComponentWithForeignChildren mapped via toForeignSubtreeRenderPayload]
   H --> I[resolved html plus assets and attachment policy]
 ```
 
@@ -91,7 +85,7 @@ flowchart TD
   B -- Yes --> C[return resolved renderer-owned output]
   B -- No --> D[queue foreign-subtree token]
   D --> E[finish current render pass]
-  E --> F[QueuedForeignSubtreeResolutionService resolveQueuedHtml]
+  E --> F[ForeignSubtreeExecutionService resolveQueuedHtml]
   F --> G[resolve nested queued tokens first]
   G --> H[dispatch foreign subtree to owning renderer]
   H --> I[merge emitted assets and root attributes]
@@ -121,12 +115,12 @@ flowchart TD
 The most useful reading order is:
 
 1. `route-renderer.ts`
-2. `orchestration/route-render-flow.ts`
+2. `orchestration/route-pipeline/route-render-orchestrator.ts`
 3. `orchestration/integration-renderer.ts`
-4. `orchestration/ownership-validation.service.ts`
-5. `orchestration/ownership-planning.service.ts`
-6. `orchestration/component-render-context.ts`
-7. `orchestration/queued-foreign-subtree-resolution.service.ts`
+4. `orchestration/ownership-graph/ownership-validation.service.ts`
+5. `orchestration/ownership-graph/component-graph.ts`
+6. `orchestration/foreign-child/component-render-context.ts`
+7. `orchestration/foreign-child/foreign-subtree-execution.service.ts`
 8. `page-loading/page-module-loader.ts`
 9. `page-loading/dependency-resolver.ts`
 10. `eco/eco.ts`
@@ -134,12 +128,12 @@ The most useful reading order is:
 ## 7) Key Files
 
 - `packages/core/src/route-renderer/route-renderer.ts`
-- `packages/core/src/route-renderer/orchestration/route-render-flow.ts`
+- `packages/core/src/route-renderer/orchestration/route-pipeline/route-render-orchestrator.ts`
 - `packages/core/src/route-renderer/orchestration/integration-renderer.ts`
-- `packages/core/src/route-renderer/orchestration/ownership-validation.service.ts`
-- `packages/core/src/route-renderer/orchestration/ownership-planning.service.ts`
-- `packages/core/src/route-renderer/orchestration/component-render-context.ts`
-- `packages/core/src/route-renderer/orchestration/queued-foreign-subtree-resolution.service.ts`
+- `packages/core/src/route-renderer/orchestration/ownership-graph/ownership-validation.service.ts`
+- `packages/core/src/route-renderer/orchestration/ownership-graph/component-graph.ts`
+- `packages/core/src/route-renderer/orchestration/foreign-child/component-render-context.ts`
+- `packages/core/src/route-renderer/orchestration/foreign-child/foreign-subtree-execution.service.ts`
 - `packages/core/src/route-renderer/page-loading/page-module-loader.ts`
 - `packages/core/src/route-renderer/page-loading/dependency-resolver.ts`
 - `packages/core/src/eco/eco.ts`