@ecopages/core 0.2.0-rc.6 → 0.2.0-rc.7

package/README.md

@@ -77,6 +77,8 @@ The manager/orchestration layer is core-owned, but framework-specific strategies
 - `ConfigBuilder` seeds one app-owned build ownership path, adapter, manifest, executor, dev graph, and runtime registry.
 - `BrowserBundleService` is the shared browser build seam used by HMR and asset-oriented browser output paths.
 - `ServerModuleTranspiler` is the shared server-side source loading seam used by runtime bootstrap and HMR metadata loading.
+- `RouteRegistry` gives exact and dynamic Pages priority over catch-alls, then selects the most specific matching catch-all prefix.
+- Browser runtime package entries resolve from the application root with ESM import conditions, so framework-local packages cannot shadow app dependencies.
 - `createApp()` stays the universal runtime entrypoint, while Vite and Nitro hosts own their advanced dev and build workflows.
 - One bundled adapter is the default bundler. Vite-based apps route through the `ViteHostBuildAdapter` boundary marker instead.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-rc.6",
+  "version": "0.2.0-rc.7",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -20,7 +20,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-rc.6",
+    "@ecopages/file-system": "0.2.0-rc.7",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.141.0",
@@ -34,7 +34,7 @@
     "@standard-schema/utils": "^0.3.0"
   },
   "peerDependencies": {
-    "@ecopages/dev-toolbar": "0.2.0-rc.6"
+    "@ecopages/dev-toolbar": "0.2.0-rc.7"
   },
   "peerDependenciesMeta": {
     "@ecopages/dev-toolbar": {

package/src/declarations.d.ts

@@ -1,4 +1,4 @@
-/// <reference path="./css-imports.d.js" />
+import './css-imports.d.js';
 
 import type { EcoPagesAppConfig } from './types/internal-types';
 import type { EcoNavigationRuntime } from './router/client/navigation-coordinator';
@@ -6,6 +6,12 @@ import type { EcoNavigationRuntime } from './router/client/navigation-coordinato
 type HMRHandler = (url: string) => Promise<void>;
 type CleanupPageRootFunction = () => void;
 type EcoPageRoot = { render: (node: unknown) => void; unmount: () => void };
+type EcoIslandComponent = (props: Record<string, unknown>) => unknown;
+/** Shared React island diagnostics and root lookup state exposed to devtools. */
+type EcoIslandRuntime = {
+	islandRoots: Record<string, EcoPageRoot>;
+	islandComponents: Record<string, EcoIslandComponent>;
+};
 type EcoPageData = {
 	module: string;
 	props: Record<string, unknown>;
@@ -17,7 +23,10 @@ type EcoPagesWindowRuntime = {
 		cleanupPageRoot?: CleanupPageRootFunction;
 		pageRoot?: EcoPageRoot | null;
 	};
+	/** Roots keyed by SSR instance ID; component keys are never used for lookup. */
 	islandRoots?: Record<string, EcoPageRoot>;
+	islandComponents?: Record<string, EcoIslandComponent>;
+	__ecoIslandRuntime?: EcoIslandRuntime;
 	page?: EcoPageData;
 };
 

package/src/islands/README.md

@@ -12,7 +12,11 @@ Hydratable component instances stamp a small, integration-agnostic attribute set
 | `data-eco-component-key`      | Optional module key used by client hydration (React) |
 | `data-eco-props`              | Optional base64 JSON props snapshot for hydration    |
 
-React may still replace the SSR host with `<eco-island>` after hydration; the marker is applied at SSR time on the component root.
+React integrations may emit `<eco-island>` as the SSR host. The host uses
+`display: contents` so it does not introduce a layout box, while the host and
+its children remain in place as the client calls `hydrateRoot()` on that host.
+React island integrations may add `data-eco-hydrated` after the initial client
+commit for development diagnostics.
 
 ## Where stamping happens
 

package/src/route-renderer/README.md

@@ -95,12 +95,12 @@ Important:
 
 - route-level fallback resolution is gone; unresolved artifacts are now a hard failure
 - ownership is declared from canonical component identity, not inferred from final HTML
-- declared page dependencies are resolved from final render inputs and carried to the owning integration; integrations may use them for renderer-specific lifecycle work such as HMR ownership
+- declared page dependencies are resolved from final render inputs and carried as dependency roots to the owning integration; those roots participate in asset, integration, ownership, and renderer-specific lifecycle collection
 - same-integration children stay renderer-local and do not need to pass through a universal transport
 
 ## Declared Foreign Child Contract
 
-Mixed-integration component configs must declare every possible foreign child in `config.dependencies.components`.
+Static mixed-integration component configs must declare every possible foreign child in `config.dependencies.components`. Page dependency resolvers can additionally provide request-time component roots when a route loads a component dynamically.
 
 `OwnershipValidationService` surfaces missing metadata or unknown integrations during `prepareRenderOptions()` and throws before render execution starts.
 

package/src/route-renderer/orchestration/document-shell/document-shell-render.service.d.ts

@@ -1,4 +1,5 @@
-import type { BaseIntegrationContext, ComponentRenderInput, ComponentRenderResult, EcoComponent, PageMetadataProps } from '../../../types/public-types.js';
+import type { BaseIntegrationContext, ComponentRenderResult, EcoComponent, PageMetadataProps } from '../../../types/public-types.js';
+import type { InternalComponentRenderInput } from '../../../types/internal-types.js';
 import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
 import { HtmlTransformerService, type HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
 export type DocumentShellLayoutInput = {
@@ -36,6 +37,8 @@ export type DocumentShellComposeChildrenHook = (context: DocumentShellComposeChi
 export type DocumentShellComposeInput = {
     primaryComponent: EcoComponent;
     primaryProps: Record<string, unknown>;
+    /** Components whose ownership graphs must join the foreign-child decision. */
+    foreignChildRoots?: ReadonlyArray<EcoComponent | Partial<EcoComponent>>;
     layout?: DocumentShellLayoutInput;
     layouts?: DocumentShellLayoutInput[];
     composeChildren?: DocumentShellComposeChildrenHook;
@@ -47,6 +50,8 @@ export type DocumentShellPageRenderInput = {
         component: EcoComponent;
         props: Record<string, unknown>;
     };
+    /** Components whose ownership graphs must join the foreign-child decision. */
+    foreignChildRoots?: ReadonlyArray<EcoComponent | Partial<EcoComponent>>;
     layout?: DocumentShellLayoutInput;
     layouts?: DocumentShellLayoutInput[];
     composeChildren?: DocumentShellComposeChildrenHook;
@@ -57,7 +62,7 @@ export type DocumentShellPageRenderInput = {
     transformDocumentHtml?: (html: string) => string;
 };
 export type DocumentShellRenderDependencies = {
-    renderComponentWithForeignChildren(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    renderComponentWithForeignChildren(input: InternalComponentRenderInput): Promise<ComponentRenderResult>;
     appendProcessedDependencies(...assetGroups: Array<readonly ProcessedAsset[] | undefined>): ProcessedAsset[];
 };
 export type DocumentShellAttributeStamping = {

package/src/route-renderer/orchestration/document-shell/document-shell-render.service.js

@@ -68,6 +68,7 @@ export async function composeDocumentShell(dependencies, input) {
         primaryRender = await dependencies.renderComponentWithForeignChildren({
             component: input.primaryComponent,
             props: input.primaryProps,
+            foreignChildRoots: input.foreignChildRoots,
             integrationContext: { rendererCache },
         });
         const composed = await composeChildren({
@@ -113,6 +114,7 @@ export async function renderPageDocumentShell(dependencies, input, docType) {
     const { documentHtml: composedDocumentHtml } = await composeDocumentShell(dependencies, {
         primaryComponent: input.page.component,
         primaryProps: input.page.props,
+        foreignChildRoots: input.foreignChildRoots,
         layout: input.layout,
         layouts: input.layouts,
         composeChildren: input.composeChildren,

package/src/route-renderer/orchestration/foreign-child/foreign-subtree-execution.service.d.ts

@@ -1,5 +1,6 @@
 import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
 import type { BaseIntegrationContext, ComponentRenderInput, ComponentRenderResult, EcoComponent, ForeignSubtreeRenderPayload } from '../../../types/public-types.js';
+import type { InternalComponentRenderInput } from '../../../types/internal-types.js';
 import { type ForeignChildRuntime } from './component-render-context.js';
 export type QueuedForeignChildDecisionInput = {
     currentIntegration: string;
@@ -38,10 +39,10 @@ export interface ForeignSubtreeExecutionDecisionInput {
 }
 export interface ForeignSubtreeExecutionRenderOptions {
     currentIntegrationName: string;
-    input: ComponentRenderInput;
+    input: InternalComponentRenderInput;
     renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
     normalizeComponentRenderOutput(result: ComponentRenderResult): ComponentRenderResult;
-    hasForeignChildDescendants(component: EcoComponent): boolean;
+    hasForeignChildDescendants(component: EcoComponent, foreignChildRoots?: ReadonlyArray<EcoComponent | Partial<EcoComponent>>): boolean;
     createForeignChildRuntime(options: {
         renderInput: ComponentRenderInput;
         rendererCache: Map<string, ForeignSubtreeExecutionOwningRenderer>;

package/src/route-renderer/orchestration/foreign-child/foreign-subtree-execution.service.js

@@ -241,7 +241,7 @@ export class ForeignSubtreeExecutionService {
         if (delegatedForeignChildRender) {
             return delegatedForeignChildRender;
         }
-        const hasForeignChildren = options.hasForeignChildDescendants(options.input.component) ||
+        const hasForeignChildren = options.hasForeignChildDescendants(options.input.component, options.input.foreignChildRoots) ||
             this.requiresForeignChildRuntime(options.input);
         const activeRenderContext = getComponentRenderContext();
         if (!hasForeignChildren) {

package/src/route-renderer/orchestration/integration-renderer.d.ts

@@ -3,7 +3,7 @@
  * Every integration renderer should extend this class
  * @module
  */
-import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
+import type { EcoPagesAppConfig, IHmrManager, InternalComponentRenderInput } from '../../types/internal-types.js';
 import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPageFile, EcoPagesElement, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
 import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
 import { HtmlTransformerService } from '../../services/html/html-transformer.service.js';
@@ -217,6 +217,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         pageProps: Record<string, unknown>;
         documentProps?: Record<string, unknown>;
         transformDocumentHtml?: (html: string) => string;
+        foreignChildRoots?: ReadonlyArray<EcoComponent | Partial<EcoComponent>>;
     }): Promise<string>;
     protected renderStringComponentWithSerializedChildren(input: ComponentRenderInput, component: (props: Record<string, unknown>) => Promise<EcoPagesElement> | EcoPagesElement): Promise<ComponentRenderResult>;
     /**
@@ -349,7 +350,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * render them with no active foreign-child runtime, which bypasses the owning
      * renderer's nested foreign-child handoff.
      */
-    renderComponentWithForeignChildren(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    renderComponentWithForeignChildren(input: InternalComponentRenderInput): Promise<ComponentRenderResult>;
     protected finalizeIslandComponentRender(input: ComponentRenderInput, result: ComponentRenderResult): ComponentRenderResult;
     private normalizeComponentRenderOutput;
     protected normalizeUnresolvedMarkerArtifactHtml(html: string): string;
@@ -360,7 +361,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * This keeps foreign-child runtime setup narrow: same-integration trees can render
      * directly without paying the queue orchestration cost.
      */
-    protected hasForeignChildDescendants(component: EcoComponent): boolean;
+    protected hasForeignChildDescendants(component: EcoComponent, foreignChildRoots?: ReadonlyArray<EcoComponent | Partial<EcoComponent>>): boolean;
     /**
      * Render a view directly to a Response object.
      * Used for explicit routing where views are rendered from route handlers.

package/src/route-renderer/orchestration/integration-renderer.js

@@ -688,7 +688,7 @@ export class IntegrationRenderer {
             input,
             renderComponent: (renderInput) => this.renderComponent(renderInput),
             normalizeComponentRenderOutput: (result) => this.normalizeComponentRenderOutput(result),
-            hasForeignChildDescendants: (component) => this.hasForeignChildDescendants(component),
+            hasForeignChildDescendants: (component, foreignChildRoots) => this.hasForeignChildDescendants(component, foreignChildRoots),
             createForeignChildRuntime: ({ renderInput, rendererCache }) => this.createForeignChildRuntime({
                 renderInput,
                 rendererCache: rendererCache,
@@ -725,8 +725,8 @@ export class IntegrationRenderer {
      * This keeps foreign-child runtime setup narrow: same-integration trees can render
      * directly without paying the queue orchestration cost.
      */
-    hasForeignChildDescendants(component) {
-        return hasForeignChildDescendantsInGraph(component, this.name);
+    hasForeignChildDescendants(component, foreignChildRoots) {
+        return hasForeignChildDescendantsInGraph(component, this.name, foreignChildRoots);
     }
     /**
      * Render a single component and return structured output for orchestration paths.

package/src/route-renderer/orchestration/ownership-graph/component-graph-collectors.d.ts

@@ -3,5 +3,5 @@ import type { EcoComponent, ResolvedLazyTrigger } from '../../../types/public-ty
 import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
 export declare function collectIntegrationNamesFromGraph(components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): Set<string>;
 export declare function collectResolvedLazyTriggersFromGraph(components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): ResolvedLazyTrigger[];
-export declare function hasForeignChildDescendantsInGraph(component: EcoComponent, currentIntegrationName: string): boolean;
+export declare function hasForeignChildDescendantsInGraph(component: EcoComponent, currentIntegrationName: string, foreignChildRoots?: ReadonlyArray<EcoComponent | Partial<EcoComponent>>): boolean;
 export declare function collectUsedIntegrationDependenciesFromGraph(appConfig: EcoPagesAppConfig, components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): ProcessedAsset[];

package/src/route-renderer/orchestration/ownership-graph/component-graph-collectors.js

@@ -31,10 +31,10 @@ export function collectResolvedLazyTriggersFromGraph(components, currentIntegrat
     });
     return triggers;
 }
-export function hasForeignChildDescendantsInGraph(component, currentIntegrationName) {
+export function hasForeignChildDescendantsInGraph(component, currentIntegrationName, foreignChildRoots) {
     let foundForeign = false;
     walkComponentGraph({
-        roots: [{ component }],
+        roots: toGraphRoots([component, ...(foreignChildRoots ?? [])]),
         currentIntegrationName,
         onComponent: ({ component: currentComponent }) => {
             if (foundForeign) {

package/src/route-renderer/orchestration/route-pipeline/route-render-orchestrator.js

@@ -88,11 +88,12 @@ export class RouteRenderOrchestrator {
             dependencyInstanceKey,
         });
         const resolvedPageDependencyComponents = resolvedPageDependencies?.components ?? [];
+        const dependencyRoots = [...componentsToResolve, ...resolvedPageDependencyComponents];
         const allDependencies = [
             ...resolvedDependencies,
-            ...collectUsedIntegrationDependenciesFromGraph(this.appConfig, componentsToResolve, adapter.name),
+            ...collectUsedIntegrationDependenciesFromGraph(this.appConfig, dependencyRoots, adapter.name),
         ];
-        const triggers = collectResolvedLazyTriggersFromGraph(componentsToResolve, adapter.name);
+        const triggers = collectResolvedLazyTriggersFromGraph(dependencyRoots, adapter.name);
         const globalAssets = triggers.length > 0
             ? await buildGlobalInjectorAssets(this.appConfig, this.assetProcessingService, triggers, adapter.name)
             : [];

package/src/route-renderer/orchestration/string-markup-renderer.d.ts

@@ -9,6 +9,6 @@ import { IntegrationRenderer, type RenderToResponseContext } from './integration
  */
 export declare abstract class StringMarkupRenderer extends IntegrationRenderer<EcoPagesElement> {
     renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
-    render({ params, query, props, locals, pageLocals, metadata, Page, Layout, layoutEntries, HtmlTemplate, pageProps, }: IntegrationRendererRenderOptions): Promise<RouteRendererBody>;
+    render({ params, query, props, locals, pageLocals, metadata, Page, Layout, layoutEntries, HtmlTemplate, pageProps, resolvedPageDependencyComponents, }: IntegrationRendererRenderOptions): Promise<RouteRendererBody>;
     renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
 }

package/src/route-renderer/orchestration/string-markup-renderer.js

@@ -14,7 +14,7 @@ export class StringMarkupRenderer extends IntegrationRenderer {
         }
         return this.renderStringComponentWithQueuedForeignSubtrees(input, input.component);
     }
-    async render({ params, query, props, locals, pageLocals, metadata, Page, Layout, layoutEntries, HtmlTemplate, pageProps, }) {
+    async render({ params, query, props, locals, pageLocals, metadata, Page, Layout, layoutEntries, HtmlTemplate, pageProps, resolvedPageDependencyComponents, }) {
         try {
             return await this.renderPageWithDocumentShell({
                 page: {
@@ -31,6 +31,7 @@ export class StringMarkupRenderer extends IntegrationRenderer {
                 htmlTemplate: HtmlTemplate,
                 metadata,
                 pageProps: pageProps ?? props ?? {},
+                foreignChildRoots: resolvedPageDependencyComponents,
             });
         }
         catch (error) {

package/src/router/README.md

@@ -56,7 +56,11 @@ Match priority:
 
 1. `exact` — the pathname must equal the route pathname exactly.
 2. `dynamic` — the clean (bracket-stripped) prefix must appear in the pathname, and the segment counts must match.
-3. `catch-all` — the clean prefix must appear in the pathname.
+3. `catch-all` — the prefix segments must match the pathname. When multiple
+   catch-all routes match, shared prefix segments are compared from left to right
+   so an earlier static segment wins over a dynamic one; when those patterns tie,
+   the route with the longer prefix wins, then pathname order provides a
+   deterministic tie-breaker.
 
 ## `client/`
 

package/src/router/server/route-registry.d.ts

@@ -62,6 +62,19 @@ export declare class RouteRegistry {
     reload(): Promise<void>;
     onReload(listener: () => void): () => void;
     matchRequest(requestUrl: string): RouteMatch | null;
+    /**
+     * Orders overlapping catch-all routes by the specificity of their prefix.
+     *
+     * @remarks
+     * Prefix segments are compared from left to right because an earlier static
+     * segment constrains a request more strongly than a later one. A longer
+     * prefix wins only after the shared segment pattern ties. The pathname tie
+     * breaker keeps equal patterns deterministic without depending on discovery
+     * order.
+     */
+    private compareCatchAllSpecificity;
+    private getCatchAllPrefix;
+    private isDynamicRouteSegment;
     listStaticPathExpansions(input: {
         runtimeOrigin: string;
     }): Promise<readonly StaticPathExpansion[]>;

package/src/router/server/route-registry.js

@@ -49,49 +49,60 @@ export class RouteRegistry {
         const requestedPathname = normalizePathname(url.pathname);
         const query = this.getSearchParams(url);
         for (const route of this.templateRouteList) {
-            if (route.kind !== 'exact') {
+            if (route.kind === 'exact') {
+                if (requestedPathname === route.pathname || requestedPathname === `${route.pathname}/`) {
+                    return {
+                        requestedPathname,
+                        templateRoute: route,
+                        params: {},
+                        query,
+                    };
+                }
                 continue;
             }
-            if (requestedPathname === route.pathname || requestedPathname === `${route.pathname}/`) {
+            const params = this.tryExtractParams(route, requestedPathname);
+            if (params) {
                 return {
                     requestedPathname,
                     templateRoute: route,
-                    params: {},
+                    params,
                     query,
                 };
             }
         }
-        for (const route of this.templateRouteList) {
-            if (route.kind !== 'dynamic') {
-                continue;
-            }
-            const params = this.tryExtractParams(route, requestedPathname);
-            if (!params) {
-                continue;
-            }
-            return {
-                requestedPathname,
-                templateRoute: route,
-                params,
-                query,
-            };
-        }
-        for (const route of this.templateRouteList) {
-            if (route.kind !== 'catch-all') {
-                continue;
-            }
-            const params = this.tryExtractParams(route, requestedPathname);
-            if (!params) {
-                continue;
+        return null;
+    }
+    /**
+     * Orders overlapping catch-all routes by the specificity of their prefix.
+     *
+     * @remarks
+     * Prefix segments are compared from left to right because an earlier static
+     * segment constrains a request more strongly than a later one. A longer
+     * prefix wins only after the shared segment pattern ties. The pathname tie
+     * breaker keeps equal patterns deterministic without depending on discovery
+     * order.
+     */
+    compareCatchAllSpecificity(left, right) {
+        const leftPrefix = this.getCatchAllPrefix(left.pathname);
+        const rightPrefix = this.getCatchAllPrefix(right.pathname);
+        const sharedLength = Math.min(leftPrefix.length, rightPrefix.length);
+        for (let index = 0; index < sharedLength; index += 1) {
+            const leftIsDynamic = this.isDynamicRouteSegment(leftPrefix[index]);
+            const rightIsDynamic = this.isDynamicRouteSegment(rightPrefix[index]);
+            if (leftIsDynamic !== rightIsDynamic) {
+                return leftIsDynamic ? 1 : -1;
             }
-            return {
-                requestedPathname,
-                templateRoute: route,
-                params,
-                query,
-            };
         }
-        return null;
+        const prefixLengthDifference = rightPrefix.length - leftPrefix.length;
+        return prefixLengthDifference !== 0 ? prefixLengthDifference : left.pathname.localeCompare(right.pathname);
+    }
+    getCatchAllPrefix(pathname) {
+        const segments = pathname.split('/').filter(Boolean);
+        const catchAllIndex = segments.findIndex((segment) => segment.startsWith('[...') && segment.endsWith(']'));
+        return catchAllIndex === -1 ? segments : segments.slice(0, catchAllIndex);
+    }
+    isDynamicRouteSegment(segment) {
+        return segment.startsWith('[') && segment.endsWith(']');
     }
     async listStaticPathExpansions(input) {
         const expansions = [];
@@ -168,6 +179,9 @@ export class RouteRegistry {
             if (priorityDifference !== 0) {
                 return priorityDifference;
             }
+            if (left.kind === 'catch-all' && right.kind === 'catch-all') {
+                return this.compareCatchAllSpecificity(left, right);
+            }
             if (left.pathname === '/') {
                 return -1;
             }

package/src/services/README.md

@@ -30,6 +30,8 @@ so shared layout styles do not need to be rebuilt for every navigated page while
 
 Browser runtime module assets resolve bare package roots through their ESM import target. For legacy packages without an `exports` map, they prefer `package.json#module` over CJS `main`; CJS resolution is only a compatibility fallback. Generated entries use `export *` for ESM files and explicit named re-exports for CJS files (so bindings such as React `jsx` exist on the vendor). A default binding is added only when the selected entry exposes one. Runtime vendors are package-root contracts: subpath imports need their own vendor declaration or remain in the consuming bundle.
 
+Package entry lookup is rooted at the application directory, so a framework-local dependency with the same name cannot shadow the application's installed package. ESM export conditions are evaluated in the same order as the generated vendor import (`node`, `import`, then `default`).
+
 ## Design Rule
 
 If a concern affects more than one integration or more than one runtime adapter, it usually belongs here instead of in a package-specific implementation.

package/src/services/assets/asset-processing-service/browser-runtime-entry-resolution.d.ts

@@ -3,6 +3,12 @@ export type BrowserRuntimeDefaultExportPolicy = 'emit-default' | 'skip-default';
 type RequireFromRoot = ReturnType<typeof createRequire>;
 /**
  * Resolves a package specifier through Node's ESM import conditions from the app root.
+ *
+ * @remarks
+ * The resolver is rooted at the application directory so package lookup cannot
+ * accidentally use a dependency with the same name from the framework's own
+ * installation. The condition order matches the generated vendor import: Node
+ * compatibility first, then ESM import, then the package default.
  */
 export declare function resolvePackageEsmEntryPath(specifier: string, rootDir: string): string | undefined;
 /**

package/src/services/assets/asset-processing-service/browser-runtime-entry-resolution.js

@@ -1,14 +1,33 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL, fileURLToPath } from 'node:url';
+import { fileURLToPath } from 'node:url';
+import { ResolverFactory } from 'oxc-resolver';
 import { isBarePackageImportSpecifier } from '../../../plugins/tsconfig-import-resolver.js';
 import { toPackageRootSpecifier } from '../../../plugins/package-specifier.js';
+const esmEntryResolvers = new Map();
+function getEsmEntryResolver(rootDir) {
+    const normalizedRoot = path.resolve(rootDir);
+    const cached = esmEntryResolvers.get(normalizedRoot);
+    if (cached) {
+        return cached;
+    }
+    const resolver = new ResolverFactory({ conditionNames: ['node', 'import', 'default'] });
+    esmEntryResolvers.set(normalizedRoot, resolver);
+    return resolver;
+}
 /**
  * Resolves a package specifier through Node's ESM import conditions from the app root.
+ *
+ * @remarks
+ * The resolver is rooted at the application directory so package lookup cannot
+ * accidentally use a dependency with the same name from the framework's own
+ * installation. The condition order matches the generated vendor import: Node
+ * compatibility first, then ESM import, then the package default.
  */
 export function resolvePackageEsmEntryPath(specifier, rootDir) {
     try {
-        return fileURLToPath(import.meta.resolve(specifier, pathToFileURL(path.join(rootDir, 'package.json')).href));
+        const result = getEsmEntryResolver(rootDir).sync(path.resolve(rootDir), specifier);
+        return result.path;
     }
     catch {
         return undefined;
@@ -56,13 +75,13 @@ export function resolveBrowserRuntimeEntryPath(options) {
     if (specifier.startsWith('.')) {
         return requireFromRoot.resolve(specifier);
     }
-    const esmResolvedPath = isBarePackageImportSpecifier(specifier, rootDir)
-        ? resolvePackageEsmEntryPath(specifier, rootDir)
-        : undefined;
     const legacyModulePath = resolveLegacyPackageModuleEntry({ specifier, requireFromRoot, rootDir });
     if (legacyModulePath) {
         return legacyModulePath;
     }
+    const esmResolvedPath = isBarePackageImportSpecifier(specifier, rootDir)
+        ? resolvePackageEsmEntryPath(specifier, rootDir)
+        : undefined;
     if (esmResolvedPath) {
         return esmResolvedPath;
     }

package/src/types/internal-types.d.ts

@@ -5,7 +5,11 @@ import type { BuildRuntime } from '../build/runtime/build-runtime.js';
 import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.js';
 import type { Processor } from '../plugins/processor.js';
 import type { EcoSourceTransform } from '../plugins/source-transform.js';
-import type { PageMetadataProps, SitemapConfig } from './public-types.js';
+import type { ComponentRenderInput, EcoComponent, PageMetadataProps, SitemapConfig } from './public-types.js';
+/** Internal render input carrying route-resolved dependency roots. */
+export type InternalComponentRenderInput = ComponentRenderInput & {
+    foreignChildRoots?: ReadonlyArray<EcoComponent | Partial<EcoComponent>>;
+};
 import type { RouteRegistry } from '../router/server/route-registry.js';
 import type { CacheConfig } from '../services/cache/cache.types.js';
 import type { DevGraphService } from '../services/runtime-state/dev-graph.service.js';