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

package/README.md

@@ -13,13 +13,16 @@ Ecopages is an extensible static site generator (SSG) built around a Bun-first c
 
 ## Current Architecture
 
+Projects load shared ambient types through `@ecopages/core/declarations`. This entry references `src/css-imports.d.ts`, which keeps the wildcard CSS declaration in a standalone ambient file so side-effect CSS imports typecheck without per-project declarations.
+
 The current core package is organized around app-owned runtime state and explicit service boundaries.
 
 The important ownership rules are:
 
 - `ConfigBuilder.build()` finalizes app-owned build and runtime services.
 - Component identity attribution is one shared source transform for server, browser, and HMR compilation paths: after a lexical `eco.` gate, it uses Oxc to wrap supported factory options with `bindComponentIdentity()`, which factories retain as `config.identity`.
-- browser bundling and server module loading are explicit, separate paths.
+- Direct local Eco Component imports (including named `export { X } from` barrels) and relative side-effect CSS imports supply Dependencies by default through the shared transform and existing collector; explicit asset declarations override inference, and inferred styles stay keyed by identity until collection. See [eco](src/eco/README.md) and [Plugin Contracts](src/plugins/README.md).
+- Browser bundling and server module loading are separate paths. SSR-enabled lazy scripts execute on the server before rendering and in the browser only on their configured trigger.
 - runtime hosts stay thin and delegate framework work into core services.
 - HMR and invalidation use shared graph-aware services instead of runtime-specific ad hoc wiring.
 
@@ -50,7 +53,10 @@ flowchart TD
 	B --> C[DevelopmentInvalidationService]
 	C --> D{Change kind}
 	D -->|Route or server source| E[Invalidate server modules]
-	D -->|Public or include| F[Reload browser]
+	D -->|Additional watch| E
+	E --> N[Notify processors]
+	N --> F[Reload browser]
+	D -->|Public asset| F
 	D -->|Processor-owned asset| G[Notify processor only]
 	D -->|HMR-eligible source| H[Core HMR manager]
 	H --> I[Strategy selection]
@@ -83,7 +89,7 @@ Use this package README as the top-level map, then drill into the focused subsys
 - `src/build/README.md`: build adapter, executor, development build coordination, and standalone Node server packaging
 - `src/services/README.md`: cross-cutting runtime services and orchestration helpers
 - `src/adapters/README.md`: Bun, Node, and shared adapter boundaries
-- `src/dev/README.md`: dev transform server and on-demand client delivery
+- `src/dev/README.md`: dev transform server, on-demand client delivery, and invalidation during compilation
 - `src/hmr/README.md`: HMR strategy and update-layer ownership
 - `src/router/README.md`: route discovery, matching, and browser navigation coordination
 - `src/route-renderer/README.md`: rendering orchestration and dependency resolution

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-rc.4",
+  "version": "0.2.0-rc.6",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -10,6 +10,9 @@
   "license": "MIT",
   "main": "./src/index.js",
   "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "sideEffects": false,
   "repository": {
     "type": "git",
@@ -17,7 +20,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-rc.4",
+    "@ecopages/file-system": "0.2.0-rc.6",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.141.0",
@@ -31,7 +34,7 @@
     "@standard-schema/utils": "^0.3.0"
   },
   "peerDependencies": {
-    "@ecopages/dev-toolbar": "0.2.0-rc.4"
+    "@ecopages/dev-toolbar": "0.2.0-rc.6"
   },
   "peerDependenciesMeta": {
     "@ecopages/dev-toolbar": {
@@ -631,4 +634,4 @@
     }
   },
   "types": "./src/index.d.ts"
-}
+}

package/src/build/contracts/content-virtual-modules.d.ts

@@ -4,9 +4,11 @@ export declare const CONTENT_VIRTUAL_MODULE_PREFIX = "ecopages:content";
 export declare const CONTENT_VIRTUAL_MODULE_PATTERN: RegExp;
 /** Matches `ecopages:content/<collection>/server` component resolver specifiers. */
 export declare const CONTENT_SERVER_VIRTUAL_MODULE_PATTERN: RegExp;
+/** Matches browser-only `ecopages:content/<collection>/browser` component loader specifiers. */
+export declare const CONTENT_BROWSER_VIRTUAL_MODULE_PATTERN: RegExp;
 export type ParsedCollectionSpecifier = {
     collectionName: string;
-    variant: 'entries' | 'server';
+    variant: 'entries' | 'server' | 'browser';
 };
 export declare function parseCollectionSpecifier(specifier: string): ParsedCollectionSpecifier | null;
 export declare function isContentServerVirtualModule(specifier: string): boolean;

package/src/build/contracts/content-virtual-modules.js

@@ -4,6 +4,8 @@ export const CONTENT_VIRTUAL_MODULE_PREFIX = 'ecopages:content';
 export const CONTENT_VIRTUAL_MODULE_PATTERN = /^ecopages:content\/[a-z][a-z0-9-]*$/;
 /** Matches `ecopages:content/<collection>/server` component resolver specifiers. */
 export const CONTENT_SERVER_VIRTUAL_MODULE_PATTERN = /^ecopages:content\/[a-z][a-z0-9-]+\/server$/;
+/** Matches browser-only `ecopages:content/<collection>/browser` component loader specifiers. */
+export const CONTENT_BROWSER_VIRTUAL_MODULE_PATTERN = /^ecopages:content\/[a-z][a-z0-9-]+\/browser$/;
 export function parseCollectionSpecifier(specifier) {
     const normalized = specifier.startsWith(`${CONTENT_VIRTUAL_MODULE_PREFIX}/`)
         ? specifier.slice(`${CONTENT_VIRTUAL_MODULE_PREFIX}/`.length)
@@ -19,6 +21,12 @@ export function parseCollectionSpecifier(specifier) {
             variant: 'server',
         };
     }
+    if (normalized.endsWith('/browser')) {
+        return {
+            collectionName: normalized.slice(0, -'/browser'.length),
+            variant: 'browser',
+        };
+    }
     return {
         collectionName: normalized,
         variant: 'entries',

package/src/css-imports.d.ts

@@ -0,0 +1,4 @@
+declare module '*.css' {
+	const styles: string;
+	export default styles;
+}

package/src/declarations.d.ts

@@ -1,3 +1,5 @@
+/// <reference path="./css-imports.d.js" />
+
 import type { EcoPagesAppConfig } from './types/internal-types';
 import type { EcoNavigationRuntime } from './router/client/navigation-coordinator';
 
@@ -25,8 +27,3 @@ declare global {
 		__ECO_PAGES__?: EcoPagesWindowRuntime;
 	}
 }
-
-declare module '*.css' {
-	const styles: string;
-	export default styles;
-}

package/src/dev/README.md

@@ -22,3 +22,5 @@ Install the client package in the app project. Core resolves it from the applica
 Disable per project with `devToolbar: { enabled: false }`, or per process with `ECOPAGES_DEV_TOOLBAR=false`.
 
 Server wiring: [dev-toolbar/README.md](../dev-toolbar/README.md) (`DevToolbarHost`, manifest, runtime bundling, HTML injection). Bring-your-own toolbars export `src/bootstrap.ts` and use the same `devToolbar.package` config key.
+
+Dev transform requests retry when their source changes or is invalidated during compilation. Concurrent requests share one in-flight compile per source, including across source and global invalidation; stale attempts release their slot before retrying. Only results for the current source snapshot enter the module cache, so rapid edits cannot label stale browser code with a newer source hash.

package/src/dev/transform-server/dev-transform-server.d.ts

@@ -24,6 +24,7 @@ export declare class DevTransformServer {
     private readonly cache;
     private readonly inFlight;
     private cacheGeneration;
+    private readonly sourceGenerations;
     constructor(options: DevTransformServerOptions);
     registerModule(sourcePath: string): string;
     getRegisteredSourcePath(moduleUrl: string): string | undefined;
@@ -31,6 +32,11 @@ export declare class DevTransformServer {
     private rebuildRuntimeSpecifierMap;
     private resolveVendorBundlePlugins;
     getWatchedModules(): ReadonlyMap<string, string>;
+    /**
+     * @remarks
+     * Marks pending work stale while preserving one in-flight compile per source.
+     * Requests awaiting that work retry against the current source when it completes.
+     */
     invalidateSource(sourcePath: string): void;
     invalidateAll(): void;
     reset(): void;

package/src/dev/transform-server/dev-transform-server.js

@@ -26,6 +26,7 @@ export class DevTransformServer {
     cache = new Map();
     inFlight = new Map();
     cacheGeneration = 0;
+    sourceGenerations = new Map();
     constructor(options) {
         this.appConfig = options.appConfig;
         this.onModuleDependencies = options.onModuleDependencies;
@@ -81,14 +82,20 @@ export class DevTransformServer {
     getWatchedModules() {
         return this.urlToSource;
     }
+    /**
+     * @remarks
+     * Marks pending work stale while preserving one in-flight compile per source.
+     * Requests awaiting that work retry against the current source when it completes.
+     */
     invalidateSource(sourcePath) {
         const normalized = path.resolve(sourcePath);
         this.cache.delete(normalized);
+        this.sourceGenerations.set(normalized, (this.sourceGenerations.get(normalized) ?? 0) + 1);
     }
     invalidateAll() {
         this.cacheGeneration += 1;
         this.cache.clear();
-        this.inFlight.clear();
+        this.sourceGenerations.clear();
         this.vendorRegistry.invalidateAll();
     }
     reset() {
@@ -169,22 +176,26 @@ export class DevTransformServer {
             return entry;
         }
         const generation = this.cacheGeneration;
+        const sourceGeneration = this.sourceGenerations.get(normalized) ?? 0;
         const promise = this.bundler
             .transpileModule(normalized)
             .then((result) => {
-            if (generation !== this.cacheGeneration) {
-                throw new Error(`[dev-transform] Stale transpile result for ${normalized}`);
+            if (generation !== this.cacheGeneration ||
+                sourceGeneration !== (this.sourceGenerations.get(normalized) ?? 0) ||
+                fileSystem.hash(normalized) !== sourceHash) {
+                return undefined;
             }
             if (result.dependencies) {
                 this.onModuleDependencies?.(normalized, result.dependencies);
             }
-            const entry = { code: result.code, sourceHash: fileSystem.hash(normalized) };
+            const entry = { code: result.code, sourceHash };
             this.cache.set(normalized, entry);
             return entry;
         })
             .finally(() => {
             this.inFlight.delete(normalized);
-        });
+        })
+            .then((entry) => entry ?? this.materialize(normalized));
         this.inFlight.set(normalized, promise);
         return promise;
     }

package/src/eco/README.md

@@ -20,6 +20,57 @@ Layouts are assigned explicitly on each `eco.page({ layout })` call — either o
 
 EcoPages does **not** infer layouts from `src/layouts/` file paths or route segment directories. A file under `src/layouts/` is only used when a page imports it and passes it to `layout`.
 
+## Dependency discovery
+
+Discovery is enabled by default for modules declaring `eco.component()`, `eco.layout()`, `eco.html()`, or `eco.page()`, as well as MDX documents compiled through `@ecopages/mdx/core`.
+
+```tsx
+import { eco } from '@ecopages/core';
+import { Counter } from './counter';
+import './page.css';
+
+export default eco.page({
+	render: () => <Counter />,
+});
+```
+
+Direct static named/default imports of local Eco Components contribute their Dependencies transitively. Configured TypeScript path aliases and relative imports are supported for both Components and CSS stylesheets (e.g., `import '@/components/button'` or `import '@/styles/main.css'`). Side-effect CSS imports become stylesheet Dependencies; the shared transform removes the imports so the existing asset pipeline owns delivery in server and browser builds. In MDX documents, top-level component and CSS imports are discovered while markdown code blocks and dynamic imports within functions are safely ignored.
+
+Discovery is conservative and module-scoped: every Eco declaration in a file shares its imported Components and styles, even when a render condition omits a Component. It does not infer which Components actually render. **Best practice:** author **one `eco.component()` per file**. Co-locating multiple components in a single file will cause all declared components in that file to share discovered dependencies.
+
+Imported Layouts contribute assets; only the explicit `layout` option controls Layout composition.
+
+Explicit `dependencies` remain supported. Explicit Components come first, followed by discovered Components in import order, with duplicate Components removed. Explicit stylesheet declarations take precedence over discovered references to the same resolved file, preserving their attributes and order. Discovered stylesheets are **not** written into `config.dependencies.stylesheets`; they stay on Component identity until collection. Inferred styles follow explicit styles and are emitted once per collection. Circular dependency traversal is guarded by Component config identity, so two Components in one file remain distinct.
+
+When a Page combines its own relative assets with a content entry, use `mergePageDependencies()`. Do not object-spread the two bags: spread copies `ownerFile` onto the other side's relative paths.
+
+```ts
+import { eco, mergePageDependencies } from '@ecopages/core';
+import { getEntryDependencies } from 'ecopages:content/posts/server';
+
+export default eco.page({
+	dependencies: async ({ props }) =>
+		mergePageDependencies({ stylesheets: ['./post.css'] }, await getEntryDependencies(props.slug)),
+	render: () => <article />,
+});
+```
+
+Browser scripts remain explicit:
+
+```ts
+scripts: [
+	{
+		src: './counter.script.ts',
+		ssr: true,
+		lazy: { 'on:visible': true },
+	},
+];
+```
+
+For Lit, this registers the custom element before server rendering while delaying browser execution until visibility. `ssr: true` does not force eager browser loading. To load eagerly, omit `lazy`. This corrects the previous behavior that emitted an extra eager script for SSR-enabled lazy entries.
+
+Named barrel re-exports (`export { Counter } from './counter'`) are followed for the imported binding only. Successful named re-export hops are watch paths, so retargeting a barrel updates page assets without editing the importing Page. Discovery does not follow `export * from './components'`, dynamic imports, namespace imports (`import * as`), package Components/CSS, CSS Modules, or custom import attributes. `export *` would pull an entire kit into the page asset graph; keep that explicit with `dependencies.components`. Plain-function modules retain their existing behavior. Ordinary utility imports do not become browser script entries. Missing supported imports report the owner file and import specifier.
+
 ## Component Patterns
 
 EcoPages supports two approaches for creating components, each suited for different use cases:
@@ -546,9 +597,6 @@ import { Counter } from '@/components/counter';
 
 export default eco.page({
 	layout: BaseLayout,
-	dependencies: {
-		components: [Counter],
-	},
 	metadata: () => ({
 		title: 'Home',
 		description: 'Welcome to EcoPages',
@@ -562,6 +610,8 @@ export default eco.page({
 });
 ```
 
+The static `Counter` import is discovered automatically. You do not list it again in `dependencies.components`. Lazy scripts stay on the Component.
+
 ## Type Definitions
 
 ```typescript
@@ -578,9 +628,25 @@ type DependencyEntry = {
 interface EcoComponentDependencies {
 	scripts?: Array<string | DependencyEntry>;
 	stylesheets?: Array<string | DependencyEntry>;
-	components?: EcoComponent[];
+	modules?: string[];
+	/** Declared eco components only — see `EcoDeclaredComponent`. */
+	components?: EcoDeclaredComponent[];
 }
 
+type FileOwnedDependencyContribution = EcoComponentDependencies & {
+	ownerFile?: string;
+};
+
+type PageDependenciesResult = FileOwnedDependencyContribution & {
+	contributions?: FileOwnedDependencyContribution[];
+};
+
+type GetPageDependencies<T> = (context: {
+	props: PagePropsFor<T>;
+	params?: Record<string, string>;
+	query?: Record<string, string>;
+}) => PageDependenciesResult | undefined | Promise<PageDependenciesResult | undefined>;
+
 // Shared base option shape used by component(), html(), and layout()
 interface ComponentOptions<P, E = EcoPagesElement> {
 	componentDir?: string;
@@ -595,7 +661,7 @@ type LayoutOptions<E = EcoPagesElement> = ComponentOptions<{ children: E }, E>;
 
 interface PageOptions<T, E = EcoPagesElement> {
 	componentDir?: string;
-	dependencies?: EcoComponentDependencies;
+	dependencies?: EcoComponentDependencies | GetPageDependencies<T>;
 	layout?: EcoComponent<{ children: E }>;
 	staticPaths?: GetStaticPaths;
 	staticProps?: GetStaticProps<T>;

package/src/eco/component-identity.d.ts

@@ -1,4 +1,5 @@
 import type { EcoComponent, EcoComponentConfig } from '../types/public-types.js';
+import { type DiscoveredDependencies } from './discovered-dependencies.js';
 /** Stable attribution for a Component created by an Integration-owned module. */
 export type ComponentIdentity = {
     id: string;
@@ -7,7 +8,7 @@ export type ComponentIdentity = {
 };
 /** Gets canonical component attribution. */
 export declare function getComponentIdentity(value: EcoComponent | EcoComponentConfig | undefined): ComponentIdentity | undefined;
-/** Merges attribution into factory options. */
-export declare function bindComponentIdentity<T extends object>(identity: ComponentIdentity, options: T): T & {
+/** Merges attribution into factory options. Optional discovered stylesheets stay keyed by identity. */
+export declare function bindComponentIdentity<T extends object>(identity: ComponentIdentity, options: T, discovered?: DiscoveredDependencies): T & {
     identity: ComponentIdentity;
 };

package/src/eco/component-identity.js

@@ -1,3 +1,4 @@
+import { registerDiscoveredDependencies } from './discovered-dependencies.js';
 function asConfig(value) {
     if (!value)
         return undefined;
@@ -12,7 +13,9 @@ export function getComponentIdentity(value) {
     const config = asConfig(value);
     return config?.identity;
 }
-/** Merges attribution into factory options. */
-export function bindComponentIdentity(identity, options) {
+/** Merges attribution into factory options. Optional discovered stylesheets stay keyed by identity. */
+export function bindComponentIdentity(identity, options, discovered) {
+    if (discovered)
+        registerDiscoveredDependencies(identity, discovered);
     return { ...options, identity };
 }

package/src/eco/discovered-dependencies.d.ts

@@ -0,0 +1,45 @@
+import type { EcoComponentConfig } from '../types/public-types.js';
+import type { ComponentIdentity } from './component-identity.js';
+export type DiscoveredDependencies = {
+    components: () => unknown[];
+    stylesheets: string[];
+    watchFiles?: string[];
+};
+/**
+ * Records discovered Components, inferred styles, and barrel watch hops on identity.
+ *
+ * @remarks
+ * Styles and watch hops are stored on the identity object through interned symbols so
+ * a bundled copy of this module still sees them during collection. The component getter
+ * stays on a same-isolate WeakMap and is attached to `config.dependencies` at factory time.
+ */
+export declare function registerDiscoveredDependencies(identity: ComponentIdentity, discovered: DiscoveredDependencies): void;
+/**
+ * Inferred stylesheet paths registered for this component identity.
+ *
+ * @remarks
+ * Provenance stays on identity so copying or merging `config.dependencies` cannot
+ * turn inferred styles into explicit ones. Paths are stored on the identity object
+ * so collection still sees them when server modules bundle a separate copy of `eco`.
+ * The collector prefers explicit entries across the whole graph by resolved path.
+ */
+export declare function getInferredStylesheets(config: EcoComponentConfig | undefined): readonly string[];
+/**
+ * Named re-export hops recorded for this component identity.
+ *
+ * @remarks
+ * Barrel files are not Component identity files. Collecting them as watch paths
+ * lets a barrel retarget invalidate HTML and Page Browser Graph caches without
+ * editing the importing Page.
+ */
+export declare function getDiscoveredWatchFiles(config: EcoComponentConfig | undefined): readonly string[];
+/**
+ * Attaches deferred discovered Component references to `config.dependencies`.
+ *
+ * @remarks
+ * The component getter reads live import bindings only during graph traversal,
+ * after module initialization. Inferred stylesheets stay keyed by identity and are
+ * not copied into the public bag, so rendering, SSR preload, ownership, and watch
+ * collectors share the same graph without object-identity bookkeeping.
+ */
+export declare function attachDiscoveredDependencies(config: EcoComponentConfig): void;

package/src/eco/discovered-dependencies.js

@@ -0,0 +1,87 @@
+const discoveries = new WeakMap();
+const INFERRED_STYLESHEETS = Symbol.for('ecopages.identity.inferredStylesheets');
+const DISCOVERED_WATCH_FILES = Symbol.for('ecopages.identity.watchFiles');
+function discoveryRecord(identity) {
+    return identity;
+}
+/**
+ * Records discovered Components, inferred styles, and barrel watch hops on identity.
+ *
+ * @remarks
+ * Styles and watch hops are stored on the identity object through interned symbols so
+ * a bundled copy of this module still sees them during collection. The component getter
+ * stays on a same-isolate WeakMap and is attached to `config.dependencies` at factory time.
+ */
+export function registerDiscoveredDependencies(identity, discovered) {
+    discoveries.set(identity, discovered);
+    const record = discoveryRecord(identity);
+    record[INFERRED_STYLESHEETS] = discovered.stylesheets;
+    record[DISCOVERED_WATCH_FILES] = discovered.watchFiles;
+}
+/**
+ * Inferred stylesheet paths registered for this component identity.
+ *
+ * @remarks
+ * Provenance stays on identity so copying or merging `config.dependencies` cannot
+ * turn inferred styles into explicit ones. Paths are stored on the identity object
+ * so collection still sees them when server modules bundle a separate copy of `eco`.
+ * The collector prefers explicit entries across the whole graph by resolved path.
+ */
+export function getInferredStylesheets(config) {
+    const identity = config?.identity;
+    if (!identity)
+        return [];
+    return discoveryRecord(identity)[INFERRED_STYLESHEETS] ?? discoveries.get(identity)?.stylesheets ?? [];
+}
+/**
+ * Named re-export hops recorded for this component identity.
+ *
+ * @remarks
+ * Barrel files are not Component identity files. Collecting them as watch paths
+ * lets a barrel retarget invalidate HTML and Page Browser Graph caches without
+ * editing the importing Page.
+ */
+export function getDiscoveredWatchFiles(config) {
+    const identity = config?.identity;
+    if (!identity)
+        return [];
+    return discoveryRecord(identity)[DISCOVERED_WATCH_FILES] ?? discoveries.get(identity)?.watchFiles ?? [];
+}
+function isDeclared(value) {
+    return typeof value === 'function' && Boolean(value.config?.identity);
+}
+/**
+ * Attaches deferred discovered Component references to `config.dependencies`.
+ *
+ * @remarks
+ * The component getter reads live import bindings only during graph traversal,
+ * after module initialization. Inferred stylesheets stay keyed by identity and are
+ * not copied into the public bag, so rendering, SSR preload, ownership, and watch
+ * collectors share the same graph without object-identity bookkeeping.
+ */
+export function attachDiscoveredDependencies(config) {
+    const discovery = config.identity && discoveries.get(config.identity);
+    if (!discovery)
+        return;
+    let explicit = config.dependencies;
+    let merged;
+    const merge = () => {
+        const current = explicit;
+        merged = {
+            ...current,
+            get components() {
+                return [...new Set([...(current?.components ?? []), ...discovery.components().filter(isDeclared)])];
+            },
+        };
+    };
+    merge();
+    Object.defineProperty(config, 'dependencies', {
+        enumerable: true,
+        configurable: true,
+        get: () => merged,
+        set: (value) => {
+            explicit = value;
+            merge();
+        },
+    });
+}

package/src/eco/eco.js

@@ -6,6 +6,7 @@ import { finalizeComponentRender, getComponentRenderContext, interceptForeignChi
 import { isThenable } from '../route-renderer/orchestration/foreign-child/foreign-child-output.utils.js';
 import { applyPageLayoutConfig, mergeLayoutDependencies, normalizePageLayouts } from './page-layout-normalization.js';
 import { getComponentIdentity } from './component-identity.js';
+import { attachDiscoveredDependencies } from './discovered-dependencies.js';
 /**
  * Creates a component factory with lazy-trigger support and foreign-child-runtime
  * interception.
@@ -58,6 +59,7 @@ function createComponentFactory(options) {
         integration: options.integration,
         dependencies: options.dependencies,
     };
+    attachDiscoveredDependencies(comp.config);
     return comp;
 }
 /**

package/src/eco/eco.types.d.ts

@@ -64,11 +64,27 @@ export type GetPageDependenciesContext<T = Record<string, unknown>> = {
     query?: PageQuery;
 };
 /**
- * Page dependency bag optionally scoped to a declaring file.
+ * Explicit dependency declarations owned by one file.
+ *
+ * @remarks
+ * Relative `scripts`, `stylesheets`, and `modules` resolve against `ownerFile`
+ * when present. Component entries keep their own identity files. Inferred
+ * stylesheets are not stored here; the collector reads them from identity.
  */
-export type PageDependenciesResult = EcoComponentDependencies & {
+export type FileOwnedDependencyContribution = EcoComponentDependencies & {
     ownerFile?: string;
 };
+/**
+ * Page dependency bag made of one or more file-owned contributions.
+ *
+ * @remarks
+ * A single bag with `ownerFile` is one contribution. `contributions` keeps
+ * assets from different files separate until collection, so merging a Page and
+ * a content entry cannot re-home relative paths.
+ */
+export type PageDependenciesResult = FileOwnedDependencyContribution & {
+    contributions?: FileOwnedDependencyContribution[];
+};
 /**
  * Resolves request-specific page dependencies for one route render.
  */

package/src/eco/page-dependency-contributions.d.ts

@@ -0,0 +1,19 @@
+import type { EcoComponentDependencies, FileOwnedDependencyContribution, PageDependenciesResult } from '../types/public-types.js';
+/**
+ * Expands a page dependency result into file-owned contributions.
+ *
+ * @remarks
+ * Nested `contributions` are expanded so collection can resolve each bag against
+ * its own owner. Empty bags are omitted.
+ */
+export declare function listFileOwnedDependencyContributions(value: PageDependenciesResult | EcoComponentDependencies | undefined): FileOwnedDependencyContribution[];
+/**
+ * Merges base page dependencies with additional dependencies (such as those returned by a content entry).
+ *
+ * @remarks
+ * Keeps each file-owned contribution intact, including `modules`. Relative assets
+ * are not flattened under a single `ownerFile`, so a Page's `./page.css` cannot
+ * resolve against a content entry directory. Object-spread of two bags copies
+ * `ownerFile` onto the other side's relative paths; use this helper instead.
+ */
+export declare function mergePageDependencies(base: EcoComponentDependencies | undefined, additional: PageDependenciesResult | EcoComponentDependencies | undefined): PageDependenciesResult | undefined;

package/src/eco/page-dependency-contributions.js

@@ -0,0 +1,52 @@
+function hasCollectableDependencyFields(dependencies) {
+    return Boolean(dependencies.stylesheets?.length ||
+        dependencies.scripts?.length ||
+        dependencies.modules?.length ||
+        dependencies.components?.length);
+}
+/**
+ * Expands a page dependency result into file-owned contributions.
+ *
+ * @remarks
+ * Nested `contributions` are expanded so collection can resolve each bag against
+ * its own owner. Empty bags are omitted.
+ */
+export function listFileOwnedDependencyContributions(value) {
+    if (!value)
+        return [];
+    const result = value;
+    const nested = result.contributions ?? [];
+    const { contributions: _contributions, ownerFile, ...dependencies } = result;
+    const listed = [];
+    if (hasCollectableDependencyFields(dependencies)) {
+        listed.push(ownerFile ? { ...dependencies, ownerFile } : dependencies);
+    }
+    for (const contribution of nested) {
+        listed.push(...listFileOwnedDependencyContributions(contribution));
+    }
+    return listed;
+}
+/**
+ * Merges base page dependencies with additional dependencies (such as those returned by a content entry).
+ *
+ * @remarks
+ * Keeps each file-owned contribution intact, including `modules`. Relative assets
+ * are not flattened under a single `ownerFile`, so a Page's `./page.css` cannot
+ * resolve against a content entry directory. Object-spread of two bags copies
+ * `ownerFile` onto the other side's relative paths; use this helper instead.
+ */
+export function mergePageDependencies(base, additional) {
+    if (!base)
+        return additional;
+    if (!additional)
+        return base;
+    const contributions = [
+        ...listFileOwnedDependencyContributions(base),
+        ...listFileOwnedDependencyContributions(additional),
+    ];
+    if (contributions.length === 0)
+        return undefined;
+    if (contributions.length === 1)
+        return contributions[0];
+    return { contributions };
+}

package/src/index.browser.d.ts

@@ -2,3 +2,6 @@ export type * from './types/public-types.js';
 export type * from './eco/eco.types.js';
 export { eco } from './eco/eco.browser.js';
 export { bindComponentIdentity, getComponentIdentity, type ComponentIdentity } from './eco/component-identity.js';
+export { attachDiscoveredDependencies } from './eco/discovered-dependencies.js';
+export { listFileOwnedDependencyContributions, mergePageDependencies } from './eco/page-dependency-contributions.js';
+export { mergeLayoutDependencies } from './eco/page-layout-normalization.js';

package/src/index.browser.js

@@ -1,2 +1,5 @@
 export { eco } from './eco/eco.browser.js';
 export { bindComponentIdentity, getComponentIdentity } from './eco/component-identity.js';
+export { attachDiscoveredDependencies } from './eco/discovered-dependencies.js';
+export { listFileOwnedDependencyContributions, mergePageDependencies } from './eco/page-dependency-contributions.js';
+export { mergeLayoutDependencies } from './eco/page-layout-normalization.js';