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

package/src/build/contracts/build-manifest.d.ts

@@ -0,0 +1,90 @@
+import type { EcoBuildPlugin } from './build-types.js';
+import { type BrowserRuntimeManifest } from '../browser/browser-runtime-manifest.js';
+/**
+ * Sealed, app-owned registry of build plugins and browser runtime assets.
+ *
+ * @remarks
+ * Core assembles one manifest during {@link ConfigBuilder.build} and stores it on
+ * `appConfig.runtime.buildManifest`. Request policy reads from this manifest when
+ * constructing server and browser {@link BuildOptions}; profiles do not inject
+ * plugins themselves.
+ *
+ * Contributor naming differs by layer but maps to the same buckets:
+ *
+ * | Integration getter | Processor getter | Manifest bucket |
+ * | --- | --- | --- |
+ * | `plugins` | `plugins` | `runtimePlugins` |
+ * | `browserBuildPlugins` | `buildPlugins` | `browserBundlePlugins` |
+ * | `browserRuntimeManifest` | — | `browserRuntimeManifest` |
+ * | — (file loaders on config) | — | `loaderPlugins` |
+ *
+ * Use {@link getServerBuildPlugins} and {@link getBrowserBuildPlugins} to turn
+ * buckets into the plugin lists passed to Rolldown. App-aware call sites should
+ * prefer {@link getAppServerBuildPlugins} and {@link getAppBrowserBuildPlugins},
+ * which add alias resolution, JSX ownership, and browser source-transform
+ * deduplication on top of the manifest lists.
+ */
+export interface AppBuildManifest {
+    /** File-extension loaders registered on the app config (for example `.mdx`). */
+    loaderPlugins: EcoBuildPlugin[];
+    /**
+     * Shared plugins for server-oriented and browser-oriented builds.
+     *
+     * @remarks
+     * Sourced from integration `plugins` and processor `plugins`. Virtual-module
+     * loaders and transforms that must run during route-module transpile belong
+     * here.
+     */
+    runtimePlugins: EcoBuildPlugin[];
+    /**
+     * Browser-bundle-only plugins.
+     *
+     * @remarks
+     * Sourced from integration `browserBuildPlugins` and processor `buildPlugins`.
+     * Do not register server route or static-page transforms here.
+     */
+    browserBundlePlugins: EcoBuildPlugin[];
+    /**
+     * Specifier → public URL map for client bundles.
+     *
+     * @remarks
+     * Not a plugin list. {@link getBrowserBuildPlugins} synthesizes
+     * `browser-runtime-plugin` from this map to rewrite manifest-owned imports.
+     */
+    browserRuntimeManifest: BrowserRuntimeManifest;
+}
+/**
+ * Merges plugin lists while preserving first-registration precedence by name.
+ *
+ * @remarks
+ * Build manifests treat plugin names as stable identities. The first plugin
+ * with a given name wins so config-time assembly stays deterministic across
+ * loader, runtime, and browser buckets.
+ */
+export declare function mergeEcoBuildPlugins(...pluginLists: Array<EcoBuildPlugin[] | undefined>): EcoBuildPlugin[];
+/**
+ * Creates one app-owned build manifest from the supplied plugin buckets.
+ */
+export declare function createAppBuildManifest(input?: Partial<AppBuildManifest>): AppBuildManifest;
+/**
+ * Returns the shared browser runtime asset manifest sealed into the app build manifest.
+ */
+export declare function getBrowserRuntimeManifest(manifest: AppBuildManifest): BrowserRuntimeManifest;
+/**
+ * Returns the plugin list used for server-oriented builds.
+ *
+ * @remarks
+ * Merges `loaderPlugins` then `runtimePlugins`. Browser-only buckets and the
+ * synthesized browser-runtime rewrite plugin are excluded.
+ */
+export declare function getServerBuildPlugins(manifest: AppBuildManifest): EcoBuildPlugin[];
+/**
+ * Returns the plugin list used for browser-oriented builds.
+ *
+ * @remarks
+ * Merges, in order: `loaderPlugins`, `runtimePlugins`, a synthesized
+ * `browser-runtime-plugin` when `browserRuntimeManifest` has entries, then
+ * `browserBundlePlugins`. Plugin names dedupe with first-registration wins via
+ * {@link mergeEcoBuildPlugins}.
+ */
+export declare function getBrowserBuildPlugins(manifest: AppBuildManifest): EcoBuildPlugin[];

package/src/build/contracts/build-manifest.js

@@ -0,0 +1,64 @@
+import { createBrowserRuntimePlugin, DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME } from '../browser/browser-runtime-plugin.js';
+import { createBrowserRuntimeManifest, mergeBrowserRuntimeManifests, } from '../browser/browser-runtime-manifest.js';
+/**
+ * Merges plugin lists while preserving first-registration precedence by name.
+ *
+ * @remarks
+ * Build manifests treat plugin names as stable identities. The first plugin
+ * with a given name wins so config-time assembly stays deterministic across
+ * loader, runtime, and browser buckets.
+ */
+export function mergeEcoBuildPlugins(...pluginLists) {
+    const byName = new Map();
+    for (const plugins of pluginLists) {
+        for (const plugin of plugins ?? []) {
+            if (!byName.has(plugin.name)) {
+                byName.set(plugin.name, plugin);
+            }
+        }
+    }
+    return Array.from(byName.values());
+}
+/**
+ * Creates one app-owned build manifest from the supplied plugin buckets.
+ */
+export function createAppBuildManifest(input) {
+    return {
+        loaderPlugins: mergeEcoBuildPlugins(input?.loaderPlugins),
+        runtimePlugins: mergeEcoBuildPlugins(input?.runtimePlugins),
+        browserBundlePlugins: mergeEcoBuildPlugins(input?.browserBundlePlugins),
+        browserRuntimeManifest: mergeBrowserRuntimeManifests(input?.browserRuntimeManifest),
+    };
+}
+/**
+ * Returns the shared browser runtime asset manifest sealed into the app build manifest.
+ */
+export function getBrowserRuntimeManifest(manifest) {
+    return manifest.browserRuntimeManifest ?? createBrowserRuntimeManifest();
+}
+/**
+ * Returns the plugin list used for server-oriented builds.
+ *
+ * @remarks
+ * Merges `loaderPlugins` then `runtimePlugins`. Browser-only buckets and the
+ * synthesized browser-runtime rewrite plugin are excluded.
+ */
+export function getServerBuildPlugins(manifest) {
+    return mergeEcoBuildPlugins(manifest.loaderPlugins, manifest.runtimePlugins);
+}
+/**
+ * Returns the plugin list used for browser-oriented builds.
+ *
+ * @remarks
+ * Merges, in order: `loaderPlugins`, `runtimePlugins`, a synthesized
+ * `browser-runtime-plugin` when `browserRuntimeManifest` has entries, then
+ * `browserBundlePlugins`. Plugin names dedupe with first-registration wins via
+ * {@link mergeEcoBuildPlugins}.
+ */
+export function getBrowserBuildPlugins(manifest) {
+    const runtimeRewritePlugin = createBrowserRuntimePlugin({
+        name: DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME,
+        manifest: getBrowserRuntimeManifest(manifest),
+    });
+    return mergeEcoBuildPlugins(manifest.loaderPlugins, manifest.runtimePlugins, runtimeRewritePlugin ? [runtimeRewritePlugin] : [], manifest.browserBundlePlugins);
+}

package/src/build/contracts/build-types.js

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

package/src/build/contracts/content-virtual-modules.d.ts

@@ -0,0 +1,12 @@
+/** Virtual module prefix for collection imports, e.g. `ecopages:content/docs`. */
+export declare const CONTENT_VIRTUAL_MODULE_PREFIX = "ecopages:content";
+/** Matches `ecopages:content/<collection>` metadata specifiers (no MDX imports). */
+export declare const CONTENT_VIRTUAL_MODULE_PATTERN: RegExp;
+/** Matches `ecopages:content/<collection>/server` component resolver specifiers. */
+export declare const CONTENT_SERVER_VIRTUAL_MODULE_PATTERN: RegExp;
+export type ParsedCollectionSpecifier = {
+    collectionName: string;
+    variant: 'entries' | 'server';
+};
+export declare function parseCollectionSpecifier(specifier: string): ParsedCollectionSpecifier | null;
+export declare function isContentServerVirtualModule(specifier: string): boolean;

package/src/build/contracts/content-virtual-modules.js

@@ -0,0 +1,29 @@
+/** Virtual module prefix for collection imports, e.g. `ecopages:content/docs`. */
+export const CONTENT_VIRTUAL_MODULE_PREFIX = 'ecopages:content';
+/** Matches `ecopages:content/<collection>` metadata specifiers (no MDX imports). */
+export const CONTENT_VIRTUAL_MODULE_PATTERN = /^ecopages:content\/[a-z][a-z0-9-]*$/;
+/** Matches `ecopages:content/<collection>/server` component resolver specifiers. */
+export const CONTENT_SERVER_VIRTUAL_MODULE_PATTERN = /^ecopages:content\/[a-z][a-z0-9-]+\/server$/;
+export function parseCollectionSpecifier(specifier) {
+    const normalized = specifier.startsWith(`${CONTENT_VIRTUAL_MODULE_PREFIX}/`)
+        ? specifier.slice(`${CONTENT_VIRTUAL_MODULE_PREFIX}/`.length)
+        : specifier.startsWith('content/')
+            ? specifier.slice('content/'.length)
+            : null;
+    if (!normalized) {
+        return null;
+    }
+    if (normalized.endsWith('/server')) {
+        return {
+            collectionName: normalized.slice(0, -'/server'.length),
+            variant: 'server',
+        };
+    }
+    return {
+        collectionName: normalized,
+        variant: 'entries',
+    };
+}
+export function isContentServerVirtualModule(specifier) {
+    return CONTENT_SERVER_VIRTUAL_MODULE_PATTERN.test(specifier);
+}

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

@@ -2,19 +2,42 @@
  * Shared helpers for the Rolldown-backed build adapters.
  *
  * @remarks
- * The standard {@link RolldownBuildAdapter} (one-shot production builds)
- * and the dev {@link RolldownDevBuildAdapter} (DevEngine-backed
- * incremental rebuilds) both need the same BuildOptions → Rolldown
- * mapping, the same dependency-graph extraction, and the same
- * post-build rewriting pipeline. This module hosts the shared code so
- * the two adapters stay semantically identical.
+ * The standard {@link RolldownBuildAdapter} uses these helpers for
+ * BuildOptions → Rolldown mapping, dependency-graph extraction, and the
+ * post-build rewriting pipeline.
  *
  * @module
  */
-import type { InputOptions, OutputOptions } from 'rolldown';
-import type { EcoBuildPlugin } from './build-types.js';
-import type { BuildDependencyGraph, BuildLog, BuildOptions, BuildResult, BuildTranspileOptions, BuildTranspileProfile } from './build-adapter.js';
+import type { InputOptions, OutputOptions, RolldownPlugin } from 'rolldown';
+import type { EcoBuildPlugin } from '../contracts/build-types.js';
+import type { BuildDependencyGraph, BuildLog, BuildOptions, BuildResult, BuildTranspileOptions, BuildTranspileProfile } from '../build-adapter.js';
 export declare function transpileProfileToOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+/**
+ * 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 declare function createNodeBuiltinExternalPlugin(): RolldownPlugin;
+/**
+ * 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 declare function createBrowserNodeBuiltinGuardPlugin(): RolldownPlugin;
 export declare function extractDependencyGraph(chunks: Array<{
     facadeModuleId: string | null;
     moduleIds: string[];