@ecopages/core 0.2.0-beta.3 → 0.2.0-beta.31

package/src/plugins/source-transform.d.ts

@@ -1,12 +1,24 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
 export interface EcoSourceTransformResult {
     code: string;
     map?: unknown;
 }
+/**
+ * Bundler-neutral source transform registered on {@link EcoPagesAppConfig.sourceTransforms}.
+ *
+ * @remarks
+ * Prefer this shape over a competing {@link EcoBuildPlugin} `onLoad` handler when
+ * the transform only rewrites module source. Browser/HMR builds run source
+ * transforms after first-wins `onLoad` plugins, so metadata injection and similar
+ * passes still run on rewritten output from boundary/runtime plugins.
+ */
 export interface EcoSourceTransform {
+    /** Stable transform name. Also used to dedupe loader plugins in browser builds. */
     name: string;
+    /** File-path filter tested against {@link normalizeTransformId | normalized ids}. */
     filter: RegExp;
+    /** Runs before default transforms, or after them when set to `post`. */
     enforce?: 'pre' | 'post';
     transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
 }
@@ -24,8 +36,27 @@ export declare function normalizeTransformId(id: string): string;
  * Applies one source transform if the normalized id matches its filter.
  */
 export declare function applySourceTransform(transform: EcoSourceTransform, code: string, id: string): EcoSourceTransformResult | string | undefined;
+/**
+ * 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 declare function applySourceTransforms(transforms: readonly EcoSourceTransform[], code: string, id: string): string;
 /**
  * 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 declare function createEcoBuildPluginFromSourceTransform(transform: EcoSourceTransform): EcoBuildPlugin;
 /**

package/src/plugins/source-transform.js

@@ -13,6 +13,27 @@ function applySourceTransform(transform, code, id) {
   }
   return transform.transform(code, normalizedId);
 }
+const SOURCE_TRANSFORM_ENFORCE_ORDER = {
+  pre: 0,
+  default: 1,
+  post: 2
+};
+function getSourceTransformEnforceOrder(transform) {
+  return SOURCE_TRANSFORM_ENFORCE_ORDER[transform.enforce ?? "default"];
+}
+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) {
+      continue;
+    }
+    current = typeof result === "string" ? result : result.code;
+  }
+  return current;
+}
 function inferLoaderFromPath(filePath) {
   const extension = path.extname(filePath).toLowerCase();
   switch (extension) {
@@ -56,13 +77,14 @@ function createVitePluginFromSourceTransform(transform) {
   };
 }
 function getAppSourceTransforms(appConfig) {
-  return Array.from(appConfig.sourceTransforms.values());
+  return appConfig.sourceTransforms ? Array.from(appConfig.sourceTransforms.values()) : [];
 }
 function createVitePluginsFromAppSourceTransforms(appConfig) {
   return getAppSourceTransforms(appConfig).map((transform) => createVitePluginFromSourceTransform(transform));
 }
 export {
   applySourceTransform,
+  applySourceTransforms,
   createEcoBuildPluginFromSourceTransform,
   createVitePluginFromSourceTransform,
   createVitePluginsFromAppSourceTransforms,

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

@@ -0,0 +1,18 @@
+/**
+ * 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 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,159 @@
+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();
+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 : void 0;
+}
+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;
+    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 matchesTsconfigPathPrefix(specifier, prefixes) {
+  return prefixes.some((prefix) => {
+    if (prefix.endsWith("/")) {
+      return specifier.startsWith(prefix);
+    }
+    return specifier === prefix || specifier.startsWith(`${prefix}/`);
+  });
+}
+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;
+}
+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;
+}
+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));
+}
+function resolveProjectImportPath(projectRoot, fromFile, specifier) {
+  if (!matchesTsconfigPathPrefix(specifier, loadTsconfigPathPrefixes(projectRoot))) {
+    return void 0;
+  }
+  return resolveProjectModulePath(projectRoot, fromFile, specifier);
+}
+export {
+  isBarePackageImportSpecifier,
+  loadTsconfigPathPrefixes,
+  matchesTsconfigPathPrefix,
+  resolveProjectImportPath,
+  resolveProjectModulePath
+};

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`

package/src/route-renderer/README.md

@@ -16,18 +16,30 @@ The route renderer layer is responsible for:
 
 The architecture is organized around three distinct concepts:
 
-- `ownership`: preparation-time metadata that describes which integration owns each declared component edge
+- `ownership`: declared component dependency metadata validated before render
 - `foreign child`: a component encountered during render whose owning integration differs from the current integration
 - `foreign subtree`: the resolved HTML, assets, and root-attachment metadata returned by the owning renderer for that foreign child
 
 These concepts intentionally live in different places:
 
-- `ownership-planning.service.ts` builds `ownershipPlan`
-- `ownership-validation.service.ts` validates declared foreign ownership up front
+- `ownership-validation.service.ts` validates declared foreign ownership up front and fails the render on misconfiguration
 - `component-render-context.ts` intercepts foreign children during active component render
-- `queued-foreign-subtree-resolution.service.ts` resolves queued foreign subtrees for renderers that cannot hand them off inline
-- `integration-renderer.ts` owns renderer-to-renderer delegation and shared shell composition
-- `route-render-flow.ts` owns route preparation, final response capture, and unresolved artifact enforcement
+- `foreign-subtree-execution.service.ts` owns mixed-integration execution policy and queued token resolution
+- `document-shell-render.service.ts` composes page, layout, and html template shells with one execution-scoped renderer cache
+- `integration-renderer.ts` owns renderer-to-renderer delegation and integration-specific render hooks
+- `route-render-orchestrator.ts` owns route preparation, final response capture, and unresolved artifact enforcement
+
+## Build-Time JSX vs Runtime Foreign Children
+
+Mixed-integration apps use two separate mechanisms:
+
+| Layer   | Mechanism                                                         | Purpose                                                                                  |
+| ------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Build   | `getJsxOwnershipPlugins()` / `getHostScopedJsxOwnershipPlugins()` | Prepend `@jsxImportSource` so bundled `.tsx` files compile with the correct JSX runtime  |
+| Build   | `eco-component-meta-plugin`                                       | Prepends the owning integration pragma when injecting `__eco` metadata into native files |
+| Runtime | `eco.component()` / `eco.embed()` + foreign-child runtime         | Hand off cross-integration children during SSR                                           |
+
+See [`../build/README.md`](../build/README.md) for the JSX ownership helper split.
 
 ## Main Files
 
@@ -38,13 +50,18 @@ These concepts intentionally live in different places:
 
 ### `orchestration/`
 
-- `route-render-flow.ts`: one route render from page-module loading through final HTML output
+Root renderer classes:
+
 - `integration-renderer.ts`: abstract base class for route rendering, explicit view rendering, and foreign-child delegation
-- `ownership-planning.service.ts`: declared ownership graph construction
-- `ownership-validation.service.ts`: up-front ownership validation for route roots and declared descendants
-- `component-render-context.ts`: active render context used by `eco.component()` to intercept foreign children
-- `queued-foreign-subtree-resolution.service.ts`: queue resolution for renderers that need token-based foreign-subtree handoff
-- `render-output.utils.ts`: unresolved artifact normalization and marker inspection
+- `string-markup-renderer.ts`: shared base for string-markup integrations
+
+Domain folders:
+
+- `ownership-graph/`: component graph walk/collect and up-front ownership validation
+- `foreign-child/`: active render context, foreign-subtree execution, deferred template serialization
+- `document-shell/`: shared page/layout/html shell composition and attribute stamping helpers
+- `route-pipeline/`: route preparation, final HTML capture, marker-artifact enforcement
+- `page-browser-graph/`: browser asset graph build, session cache, and injector assets
 
 ### `page-loading/`
 
@@ -56,11 +73,11 @@ These concepts intentionally live in different places:
 The route-render contract is:
 
 1. `RouteRendererFactory` selects the owning integration renderer.
-2. `IntegrationRenderer.execute()` delegates preparation and finalization to `RouteRenderFlow`.
-3. `RouteRenderFlow.prepareRenderOptions()` loads the page module, validates ownership, builds `ownershipPlan`, resolves page data, resolves dependencies, and builds the page browser graph.
+2. `IntegrationRenderer.execute()` delegates preparation and finalization to `RouteRenderOrchestrator`.
+3. `RouteRenderOrchestrator.prepareRenderOptions()` loads the page module, validates ownership (fail-fast), resolves page data, resolves dependencies, and builds the page browser graph.
 4. The integration renderer performs page, layout, and document-shell rendering. When it encounters a foreign child, it delegates that child back to the owning renderer.
 5. If a renderer needs queued handoff, it emits internal foreign-subtree tokens and resolves them before returning final HTML.
-6. `RouteRenderFlow.execute()` captures the final body, rejects unresolved `<eco-marker>` artifacts, stamps root or document attributes when needed, and runs the HTML transformer.
+6. `RouteRenderOrchestrator.executePrepared()` captures the final body, rejects unresolved `<eco-marker>` artifacts, stamps document attributes when needed, and runs the HTML transformer.
 
 Important:
 
@@ -72,38 +89,28 @@ Important:
 
 Mixed-integration component configs must declare every possible foreign child in `config.dependencies.components`.
 
-That declaration is used for two things:
-
-- `OwnershipValidationService` surfaces missing metadata or unknown integrations before render execution
-- `OwnershipPlanningService` records the expected ownership shape in `ownershipPlan`
+`OwnershipValidationService` surfaces missing metadata or unknown integrations during `prepareRenderOptions()` and throws before render execution starts.
 
 At runtime, renderers still discover actual foreign children through the active component render context.
 
 ## Foreign Subtree Contract
 
-`renderForeignSubtree()` is the compatibility contract for renderer-to-renderer handoff. It returns:
-
-- `html`
-- `assets`
-- `rootTag`
-- optional `rootAttributes`
-- `attachmentPolicy`
-- `integrationName`
-
-`renderComponentWithForeignChildren()` is the higher-level renderer entrypoint. It is responsible for:
+`renderComponentWithForeignChildren()` is the renderer entrypoint for mixed-integration trees. It is responsible for:
 
 - reusing the execution-scoped owning-renderer cache
 - deciding whether the current component can stay local
 - creating a foreign-child runtime when nested foreign ownership must be resolved
 - normalizing unresolved artifact HTML before the render leaves the renderer
 
+Queue resolution maps owning-renderer output into the foreign-subtree payload shape via `toForeignSubtreeRenderPayload()` inside `foreign-subtree-execution.service.ts`.
+
 ## Queue Model
 
 Not every integration needs queue-based handoff.
 
 - If a renderer can resolve a foreign child inline, it returns resolved output immediately.
 - If it cannot, it may emit internal foreign-subtree tokens and resolve them before returning final HTML.
-- The queue service is only for renderer-owned transport inside one render pass. It is not a general route-level fallback mechanism.
+- Queue mechanics live inside `ForeignSubtreeExecutionService`; they are renderer-owned transport inside one render pass, not a general route-level fallback mechanism.
 
 ## React Island Notes
 
@@ -114,5 +121,5 @@ Not every integration needs queue-based handoff.
 
 ## Current Limits
 
-- `ownershipPlan` is still diagnostic and preparatory metadata; it does not yet drive a full route-composer execution model.
 - Different integrations still own different foreign-child runtime strategies, which is intentional where child transport or hydration behavior differs.
+- `integration-renderer.ts` remains the largest integration hook surface even after document-shell extraction.

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

@@ -0,0 +1,107 @@
+import type { BaseIntegrationContext, ComponentRenderInput, ComponentRenderResult, EcoComponent, PageMetadataProps } from '../../../types/public-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 = {
+    component: EcoComponent;
+    props?: Record<string, unknown>;
+};
+export type DocumentShellComposeChildrenContext = {
+    primaryComponent: EcoComponent;
+    primaryProps: Record<string, unknown>;
+    primaryRender?: ComponentRenderResult;
+    layouts: DocumentShellLayoutInput[];
+    rendererCache: BaseIntegrationContext['rendererCache'];
+    renderComponentWithForeignChildren: DocumentShellRenderDependencies['renderComponentWithForeignChildren'];
+};
+export type DocumentShellComposeChildrenResult = {
+    /** Serialized or element children passed to the HTML template shell. */
+    children: unknown;
+    layoutRenders: ComponentRenderResult[];
+    /**
+     * Primary/page render assets when the hook performs unified composition.
+     *
+     * @remarks
+     * Omit only when the default sequential string path runs (core renders primary first).
+     */
+    primaryRender?: ComponentRenderResult;
+};
+/**
+ * Optional hook that replaces default sequential string layout wrapping.
+ *
+ * @remarks
+ * When provided, core skips the initial primary render and expects the hook to return
+ * `children` for the HTML template. Supply `primaryRender` so dependency assets still merge.
+ */
+export type DocumentShellComposeChildrenHook = (context: DocumentShellComposeChildrenContext) => Promise<DocumentShellComposeChildrenResult>;
+export type DocumentShellComposeInput = {
+    primaryComponent: EcoComponent;
+    primaryProps: Record<string, unknown>;
+    layout?: DocumentShellLayoutInput;
+    layouts?: DocumentShellLayoutInput[];
+    composeChildren?: DocumentShellComposeChildrenHook;
+    htmlTemplate: EcoComponent;
+    documentProps: Record<string, unknown>;
+};
+export type DocumentShellPageRenderInput = {
+    page: {
+        component: EcoComponent;
+        props: Record<string, unknown>;
+    };
+    layout?: DocumentShellLayoutInput;
+    layouts?: DocumentShellLayoutInput[];
+    composeChildren?: DocumentShellComposeChildrenHook;
+    htmlTemplate: EcoComponent;
+    metadata: PageMetadataProps;
+    pageProps: Record<string, unknown>;
+    documentProps?: Record<string, unknown>;
+    transformDocumentHtml?: (html: string) => string;
+};
+export type DocumentShellRenderDependencies = {
+    renderComponentWithForeignChildren(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    appendProcessedDependencies(...assetGroups: Array<readonly ProcessedAsset[] | undefined>): ProcessedAsset[];
+};
+export type DocumentShellAttributeStamping = {
+    applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+    applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
+};
+/**
+ * Default sequential string-child composition for document shell layers.
+ */
+export declare function composeSequentialLayoutChildren(context: DocumentShellComposeChildrenContext): Promise<DocumentShellComposeChildrenResult>;
+/**
+ * Composes page or view content through optional layout and document shells.
+ *
+ * One execution-scoped renderer cache is threaded through every shell layer so
+ * repeated foreign delegation reuses initialized renderers within one render pass.
+ */
+export declare function composeDocumentShell(dependencies: DocumentShellRenderDependencies, input: DocumentShellComposeInput): Promise<{
+    documentHtml: string;
+}>;
+/**
+ * Applies optional component-root and document-root attribute stamping before HTML
+ * transformation runs on explicit renderer-owned paths.
+ */
+export declare function applyDocumentShellAttributeStamping(html: string, stamping: DocumentShellAttributeStamping, options: {
+    componentRootAttributes?: Record<string, string>;
+    documentAttributes?: Record<string, string>;
+}): string;
+/**
+ * Builds the final serialized document HTML for one route page render.
+ */
+export declare function renderPageDocumentShell(dependencies: DocumentShellRenderDependencies, input: DocumentShellPageRenderInput, docType: string): Promise<string>;
+/**
+ * Finalizes already-resolved HTML for explicit renderer-owned paths.
+ *
+ * @remarks
+ * Callers append renderer bootstrap dependencies before invoking this helper.
+ * Stamps document/root attributes and runs HTML transformation after nested
+ * foreign-subtree resolution without routing back through shared route execution.
+ */
+export declare function finalizeDocumentShellHtml(htmlTransformer: HtmlTransformerService, options: {
+    html: string;
+    partial?: boolean;
+    componentRootAttributes?: Record<string, string>;
+    documentAttributes?: Record<string, string>;
+    transformHtml?: boolean;
+    htmlContributions?: HtmlDocumentContribution[];
+}): Promise<string>;