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

package/src/build/{browser-runtime-plugin.d.ts → browser/browser-runtime-plugin.d.ts}

@@ -11,22 +11,16 @@
  * - `onLoad` for JS/TS files → AST-walking import/export rewrite against the
  *   manifest specifier set, with a `code.includes(specifier)` fast path
  *
- * The plugin object carries the manifest's `specifier → publicPath` map
- * under `BROWSER_RUNTIME_IMPORT_REWRITE_MAP` so
- * `collectBrowserRuntimeImportRewriteMap` and the post-build rewriter can
- * read it without re-walking the manifest.
- *
- * This is the single source of truth for browser-runtime plugin behavior.
- * Per-bundler bridges can treat it as a single plugin.
+ * The plugin object carries the manifest under `BROWSER_RUNTIME_MANIFEST` so
+ * post-build rewriters can resolve exact and subpath imports without rebuilding
+ * the map by hand.
  */
-import type { EcoBuildPlugin } from './build-types.js';
+import type { EcoBuildPlugin } from '../contracts/build-types.js';
 import { type BrowserRuntimeManifest } from './browser-runtime-manifest.js';
 /**
- * Symbol used to attach the manifest's `specifier → publicPath` map to a
- * plugin instance. Consumers read it via `getBrowserRuntimeImportRewriteMap`
- * or `collectBrowserRuntimeImportRewriteMap`.
+ * Symbol used to attach the browser-runtime manifest to a plugin instance.
  */
-export declare const BROWSER_RUNTIME_IMPORT_REWRITE_MAP: unique symbol;
+export declare const BROWSER_RUNTIME_MANIFEST: unique symbol;
 /**
  * Default name used by `createBrowserRuntimePlugin` when the caller
  * does not provide one.
@@ -63,8 +57,13 @@ export type CreateBrowserRuntimePluginOptions = {
  *
  * Exposed for the post-build rewriter and for tests.
  */
-export declare function rewriteBrowserRuntimeImports(code: string, specifierMap: ReadonlyMap<string, string>, filePath?: string): string;
+export declare function rewriteBrowserRuntimeImports(code: string, manifest: BrowserRuntimeManifest, filePath?: string): string;
+export declare function getBrowserRuntimeManifestFromPlugin(plugin: EcoBuildPlugin): BrowserRuntimeManifest | undefined;
+/**
+ * Returns the exact specifier → publicPath map derived from the plugin manifest.
+ */
 export declare function getBrowserRuntimeImportRewriteMap(plugin: EcoBuildPlugin): ReadonlyMap<string, string> | undefined;
+export declare function collectBrowserRuntimeManifests(plugins: EcoBuildPlugin[] | undefined): BrowserRuntimeManifest[];
 export declare function collectBrowserRuntimeImportRewriteMap(plugins: EcoBuildPlugin[] | undefined): ReadonlyMap<string, string>;
 /**
  * Creates a build plugin that exposes the union of browser-runtime

package/src/build/browser/browser-runtime-plugin.js

@@ -0,0 +1,218 @@
+/**
+ * Unified browser-runtime plugin factory.
+ *
+ * @remarks
+ * Single factory that exposes the union of behaviors for the browser
+ * runtime:
+ *
+ * - `onResolve` for manifest specifiers → mapped public URL, marked external
+ * - `onResolve` for paths starting with `/` whose target is in the manifest's
+ *   public path set → marked external
+ * - `onLoad` for JS/TS files → AST-walking import/export rewrite against the
+ *   manifest specifier set, with a `code.includes(specifier)` fast path
+ *
+ * The plugin object carries the manifest under `BROWSER_RUNTIME_MANIFEST` so
+ * post-build rewriters can resolve exact and subpath imports without rebuilding
+ * the map by hand.
+ */
+import path from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { parseModuleSource } from '../../cache/module-parse-cache.js';
+import { getBrowserRuntimeSpecifierMap, mergeBrowserRuntimeManifests, resolveBrowserRuntimePublicPath, } from './browser-runtime-manifest.js';
+import { buildSpecifierFilter } from './browser-runtime-plugin-helpers.js';
+/**
+ * Symbol used to attach the browser-runtime manifest to a plugin instance.
+ */
+export const BROWSER_RUNTIME_MANIFEST = Symbol.for('ecopages.browserRuntimeManifest');
+/**
+ * Default name used by `createBrowserRuntimePlugin` when the caller
+ * does not provide one.
+ */
+export const DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME = 'browser-runtime-plugin';
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object';
+}
+function inferLoaderFromPath(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    switch (extension) {
+        case '.mts':
+        case '.cts':
+        case '.ts':
+            return 'ts';
+        case '.tsx':
+            return 'tsx';
+        case '.jsx':
+            return 'jsx';
+        default:
+            return 'js';
+    }
+}
+function queueReplacement(options) {
+    if (!isRecord(options.source) || typeof options.source.value !== 'string') {
+        return;
+    }
+    const mappedPath = resolveBrowserRuntimePublicPath(options.source.value, options.manifest);
+    if (!mappedPath || typeof options.source.start !== 'number' || typeof options.source.end !== 'number') {
+        return;
+    }
+    const quote = options.code[options.source.start] === "'" ? "'" : '"';
+    options.edits.push({
+        start: options.source.start,
+        end: options.source.end,
+        replacement: `${quote}${mappedPath}${quote}`,
+    });
+}
+/**
+ * Rewrites static ESM import/export specifiers and string-literal dynamic imports
+ * from manifest-owned runtime specifiers to concrete browser public URLs.
+ *
+ * Exposed for the post-build rewriter and for tests.
+ */
+export function rewriteBrowserRuntimeImports(code, manifest, filePath = 'browser-runtime-imports.js') {
+    if (manifest.assets.length === 0) {
+        return code;
+    }
+    const edits = [];
+    try {
+        const result = parseModuleSource(filePath, code);
+        const walk = (node) => {
+            if (!isRecord(node)) {
+                return;
+            }
+            if (node.type === 'ImportDeclaration' ||
+                node.type === 'ExportNamedDeclaration' ||
+                node.type === 'ExportAllDeclaration') {
+                queueReplacement({ code, source: node.source, manifest, edits });
+            }
+            if (node.type === 'ImportExpression' && isRecord(node.source)) {
+                if (node.source.type === 'StringLiteral' || node.source.type === 'Literal') {
+                    queueReplacement({ code, source: node.source, manifest, edits });
+                }
+            }
+            for (const value of Object.values(node)) {
+                if (Array.isArray(value)) {
+                    for (const child of value) {
+                        walk(child);
+                    }
+                }
+                else {
+                    walk(value);
+                }
+            }
+        };
+        walk(result.program);
+    }
+    catch {
+        return code;
+    }
+    if (edits.length === 0) {
+        return code;
+    }
+    edits.sort((left, right) => right.start - left.start);
+    let rewritten = code;
+    for (const edit of edits) {
+        rewritten = rewritten.slice(0, edit.start) + edit.replacement + rewritten.slice(edit.end);
+    }
+    return rewritten;
+}
+function importMightReferenceRuntimeRoots(code, rootSpecifiers) {
+    return rootSpecifiers.some((specifier) => code.includes(specifier));
+}
+export function getBrowserRuntimeManifestFromPlugin(plugin) {
+    return plugin[BROWSER_RUNTIME_MANIFEST];
+}
+/**
+ * Returns the exact specifier → publicPath map derived from the plugin manifest.
+ */
+export function getBrowserRuntimeImportRewriteMap(plugin) {
+    const manifest = getBrowserRuntimeManifestFromPlugin(plugin);
+    return manifest ? getBrowserRuntimeSpecifierMap(manifest) : undefined;
+}
+export function collectBrowserRuntimeManifests(plugins) {
+    const manifests = [];
+    for (const plugin of plugins ?? []) {
+        const manifest = getBrowserRuntimeManifestFromPlugin(plugin);
+        if (manifest) {
+            manifests.push(manifest);
+        }
+    }
+    return manifests;
+}
+export function collectBrowserRuntimeImportRewriteMap(plugins) {
+    return getBrowserRuntimeSpecifierMap(mergeBrowserRuntimeManifests(...collectBrowserRuntimeManifests(plugins)));
+}
+/**
+ * Creates a build plugin that exposes the union of browser-runtime
+ * manifest behaviors (alias resolution, public-path matching, and source
+ * import/export rewrite). See {@link CreateBrowserRuntimePluginOptions}
+ * for per-behavior toggles.
+ *
+ * Returns `null` for an empty manifest so callers can short-circuit
+ * registration without sprinkling `if (plugin)` everywhere.
+ */
+export function createBrowserRuntimePlugin(options) {
+    const { manifest } = options;
+    const specifierMap = getBrowserRuntimeSpecifierMap(manifest);
+    const specifierFilter = buildSpecifierFilter(specifierMap);
+    if (!specifierFilter) {
+        return null;
+    }
+    const external = options.external ?? true;
+    const rewriteImports = options.rewriteImports ?? true;
+    const matchPublicPaths = options.matchPublicPaths ?? true;
+    const publicPathSet = new Set(specifierMap.values());
+    const rootSpecifiers = manifest.assets.map((asset) => asset.specifier);
+    const plugin = {
+        name: options.name ?? DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME,
+        setup(build) {
+            build.onResolve({ filter: specifierFilter }, (args) => {
+                const mappedPath = resolveBrowserRuntimePublicPath(args.path, manifest);
+                if (!mappedPath) {
+                    return undefined;
+                }
+                return {
+                    path: mappedPath,
+                    external,
+                };
+            });
+            if (matchPublicPaths) {
+                build.onResolve({ filter: /^\// }, (args) => {
+                    if (!publicPathSet.has(args.path)) {
+                        return undefined;
+                    }
+                    return {
+                        path: args.path,
+                        external: true,
+                    };
+                });
+            }
+            if (rewriteImports) {
+                build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, (args) => {
+                    if (!path.isAbsolute(args.path) || !existsSync(args.path)) {
+                        return undefined;
+                    }
+                    const code = readFileSync(args.path, 'utf-8');
+                    /**
+                     * Fast-path optimization: skip AST parsing for files that don't contain
+                     * any manifest-owned specifiers. This avoids expensive oxc-parser calls
+                     * on every JS/TS file in the dependency graph.
+                     */
+                    if (!importMightReferenceRuntimeRoots(code, rootSpecifiers)) {
+                        return undefined;
+                    }
+                    const rewritten = rewriteBrowserRuntimeImports(code, manifest, args.path);
+                    if (rewritten === code) {
+                        return undefined;
+                    }
+                    return {
+                        contents: rewritten,
+                        loader: inferLoaderFromPath(args.path),
+                        resolveDir: path.dirname(args.path),
+                    };
+                });
+            }
+        },
+    };
+    plugin[BROWSER_RUNTIME_MANIFEST] = manifest;
+    return plugin;
+}

package/src/build/browser/jsx-ownership-plugins.d.ts

@@ -0,0 +1,24 @@
+import type { EcoBuildPlugin } from '../contracts/build-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+/**
+ * Foreign JSX override plugins for mixed-integration app builds.
+ *
+ * Each plugin rewrites files for one `(integration, extension)` pair with that
+ * integration's own `@jsxImportSource` so the bundler preserves the owning JSX
+ * runtime for native extension ownership.
+ *
+ * Extensions are sorted longest-first so `.page.react.tsx` wins over `.tsx`.
+ */
+export declare function getJsxOwnershipPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
+/**
+ * Host-scoped JSX override plugins for one integration's client bundle graph.
+ *
+ * When a host integration (for example React) bundles foreign `.tsx` files, those
+ * files must compile with the host JSX runtime instead of the project default.
+ * Use this helper for host-owned client bundles. For app-wide transpilation that
+ * should preserve each integration's native JSX runtime, use
+ * {@link getJsxOwnershipPlugins} instead.
+ */
+export declare function getHostScopedJsxOwnershipPlugins(appConfig: EcoPagesAppConfig, hostIntegrationName: string, options?: {
+    name?: string;
+}): EcoBuildPlugin[];

package/src/build/browser/jsx-ownership-plugins.js

@@ -0,0 +1,55 @@
+import { createForeignJsxOverridePlugin } from '../../plugins/foreign-jsx-override-plugin.js';
+import { collectJsxExtensions, filterJsxSourceExtensions } from '../../plugins/jsx-import-source.utils.js';
+function collectJsxExtensionEntries(appConfig) {
+    return (appConfig.integrations ?? [])
+        .filter((integration) => integration.jsxImportSource)
+        .flatMap((integration) => filterJsxSourceExtensions(integration.extensions).map((extension) => ({ integration, extension })))
+        .sort((left, right) => right.extension.length - left.extension.length);
+}
+/**
+ * Foreign JSX override plugins for mixed-integration app builds.
+ *
+ * Each plugin rewrites files for one `(integration, extension)` pair with that
+ * integration's own `@jsxImportSource` so the bundler preserves the owning JSX
+ * runtime for native extension ownership.
+ *
+ * Extensions are sorted longest-first so `.page.react.tsx` wins over `.tsx`.
+ */
+export function getJsxOwnershipPlugins(appConfig) {
+    const jsxExtensions = collectJsxExtensionEntries(appConfig);
+    return jsxExtensions.map(({ integration, extension }) => createForeignJsxOverridePlugin({
+        hostJsxImportSource: integration.jsxImportSource,
+        foreignExtensions: [extension],
+        excludeExtensions: jsxExtensions
+            .filter((candidate) => candidate.extension.length > extension.length)
+            .filter((candidate) => candidate.extension.endsWith(extension))
+            .map((candidate) => candidate.extension),
+        name: `ecopages-jsx-ownership-${integration.name}-${extension.replace(/[^a-zA-Z0-9]+/g, '-')}`,
+    }));
+}
+/**
+ * Host-scoped JSX override plugins for one integration's client bundle graph.
+ *
+ * When a host integration (for example React) bundles foreign `.tsx` files, those
+ * files must compile with the host JSX runtime instead of the project default.
+ * Use this helper for host-owned client bundles. For app-wide transpilation that
+ * should preserve each integration's native JSX runtime, use
+ * {@link getJsxOwnershipPlugins} instead.
+ */
+export function getHostScopedJsxOwnershipPlugins(appConfig, hostIntegrationName, options) {
+    const hostIntegration = (appConfig.integrations ?? []).find((integration) => integration.name === hostIntegrationName);
+    const hostJsxImportSource = hostIntegration?.jsxImportSource;
+    if (!hostJsxImportSource) {
+        return [];
+    }
+    const foreignExtensions = collectJsxExtensions(appConfig.integrations ?? [], {
+        excludeIntegrationName: hostIntegrationName,
+    });
+    return [
+        createForeignJsxOverridePlugin({
+            name: options?.name ?? `ecopages-jsx-ownership-host-${hostIntegrationName}`,
+            hostJsxImportSource,
+            foreignExtensions,
+        }),
+    ];
+}

package/src/build/browser/lit-static-render-worker-context.d.ts

@@ -0,0 +1,2 @@
+/** Returns whether the current thread is the Lit static-render worker. */
+export declare function isLitStaticRenderWorkerThread(): boolean;

package/src/build/browser/lit-static-render-worker-context.js

@@ -0,0 +1,4 @@
+/** Returns whether the current thread is the Lit static-render worker. */
+export function isLitStaticRenderWorkerThread() {
+    return process.env.ECOPAGES_LIT_STATIC_RENDER_WORKER === 'true';
+}