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

package/src/build/rolldown/rolldown-adapter-helpers.js

@@ -0,0 +1,458 @@
+/**
+ * Shared helpers for the Rolldown-backed build adapters.
+ *
+ * @remarks
+ * The standard {@link RolldownBuildAdapter} uses these helpers for
+ * BuildOptions → Rolldown mapping, dependency-graph extraction, and the
+ * post-build rewriting pipeline.
+ *
+ * @module
+ */
+import { builtinModules, createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { isBarePackageImportSpecifier } from '../../plugins/tsconfig-import-resolver.js';
+import { collectBrowserRuntimeImportRewriteMap, rewriteBrowserRuntimeImports, } from '../browser/browser-runtime-plugin.js';
+import { createServerSideCssShimPlugin } from './server-side-css-shim-plugin.js';
+import { createRolldownPluginBridge } from './rolldown-plugin-bridge.js';
+import { isDeclaredAppPackageImport, isWorkspacePackageImport, normalizeNodeRuntimeBuildOutputs, } from './runtime-build-output-normalizer.js';
+const corePackageRequire = createRequire(new URL('../../../package.json', import.meta.url));
+const nodeBuiltinSpecifiers = new Set(builtinModules);
+let corePackageNames;
+/**
+ * Returns the set of packages declared as direct dependencies in core's own
+ * `package.json` (all dependency fields combined).
+ *
+ * @remarks
+ * Result is cached for the lifetime of the process. This is safe because
+ * core's own package.json does not change at runtime.
+ */
+function getCorePackageNames() {
+    if (corePackageNames) {
+        return corePackageNames;
+    }
+    const packageJsonPath = new URL('../../../package.json', import.meta.url);
+    corePackageNames = new Set();
+    try {
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+        for (const field of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+            const entries = packageJson[field];
+            if (!entries || typeof entries !== 'object') {
+                continue;
+            }
+            for (const name of Object.keys(entries)) {
+                corePackageNames.add(name);
+            }
+        }
+    }
+    catch {
+        // Return empty set on read/parse failure; packages will be bundled.
+    }
+    return corePackageNames;
+}
+function isCoreDeclaredPackageImport(specifier) {
+    const name = specifier.startsWith('@')
+        ? specifier.split('/').slice(0, 2).join('/')
+        : (specifier.split('/')[0] ?? specifier);
+    return getCorePackageNames().has(name);
+}
+export function transpileProfileToOptions(profile) {
+    switch (profile) {
+        case 'browser-script':
+        case 'hmr-runtime':
+        case 'hmr-entrypoint':
+            return {
+                target: 'browser',
+                format: 'esm',
+                sourcemap: 'none',
+            };
+    }
+}
+function isPackageImport(id, contextRoot) {
+    return isBarePackageImportSpecifier(id, contextRoot);
+}
+function tryResolveModule(id, resolver) {
+    try {
+        return resolver.resolve(id);
+    }
+    catch {
+        return undefined;
+    }
+}
+function getAppRootRequire(cache, contextRoot) {
+    const cacheKey = path.resolve(contextRoot);
+    let req = cache.get(cacheKey);
+    if (!req) {
+        req = createRequire(path.join(cacheKey, 'package.json'));
+        cache.set(cacheKey, req);
+    }
+    return req;
+}
+/**
+ * Determines whether a package import should be bundled into the output
+ * rather than left as an external bare specifier.
+ *
+ * @remarks
+ * Resolution is evaluated in three tiers:
+ *
+ * 1. **Workspace packages** (`workspace:` protocol) — always bundled; they
+ *    are source-only and cannot be resolved by Node.js at runtime.
+ * 2. **App-declared packages** — bundled only when their resolved entry is a
+ *    TypeScript or JSX file (source packages); pre-compiled packages are left
+ *    external so the app's own resolver handles them at runtime.
+ * 3. **Everything else** (undeclared transitives) — split into two sub-cases:
+ *    - A **direct dependency of core** that resolves to a compiled JS file
+ *      (e.g. `oxc-parser`, `rolldown`, `ws`): externalized so the
+ *      `runtime-build-output-normalizer` can rewrite the import to an
+ *      absolute `file://` URL after the build. "Direct" means declared in
+ *      core's own `package.json`; transitives that merely *resolve through*
+ *      core's `require` are excluded.
+ *    - **Everything else** (true transitives like `lexical`, `@lexical/react`):
+ *      bundled unconditionally. pnpm strict hoisting means these packages
+ *      are unreachable as bare specifiers from output directories such as
+ *      `.eco/`, `.server-route-modules/`, or `dist/.server/`.
+ *
+ * @param id - The package specifier (e.g., `@scope/pkg/subpath`).
+ * @param contextRoot - The root directory of the app being built.
+ * @param appRootRequireCache - Cache of `require` instances per context root.
+ * @returns `true` if the import should be bundled, `false` to externalize.
+ */
+function shouldBundlePackageImport(id, contextRoot, appRootRequireCache) {
+    if (isWorkspacePackageImport(id, contextRoot)) {
+        return true;
+    }
+    if (isDeclaredAppPackageImport(id, contextRoot)) {
+        const appRootRequire = getAppRootRequire(appRootRequireCache, contextRoot);
+        const appResolvedPath = tryResolveModule(id, appRootRequire);
+        return Boolean(appResolvedPath && /\.(?:[cm]?ts|tsx|jsx)$/u.test(appResolvedPath));
+    }
+    if (isCoreDeclaredPackageImport(id)) {
+        const coreResolvedPath = tryResolveModule(id, corePackageRequire);
+        if (coreResolvedPath && !/\.(?:[cm]?ts|tsx|jsx)$/u.test(coreResolvedPath)) {
+            return false;
+        }
+    }
+    return true;
+}
+function createExternalMatcher(options, appRootRequireCache) {
+    const explicitExternals = new Set(options.external ?? []);
+    const externalPackages = options.externalPackages === true;
+    const contextRoot = options.root ? path.resolve(options.root) : process.cwd();
+    return (id) => {
+        if (explicitExternals.has(id)) {
+            return true;
+        }
+        if (!externalPackages || !isPackageImport(id, contextRoot)) {
+            return false;
+        }
+        return !shouldBundlePackageImport(id, contextRoot, appRootRequireCache);
+    };
+}
+function isNodeBuiltinSpecifier(id) {
+    return id.startsWith('node:') || nodeBuiltinSpecifiers.has(id);
+}
+/**
+ * Resolves Node builtins as external before Rolldown falls back to file resolution.
+ *
+ * @remarks
+ * Rolldown documents two first-class externalization points: its `external`
+ * option is checked before resolution, and a plugin `resolveId` hook can return
+ * `{ id, external: true }`. Core uses the latter to keep Node-builtin ownership
+ * explicit in the Node-target plugin pipeline.
+ *
+ * The hook runs before Rolldown's internal filesystem resolver, leaving imports
+ * such as `node:fs` intact for the Node runtime. It is installed only for
+ * Node-target builds, so browser bundles still surface accidental Node builtin
+ * imports as resolver failures.
+ *
+ * See {@link https://rolldown.rs/in-depth/external-modules | Rolldown external modules}.
+ */
+export function createNodeBuiltinExternalPlugin() {
+    return {
+        name: 'ecopages-node-builtin-external',
+        resolveId(id) {
+            return isNodeBuiltinSpecifier(id) ? { id, external: true } : null;
+        },
+    };
+}
+/**
+ * Rejects Node builtins in browser-target builds before Rolldown externalizes them.
+ *
+ * @remarks
+ * With `platform: 'browser'`, Rolldown leaves `node:*` imports in the output as
+ * bare specifiers. This plugin fails the build instead so server-only graphs
+ * cannot reach the browser as silent CORS errors.
+ */
+export function createBrowserNodeBuiltinGuardPlugin() {
+    return {
+        name: 'ecopages-browser-node-builtin-guard',
+        resolveId(id, importer) {
+            if (!isNodeBuiltinSpecifier(id)) {
+                return null;
+            }
+            const from = importer ? ` (imported from ${importer})` : '';
+            throw new Error(`[browser-build] Node builtin "${id}" cannot be bundled for the browser${from}. ` +
+                `Check package "browser" exports and the client-graph boundary for the importer.`);
+        },
+    };
+}
+function mapRolldownFormat(value) {
+    switch (value) {
+        case 'cjs':
+            return 'cjs';
+        case 'iife':
+            return 'iife';
+        default:
+            return 'esm';
+    }
+}
+function mapRolldownPlatform(value) {
+    if (value === 'browser')
+        return 'browser';
+    if (value === 'node')
+        return 'node';
+    if (value && /^(?:es\d+|chrome\d+|edge\d+|firefox\d+|safari\d+|hermes|deno\d+|ios\d+)$/.test(value)) {
+        return 'node';
+    }
+    return 'neutral';
+}
+function mapRolldownSourcemap(value) {
+    switch (value) {
+        case 'none':
+            return false;
+        case 'inline':
+            return 'inline';
+        case 'external':
+        case 'linked':
+            return 'hidden';
+        default:
+            return true;
+    }
+}
+function mapRolldownJsx(jsx) {
+    const { factory, fragment, ...rest } = jsx;
+    const out = { ...rest };
+    if (factory !== undefined) {
+        out.pragma = factory;
+    }
+    if (fragment !== undefined) {
+        out.pragmaFrag = fragment;
+    }
+    return out;
+}
+function toEntryFileNamesPattern(value) {
+    if (!value) {
+        return undefined;
+    }
+    const literal = !/\[[^\]]+\]/u.test(value);
+    const stripped = value.replaceAll(/\.?\[ext\]/g, '');
+    if (stripped.length === 0) {
+        return undefined;
+    }
+    return { pattern: stripped, literal };
+}
+function getJavaScriptOutExtension(options, literal) {
+    if (literal) {
+        return undefined;
+    }
+    if (options.target === 'browser') {
+        return '.js';
+    }
+    if (options.format === 'cjs') {
+        return '.cjs';
+    }
+    return '.mjs';
+}
+function normalizeOutputPath(outputPath, outdir) {
+    return path.isAbsolute(outputPath) ? path.normalize(outputPath) : path.normalize(path.join(outdir, outputPath));
+}
+function normalizeModulePath(modulePath, contextRoot) {
+    return path.isAbsolute(modulePath)
+        ? path.normalize(modulePath)
+        : path.normalize(path.resolve(contextRoot, modulePath));
+}
+export function extractDependencyGraph(chunks, contextRoot) {
+    const entrypoints = {};
+    for (const chunk of chunks) {
+        if (!chunk.facadeModuleId) {
+            continue;
+        }
+        const entrypointPath = normalizeModulePath(chunk.facadeModuleId, contextRoot);
+        entrypoints[entrypointPath] = Array.from(new Set([entrypointPath, ...chunk.moduleIds.map((id) => normalizeModulePath(id, contextRoot))]));
+    }
+    return { entrypoints };
+}
+export function toBuildLogs(error) {
+    if (error instanceof Error) {
+        return [{ message: error.message }];
+    }
+    return [{ message: 'Unknown build error' }];
+}
+/**
+ * Translates a {@link BuildOptions} into Rolldown's `InputOptions` and
+ * `OutputOptions`. Always sets `experimental.nativeMagicString: true`
+ * and always consolidates eco plugins via the bridge.
+ */
+export function resolveRolldownOptions(options, contextRoot, outdir, appRootRequireCache) {
+    const rolldownPlatform = mapRolldownPlatform(options.target);
+    const external = createExternalMatcher(options, appRootRequireCache);
+    const transformOptions = {};
+    if (options.define) {
+        transformOptions.define = options.define;
+    }
+    if (options.jsx) {
+        transformOptions.jsx = mapRolldownJsx(options.jsx);
+    }
+    if (options.target && /^(?:es|chrome|edge|firefox|safari|hermes|deno|ios)/.test(options.target)) {
+        transformOptions.target = options.target;
+    }
+    const bundlePlugins = options.plugins ?? [];
+    const sourceTransforms = options.sourceTransforms ?? [];
+    const appPlugins = createRolldownPluginBridge(bundlePlugins, contextRoot, sourceTransforms);
+    const allPlugins = [
+        ...(rolldownPlatform === 'node' ? [createNodeBuiltinExternalPlugin()] : []),
+        ...(rolldownPlatform === 'browser' ? [createBrowserNodeBuiltinGuardPlugin()] : []),
+        ...(options.target !== 'browser' ? [createServerSideCssShimPlugin()] : []),
+        ...appPlugins,
+    ];
+    const inputOptions = {
+        input: options.entrypoints,
+        cwd: contextRoot,
+        external,
+        platform: mapRolldownPlatform(options.target),
+        transform: Object.keys(transformOptions).length > 0 ? transformOptions : undefined,
+        resolve: options.conditions ? { conditionNames: options.conditions } : undefined,
+        treeshake: typeof options.treeshaking === 'boolean' ? options.treeshaking : true,
+        ...(process.env.ECOPAGES_PROFILE_BUILD === '1'
+            ? {}
+            : {
+                checks: {
+                    pluginTimings: false,
+                },
+            }),
+        experimental: {
+            nativeMagicString: true,
+        },
+        plugins: allPlugins,
+    };
+    const entryFileNames = toEntryFileNamesPattern(options.naming);
+    const jsExtension = getJavaScriptOutExtension(options, entryFileNames?.literal ?? false);
+    const finalEntryFileNames = entryFileNames
+        ? jsExtension
+            ? `${entryFileNames.pattern}${jsExtension}`
+            : entryFileNames.pattern
+        : jsExtension
+            ? `[name]${jsExtension}`
+            : '[name]';
+    const entrypointCount = Array.isArray(options.entrypoints)
+        ? options.entrypoints.length
+        : Object.keys(options.entrypoints).length;
+    const disableCodeSplitting = options.splitting === false && entrypointCount === 1;
+    const outputOptions = {
+        dir: outdir,
+        format: mapRolldownFormat(options.format),
+        minify: !!options.minify,
+        entryFileNames: finalEntryFileNames,
+        chunkFileNames: '[name]-[hash].js',
+        assetFileNames: '[name]-[hash][extname]',
+        sourcemap: mapRolldownSourcemap(options.sourcemap),
+        ...(disableCodeSplitting ? { codeSplitting: false } : {}),
+    };
+    return { inputOptions, outputOptions };
+}
+/**
+ * Rewrites manifest-owned runtime specifiers in emitted JS output
+ * files. Skips work when the specifier map is empty or when a
+ * `(specifierMap, path, content)` tuple was already seen.
+ *
+ * The content cache is module-level and is keyed on a djb2 hash of
+ * the input bytes plus a sorted fingerprint of the specifier map. A
+ * manifest change correctly invalidates prior entries; different
+ * content of the same length does not collide.
+ */
+export function rewriteBrowserRuntimeImportsInOutputs(result, contextRoot, plugins) {
+    if (!result.success || result.outputs.length === 0) {
+        return result;
+    }
+    const specifierMap = collectBrowserRuntimeImportRewriteMap(plugins);
+    if (specifierMap.size === 0) {
+        return result;
+    }
+    const moduleRequireFromContext = createRequire(path.join(contextRoot, 'package.json'));
+    const fs = moduleRequireFromContext('node:fs');
+    const cacheFingerprint = `${Array.from(specifierMap.entries()).sort().join('|')}`;
+    for (const output of result.outputs) {
+        if (!/\.(?:[cm]?js)$/u.test(output.path)) {
+            continue;
+        }
+        const code = fs.readFileSync(output.path, 'utf-8');
+        const contentKey = `${cacheFingerprint}::${output.path}::${djb2(code)}`;
+        if (rewriteCache.has(contentKey)) {
+            continue;
+        }
+        const rewritten = rewriteBrowserRuntimeImports(code, specifierMap, output.path);
+        if (rewritten !== code) {
+            fs.writeFileSync(output.path, rewritten);
+        }
+        rememberRewrite(contentKey);
+    }
+    return result;
+}
+const REWRITE_CACHE_MAX_ENTRIES = 2048;
+const rewriteCache = new Set();
+/**
+ * @remarks
+ * Dev rebuilds hit the same output paths with stable specifier maps; memoizing
+ * skips re-reading and re-writing unchanged files. The cache is capped because
+ * a process-global set would otherwise grow for the lifetime of a watch session.
+ * Eviction uses insertion order as an approximate LRU.
+ */
+function rememberRewrite(contentKey) {
+    rewriteCache.add(contentKey);
+    if (rewriteCache.size > REWRITE_CACHE_MAX_ENTRIES) {
+        const oldest = rewriteCache.values().next().value;
+        if (oldest !== undefined) {
+            rewriteCache.delete(oldest);
+        }
+    }
+}
+function djb2(input) {
+    let hash = 5381;
+    for (let i = 0; i < input.length; i++) {
+        hash = ((hash << 5) + hash + input.charCodeAt(i)) | 0;
+    }
+    return hash.toString(36);
+}
+/** Test-only: clears the rewriter content cache. */
+export function clearRewriteCacheForTests() {
+    rewriteCache.clear();
+}
+/** Normalizes node-runtime import paths in emitted outputs. */
+export function rewriteNodeRuntimeImportsInOutputs(result, contextRoot) {
+    if (!result.success || result.outputs.length === 0) {
+        return result;
+    }
+    normalizeNodeRuntimeBuildOutputs(result.outputs.map((output) => output.path), contextRoot);
+    return result;
+}
+/** Maps a Rolldown `output` to a normalized {@link BuildResult}. */
+export function buildResultFromRolldownOutput(output, outdir, contextRoot) {
+    const outputs = output.output.map((entry) => ({
+        path: normalizeOutputPath(entry.fileName, outdir),
+    }));
+    const entryChunks = output.output.filter((entry) => entry.type === 'chunk' && entry.isEntry);
+    const dependencyGraph = entryChunks.length > 0 ? extractDependencyGraph(entryChunks, contextRoot) : undefined;
+    const entryOutputs = {};
+    for (const chunk of entryChunks) {
+        if (chunk.facadeModuleId) {
+            entryOutputs[normalizeModulePath(chunk.facadeModuleId, contextRoot)] = normalizeOutputPath(chunk.fileName, outdir);
+        }
+    }
+    return {
+        success: true,
+        logs: [],
+        outputs,
+        dependencyGraph,
+        entryOutputs: entryChunks.length > 0 ? entryOutputs : undefined,
+    };
+}

package/src/build/{rolldown-build-adapter.d.ts → rolldown/rolldown-build-adapter.d.ts}

@@ -6,19 +6,15 @@
  * default adapter installed by `ConfigBuilder` and the adapter that
  * issues real builds in production.
  *
- * Each `build()` creates a fresh `rolldown()` bundler, so there is no
- * module-graph reuse across calls. For HMR/watch mode where the same
- * entrypoints are rebuilt repeatedly, see {@link RolldownDevBuildAdapter}.
+ * Each `build()` creates a fresh `rolldown()` bundler.
  */
-import type { BuildAdapter, BuildOptions, BuildResult, BuildTranspileOptions, BuildTranspileProfile } from './build-adapter.js';
+import type { BuildAdapter, BuildOptions, BuildResult, BuildTranspileOptions, BuildTranspileProfile } from '../build-adapter.js';
 export declare class RolldownBuildAdapter implements BuildAdapter {
     readonly ownership: "rolldown";
     /** Per-adapter require cache, keyed on resolved context root. */
     private readonly appRootRequireCache;
     /**
-     * Issues one build. Creates a fresh `rolldown()` bundler per call,
-     * so no module-graph reuse. For repeated rebuilds on the same
-     * entrypoints, use {@link RolldownDevBuildAdapter}.
+     * Issues one build. Creates a fresh `rolldown()` bundler per call.
      */
     buildOrThrow(options: BuildOptions): Promise<BuildResult>;
     build(options: BuildOptions): Promise<BuildResult>;

package/src/build/rolldown/rolldown-build-adapter.js

@@ -0,0 +1,57 @@
+/**
+ * Bundler-backed build adapter.
+ *
+ * @remarks
+ * Implements {@link BuildAdapter} on top of Rolldown. This is the
+ * default adapter installed by `ConfigBuilder` and the adapter that
+ * issues real builds in production.
+ *
+ * Each `build()` creates a fresh `rolldown()` bundler.
+ */
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { rolldown } from 'rolldown';
+import { buildResultFromRolldownOutput, resolveRolldownOptions, rewriteBrowserRuntimeImportsInOutputs, rewriteNodeRuntimeImportsInOutputs, toBuildLogs, transpileProfileToOptions, } from './rolldown-adapter-helpers.js';
+import { recordRolldownBuildInvocation } from './rolldown-build-invocation-metrics.js';
+const moduleRequire = createRequire(import.meta.url);
+export class RolldownBuildAdapter {
+    ownership = 'rolldown';
+    /** Per-adapter require cache, keyed on resolved context root. */
+    appRootRequireCache = new Map();
+    /**
+     * Issues one build. Creates a fresh `rolldown()` bundler per call.
+     */
+    async buildOrThrow(options) {
+        recordRolldownBuildInvocation('rolldown');
+        const contextRoot = options.root ? path.resolve(options.root) : process.cwd();
+        const outdir = path.resolve(options.outdir ?? 'dist/assets');
+        const plugins = options.plugins ?? [];
+        const { inputOptions, outputOptions } = resolveRolldownOptions(options, contextRoot, outdir, this.appRootRequireCache);
+        const bundle = await rolldown(inputOptions);
+        const output = await bundle.write(outputOptions);
+        await bundle.close();
+        const baseResult = buildResultFromRolldownOutput(output, outdir, contextRoot);
+        return rewriteNodeRuntimeImportsInOutputs(rewriteBrowserRuntimeImportsInOutputs(baseResult, contextRoot, plugins), contextRoot);
+    }
+    async build(options) {
+        try {
+            return await this.buildOrThrow(options);
+        }
+        catch (error) {
+            return {
+                success: false,
+                logs: toBuildLogs(error),
+                outputs: [],
+            };
+        }
+    }
+    resolve(importPath, rootDir) {
+        return moduleRequire.resolve(importPath, { paths: [rootDir] });
+    }
+    getTranspileOptions(profile) {
+        return transpileProfileToOptions(profile);
+    }
+}
+export function createRolldownBuildAdapter() {
+    return new RolldownBuildAdapter();
+}

package/src/build/rolldown/rolldown-build-invocation-metrics.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Process-wide Rolldown build invocation counters for benchmarks and spikes.
+ *
+ * Gated behind {@link isRolldownBuildMetricsEnabled} so production paths stay quiet.
+ */
+export declare function isRolldownBuildMetricsEnabled(): boolean;
+export declare function recordRolldownBuildInvocation(adapter?: 'rolldown'): void;
+export declare function getRolldownBuildInvocationCounts(): Readonly<Record<string, number>>;
+export declare function resetRolldownBuildInvocationCounts(): void;
+export declare function recordPageModuleBuildInvocation(): void;
+export declare function getPageModuleRolldownBuildInvocations(): number;
+export declare function getTotalRolldownBuildInvocations(): number;

package/src/build/rolldown/rolldown-build-invocation-metrics.js

@@ -0,0 +1,39 @@
+/**
+ * Process-wide Rolldown build invocation counters for benchmarks and spikes.
+ *
+ * Gated behind {@link isRolldownBuildMetricsEnabled} so production paths stay quiet.
+ */
+const invocationCounts = new Map();
+let pageModuleBuildInvocations = 0;
+export function isRolldownBuildMetricsEnabled() {
+    return process.env.ECOPAGES_ROLLDOWN_BUILD_METRICS === '1' || process.env.ECOPAGES_LOGGER_DEBUG === 'true';
+}
+export function recordRolldownBuildInvocation(adapter = 'rolldown') {
+    if (!isRolldownBuildMetricsEnabled()) {
+        return;
+    }
+    invocationCounts.set(adapter, (invocationCounts.get(adapter) ?? 0) + 1);
+}
+export function getRolldownBuildInvocationCounts() {
+    return Object.fromEntries(invocationCounts);
+}
+export function resetRolldownBuildInvocationCounts() {
+    invocationCounts.clear();
+    pageModuleBuildInvocations = 0;
+}
+export function recordPageModuleBuildInvocation() {
+    if (!isRolldownBuildMetricsEnabled()) {
+        return;
+    }
+    pageModuleBuildInvocations += 1;
+}
+export function getPageModuleRolldownBuildInvocations() {
+    return pageModuleBuildInvocations;
+}
+export function getTotalRolldownBuildInvocations() {
+    let total = 0;
+    for (const count of invocationCounts.values()) {
+        total += count;
+    }
+    return total;
+}

package/src/build/{rolldown-plugin-bridge.d.ts → rolldown/rolldown-plugin-bridge.d.ts}

@@ -40,7 +40,8 @@
  * on every source file.
  */
 import type { Plugin } from 'rolldown';
-import type { EcoBuildPlugin } from './build-types.js';
+import type { EcoSourceTransform } from '../../plugins/source-transform.js';
+import type { EcoBuildPlugin } from '../contracts/build-types.js';
 /**
  * Creates a Rolldown `Plugin` array that drives the supplied
  * `EcoBuildPlugin` instances.
@@ -55,5 +56,18 @@ import type { EcoBuildPlugin } from './build-types.js';
  * Plugin ordering is preserved: registrations from earlier eco plugins
  * are checked before registrations from later ones, matching the
  * original per-plugin priority semantics.
+ *
+ * @remarks
+ * Rolldown re-fires `buildStart` on each build, so registrations and the
+ * virtual-module counter are cleared before every `setup` pass — otherwise
+ * handlers accumulate when bridge plugins are reused.
+ *
+ * @param plugins - `EcoBuildPlugin` instances registered for this build.
+ * @param contextRoot - Project root used to resolve relative load paths.
+ * @param sourceTransforms - Optional app-owned transforms applied after a matching
+ * `onLoad` handler returns module contents. Browser builds pass
+ * {@link getAppSourceTransforms | app source transforms} here so metadata injection
+ * still runs on output rewritten by boundary/runtime plugins. Virtual modules,
+ * CSS, and asset loads are skipped.
  */
-export declare function createRolldownPluginBridge(plugins: EcoBuildPlugin[], contextRoot: string): Plugin[];
+export declare function createRolldownPluginBridge(plugins: EcoBuildPlugin[], contextRoot: string, sourceTransforms?: readonly EcoSourceTransform[]): Plugin[];