@ecopages/core 0.2.0-beta.38 → 0.2.0-beta.39

package/src/eco/eco.js

@@ -5,6 +5,7 @@
 import { finalizeComponentRender, getComponentRenderContext, interceptForeignChild, } from '../route-renderer/orchestration/foreign-child/component-render-context.js';
 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';
 /**
  * Creates a component factory with lazy-trigger support and foreign-child-runtime
  * interception.
@@ -20,7 +21,7 @@ import { applyPageLayoutConfig, mergeLayoutDependencies, normalizePageLayouts }
  * @returns Configured eco component.
  */
 function createComponentFactory(options) {
-    const integrationName = options.integration ?? options.__eco?.integration;
+    const integrationName = options.integration ?? options.identity?.integration;
     const comp = ((props) => {
         const componentProps = (props ?? {});
         const renderInline = (nextProps = props) => finalizeComponentRender(comp, options.render(nextProps));
@@ -48,12 +49,12 @@ function createComponentFactory(options) {
             activeRenderContext.foreignChildRuntime &&
             integrationName &&
             integrationName !== activeRenderContext.currentIntegration) {
-            throw new Error(`[ecopages] Missing foreign-child interception from ${activeRenderContext.currentIntegration} to ${integrationName} for ${options.__eco?.file ?? 'unknown component'}.`);
+            throw new Error(`[ecopages] Missing foreign-child interception from ${activeRenderContext.currentIntegration} to ${integrationName} for ${options.identity?.file ?? 'unknown component'}.`);
         }
         return renderInline();
     });
     comp.config = {
-        __eco: options.__eco,
+        identity: options.identity,
         integration: options.integration,
         dependencies: options.dependencies,
     };
@@ -78,8 +79,8 @@ function isMissingForeignChildInterceptionError(error) {
 function embed(component, props, children) {
     const activeRenderContext = getComponentRenderContext();
     const ecoComponent = component;
-    const targetIntegration = ecoComponent.config?.integration ?? ecoComponent.config?.__eco?.integration;
-    const componentFile = ecoComponent.config?.__eco?.file ?? 'unknown component';
+    const targetIntegration = ecoComponent.config?.integration ?? getComponentIdentity(ecoComponent)?.integration;
+    const componentFile = getComponentIdentity(ecoComponent)?.file ?? 'unknown component';
     const nextProps = (children === undefined ? props : { ...props, children });
     try {
         return component(nextProps);
@@ -117,7 +118,7 @@ function page(options) {
         ? mergeLayoutDependencies(undefined, layoutEntries)
         : mergeLayoutDependencies(dependenciesInput, layoutEntries);
     const componentOptions = {
-        __eco: options.__eco,
+        identity: options.identity,
         integration: options.integration,
         dependencies: staticDependencies,
         render,

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

@@ -2,8 +2,9 @@
  * Type definitions for the eco namespace API
  * @module
  */
-import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayouts, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext, PageParams, PageQuery } from '../types/public-types.js';
+import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoLayoutComponent, EcoPageLayouts, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext, PageParams, PageQuery } from '../types/public-types.js';
 import type { CacheStrategy } from '../services/cache/cache.types.js';
+import type { ComponentIdentity } from './component-identity.js';
 /**
  * Extracts the props type from one eco component.
  */
@@ -87,8 +88,8 @@ export type LazyTrigger = DependencyLazyTrigger;
  * @template E - The element/return type (defaults to EcoPagesElement for Kita, use ReactNode for React)
  */
 export interface ComponentOptions<P, E = EcoPagesElement> {
-    /** @internal Injected by eco-component-meta-plugin */
-    __eco?: EcoInjectedMeta;
+    /** @internal Bound by the component identity attribution transform. */
+    identity?: ComponentIdentity;
     integration?: string;
     dependencies?: EcoComponentDependencies;
     render: (props: P) => E | Promise<E>;
@@ -110,8 +111,8 @@ export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>
  * Base options shared by all page variants
  */
 export interface PageOptionsBase<T, E = EcoPagesElement> {
-    /** @internal Injected by eco-component-meta-plugin */
-    __eco?: EcoInjectedMeta;
+    /** @internal Bound by the component identity attribution transform. */
+    identity?: ComponentIdentity;
     integration?: string;
     /**
      * Declares browser dependencies for the page, or resolves them per render after

package/src/errors/http-error.d.ts

@@ -14,6 +14,14 @@ export declare class HttpError extends Error {
     readonly status: number;
     readonly details?: HttpErrorDetails;
     constructor(status: number, message: string, details?: HttpErrorDetails);
+    /**
+     * Detects HttpError across bundle boundaries where `instanceof` can fail.
+     *
+     * @remarks
+     * Page modules may load a different class identity than core runtime code.
+     * Prefer this over `instanceof` when catching errors from app page bundles.
+     */
+    static isHttpError(error: unknown): error is HttpError;
     /**
      * Serialize error to JSON for API responses.
      */

package/src/errors/http-error.js

@@ -11,6 +11,22 @@ export class HttpError extends Error {
         this.status = status;
         this.details = details;
     }
+    /**
+     * Detects HttpError across bundle boundaries where `instanceof` can fail.
+     *
+     * @remarks
+     * Page modules may load a different class identity than core runtime code.
+     * Prefer this over `instanceof` when catching errors from app page bundles.
+     */
+    static isHttpError(error) {
+        if (error instanceof HttpError) {
+            return true;
+        }
+        return (typeof error === 'object' &&
+            error !== null &&
+            error.name === 'HttpError' &&
+            typeof error.status === 'number');
+    }
     /**
      * Serialize error to JSON for API responses.
      */

package/src/errors/undeclared-component-dependency-error.d.ts

@@ -1,7 +1,7 @@
 export declare function getUndeclaredComponentDependencyMessage(parentComponentFile?: string): string;
 /**
  * Thrown when `dependencies.components` contains a plain function or component
- * without plugin-injected `config.__eco` metadata.
+ * without plugin-bound component identity attribution.
  */
 export declare class UndeclaredComponentDependencyError extends Error {
     name: string;

package/src/errors/undeclared-component-dependency-error.js

@@ -1,10 +1,10 @@
 export function getUndeclaredComponentDependencyMessage(parentComponentFile) {
     const parentHint = parentComponentFile ? ` (declared by ${parentComponentFile})` : '';
-    return `[ecopages] dependencies.components entries must be eco.component(), eco.layout(), or eco.html() components with __eco metadata${parentHint}. Plain functions and untyped components are not valid dependency entries.`;
+    return `[ecopages] dependencies.components entries must be eco.component(), eco.layout(), or eco.html() components with component identity${parentHint}. Plain functions and untyped components are not valid dependency entries.`;
 }
 /**
  * Thrown when `dependencies.components` contains a plain function or component
- * without plugin-injected `config.__eco` metadata.
+ * without plugin-bound component identity attribution.
  */
 export class UndeclaredComponentDependencyError extends Error {
     name = 'UndeclaredComponentDependencyError';

package/src/index.browser.d.ts

@@ -1,3 +1,4 @@
 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';

package/src/index.browser.js

@@ -1 +1,2 @@
 export { eco } from './eco/eco.browser.js';
+export { bindComponentIdentity, getComponentIdentity } from './eco/component-identity.js';

package/src/index.d.ts

@@ -4,5 +4,6 @@ export { eco } from './eco/eco.js';
 export { defineApiHandler, defineGroupHandler, defineGet, definePost, definePut, defineDelete, definePatch, defineOptions, defineHead, json, html, redirect, type GroupHandler, } from './adapters/shared/http/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';
+export { bindComponentIdentity, getComponentIdentity, type ComponentIdentity } from './eco/component-identity.js';
 export { SchemaError, validateStandardSchema } from './services/validation/validate-standard-schema.js';
 export { buildIslandHostAttributes, ECO_ISLAND_HOST_ATTRIBUTE, ECO_ISLAND_INTEGRATION_ATTRIBUTE, finalizeIslandComponentRender, isIslandHostElement, mergeIslandHostAttributes, } from './islands/island-host.js';

package/src/index.js

@@ -2,5 +2,6 @@ export { eco } from './eco/eco.js';
 export { defineApiHandler, defineGroupHandler, defineGet, definePost, definePut, defineDelete, definePatch, defineOptions, defineHead, json, html, redirect, } from './adapters/shared/http/define-api-handler.js';
 export { createEcoBuildPluginFromSourceTransform, createVitePluginsFromAppSourceTransforms, getAppSourceTransforms, createVitePluginFromSourceTransform, normalizeTransformId, } from './plugins/source-transform.js';
 export { createEcoComponentMetaTransform } from './plugins/eco-component-meta-plugin.js';
+export { bindComponentIdentity, getComponentIdentity } from './eco/component-identity.js';
 export { SchemaError, validateStandardSchema } from './services/validation/validate-standard-schema.js';
 export { buildIslandHostAttributes, ECO_ISLAND_HOST_ATTRIBUTE, ECO_ISLAND_INTEGRATION_ATTRIBUTE, finalizeIslandComponentRender, isIslandHostElement, mergeIslandHostAttributes, } from './islands/island-host.js';

package/src/plugins/README.md

@@ -19,13 +19,14 @@ These contracts are responsible for:
 - `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
+- `eco-component-meta-plugin.ts`: component-identity attribution transform that uses a lexical `eco.` gate, then an Oxc `CallExpression` rewrite
 
 ## 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.
+- The transform wraps native `eco.page()`, `eco.component()`, `eco.layout()`, and `eco.html()` factory options with `bindComponentIdentity()`. Factories retain the resulting `options.identity` on `config`, and runtime consumers read it through `getComponentIdentity()`. Browser, HMR, and server builds use the same source transform, so ownership and dependency diagnostics retain stable file attribution without a loader duplicate.
 
 ## Lifecycle Summary
 

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

@@ -1,108 +1,12 @@
-/**
- * Bun plugin that auto-injects `__eco` metadata into EcoComponent config objects.
- *
- * This plugin uses AST parsing (via oxc-parser) to reliably inject the `__eco` property
- * into EcoComponent config objects at import time. The injected metadata contains:
- * - `dir`: The directory path of the component file (used for dependency resolution)
- * - `integration`: The integration type (e.g., 'react', 'kitajs', 'ghtml', 'lit')
- *
- * The plugin intercepts file loading for all configured integration extensions and
- * transforms component configs before they are executed.
- *
- * @example
- * ```typescript
- * // Before transformation:
- * export default eco.page({
- *   render: () => '<div>Hello</div>',
- * });
- *
- * // After transformation:
- * export default eco.page({
- *   __eco: { id: "<hash>", file: "/path/to/pages/index.tsx", integration: "react" },
- *   render: () => '<div>Hello</div>',
- * });
- * ```
- *
- * @module eco-component-meta-plugin
- */
-import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
-import { type EcoSourceTransform, type EcoViteCompatiblePlugin } from './source-transform.js';
-/**
- * Options for creating the eco-component-meta-plugin.
- */
+import type { EcoSourceTransform, EcoViteCompatiblePlugin } from './source-transform.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
 export interface EcoComponentDirPluginOptions {
-    /** The EcoPages application configuration containing integration settings */
     config: EcoPagesAppConfig;
 }
-/**
- * Creates the bundler-neutral metadata transform used by Ecopages loaders and
- * Vite-compatible adapters.
- */
+/** Attributes real `eco.*()` factory calls with canonical component identity. */
+export declare function attributeComponentIdentity(contents: string, filePath: string, integration: string): string;
 export declare function createEcoComponentMetaTransform(options: EcoComponentDirPluginOptions): EcoSourceTransform;
-/**
- * Creates a build plugin that auto-injects `__eco` metadata into EcoComponent config objects.
- *
- * This plugin intercepts file loading for all integration-compatible files and:
- * 1. Strips any query string from the file path (for dev mode cache-busting)
- * 2. Reads the file contents
- * 3. Parses the AST using oxc-parser to find injection points
- * 4. Injects `__eco: { id: "...", file: "...", integration: "..." }` into config objects
- * 5. Returns the transformed content with the appropriate loader
- *
- * 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
- *
- * @param options - Plugin options containing the EcoPages config
- * @returns A build plugin instance ready for registration
- *
- * @example
- * ```typescript
- * import { createEcoComponentMetaPlugin } from '@ecopages/core';
- *
- * const plugin = createEcoComponentMetaPlugin({ config: appConfig });
- * appConfig.loaders.set(plugin.name, plugin);
- * ```
- */
-export declare function createEcoComponentMetaPlugin(options: EcoComponentDirPluginOptions): EcoBuildPlugin;
-/**
- * Creates a Vite-compatible metadata injection plugin from the shared
- * Ecopages source-transform primitive.
- */
 export declare function createEcoComponentMetaVitePlugin(options: EcoComponentDirPluginOptions): EcoViteCompatiblePlugin;
-/**
- * Injects `__eco` metadata into EcoComponent config objects in file content.
- *
- * Uses oxc-parser for robust AST-based code analysis, which handles edge cases
- * that regex-based approaches would miss (e.g., complex generics, nested objects,
- * comments, string literals containing similar patterns).
- *
- * The injection is performed by:
- * 1. Parsing the source code into an AST
- * 2. Walking the AST to find all config object patterns
- * 3. Collecting insertion points (sorted in reverse order to preserve positions)
- * 4. Inserting the `__eco` property at each point
- *
- * @param contents - The source code content to transform
- * @param filePath - Absolute path to the file (used to derive the directory)
- * @param integration - The integration identifier for this file type
- * @returns Transformed source code with `__eco` injected, or original if no patterns found
- *
- * @example
- * ```typescript
- * const result = injectEcoMeta(
- *   'export default eco.page({ render: () => "<div>Hi</div>" });',
- *   '/app/src/pages/index.tsx',
- *   'react'
- * );
- * // Result: 'export default eco.page({ __eco: { id: "<hash>", file: "/app/src/pages/index.tsx", integration: "react" }, render: () => "<div>Hi</div>" });'
- * ```
- */
-export declare function injectEcoMeta(contents: string, filePath: string, integration: string): string;
-export default createEcoComponentMetaPlugin;
+export declare function createEcoComponentMetaPlugin(options: EcoComponentDirPluginOptions): EcoBuildPlugin;
+export default createEcoComponentMetaTransform;