@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.40

package/src/route-renderer/page-loading/ecopages-virtual-imports.js

@@ -1,57 +1,70 @@
-import { readFileSync } from "node:fs";
-import { parseSync } from "oxc-parser";
-function extractEcopagesVirtualImports(file) {
-  let source;
-  try {
-    source = readFileSync(file, "utf-8");
-  } catch {
-    return [];
-  }
-  let result;
-  try {
-    result = parseSync(file, source, { sourceType: "module" });
-  } catch {
-    return [];
-  }
-  const found = /* @__PURE__ */ new Map();
-  for (const node of result.program.body ?? []) {
-    if (node.type !== "ImportDeclaration") continue;
-    if (node.importKind === "type") continue;
-    const specifier = node.source?.value ?? "";
-    if (!specifier.startsWith("ecopages:")) continue;
-    if (found.get(specifier) === null) {
-      continue;
+import { readFileSync } from 'node:fs';
+import { isContentServerVirtualModule } from '../../build/contracts/content-virtual-modules.js';
+import { parseModuleSource } from '../../cache/module-parse-cache.js';
+export function isBrowserEcopagesVirtualImport(specifier) {
+    return specifier.startsWith('ecopages:') && !isContentServerVirtualModule(specifier);
+}
+/**
+ * Extracts runtime `ecopages:` virtual-module imports from a component source file.
+ *
+ * Type-only imports are skipped and bare namespace imports are represented by an
+ * `undefined` import list so downstream module generation can preserve that shape.
+ */
+export function extractEcopagesVirtualImports(file) {
+    let source;
+    try {
+        source = readFileSync(file, 'utf-8');
     }
-    const namedImports = [];
-    for (const spec of node.specifiers ?? []) {
-      if (spec.type === "ImportSpecifier") {
-        let importedName = spec.local?.name;
-        if (spec.imported?.type === "Identifier") {
-          importedName = spec.imported.name;
-        } else if (spec.imported?.type === "Literal") {
-          importedName = spec.imported.value;
-        }
-        namedImports.push(importedName);
-      }
+    catch {
+        return [];
     }
-    if (namedImports.length === 0) {
-      found.set(specifier, null);
-      continue;
+    let result;
+    try {
+        result = parseModuleSource(file, source);
     }
-    const existing = found.get(specifier);
-    if (!existing) {
-      found.set(specifier, new Set(namedImports));
-      continue;
+    catch {
+        return [];
     }
-    for (const imported of namedImports) {
-      existing.add(imported);
+    const found = new Map();
+    for (const node of result.program.body ?? []) {
+        if (node.type !== 'ImportDeclaration')
+            continue;
+        if (node.importKind === 'type')
+            continue;
+        const specifier = node.source?.value ?? '';
+        if (!isBrowserEcopagesVirtualImport(specifier))
+            continue;
+        if (found.get(specifier) === null) {
+            continue;
+        }
+        const namedImports = [];
+        for (const spec of node.specifiers ?? []) {
+            if (spec.type === 'ImportSpecifier') {
+                let importedName = spec.local?.name;
+                if (spec.imported?.type === 'Identifier') {
+                    importedName = spec.imported.name;
+                }
+                else if (spec.imported?.type === 'Literal') {
+                    importedName = spec.imported.value;
+                }
+                namedImports.push(importedName);
+            }
+        }
+        if (namedImports.length === 0) {
+            found.set(specifier, null);
+            continue;
+        }
+        const existing = found.get(specifier);
+        if (!existing) {
+            found.set(specifier, new Set(namedImports));
+            continue;
+        }
+        for (const imported of namedImports) {
+            existing.add(imported);
+        }
     }
-  }
-  return Array.from(found.entries()).map(([from, importsSet]) => ({
-    from,
-    imports: importsSet ? Array.from(importsSet) : void 0
-  }));
+    return Array.from(found.entries()).map(([from, importsSet]) => ({
+        from,
+        imports: importsSet ? Array.from(importsSet) : undefined,
+    }));
 }
-export {
-  extractEcopagesVirtualImports
-};

package/src/route-renderer/page-loading/file-scoped-dependency-components.d.ts

@@ -0,0 +1,42 @@
+import type { EcoComponent, EcoComponentConfig, EcoComponentDependencies } from '../../types/public-types.js';
+import type { PageDependenciesResult } from '../../eco/eco.types.js';
+/**
+ * Attaches canonical file-backed identity to one component config.
+ */
+export declare function attachEcoFileMetadataToConfig(config: EcoComponentConfig, ownerFile: string, integrationName: string): EcoComponentConfig;
+/**
+ * Builds a synthetic component config rooted at one file so direct dependency
+ * declarations can flow through the shared component dependency collector.
+ */
+export declare function createFileScopedDependencyComponent(options: {
+    ownerFile: string;
+    integrationName: string;
+    dependencies: Pick<EcoComponentDependencies, 'scripts' | 'stylesheets' | 'modules'>;
+}): Partial<EcoComponent> | undefined;
+/**
+ * Expands one dependency bag into component roots understood by the shared collector.
+ */
+export declare function collectFileScopedDependencyComponents(options: {
+    ownerFile: string;
+    integrationName: string;
+    dependencies: EcoComponentDependencies;
+}): Array<EcoComponent | Partial<EcoComponent>>;
+export type CollectComponentConfigFilePathsOptions = {
+    additionalPaths?: ReadonlyArray<string>;
+    includeLayouts?: boolean;
+};
+/**
+ * Walks component configs and collects every resolved identity file path.
+ */
+export declare function collectComponentConfigFilePaths(components: ReadonlyArray<EcoComponent | Partial<EcoComponent> | undefined>, options?: CollectComponentConfigFilePathsOptions): Set<string>;
+/**
+ * Collects source files that should invalidate a per-instance browser graph entry.
+ */
+export declare function collectDependencyWatchPaths(ownerFile: string, components: ReadonlyArray<EcoComponent | Partial<EcoComponent>>): string[];
+/**
+ * Separates optional owner metadata from a resolved page dependency bag.
+ */
+export declare function splitPageDependenciesResult(result: PageDependenciesResult): {
+    dependencies: EcoComponentDependencies;
+    ownerFile?: string;
+};

package/src/route-renderer/page-loading/file-scoped-dependency-components.js

@@ -0,0 +1,94 @@
+import path from 'node:path';
+import { rapidhash } from '../../utils/hash.js';
+import { bindComponentIdentity, getComponentIdentity } from '../../eco/component-identity.js';
+/**
+ * Attaches canonical file-backed identity to one component config.
+ */
+export function attachEcoFileMetadataToConfig(config, ownerFile, integrationName) {
+    return bindComponentIdentity({
+        id: getComponentIdentity(config)?.id ?? rapidhash(ownerFile).toString(36),
+        file: ownerFile,
+        integration: getComponentIdentity(config)?.integration ?? integrationName,
+    }, config);
+}
+/**
+ * Builds a synthetic component config rooted at one file so direct dependency
+ * declarations can flow through the shared component dependency collector.
+ */
+export function createFileScopedDependencyComponent(options) {
+    const { scripts, stylesheets, modules } = options.dependencies;
+    if (!scripts?.length && !stylesheets?.length && !modules?.length) {
+        return undefined;
+    }
+    return {
+        config: attachEcoFileMetadataToConfig({ dependencies: { scripts, stylesheets, modules } }, options.ownerFile, options.integrationName),
+    };
+}
+/**
+ * Expands one dependency bag into component roots understood by the shared collector.
+ */
+export function collectFileScopedDependencyComponents(options) {
+    const components = [];
+    if (options.dependencies.components?.length) {
+        components.push(...options.dependencies.components);
+    }
+    const ownerComponent = createFileScopedDependencyComponent({
+        ownerFile: options.ownerFile,
+        integrationName: options.integrationName,
+        dependencies: options.dependencies,
+    });
+    if (ownerComponent) {
+        components.push(ownerComponent);
+    }
+    return components;
+}
+/**
+ * Walks component configs and collects every resolved identity file path.
+ */
+export function collectComponentConfigFilePaths(components, options) {
+    const files = new Set();
+    const visited = new Set();
+    for (const additionalPath of options?.additionalPaths ?? []) {
+        files.add(path.resolve(additionalPath));
+    }
+    const visit = (config) => {
+        const file = getComponentIdentity(config)?.file;
+        if (!file) {
+            return;
+        }
+        if (!config) {
+            return;
+        }
+        const resolved = path.resolve(file);
+        if (visited.has(resolved)) {
+            return;
+        }
+        visited.add(resolved);
+        files.add(resolved);
+        for (const dependency of config.dependencies?.components ?? []) {
+            visit(dependency?.config);
+        }
+        if (options?.includeLayouts) {
+            for (const layout of config.layouts ?? []) {
+                visit(layout?.config);
+            }
+        }
+    };
+    for (const component of components) {
+        visit(component?.config);
+    }
+    return files;
+}
+/**
+ * Collects source files that should invalidate a per-instance browser graph entry.
+ */
+export function collectDependencyWatchPaths(ownerFile, components) {
+    return Array.from(collectComponentConfigFilePaths(components, { additionalPaths: [ownerFile] }));
+}
+/**
+ * Separates optional owner metadata from a resolved page dependency bag.
+ */
+export function splitPageDependenciesResult(result) {
+    const { ownerFile, ...dependencies } = result;
+    return { dependencies, ownerFile };
+}

package/src/route-renderer/page-loading/lazy-entry-collection.js

@@ -1,105 +1,82 @@
-import { AssetFactory } from "../../services/assets/asset-processing-service/index.js";
-import { rapidhash } from "../../utils/hash.js";
-import { getLazyTriggerKey } from "./lazy-trigger-planning.js";
+import { AssetFactory } from '../../services/assets/asset-processing-service/index.js';
+import { rapidhash } from '../../utils/hash.js';
+import { getLazyTriggerKey } from './lazy-trigger-planning.js';
 function isDependencyEntryObject(entry) {
-  return typeof entry === "object" && entry !== null;
+    return typeof entry === 'object' && entry !== null;
 }
 function getDependencyEntrySrcOrThrow(entry, errorMessage) {
-  if (!entry.src) {
-    throw new Error(errorMessage);
-  }
-  return entry.src;
-}
-function collectLazyScriptEntries(options) {
-  const {
-    scriptEntries,
-    componentFile,
-    componentDir,
-    integrationName,
-    dependencies,
-    lazyDependencyKeys,
-    registerLazyScript,
-    resolveDependencyPath,
-    resolveLazyScripts,
-    createModuleScriptAttributes,
-    createEcopagesJsxLazyEntryName,
-    pushUniqueDependency,
-    getLazyScriptMissingSrcMessage,
-    isEcopagesJsxIntegration
-  } = options;
-  for (const [index, scriptEntry] of scriptEntries.entries()) {
-    if (!isDependencyEntryObject(scriptEntry) || !scriptEntry.lazy) {
-      continue;
-    }
-    const lazy = scriptEntry.lazy;
-    const content = scriptEntry.content;
-    const src = scriptEntry.src;
-    const attributes = scriptEntry.attributes;
-    if (content) {
-      const lazyKey2 = `lazy:${rapidhash(`${componentFile}:entry:${index}:${content}`).toString(16)}`;
-      const depKey2 = `lazy:entry:content:${getLazyTriggerKey(lazy)}:${content}:${JSON.stringify(attributes ?? {})}`;
-      pushUniqueDependency(
-        lazyDependencyKeys,
-        depKey2,
-        dependencies,
-        AssetFactory.createContentScript({
-          position: "head",
-          content,
-          excludeFromHtml: true,
-          attributes: {
-            ...createModuleScriptAttributes(attributes),
-            "data-eco-lazy-key": lazyKey2
-          }
-        })
-      );
-      registerLazyScript({
-        lazy,
-        lazyKey: lazyKey2
-      });
-      continue;
+    if (!entry.src) {
+        throw new Error(errorMessage);
     }
-    const script = src ?? getDependencyEntrySrcOrThrow(scriptEntry, getLazyScriptMissingSrcMessage());
-    const resolvedPath = resolveDependencyPath(componentDir, script);
-    const fallbackUrl = resolveLazyScripts(componentDir, [script]).split(",")[0] ?? "";
-    const lazyKey = `lazy:${rapidhash(`${resolvedPath}:${getLazyTriggerKey(lazy)}`).toString(16)}`;
-    const lazyEntryName = createEcopagesJsxLazyEntryName(
-      integrationName,
-      `${resolvedPath}:${getLazyTriggerKey(lazy)}`
-    );
-    const depKey = `lazy:entry:file:${getLazyTriggerKey(lazy)}:${resolvedPath}:${JSON.stringify(attributes ?? {})}`;
-    pushUniqueDependency(
-      lazyDependencyKeys,
-      depKey,
-      dependencies,
-      isEcopagesJsxIntegration(integrationName) ? AssetFactory.createContentScript({
-        name: lazyEntryName,
-        position: "head",
-        content: `import ${JSON.stringify(resolvedPath)};`,
-        excludeFromHtml: true,
-        bundleOptions: {
-          splitting: false
-        },
-        attributes: {
-          ...createModuleScriptAttributes(attributes),
-          "data-eco-lazy-key": lazyKey
+    return entry.src;
+}
+/**
+ * Collects lazy script dependency entries and emits their hidden bundle inputs.
+ *
+ * This helper also reports the trigger-to-script relationship back to the caller so
+ * later stages can build the lazy-trigger manifest without reparsing dependency config.
+ */
+export function collectLazyScriptEntries(options) {
+    const { scriptEntries, componentFile, componentDir, integrationName, dependencies, lazyDependencyKeys, registerLazyScript, resolveDependencyPath, resolveLazyScripts, createModuleScriptAttributes, createEcopagesJsxLazyEntryName, pushUniqueDependency, getLazyScriptMissingSrcMessage, isEcopagesJsxIntegration, } = options;
+    for (const [index, scriptEntry] of scriptEntries.entries()) {
+        if (!isDependencyEntryObject(scriptEntry) || !scriptEntry.lazy) {
+            continue;
         }
-      }) : AssetFactory.createFileScript({
-        filepath: resolvedPath,
-        position: "head",
-        excludeFromHtml: true,
-        attributes: {
-          ...createModuleScriptAttributes(attributes),
-          "data-eco-lazy-key": lazyKey
+        const lazy = scriptEntry.lazy;
+        const content = scriptEntry.content;
+        const src = scriptEntry.src;
+        const attributes = scriptEntry.attributes;
+        if (content) {
+            const lazyKey = `lazy:${rapidhash(`${componentFile}:entry:${index}:${content}`).toString(16)}`;
+            const depKey = `lazy:entry:content:${getLazyTriggerKey(lazy)}:${content}:${JSON.stringify(attributes ?? {})}`;
+            pushUniqueDependency(lazyDependencyKeys, depKey, dependencies, AssetFactory.createContentScript({
+                position: 'head',
+                content,
+                excludeFromHtml: true,
+                attributes: {
+                    ...createModuleScriptAttributes(attributes),
+                    'data-eco-lazy-key': lazyKey,
+                },
+            }));
+            registerLazyScript({
+                lazy,
+                lazyKey,
+            });
+            continue;
         }
-      })
-    );
-    registerLazyScript({
-      lazy,
-      lazyKey,
-      fallbackUrl
-    });
-  }
+        const script = src ?? getDependencyEntrySrcOrThrow(scriptEntry, getLazyScriptMissingSrcMessage());
+        const resolvedPath = resolveDependencyPath(componentDir, script);
+        const fallbackUrl = resolveLazyScripts(componentDir, [script]).split(',')[0] ?? '';
+        const lazyKey = `lazy:${rapidhash(`${resolvedPath}:${getLazyTriggerKey(lazy)}`).toString(16)}`;
+        const lazyEntryName = createEcopagesJsxLazyEntryName(integrationName, `${resolvedPath}:${getLazyTriggerKey(lazy)}`);
+        const depKey = `lazy:entry:file:${getLazyTriggerKey(lazy)}:${resolvedPath}:${JSON.stringify(attributes ?? {})}`;
+        pushUniqueDependency(lazyDependencyKeys, depKey, dependencies, isEcopagesJsxIntegration(integrationName)
+            ? AssetFactory.createContentScript({
+                name: lazyEntryName,
+                position: 'head',
+                content: `import ${JSON.stringify(resolvedPath)};`,
+                excludeFromHtml: true,
+                bundleOptions: {
+                    splitting: false,
+                },
+                attributes: {
+                    ...createModuleScriptAttributes(attributes),
+                    'data-eco-lazy-key': lazyKey,
+                },
+            })
+            : AssetFactory.createFileScript({
+                filepath: resolvedPath,
+                position: 'head',
+                excludeFromHtml: true,
+                attributes: {
+                    ...createModuleScriptAttributes(attributes),
+                    'data-eco-lazy-key': lazyKey,
+                },
+            }));
+        registerLazyScript({
+            lazy,
+            lazyKey,
+            fallbackUrl,
+        });
+    }
 }
-export {
-  collectLazyScriptEntries
-};

package/src/route-renderer/page-loading/lazy-trigger-planning.js

@@ -1,40 +1,51 @@
-import { rapidhash } from "../../utils/hash.js";
-function getLazyTriggerKey(lazy) {
-  if ("on:idle" in lazy) {
-    return "on:idle";
-  }
-  if ("on:interaction" in lazy) {
-    return `on:interaction:${lazy["on:interaction"]}`;
-  }
-  if ("on:visible" in lazy) {
-    const value = lazy["on:visible"];
-    return `on:visible:${value === true ? "true" : value}`;
-  }
-  return JSON.stringify(lazy);
-}
-function buildResolvedLazyTriggers(config, groups) {
-  if (groups.length === 0) return [];
-  const componentFile = config.__eco?.file ?? "";
-  const sortedUrls = groups.flatMap((group) => group.scripts).sort().join(",");
-  const triggerId = `eco-trigger-${rapidhash(`${componentFile}:${sortedUrls}`).toString(16)}`;
-  const rules = groups.map((group) => {
-    const { scripts, lazy } = group;
-    if ("on:idle" in lazy) {
-      return { "on:idle": { scripts } };
+import { getComponentIdentity } from '../../eco/component-identity.js';
+import { rapidhash } from '../../utils/hash.js';
+/**
+ * Creates a stable grouping key for a lazy trigger declaration.
+ */
+export function getLazyTriggerKey(lazy) {
+    if ('on:idle' in lazy) {
+        return 'on:idle';
     }
-    if ("on:interaction" in lazy) {
-      return { "on:interaction": { value: lazy["on:interaction"], scripts } };
+    if ('on:interaction' in lazy) {
+        return `on:interaction:${lazy['on:interaction']}`;
     }
-    if ("on:visible" in lazy) {
-      const visibleSelector = lazy["on:visible"];
-      if (visibleSelector === true) return { "on:visible": { scripts } };
-      return { "on:visible": { value: String(visibleSelector), scripts } };
+    if ('on:visible' in lazy) {
+        const value = lazy['on:visible'];
+        return `on:visible:${value === true ? 'true' : value}`;
     }
-    throw new Error(`Unknown lazy trigger kind: ${JSON.stringify(lazy)}`);
-  });
-  return [{ triggerId, rules }];
+    return JSON.stringify(lazy);
+}
+/**
+ * Derives the public lazy-trigger manifest attached to a component config.
+ *
+ * The generated `triggerId` is stable for the same component file and set of
+ * resolved script URLs, independent of declaration order.
+ */
+export function buildResolvedLazyTriggers(config, groups) {
+    if (groups.length === 0)
+        return [];
+    const componentFile = getComponentIdentity(config)?.file ?? '';
+    const sortedUrls = groups
+        .flatMap((group) => group.scripts)
+        .sort()
+        .join(',');
+    const triggerId = `eco-trigger-${rapidhash(`${componentFile}:${sortedUrls}`).toString(16)}`;
+    const rules = groups.map((group) => {
+        const { scripts, lazy } = group;
+        if ('on:idle' in lazy) {
+            return { 'on:idle': { scripts } };
+        }
+        if ('on:interaction' in lazy) {
+            return { 'on:interaction': { value: lazy['on:interaction'], scripts } };
+        }
+        if ('on:visible' in lazy) {
+            const visibleSelector = lazy['on:visible'];
+            if (visibleSelector === true)
+                return { 'on:visible': { scripts } };
+            return { 'on:visible': { value: String(visibleSelector), scripts } };
+        }
+        throw new Error(`Unknown lazy trigger kind: ${JSON.stringify(lazy)}`);
+    });
+    return [{ triggerId, rules }];
 }
-export {
-  buildResolvedLazyTriggers,
-  getLazyTriggerKey
-};

package/src/route-renderer/page-loading/module-declaration-aggregation.js

@@ -1,33 +1,44 @@
-import { normalizeModuleDeclarations } from "../../eco/module-dependencies.js";
+import { normalizeModuleDeclarations } from '../../eco/module-dependencies.js';
+import { isBrowserEcopagesVirtualImport } from './ecopages-virtual-imports.js';
+/**
+ * Narrows arbitrary config input onto the declared module string array shape.
+ */
 function getDeclaredModules(value) {
-  if (!Array.isArray(value)) {
-    return void 0;
-  }
-  return value.every((entry) => typeof entry === "string") ? value : void 0;
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    return value.every((entry) => typeof entry === 'string') ? value : undefined;
 }
+/**
+ * Merges one module declaration into the aggregated map, preserving the wildcard
+ * import semantics represented by `null`.
+ */
 function mergeModuleDeclaration(modulesMap, declaration) {
-  const existing = modulesMap.get(declaration.from);
-  if (!declaration.imports || declaration.imports.length === 0) {
-    modulesMap.set(declaration.from, null);
-    return;
-  }
-  if (existing === null) {
-    return;
-  }
-  const merged = existing ?? /* @__PURE__ */ new Set();
-  for (const imported of declaration.imports) {
-    merged.add(imported);
-  }
-  modulesMap.set(declaration.from, merged);
+    const existing = modulesMap.get(declaration.from);
+    if (!declaration.imports || declaration.imports.length === 0) {
+        modulesMap.set(declaration.from, null);
+        return;
+    }
+    if (existing === null) {
+        return;
+    }
+    const merged = existing ?? new Set();
+    for (const imported of declaration.imports) {
+        merged.add(imported);
+    }
+    modulesMap.set(declaration.from, merged);
 }
-function collectModuleDeclarations(modulesMap, declaredModules, autoVirtualImports) {
-  for (const declaration of normalizeModuleDeclarations(getDeclaredModules(declaredModules))) {
-    mergeModuleDeclaration(modulesMap, declaration);
-  }
-  for (const declaration of autoVirtualImports) {
-    mergeModuleDeclaration(modulesMap, declaration);
-  }
+/**
+ * Combines explicit config module declarations with auto-detected `ecopages:` imports.
+ */
+export function collectModuleDeclarations(modulesMap, declaredModules, autoVirtualImports) {
+    for (const declaration of normalizeModuleDeclarations(getDeclaredModules(declaredModules))) {
+        if (declaration.from.startsWith('ecopages:') && !isBrowserEcopagesVirtualImport(declaration.from)) {
+            continue;
+        }
+        mergeModuleDeclaration(modulesMap, declaration);
+    }
+    for (const declaration of autoVirtualImports) {
+        mergeModuleDeclaration(modulesMap, declaration);
+    }
 }
-export {
-  collectModuleDeclarations
-};

package/src/route-renderer/page-loading/module-declaration-scripts.js

@@ -1,18 +1,13 @@
-import { rapidhash } from "../../utils/hash.js";
-function createModuleScriptName(from, imports) {
-  const normalizedImports = imports ? [...imports].sort().join(",") : "*";
-  const hash = rapidhash(`${from}|${normalizedImports}`).toString(16);
-  return `module-${hash}`;
+import { rapidhash } from '../../utils/hash.js';
+export function createModuleScriptName(from, imports) {
+    const normalizedImports = imports ? [...imports].sort().join(',') : '*';
+    const hash = rapidhash(`${from}|${normalizedImports}`).toString(16);
+    return `module-${hash}`;
 }
-function createNamedImportModuleSource(from, imports) {
-  const namedImports = [...new Set(imports)].sort().join(", ");
-  return `export { ${namedImports} } from '${from}';`;
+export function createNamedImportModuleSource(from, imports) {
+    const namedImports = [...new Set(imports)].sort().join(', ');
+    return `export { ${namedImports} } from '${from}';`;
 }
-function createNamespaceImportModuleSource(from) {
-  return `export * from '${from}';`;
+export function createNamespaceImportModuleSource(from) {
+    return `export * from '${from}';`;
 }
-export {
-  createModuleScriptName,
-  createNamedImportModuleSource,
-  createNamespaceImportModuleSource
-};