@ecopages/core 0.2.0-alpha.1 → 0.2.0-alpha.10

package/src/hmr/strategies/js-hmr-strategy.js

@@ -2,13 +2,13 @@ import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
 import { HmrStrategy, HmrStrategyType } from "../hmr-strategy";
 import { appLogger } from "../../global/app-logger";
-import { defaultBuildAdapter } from "../../build/build-adapter.js";
 class JsHmrStrategy extends HmrStrategy {
+  type = HmrStrategyType.SCRIPT;
+  context;
   constructor(context) {
     super();
     this.context = context;
   }
-  type = HmrStrategyType.SCRIPT;
   /**
    * Determines if the file is a JS/TS file that could affect registered entrypoints.
    *
@@ -23,10 +23,25 @@ class JsHmrStrategy extends HmrStrategy {
     const watchedFiles = this.context.getWatchedFiles();
     const isJsTs = /\.(ts|tsx|js|jsx)$/.test(filePath);
     const isInSrc = filePath.startsWith(this.context.getSrcDir());
+    const isRouteTemplate = filePath.startsWith(this.context.getPagesDir()) || filePath.startsWith(this.context.getLayoutsDir());
+    const isIntegrationTemplate = isRouteTemplate && this.context.getTemplateExtensions().some((extension) => filePath.endsWith(extension));
     if (watchedFiles.size === 0) {
       return false;
     }
-    return isJsTs && isInSrc;
+    if (!isJsTs || !isInSrc) {
+      return false;
+    }
+    if (isIntegrationTemplate) {
+      return false;
+    }
+    if (watchedFiles.has(filePath)) {
+      return true;
+    }
+    const entrypointDependencyGraph = this.context.getEntrypointDependencyGraph();
+    if (entrypointDependencyGraph.supportsSelectiveInvalidation()) {
+      return entrypointDependencyGraph.getDependencyEntrypoints(filePath).size > 0;
+    }
+    return true;
   }
   /**
    * Processes a file change by rebuilding affected entrypoints.
@@ -36,6 +51,8 @@ class JsHmrStrategy extends HmrStrategy {
    * @remarks
    * If runtime-specific dependency graph hooks are unavailable, this strategy
    * falls back to rebuilding all watched entrypoints.
+   * When multiple entrypoints are impacted they are bundled in a single esbuild
+   * invocation to share AST parsing and chunk deduplication.
    * @returns Action to broadcast update events
    */
   async process(filePath) {
@@ -45,24 +62,37 @@ class JsHmrStrategy extends HmrStrategy {
       appLogger.debug(`[JsHmrStrategy] No watched files to rebuild`);
       return { type: "none" };
     }
-    const updates = [];
-    let reloadRequired = false;
-    const dependencyHits = this.context.getDependencyEntrypoints?.(filePath) ?? /* @__PURE__ */ new Set();
+    const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
     const hasDependencyHit = dependencyHits.size > 0;
     const impactedEntrypoints = hasDependencyHit ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(entrypoint)) : Array.from(watchedFiles.keys());
+    const buildableEntrypoints = impactedEntrypoints.filter(
+      (entrypoint) => this.context.shouldProcessEntrypoint?.(entrypoint) ?? true
+    );
     if (!hasDependencyHit) {
       appLogger.debug("[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints");
     }
-    for (const entrypoint of impactedEntrypoints) {
+    if (buildableEntrypoints.length === 0) {
+      return { type: "none" };
+    }
+    const buildResult = await this.bundleEntrypoints(buildableEntrypoints);
+    if (!buildResult.success) {
+      return { type: "none" };
+    }
+    const updates = [];
+    let reloadRequired = false;
+    for (const entrypoint of buildableEntrypoints) {
       const outputUrl = watchedFiles.get(entrypoint);
-      if (!outputUrl) {
-        continue;
+      if (!outputUrl) continue;
+      if (buildResult.dependencies) {
+        const entrypointDeps = buildResult.dependencies.get(path.resolve(entrypoint)) ?? [];
+        this.context.getEntrypointDependencyGraph().setEntrypointDependencies(entrypoint, entrypointDeps);
       }
-      const result = await this.bundleEntrypoint(entrypoint, outputUrl);
+      const srcDir = this.context.getSrcDir();
+      const relativePath = path.relative(srcDir, entrypoint);
+      const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
+      const outputPath = path.join(this.context.getDistDir(), relativePathJs);
+      const result = await this.processOutput(outputPath, outputUrl);
       if (result.success) {
-        if (result.dependencies && this.context.setEntrypointDependencies) {
-          this.context.setEntrypointDependencies(entrypoint, result.dependencies);
-        }
         updates.push(outputUrl);
         if (result.requiresReload) {
           reloadRequired = true;
@@ -74,18 +104,14 @@ class JsHmrStrategy extends HmrStrategy {
         appLogger.debug(`[JsHmrStrategy] Full reload required (no HMR accept found)`);
         return {
           type: "broadcast",
-          events: [
-            {
-              type: "reload"
-            }
-          ]
+          events: [{ type: "reload" }]
         };
       }
       return {
         type: "broadcast",
-        events: updates.map((path2) => ({
+        events: updates.map((p) => ({
           type: "update",
-          path: path2,
+          path: p,
           timestamp: Date.now()
         }))
       };
@@ -93,44 +119,40 @@ class JsHmrStrategy extends HmrStrategy {
     return { type: "none" };
   }
   /**
-   * Bundles a single entrypoint and processes the output.
-   *
-   * @param entrypointPath - Absolute path to the source file
-   * @param outputUrl - URL path for the bundled file
-   * @returns True if bundling was successful
+   * Bundles one or more entrypoints in a single esbuild invocation.
+   * Uses the source directory as the output base so that the directory structure
+   * is preserved under the HMR dist folder.
    */
-  async bundleEntrypoint(entrypointPath, outputUrl) {
+  async bundleEntrypoints(entrypoints) {
     try {
-      const srcDir = this.context.getSrcDir();
-      const relativePath = path.relative(srcDir, entrypointPath);
-      const relativePathJs = relativePath.replace(/\.(tsx?|jsx?)$/, ".js");
-      const outputPath = path.join(this.context.getDistDir(), relativePathJs);
-      const result = await defaultBuildAdapter.build({
-        entrypoints: [entrypointPath],
+      const result = await this.context.getBrowserBundleService().bundle({
+        profile: "hmr-entrypoint",
+        entrypoints,
         outdir: this.context.getDistDir(),
-        naming: relativePathJs,
-        ...defaultBuildAdapter.getTranspileOptions("hmr-entrypoint"),
+        outbase: this.context.getSrcDir(),
+        naming: "[dir]/[name]",
         plugins: this.context.getPlugins(),
-        minify: false,
-        external: ["react", "react-dom"]
+        minify: false
       });
       if (!result.success) {
-        appLogger.error(`[JsHmrStrategy] Failed to build ${entrypointPath}:`, result.logs);
-        return { success: false, requiresReload: false, dependencies: void 0 };
+        appLogger.error("[JsHmrStrategy] Batched build failed:", result.logs);
+        return { success: false };
       }
-      const dependencyGraph = result.dependencyGraph?.entrypoints?.[path.resolve(entrypointPath)] ?? [];
-      const output = await this.processOutput(outputPath, outputUrl);
-      return {
-        ...output,
-        dependencies: dependencyGraph
-      };
+      const dependencies = /* @__PURE__ */ new Map();
+      if (result.dependencyGraph?.entrypoints) {
+        for (const [entrypoint, deps] of Object.entries(result.dependencyGraph.entrypoints)) {
+          dependencies.set(path.resolve(entrypoint), deps);
+        }
+      }
+      return { success: true, dependencies };
     } catch (error) {
-      appLogger.error(`[JsHmrStrategy] Error bundling ${entrypointPath}:`, error);
-      return { success: false, requiresReload: false, dependencies: void 0 };
+      appLogger.error("[JsHmrStrategy] Error in batched build:", error);
+      return { success: false };
     }
   }
   /**
-   * Processes bundled output by replacing specifiers and injecting HMR code.
+   * Processes bundled output and determines whether the browser can hot-accept
+   * the update or must fall back to a full reload.
    *
    * @param filepath - Path to the bundled output file
    * @param url - URL path for the bundled file
@@ -138,12 +160,10 @@ class JsHmrStrategy extends HmrStrategy {
    */
   async processOutput(filepath, url) {
     try {
-      let code = await fileSystem.readFile(filepath);
+      const code = await fileSystem.readFile(filepath);
       if (code.includes("/* [ecopages] hmr */")) {
         return { success: true, requiresReload: !code.includes("import.meta.hot.accept") };
       }
-      code = this.replaceBareSpecifiers(code);
-      await fileSystem.writeAsync(filepath, code);
       appLogger.debug(`[JsHmrStrategy] Processed ${url}`);
       const hasHmrAccept = code.includes("import.meta.hot.accept");
       return { success: true, requiresReload: !hasHmrAccept };
@@ -152,27 +172,6 @@ class JsHmrStrategy extends HmrStrategy {
       return { success: false, requiresReload: false };
     }
   }
-  /**
-   * Replaces bare specifiers with vendor URLs.
-   *
-   * Handles both static imports and dynamic imports.
-   *
-   * @param code - The bundled code to transform
-   * @returns The transformed code with vendor URLs
-   */
-  replaceBareSpecifiers(code) {
-    const specifierMap = this.context.getSpecifierMap();
-    if (specifierMap.size === 0) {
-      return code;
-    }
-    let result = code;
-    for (const [bareSpec, vendorUrl] of specifierMap.entries()) {
-      const escaped = bareSpec.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      result = result.replace(new RegExp(`from\\s*["']${escaped}["']`, "g"), `from "${vendorUrl}"`);
-      result = result.replace(new RegExp(`import\\(["']${escaped}["']\\)`, "g"), `import("${vendorUrl}")`);
-    }
-    return result;
-  }
 }
 export {
   JsHmrStrategy

package/src/index.d.ts

@@ -2,4 +2,4 @@ export type * from './public-types.js';
 export type * from './eco/eco.types.js';
 export { eco } from './eco/eco.js';
 export { EcopagesApp, createApp, type EcopagesAppOptions } from './create-app.js';
-export { defineApiHandler, defineGroupHandler, type GroupHandler } from './define-api-handler.js';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from './adapters/shared/define-api-handler.js';

package/src/index.js

@@ -1,6 +1,6 @@
 import { eco } from "./eco/eco.js";
 import { EcopagesApp, createApp } from "./create-app.js";
-import { defineApiHandler, defineGroupHandler } from "./define-api-handler.js";
+import { defineApiHandler, defineGroupHandler } from "./adapters/shared/define-api-handler.js";
 export {
   EcopagesApp,
   createApp,

package/src/integrations/ghtml/ghtml-renderer.d.ts

@@ -3,7 +3,7 @@
  * @module
  */
 import type { EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../public-types.js';
-import { IntegrationRenderer, type RenderToResponseContext } from '../../route-renderer/integration-renderer.js';
+import { IntegrationRenderer, type RenderToResponseContext } from '../../route-renderer/orchestration/integration-renderer.js';
 /**
  * A renderer for the ghtml integration.
  * It renders a page using the HtmlTemplate and Page components.

package/src/integrations/ghtml/ghtml-renderer.js

@@ -1,4 +1,6 @@
-import { IntegrationRenderer } from "../../route-renderer/integration-renderer.js";
+import {
+  IntegrationRenderer
+} from "../../route-renderer/orchestration/integration-renderer.js";
 import { GHTML_PLUGIN_NAME } from "./ghtml.plugin.js";
 class GhtmlRenderer extends IntegrationRenderer {
   name = GHTML_PLUGIN_NAME;

package/src/internal-types.d.ts

@@ -1,17 +1,17 @@
 import type { EcoBuildPlugin } from './build/build-types.js';
+import type { AppBuildManifest } from './build/build-manifest.js';
+import type { BuildAdapter, BuildExecutor } from './build/build-adapter.js';
 import type { IntegrationPlugin } from './plugins/integration-plugin.js';
 import type { Processor } from './plugins/processor.js';
 import type { PageMetadataProps } from './public-types.js';
-import type { FSRouter } from './router/fs-router.js';
+import type { FSRouter } from './router/server/fs-router.js';
 import type { CacheConfig } from './services/cache/cache.types.js';
-/**
- * The templates used to build the pages and loaded via the includes directory.
- */
-export type IncludesTemplates = {
-    head: string;
-    html: string;
-    seo: string;
-};
+import type { DevGraphService } from './services/runtime-state/dev-graph.service.js';
+import type { EntrypointDependencyGraph } from './services/runtime-state/entrypoint-dependency-graph.service.js';
+import type { NodeRuntimeManifest } from './services/runtime-manifest/node-runtime-manifest.service.js';
+import type { RuntimeSpecifierRegistry } from './services/runtime-state/runtime-specifier-registry.service.js';
+import type { ServerInvalidationState } from './services/runtime-state/server-invalidation-state.service.js';
+import type { ServerModuleTranspiler } from './services/module-loading/server-module-transpiler.service.js';
 export interface RobotsPreference {
     /**
      * The user agent
@@ -58,20 +58,22 @@ export type EcoPagesAppConfig = {
      * @default "layouts"
      */
     layoutsDir: string;
-    /**
-     * The templates used for the pages
-     * @default "{head: 'head.kita.tsx', html: 'html.kita.tsx', seo: 'seo.kita.tsx'}"
-     */
-    includesTemplates: IncludesTemplates;
-    /** Error 404 page
-     * @default "404.kita.tsx"
-     */
-    error404Template: string;
     /**
      * The directory where the output will be located
      * @default "dist"
      */
     distDir: string;
+    /**
+     * The directory where internal runtime and build artifacts are stored.
+     *
+     * @remarks
+     * This directory is not intended for deployment. It owns transpiled server
+     * modules, runtime manifests, and processor caches so `distDir` can remain a
+     * clean export tree.
+     *
+     * @default ".eco"
+     */
+    workDir: string;
     /**
      * The templates extensions based on the integrations
      */
@@ -106,6 +108,7 @@ export type EcoPagesAppConfig = {
         config: string;
         componentsDir: string;
         distDir: string;
+        workDir: string;
         includesDir: string;
         layoutsDir: string;
         pagesDir: string;
@@ -128,6 +131,24 @@ export type EcoPagesAppConfig = {
      * @default { store: 'memory', defaultStrategy: 'static', enabled: true }
      */
     cache?: CacheConfig;
+    /**
+     * Runtime-owned services attached after config construction.
+     *
+     * These values are internal implementation details used to thread per-app
+     * executors and similar runtime state through the system without relying on
+     * process-global registries.
+     */
+    runtime?: {
+        buildAdapter?: BuildAdapter;
+        buildManifest?: AppBuildManifest;
+        buildExecutor?: BuildExecutor;
+        devGraphService?: DevGraphService;
+        entrypointDependencyGraph?: EntrypointDependencyGraph;
+        nodeRuntimeManifest?: NodeRuntimeManifest;
+        runtimeSpecifierRegistry?: RuntimeSpecifierRegistry;
+        serverInvalidationState?: ServerInvalidationState;
+        serverModuleTranspiler?: ServerModuleTranspiler;
+    };
     /**
      * Experimental features.
      */

package/src/plugins/README.md

@@ -0,0 +1,34 @@
+# Plugin Contracts
+
+This directory contains the authoring contracts for Ecopages integrations, processors, and related plugin-facing runtime declarations.
+
+## Purpose
+
+The plugin layer defines what packages are allowed to declare about themselves, while core retains orchestration ownership.
+
+These contracts are responsible for:
+
+- integration registration and lifecycle hooks
+- processor registration and asset capability declaration
+- runtime capability declaration and validation input
+- shared build-plugin bridge types used by integrations and processors
+
+## Main Files
+
+- `integration-plugin.ts`: framework-semantics contract for render integrations
+- `processor.ts`: asset-transformation contract for processors
+- `runtime-capability.ts`: runtime compatibility declaration types
+- `eco-component-meta-plugin.ts`: shared metadata transform used by core loading/build paths
+
+## Ownership Rules
+
+- Integrations own rendering semantics, hydration behavior, and integration-specific HMR strategy.
+- Processors own asset semantics, cache ownership, and processor-specific watch behavior.
+- Core owns lifecycle ordering, startup orchestration, and manifest assembly.
+
+## Lifecycle Summary
+
+1. Config build validates and prepares plugin contributions.
+2. Core seals the app-owned build manifest.
+3. Runtime startup calls runtime-only setup hooks.
+4. Request-time rendering and development invalidation reuse those finalized contracts.

package/src/plugins/alias-resolver-plugin.js

@@ -1,9 +1,11 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mdx", ".css", ".scss", ".sass", ".less"];
 function findResolvablePath(candidate) {
   if (path.extname(candidate)) {
-    return existsSync(candidate) ? candidate : void 0;
+    if (existsSync(candidate)) {
+      return candidate;
+    }
   }
   for (const extension of RESOLVABLE_EXTENSIONS) {
     const fileCandidate = `${candidate}${extension}`;
@@ -19,6 +21,18 @@ function findResolvablePath(candidate) {
   }
   return void 0;
 }
+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 target = findResolvablePath(path.resolve(path.dirname(resolvedPath), match[1]));
+  return target ?? resolvedPath;
+}
 function createAliasResolverPlugin(srcDir) {
   return {
     name: "ecopages-alias-resolver",
@@ -27,7 +41,7 @@ function createAliasResolverPlugin(srcDir) {
         const candidate = path.join(srcDir, args.path.slice(2));
         const resolved = findResolvablePath(candidate);
         if (resolved) {
-          return { path: resolved };
+          return { path: resolveAliasedBarrelTarget(resolved) };
         }
         return {};
       });

package/src/plugins/eco-component-meta-plugin.d.ts

@@ -47,6 +47,8 @@ export interface EcoComponentDirPluginOptions {
  * Supported patterns:
  * - `eco.page({ ... })` - Page component declarations
  * - `eco.component({ ... })` - Reusable component declarations
+ * - `eco.html({ ... })` - HTML shell declarations
+ * - `eco.layout({ ... })` - Layout declarations
  * - `Component.config = { ... }` - Config assignment pattern
  * - `config: { ... }` - Config property in object literals
  * - `export const config = { ... }` - Exported config declarations

package/src/plugins/eco-component-meta-plugin.js

@@ -70,7 +70,7 @@ function findInjectionPoints(node, insertions, injection, isInsideEcoComponent =
     if (callee?.type === "MemberExpression" || callee?.type === "StaticMemberExpression") {
       const obj = callee.object;
       const prop = callee.property;
-      if (obj?.type === "Identifier" && obj?.name === "eco" && (prop?.name === "page" || prop?.name === "component")) {
+      if (obj?.type === "Identifier" && obj?.name === "eco" && (prop?.name === "page" || prop?.name === "component" || prop?.name === "html" || prop?.name === "layout")) {
         const args = n.arguments;
         const firstArg = args?.[0];
         if (firstArg?.type === "ObjectExpression") {

package/src/plugins/integration-plugin.d.ts

@@ -2,9 +2,11 @@ import type { EcoBuildPlugin } from '../build/build-types';
 import type { EcoPagesAppConfig, IHmrManager } from '../internal-types';
 import type { HmrStrategy } from '../hmr/hmr-strategy';
 import type { EcoComponent, EcoPagesElement } from '../public-types';
-import type { IntegrationRenderer } from '../route-renderer/integration-renderer';
-import { AssetProcessingService } from '../services/asset-processing-service/asset-processing.service';
-import type { AssetDefinition, ProcessedAsset } from '../services/asset-processing-service/assets.types';
+import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer';
+import { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service';
+import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types';
+import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
+export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
 export declare const INTEGRATION_PLUGIN_ERRORS: {
     readonly NOT_INITIALIZED_WITH_APP_CONFIG: "Plugin not initialized with app config";
     readonly NOT_INITIALIZED_WITH_ASSET_SERVICE: "Plugin not initialized with asset dependency service";
@@ -31,6 +33,11 @@ export interface IntegrationPluginConfig {
      * @default 'render'
      */
     staticBuildStep?: 'render' | 'fetch';
+    /**
+     * Declares runtime-specific requirements that must be satisfied before the
+     * app can start with this integration enabled.
+     */
+    runtimeCapability?: RuntimeCapabilityDeclaration;
 }
 /**
  * Metadata used by integration-owned boundary policy.
@@ -54,6 +61,7 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     readonly extensions: string[];
     abstract renderer: RendererClass<C>;
     readonly staticBuildStep: 'render' | 'fetch';
+    readonly runtimeCapability?: RuntimeCapabilityDeclaration;
     protected integrationDependencies: AssetDefinition[];
     protected resolvedIntegrationDependencies: ProcessedAsset[];
     protected options?: Record<string, unknown>;
@@ -80,6 +88,20 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * ```
      */
     getHmrStrategy?(): HmrStrategy | undefined;
+    /**
+     * Returns bare-specifier mappings that should be registered in the active
+     * runtime specifier registry.
+     *
+     * @remarks
+     * Override this when the integration owns browser runtime bundles that must
+     * be addressable from client-side imports through stable bare specifiers.
+     *
+     * Today these mappings are consumed by the development runtime and browser
+     * bundle aliasing path. They are intentionally generic enough to grow into a
+     * broader import-map-style facility later without moving framework-specific
+     * map contents into core.
+     */
+    getRuntimeSpecifierMap(): Record<string, string>;
     setHmrManager(hmrManager: IHmrManager): void;
     initializeAssetDefinitionService(): void;
     getResolvedIntegrationDependencies(): ProcessedAsset[];
@@ -96,7 +118,19 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * @returns `true` when the boundary should be deferred; otherwise `false`.
      */
     shouldDeferComponentBoundary(_input: ComponentBoundaryPolicyInput): boolean;
+    /**
+     * Prepares build-facing contributions before the app build manifest is sealed.
+     *
+     * @remarks
+     * Override this when an integration needs to materialize runtime/build plugin
+     * declarations ahead of runtime startup. Keep runtime-only side effects out of
+     * this hook; they belong in `setup()`.
+     */
+    prepareBuildContributions(): Promise<void>;
+    /**
+     * Performs runtime-only integration setup after config build has already
+     * sealed manifest contributions.
+     */
     setup(): Promise<void>;
     teardown(): Promise<void>;
 }
-export {};

package/src/plugins/integration-plugin.js

@@ -1,4 +1,4 @@
-import { AssetProcessingService } from "../services/asset-processing-service/asset-processing.service";
+import { AssetProcessingService } from "../services/assets/asset-processing-service/asset-processing.service";
 const INTEGRATION_PLUGIN_ERRORS = {
   NOT_INITIALIZED_WITH_APP_CONFIG: "Plugin not initialized with app config",
   NOT_INITIALIZED_WITH_ASSET_SERVICE: "Plugin not initialized with asset dependency service"
@@ -7,6 +7,7 @@ class IntegrationPlugin {
   name;
   extensions;
   staticBuildStep;
+  runtimeCapability;
   integrationDependencies;
   resolvedIntegrationDependencies = [];
   options;
@@ -21,6 +22,7 @@ class IntegrationPlugin {
     this.extensions = config.extensions;
     this.integrationDependencies = config.integrationDependencies || [];
     this.staticBuildStep = config.staticBuildStep || "render";
+    this.runtimeCapability = config.runtimeCapability;
   }
   setConfig(appConfig) {
     this.appConfig = appConfig;
@@ -29,8 +31,25 @@ class IntegrationPlugin {
   setRuntimeOrigin(runtimeOrigin) {
     this.runtimeOrigin = runtimeOrigin;
   }
+  /**
+   * Returns bare-specifier mappings that should be registered in the active
+   * runtime specifier registry.
+   *
+   * @remarks
+   * Override this when the integration owns browser runtime bundles that must
+   * be addressable from client-side imports through stable bare specifiers.
+   *
+   * Today these mappings are consumed by the development runtime and browser
+   * bundle aliasing path. They are intentionally generic enough to grow into a
+   * broader import-map-style facility later without moving framework-specific
+   * map contents into core.
+   */
+  getRuntimeSpecifierMap() {
+    return {};
+  }
   setHmrManager(hmrManager) {
     this.hmrManager = hmrManager;
+    hmrManager.registerSpecifierMap(this.getRuntimeSpecifierMap());
     const strategy = this.getHmrStrategy?.();
     if (strategy) {
       hmrManager.registerStrategy(strategy);
@@ -82,6 +101,20 @@ class IntegrationPlugin {
   shouldDeferComponentBoundary(_input) {
     return false;
   }
+  /**
+   * Prepares build-facing contributions before the app build manifest is sealed.
+   *
+   * @remarks
+   * Override this when an integration needs to materialize runtime/build plugin
+   * declarations ahead of runtime startup. Keep runtime-only side effects out of
+   * this hook; they belong in `setup()`.
+   */
+  async prepareBuildContributions() {
+  }
+  /**
+   * Performs runtime-only integration setup after config build has already
+   * sealed manifest contributions.
+   */
   async setup() {
     if (this.integrationDependencies.length === 0) return;
     if (!this.assetProcessingService) throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_ASSET_SERVICE);

package/src/plugins/processor.d.ts

@@ -1,6 +1,8 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
 import type { EcoPagesAppConfig, IClientBridge } from '../internal-types';
-import type { AssetDefinition } from '../services/asset-processing-service';
+import type { AssetDefinition } from '../services/assets/asset-processing-service';
+import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
+export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
 export declare const PROCESSOR_ERRORS: {
     readonly CACHE_DIRECTORY_NOT_SET: "Cache directory not set in context";
 };
@@ -38,6 +40,7 @@ export interface ProcessorConfig<TOptions = Record<string, unknown>> {
     options?: TOptions;
     watch?: ProcessorWatchConfig;
     capabilities?: ProcessorAssetCapability[];
+    runtimeCapability?: RuntimeCapabilityDeclaration;
 }
 export interface ProcessorContext {
     config: EcoPagesAppConfig;
@@ -59,12 +62,22 @@ export declare abstract class Processor<TOptions = Record<string, unknown>> {
     protected options?: TOptions;
     protected watchConfig?: ProcessorWatchConfig;
     protected capabilities: ProcessorAssetCapability[];
+    readonly runtimeCapability?: RuntimeCapabilityDeclaration;
     /** Plugins that are only used during the build process */
     abstract buildPlugins?: EcoBuildPlugin[];
     /** Plugins that are used during runtime for file processing */
     abstract plugins?: EcoBuildPlugin[];
     constructor(config: ProcessorConfig<TOptions>);
     setContext(appConfig: EcoPagesAppConfig): void;
+    /**
+     * Prepares build-facing processor contributions before config finalization.
+     *
+     * @remarks
+     * Override this when a processor must compute runtime/build plugins or other
+     * manifest-owned state before startup. Runtime-only work such as cache
+     * warming or watcher registration should stay in `setup()`.
+     */
+    prepareBuildContributions(): Promise<void>;
     abstract setup(): Promise<void>;
     abstract teardown(): Promise<void>;
     abstract process(input: unknown, filePath?: string): Promise<unknown>;