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

package/src/build/rolldown/rolldown-plugin-bridge.js

@@ -0,0 +1,284 @@
+/**
+ * Bundler plugin bridge.
+ *
+ * @remarks
+ * Translates an array of `EcoBuildPlugin` instances (the runtime-agnostic
+ * plugin contract used by Ecopages processors and integrations) into
+ * the bundler's native `Plugin` array. The bridge exposes the same
+ * three hooks (`onResolve`, `onLoad`, `module`) the `EcoBuildPlugin`
+ * contract uses, but maps them to the bundler's `resolveId`/`load`
+ * hooks.
+ *
+ * The shared `EcoBuildPlugin` contract stays the boundary between
+ * integrations and bundler backends.
+ *
+ * **Namespace handling.**
+ *
+ * The shared `EcoBuildPlugin` contract scopes `onResolve`/`onLoad`
+ * handlers with a `namespace` string. The bundler encodes namespaces
+ * into the module id (no separate field). The bridge prepends
+ * `<namespace>:` to the resolved id when the result includes a
+ * namespace, and matches `onLoad`/`onResolve` filters against that
+ * prefix. The bridge strips the prefix before forwarding the id back
+ * to the callback so plugin code keeps seeing the same `path` shape
+ * it did on the historical contract.
+ *
+ * **Plugin ordering is semantically significant.**
+ *
+ * The bundler's `resolveId` and `load` are "first" hooks: the first
+ * plugin that returns a non-null value wins. Because the bridge
+ * translates each `EcoBuildPlugin` into its own bundler plugin and
+ * preserves the array order, the position of each plugin in the
+ * `plugins` array determines its priority:
+ *
+ * - **Index 0** has the highest priority.
+ * - **Last index** has the lowest priority.
+ *
+ * When adding new integrations or processors, ensure security-critical
+ * plugins (e.g. `ecopages-client-graph-boundary`) are placed **before**
+ * general-purpose loaders in the array so they always get first refusal
+ * on every source file.
+ */
+import path from 'node:path';
+import { finalizeLoadResultWithSourceTransforms } from './rolldown-source-transform-pass.js';
+import { escapeRegExp } from '../browser/browser-runtime-plugin-helpers.js';
+const NAMESPACE_SEPARATOR = ':';
+function joinNamespace(namespace, value) {
+    return namespace ? `${namespace}${NAMESPACE_SEPARATOR}${value}` : value;
+}
+function splitNamespace(id) {
+    const separatorIndex = id.indexOf(NAMESPACE_SEPARATOR);
+    if (separatorIndex <= 0) {
+        return { namespace: undefined, path: id };
+    }
+    return {
+        namespace: id.slice(0, separatorIndex),
+        path: id.slice(separatorIndex + 1),
+    };
+}
+function inferRolldownModuleTypeFromPath(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    switch (extension) {
+        case '.ts':
+            return 'ts';
+        case '.tsx':
+            return 'tsx';
+        case '.jsx':
+            return 'jsx';
+        case '.json':
+            return 'json';
+        case '.css':
+            return 'css';
+        default:
+            return 'js';
+    }
+}
+function normalizeRolldownModuleType(loader) {
+    switch (loader) {
+        case 'js':
+        case 'jsx':
+        case 'ts':
+        case 'tsx':
+        case 'json':
+        case 'css':
+        case 'text':
+        case 'base64':
+        case 'dataurl':
+        case 'binary':
+        case 'empty':
+            return loader;
+        case 'global-css':
+        case 'local-css':
+            return 'css';
+        case 'file':
+        case 'copy':
+            return 'asset';
+        default:
+            return undefined;
+    }
+}
+function convertLoadResultToModuleSource(result) {
+    if (result.loader === 'object' && result.exports && typeof result.exports === 'object') {
+        return Object.entries(result.exports)
+            .map(([key, value]) => key === 'default'
+            ? `export default ${JSON.stringify(value)};`
+            : `export const ${key} = ${JSON.stringify(value)};`)
+            .join('\n');
+    }
+    return undefined;
+}
+function buildIdFilter(filter, namespace) {
+    if (!namespace) {
+        return filter;
+    }
+    return new RegExp(`^${escapeRegExp(namespace)}${NAMESPACE_SEPARATOR}${filter.source.slice(1)}`);
+}
+function resolvePluginPath(value, importer, contextRoot) {
+    if (path.isAbsolute(value)) {
+        return value;
+    }
+    if (value.startsWith('.') || value.startsWith('..')) {
+        const baseDir = importer ? path.dirname(importer) : contextRoot;
+        return path.resolve(baseDir, value);
+    }
+    return value;
+}
+function convertPluginOnLoadResult(args, result) {
+    if (!result || typeof result !== 'object') {
+        return undefined;
+    }
+    const candidate = result;
+    const { path: sourcePath } = splitNamespace(args.id);
+    const sourceFromExports = convertLoadResultToModuleSource(candidate);
+    if (sourceFromExports) {
+        const description = {
+            code: sourceFromExports,
+            moduleType: 'js',
+        };
+        return description;
+    }
+    if (typeof candidate.contents === 'string' || candidate.contents instanceof Uint8Array) {
+        const code = typeof candidate.contents === 'string' ? candidate.contents : new TextDecoder().decode(candidate.contents);
+        const description = {
+            code,
+            moduleType: (normalizeRolldownModuleType(candidate.loader) ??
+                inferRolldownModuleTypeFromPath(sourcePath)),
+        };
+        return description;
+    }
+    return undefined;
+}
+function convertPluginOnResolveResult(result, importer, contextRoot) {
+    if (!result || typeof result !== 'object') {
+        return undefined;
+    }
+    const candidate = result;
+    if (typeof candidate.path !== 'string' && typeof candidate.namespace !== 'string') {
+        if (typeof candidate.external !== 'boolean') {
+            return undefined;
+        }
+    }
+    const partial = { id: '' };
+    if (typeof candidate.path === 'string') {
+        partial.id = joinNamespace(candidate.namespace, resolvePluginPath(candidate.path, importer, contextRoot));
+    }
+    else if (typeof candidate.namespace === 'string') {
+        partial.id = joinNamespace(candidate.namespace, '');
+    }
+    if (typeof candidate.external === 'boolean') {
+        partial.external = candidate.external;
+    }
+    return partial;
+}
+/**
+ * Creates a Rolldown `Plugin` array that drives the supplied
+ * `EcoBuildPlugin` instances.
+ *
+ * All eco plugins are merged into a single Rolldown plugin to minimize
+ * Rust→JS FFI overhead. Rolldown calls every hook for every module when
+ * there is no static filter, so N separate plugins would cause N
+ * `resolveId` + N `load` calls per module. Consolidating into one
+ * plugin reduces that to 1 call each, with JavaScript-side filtering
+ * routing to the correct eco plugin callback.
+ *
+ * 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 function createRolldownPluginBridge(plugins, contextRoot, sourceTransforms = []) {
+    if (plugins.length === 0) {
+        return [];
+    }
+    const moduleCounter = { value: 0 };
+    const resolveRegistrations = [];
+    const loadRegistrations = [];
+    const registerResolve = (filter, callback) => {
+        resolveRegistrations.push({ filter, callback });
+    };
+    const registerLoad = (filter, callback) => {
+        loadRegistrations.push({ filter, callback });
+    };
+    const resolveIdHandler = async (source, importer, _extraOptions) => {
+        for (const { filter, callback } of resolveRegistrations) {
+            if (!filter.test(source)) {
+                continue;
+            }
+            const { namespace, path: sourcePath } = splitNamespace(source);
+            const result = await callback({ path: sourcePath, importer, namespace });
+            const converted = convertPluginOnResolveResult(result, importer, contextRoot);
+            if (converted !== undefined) {
+                return converted;
+            }
+        }
+        return undefined;
+    };
+    const loadHandler = async (id) => {
+        let loadResult;
+        for (const { filter, callback } of loadRegistrations) {
+            if (!filter.test(id)) {
+                continue;
+            }
+            const { namespace, path: sourcePath } = splitNamespace(id);
+            const result = await callback({ path: sourcePath, namespace });
+            const converted = convertPluginOnLoadResult({ id }, result);
+            if (converted !== undefined) {
+                loadResult = converted;
+                break;
+            }
+        }
+        const { namespace, path: sourcePath } = splitNamespace(id);
+        return finalizeLoadResultWithSourceTransforms({
+            id,
+            namespace,
+            sourcePath,
+            loadResult,
+            sourceTransforms,
+            contextRoot,
+            inferModuleTypeFromPath: (filePath) => inferRolldownModuleTypeFromPath(filePath),
+        });
+    };
+    const plugin = {
+        name: 'ecopages-plugin-bridge',
+        buildStart: async () => {
+            resolveRegistrations.length = 0;
+            loadRegistrations.length = 0;
+            moduleCounter.value = 0;
+            for (const ecoPlugin of plugins) {
+                const bridge = {
+                    onResolve: (options, callback) => {
+                        registerResolve(buildIdFilter(options.filter, options.namespace), callback);
+                    },
+                    onLoad: (options, callback) => {
+                        registerLoad(buildIdFilter(options.filter, options.namespace), callback);
+                    },
+                    module: (specifier, callback) => {
+                        const namespace = `ecopages-module-${moduleCounter.value}`;
+                        moduleCounter.value += 1;
+                        const filter = new RegExp(`^${escapeRegExp(specifier)}$`);
+                        registerResolve(filter, async () => ({
+                            path: joinNamespace(namespace, specifier),
+                        }));
+                        registerLoad(buildIdFilter(/.*/, namespace), async () => callback());
+                    },
+                };
+                await ecoPlugin.setup(bridge);
+            }
+        },
+        resolveId: resolveIdHandler,
+        load: loadHandler,
+    };
+    return [plugin];
+}

package/src/build/rolldown/rolldown-source-transform-pass.d.ts

@@ -0,0 +1,15 @@
+import type { LoadResult, SourceDescription } from 'rolldown';
+import { type EcoSourceTransform } from '../../plugins/source-transform.js';
+/**
+ * Runs app-owned source transforms after first-wins `onLoad` plugins produce
+ * module contents for one Rolldown load request.
+ */
+export declare function finalizeLoadResultWithSourceTransforms(options: {
+    id: string;
+    namespace: string | undefined;
+    sourcePath: string;
+    loadResult: LoadResult | undefined;
+    sourceTransforms: readonly EcoSourceTransform[];
+    contextRoot: string;
+    inferModuleTypeFromPath: (filePath: string) => SourceDescription['moduleType'];
+}): Promise<LoadResult | undefined>;

package/src/build/rolldown/rolldown-source-transform-pass.js

@@ -0,0 +1,70 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { applySourceTransforms, normalizeTransformId, } from '../../plugins/source-transform.js';
+/**
+ * Standard source extensions eligible for the browser post-load transform pass.
+ *
+ * @remarks
+ * Compound integration templates (for example `.kita.tsx`) still match because
+ * matching uses the final path suffix. Keep this aligned with integration
+ * template extensions registered in app config.
+ */
+const TRANSFORMABLE_SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mdx']);
+function shouldApplySourceTransforms(namespace, sourcePath) {
+    if (namespace !== undefined) {
+        return false;
+    }
+    const normalizedPath = normalizeTransformId(sourcePath);
+    return TRANSFORMABLE_SOURCE_EXTENSIONS.has(path.extname(normalizedPath).toLowerCase());
+}
+function shouldTransformLoadedModule(moduleType) {
+    return moduleType !== 'css' && moduleType !== 'asset';
+}
+function applyTransformsToLoadedSource(sourceTransforms, id, sourcePath, code) {
+    if (sourceTransforms.length === 0) {
+        return code;
+    }
+    return applySourceTransforms(sourceTransforms, code, sourcePath);
+}
+/**
+ * Runs app-owned source transforms after first-wins `onLoad` plugins produce
+ * module contents for one Rolldown load request.
+ */
+export async function finalizeLoadResultWithSourceTransforms(options) {
+    const { id, namespace, sourcePath, loadResult, sourceTransforms, contextRoot, inferModuleTypeFromPath } = options;
+    if (!shouldApplySourceTransforms(namespace, sourcePath)) {
+        return loadResult;
+    }
+    if (typeof loadResult === 'object' &&
+        loadResult !== null &&
+        'code' in loadResult &&
+        typeof loadResult.code === 'string') {
+        if (!shouldTransformLoadedModule(loadResult.moduleType)) {
+            return loadResult;
+        }
+        const transformedCode = applyTransformsToLoadedSource(sourceTransforms, id, sourcePath, loadResult.code);
+        if (transformedCode === loadResult.code) {
+            return loadResult;
+        }
+        return {
+            code: transformedCode,
+            moduleType: loadResult.moduleType,
+        };
+    }
+    if (loadResult !== undefined || sourceTransforms.length === 0) {
+        return loadResult;
+    }
+    const normalizedPath = path.isAbsolute(sourcePath) ? sourcePath : path.resolve(contextRoot, sourcePath);
+    if (!fileSystem.exists(normalizedPath)) {
+        return loadResult;
+    }
+    const originalCode = fileSystem.readFileSync(normalizedPath);
+    const transformedCode = applyTransformsToLoadedSource(sourceTransforms, id, sourcePath, originalCode);
+    if (transformedCode === originalCode) {
+        return loadResult;
+    }
+    return {
+        code: transformedCode,
+        moduleType: inferModuleTypeFromPath(normalizedPath),
+    };
+}

package/src/build/rolldown/runtime-build-output-normalizer.js

@@ -0,0 +1,253 @@
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isBarePackageImportSpecifier } from '../../plugins/tsconfig-import-resolver.js';
+const corePackageRequire = createRequire(new URL('../../../package.json', import.meta.url));
+const appDeclaredPackageCache = new Map();
+const appWorkspacePackageCache = new Map();
+/**
+ * Core-owned packages that are part of the Node adapter's runtime surface and
+ * should therefore be preserved as bare specifiers in bundled output.
+ *
+ * Only list packages whose bare-specifier form will be resolvable from the
+ * app's Node.js runtime (i.e. they ship alongside the framework and do not
+ * need to be in the app's own package.json).
+ *
+ * Build-time tools (e.g. oxc-parser, rolldown) deliberately omitted — their
+ * imports in server-side output must be rewritten to absolute file: URLs so
+ * the bundler does not embed them in app code.
+ */
+const CORE_RUNTIME_BARE_SPECIFIER_PACKAGES = new Set(['ws']);
+function tryResolveRuntimeImport(specifier, resolver) {
+    try {
+        return resolver.resolve(specifier);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Extracts the package name from a file:// URL pointing to a node_modules path.
+ *
+ * @remarks
+ * Given a URL like `file:///path/to/node_modules/@scope/pkg/dist/index.js`,
+ * returns `@scope/pkg`. Given `file:///path/to/node_modules/pkg/dist/index.js`,
+ * returns `pkg`. Returns `undefined` if the URL doesn't point to node_modules.
+ *
+ * Handles pnpm's nested node_modules structure by finding the LAST node_modules
+ * in the path (e.g., `node_modules/.pnpm/pkg@version/node_modules/@scope/pkg/...`).
+ */
+function extractPackageNameFromFileUrl(specifier) {
+    if (!specifier.startsWith('file://')) {
+        return undefined;
+    }
+    // Find the LAST node_modules in the path to handle pnpm's nested structure
+    const lastNodeModulesIndex = specifier.lastIndexOf('/node_modules/');
+    if (lastNodeModulesIndex === -1) {
+        return undefined;
+    }
+    const afterNodeModules = specifier.slice(lastNodeModulesIndex + '/node_modules/'.length);
+    const parts = afterNodeModules.split('/');
+    if (parts.length === 0) {
+        return undefined;
+    }
+    if (parts[0]?.startsWith('@') && parts.length > 1) {
+        return `${parts[0]}/${parts[1]}`;
+    }
+    return parts[0];
+}
+function getPackageNameFromSpecifier(specifier) {
+    if (specifier.startsWith('@')) {
+        return specifier.split('/').slice(0, 2).join('/');
+    }
+    return specifier.split('/')[0] ?? specifier;
+}
+function getDeclaredAppPackages(rootDir) {
+    const cacheKey = path.resolve(rootDir);
+    const cached = appDeclaredPackageCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const packageJsonPath = path.resolve(rootDir, 'package.json');
+    const declaredPackages = 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 packageName of Object.keys(entries)) {
+                declaredPackages.add(packageName);
+            }
+        }
+    }
+    catch {
+        appDeclaredPackageCache.set(cacheKey, declaredPackages);
+        return declaredPackages;
+    }
+    appDeclaredPackageCache.set(cacheKey, declaredPackages);
+    return declaredPackages;
+}
+/**
+ * Returns the set of workspace packages declared in the app's package.json.
+ *
+ * Workspace packages are identified by the `workspace:` protocol in their
+ * version specifier (e.g., `"workspace:*"`, `"workspace:^1.0.0"`). These
+ * packages are typically source-only and must be bundled rather than
+ * externalized.
+ */
+function getWorkspacePackages(rootDir) {
+    const cacheKey = path.resolve(rootDir);
+    const cached = appWorkspacePackageCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const packageJsonPath = path.resolve(rootDir, 'package.json');
+    const workspacePackages = 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 [packageName, version] of Object.entries(entries)) {
+                if (typeof version === 'string' && version.startsWith('workspace:')) {
+                    workspacePackages.add(packageName);
+                }
+            }
+        }
+    }
+    catch {
+        appWorkspacePackageCache.set(cacheKey, workspacePackages);
+        return workspacePackages;
+    }
+    appWorkspacePackageCache.set(cacheKey, workspacePackages);
+    return workspacePackages;
+}
+/**
+ * Returns true if the given specifier is a workspace package.
+ *
+ * Workspace packages are declared with the `workspace:` protocol and are
+ * typically source-only, requiring bundling rather than externalization.
+ */
+export function isWorkspacePackageImport(specifier, rootDir) {
+    return getWorkspacePackages(rootDir).has(getPackageNameFromSpecifier(specifier));
+}
+export function isDeclaredAppPackageImport(specifier, rootDir) {
+    return getDeclaredAppPackages(rootDir).has(getPackageNameFromSpecifier(specifier));
+}
+/**
+ * Whether the given bare specifier should be left as-is (not rewritten to a
+ * file URL) in bundled output.
+ *
+ * Two categories qualify:
+ * 1. **App-declared packages** — present in the app's own package.json; the
+ *    app's resolver will find them at runtime.
+ * 2. **Core runtime surface packages** — a curated subset of the framework's
+ *    own dependencies that are part of its public Node adapter surface (e.g.
+ *    `ws`). These ship alongside the framework and are resolvable from the
+ *    bundled output's location even when the app has not declared them.
+ *
+ * Build-time packages declared by core (e.g. `oxc-parser`, `rolldown`) are
+ * intentionally *not* included here — their imports must still be rewritten
+ * to absolute `file:` URLs so they are not left as bare specifiers in app
+ * output.
+ */
+function isDeclaredInResolutionChain(specifier, rootDir) {
+    const packageName = getPackageNameFromSpecifier(specifier);
+    if (CORE_RUNTIME_BARE_SPECIFIER_PACKAGES.has(packageName)) {
+        return true;
+    }
+    return isDeclaredAppPackageImport(specifier, rootDir);
+}
+function rewriteRuntimeImportSpecifier(specifier, quote, rootDir) {
+    if (!isBarePackageImportSpecifier(specifier, rootDir)) {
+        return undefined;
+    }
+    if (isDeclaredInResolutionChain(specifier, rootDir)) {
+        return undefined;
+    }
+    const resolvedPath = tryResolveRuntimeImport(specifier, corePackageRequire);
+    if (!resolvedPath || !/\.(?:[cm]?[jt]s|tsx|jsx)$/u.test(resolvedPath)) {
+        return undefined;
+    }
+    return `${quote}${pathToFileURL(resolvedPath).href}${quote}`;
+}
+function rewriteRuntimeBuildOutputImports(code, rootDir) {
+    const rewriteSpecifier = (prefix, quote, specifier) => {
+        const rewrittenSpecifier = rewriteRuntimeImportSpecifier(specifier, quote, rootDir);
+        return `${prefix}${rewrittenSpecifier ?? `${quote}${specifier}${quote}`}`;
+    };
+    /**
+     * Rewrites file:// URLs pointing to node_modules back to bare specifiers,
+     * but only when the package is resolvable from the app's resolution chain.
+     *
+     * @remarks
+     * Rolldown resolves external imports to file:// URLs during the build. For
+     * packages declared in the app's package.json, rewriting to bare specifiers
+     * is safe and preserves CJS named-export interop. For transitive
+     * dependencies that aren't directly resolvable, the file:// URL is kept as-is
+     * to avoid ERR_MODULE_NOT_FOUND errors at runtime.
+     */
+    const rewriteFileUrl = (prefix, quote, specifier) => {
+        const packageName = extractPackageNameFromFileUrl(specifier);
+        if (!packageName) {
+            return `${prefix}${quote}${specifier}${quote}`;
+        }
+        if (!isDeclaredInResolutionChain(packageName, rootDir)) {
+            return `${prefix}${quote}${specifier}${quote}`;
+        }
+        // Extract the subpath after the package name
+        // Use lastIndexOf to handle pnpm's nested node_modules structure
+        const lastNodeModulesIndex = specifier.lastIndexOf('/node_modules/');
+        if (lastNodeModulesIndex === -1) {
+            return `${prefix}${quote}${specifier}${quote}`;
+        }
+        const afterNodeModules = specifier.slice(lastNodeModulesIndex + '/node_modules/'.length);
+        const afterPackage = afterNodeModules.slice(packageName.length);
+        // Reconstruct the bare specifier
+        const bareSpecifier = packageName + afterPackage;
+        return `${prefix}${quote}${bareSpecifier}${quote}`;
+    };
+    const withResolvedPackages = code
+        .replace(/(\bfrom\s+)(['"])([^'"\\]+)\2/g, (_match, prefix, quote, specifier) => rewriteSpecifier(prefix, quote, specifier))
+        .replace(/(\bimport\s+)(['"])([^'"\\]+)\2/g, (_match, prefix, quote, specifier) => rewriteSpecifier(prefix, quote, specifier))
+        .replace(/(\bimport\s*\(\s*)(['"])([^'"\\]+)\2/g, (_match, prefix, quote, specifier) => rewriteSpecifier(prefix, quote, specifier));
+    // Rewrite file:// URLs pointing to node_modules back to bare specifiers
+    const withBareSpecifiers = withResolvedPackages
+        .replace(/(\bfrom\s+)(['"])(file:\/\/[^'"\\]+)\2/g, (_match, prefix, quote, specifier) => rewriteFileUrl(prefix, quote, specifier))
+        .replace(/(\bimport\s+)(['"])(file:\/\/[^'"\\]+)\2/g, (_match, prefix, quote, specifier) => rewriteFileUrl(prefix, quote, specifier))
+        .replace(/(\bimport\s*\(\s*)(['"])(file:\/\/[^'"\\]+)\2/g, (_match, prefix, quote, specifier) => rewriteFileUrl(prefix, quote, specifier));
+    return withBareSpecifiers.replace(/(['"])(@oxc-project\/runtime\/(?:helpers(?:\/esm)?\/[^'"\\]+))\1/g, (match, quote, specifier) => {
+        const resolvedPath = tryResolveRuntimeImport(specifier, corePackageRequire);
+        return resolvedPath ? `${quote}${pathToFileURL(resolvedPath).href}${quote}` : match;
+    });
+}
+export function normalizeNodeRuntimeBuildOutputFile(filePath, rootDir) {
+    if (process.env.ECOPAGES_LOGGER_DEBUG === 'true') {
+        console.log(`[normalizeNodeRuntimeBuildOutputFile] Checking ${filePath}`);
+    }
+    if (!/\.(?:[cm]?js)$/u.test(filePath)) {
+        return;
+    }
+    const fileSystem = corePackageRequire('node:fs');
+    if (!fileSystem.existsSync(filePath)) {
+        return;
+    }
+    const code = fileSystem.readFileSync(filePath, 'utf-8');
+    const rewritten = rewriteRuntimeBuildOutputImports(code, rootDir);
+    if (rewritten !== code) {
+        if (process.env.ECOPAGES_LOGGER_DEBUG === 'true') {
+            console.log(`[normalizeNodeRuntimeBuildOutputFile] Rewriting ${filePath}`);
+        }
+        fileSystem.writeFileSync(filePath, rewritten);
+    }
+}
+export function normalizeNodeRuntimeBuildOutputs(outputPaths, rootDir) {
+    for (const outputPath of outputPaths) {
+        normalizeNodeRuntimeBuildOutputFile(outputPath, rootDir);
+    }
+}

package/src/build/rolldown/server-side-css-shim-plugin.js

@@ -0,0 +1,58 @@
+/**
+ * Server-side CSS shim plugin for the bundler adapter.
+ *
+ * @remarks
+ * Page modules imported by the server (so the framework can read
+ * `getStaticProps` / `staticPaths` / page metadata) commonly have
+ * `import './style.css'` at the top. The bundler does not bundle
+ * CSS, and the server only needs the JS exports — the CSS itself
+ * is delivered to the browser via the page's `dependencies.stylesheets`
+ * declarations. This plugin:
+ *
+ * - Resolves `.css` imports to the absolute on-disk path.
+ * - Loads them and returns an empty ESM module with
+ *   `moduleSideEffects: true` so the bundler keeps the import in
+ *   the dependency graph without trying to bundle the bytes.
+ *
+ * The plugin is added by the adapter on every server-side build.
+ * Browser-side builds that want real CSS bundling should keep using
+ * a dedicated CSS pipeline (e.g. the postcss processor's output)
+ * and continue to declare stylesheets in `dependencies.stylesheets`
+ * — the shim is intentionally inert for those flows.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+const CSS_PATH = /\.css$/u;
+const CSS_QUERY = '?ecopages-css-shim';
+function stripShimQuery(id) {
+    const queryIndex = id.indexOf('?');
+    return queryIndex === -1 ? id : id.slice(0, queryIndex);
+}
+/**
+ * Builds a Rolldown plugin that turns `.css` imports into no-op ESM
+ * modules while preserving the dependency graph.
+ */
+export function createServerSideCssShimPlugin() {
+    return {
+        name: 'ecopages:server-side-css-shim',
+        async resolveId(source, importer) {
+            if (!CSS_PATH.test(source)) {
+                return null;
+            }
+            const resolved = importer ? path.resolve(path.dirname(importer), source) : path.resolve(source);
+            return existsSync(resolved) ? `${resolved}${CSS_QUERY}` : null;
+        },
+        async load(id) {
+            if (!id.endsWith(CSS_QUERY)) {
+                return null;
+            }
+            const realPath = stripShimQuery(id);
+            readFileSync(realPath, 'utf-8');
+            return {
+                code: 'export default "";',
+                moduleType: 'js',
+                moduleSideEffects: true,
+            };
+        },
+    };
+}

package/src/build/runtime/build-profile-options.d.ts

@@ -0,0 +1,7 @@
+import type { BuildOptions } from '../build-adapter.js';
+import type { BuildProfile } from './build-runtime.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+/**
+ * Resolves shared Rolldown options for a build profile.
+ */
+export declare function resolveBuildProfileOptions(profile: BuildProfile, appConfig: EcoPagesAppConfig, overrides?: Partial<BuildOptions>): Partial<BuildOptions>;