@ecopages/core 0.2.0-beta.31 → 0.2.0-beta.33

package/src/build/runtime/serialized-build-executor.js

@@ -1,63 +1,79 @@
-class SerializedBuildExecutor {
-  inner;
-  tail = Promise.resolve();
-  constructor(inner) {
-    this.inner = inner;
-  }
-  /**
-   * Run a build through the serialized queue. The returned promise
-   * resolves with the inner executor's `BuildResult`. A rejected
-   * inner build does not block the queue — the next caller can
-   * proceed.
-   */
-  build(options) {
-    return this.run(() => this.inner.build(options));
-  }
-  /**
-   * Run an arbitrary async operation through the serialized queue.
-   *
-   * Use this when the work is not a `build()` call against a wrapped
-   * executor (e.g. when composing with a coordinator that needs to
-   * inject recovery around the inner call). The returned promise
-   * resolves with the operation's result. A rejected operation does
-   * not block the queue.
-   */
-  run(operation) {
-    const next = this.tail.catch(() => void 0).then(() => operation());
-    this.tail = next.catch(() => void 0);
-    return next;
-  }
-  /**
-   * Returns the wrapped executor. Tests use this to assert the
-   * delegation chain.
-   */
-  unwrap() {
-    return this.inner;
-  }
-  /**
-   * Reset the queue to an empty state. Tests use this to recover
-   * from a poisoned tail.
-   */
-  resetForTests() {
-    this.tail = Promise.resolve();
-  }
-  /**
-   * Overrides the internal queue tail for fault-recovery tests. The
-   * supplied promise is awaited before the next enqueued operation
-   * starts.
-   */
-  setBuildQueueForTests(queue) {
-    this.tail = queue;
-  }
-  /**
-   * Returns the current internal queue tail for fault-recovery
-   * tests. Tests await this to assert that recovery has cleared a
-   * wedged queue.
-   */
-  getBuildQueueForTests() {
-    return this.tail;
-  }
+/**
+ * FIFO-serialized build executor wrapper.
+ *
+ * @remarks
+ * Wraps any `BuildExecutor` and ensures that no two builds run
+ * concurrently. The next build waits for the previous one to finish
+ * (success or failure) before starting.
+ *
+ * This is a bundler-agnostic primitive. It is unaware of bundler
+ * lifecycle events and exists purely to enforce one build at a time.
+ * Use it from the dev watch pipeline, the static preview path, or any
+ * caller that issues builds concurrently.
+ */
+/**
+ * FIFO-serialized wrapper around a {@link BuildExecutor}.
+ *
+ * Every `build()` call enqueues onto the wrapper's internal queue. A
+ * build only starts after the previous build's promise has settled.
+ */
+export class SerializedBuildExecutor {
+    inner;
+    tail = Promise.resolve();
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /**
+     * Run a build through the serialized queue. The returned promise
+     * resolves with the inner executor's `BuildResult`. A rejected
+     * inner build does not block the queue — the next caller can
+     * proceed.
+     */
+    build(options) {
+        return this.run(() => this.inner.build(options));
+    }
+    /**
+     * Run an arbitrary async operation through the serialized queue.
+     *
+     * Use this when the work is not a `build()` call against a wrapped
+     * executor (e.g. when composing with a coordinator that needs to
+     * inject recovery around the inner call). The returned promise
+     * resolves with the operation's result. A rejected operation does
+     * not block the queue.
+     */
+    run(operation) {
+        const next = this.tail.catch(() => undefined).then(() => operation());
+        this.tail = next.catch(() => undefined);
+        return next;
+    }
+    /**
+     * Returns the wrapped executor. Tests use this to assert the
+     * delegation chain.
+     */
+    unwrap() {
+        return this.inner;
+    }
+    /**
+     * Reset the queue to an empty state. Tests use this to recover
+     * from a poisoned tail.
+     */
+    resetForTests() {
+        this.tail = Promise.resolve();
+    }
+    /**
+     * Overrides the internal queue tail for fault-recovery tests. The
+     * supplied promise is awaited before the next enqueued operation
+     * starts.
+     */
+    setBuildQueueForTests(queue) {
+        this.tail = queue;
+    }
+    /**
+     * Returns the current internal queue tail for fault-recovery
+     * tests. Tests await this to assert that recovery has cleared a
+     * wedged queue.
+     */
+    getBuildQueueForTests() {
+        return this.tail;
+    }
 }
-export {
-  SerializedBuildExecutor
-};

package/src/cache/index.js

@@ -1,6 +1,6 @@
-import { ModuleParseCache, moduleParseCache, cachedParseSync } from "./module-parse-cache.js";
-export {
-  ModuleParseCache,
-  cachedParseSync,
-  moduleParseCache
-};
+/**
+ * Public cache exports for the bundler plugin chain.
+ *
+ * @module @ecopages/core/cache
+ */
+export { ModuleParseCache, moduleParseCache, cachedParseSync } from './module-parse-cache.js';

package/src/cache/module-parse-cache.js

@@ -1,75 +1,106 @@
-import { parseSync } from "oxc-parser";
-import { rapidhash } from "../utils/hash.js";
-const DEFAULT_MAX_ENTRIES = 1e4;
-class ModuleParseCache {
-  entries = /* @__PURE__ */ new Map();
-  maxEntries;
-  hits = 0;
-  misses = 0;
-  constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
-    if (maxEntries <= 0) {
-      throw new Error(`ModuleParseCache: maxEntries must be > 0, got ${maxEntries}`);
+/**
+ * Process-wide parse cache for `oxc-parser.parseSync`.
+ *
+ * @remarks
+ * Several build plugins (eco-component-meta, client-graph-boundary,
+ * browser-runtime) each call `parseSync` on the same source file with
+ * overlapping options. This cache memoizes the parse result keyed by
+ * `(absolute path, source, options)`. When the source is unchanged,
+ * subsequent calls return the cached result without re-parsing.
+ *
+ * The cache is LRU-bounded (10 000 entries) and key-stable across a
+ * single HMR session. It is **content-hashed** rather than
+ * mtime-hashed so that `touch`/`utimes` does not invalidate a
+ * still-valid parse.
+ */
+import { parseSync } from 'oxc-parser';
+import { rapidhash } from '../utils/hash.js';
+const DEFAULT_MAX_ENTRIES = 10_000;
+/**
+ * LRU-bounded module parse cache.
+ *
+ * Single instance shared across the process. Constructed lazily; use
+ * {@link moduleParseCache} for the default shared instance.
+ */
+export class ModuleParseCache {
+    entries = new Map();
+    maxEntries;
+    hits = 0;
+    misses = 0;
+    constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
+        if (maxEntries <= 0) {
+            throw new Error(`ModuleParseCache: maxEntries must be > 0, got ${maxEntries}`);
+        }
+        this.maxEntries = maxEntries;
     }
-    this.maxEntries = maxEntries;
-  }
-  /**
-   * Parse `source` for `filePath`, memoizing by (filePath, source, options).
-   *
-   * @returns the {@link ParseResult} from `oxc-parser.parseSync`.
-   */
-  getOrParse(filePath, source, options = {}) {
-    const hash = rapidhash(source);
-    const key = makeKey(filePath, hash, options);
-    const existing = this.entries.get(key);
-    if (existing && existing.hash === hash) {
-      this.hits += 1;
-      this.entries.delete(key);
-      this.entries.set(key, existing);
-      return existing.result;
+    /**
+     * Parse `source` for `filePath`, memoizing by (filePath, source, options).
+     *
+     * @returns the {@link ParseResult} from `oxc-parser.parseSync`.
+     */
+    getOrParse(filePath, source, options = {}) {
+        const hash = rapidhash(source);
+        const key = makeKey(filePath, hash, options);
+        const existing = this.entries.get(key);
+        if (existing && existing.hash === hash) {
+            this.hits += 1;
+            // Refresh LRU position.
+            this.entries.delete(key);
+            this.entries.set(key, existing);
+            return existing.result;
+        }
+        this.misses += 1;
+        const result = parseSync(filePath, source, options);
+        this.entries.set(key, { hash, result });
+        if (this.entries.size > this.maxEntries) {
+            // Map iteration order is insertion order; the first key is the
+            // least recently used (we delete-then-set on hits, so the
+            // oldest still-present entry is the LRU one).
+            const oldestKey = this.entries.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.entries.delete(oldestKey);
+            }
+        }
+        return result;
     }
-    this.misses += 1;
-    const result = parseSync(filePath, source, options);
-    this.entries.set(key, { hash, result });
-    if (this.entries.size > this.maxEntries) {
-      const oldestKey = this.entries.keys().next().value;
-      if (oldestKey !== void 0) {
-        this.entries.delete(oldestKey);
-      }
+    /** Clear all cached entries. Useful in tests and on full-rebuild signals. */
+    clear() {
+        this.entries.clear();
+        this.hits = 0;
+        this.misses = 0;
+    }
+    /** Current cache size (for observability). */
+    get size() {
+        return this.entries.size;
+    }
+    /** Cumulative hit/miss counters (for observability). */
+    stats() {
+        const total = this.hits + this.misses;
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            size: this.entries.size,
+            hitRate: total === 0 ? 0 : this.hits / total,
+        };
     }
-    return result;
-  }
-  /** Clear all cached entries. Useful in tests and on full-rebuild signals. */
-  clear() {
-    this.entries.clear();
-    this.hits = 0;
-    this.misses = 0;
-  }
-  /** Current cache size (for observability). */
-  get size() {
-    return this.entries.size;
-  }
-  /** Cumulative hit/miss counters (for observability). */
-  stats() {
-    const total = this.hits + this.misses;
-    return {
-      hits: this.hits,
-      misses: this.misses,
-      size: this.entries.size,
-      hitRate: total === 0 ? 0 : this.hits / total
-    };
-  }
 }
-const moduleParseCache = new ModuleParseCache();
-function cachedParseSync(filePath, source, options = {}) {
-  return moduleParseCache.getOrParse(filePath, source, options);
+/**
+ * Default shared cache. Use this from plugin code so the cache is
+ * amortized across plugins and build invocations.
+ */
+export const moduleParseCache = new ModuleParseCache();
+/**
+ * Drop-in replacement for `oxc-parser.parseSync` that uses the shared
+ * {@link moduleParseCache}. Use everywhere we currently call `parseSync`
+ * on user/source files during a build.
+ */
+export function cachedParseSync(filePath, source, options = {}) {
+    return moduleParseCache.getOrParse(filePath, source, options);
 }
 function makeKey(filePath, sourceHash, options) {
-  const lang = options.lang ?? "";
-  const sourceType = options.sourceType ?? "";
-  return `${filePath} ${sourceHash.toString(36)} ${lang} ${sourceType}`;
+    // Stringify only the option keys we actually use; `parseSync` does
+    // not deeply equal-check options so any extra keys would be noise.
+    const lang = options.lang ?? '';
+    const sourceType = options.sourceType ?? '';
+    return `${filePath} ${sourceHash.toString(36)} ${lang} ${sourceType}`;
 }
-export {
-  ModuleParseCache,
-  cachedParseSync,
-  moduleParseCache
-};

package/src/client/navigation-scripts/classification.js

@@ -1,41 +1,49 @@
-const EXECUTABLE_SCRIPT_TYPES = /* @__PURE__ */ new Set([
-  "application/javascript",
-  "application/ecmascript",
-  "module",
-  "text/ecmascript",
-  "text/javascript"
+/**
+ * Classifies head scripts for navigation-time persistence and execution.
+ * @module
+ */
+const EXECUTABLE_SCRIPT_TYPES = new Set([
+    'application/javascript',
+    'application/ecmascript',
+    'module',
+    'text/ecmascript',
+    'text/javascript',
 ]);
-function isNonExecutableHeadScript(element) {
-  if (element.tagName !== "SCRIPT") {
-    return false;
-  }
-  const type = (element.getAttribute("type") ?? "").trim().toLowerCase();
-  if (!type) {
-    return false;
-  }
-  return !EXECUTABLE_SCRIPT_TYPES.has(type);
+/**
+ * Returns whether a script tag carries non-executable data (for example JSON-LD).
+ */
+export function isNonExecutableHeadScript(element) {
+    if (element.tagName !== 'SCRIPT') {
+        return false;
+    }
+    const type = (element.getAttribute('type') ?? '').trim().toLowerCase();
+    if (!type) {
+        return false;
+    }
+    return !EXECUTABLE_SCRIPT_TYPES.has(type);
 }
-function shouldPersistExecutableInlineHeadScript(element) {
-  if (element.tagName !== "SCRIPT") {
-    return false;
-  }
-  const scriptId = element.getAttribute("data-eco-script-id") || element.getAttribute("id");
-  if (!scriptId) {
-    return false;
-  }
-  if (element.hasAttribute("data-eco-rerun")) {
-    return false;
-  }
-  if (element.src) {
-    return false;
-  }
-  return !isNonExecutableHeadScript(element);
+/**
+ * Returns whether an identified inline head script should survive head diffing.
+ */
+export function shouldPersistExecutableInlineHeadScript(element) {
+    if (element.tagName !== 'SCRIPT') {
+        return false;
+    }
+    const scriptId = element.getAttribute('data-eco-script-id') || element.getAttribute('id');
+    if (!scriptId) {
+        return false;
+    }
+    if (element.hasAttribute('data-eco-rerun')) {
+        return false;
+    }
+    if (element.src) {
+        return false;
+    }
+    return !isNonExecutableHeadScript(element);
 }
-function isRerunScript(element) {
-  return element.tagName === "SCRIPT" && element.hasAttribute("data-eco-rerun");
+/**
+ * Returns whether a script is queued for rerun after navigation commit.
+ */
+export function isRerunScript(element) {
+    return element.tagName === 'SCRIPT' && element.hasAttribute('data-eco-rerun');
 }
-export {
-  isNonExecutableHeadScript,
-  isRerunScript,
-  shouldPersistExecutableInlineHeadScript
-};

package/src/client/navigation-scripts/index.js

@@ -1,23 +1,3 @@
-import { isNonExecutableHeadScript, isRerunScript, shouldPersistExecutableInlineHeadScript } from "./classification.js";
-import { RERUN_SRC_ATTR, getRegisteredRerunScript } from "./registry.js";
-import {
-  collectRerunScripts,
-  createRerunScriptUrl,
-  findExistingRerunScript,
-  flushPendingRerunScripts,
-  isExternalModuleRerunScript,
-  resetRerunNonceForTests
-} from "./rerun-queue.js";
-export {
-  RERUN_SRC_ATTR,
-  collectRerunScripts,
-  createRerunScriptUrl,
-  findExistingRerunScript,
-  flushPendingRerunScripts,
-  getRegisteredRerunScript,
-  isExternalModuleRerunScript,
-  isNonExecutableHeadScript,
-  isRerunScript,
-  resetRerunNonceForTests,
-  shouldPersistExecutableInlineHeadScript
-};
+export { isNonExecutableHeadScript, isRerunScript, shouldPersistExecutableInlineHeadScript } from './classification.js';
+export { RERUN_SRC_ATTR, getRegisteredRerunScript } from './registry.js';
+export { collectRerunScripts, createRerunScriptUrl, findExistingRerunScript, flushPendingRerunScripts, isExternalModuleRerunScript, resetRerunNonceForTests, } from './rerun-queue.js';

package/src/client/navigation-scripts/navigation-scripts.test.browser.js

@@ -1,65 +1,61 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { isNonExecutableHeadScript } from "./classification.js";
-import {
-  collectRerunScripts,
-  createRerunScriptUrl,
-  flushPendingRerunScripts,
-  resetRerunNonceForTests
-} from "./rerun-queue.js";
-import { RERUN_SRC_ATTR } from "./registry.js";
-describe("isNonExecutableHeadScript", () => {
-  it("treats JSON-LD scripts as non-executable", () => {
-    const script = document.createElement("script");
-    script.type = "application/ld+json";
-    expect(isNonExecutableHeadScript(script)).toBe(true);
-  });
-  it("treats untyped scripts as executable", () => {
-    const script = document.createElement("script");
-    expect(isNonExecutableHeadScript(script)).toBe(false);
-  });
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { isNonExecutableHeadScript } from './classification.js';
+import { collectRerunScripts, createRerunScriptUrl, flushPendingRerunScripts, resetRerunNonceForTests, } from './rerun-queue.js';
+import { RERUN_SRC_ATTR } from './registry.js';
+describe('isNonExecutableHeadScript', () => {
+    it('treats JSON-LD scripts as non-executable', () => {
+        const script = document.createElement('script');
+        script.type = 'application/ld+json';
+        expect(isNonExecutableHeadScript(script)).toBe(true);
+    });
+    it('treats untyped scripts as executable', () => {
+        const script = document.createElement('script');
+        expect(isNonExecutableHeadScript(script)).toBe(false);
+    });
 });
-describe("collectRerunScripts and flushPendingRerunScripts", () => {
-  afterEach(() => {
-    document.head.replaceChildren();
-    document.body.replaceChildren();
-    resetRerunNonceForTests();
-  });
-  it("replays registered rerun callbacks without duplicating script tags", () => {
-    const callback = vi.fn();
-    window.__ECO_PAGES__ = {
-      rerunScripts: { "eco-test": callback }
-    };
-    try {
-      flushPendingRerunScripts([
-        {
-          parent: "head",
-          attributes: [
-            ["data-eco-rerun", ""],
-            ["data-eco-script-id", "eco-test"]
-          ],
-          textContent: "",
-          src: null,
-          scriptId: "eco-test"
+describe('collectRerunScripts and flushPendingRerunScripts', () => {
+    afterEach(() => {
+        document.head.replaceChildren();
+        document.body.replaceChildren();
+        resetRerunNonceForTests();
+    });
+    it('replays registered rerun callbacks without duplicating script tags', () => {
+        const callback = vi.fn();
+        window.__ECO_PAGES__ = {
+            rerunScripts: { 'eco-test': callback },
+        };
+        try {
+            flushPendingRerunScripts([
+                {
+                    parent: 'head',
+                    attributes: [
+                        ['data-eco-rerun', ''],
+                        ['data-eco-script-id', 'eco-test'],
+                    ],
+                    textContent: '',
+                    src: null,
+                    scriptId: 'eco-test',
+                },
+            ]);
+            expect(callback).toHaveBeenCalledOnce();
+            expect(document.head.querySelector('script[data-eco-script-id="eco-test"]')).toBeNull();
         }
-      ]);
-      expect(callback).toHaveBeenCalledOnce();
-      expect(document.head.querySelector('script[data-eco-script-id="eco-test"]')).toBeNull();
-    } finally {
-      delete window.__ECO_PAGES__;
-    }
-  });
-  it("cache-busts external module rerun scripts", () => {
-    const html = '<html><head><script data-eco-rerun src="/app.js" type="module"><\/script></head></html>';
-    const parsed = new DOMParser().parseFromString(html, "text/html");
-    const scripts = collectRerunScripts(parsed);
-    flushPendingRerunScripts(scripts);
-    const inserted = document.head.querySelector(`script[${RERUN_SRC_ATTR}]`);
-    expect(inserted?.getAttribute("src")).toMatch(/__eco_rerun=1/);
-    expect(inserted?.getAttribute(RERUN_SRC_ATTR)).toBe("/app.js");
-  });
-  it("appends a unique nonce on each module rerun url", () => {
-    const first = createRerunScriptUrl("/app.js");
-    const second = createRerunScriptUrl("/app.js");
-    expect(first).not.toBe(second);
-  });
+        finally {
+            delete window.__ECO_PAGES__;
+        }
+    });
+    it('cache-busts external module rerun scripts', () => {
+        const html = '<html><head><script data-eco-rerun src="/app.js" type="module"></script></head></html>';
+        const parsed = new DOMParser().parseFromString(html, 'text/html');
+        const scripts = collectRerunScripts(parsed);
+        flushPendingRerunScripts(scripts);
+        const inserted = document.head.querySelector(`script[${RERUN_SRC_ATTR}]`);
+        expect(inserted?.getAttribute('src')).toMatch(/__eco_rerun=1/);
+        expect(inserted?.getAttribute(RERUN_SRC_ATTR)).toBe('/app.js');
+    });
+    it('appends a unique nonce on each module rerun url', () => {
+        const first = createRerunScriptUrl('/app.js');
+        const second = createRerunScriptUrl('/app.js');
+        expect(first).not.toBe(second);
+    });
 });

package/src/client/navigation-scripts/registry.js

@@ -1,12 +1,16 @@
-const RERUN_SRC_ATTR = "data-eco-rerun-src";
-function getRegisteredRerunScript(scriptId) {
-  if (!scriptId) {
-    return null;
-  }
-  const runtimeWindow = window;
-  return runtimeWindow.__ECO_PAGES__?.rerunScripts?.[scriptId] ?? null;
+/**
+ * `__ECO_PAGES__.rerunScripts` registry access for navigation reruns.
+ * @module
+ */
+/** Attribute storing the original module `src` after cache-busting. */
+export const RERUN_SRC_ATTR = 'data-eco-rerun-src';
+/**
+ * Returns a registered in-memory rerun callback for the given script id.
+ */
+export function getRegisteredRerunScript(scriptId) {
+    if (!scriptId) {
+        return null;
+    }
+    const runtimeWindow = window;
+    return runtimeWindow.__ECO_PAGES__?.rerunScripts?.[scriptId] ?? null;
 }
-export {
-  RERUN_SRC_ATTR,
-  getRegisteredRerunScript
-};