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

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

@@ -0,0 +1,28 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import { type BuildExecutor } from '../build-adapter.js';
+export type BuildProfile = 'server-entry' | 'route-module' | 'browser-hmr';
+export interface BuildRuntime {
+    getProfile(profile: BuildProfile): BuildExecutor;
+    dispose(): Promise<void>;
+}
+export declare function getBuildRuntime(appConfig: EcoPagesAppConfig): BuildRuntime | undefined;
+/**
+ * Returns the installed build runtime, installing it when missing.
+ */
+export declare function requireBuildRuntime(appConfig: EcoPagesAppConfig): BuildRuntime;
+/**
+ * Installs profile-based build executors for one app instance.
+ *
+ * @remarks
+ * For Rolldown ownership, server-entry stays serialized single-flight while
+ * route-module and browser-HMR run in parallel one-shot builds. Vite-host
+ * profiles wrap a boundary marker and reject framework-owned build attempts.
+ * Profiles do not inject app plugins — assemble complete
+ * {@link BuildOptions} with {@link createServerBuildRequest} /
+ * {@link createBrowserBuildRequest} (or {@link BrowserBundleService}) first.
+ */
+export declare function installBuildRuntime(appConfig: EcoPagesAppConfig): BuildRuntime;
+/**
+ * No-op retained for server teardown call sites.
+ */
+export declare function disposeAppBuildRuntime(appConfig: EcoPagesAppConfig): Promise<void>;

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

@@ -0,0 +1,65 @@
+import { availableParallelism } from "node:os";
+import { getAppBuildAdapter } from "../build-adapter.js";
+import { ParallelBuildExecutor } from "./parallel-build-executor.js";
+import { DedupingBuildExecutor } from "./deduping-build-executor.js";
+import { SerializedBuildExecutor } from "./serialized-build-executor.js";
+function resolveParallelismLimit() {
+  return Math.max(1, availableParallelism() - 1);
+}
+function patchAppRuntime(appConfig, patch) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    ...patch
+  };
+}
+class AppBuildRuntime {
+  serverEntryExecutor;
+  routeModuleExecutor;
+  hmrExecutor;
+  constructor(appConfig) {
+    const adapter = getAppBuildAdapter(appConfig);
+    const limit = resolveParallelismLimit();
+    this.serverEntryExecutor = new SerializedBuildExecutor(adapter);
+    this.routeModuleExecutor = new DedupingBuildExecutor(new ParallelBuildExecutor(adapter, limit));
+    this.hmrExecutor = new DedupingBuildExecutor(new ParallelBuildExecutor(adapter, Math.min(3, limit)));
+  }
+  getProfile(profile) {
+    switch (profile) {
+      case "server-entry":
+        return this.serverEntryExecutor;
+      case "route-module":
+        return this.routeModuleExecutor;
+      case "browser-hmr":
+        return this.hmrExecutor;
+    }
+  }
+  /**
+   * No-op for profile teardown.
+   *
+   * @remarks
+   * Rolldown-owned profiles use one-shot builds, and Vite-host profiles only
+   * wrap a boundary marker. Neither owns a long-lived engine to close.
+   */
+  async dispose() {
+  }
+}
+function getBuildRuntime(appConfig) {
+  return appConfig.runtime?.buildRuntime;
+}
+function requireBuildRuntime(appConfig) {
+  return getBuildRuntime(appConfig) ?? installBuildRuntime(appConfig);
+}
+function installBuildRuntime(appConfig) {
+  const buildRuntime = new AppBuildRuntime(appConfig);
+  patchAppRuntime(appConfig, { buildRuntime });
+  return buildRuntime;
+}
+async function disposeAppBuildRuntime(appConfig) {
+  await getBuildRuntime(appConfig)?.dispose();
+}
+export {
+  disposeAppBuildRuntime,
+  getBuildRuntime,
+  installBuildRuntime,
+  requireBuildRuntime
+};

package/src/build/runtime/deduping-build-executor.d.ts

@@ -0,0 +1,21 @@
+import type { BuildExecutor, BuildOptions, BuildResult } from '../build-adapter.js';
+export { createBuildRequestIdentity, createBuildOptionsDedupeKey } from './build-request-identity.js';
+/**
+ * In-flight build coalescing wrapper.
+ *
+ * @remarks
+ * `ParallelBuildExecutor` allows concurrent builds but does not dedupe identical
+ * options. Multiple callers (route import, browser bundles, HMR) can hit the
+ * same Rolldown request before disk or import caches warm. This wrapper shares
+ * one inner `build()` promise per dedupe key until it settles.
+ *
+ * Wrap route-module and browser-hmr profiles only; server-entry stays serialized.
+ */
+export declare class DedupingBuildExecutor implements BuildExecutor {
+    private readonly inner;
+    private readonly inFlight;
+    constructor(inner: BuildExecutor);
+    build(options: BuildOptions): Promise<BuildResult>;
+    unwrap(): BuildExecutor;
+    getInFlightCountForTests(): number;
+}

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

@@ -0,0 +1,34 @@
+import { createBuildRequestIdentity } from "./build-request-identity.js";
+import { createBuildRequestIdentity as createBuildRequestIdentity2, createBuildOptionsDedupeKey } from "./build-request-identity.js";
+class DedupingBuildExecutor {
+  inner;
+  inFlight = /* @__PURE__ */ new Map();
+  constructor(inner) {
+    this.inner = inner;
+  }
+  build(options) {
+    const key = createBuildRequestIdentity(options);
+    const existing = this.inFlight.get(key);
+    if (existing) {
+      return existing;
+    }
+    const buildPromise = this.inner.build(options).finally(() => {
+      if (this.inFlight.get(key) === buildPromise) {
+        this.inFlight.delete(key);
+      }
+    });
+    this.inFlight.set(key, buildPromise);
+    return buildPromise;
+  }
+  unwrap() {
+    return this.inner;
+  }
+  getInFlightCountForTests() {
+    return this.inFlight.size;
+  }
+}
+export {
+  DedupingBuildExecutor,
+  createBuildOptionsDedupeKey,
+  createBuildRequestIdentity2 as createBuildRequestIdentity
+};

package/src/build/runtime/parallel-build-executor.d.ts

@@ -0,0 +1,21 @@
+import type { BuildExecutor, BuildOptions, BuildResult } from '../build-adapter.js';
+/**
+ * Concurrency-limited build executor wrapper.
+ *
+ * @remarks
+ * Runs up to `limit` builds concurrently. Use for independent route-module
+ * and HMR browser builds where FIFO serialization is unnecessary.
+ */
+export declare class ParallelBuildExecutor implements BuildExecutor {
+    private readonly inner;
+    private readonly limit;
+    private activeCount;
+    private queue;
+    constructor(inner: BuildExecutor, limit: number);
+    build(options: BuildOptions): Promise<BuildResult>;
+    private drainQueue;
+    unwrap(): BuildExecutor;
+    getConcurrencyLimitForTests(): number;
+    getActiveCountForTests(): number;
+    getQueuedCountForTests(): number;
+}

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

@@ -0,0 +1,52 @@
+class ParallelBuildExecutor {
+  inner;
+  limit;
+  activeCount = 0;
+  queue = [];
+  constructor(inner, limit) {
+    this.inner = inner;
+    this.limit = Math.max(1, limit);
+  }
+  build(options) {
+    return new Promise((resolve, reject) => {
+      this.queue.push({
+        operation: () => this.inner.build(options),
+        resolve,
+        reject
+      });
+      this.drainQueue();
+    });
+  }
+  drainQueue() {
+    while (this.activeCount < this.limit && this.queue.length > 0) {
+      const next = this.queue.shift();
+      if (!next) {
+        return;
+      }
+      this.activeCount += 1;
+      void next.operation().then((result) => {
+        next.resolve(result);
+      }).catch((error) => {
+        next.reject(error);
+      }).finally(() => {
+        this.activeCount -= 1;
+        this.drainQueue();
+      });
+    }
+  }
+  unwrap() {
+    return this.inner;
+  }
+  getConcurrencyLimitForTests() {
+    return this.limit;
+  }
+  getActiveCountForTests() {
+    return this.activeCount;
+  }
+  getQueuedCountForTests() {
+    return this.queue.length;
+  }
+}
+export {
+  ParallelBuildExecutor
+};

package/src/build/{serialized-build-executor.d.ts → runtime/serialized-build-executor.d.ts}

@@ -1,4 +1,4 @@
-import type { BuildExecutor, BuildOptions, BuildResult } from './build-adapter.js';
+import type { BuildExecutor, BuildOptions, BuildResult } from '../build-adapter.js';
 /**
  * FIFO-serialized build executor wrapper.
  *

package/src/client/navigation-scripts/classification.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Classifies head scripts for navigation-time persistence and execution.
+ * @module
+ */
+/**
+ * Returns whether a script tag carries non-executable data (for example JSON-LD).
+ */
+export declare function isNonExecutableHeadScript(element: Element): boolean;
+/**
+ * Returns whether an identified inline head script should survive head diffing.
+ */
+export declare function shouldPersistExecutableInlineHeadScript(element: Element): boolean;
+/**
+ * Returns whether a script is queued for rerun after navigation commit.
+ */
+export declare function isRerunScript(element: Element): element is HTMLScriptElement;

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

@@ -0,0 +1,41 @@
+const EXECUTABLE_SCRIPT_TYPES = /* @__PURE__ */ 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);
+}
+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");
+}
+export {
+  isNonExecutableHeadScript,
+  isRerunScript,
+  shouldPersistExecutableInlineHeadScript
+};

package/src/client/navigation-scripts/index.d.ts

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

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

@@ -0,0 +1,23 @@
+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
+};

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

@@ -0,0 +1,65 @@
+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"
+        }
+      ]);
+      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);
+  });
+});

package/src/client/navigation-scripts/registry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `__ECO_PAGES__.rerunScripts` registry access for navigation reruns.
+ * @module
+ */
+export type RerunScriptCallback = () => void;
+/** Attribute storing the original module `src` after cache-busting. */
+export declare const RERUN_SRC_ATTR = "data-eco-rerun-src";
+/**
+ * Returns a registered in-memory rerun callback for the given script id.
+ */
+export declare function getRegisteredRerunScript(scriptId: string | null): RerunScriptCallback | null;

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

@@ -0,0 +1,12 @@
+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;
+}
+export {
+  RERUN_SRC_ATTR,
+  getRegisteredRerunScript
+};

package/src/client/navigation-scripts/rerun-queue.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Queueing and replay of `data-eco-rerun` scripts after navigation.
+ * @module
+ */
+export type PendingRerunScript = {
+    parent: 'head' | 'body';
+    attributes: Array<[string, string]>;
+    textContent: string;
+    src: string | null;
+    scriptId: string | null;
+};
+/**
+ * Collects rerun scripts from an incoming document.
+ */
+export declare function collectRerunScripts(document: Document, filter?: (script: HTMLScriptElement) => boolean): PendingRerunScript[];
+/**
+ * Returns whether a rerun script is an external ES module that needs cache busting.
+ */
+export declare function isExternalModuleRerunScript(script: PendingRerunScript): boolean;
+/**
+ * Finds an existing rerun script in `root` by id or by src and inline content.
+ */
+export declare function findExistingRerunScript(root: ParentNode, script: PendingRerunScript): HTMLScriptElement | null;
+/**
+ * Appends a nonce query parameter so module scripts re-execute after navigation.
+ */
+export declare function createRerunScriptUrl(src: string): string;
+/**
+ * Replays queued rerun scripts after the incoming page body is in place.
+ *
+ * @remarks
+ * Flushed elements keep `data-eco-rerun` so head cleanup does not treat them
+ * as persistable inline scripts on the next navigation.
+ */
+export declare function flushPendingRerunScripts(scripts: readonly PendingRerunScript[]): void;
+/** @remarks Test-only reset for nonce sequencing. */
+export declare function resetRerunNonceForTests(): void;

package/src/client/navigation-scripts/rerun-queue.js

@@ -0,0 +1,73 @@
+import { RERUN_SRC_ATTR, getRegisteredRerunScript } from "./registry.js";
+let rerunNonce = 0;
+function collectRerunScripts(document2, filter) {
+  return Array.from(document2.querySelectorAll("script[data-eco-rerun]")).filter((script) => filter ? filter(script) : true).map((script) => ({
+    parent: script.closest("body") ? "body" : "head",
+    attributes: Array.from(script.attributes).map((attribute) => [attribute.name, attribute.value]),
+    textContent: script.textContent ?? "",
+    src: script.getAttribute("src"),
+    scriptId: script.getAttribute("data-eco-script-id")
+  }));
+}
+function isExternalModuleRerunScript(script) {
+  if (!script.src) {
+    return false;
+  }
+  return script.attributes.some(([name, value]) => name === "type" && value === "module");
+}
+function findExistingRerunScript(root, script) {
+  const scripts = Array.from(root.querySelectorAll("script"));
+  if (script.scriptId) {
+    return scripts.find((candidate) => candidate.getAttribute("data-eco-script-id") === script.scriptId) ?? null;
+  }
+  return scripts.find(
+    (candidate) => (candidate.getAttribute(RERUN_SRC_ATTR) ?? candidate.getAttribute("src")) === script.src && (candidate.textContent ?? "") === script.textContent
+  ) ?? null;
+}
+function createRerunScriptUrl(src) {
+  const url = new URL(src, document.baseURI);
+  url.searchParams.set("__eco_rerun", String(++rerunNonce));
+  return url.toString();
+}
+function flushPendingRerunScripts(scripts) {
+  for (const script of scripts) {
+    const targetParent = script.parent === "body" ? document.body : document.head;
+    const registeredRerun = getRegisteredRerunScript(script.scriptId);
+    const replacement = document.createElement("script");
+    const shouldBustModuleSrc = isExternalModuleRerunScript(script) && !registeredRerun;
+    for (const [name, value] of script.attributes) {
+      if (name === "src" && shouldBustModuleSrc) {
+        replacement.setAttribute(RERUN_SRC_ATTR, value);
+        replacement.setAttribute("src", createRerunScriptUrl(value));
+        continue;
+      }
+      replacement.setAttribute(name, value);
+    }
+    replacement.textContent = script.textContent;
+    const existingScript = findExistingRerunScript(targetParent, script);
+    if (registeredRerun) {
+      const needsScriptElement = isExternalModuleRerunScript(script);
+      if (!existingScript && needsScriptElement) {
+        targetParent.appendChild(replacement);
+      }
+      registeredRerun();
+      continue;
+    }
+    if (existingScript) {
+      existingScript.replaceWith(replacement);
+      continue;
+    }
+    targetParent.appendChild(replacement);
+  }
+}
+function resetRerunNonceForTests() {
+  rerunNonce = 0;
+}
+export {
+  collectRerunScripts,
+  createRerunScriptUrl,
+  findExistingRerunScript,
+  flushPendingRerunScripts,
+  isExternalModuleRerunScript,
+  resetRerunNonceForTests
+};

package/src/client/scroll.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Window scroll behavior during client-side navigations.
+ * @module
+ */
+export type WindowScrollBehavior = 'top' | 'preserve' | 'auto';
+export type ManageWindowScrollOptions = {
+    scrollBehavior: WindowScrollBehavior;
+    smoothScroll: boolean;
+};
+/**
+ * Updates window scroll position after a navigation commit.
+ *
+ * @remarks
+ * Hash navigations always scroll to the target element and ignore `scrollBehavior`.
+ * Fragment targets are resolved by element id (`#section` → `getElementById('section')`).
+ */
+export declare function manageWindowScroll(newUrl: URL, previousUrl: URL, options: ManageWindowScrollOptions): void;

package/src/client/scroll.js

@@ -0,0 +1,25 @@
+function manageWindowScroll(newUrl, previousUrl, options) {
+  const { scrollBehavior, smoothScroll } = options;
+  if (newUrl.hash) {
+    const target = document.getElementById(newUrl.hash.slice(1));
+    target?.scrollIntoView({ behavior: smoothScroll ? "smooth" : "instant" });
+    return;
+  }
+  const behavior = smoothScroll ? "smooth" : "instant";
+  switch (scrollBehavior) {
+    case "preserve":
+      break;
+    case "auto":
+      if (newUrl.pathname !== previousUrl.pathname) {
+        window.scrollTo({ top: 0, left: 0, behavior });
+      }
+      break;
+    case "top":
+    default:
+      window.scrollTo({ top: 0, left: 0, behavior });
+      break;
+  }
+}
+export {
+  manageWindowScroll
+};

package/src/client/scroll.test.browser.js

@@ -0,0 +1,37 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { manageWindowScroll } from "./scroll.js";
+const options = { scrollBehavior: "top", smoothScroll: false };
+describe("manageWindowScroll", () => {
+  afterEach(() => {
+    history.replaceState({}, "", "/");
+    document.body.replaceChildren();
+    vi.restoreAllMocks();
+  });
+  it("scrolls to top by default", () => {
+    const scrollTo = vi.spyOn(window, "scrollTo").mockImplementation(() => {
+    });
+    manageWindowScroll(new URL("/next", window.location.origin), new URL("/prev", window.location.origin), options);
+    expect(scrollTo).toHaveBeenCalledWith({ top: 0, left: 0, behavior: "instant" });
+  });
+  it("preserves scroll when scrollBehavior is preserve", () => {
+    const scrollTo = vi.spyOn(window, "scrollTo").mockImplementation(() => {
+    });
+    manageWindowScroll(new URL("/next", window.location.origin), new URL("/prev", window.location.origin), {
+      ...options,
+      scrollBehavior: "preserve"
+    });
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+  it("scrolls to hash target by element id", () => {
+    const section = document.createElement("section");
+    section.id = "section";
+    section.scrollIntoView = vi.fn();
+    document.body.append(section);
+    manageWindowScroll(
+      new URL("/page#section", window.location.origin),
+      new URL("/page", window.location.origin),
+      options
+    );
+    expect(section.scrollIntoView).toHaveBeenCalledWith({ behavior: "instant" });
+  });
+});

package/src/client/view-transitions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * View Transition API helpers for `data-view-transition` markup.
+ * @module
+ */
+/**
+ * Assigns `view-transition-name` from `data-view-transition` and injects morph styles.
+ *
+ * @remarks
+ * Elements without `data-view-transition-animate="fade"` get a geometric morph:
+ * the old snapshot is hidden so cross-fade ghosting does not appear.
+ */
+export declare function applyViewTransitionNames(): void;
+/**
+ * Clears inline transition names and dynamic morph styles after a transition ends.
+ */
+export declare function clearViewTransitionNames(): void;