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

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

@@ -1,414 +1,133 @@
-/**
- * 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 { cachedParseSync } from '../cache/module-parse-cache.js';
 import { prependJsxImportSourceIfMissing } from './jsx-import-source.utils.js';
+import { createEcoBuildPluginFromSourceTransform, createVitePluginFromSourceTransform } from './source-transform.js';
+import { cachedParseSync } from '../cache/module-parse-cache.js';
 import { rapidhash } from '../utils/hash.js';
-import { createEcoBuildPluginFromSourceTransform, createVitePluginFromSourceTransform, } from './source-transform.js';
-/**
- * Pattern to match regex special characters that need escaping.
- * Used when building the file extension filter pattern.
- */
-const REGEX_SPECIAL_CHARS = /[.*+?^${}()|[\]\\]/g;
-/**
- * Set of valid Bun loader extensions.
- * Only files with these base extensions can be processed by Bun's loader system.
- */
-const VALID_LOADER_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx']);
-/**
- * Checks if an extension can be handled by a valid Bun loader.
- *
- * Compound extensions like `.kita.tsx` are valid because the final
- * extension is `.tsx`, which Bun can process.
- *
- * @param ext - The file extension to check (e.g., '.tsx', '.kita.tsx')
- * @returns `true` if the extension ends with a valid loader extension
- */
-function hasValidLoaderExtension(ext) {
-    for (const validExt of VALID_LOADER_EXTENSIONS) {
-        if (ext.endsWith(validExt)) {
-            return true;
-        }
-    }
-    return false;
+function integrationForFile(filePath, config) {
+    const candidates = config.integrations
+        .flatMap((integration) => integration.extensions.map((extension) => [extension, integration]))
+        .sort(([left], [right]) => right.length - left.length);
+    const match = candidates.find(([extension]) => filePath.endsWith(extension));
+    return match ? { name: match[1].name, jsxImportSource: match[1].jsxImportSource } : { name: 'ghtml' };
+}
+function isAstNode(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isEcoFactoryCall(node) {
+    if (node.type !== 'CallExpression' || !isAstNode(node.callee))
+        return false;
+    const callee = node.callee;
+    if (callee.type !== 'MemberExpression' && callee.type !== 'StaticMemberExpression')
+        return false;
+    if (!isAstNode(callee.object) || callee.object.type !== 'Identifier' || callee.object.name !== 'eco')
+        return false;
+    if (!isAstNode(callee.property) || callee.property.type !== 'Identifier')
+        return false;
+    return ['page', 'component', 'layout', 'html'].includes(String(callee.property.name));
 }
-function buildExtensionToIntegrationMap(integrations) {
-    const mapping = [];
-    for (const integration of integrations) {
-        for (const ext of integration.extensions) {
-            mapping.push([
-                ext,
-                {
-                    name: integration.name,
-                    jsxImportSource: integration.jsxImportSource,
-                },
-            ]);
-        }
+function isIdentityBinding(node) {
+    if (!isAstNode(node) || node.type !== 'CallExpression' || !isAstNode(node.callee))
+        return false;
+    return node.callee.type === 'Identifier' && node.callee.name === 'bindComponentIdentity';
+}
+function walkAst(node, visit) {
+    if (Array.isArray(node)) {
+        for (const child of node)
+            walkAst(child, visit);
+        return;
     }
-    mapping.sort((a, b) => b[0].length - a[0].length);
-    return mapping;
+    if (!isAstNode(node))
+        return;
+    visit(node);
+    for (const value of Object.values(node))
+        walkAst(value, visit);
 }
-/**
- * Detects the integration type for a file based on its extension.
- *
- * Uses the pre-sorted extension-to-integration map to find the most
- * specific matching extension.
- *
- * @param filePath - Absolute path to the file
- * @param extensionToIntegration - Pre-built extension mapping from buildExtensionToIntegrationMap
- * @returns The integration identifier (e.g., 'react', 'kitajs', 'lit', 'ghtml')
- */
-function detectIntegration(filePath, extensionToIntegration) {
-    for (const [ext, integration] of extensionToIntegration) {
-        if (filePath.endsWith(ext)) {
-            return integration;
-        }
+function addIdentityBindingImport(contents, program) {
+    const imports = program.body.filter((node) => isAstNode(node) &&
+        node.type === 'ImportDeclaration' &&
+        isAstNode(node.source) &&
+        node.source.value === '@ecopages/core');
+    const valueImport = imports.find((node) => node.importKind !== 'type');
+    if (!valueImport)
+        return `import { bindComponentIdentity } from '@ecopages/core';\n${contents}`;
+    const specifiers = Array.isArray(valueImport.specifiers) ? valueImport.specifiers.filter(isAstNode) : [];
+    if (specifiers.some((specifier) => specifier.type === 'ImportSpecifier' &&
+        isAstNode(specifier.imported) &&
+        specifier.imported.name === 'bindComponentIdentity')) {
+        return contents;
+    }
+    const namedSpecifiers = specifiers.filter((specifier) => specifier.type === 'ImportSpecifier');
+    if (namedSpecifiers.length > 0) {
+        const lastSpecifier = namedSpecifiers[namedSpecifiers.length - 1];
+        return `${contents.slice(0, lastSpecifier.end)}, bindComponentIdentity${contents.slice(lastSpecifier.end)}`;
     }
-    return { name: 'ghtml' };
+    if (specifiers.some((specifier) => specifier.type === 'ImportNamespaceSpecifier')) {
+        return `import { bindComponentIdentity } from '@ecopages/core';\n${contents}`;
+    }
+    const defaultSpecifier = specifiers.find((specifier) => specifier.type === 'ImportDefaultSpecifier');
+    if (defaultSpecifier) {
+        return `${contents.slice(0, defaultSpecifier.end)}, { bindComponentIdentity }${contents.slice(defaultSpecifier.end)}`;
+    }
+    return `import { bindComponentIdentity } from '@ecopages/core';\n${contents}`;
 }
-/**
- * Creates a RegExp pattern that matches files with any of the configured extensions.
- *
- * The pattern also matches optional query strings (e.g., `file.tsx?update=123`)
- * which are used for cache-busting in development mode.
- *
- * @param extensions - Array of file extensions to match
- * @returns RegExp pattern for use with Bun's onLoad filter
- * @throws Error if no extensions are provided
- *
- * @example
- * ```typescript
- * const pattern = createExtensionPattern(['.tsx', '.kita.tsx']);
- * pattern.test('component.tsx');           // true
- * pattern.test('component.tsx?v=123');     // true
- * pattern.test('component.ts');            // false
- * ```
- */
-function createExtensionPattern(extensions) {
-    if (extensions.length === 0) {
-        throw new Error('[eco-component-meta-plugin] No extensions configured. At least one integration is required.');
+/** Attributes real `eco.*()` factory calls with canonical component identity. */
+export function attributeComponentIdentity(contents, filePath, integration) {
+    if (!contents.includes('eco.'))
+        return contents;
+    let program;
+    try {
+        program = cachedParseSync(filePath, contents, { sourceType: 'module' }).program;
+    }
+    catch {
+        return contents;
     }
-    const uniqueExtensions = [...new Set(extensions)];
-    const escaped = uniqueExtensions.map((ext) => ext.replace(REGEX_SPECIAL_CHARS, '\\$&'));
-    return new RegExp(`(${escaped.join('|')})(\\?.*)?$`);
+    const identityLiteral = `{ id: ${JSON.stringify(rapidhash(filePath).toString(36))}, file: ${JSON.stringify(filePath)}, integration: ${JSON.stringify(integration)} }`;
+    const edits = [];
+    walkAst(program, (node) => {
+        if (!isEcoFactoryCall(node) || !Array.isArray(node.arguments))
+            return;
+        const firstArgument = node.arguments[0];
+        if (!isAstNode(firstArgument) || isIdentityBinding(firstArgument))
+            return;
+        if (typeof firstArgument.start !== 'number' || typeof firstArgument.end !== 'number')
+            return;
+        edits.push({
+            start: firstArgument.start,
+            end: firstArgument.end,
+            replacement: `bindComponentIdentity(${identityLiteral}, ${contents.slice(firstArgument.start, firstArgument.end)})`,
+        });
+    });
+    if (edits.length === 0)
+        return contents;
+    let transformed = contents;
+    for (const edit of edits.sort((left, right) => right.start - left.start)) {
+        transformed = `${transformed.slice(0, edit.start)}${edit.replacement}${transformed.slice(edit.end)}`;
+    }
+    return addIdentityBindingImport(transformed, program);
 }
-/**
- * Creates the bundler-neutral metadata transform used by Ecopages loaders and
- * Vite-compatible adapters.
- */
 export function createEcoComponentMetaTransform(options) {
-    const allExtensions = options.config.integrations
+    const extensions = options.config.integrations
         .flatMap((integration) => integration.extensions)
-        .filter(hasValidLoaderExtension);
-    if (allExtensions.length === 0) {
-        throw new Error('[eco-component-meta-plugin] No extensions configured. At least one integration is required.');
-    }
-    const extensionPattern = createExtensionPattern(allExtensions);
-    const extensionToIntegration = buildExtensionToIntegrationMap(options.config.integrations);
+        .filter((extension) => ['.ts', '.tsx', '.js', '.jsx'].some((suffix) => extension.endsWith(suffix)))
+        .map((extension) => extension.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    const filter = new RegExp(`(${extensions.join('|')})(\\?.*)?$`);
     return {
-        name: 'eco-component-meta-plugin',
+        name: 'eco-component-identity-attribution',
         enforce: 'pre',
-        filter: extensionPattern,
+        filter,
         transform(code, id) {
-            const integration = detectIntegration(id, extensionToIntegration);
+            if (id.endsWith('.mdx'))
+                return { code };
+            const integration = integrationForFile(id, options.config);
             return {
-                code: prependJsxImportSourceIfMissing(injectEcoMeta(code, id, integration.name), integration.jsxImportSource),
+                code: prependJsxImportSourceIfMissing(attributeComponentIdentity(code, id, integration.name), integration.jsxImportSource),
             };
         },
     };
 }
-/**
- * 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 function createEcoComponentMetaPlugin(options) {
-    return createEcoBuildPluginFromSourceTransform(createEcoComponentMetaTransform(options));
-}
-/**
- * Creates a Vite-compatible metadata injection plugin from the shared
- * Ecopages source-transform primitive.
- */
 export function createEcoComponentMetaVitePlugin(options) {
     return createVitePluginFromSourceTransform(createEcoComponentMetaTransform(options));
 }
-/**
- * Recursively walks the AST (Abstract Syntax Tree) to find all injection points for `__eco` metadata.
- *
- * ## What is an AST?
- *
- * An AST is a tree representation of source code. Instead of treating code as text,
- * a parser breaks it down into a structured tree where each node represents a
- * syntactic construct (variable, function call, object, etc.).
- *
- * For example, this code:
- * ```typescript
- * eco.page({ render: () => 'hi' })
- * ```
- *
- * Becomes an AST like:
- * ```
- * CallExpression
- * ├── callee: MemberExpression
- * │   ├── object: Identifier (name: "eco")
- * │   └── property: Identifier (name: "page")
- * └── arguments: [
- *     └── ObjectExpression (start: 9)  <-- We inject here at position 10 (after "{")
- *         └── properties: [...]
- * ]
- * ```
- *
- * ## How this function works
- *
- * 1. **Recursive traversal**: Visits every node in the tree, checking each one
- * 2. **Pattern matching**: Checks if the current node matches one of our target patterns
- * 3. **Position tracking**: When a match is found, records the `start` position of the
- *    config object (the character index in the original source where `{` appears)
- * 4. **Insertion offset**: Adds +1 to insert right after the opening `{`
- *
- * ## Supported patterns
- *
- * | Pattern | AST Node Type | Example | File Types |
- * |---------|---------------|---------|------------|
- * | `eco.page({...})` | CallExpression | `export default eco.page({ render: () => 'hi' })` | All |
- * | `eco.component({...})` | CallExpression | `export const Btn = eco.component({ render: () => '<button/>' })` | All |
- * | `eco.html({...})` | CallExpression | `export default eco.html({ render: () => '<html />' })` | All |
- * | `eco.layout({...})` | CallExpression | `export const MainLayout = eco.layout({ render: () => '<main />' })` | All |
- * | `X.config = {...}` | AssignmentExpression | `MyComponent.config = { dependencies: [] }` | All |
- * | `config: {...}` | ObjectProperty | `const X: EcoComponent = { config: {...} }` | EcoComponent-typed only |
- *
- * ## Why AST over regex?
- *
- * Regex would fail on edge cases like:
- * - `eco.page<ComplexType<(arg: string) => void>>({...})` - generics with arrows
- * - `// eco.page({ commented out })` - comments
- * - `const str = "eco.page({ in a string })"` - string literals
- * - Nested objects that look like config patterns
- *
- * AST parsing understands the actual code structure, not just text patterns.
- *
- * @param node - Current AST node being visited (starts with the root Program node)
- * @param insertions - Array to collect insertion points (mutated by this function)
- * @param injection - The injection text to insert at each point (e.g., ` __eco: {...},`)
- * @param isInsideEcoComponent - Whether we're inside an EcoComponent-typed declaration
- */
-function findInjectionPoints(node, insertions, injection, isInsideEcoComponent = false) {
-    if (!node || typeof node !== 'object')
-        return;
-    const n = node;
-    /**
-     * Pattern 1: eco.page({...}), eco.component({...}), eco.html({...}), or eco.layout({...})
-     * AST structure: CallExpression with MemberExpression callee where object is "eco"
-     */
-    if (n.type === 'CallExpression') {
-        const callee = n.callee;
-        /**
-         * MemberExpression represents "something.property" syntax.
-         * StaticMemberExpression is oxc's variant for computed vs non-computed access.
-         */
-        if (callee?.type === 'MemberExpression' || callee?.type === 'StaticMemberExpression') {
-            const obj = callee.object;
-            const prop = callee.property;
-            /** Check: is this `eco.page(...)`, `eco.component(...)`, `eco.html(...)`, or `eco.layout(...)`? */
-            if (obj?.type === 'Identifier' &&
-                obj?.name === 'eco' &&
-                (prop?.name === 'page' ||
-                    prop?.name === 'component' ||
-                    prop?.name === 'html' ||
-                    prop?.name === 'layout')) {
-                /** Get the first argument - should be an object literal {...} */
-                const args = n.arguments;
-                const firstArg = args?.[0];
-                if (firstArg?.type === 'ObjectExpression') {
-                    /**
-                     * `start` is the character index where this object begins (the "{").
-                     * Insert at position+1 to place content right after "{".
-                     */
-                    const start = firstArg.start;
-                    if (typeof start === 'number') {
-                        insertions.push({ position: start + 1, text: injection });
-                    }
-                }
-            }
-        }
-    }
-    /**
-     * Pattern 2: Something.config = {...}
-     * AST structure: AssignmentExpression with MemberExpression left side ending in "config"
-     * This pattern is safe for all files because it requires a qualifier (e.g., MyComponent.config).
-     */
-    if (n.type === 'AssignmentExpression') {
-        const left = n.left;
-        const right = n.right;
-        /** Case: MyComponent.config = {...} */
-        if (left?.type === 'MemberExpression' || left?.type === 'StaticMemberExpression') {
-            const prop = left.property;
-            if (prop?.name === 'config' && right?.type === 'ObjectExpression') {
-                const start = right.start;
-                if (typeof start === 'number') {
-                    insertions.push({ position: start + 1, text: injection });
-                }
-            }
-        }
-    }
-    /**
-     * Pattern 3: { config: {...} } - config as an object property inside EcoComponent
-     * AST structure: ObjectProperty/Property with key "config" and value as ObjectExpression
-     *
-     * This pattern is matched when the parent VariableDeclarator has a type annotation
-     * containing "EcoComponent", e.g., `const X: EcoComponent = { config: {...} }`
-     *
-     * We track whether we're inside an EcoComponent-typed object via the `isInsideEcoComponent` flag.
-     */
-    if (n.type === 'ObjectProperty' || n.type === 'Property') {
-        const key = n.key;
-        const value = n.value;
-        if ((key?.type === 'Identifier' || key?.type === 'IdentifierName') &&
-            key?.name === 'config' &&
-            value?.type === 'ObjectExpression' &&
-            isInsideEcoComponent) {
-            const start = value.start;
-            if (typeof start === 'number') {
-                insertions.push({ position: start + 1, text: injection });
-            }
-        }
-    }
-    /**
-     * Check if we're entering an EcoComponent-typed variable declaration.
-     * This sets a flag for child nodes to know they're inside an EcoComponent.
-     *
-     * Type annotation is on the `id` (Identifier), not the VariableDeclarator directly.
-     * e.g., `const X: EcoComponent = {...}` has the annotation on the "X" Identifier.
-     */
-    let childIsInsideEcoComponent = isInsideEcoComponent;
-    if (n.type === 'VariableDeclarator') {
-        const id = n.id;
-        const typeAnnotation = id?.typeAnnotation;
-        if (typeAnnotation) {
-            const typeStr = JSON.stringify(typeAnnotation);
-            if (typeStr.includes('EcoComponent')) {
-                childIsInsideEcoComponent = true;
-            }
-        }
-    }
-    /**
-     * Recursive traversal: Visit all child nodes in the AST.
-     *
-     * This is how we "walk" the tree - for each property of the current node,
-     * if it's an array (like `body` containing statements) or an object (like `callee`),
-     * we recursively call findInjectionPoints on it.
-     * We skip metadata properties (start, end, type) that don't contain child nodes.
-     */
-    for (const key in n) {
-        if (key === 'start' || key === 'end' || key === 'type')
-            continue;
-        const value = n[key];
-        if (Array.isArray(value)) {
-            for (const child of value) {
-                findInjectionPoints(child, insertions, injection, childIsInsideEcoComponent);
-            }
-        }
-        else if (typeof value === 'object' && value !== null) {
-            findInjectionPoints(value, insertions, injection, childIsInsideEcoComponent);
-        }
-    }
-}
-/**
- * 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 function injectEcoMeta(contents, filePath, integration) {
-    const result = cachedParseSync(filePath, contents);
-    if (result.errors.length > 0) {
-        console.warn(`[eco-component-meta-plugin] Parse errors in ${filePath}:`, result.errors);
-        return contents;
-    }
-    const ast = result.program;
-    const id = rapidhash(filePath).toString(36);
-    const injection = ` __eco: { id: "${id}", file: "${filePath}", integration: "${integration}" },`;
-    const insertions = [];
-    findInjectionPoints(ast, insertions, injection);
-    if (insertions.length === 0) {
-        return contents;
-    }
-    insertions.sort((a, b) => b.position - a.position);
-    let transformed = contents;
-    for (const { position, text } of insertions) {
-        transformed = transformed.slice(0, position) + text + transformed.slice(position);
-    }
-    return transformed;
+export function createEcoComponentMetaPlugin(options) {
+    return createEcoBuildPluginFromSourceTransform(createEcoComponentMetaTransform(options));
 }
-export default createEcoComponentMetaPlugin;
+export default createEcoComponentMetaTransform;

package/src/plugins/processor.d.ts

@@ -112,6 +112,16 @@ export declare abstract class Processor<TOptions = Record<string, unknown>> {
      * warming or watcher registration should stay in `setup()`.
      */
     prepareBuildContributions(): Promise<void>;
+    /**
+     * Declares watch-mode SSR prewarm pathnames and readiness for core.
+     *
+     * @remarks
+     * Processors return paths and readiness only; core owns parallel rendering and page cache population.
+     */
+    collectDevPrewarmPlan(): Promise<{
+        pathnames: readonly string[];
+        readiness: 'background' | 'beforeReady';
+    }>;
     /**
      * Reports whether this processor's build inputs changed since the last
      * incremental static build.

package/src/plugins/processor.js

@@ -66,6 +66,15 @@ export class Processor {
      * warming or watcher registration should stay in `setup()`.
      */
     async prepareBuildContributions() { }
+    /**
+     * Declares watch-mode SSR prewarm pathnames and readiness for core.
+     *
+     * @remarks
+     * Processors return paths and readiness only; core owns parallel rendering and page cache population.
+     */
+    collectDevPrewarmPlan() {
+        return Promise.resolve({ pathnames: [], readiness: 'background' });
+    }
     /**
      * Reports whether this processor's build inputs changed since the last
      * incremental static build.

package/src/route-renderer/README.md

@@ -33,11 +33,11 @@ These concepts intentionally live in different places:
 
 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                                           |
+| Layer   | Mechanism                                                         | Purpose                                                                                                                                        |
+| ------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Build   | `getJsxOwnershipPlugins()` / `getHostScopedJsxOwnershipPlugins()` | Prepend `@jsxImportSource` so bundled `.tsx` files compile with the correct JSX runtime                                                        |
+| Build   | component identity source transform                               | After a lexical `eco.` gate, uses Oxc to wrap native factory options with `bindComponentIdentity()` and prepends the owning integration pragma |
+| 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.
 
@@ -69,9 +69,11 @@ Domain folders:
 
 **Page Browser Graph session behavior:**
 
-- In development, each Page Browser Graph is built on first request, cached in `page-browser-graph-session` with generation-safe commits, and invalidated when a tracked dependency changes. Hosts call `prepareHmrFileChange()` before HMR dispatch and defer client broadcasts when no browser subscribers are connected.
+- In development, each Page Browser Graph is built on first request, cached in `page-browser-graph-session` with generation-safe commits, and invalidated when a tracked dependency changes. The per-route fast path is disabled while HMR is enabled so prop-dependent `dependencies(props)` cannot reuse the wrong graph. Hosts call `prepareHmrFileChange()` before HMR dispatch and defer client broadcasts when no browser subscribers are connected.
+- Dev SSR prewarm schedules processor-declared pathnames for background rendering. Static pages cache in watch mode when their Cache Strategy allows it; dynamic pages are never retained. The watcher invalidates HTML through `invalidateAppPageCacheBySourcePaths` when a registered source dependency changes, and falls back to global cache clear for categories whose route impact cannot be narrowed.
+- **Measuring dev page load:** set `ECOPAGES_REQUEST_PIPELINE_METRICS=1` and run `pnpm run test:bench:docs`. Compare cold vs warm navigations and phase totals from the benchmark output.
 - Production static export prebuilds browser graphs from the finalized route list into the in-memory `page-browser-graph-session` via `production-page-browser-graph-prebuild.ts`. Failed exports clear staged production session records so retries cannot reuse partial graph output.
-- Integrations activate lazily on first render or graph prebuild via `ensureIntegrationRuntimeReady()`. Processors and loaders still initialize eagerly during `setupAppRuntimePlugins()`.
+- Integrations activate lazily on first render or graph prebuild via `ensureIntegrationRuntimeReady()`. Processors initialize their small virtual modules during `setupAppRuntimePlugins()`; content collection server artifacts are built lazily when a server build first resolves the collection.
 
 ### `page-loading/`
 
@@ -84,7 +86,7 @@ The route-render contract is:
 
 1. `RouteRendererFactory` selects the owning integration renderer.
 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.
+3. `RouteRenderOrchestrator.prepareRenderOptions()` loads the page module, validates ownership (fail-fast), resolves final page props, resolves dependencies, and builds the page browser graph. Graph cache identity includes route params and query; contribution collection receives those same final props.
 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. `RouteRenderOrchestrator.executePrepared()` captures the final body, rejects unresolved `<eco-marker>` artifacts, stamps document attributes when needed, and runs the HTML transformer.
@@ -92,7 +94,8 @@ The route-render contract is:
 Important:
 
 - route-level fallback resolution is gone; unresolved artifacts are now a hard failure
-- ownership is declared from component metadata, not inferred from final HTML
+- ownership is declared from canonical component identity, not inferred from final HTML
+- declared page dependencies are resolved from final render inputs and carried to the owning integration; integrations may use them for renderer-specific lifecycle work such as HMR ownership
 - same-integration children stay renderer-local and do not need to pass through a universal transport
 
 ## Declared Foreign Child Contract

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

@@ -6,7 +6,7 @@ function resolveDocumentShellLayouts(input) {
     return input.layout ? [input.layout] : [];
 }
 function resolveComponentIntegrationName(component) {
-    return component.config?.integration ?? component.config?.__eco?.integration ?? 'ecopages';
+    return component.config?.integration ?? component.config?.identity?.integration ?? 'ecopages';
 }
 /**
  * Default sequential string-child composition for document shell layers.

package/src/route-renderer/orchestration/foreign-child/foreign-subtree-execution.service.js

@@ -271,7 +271,7 @@ export class ForeignSubtreeExecutionService {
         };
     }
     getForeignOwnerIntegrationName(component, currentIntegrationName) {
-        const integrationName = component.config?.integration ?? component.config?.__eco?.integration;
+        const integrationName = component.config?.integration ?? component.config?.identity?.integration;
         if (!integrationName || integrationName === 'html' || integrationName === currentIntegrationName) {
             return undefined;
         }