@ecopages/core 0.2.0-alpha.9 → 0.2.1-beta.0

package/src/errors/index.d.ts

@@ -1,2 +1,3 @@
 export { HttpError } from './http-error.js';
 export type { HttpErrorDetails, HttpErrorJson } from './http-error.js';
+export { LocalsAccessError } from './locals-access-error.js';

package/src/errors/index.js

@@ -1,4 +1,6 @@
 import { HttpError } from "./http-error.js";
+import { LocalsAccessError } from "./locals-access-error.js";
 export {
-  HttpError
+  HttpError,
+  LocalsAccessError
 };

package/src/hmr/client/hmr-runtime.js

@@ -33,7 +33,7 @@ import { getEcoNavigationRuntime } from "../../router/client/navigation-coordina
         break;
       case "layout-update": {
         await waitForNavigationToSettle(navigationRuntime);
-        if (await navigationRuntime.reloadCurrentPage({ clearCache: true })) {
+        if (await navigationRuntime.reloadCurrentPage({ clearCache: true, moduleUrl: getActiveHmrModuleUrl() })) {
         } else {
           location.reload();
         }
@@ -71,6 +71,14 @@ import { getEcoNavigationRuntime } from "../../router/client/navigation-coordina
       console.error("[ecopages] Failed to apply HMR update:", e);
     }
   }
+  function getActiveHmrModuleUrl() {
+    const pageModule = window.__ECO_PAGES__?.page?.module;
+    if (pageModule && pageModule.includes("/assets/_hmr/")) {
+      return pageModule.split("?")[0];
+    }
+    const handlerPaths = Object.keys(window.__ECO_PAGES__?.hmrHandlers ?? {});
+    return handlerPaths[handlerPaths.length - 1];
+  }
   async function waitForNavigationToSettle(navigationRuntime) {
     if (!navigationRuntime.hasPendingNavigationTransaction()) {
       return;

package/src/hmr/hmr-strategy.d.ts

@@ -1,4 +1,4 @@
-import type { ClientBridgeEvent } from '../public-types';
+import type { ClientBridgeEvent } from '../types/public-types.js';
 /**
  * HMR Strategy Pattern
  *
@@ -18,11 +18,13 @@ import type { ClientBridgeEvent } from '../public-types';
  *   async process(filePath: string): Promise<HmrAction> {
  *     return {
  *       type: 'broadcast',
- *       events: [{ type: 'update', path: filePath, timestamp: Date.now() }]
+ *       events: [{ type: 'update', path: filePath, timestamp: Date.now() }],
  *     };
  *   }
  * }
-
+ * ```
+ */
+/**
  * Defines the category of an HMR strategy, which determines its execution priority.
  * Strategies are evaluated in descending order: INTEGRATION → ASSET → SCRIPT → FALLBACK.
  *
@@ -30,28 +32,29 @@ import type { ClientBridgeEvent } from '../public-types';
  * The numeric values represent base priorities. Strategies can fine-tune their priority
  * using the `priorityOffset` property.
  */
-export declare enum HmrStrategyType {
+export declare const HmrStrategyType: {
     /**
      * Integration-specific strategies (React, Lit, etc.)
      * Highest priority to allow framework-specific HMR handling.
      */
-    INTEGRATION = 100,
+    readonly INTEGRATION: 100;
     /**
      * Asset processing strategies (CSS, images, etc.)
      * High priority for specialized asset handling.
      */
-    ASSET = 50,
+    readonly ASSET: 50;
     /**
      * Generic script bundling strategies (JS/TS)
      * Medium priority for standard script processing.
      */
-    SCRIPT = 25,
+    readonly SCRIPT: 25;
     /**
      * Fallback strategy for unhandled file types.
      * Lowest priority, triggers full page reload.
      */
-    FALLBACK = 0
-}
+    readonly FALLBACK: 0;
+};
+export type HmrStrategyType = (typeof HmrStrategyType)[keyof typeof HmrStrategyType];
 /**
  * Represents an action to be taken after processing a file change.
  */
@@ -62,7 +65,7 @@ export interface HmrAction {
     type: 'broadcast' | 'none';
     /**
      * The HMR events to broadcast, if type is 'broadcast'.
-     * capable of broadcasting multiple events at once.
+     * Multiple events may be broadcast in one action.
      */
     events?: ClientBridgeEvent[];
 }
@@ -74,8 +77,8 @@ export interface HmrAction {
  * whether they match the changed file path.
  *
  * @remarks
- * Strategies should be stateless and idempotent. The same file change should always
- * produce the same result when processed by the same strategy.
+ * Strategies are expected to be stateless and idempotent. The same file change
+ * should produce the same result when processed by the same strategy.
  *
  * @example
  * ```typescript
@@ -120,7 +123,7 @@ export declare abstract class HmrStrategy {
      * Determines if this strategy can handle the given file path.
      *
      * @param filePath - Absolute path to the changed file
-     * @returns True if this strategy should process the file
+     * @returns `true` when this strategy should process the file
      *
      * @example
      * ```typescript

package/src/hmr/hmr-strategy.js

@@ -1,10 +1,25 @@
-var HmrStrategyType = /* @__PURE__ */ ((HmrStrategyType2) => {
-  HmrStrategyType2[HmrStrategyType2["INTEGRATION"] = 100] = "INTEGRATION";
-  HmrStrategyType2[HmrStrategyType2["ASSET"] = 50] = "ASSET";
-  HmrStrategyType2[HmrStrategyType2["SCRIPT"] = 25] = "SCRIPT";
-  HmrStrategyType2[HmrStrategyType2["FALLBACK"] = 0] = "FALLBACK";
-  return HmrStrategyType2;
-})(HmrStrategyType || {});
+const HmrStrategyType = {
+  /**
+   * Integration-specific strategies (React, Lit, etc.)
+   * Highest priority to allow framework-specific HMR handling.
+   */
+  INTEGRATION: 100,
+  /**
+   * Asset processing strategies (CSS, images, etc.)
+   * High priority for specialized asset handling.
+   */
+  ASSET: 50,
+  /**
+   * Generic script bundling strategies (JS/TS)
+   * Medium priority for standard script processing.
+   */
+  SCRIPT: 25,
+  /**
+   * Fallback strategy for unhandled file types.
+   * Lowest priority, triggers full page reload.
+   */
+  FALLBACK: 0
+};
 class HmrStrategy {
   /**
    * Optional offset to fine-tune priority within the same category.

package/src/hmr/strategies/default-hmr-strategy.d.ts

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import { HmrStrategy, HmrStrategyType, type HmrAction } from '../hmr-strategy';
+import { HmrStrategy, type HmrAction } from '../hmr-strategy.js';
 /**
  * Default fallback strategy for unhandled file types.
  *
@@ -25,7 +25,7 @@ import { HmrStrategy, HmrStrategyType, type HmrAction } from '../hmr-strategy';
  * ```
  */
 export declare class DefaultHmrStrategy extends HmrStrategy {
-    readonly type = HmrStrategyType.FALLBACK;
+    readonly type: 0;
     /**
      * Matches all file paths.
      *

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

@@ -1,4 +1,4 @@
-import { HmrStrategy, HmrStrategyType } from "../hmr-strategy";
+import { HmrStrategy, HmrStrategyType } from "../hmr-strategy.js";
 class DefaultHmrStrategy extends HmrStrategy {
   type = HmrStrategyType.FALLBACK;
   /**

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

@@ -7,7 +7,7 @@
  *
  * @module
  */
-import { HmrStrategy, HmrStrategyType, type HmrAction } from '../hmr-strategy';
+import { HmrStrategy, type HmrAction } from '../hmr-strategy.js';
 import type { EcoBuildPlugin } from '../../build/build-types.js';
 import type { BrowserBundleExecutor } from '../../services/assets/browser-bundle.service.js';
 import type { EntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.js';
@@ -20,10 +20,6 @@ export interface JsHmrContext {
      * Map of registered entrypoints to their output URLs.
      */
     getWatchedFiles(): Map<string, string>;
-    /**
-     * Map of bare specifiers to vendor URLs for import resolution.
-     */
-    getSpecifierMap(): Map<string, string>;
     getEntrypointDependencyGraph(): EntrypointDependencyGraph;
     /**
      * Directory where HMR bundles are written.
@@ -85,7 +81,6 @@ export interface JsHmrContext {
  * ```typescript
  * const context = {
  *   getWatchedFiles: () => watchedFilesMap,
- *   getSpecifierMap: () => specifierMap,
  *   getDistDir: () => '/path/to/dist/_hmr',
  *   getPlugins: () => [],
  *   getSrcDir: () => '/path/to/src'
@@ -94,7 +89,7 @@ export interface JsHmrContext {
  * ```
  */
 export declare class JsHmrStrategy extends HmrStrategy {
-    readonly type = HmrStrategyType.SCRIPT;
+    readonly type: 25;
     private context;
     constructor(context: JsHmrContext);
     /**
@@ -116,13 +111,13 @@ export declare 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
+     * When multiple entrypoints are impacted they are bundled in a single
      * invocation to share AST parsing and chunk deduplication.
      * @returns Action to broadcast update events
      */
     process(filePath: string): Promise<HmrAction>;
     /**
-     * Bundles one or more entrypoints in a single esbuild invocation.
+     * Bundles one or more entrypoints in a single build invocation.
      * Uses the source directory as the output base so that the directory structure
      * is preserved under the HMR dist folder.
      */

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

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
-import { HmrStrategy, HmrStrategyType } from "../hmr-strategy";
-import { appLogger } from "../../global/app-logger";
+import { HmrStrategy, HmrStrategyType } from "../hmr-strategy.js";
+import { appLogger } from "../../global/app-logger.js";
 class JsHmrStrategy extends HmrStrategy {
   type = HmrStrategyType.SCRIPT;
   context;
@@ -23,8 +23,7 @@ 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));
+    const isIntegrationTemplate = this.context.getTemplateExtensions().some((extension) => filePath.endsWith(extension));
     if (watchedFiles.size === 0) {
       return false;
     }
@@ -37,10 +36,6 @@ class JsHmrStrategy extends HmrStrategy {
     if (watchedFiles.has(filePath)) {
       return true;
     }
-    const entrypointDependencyGraph = this.context.getEntrypointDependencyGraph();
-    if (entrypointDependencyGraph.supportsSelectiveInvalidation()) {
-      return entrypointDependencyGraph.getDependencyEntrypoints(filePath).size > 0;
-    }
     return true;
   }
   /**
@@ -51,7 +46,7 @@ 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
+   * When multiple entrypoints are impacted they are bundled in a single
    * invocation to share AST parsing and chunk deduplication.
    * @returns Action to broadcast update events
    */
@@ -119,7 +114,7 @@ class JsHmrStrategy extends HmrStrategy {
     return { type: "none" };
   }
   /**
-   * Bundles one or more entrypoints in a single esbuild invocation.
+   * Bundles one or more entrypoints in a single build invocation.
    * Uses the source directory as the output base so that the directory structure
    * is preserved under the HMR dist folder.
    */

package/src/index.browser.d.ts

@@ -1,3 +1,3 @@
-export type * from './public-types.js';
+export type * from './types/public-types.js';
 export type * from './eco/eco.types.js';
-export { eco } from './eco/eco.js';
+export { eco } from './eco/eco.browser.js';

package/src/index.browser.js

@@ -1,4 +1,4 @@
-import { eco } from "./eco/eco.js";
+import { eco } from "./eco/eco.browser.js";
 export {
   eco
 };

package/src/index.d.ts

@@ -1,5 +1,6 @@
-export type * from './public-types.js';
+export type * from './types/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 './adapters/shared/define-api-handler.js';
+export { createEcoBuildPluginFromSourceTransform, createVitePluginsFromAppSourceTransforms, getAppSourceTransforms, createVitePluginFromSourceTransform, normalizeTransformId, type EcoSourceTransform, type EcoSourceTransformResult, type EcoViteCompatiblePlugin, } from './plugins/source-transform.js';
+export { createEcoComponentMetaTransform } from './plugins/eco-component-meta-plugin.js';

package/src/index.js

@@ -1,10 +1,21 @@
 import { eco } from "./eco/eco.js";
-import { EcopagesApp, createApp } from "./create-app.js";
 import { defineApiHandler, defineGroupHandler } from "./adapters/shared/define-api-handler.js";
+import {
+  createEcoBuildPluginFromSourceTransform,
+  createVitePluginsFromAppSourceTransforms,
+  getAppSourceTransforms,
+  createVitePluginFromSourceTransform,
+  normalizeTransformId
+} from "./plugins/source-transform.js";
+import { createEcoComponentMetaTransform } from "./plugins/eco-component-meta-plugin.js";
 export {
-  EcopagesApp,
-  createApp,
+  createEcoBuildPluginFromSourceTransform,
+  createEcoComponentMetaTransform,
+  createVitePluginFromSourceTransform,
+  createVitePluginsFromAppSourceTransforms,
   defineApiHandler,
   defineGroupHandler,
-  eco
+  eco,
+  getAppSourceTransforms,
+  normalizeTransformId
 };

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

@@ -2,7 +2,7 @@
  * This module contains the ghtml renderer
  * @module
  */
-import type { EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../public-types.js';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../types/public-types.js';
 import { IntegrationRenderer, type RenderToResponseContext } from '../../route-renderer/orchestration/integration-renderer.js';
 /**
  * A renderer for the ghtml integration.
@@ -10,6 +10,7 @@ import { IntegrationRenderer, type RenderToResponseContext } from '../../route-r
  */
 export declare class GhtmlRenderer extends IntegrationRenderer<EcoPagesElement> {
     name: string;
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
     render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, }: IntegrationRendererRenderOptions): Promise<RouteRendererBody>;
     renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
 }

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

@@ -1,9 +1,15 @@
 import {
   IntegrationRenderer
 } from "../../route-renderer/orchestration/integration-renderer.js";
-import { GHTML_PLUGIN_NAME } from "./ghtml.plugin.js";
+import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
 class GhtmlRenderer extends IntegrationRenderer {
   name = GHTML_PLUGIN_NAME;
+  async renderComponent(input) {
+    return this.renderStringComponentWithQueuedForeignSubtrees(
+      input,
+      input.component
+    );
+  }
   async render({
     params,
     query,
@@ -16,42 +22,31 @@ class GhtmlRenderer extends IntegrationRenderer {
     HtmlTemplate
   }) {
     try {
-      const pageContent = await Page({ params, query, ...props, locals: pageLocals });
-      const children = Layout && typeof Layout === "function" ? await Layout({ children: pageContent, locals }) : pageContent;
-      const body = await HtmlTemplate({
+      return await this.renderPageWithDocumentShell({
+        page: {
+          component: Page,
+          props: { params, query, ...props, locals: pageLocals }
+        },
+        layout: Layout ? {
+          component: Layout,
+          props: locals ? { locals } : {}
+        } : void 0,
+        htmlTemplate: HtmlTemplate,
         metadata,
-        children,
-        pageProps: props || {}
+        pageProps: props ?? {}
       });
-      return this.DOC_TYPE + body;
     } catch (error) {
       throw this.createRenderError("Error rendering page", error);
     }
   }
   async renderToResponse(view, props, ctx) {
     try {
-      const Layout = view.config?.layout;
-      const viewFn = view;
-      const pageContent = await viewFn(props);
-      let body;
-      if (ctx.partial) {
-        body = pageContent;
-      } else {
-        const children = Layout ? await Layout({ children: pageContent }) : pageContent;
-        const HtmlTemplate = await this.getHtmlTemplate();
-        const metadata = view.metadata ? await view.metadata({
-          params: {},
-          query: {},
-          props,
-          appConfig: this.appConfig
-        }) : this.appConfig.defaultMetadata;
-        body = this.DOC_TYPE + await HtmlTemplate({
-          metadata,
-          children,
-          pageProps: props
-        });
-      }
-      return this.createHtmlResponse(body, ctx);
+      return await this.renderViewWithDocumentShell({
+        view,
+        props,
+        ctx,
+        layout: view.config?.layout
+      });
     } catch (error) {
       throw this.createRenderError("Error rendering view", error);
     }

package/src/integrations/ghtml/ghtml.constants.d.ts

@@ -0,0 +1 @@
+export declare const GHTML_PLUGIN_NAME = "ghtml";

package/src/integrations/ghtml/ghtml.constants.js

@@ -0,0 +1,4 @@
+const GHTML_PLUGIN_NAME = "ghtml";
+export {
+  GHTML_PLUGIN_NAME
+};

package/src/integrations/ghtml/ghtml.plugin.d.ts

@@ -1,9 +1,5 @@
-import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin';
-import { GhtmlRenderer } from './ghtml-renderer';
-/**
- * The name of the ghtml plugin
- */
-export declare const GHTML_PLUGIN_NAME = "ghtml";
+import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin.js';
+import { GhtmlRenderer } from './ghtml-renderer.js';
 /**
  * The Ghtml plugin class
  * This plugin provides support for ghtml components in Ecopages

package/src/integrations/ghtml/ghtml.plugin.js

@@ -1,6 +1,6 @@
-import { IntegrationPlugin } from "../../plugins/integration-plugin";
-import { GhtmlRenderer } from "./ghtml-renderer";
-const GHTML_PLUGIN_NAME = "ghtml";
+import { IntegrationPlugin } from "../../plugins/integration-plugin.js";
+import { GhtmlRenderer } from "./ghtml-renderer.js";
+import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
 class GhtmlPlugin extends IntegrationPlugin {
   renderer = GhtmlRenderer;
   constructor(options) {
@@ -15,7 +15,6 @@ function ghtmlPlugin(options) {
   return new GhtmlPlugin(options);
 }
 export {
-  GHTML_PLUGIN_NAME,
   GhtmlPlugin,
   ghtmlPlugin
 };

package/src/plugins/README.md

@@ -18,6 +18,7 @@ These contracts are responsible for:
 - `integration-plugin.ts`: framework-semantics contract for render integrations
 - `processor.ts`: asset-transformation contract for processors
 - `runtime-capability.ts`: runtime compatibility declaration types
+- `source-transform.ts`: bundler-neutral source-transform primitive with Ecopages adapters plus app-level Vite plugin composition helpers
 - `eco-component-meta-plugin.ts`: shared metadata transform used by core loading/build paths
 
 ## Ownership Rules

package/src/plugins/alias-resolver-cache.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Per-plugin cache for `@/...` alias resolution.
+ *
+ * @remarks
+ * The `ecopages-alias-resolver` plugin resolves project aliases like
+ * `@/components/Button` to concrete file paths under the app's `srcDir`.
+ * Each resolution can trigger up to 22 `existsSync` calls and (when
+ * the resolved path is a barrel) a `readFileSync` to detect
+ * `export * from './...'` forwarding.
+ *
+ * This cache memoizes the result keyed by `(srcDir, specifier)`. It is
+ * process-local and not currently invalidated by the file watcher —
+ * `srcDir` contents are assumed to be stable for the lifetime of the
+ * process.
+ */
+export declare class AliasResolverCache {
+    private readonly entries;
+    private readonly maxEntries;
+    private hits;
+    private misses;
+    constructor(maxEntries?: number);
+    /**
+     * Look up a previously-computed resolution for `(srcDir, specifier)`.
+     *
+     * Returns `{ hit: true, resolved }` on cache hit (resolved may be
+     * `undefined` for an unresolvable specifier), or `{ hit: false }` on
+     * miss. The caller is responsible for re-running the resolver and
+     * calling `set` to store the new entry.
+     */
+    get(srcDir: string, specifier: string): {
+        hit: true;
+        resolved: string | undefined;
+    } | {
+        hit: false;
+    };
+    /**
+     * Store a resolution result.
+     *
+     * Pass `undefined` for `resolved` to memoize the negative case
+     * (specifier did not resolve) and avoid repeating the FS walk on
+     * every `@/...` import.
+     */
+    set(srcDir: string, specifier: string, resolved: string | undefined): void;
+    /**
+     * Drop all entries whose `srcDir` is under `rootDir`. Use this from
+     * the file watcher when files are added or removed under the app's
+     * source tree.
+     *
+     * Path comparison is path-aware (handles both POSIX `/` and
+     * Windows `\` separators) via `path.relative` so cached entries
+     * normalized on one platform still match the watcher's `rootDir`
+     * on another. Without this, a Windows build that sees
+     * `entry.srcDir === 'C:\app\src'` would miss
+     * `entry.srcDir.startsWith('C:/app/src/')` and leave stale entries.
+     */
+    invalidateUnder(rootDir: string): number;
+    /** Clear all entries. */
+    clear(): void;
+    /** Current cache size. */
+    get size(): number;
+    /** Hit/miss counters for observability. */
+    stats(): {
+        hits: number;
+        misses: number;
+        size: number;
+        hitRate: number;
+    };
+}

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

@@ -0,0 +1,106 @@
+import path from "node:path";
+const DEFAULT_MAX_ENTRIES = 2e3;
+class AliasResolverCache {
+  entries = /* @__PURE__ */ new Map();
+  maxEntries;
+  hits = 0;
+  misses = 0;
+  constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
+    if (maxEntries <= 0) {
+      throw new Error(`AliasResolverCache: maxEntries must be > 0, got ${maxEntries}`);
+    }
+    this.maxEntries = maxEntries;
+  }
+  /**
+   * Look up a previously-computed resolution for `(srcDir, specifier)`.
+   *
+   * Returns `{ hit: true, resolved }` on cache hit (resolved may be
+   * `undefined` for an unresolvable specifier), or `{ hit: false }` on
+   * miss. The caller is responsible for re-running the resolver and
+   * calling `set` to store the new entry.
+   */
+  get(srcDir, specifier) {
+    const key = makeKey(srcDir, specifier);
+    const existing = this.entries.get(key);
+    if (existing) {
+      this.hits += 1;
+      this.entries.delete(key);
+      this.entries.set(key, existing);
+      return { hit: true, resolved: existing.resolved };
+    }
+    this.misses += 1;
+    return { hit: false };
+  }
+  /**
+   * Store a resolution result.
+   *
+   * Pass `undefined` for `resolved` to memoize the negative case
+   * (specifier did not resolve) and avoid repeating the FS walk on
+   * every `@/...` import.
+   */
+  set(srcDir, specifier, resolved) {
+    const key = makeKey(srcDir, specifier);
+    this.entries.set(key, { srcDir, resolved });
+    if (this.entries.size > this.maxEntries) {
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey !== void 0) {
+        this.entries.delete(oldestKey);
+      }
+    }
+  }
+  /**
+   * Drop all entries whose `srcDir` is under `rootDir`. Use this from
+   * the file watcher when files are added or removed under the app's
+   * source tree.
+   *
+   * Path comparison is path-aware (handles both POSIX `/` and
+   * Windows `\` separators) via `path.relative` so cached entries
+   * normalized on one platform still match the watcher's `rootDir`
+   * on another. Without this, a Windows build that sees
+   * `entry.srcDir === 'C:\app\src'` would miss
+   * `entry.srcDir.startsWith('C:/app/src/')` and leave stale entries.
+   */
+  invalidateUnder(rootDir) {
+    const normalizedRoot = path.resolve(rootDir);
+    let removed = 0;
+    for (const [key, entry] of this.entries) {
+      if (isUnderDirectory(path.resolve(entry.srcDir), normalizedRoot)) {
+        this.entries.delete(key);
+        removed += 1;
+      }
+    }
+    return removed;
+  }
+  /** Clear all entries. */
+  clear() {
+    this.entries.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+  /** Current cache size. */
+  get size() {
+    return this.entries.size;
+  }
+  /** Hit/miss counters for observability. */
+  stats() {
+    const total = this.hits + this.misses;
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      size: this.entries.size,
+      hitRate: total === 0 ? 0 : this.hits / total
+    };
+  }
+}
+function makeKey(srcDir, specifier) {
+  return `${srcDir} ${specifier}`;
+}
+function isUnderDirectory(candidate, parent) {
+  if (candidate === parent) return true;
+  const rel = path.relative(parent, candidate);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return false;
+  return true;
+}
+export {
+  AliasResolverCache
+};

package/src/plugins/alias-resolver-plugin.d.ts

@@ -1,2 +1,6 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
-export declare function createAliasResolverPlugin(srcDir: string): EcoBuildPlugin;
+import { AliasResolverCache } from './alias-resolver-cache.js';
+export declare function resolveAppSourceAliasPath(srcDir: string, specifier: string): string | undefined;
+export declare function createAliasResolverPlugin(srcDir: string, options?: {
+    cache?: AliasResolverCache;
+}): EcoBuildPlugin;