@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.20

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

@@ -4,6 +4,8 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 const corePackageRequire = createRequire(new URL("../../package.json", import.meta.url));
 const appDeclaredPackageCache = /* @__PURE__ */ new Map();
+const appWorkspacePackageCache = /* @__PURE__ */ new Map();
+const CORE_RUNTIME_BARE_SPECIFIER_PACKAGES = /* @__PURE__ */ new Set(["ws"]);
 function tryResolveRuntimeImport(specifier, resolver) {
   try {
     return resolver.resolve(specifier);
@@ -14,6 +16,24 @@ function tryResolveRuntimeImport(specifier, resolver) {
 function isBareRuntimeImport(specifier) {
   return !specifier.startsWith(".") && !path.isAbsolute(specifier) && !specifier.startsWith("/") && !specifier.startsWith("node:") && !specifier.startsWith("@/") && !specifier.startsWith("~/") && !specifier.startsWith("#") && !specifier.includes(":");
 }
+function extractPackageNameFromFileUrl(specifier) {
+  if (!specifier.startsWith("file://")) {
+    return void 0;
+  }
+  const lastNodeModulesIndex = specifier.lastIndexOf("/node_modules/");
+  if (lastNodeModulesIndex === -1) {
+    return void 0;
+  }
+  const afterNodeModules = specifier.slice(lastNodeModulesIndex + "/node_modules/".length);
+  const parts = afterNodeModules.split("/");
+  if (parts.length === 0) {
+    return void 0;
+  }
+  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("/");
@@ -46,14 +66,52 @@ function getDeclaredAppPackages(rootDir) {
   appDeclaredPackageCache.set(cacheKey, declaredPackages);
   return declaredPackages;
 }
+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 = /* @__PURE__ */ 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;
+}
+function isWorkspacePackageImport(specifier, rootDir) {
+  return getWorkspacePackages(rootDir).has(getPackageNameFromSpecifier(specifier));
+}
 function isDeclaredAppPackageImport(specifier, rootDir) {
   return getDeclaredAppPackages(rootDir).has(getPackageNameFromSpecifier(specifier));
 }
+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 (!isBareRuntimeImport(specifier)) {
     return void 0;
   }
-  if (isDeclaredAppPackageImport(specifier, rootDir)) {
+  if (isDeclaredInResolutionChain(specifier, rootDir)) {
     return void 0;
   }
   const resolvedPath = tryResolveRuntimeImport(specifier, corePackageRequire);
@@ -67,6 +125,23 @@ function rewriteRuntimeBuildOutputImports(code, rootDir) {
     const rewrittenSpecifier = rewriteRuntimeImportSpecifier(specifier, quote, rootDir);
     return `${prefix}${rewrittenSpecifier ?? `${quote}${specifier}${quote}`}`;
   };
+  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}`;
+    }
+    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);
+    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)
@@ -77,7 +152,17 @@ function rewriteRuntimeBuildOutputImports(code, rootDir) {
     /(\bimport\s*\(\s*)(['"])([^'"\\]+)\2/g,
     (_match, prefix, quote, specifier) => rewriteSpecifier(prefix, quote, specifier)
   );
-  return withResolvedPackages.replace(
+  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);
@@ -86,6 +171,9 @@ function rewriteRuntimeBuildOutputImports(code, rootDir) {
   );
 }
 function normalizeNodeRuntimeBuildOutputFile(filePath, rootDir) {
+  if (process.env.ECOPAGES_LOGGER_DEBUG === "true") {
+    console.log(`[normalizeNodeRuntimeBuildOutputFile] Checking ${filePath}`);
+  }
   if (!/\.(?:[cm]?js)$/u.test(filePath)) {
     return;
   }
@@ -96,6 +184,9 @@ function normalizeNodeRuntimeBuildOutputFile(filePath, rootDir) {
   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);
   }
 }
@@ -106,6 +197,7 @@ function normalizeNodeRuntimeBuildOutputs(outputPaths, rootDir) {
 }
 export {
   isDeclaredAppPackageImport,
+  isWorkspacePackageImport,
   normalizeNodeRuntimeBuildOutputFile,
   normalizeNodeRuntimeBuildOutputs
 };

package/src/build/server-entry-build-cache.d.ts

@@ -0,0 +1,44 @@
+import type { BuildResult } from './build-adapter.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+/** @deprecated Use {@link ROUTE_MODULE_BUILD_CACHE_FILENAME}; both caches share the same manifest filename. */
+export declare const SERVER_ENTRY_BUILD_CACHE_FILENAME = ".build-cache.json";
+export declare const SERVER_BUNDLE_MANIFEST_FILENAME = "manifest.json";
+export interface ServerBundleDeployManifest {
+    serverEntry: string;
+    distDir: string;
+    builtAt: number;
+}
+export interface ServerEntryBuildCacheManifest {
+    invalidationVersion: string;
+    entryPath: string;
+    entryHash: string;
+    buildInputsFingerprint: string;
+    buildKey: string;
+    outputPaths: string[];
+    dependencyHashes: Record<string, string>;
+    builtAt: number;
+}
+export interface ServerEntryBuildCacheLookup {
+    manifest: ServerEntryBuildCacheManifest;
+    outputPaths: string[];
+}
+export declare function getServerBundleOutputPaths(appConfig: EcoPagesAppConfig): {
+    distDir: string;
+    serverOutdir: string;
+    serverEntryPath: string;
+    manifestPath: string;
+};
+export declare function readServerEntryBuildCacheManifest(appConfig: EcoPagesAppConfig): ServerEntryBuildCacheManifest | undefined;
+export declare function writeServerBundleDeployManifest(appConfig: EcoPagesAppConfig, serverEntryPath: string): void;
+export declare function lookupServerEntryBuildCache(options: {
+    appConfig: EcoPagesAppConfig;
+    entryPath: string;
+    force?: boolean;
+}): ServerEntryBuildCacheLookup | undefined;
+export declare function recordServerEntryBuildCache(options: {
+    appConfig: EcoPagesAppConfig;
+    entryPath: string;
+    buildResult: BuildResult;
+    outputPaths: string[];
+}): void;
+export declare function resolveProductionServerEntry(cwd?: string): string | undefined;

package/src/build/server-entry-build-cache.js

@@ -0,0 +1,161 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { getAppServerBuildPlugins } from "./build-adapter.js";
+import { createBuildInputsFingerprint } from "./build-input-fingerprint.js";
+import {
+  isProductionCacheManifestCurrent,
+  matchesProductionCacheBuildKey,
+  matchesProductionCacheFingerprint,
+  readProductionCacheManifest,
+  writeProductionCacheManifest
+} from "./production-build-cache.js";
+import { getCorePackageVersion } from "../services/module-loading/route-module-build-manifest.js";
+import {
+  RouteModuleDependencyHasher,
+  createRouteModuleDependencyHashes
+} from "../services/module-loading/route-module-dependency-hasher.js";
+import { resolveInternalExecutionDir } from "../utils/resolve-work-dir.js";
+import { SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME } from "../utils/resolve-entry-file.js";
+import { ROUTE_MODULE_BUILD_CACHE_FILENAME } from "../services/module-loading/route-module-build-manifest.js";
+const SERVER_ENTRY_BUILD_CACHE_FILENAME = ROUTE_MODULE_BUILD_CACHE_FILENAME;
+const SERVER_BUNDLE_MANIFEST_FILENAME = "manifest.json";
+function getServerEntryCacheDir(appConfig) {
+  return path.join(resolveInternalExecutionDir(appConfig), ".server-entry");
+}
+function getServerEntryCacheManifestPath(appConfig) {
+  return path.join(getServerEntryCacheDir(appConfig), SERVER_ENTRY_BUILD_CACHE_FILENAME);
+}
+function hashDependencyGraph(entryPath, dependencyGraph, hasher, rootDir) {
+  if (!dependencyGraph) {
+    return { [path.resolve(entryPath)]: fileSystem.hash(entryPath) };
+  }
+  return createRouteModuleDependencyHashes(hasher, { dependencyGraph }, entryPath, rootDir);
+}
+function createServerEntryBuildKey(appConfig) {
+  try {
+    const plugins = getAppServerBuildPlugins(appConfig);
+    const pluginNames = plugins.map((plugin) => plugin.name).sort().join("|");
+    return ["node", "esm", "external-packages", pluginNames].join("::");
+  } catch {
+    return "node::esm::external-packages";
+  }
+}
+function getServerBundleOutputPaths(appConfig) {
+  const distDir = appConfig.absolutePaths?.distDir ?? path.join(appConfig.rootDir, appConfig.distDir);
+  const serverOutdir = path.join(distDir, SERVER_BUNDLE_DIR);
+  const serverEntryPath = path.join(serverOutdir, SERVER_BUNDLE_FILENAME);
+  const manifestPath = path.join(serverOutdir, SERVER_BUNDLE_MANIFEST_FILENAME);
+  return { distDir, serverOutdir, serverEntryPath, manifestPath };
+}
+function readServerEntryBuildCacheManifest(appConfig) {
+  return readProductionCacheManifest(getServerEntryCacheManifestPath(appConfig));
+}
+function writeServerEntryBuildCacheManifest(appConfig, manifest) {
+  writeProductionCacheManifest(
+    path.join(getServerEntryCacheDir(appConfig), SERVER_ENTRY_BUILD_CACHE_FILENAME),
+    manifest
+  );
+}
+function writeServerBundleDeployManifest(appConfig, serverEntryPath) {
+  const { distDir, manifestPath } = getServerBundleOutputPaths(appConfig);
+  fileSystem.ensureDir(path.dirname(manifestPath));
+  const payload = {
+    serverEntry: path.relative(path.dirname(manifestPath), serverEntryPath) || SERVER_BUNDLE_FILENAME,
+    distDir,
+    builtAt: Date.now()
+  };
+  fileSystem.write(manifestPath, `${JSON.stringify(payload, null, "	")}
+`);
+}
+function lookupServerEntryBuildCache(options) {
+  if (options.force) {
+    return void 0;
+  }
+  if (process.env.NODE_ENV !== "production") {
+    return void 0;
+  }
+  const entryPath = path.resolve(options.entryPath);
+  const entryHash = fileSystem.hash(entryPath);
+  const buildInputsFingerprint = createBuildInputsFingerprint(options.appConfig);
+  const buildKey = createServerEntryBuildKey(options.appConfig);
+  const manifest = readServerEntryBuildCacheManifest(options.appConfig);
+  if (!manifest) {
+    return void 0;
+  }
+  if (!isProductionCacheManifestCurrent(manifest, getCorePackageVersion())) {
+    return void 0;
+  }
+  if (manifest.entryPath !== entryPath || manifest.entryHash !== entryHash || !matchesProductionCacheFingerprint(manifest, buildInputsFingerprint) || !matchesProductionCacheBuildKey(manifest, buildKey)) {
+    return void 0;
+  }
+  const hasher = new RouteModuleDependencyHasher();
+  if (!hasher.matchesStoredHashes(manifest.dependencyHashes, entryPath, entryHash)) {
+    return void 0;
+  }
+  const existingOutputs = manifest.outputPaths.filter((outputPath) => fileSystem.exists(outputPath));
+  if (existingOutputs.length === 0) {
+    return void 0;
+  }
+  return {
+    manifest,
+    outputPaths: existingOutputs
+  };
+}
+function recordServerEntryBuildCache(options) {
+  if (process.env.NODE_ENV !== "production") {
+    return;
+  }
+  const entryPath = path.resolve(options.entryPath);
+  const entryHash = fileSystem.hash(entryPath);
+  const hasher = new RouteModuleDependencyHasher();
+  const dependencyHashes = hashDependencyGraph(
+    entryPath,
+    options.buildResult.dependencyGraph,
+    hasher,
+    options.appConfig.rootDir
+  );
+  const manifest = {
+    invalidationVersion: getCorePackageVersion(),
+    entryPath,
+    entryHash,
+    buildInputsFingerprint: createBuildInputsFingerprint(options.appConfig),
+    buildKey: createServerEntryBuildKey(options.appConfig),
+    outputPaths: options.outputPaths,
+    dependencyHashes,
+    builtAt: Date.now()
+  };
+  writeServerEntryBuildCacheManifest(options.appConfig, manifest);
+}
+function resolveProductionServerEntry(cwd = process.cwd()) {
+  const manifestPath = path.join(cwd, "dist", SERVER_BUNDLE_DIR, SERVER_BUNDLE_MANIFEST_FILENAME);
+  if (fileSystem.exists(manifestPath)) {
+    try {
+      const parsed = JSON.parse(fileSystem.readFileSync(manifestPath));
+      if (parsed?.serverEntry) {
+        const fromManifest = path.isAbsolute(parsed.serverEntry) ? parsed.serverEntry : path.join(path.dirname(manifestPath), parsed.serverEntry);
+        if (fileSystem.exists(fromManifest)) {
+          return fromManifest;
+        }
+      }
+      if (parsed?.distDir) {
+        const fromDistDir = path.join(parsed.distDir, SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
+        if (fileSystem.exists(fromDistDir)) {
+          return fromDistDir;
+        }
+      }
+    } catch {
+    }
+  }
+  const legacyPath = path.join(cwd, "dist", SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
+  return fileSystem.exists(legacyPath) ? legacyPath : void 0;
+}
+export {
+  SERVER_BUNDLE_MANIFEST_FILENAME,
+  SERVER_ENTRY_BUILD_CACHE_FILENAME,
+  getServerBundleOutputPaths,
+  lookupServerEntryBuildCache,
+  readServerEntryBuildCacheManifest,
+  recordServerEntryBuildCache,
+  resolveProductionServerEntry,
+  writeServerBundleDeployManifest
+};

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;