@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.0

package/src/services/assets/asset-processing-service/asset.factory.js

@@ -1,82 +1,79 @@
-import { RESOLVED_ASSETS_DIR, RESOLVED_ASSETS_VENDORS_DIR } from "../../../config/constants.js";
-import { deepMerge } from "../../../utils/deep-merge.js";
-class AssetFactory {
-  static RESOLVED_ASSETS_DIR = RESOLVED_ASSETS_DIR;
-  static RESOLVED_ASSETS_VENDORS_DIR = RESOLVED_ASSETS_VENDORS_DIR;
-  static createContentScript(options) {
-    return {
-      kind: "script",
-      source: "content",
-      position: options.position || "body",
-      ...options
-    };
-  }
-  static createInlineContentScript(options) {
-    return {
-      ...AssetFactory.createContentScript(options),
-      inline: true
-    };
-  }
-  static createFileScript(options) {
-    return {
-      kind: "script",
-      source: "file",
-      position: options.position || "body",
-      ...options
-    };
-  }
-  static createInlineFileScript(options) {
-    return {
-      ...AssetFactory.createFileScript(options),
-      inline: true
-    };
-  }
-  static createNodeModuleScript(options) {
-    return {
-      kind: "script",
-      source: "node-module",
-      position: options.position || "body",
-      ...options
-    };
-  }
-  static createInlineNodeModuleScript(options) {
-    return {
-      ...AssetFactory.createNodeModuleScript(options),
-      inline: true
-    };
-  }
-  static createJsonScript(options) {
-    return {
-      kind: "script",
-      source: "content",
-      attributes: deepMerge(options.attributes, { type: "application/json" }),
-      position: options.position || "body",
-      ...options
-    };
-  }
-  static createContentStylesheet(options) {
-    return {
-      kind: "stylesheet",
-      source: "content",
-      position: "head",
-      ...options
-    };
-  }
-  static createInlineContentStylesheet(options) {
-    return {
-      ...AssetFactory.createContentStylesheet(options),
-      inline: true
-    };
-  }
-  static createFileStylesheet(options) {
-    return {
-      kind: "stylesheet",
-      source: "file",
-      position: options.position || "head",
-      ...options
-    };
-  }
+import { RESOLVED_ASSETS_DIR, RESOLVED_ASSETS_VENDORS_DIR } from '../../../config/constants.js';
+import { deepMerge } from '../../../utils/deep-merge.js';
+export class AssetFactory {
+    static RESOLVED_ASSETS_DIR = RESOLVED_ASSETS_DIR;
+    static RESOLVED_ASSETS_VENDORS_DIR = RESOLVED_ASSETS_VENDORS_DIR;
+    static createContentScript(options) {
+        return {
+            kind: 'script',
+            source: 'content',
+            position: options.position || 'body',
+            ...options,
+        };
+    }
+    static createInlineContentScript(options) {
+        return {
+            ...AssetFactory.createContentScript(options),
+            inline: true,
+        };
+    }
+    static createFileScript(options) {
+        return {
+            kind: 'script',
+            source: 'file',
+            position: options.position || 'body',
+            ...options,
+        };
+    }
+    static createInlineFileScript(options) {
+        return {
+            ...AssetFactory.createFileScript(options),
+            inline: true,
+        };
+    }
+    static createNodeModuleScript(options) {
+        return {
+            kind: 'script',
+            source: 'node-module',
+            position: options.position || 'body',
+            ...options,
+        };
+    }
+    static createInlineNodeModuleScript(options) {
+        return {
+            ...AssetFactory.createNodeModuleScript(options),
+            inline: true,
+        };
+    }
+    static createJsonScript(options) {
+        return {
+            kind: 'script',
+            source: 'content',
+            attributes: deepMerge(options.attributes, { type: 'application/json' }),
+            position: options.position || 'body',
+            ...options,
+        };
+    }
+    static createContentStylesheet(options) {
+        return {
+            kind: 'stylesheet',
+            source: 'content',
+            position: 'head',
+            ...options,
+        };
+    }
+    static createInlineContentStylesheet(options) {
+        return {
+            ...AssetFactory.createContentStylesheet(options),
+            inline: true,
+        };
+    }
+    static createFileStylesheet(options) {
+        return {
+            kind: 'stylesheet',
+            source: 'file',
+            position: options.position || 'head',
+            ...options,
+        };
+    }
 }
-export {
-  AssetFactory
-};

package/src/services/assets/asset-processing-service/assets.types.d.ts

@@ -1,4 +1,4 @@
-import type { EcoBuildPlugin } from '../../../build/build-types.js';
+import type { EcoBuildPlugin } from '../../../build/contracts/build-types.js';
 export type AssetSource = 'content' | 'file' | 'node-module';
 export type AssetKind = 'script' | 'stylesheet';
 export type AssetPosition = 'head' | 'body';

package/src/services/assets/asset-processing-service/assets.types.js

@@ -0,0 +1 @@
+export {};

package/src/services/assets/asset-processing-service/browser-runtime-asset.factory.d.ts

@@ -1,4 +1,4 @@
-import type { EcoBuildPlugin } from '../../../build/build-types.js';
+import type { EcoBuildPlugin } from '../../../build/contracts/build-types.js';
 import type { AssetDefinition } from './assets.types.js';
 import { type BrowserRuntimeEntryModuleConfig } from './browser-runtime-entry.factory.js';
 export declare const BROWSER_RUNTIME_SCRIPT_ATTRIBUTES: {

package/src/services/assets/asset-processing-service/browser-runtime-asset.factory.js

@@ -1,50 +1,61 @@
-import { AssetFactory } from "./asset.factory.js";
-import {
-  createBrowserRuntimeEntryModule
-} from "./browser-runtime-entry.factory.js";
-const BROWSER_RUNTIME_SCRIPT_ATTRIBUTES = {
-  type: "module",
-  defer: ""
+import { AssetFactory } from './asset.factory.js';
+import { createBrowserRuntimeEntryModule, } from './browser-runtime-entry.factory.js';
+export const BROWSER_RUNTIME_SCRIPT_ATTRIBUTES = {
+    type: 'module',
+    defer: '',
 };
-function buildBrowserRuntimeAssetUrl(fileName) {
-  return `/${AssetFactory.RESOLVED_ASSETS_VENDORS_DIR}/${fileName}`;
+/**
+ * Builds the public vendor URL used for generated browser runtime assets.
+ */
+export function buildBrowserRuntimeAssetUrl(fileName) {
+    return `/${AssetFactory.RESOLVED_ASSETS_VENDORS_DIR}/${fileName}`;
 }
-function createBrowserRuntimeScriptAsset(options) {
-  return AssetFactory.createNodeModuleScript({
-    position: "head",
-    importPath: options.importPath,
-    name: options.name,
-    packageRole: "runtime",
-    excludeFromHtml: true,
-    bundleOptions: {
-      naming: options.fileName,
-      ...options.bundleOptions
-    },
-    attributes: {
-      ...BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
-      ...options.attributes ?? {}
-    }
-  });
+/**
+ * Declares a browser runtime script asset backed by one importable module.
+ *
+ * @remarks
+ * Runtime assets are emitted as excluded head scripts because integrations often
+ * need the bundler output and specifier registration without injecting the raw
+ * asset directly into HTML during dependency resolution.
+ */
+export function createBrowserRuntimeScriptAsset(options) {
+    return AssetFactory.createNodeModuleScript({
+        position: 'head',
+        importPath: options.importPath,
+        name: options.name,
+        packageRole: 'runtime',
+        excludeFromHtml: true,
+        bundleOptions: {
+            naming: options.fileName,
+            ...options.bundleOptions,
+        },
+        attributes: {
+            ...BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
+            ...(options.attributes ?? {}),
+        },
+    });
 }
-function createBrowserRuntimeModuleAsset(options) {
-  const importPath = createBrowserRuntimeEntryModule({
-    modules: options.modules,
-    fileName: `${options.name}-entry.mjs`,
-    rootDir: options.rootDir,
-    workDir: options.workDir,
-    cacheDirName: options.cacheDirName
-  });
-  return createBrowserRuntimeScriptAsset({
-    importPath,
-    name: options.name,
-    fileName: options.fileName,
-    bundleOptions: options.bundleOptions,
-    attributes: options.attributes
-  });
+/**
+ * Creates a browser runtime asset from a generated re-export entry module.
+ *
+ * @remarks
+ * This is the shared "module list -> generated entry file -> runtime asset"
+ * path used by integrations that need browser-side runtime bundles without
+ * owning bespoke entry-file generation logic.
+ */
+export function createBrowserRuntimeModuleAsset(options) {
+    const importPath = createBrowserRuntimeEntryModule({
+        modules: options.modules,
+        fileName: `${options.name}-entry.mjs`,
+        rootDir: options.rootDir,
+        workDir: options.workDir,
+        cacheDirName: options.cacheDirName,
+    });
+    return createBrowserRuntimeScriptAsset({
+        importPath,
+        name: options.name,
+        fileName: options.fileName,
+        bundleOptions: options.bundleOptions,
+        attributes: options.attributes,
+    });
 }
-export {
-  BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
-  buildBrowserRuntimeAssetUrl,
-  createBrowserRuntimeModuleAsset,
-  createBrowserRuntimeScriptAsset
-};

package/src/services/assets/asset-processing-service/browser-runtime-entry-resolution.d.ts

@@ -0,0 +1,52 @@
+import type { createRequire } from 'node:module';
+export type BrowserRuntimeDefaultExportPolicy = 'emit-default' | 'skip-default';
+type RequireFromRoot = ReturnType<typeof createRequire>;
+/**
+ * Resolves a package specifier to its ESM entry file path from the app root.
+ */
+export declare function resolvePackageEsmEntryPath(specifier: string, rootDir: string): string | undefined;
+/**
+ * Builds a relative import path from a generated runtime entry file to a resolved module path.
+ */
+export declare function toRelativeEntryImport(entryDir: string, resolvedPath: string): string;
+/**
+ * Resolves a browser runtime entry import to an ESM file path when possible.
+ *
+ * @remarks
+ * `createRequire().resolve()` follows the `require` export condition and can
+ * land on `.cjs` entrypoints. Browser vendor bundles then emit runtime
+ * `require()` calls for React externals. Prefer Node's ESM resolver first, then
+ * a `.cjs` → `.js` sibling fallback.
+ */
+export declare function resolveBrowserRuntimeEntryImport(options: {
+    specifier: string;
+    requireFromRoot: RequireFromRoot;
+    entryDir: string;
+    rootDir: string;
+}): string;
+/**
+ * Decides whether a generated runtime entry should re-export a default binding.
+ *
+ * @remarks
+ * ESM-only packages such as `@tanstack/react-query` expose named exports only.
+ * Legacy CJS packages such as `react` assign `module.exports` directly and have
+ * no `.default` under `require()`, but still need a default re-export for
+ * `import React from 'react'` in browser bundles.
+ *
+ * ESM source inspection is a best-effort fast path; when it is inconclusive the
+ * policy falls back to the shape returned by `require()`.
+ */
+export declare function inferBrowserRuntimeDefaultExportPolicy(options: {
+    specifier: string;
+    requireFromRoot: RequireFromRoot;
+    rootDir: string;
+}): BrowserRuntimeDefaultExportPolicy;
+/**
+ * Reads the named runtime exports that should be re-exported from a generated runtime entry module.
+ *
+ * @remarks
+ * Default exports are handled separately because generated runtime entry files need to emit a
+ * synthetic default binding only when the caller explicitly asks for it.
+ */
+export declare function listBrowserRuntimeModuleExportNames(specifier: string, requireFromRoot: RequireFromRoot): string[];
+export {};

package/src/services/assets/asset-processing-service/browser-runtime-entry-resolution.js

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { isBarePackageImportSpecifier } from '../../../plugins/tsconfig-import-resolver.js';
+/**
+ * Resolves a package specifier to its ESM entry file path from the app root.
+ */
+export function resolvePackageEsmEntryPath(specifier, rootDir) {
+    try {
+        return fileURLToPath(import.meta.resolve(specifier, pathToFileURL(path.join(rootDir, 'package.json')).href));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Builds a relative import path from a generated runtime entry file to a resolved module path.
+ */
+export function toRelativeEntryImport(entryDir, resolvedPath) {
+    let relativePath = path.relative(entryDir, resolvedPath).replace(/\\/g, '/');
+    if (!relativePath.startsWith('.')) {
+        relativePath = `./${relativePath}`;
+    }
+    return relativePath;
+}
+/**
+ * Resolves a browser runtime entry import to an ESM file path when possible.
+ *
+ * @remarks
+ * `createRequire().resolve()` follows the `require` export condition and can
+ * land on `.cjs` entrypoints. Browser vendor bundles then emit runtime
+ * `require()` calls for React externals. Prefer Node's ESM resolver first, then
+ * a `.cjs` → `.js` sibling fallback.
+ */
+export function resolveBrowserRuntimeEntryImport(options) {
+    const { specifier, requireFromRoot, entryDir, rootDir } = options;
+    if (specifier.startsWith('node:') || specifier.startsWith('file:')) {
+        return specifier;
+    }
+    if (specifier.startsWith('.')) {
+        const resolvedPath = requireFromRoot.resolve(specifier);
+        return toRelativeEntryImport(entryDir, resolvedPath);
+    }
+    if (isBarePackageImportSpecifier(specifier, rootDir)) {
+        const esmResolvedPath = resolvePackageEsmEntryPath(specifier, rootDir);
+        if (esmResolvedPath) {
+            return toRelativeEntryImport(entryDir, esmResolvedPath);
+        }
+    }
+    const resolvedPath = requireFromRoot.resolve(specifier);
+    const esmSibling = resolvedPath.endsWith('.cjs')
+        ? `${resolvedPath.slice(0, -4)}.js`
+        : resolvedPath.endsWith('.cts')
+            ? `${resolvedPath.slice(0, -4)}.ts`
+            : undefined;
+    if (esmSibling && fs.existsSync(esmSibling)) {
+        return toRelativeEntryImport(entryDir, esmSibling);
+    }
+    return toRelativeEntryImport(entryDir, resolvedPath);
+}
+/**
+ * Decides whether a generated runtime entry should re-export a default binding.
+ *
+ * @remarks
+ * ESM-only packages such as `@tanstack/react-query` expose named exports only.
+ * Legacy CJS packages such as `react` assign `module.exports` directly and have
+ * no `.default` under `require()`, but still need a default re-export for
+ * `import React from 'react'` in browser bundles.
+ *
+ * ESM source inspection is a best-effort fast path; when it is inconclusive the
+ * policy falls back to the shape returned by `require()`.
+ */
+export function inferBrowserRuntimeDefaultExportPolicy(options) {
+    const { specifier, requireFromRoot, rootDir } = options;
+    const esmPath = resolvePackageEsmEntryPath(specifier, rootDir);
+    if (esmPath && fs.existsSync(esmPath)) {
+        const source = fs.readFileSync(esmPath, 'utf8');
+        if (/\bexport\s+default\b/.test(source)) {
+            return 'emit-default';
+        }
+        if (/\bexport\s+(?:[\w*{]|const|let|var|function|class)/.test(source)) {
+            return 'skip-default';
+        }
+    }
+    try {
+        const moduleExports = requireFromRoot(specifier);
+        if (moduleExports.default !== undefined) {
+            return 'emit-default';
+        }
+        return moduleExports.__esModule === true ? 'skip-default' : 'emit-default';
+    }
+    catch {
+        return 'skip-default';
+    }
+}
+/**
+ * Reads the named runtime exports that should be re-exported from a generated runtime entry module.
+ *
+ * @remarks
+ * Default exports are handled separately because generated runtime entry files need to emit a
+ * synthetic default binding only when the caller explicitly asks for it.
+ */
+export function listBrowserRuntimeModuleExportNames(specifier, requireFromRoot) {
+    let moduleExports;
+    try {
+        moduleExports = requireFromRoot(specifier);
+    }
+    catch {
+        return [];
+    }
+    return Object.keys(moduleExports)
+        .filter((name) => name !== '__esModule' && name !== 'default')
+        .filter((name) => /^[$A-Z_a-z][$\w]*$/.test(name))
+        .sort();
+}

package/src/services/assets/asset-processing-service/browser-runtime-entry.factory.js

@@ -1,61 +1,56 @@
-import fs from "node:fs";
-import path from "node:path";
-import { createRequire } from "node:module";
-import { DEFAULT_ECOPAGES_WORK_DIR } from "../../../config/constants.js";
-function createBrowserRuntimeEntryModule(options) {
-  if (options.modules.some((module) => !module.specifier.startsWith("node:")) && !options.rootDir) {
-    throw new Error("createBrowserRuntimeEntryModule requires rootDir to resolve package specifiers");
-  }
-  const rootDir = options.rootDir ?? process.cwd();
-  const workDir = options.workDir ?? path.join(rootDir, DEFAULT_ECOPAGES_WORK_DIR);
-  const artifactsDir = path.join(
-    workDir,
-    ".browser-runtime-entries",
-    options.cacheDirName ?? "ecopages-browser-runtime"
-  );
-  fs.mkdirSync(artifactsDir, { recursive: true });
-  const requireFromRoot = createRequire(path.join(rootDir, "package.json"));
-  const seenExports = /* @__PURE__ */ new Set();
-  const statements = [];
-  const filePath = path.join(artifactsDir, options.fileName);
-  const entryDir = path.dirname(filePath);
-  for (const module of options.modules) {
-    const importSpecifier = resolveEntryImportSpecifier(module.specifier, requireFromRoot, entryDir);
-    if (module.defaultExport) {
-      statements.push(`import __ecopages_default_export__ from '${importSpecifier}';`);
-      statements.push("export default __ecopages_default_export__;");
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { DEFAULT_ECOPAGES_WORK_DIR } from '../../../config/constants.js';
+import { inferBrowserRuntimeDefaultExportPolicy, listBrowserRuntimeModuleExportNames, resolveBrowserRuntimeEntryImport, } from './browser-runtime-entry-resolution.js';
+/**
+ * Creates a generated ESM entry module that re-exports runtime modules through
+ * one stable file.
+ *
+ * @remarks
+ * Integrations use this helper when they need a browser runtime asset composed
+ * from multiple bare specifiers but do not want to own temporary file assembly
+ * logic themselves. The generated file lives under the app work directory so
+ * repeated runs can reuse the same location without placing sources inside
+ * `node_modules`, which can cause bundlers to externalize bare imports.
+ */
+export function createBrowserRuntimeEntryModule(options) {
+    if (options.modules.some((module) => !module.specifier.startsWith('node:')) && !options.rootDir) {
+        throw new Error('createBrowserRuntimeEntryModule requires rootDir to resolve package specifiers');
     }
-    const exportNames = getModuleExportNames(module.specifier, requireFromRoot).filter(
-      (name) => !seenExports.has(name)
-    );
-    if (exportNames.length > 0) {
-      statements.push(`export { ${exportNames.join(", ")} } from '${importSpecifier}';`);
-      for (const exportName of exportNames) {
-        seenExports.add(exportName);
-      }
+    const rootDir = options.rootDir ?? process.cwd();
+    const workDir = options.workDir ?? path.join(rootDir, DEFAULT_ECOPAGES_WORK_DIR);
+    const artifactsDir = path.join(workDir, '.browser-runtime-entries', options.cacheDirName ?? 'ecopages-browser-runtime');
+    fs.mkdirSync(artifactsDir, { recursive: true });
+    const requireFromRoot = createRequire(path.join(rootDir, 'package.json'));
+    const seenExports = new Set();
+    const statements = [];
+    const filePath = path.join(artifactsDir, options.fileName);
+    const entryDir = path.dirname(filePath);
+    for (const module of options.modules) {
+        const importSpecifier = resolveBrowserRuntimeEntryImport({
+            specifier: module.specifier,
+            requireFromRoot,
+            entryDir,
+            rootDir,
+        });
+        if (module.defaultExport &&
+            inferBrowserRuntimeDefaultExportPolicy({ specifier: module.specifier, requireFromRoot, rootDir }) ===
+                'emit-default') {
+            statements.push(`import __ecopages_default_export__ from '${importSpecifier}';`);
+            statements.push('export default __ecopages_default_export__;');
+        }
+        const exportNames = listBrowserRuntimeModuleExportNames(module.specifier, requireFromRoot).filter((name) => !seenExports.has(name));
+        if (exportNames.length > 0) {
+            statements.push(`export { ${exportNames.join(', ')} } from '${importSpecifier}';`);
+            for (const exportName of exportNames) {
+                seenExports.add(exportName);
+            }
+        }
     }
-  }
-  const content = statements.join("\n");
-  if (!fs.existsSync(filePath) || fs.readFileSync(filePath, "utf-8") !== content) {
-    fs.writeFileSync(filePath, content, "utf-8");
-  }
-  return filePath;
-}
-function resolveEntryImportSpecifier(specifier, requireFromRoot, entryDir) {
-  if (specifier.startsWith("node:") || specifier.startsWith("file:")) {
-    return specifier;
-  }
-  const resolvedPath = requireFromRoot.resolve(specifier);
-  let relativePath = path.relative(entryDir, resolvedPath).replace(/\\/g, "/");
-  if (!relativePath.startsWith(".")) {
-    relativePath = `./${relativePath}`;
-  }
-  return relativePath;
-}
-function getModuleExportNames(specifier, requireFromRoot) {
-  const moduleExports = requireFromRoot(specifier);
-  return Object.keys(moduleExports).filter((name) => name !== "__esModule" && name !== "default").filter((name) => /^[$A-Z_a-z][$\w]*$/.test(name)).sort();
+    const content = statements.join('\n');
+    if (!fs.existsSync(filePath) || fs.readFileSync(filePath, 'utf-8') !== content) {
+        fs.writeFileSync(filePath, content, 'utf-8');
+    }
+    return filePath;
 }
-export {
-  createBrowserRuntimeEntryModule
-};

package/src/services/assets/asset-processing-service/finalize-processed-asset.d.ts

@@ -0,0 +1,3 @@
+import type { ProcessedAsset } from './assets.types.js';
+/** Applies the public source URL to one processed asset when available. */
+export declare function finalizeProcessedAsset(processed: ProcessedAsset, resolveProcessedAssetSrcUrl: (processed: ProcessedAsset) => string | undefined): ProcessedAsset;

package/src/services/assets/asset-processing-service/finalize-processed-asset.js

@@ -0,0 +1,5 @@
+/** Applies the public source URL to one processed asset when available. */
+export function finalizeProcessedAsset(processed, resolveProcessedAssetSrcUrl) {
+    const srcUrl = resolveProcessedAssetSrcUrl(processed);
+    return srcUrl ? { ...processed, srcUrl } : processed;
+}

package/src/services/assets/asset-processing-service/grouped-content-bundles.d.ts

@@ -1,4 +1,6 @@
 import type { AssetDefinition, ProcessedAsset } from './assets.types.js';
+/** Forces grouped content scripts to run through the bundler in production builds. */
+export declare function ensureGroupedContentScriptsBundle(dependencies: AssetDefinition[]): void;
 /**
  * Splits grouped content-script dependencies from ordinary dependencies so callers can
  * route them through `processGrouped` without changing ordering for the remaining assets.
@@ -12,7 +14,6 @@ type GroupedBundleProcessor = {
 };
 type ProcessGroupedDependencyBundlesOptions = {
     bundles: AssetDefinition[][];
-    key: string;
     getCachedAsset: (dep: AssetDefinition, depKey: string) => ProcessedAsset | null;
     getDependencyKey: (dep: AssetDefinition) => string;
     getGroupedProcessor: () => GroupedBundleProcessor | undefined;