@ecopages/core 0.2.0-beta.30 → 0.2.0-beta.32

package/src/adapters/shared/ws/websocket-lifecycle.js

@@ -1,55 +1,62 @@
-import { appLogger } from "../../../global/app-logger.js";
+import { appLogger } from '../../../global/app-logger.js';
 function sendOutgoingMessage(transport, message) {
-  if (typeof message === "string") {
-    transport.send(message);
-  } else if (message instanceof Blob) {
-    void message.arrayBuffer().then((buffer) => transport.send(new Uint8Array(buffer)));
-  } else if (message instanceof ArrayBuffer) {
-    transport.send(new Uint8Array(message));
-  } else if (ArrayBuffer.isView(message)) {
-    transport.send(new Uint8Array(message.buffer, message.byteOffset, message.byteLength));
-  } else {
-    transport.send(message);
-  }
+    if (typeof message === 'string') {
+        transport.send(message);
+    }
+    else if (message instanceof Blob) {
+        void message.arrayBuffer().then((buffer) => transport.send(new Uint8Array(buffer)));
+    }
+    else if (message instanceof ArrayBuffer) {
+        transport.send(new Uint8Array(message));
+    }
+    else if (ArrayBuffer.isView(message)) {
+        transport.send(new Uint8Array(message.buffer, message.byteOffset, message.byteLength));
+    }
+    else {
+        transport.send(message);
+    }
 }
-function createEcopagesSocket(transport, meta) {
-  return {
-    kind: meta.kind,
-    params: meta.params,
-    search: meta.search,
-    context: meta.context,
-    send: (message) => sendOutgoingMessage(transport, message),
-    sendStream: async (stream) => {
-      const reader = stream.getReader();
-      try {
-        while (true) {
-          const { value, done } = await reader.read();
-          if (done) break;
-          if (value) transport.send(value);
-        }
-      } finally {
-        reader.releaseLock();
-      }
-    },
-    close: (code, reason) => transport.close(code, reason)
-  };
+/**
+ * @remarks
+ * Bun and Node adapters previously duplicated outgoing-message dispatch and
+ * stream forwarding; this is the shared implementation both transports delegate to.
+ */
+export function createEcopagesSocket(transport, meta) {
+    return {
+        kind: meta.kind,
+        params: meta.params,
+        search: meta.search,
+        context: meta.context,
+        send: (message) => sendOutgoingMessage(transport, message),
+        sendStream: async (stream) => {
+            const reader = stream.getReader();
+            try {
+                while (true) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    if (value)
+                        transport.send(value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        },
+        close: (code, reason) => transport.close(code, reason),
+    };
 }
-function toWebSocketCloseInfo(code, reason) {
-  return {
-    code,
-    reason,
-    wasClean: code === 1e3 || code === 1001
-  };
+export function toWebSocketCloseInfo(code, reason) {
+    return {
+        code,
+        reason,
+        wasClean: code === 1000 || code === 1001,
+    };
 }
-function invokeWebSocketHandlerHook(kind, hookName, result) {
-  if (result instanceof Promise) {
-    result.catch((error) => {
-      appLogger.error(`[WS:${kind}] ${hookName} failed:`, error);
-    });
-  }
+export function invokeWebSocketHandlerHook(kind, hookName, result) {
+    if (result instanceof Promise) {
+        result.catch((error) => {
+            appLogger.error(`[WS:${kind}] ${hookName} failed:`, error);
+        });
+    }
 }
-export {
-  createEcopagesSocket,
-  invokeWebSocketHandlerHook,
-  toWebSocketCloseInfo
-};

package/src/build/README.md

@@ -2,6 +2,23 @@
 
 The build layer is the bundler contract for Ecopages. One bundled adapter is the default; one host-owned boundary marker covers the Vite-host path.
 
+## Contents
+
+- [Mental Model](#mental-model)
+- [Files](#files)
+- [Default Flow](#default-flow)
+- [App build manifest](#app-build-manifest)
+- [Vite-Host Boundary](#vite-host-boundary)
+- [Plugin Authoring](#plugin-authoring)
+- [BuildOptions Caveats](#buildoptions-caveats)
+- [Dev / watch path](#dev--watch-path)
+- [Metrics](#metrics)
+- [Production build caches](#production-build-caches)
+- [Unified pages graph](#unified-pages-graph)
+- [JSX Ownership Plugins](#jsx-ownership-plugins)
+- [Rolldown operator notes](#rolldown-operator-notes)
+- [Testing Strategy](#testing-strategy)
+
 ## Mental Model
 
 Three concentric shapes, plus profile executors and request policy:
@@ -122,7 +139,7 @@ App-manifest plugins keep canonical registration order and cannot be silently re
 
 `BuildOptions` is modeled on the bundler's options shape. Most fields map cleanly. The exceptions:
 
-- `splitting` — accepted but currently ignored. The bundler splits by default. The per-chunk naming is fixed to `[name]-[hash]`. If you need to disable splitting or rename chunks, the adapter will need a new option.
+- `splitting` — when `false` with a single entrypoint, maps to Rolldown `codeSplitting: false` so dynamic imports stay in one file. Multi-entrypoint builds ignore `splitting: false` because Rolldown cannot inline across multiple inputs.
 - `bundle` — accepted but ignored. The bundler always bundles.
 - `outbase` — accepted but ignored. The adapter derives the base from `options.root` directly.
 
@@ -188,6 +205,40 @@ Mixed-integration apps need explicit `@jsxImportSource` handling in two differen
 
 `foreign-jsx-override-plugin.ts` is the shared implementation. Prefer the helpers above instead of calling it directly from integrations.
 
+## Rolldown operator notes
+
+Ecopages bundles with Rolldown across Node, Bun, and browser targets. Vite-hosted apps use `ViteHostBuildAdapter` as a boundary marker; the host runs its own pipeline.
+
+### Plugin hook filters
+
+Rolldown evaluates plugin hooks on the Rust side and only calls JavaScript when the filter matches. Hooks without filters run for every module through Rust→JS FFI, causing **3–4× slowdown** with multiple plugins.
+
+```typescript
+// BAD — called for every module
+resolveId(source, importer) { /* ... */ }
+
+// GOOD — skipped unless the filter matches
+resolveId: {
+  filter: { id: /\.tsx?$/ },
+  handler(source, importer) { /* ... */ },
+}
+```
+
+If patterns are dynamic (populated during `buildStart`), Rolldown cannot use filters because they are read at registration time. Consolidate dynamic plugins into a **single** Rolldown plugin to minimize FFI calls. See [rolldown.rs/reference/plugin-hooks](https://rolldown.rs/reference/plugin-hooks).
+
+### Consolidate plugins
+
+Each Rolldown plugin adds FFI overhead per module per hook. Ecopages merges all `EcoBuildPlugin` instances into one Rolldown plugin in `rolldown-plugin-bridge.ts` with JavaScript-side routing.
+
+### Benchmarks
+
+Kitchen-sink benchmarks (`ECOPAGES_BENCH=1 pnpm vitest bench`) show Rolldown winning 15/18 scenarios versus esbuild, with a **1.21×** geometric mean speedup. Largest wins: React page rebuilds (1.56×), production single page (1.49×), Lit (1.52×), Ecopages-JSX (1.47×). Three scenarios regressed (KitaJS postcss, dynamic route, no-op rebuild); route-module disk cache and fingerprinted production caches reduce repeated work on warm paths.
+
+### Native MagicString and CSS shim
+
+- `experimental.nativeMagicString: true` enables Rust-native string manipulation for faster transforms.
+- Server-side builds use `createServerSideCssShimPlugin()` to turn `.css` imports into empty ESM modules. Skipped for browser builds.
+
 ## Testing Strategy
 
 - `rolldown/rolldown-build-adapter.test.ts` covers the adapter's `build`, `resolve`, `getTranspileOptions`, and dependency-graph extraction end-to-end.

package/src/build/app-build-manifest-runtime.js

@@ -1,124 +1,145 @@
-import { mergeBrowserRuntimeManifests } from "./browser/browser-runtime-manifest.js";
-import { appLogger } from "../global/app-logger.js";
-import { startupTrace } from "../diagnostics/startup-trace.js";
-import { isLitStaticRenderWorkerThread } from "./browser/lit-static-render-worker-context.js";
+import { mergeBrowserRuntimeManifests } from './browser/browser-runtime-manifest.js';
+import { appLogger } from '../global/app-logger.js';
+import { startupTrace } from '../diagnostics/startup-trace.js';
+import { isLitStaticRenderWorkerThread } from './browser/lit-static-render-worker-context.js';
 function patchAppRuntime(appConfig, patch) {
-  appConfig.runtime = {
-    ...appConfig.runtime ?? {},
-    ...patch
-  };
+    appConfig.runtime = {
+        ...(appConfig.runtime ?? {}),
+        ...patch,
+    };
 }
 function registerRuntimePlugins(appConfig, onRuntimePlugin) {
-  for (const loader of appConfig.loaders.values()) {
-    onRuntimePlugin?.(loader);
-  }
-  for (const processor of appConfig.processors.values()) {
-    if (processor.plugins) {
-      for (const plugin of processor.plugins) {
-        onRuntimePlugin?.(plugin);
-      }
+    for (const loader of appConfig.loaders.values()) {
+        onRuntimePlugin?.(loader);
     }
-  }
-  for (const integration of appConfig.integrations) {
-    for (const plugin of integration.plugins) {
-      onRuntimePlugin?.(plugin);
+    for (const processor of appConfig.processors.values()) {
+        if (processor.plugins) {
+            for (const plugin of processor.plugins) {
+                onRuntimePlugin?.(plugin);
+            }
+        }
+    }
+    for (const integration of appConfig.integrations) {
+        for (const plugin of integration.plugins) {
+            onRuntimePlugin?.(plugin);
+        }
     }
-  }
 }
-async function collectConfiguredAppBuildManifestContributions(appConfig) {
-  const runtimePlugins = [];
-  const browserBundlePlugins = [];
-  const browserRuntimeManifests = [];
-  for (const processor of appConfig.processors.values()) {
-    await processor.prepareBuildContributions();
-    if (processor.plugins) {
-      runtimePlugins.push(...processor.plugins);
+/**
+ * Collects integration and processor contributions before the app build manifest is sealed.
+ *
+ * @remarks
+ * Called from {@link ConfigBuilder.build} via {@link updateAppBuildManifest}. Walks
+ * processors first, then integrations, invoking {@link Processor.prepareBuildContributions}
+ * and {@link IntegrationPlugin.prepareBuildContributions} so dynamic plugin lists can be
+ * materialized before sealing.
+ *
+ * Maps contributor getters to manifest buckets:
+ * - `processor.plugins` / `integration.plugins` → `runtimePlugins`
+ * - `processor.buildPlugins` / `integration.browserBuildPlugins` → `browserBundlePlugins`
+ * - `integration.browserRuntimeManifest` → merged `browserRuntimeManifest`
+ *
+ * Loaders are not collected here; {@link createConfiguredAppBuildManifest} always takes
+ * them from `appConfig.loaders`.
+ */
+export async function collectConfiguredAppBuildManifestContributions(appConfig) {
+    const runtimePlugins = [];
+    const browserBundlePlugins = [];
+    const browserRuntimeManifests = [];
+    for (const processor of appConfig.processors.values()) {
+        await processor.prepareBuildContributions();
+        if (processor.plugins) {
+            runtimePlugins.push(...processor.plugins);
+        }
+        if (processor.buildPlugins) {
+            browserBundlePlugins.push(...processor.buildPlugins);
+        }
     }
-    if (processor.buildPlugins) {
-      browserBundlePlugins.push(...processor.buildPlugins);
+    for (const integration of appConfig.integrations) {
+        integration.setConfig(appConfig);
+        await integration.prepareBuildContributions();
+        runtimePlugins.push(...(integration.plugins ?? []));
+        browserBundlePlugins.push(...(integration.browserBuildPlugins ?? []));
+        browserRuntimeManifests.push(integration.browserRuntimeManifest);
     }
-  }
-  for (const integration of appConfig.integrations) {
-    integration.setConfig(appConfig);
-    await integration.prepareBuildContributions();
-    runtimePlugins.push(...integration.plugins ?? []);
-    browserBundlePlugins.push(...integration.browserBuildPlugins ?? []);
-    browserRuntimeManifests.push(integration.browserRuntimeManifest);
-  }
-  return {
-    runtimePlugins,
-    browserBundlePlugins,
-    browserRuntimeManifest: mergeBrowserRuntimeManifests(...browserRuntimeManifests)
-  };
+    return {
+        runtimePlugins,
+        browserBundlePlugins,
+        browserRuntimeManifest: mergeBrowserRuntimeManifests(...browserRuntimeManifests),
+    };
 }
-async function setupAppRuntimePlugins(options) {
-  startupTrace.markPhaseStart("setupAppRuntimePlugins");
-  if (options.appConfig.runtime?.runtimeAssetsPrepared) {
-    appLogger.debug("Skipped setupAppRuntimePlugins: runtime assets already prepared");
-    registerRuntimePlugins(options.appConfig, options.onRuntimePlugin);
-    startupTrace.markPhaseEnd("setupAppRuntimePlugins");
-    return;
-  }
-  if (isLitStaticRenderWorkerThread()) {
-    appLogger.debug("Lit static-render worker: skipping processor setup (main thread already prepared artifacts)");
-  }
-  appLogger.debugTime("setupAppRuntimePlugins");
-  try {
-    if (options.onRuntimePlugin) {
-      patchAppRuntime(options.appConfig, { onRuntimePlugin: options.onRuntimePlugin });
+export async function setupAppRuntimePlugins(options) {
+    startupTrace.markPhaseStart('setupAppRuntimePlugins');
+    if (options.appConfig.runtime?.runtimeAssetsPrepared) {
+        appLogger.debug('Skipped setupAppRuntimePlugins: runtime assets already prepared');
+        registerRuntimePlugins(options.appConfig, options.onRuntimePlugin);
+        startupTrace.markPhaseEnd('setupAppRuntimePlugins');
+        return;
     }
-    for (const loader of options.appConfig.loaders.values()) {
-      options.onRuntimePlugin?.(loader);
+    if (isLitStaticRenderWorkerThread()) {
+        appLogger.debug('Lit static-render worker: skipping processor setup (main thread already prepared artifacts)');
     }
-    const skipProcessorSetup = isLitStaticRenderWorkerThread();
-    for (const processor of options.appConfig.processors.values()) {
-      if (!skipProcessorSetup) {
-        await processor.setup();
-      }
-      if (processor.plugins) {
-        for (const plugin of processor.plugins) {
-          options.onRuntimePlugin?.(plugin);
+    appLogger.debugTime('setupAppRuntimePlugins');
+    try {
+        if (options.onRuntimePlugin) {
+            patchAppRuntime(options.appConfig, { onRuntimePlugin: options.onRuntimePlugin });
+        }
+        for (const loader of options.appConfig.loaders.values()) {
+            options.onRuntimePlugin?.(loader);
         }
-      }
+        const skipProcessorSetup = isLitStaticRenderWorkerThread();
+        for (const processor of options.appConfig.processors.values()) {
+            if (!skipProcessorSetup) {
+                await processor.setup();
+            }
+            if (processor.plugins) {
+                for (const plugin of processor.plugins) {
+                    options.onRuntimePlugin?.(plugin);
+                }
+            }
+        }
+        patchAppRuntime(options.appConfig, { runtimeAssetsPrepared: true });
+    }
+    finally {
+        appLogger.debugTimeEnd('setupAppRuntimePlugins');
+        startupTrace.markPhaseEnd('setupAppRuntimePlugins');
     }
-    patchAppRuntime(options.appConfig, { runtimeAssetsPrepared: true });
-  } finally {
-    appLogger.debugTimeEnd("setupAppRuntimePlugins");
-    startupTrace.markPhaseEnd("setupAppRuntimePlugins");
-  }
 }
-async function ensureIntegrationRuntimeReady(options) {
-  const runtime = options.appConfig.runtime ?? {};
-  options.appConfig.runtime = runtime;
-  runtime.integrationActivations ??= /* @__PURE__ */ new Map();
-  const existing = runtime.integrationActivations.get(options.integrationName);
-  if (existing) {
-    await existing;
-    return;
-  }
-  const integration = options.appConfig.integrations.find((plugin) => plugin.name === options.integrationName);
-  if (!integration) {
-    return;
-  }
-  const activation = (async () => {
-    integration.setConfig(options.appConfig);
-    integration.setRuntimeOrigin(options.runtimeOrigin);
-    await integration.setup();
-    const onRuntimePlugin = options.onRuntimePlugin ?? options.appConfig.runtime?.onRuntimePlugin;
-    for (const plugin of integration.plugins ?? []) {
-      onRuntimePlugin?.(plugin);
+/**
+ * Activates one integration's runtime setup on first use.
+ *
+ * @remarks
+ * Concurrent callers share a single in-flight promise per integration name.
+ * Failed activations are evicted so a later caller can retry.
+ */
+export async function ensureIntegrationRuntimeReady(options) {
+    const runtime = options.appConfig.runtime ?? {};
+    options.appConfig.runtime = runtime;
+    runtime.integrationActivations ??= new Map();
+    const existing = runtime.integrationActivations.get(options.integrationName);
+    if (existing) {
+        await existing;
+        return;
+    }
+    const integration = options.appConfig.integrations.find((plugin) => plugin.name === options.integrationName);
+    if (!integration) {
+        return;
+    }
+    const activation = (async () => {
+        integration.setConfig(options.appConfig);
+        integration.setRuntimeOrigin(options.runtimeOrigin);
+        await integration.setup();
+        const onRuntimePlugin = options.onRuntimePlugin ?? options.appConfig.runtime?.onRuntimePlugin;
+        for (const plugin of integration.plugins ?? []) {
+            onRuntimePlugin?.(plugin);
+        }
+    })();
+    runtime.integrationActivations.set(options.integrationName, activation);
+    try {
+        await activation;
+    }
+    catch (error) {
+        runtime.integrationActivations.delete(options.integrationName);
+        throw error;
     }
-  })();
-  runtime.integrationActivations.set(options.integrationName, activation);
-  try {
-    await activation;
-  } catch (error) {
-    runtime.integrationActivations.delete(options.integrationName);
-    throw error;
-  }
 }
-export {
-  collectConfiguredAppBuildManifestContributions,
-  ensureIntegrationRuntimeReady,
-  setupAppRuntimePlugins
-};

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

@@ -1,61 +1,58 @@
-class BrowserRuntimeManifestConflictError extends Error {
-  specifier;
-  existing;
-  incoming;
-  constructor(specifier, existing, incoming) {
-    super(
-      `Browser runtime asset conflict for ${specifier}: ${existing.owner} maps to ${existing.publicPath}, ${incoming.owner} maps to ${incoming.publicPath}`
-    );
-    this.name = "BrowserRuntimeManifestConflictError";
-    this.specifier = specifier;
-    this.existing = existing;
-    this.incoming = incoming;
-  }
+export class BrowserRuntimeManifestConflictError extends Error {
+    specifier;
+    existing;
+    incoming;
+    constructor(specifier, existing, incoming) {
+        super(`Browser runtime asset conflict for ${specifier}: ${existing.owner} maps to ${existing.publicPath}, ` +
+            `${incoming.owner} maps to ${incoming.publicPath}`);
+        this.name = 'BrowserRuntimeManifestConflictError';
+        this.specifier = specifier;
+        this.existing = existing;
+        this.incoming = incoming;
+    }
 }
 function normalizeDeclaration(declaration) {
-  return {
-    ...declaration,
-    externals: declaration.externals ?? []
-  };
+    return {
+        ...declaration,
+        externals: declaration.externals ?? [],
+    };
 }
 function hasCompatibleRuntimeAsset(existing, incoming) {
-  return existing.owner === incoming.owner && existing.importPath === incoming.importPath && existing.publicPath === incoming.publicPath && existing.mode === incoming.mode && arrayEquals(existing.externals, incoming.externals);
+    return (existing.owner === incoming.owner &&
+        existing.importPath === incoming.importPath &&
+        existing.publicPath === incoming.publicPath &&
+        existing.mode === incoming.mode &&
+        arrayEquals(existing.externals, incoming.externals));
 }
 function arrayEquals(left, right) {
-  if (left.length !== right.length) {
-    return false;
-  }
-  return left.every((value, index) => value === right[index]);
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((value, index) => value === right[index]);
 }
-function createBrowserRuntimeManifest(declarations = []) {
-  const assets = [];
-  const bySpecifier = /* @__PURE__ */ new Map();
-  for (const declaration of declarations) {
-    const asset = normalizeDeclaration(declaration);
-    const existing = bySpecifier.get(asset.specifier);
-    if (existing) {
-      if (!hasCompatibleRuntimeAsset(existing, asset)) {
-        throw new BrowserRuntimeManifestConflictError(asset.specifier, existing, asset);
-      }
-      continue;
+export function createBrowserRuntimeManifest(declarations = []) {
+    const assets = [];
+    const bySpecifier = new Map();
+    for (const declaration of declarations) {
+        const asset = normalizeDeclaration(declaration);
+        const existing = bySpecifier.get(asset.specifier);
+        if (existing) {
+            if (!hasCompatibleRuntimeAsset(existing, asset)) {
+                throw new BrowserRuntimeManifestConflictError(asset.specifier, existing, asset);
+            }
+            continue;
+        }
+        assets.push(asset);
+        bySpecifier.set(asset.specifier, asset);
     }
-    assets.push(asset);
-    bySpecifier.set(asset.specifier, asset);
-  }
-  return {
-    assets,
-    bySpecifier
-  };
+    return {
+        assets,
+        bySpecifier,
+    };
 }
-function mergeBrowserRuntimeManifests(...manifests) {
-  return createBrowserRuntimeManifest(manifests.flatMap((manifest) => manifest?.assets ?? []));
+export function mergeBrowserRuntimeManifests(...manifests) {
+    return createBrowserRuntimeManifest(manifests.flatMap((manifest) => manifest?.assets ?? []));
 }
-function getBrowserRuntimeSpecifierMap(manifest) {
-  return new Map(manifest.assets.map((asset) => [asset.specifier, asset.publicPath]));
+export function getBrowserRuntimeSpecifierMap(manifest) {
+    return new Map(manifest.assets.map((asset) => [asset.specifier, asset.publicPath]));
 }
-export {
-  BrowserRuntimeManifestConflictError,
-  createBrowserRuntimeManifest,
-  getBrowserRuntimeSpecifierMap,
-  mergeBrowserRuntimeManifests
-};

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

@@ -1,14 +1,34 @@
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Shared helpers for the browser-runtime plugin.
+ *
+ * @remarks
+ * `createBrowserRuntimePlugin` needs to:
+ *
+ * 1. Escape each specifier for inclusion in a regex filter.
+ * 2. Build a `RegExp` whose alternation matches any of those specifiers.
+ *
+ * These utilities are extracted here so the plugin does not duplicate
+ * the same code path.
+ */
+/**
+ * Escapes a literal specifier for inclusion in a regular expression.
+ *
+ * Only the regex metacharacters are escaped: `. * + ? ^ $ { } ( ) | [ ] \`
+ */
+export function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-function buildSpecifierFilter(specifierMap) {
-  if (specifierMap.size === 0) {
-    return null;
-  }
-  const alternation = Array.from(specifierMap.keys()).map(escapeRegExp).join("|");
-  return new RegExp(`^(${alternation})$`);
+/**
+ * Builds a `RegExp` whose alternation matches any of the keys in
+ * `specifierMap`.
+ *
+ * Returns `null` for an empty map so callers can short-circuit and
+ * avoid registering a no-op `onResolve` / `onLoad` filter.
+ */
+export function buildSpecifierFilter(specifierMap) {
+    if (specifierMap.size === 0) {
+        return null;
+    }
+    const alternation = Array.from(specifierMap.keys()).map(escapeRegExp).join('|');
+    return new RegExp(`^(${alternation})$`);
 }
-export {
-  buildSpecifierFilter,
-  escapeRegExp
-};