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

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

@@ -0,0 +1,79 @@
+/**
+ * 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;
+    }
+}

package/src/cache/index.d.ts

@@ -3,4 +3,5 @@
  *
  * @module @ecopages/core/cache
  */
-export { ModuleParseCache, moduleParseCache, cachedParseSync, type ModuleParseOptions } from './module-parse-cache.js';
+export { ModuleParseCache, moduleParseCache, cachedParseSync, parseModuleSource, parserLanguageForFile, type ModuleParseOptions, type ParserLanguage, } from './module-parse-cache.js';
+export { recordModuleTransformProfile } from './module-transform-profiler.js';

package/src/cache/index.js

@@ -1,6 +1,7 @@
-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, parseModuleSource, parserLanguageForFile, } from './module-parse-cache.js';
+export { recordModuleTransformProfile } from './module-transform-profiler.js';

package/src/cache/module-parse-cache.d.ts

@@ -22,6 +22,11 @@ export type ModuleParseOptions = ParserOptions & {
      */
     lang?: ParserOptions['lang'];
 };
+export type ParserLanguage = 'js' | 'jsx' | 'ts' | 'tsx';
+/** Resolves the Oxc dialect for a source module from its file extension. */
+export declare function parserLanguageForFile(filePath: string): ParserLanguage;
+/** Parses an ECMAScript module with the shared, normalized cache contract. */
+export declare function parseModuleSource(filePath: string, source: string, options?: ModuleParseOptions): ParseResult;
 /**
  * LRU-bounded module parse cache.
  *

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

@@ -1,75 +1,130 @@
-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 { extname } from 'node:path';
+import { parseSync } from 'oxc-parser';
+import { rapidhash } from '../utils/hash.js';
+const DEFAULT_MAX_ENTRIES = 10_000;
+/** Resolves the Oxc dialect for a source module from its file extension. */
+export function parserLanguageForFile(filePath) {
+    const extension = extname(filePath).toLowerCase();
+    if (extension === '.tsx')
+        return 'tsx';
+    if (extension === '.ts' || extension === '.mts' || extension === '.cts')
+        return 'ts';
+    if (extension === '.jsx')
+        return 'jsx';
+    return 'js';
+}
+/** Parses an ECMAScript module with the shared, normalized cache contract. */
+export function parseModuleSource(filePath, source, options = {}) {
+    return moduleParseCache.getOrParse(filePath, source, normalizeModuleParseOptions(filePath, options));
+}
+/**
+ * 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;
+    }
+    /**
+     * Parse `source` for `filePath`, memoizing by (filePath, source, options).
+     *
+     * @returns the {@link ParseResult} from `oxc-parser.parseSync`.
+     */
+    getOrParse(filePath, source, options = {}) {
+        const normalizedOptions = normalizeModuleParseOptions(filePath, options);
+        const hash = rapidhash(source);
+        const key = makeKey(filePath, hash, normalizedOptions);
+        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, normalizedOptions);
+        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;
+    }
+    /** Clear all cached entries. Useful in tests and on full-rebuild signals. */
+    clear() {
+        this.entries.clear();
+        this.hits = 0;
+        this.misses = 0;
     }
-    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;
+    /** Current cache size (for observability). */
+    get size() {
+        return this.entries.size;
     }
-    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);
-      }
+    /** 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;
+}
+/**
+ * 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 parseModuleSource(filePath, source, options);
+}
+function normalizeModuleParseOptions(filePath, options) {
     return {
-      hits: this.hits,
-      misses: this.misses,
-      size: this.entries.size,
-      hitRate: total === 0 ? 0 : this.hits / total
+        ...options,
+        lang: options.lang ?? parserLanguageForFile(filePath),
+        sourceType: options.sourceType ?? 'module',
     };
-  }
-}
-const moduleParseCache = new ModuleParseCache();
-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/cache/module-transform-profiler.d.ts

@@ -0,0 +1,8 @@
+type ProfileRecord = {
+    category: string;
+    phase: string;
+    ms: number;
+    cacheHit?: boolean;
+};
+export declare function recordModuleTransformProfile(record: ProfileRecord): void;
+export {};

package/src/cache/module-transform-profiler.js

@@ -0,0 +1,8 @@
+export function recordModuleTransformProfile(record) {
+    if (process.env.ECO_AST_PROFILE !== '1')
+        return;
+    console.info(`[ecopages:ast-profile] ${JSON.stringify({
+        ...record,
+        ms: Number(record.ms.toFixed(3)),
+    })}`);
+}

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,49 @@
+/**
+ * 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',
+]);
+/**
+ * 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);
+}
+/**
+ * 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);
+}
+/**
+ * Returns whether a script is queued for rerun after navigation commit.
+ */
+export function isRerunScript(element) {
+    return element.tagName === 'SCRIPT' && element.hasAttribute('data-eco-rerun');
+}

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,3 @@
+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.d.ts

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

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

@@ -0,0 +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);
+    });
+});
+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,16 @@
+/**
+ * `__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;
+}

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,90 @@
+/**
+ * Queueing and replay of `data-eco-rerun` scripts after navigation.
+ * @module
+ */
+import { RERUN_SRC_ATTR, getRegisteredRerunScript } from './registry.js';
+let rerunNonce = 0;
+/**
+ * Collects rerun scripts from an incoming document.
+ */
+export function collectRerunScripts(document, filter) {
+    return Array.from(document.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'),
+    }));
+}
+/**
+ * Returns whether a rerun script is an external ES module that needs cache busting.
+ */
+export function isExternalModuleRerunScript(script) {
+    if (!script.src) {
+        return false;
+    }
+    return script.attributes.some(([name, value]) => name === 'type' && value === 'module');
+}
+/**
+ * Finds an existing rerun script in `root` by id or by src and inline content.
+ */
+export 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);
+}
+/**
+ * Appends a nonce query parameter so module scripts re-execute after navigation.
+ */
+export function createRerunScriptUrl(src) {
+    const url = new URL(src, document.baseURI);
+    url.searchParams.set('__eco_rerun', String(++rerunNonce));
+    return url.toString();
+}
+/**
+ * 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 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);
+    }
+}
+/** @remarks Test-only reset for nonce sequencing. */
+export function resetRerunNonceForTests() {
+    rerunNonce = 0;
+}

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;