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

package/src/client/scroll.js

@@ -0,0 +1,33 @@
+/**
+ * Window scroll behavior during client-side navigations.
+ * @module
+ */
+/**
+ * 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 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;
+    }
+}

package/src/client/scroll.test.browser.d.ts

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

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

@@ -0,0 +1,31 @@
+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,32 @@
+/**
+ * View Transition API helpers for `data-view-transition` markup and safe root defaults.
+ * @module
+ */
+/**
+ * Whether a document tree contains elements that participate in named view transitions.
+ */
+export declare function documentHasNamedViewTransitions(doc: Document): boolean;
+/**
+ * Whether SPA navigation should use `startViewTransition` (old or incoming page).
+ */
+export declare function navigationHasNamedViewTransitions(current: Document, incoming: Document): boolean;
+/**
+ * Injects persisted CSS that opts the document out of the root view-transition group.
+ *
+ * @remarks
+ * Uses `data-eco-persist` so head morphing does not drop the stylesheet between navigations.
+ * Named `data-view-transition` morph / fade rules live in a separate dynamic style tag.
+ */
+export declare function ensureRootViewTransitionStyles(): void;
+/**
+ * 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;

package/src/client/view-transitions.js

@@ -0,0 +1,120 @@
+/**
+ * View Transition API helpers for `data-view-transition` markup and safe root defaults.
+ * @module
+ */
+const VIEW_TRANSITION_ATTR = 'data-view-transition';
+const VIEW_TRANSITION_ANIMATE_ATTR = 'data-view-transition-animate';
+const VIEW_TRANSITION_DURATION_ATTR = 'data-view-transition-duration';
+const DYNAMIC_STYLES_ID = 'eco-vt-dynamic-styles';
+const ROOT_STYLES_ID = 'eco-vt-root-styles';
+/**
+ * @remarks
+ * UA default is `html { view-transition-name: root }`, which snapshots the whole
+ * document and crossfades with plus-lighter (flashes lighter on dark UIs). Routers
+ * inject this opt-out when `viewTransitions` is enabled. Named `data-view-transition`
+ * morphs still run. Full-page fades are not a supported default — use named elements
+ * or app-owned motion outside the View Transitions API.
+ */
+const ROOT_STYLES_CSS = `html {
+	view-transition-name: none;
+}
+`;
+/**
+ * Whether a document tree contains elements that participate in named view transitions.
+ */
+export function documentHasNamedViewTransitions(doc) {
+    return doc.querySelector(`[${VIEW_TRANSITION_ATTR}]`) !== null;
+}
+/**
+ * Whether SPA navigation should use `startViewTransition` (old or incoming page).
+ */
+export function navigationHasNamedViewTransitions(current, incoming) {
+    return documentHasNamedViewTransitions(current) || documentHasNamedViewTransitions(incoming);
+}
+/**
+ * Injects persisted CSS that opts the document out of the root view-transition group.
+ *
+ * @remarks
+ * Uses `data-eco-persist` so head morphing does not drop the stylesheet between navigations.
+ * Named `data-view-transition` morph / fade rules live in a separate dynamic style tag.
+ */
+export function ensureRootViewTransitionStyles() {
+    let styleEl = document.getElementById(ROOT_STYLES_ID);
+    if (!styleEl) {
+        styleEl = document.createElement('style');
+        styleEl.id = ROOT_STYLES_ID;
+        styleEl.setAttribute('data-eco-persist', '');
+        document.head.append(styleEl);
+    }
+    if (styleEl.textContent !== ROOT_STYLES_CSS) {
+        styleEl.textContent = ROOT_STYLES_CSS;
+    }
+}
+/**
+ * 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 function applyViewTransitionNames() {
+    const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+    const morphNames = [];
+    const customDurations = [];
+    elements.forEach((el) => {
+        const name = el.getAttribute(VIEW_TRANSITION_ATTR);
+        if (!name) {
+            return;
+        }
+        el.style.viewTransitionName = name;
+        const animate = el.getAttribute(VIEW_TRANSITION_ANIMATE_ATTR);
+        if (animate !== 'fade') {
+            morphNames.push(name);
+        }
+        const duration = el.getAttribute(VIEW_TRANSITION_DURATION_ATTR);
+        if (duration) {
+            customDurations.push({ name, duration });
+        }
+    });
+    if (morphNames.length > 0 || customDurations.length > 0) {
+        injectDynamicStyles(morphNames, customDurations);
+    }
+}
+/**
+ * Clears inline transition names and dynamic morph styles after a transition ends.
+ */
+export function clearViewTransitionNames() {
+    const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+    elements.forEach((el) => {
+        el.style.viewTransitionName = '';
+    });
+    const styleEl = document.getElementById(DYNAMIC_STYLES_ID);
+    if (styleEl) {
+        styleEl.textContent = '';
+    }
+}
+function injectDynamicStyles(morphNames, customDurations) {
+    let styleEl = document.getElementById(DYNAMIC_STYLES_ID);
+    if (!styleEl) {
+        styleEl = document.createElement('style');
+        styleEl.id = DYNAMIC_STYLES_ID;
+        /**
+         * @remarks
+         * Head morphing must not drop this tag between navigations.
+         */
+        styleEl.setAttribute('data-eco-persist', '');
+        document.head.append(styleEl);
+    }
+    const morphCss = morphNames
+        .map((name) => `
+		::view-transition-old(${name}) { display: none !important; }
+		::view-transition-new(${name}) { animation: none !important; opacity: 1 !important; }
+	`)
+        .join('\n');
+    const durationCss = customDurations
+        .map(({ name, duration }) => `
+		::view-transition-group(${name}) { animation-duration: ${duration} !important; }
+	`)
+        .join('\n');
+    styleEl.textContent = `${morphCss}\n${durationCss}`;
+}

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

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

package/src/client/view-transitions.test.browser.js

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { applyViewTransitionNames, clearViewTransitionNames, documentHasNamedViewTransitions, ensureRootViewTransitionStyles, navigationHasNamedViewTransitions, } from './view-transitions.js';
+describe('documentHasNamedViewTransitions', () => {
+    afterEach(() => {
+        document.body.replaceChildren();
+    });
+    it('returns false when no markup is present', () => {
+        expect(documentHasNamedViewTransitions(document)).toBe(false);
+    });
+    it('returns true when data-view-transition is present', () => {
+        document.body.innerHTML = '<div data-view-transition="x"></div>';
+        expect(documentHasNamedViewTransitions(document)).toBe(true);
+    });
+    it('navigation checks current or incoming document', () => {
+        const incoming = new DOMParser().parseFromString('<html><body><div data-view-transition="hero"></div></body></html>', 'text/html');
+        expect(navigationHasNamedViewTransitions(document, incoming)).toBe(true);
+    });
+});
+describe('ensureRootViewTransitionStyles', () => {
+    afterEach(() => {
+        document.getElementById('eco-vt-root-styles')?.remove();
+        document.getElementById('eco-vt-dynamic-styles')?.remove();
+        document.body.replaceChildren();
+    });
+    it('opts the document out of the root view-transition group without !important', () => {
+        ensureRootViewTransitionStyles();
+        const style = document.getElementById('eco-vt-root-styles');
+        expect(style).not.toBeNull();
+        expect(style?.hasAttribute('data-eco-persist')).toBe(true);
+        expect(style?.textContent).toContain('view-transition-name: none');
+        expect(style?.textContent).not.toContain('!important');
+        expect(getComputedStyle(document.documentElement).viewTransitionName).toBe('none');
+    });
+    it('reuses a single style element', () => {
+        ensureRootViewTransitionStyles();
+        ensureRootViewTransitionStyles();
+        expect(document.querySelectorAll('#eco-vt-root-styles')).toHaveLength(1);
+    });
+});
+describe('applyViewTransitionNames with root styles', () => {
+    afterEach(() => {
+        document.getElementById('eco-vt-root-styles')?.remove();
+        document.getElementById('eco-vt-dynamic-styles')?.remove();
+        document.body.replaceChildren();
+    });
+    it('keeps root styles when clearing named morph styles', () => {
+        ensureRootViewTransitionStyles();
+        document.body.innerHTML = '<div data-view-transition="hero"></div>';
+        applyViewTransitionNames();
+        expect(document.getElementById('eco-vt-dynamic-styles')?.textContent).toContain('view-transition-old(hero)');
+        expect(document.getElementById('eco-vt-root-styles')?.textContent).toContain('view-transition-name: none');
+        clearViewTransitionNames();
+        expect(document.getElementById('eco-vt-dynamic-styles')?.textContent).toBe('');
+        expect(document.getElementById('eco-vt-root-styles')?.textContent).toContain('view-transition-name: none');
+    });
+});

package/src/config/config-builder.d.ts

@@ -3,12 +3,12 @@
  * @module
  */
 import { type BuildOwnership } from '../build/build-adapter.js';
-import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
 import type { EcoPagesAppConfig, RobotsPreference } from '../types/internal-types.js';
 import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.js';
 import type { Processor } from '../plugins/processor.js';
 import type { EcoSourceTransform } from '../plugins/source-transform.js';
-import type { PageMetadataProps } from '../types/public-types.js';
+import type { PageMetadataProps, SitemapConfig } from '../types/public-types.js';
 import type { CacheConfig } from '../services/cache/cache.types.js';
 export declare const CONFIG_BUILDER_ERRORS: {
     readonly DUPLICATE_INTEGRATION_NAMES: "Integrations names must be unique";
@@ -16,7 +16,7 @@ export declare const CONFIG_BUILDER_ERRORS: {
     readonly MIXED_JSX_ENGINES: "Both kitajs and react integrations are enabled. Use per-file JSX import source/pragma consistently (e.g. `/** @jsxImportSource react */` for React files and `/** @jsxImportSource @kitajs/html */` for Kita files).";
     readonly duplicateProcessorName: (name: string) => string;
     readonly duplicateLoaderName: (name: string) => string;
-    readonly duplicateSemanticTemplate: (kind: "html" | "404", matches: string[]) => string;
+    readonly duplicateSemanticTemplate: (kind: "html" | "404" | "500", matches: string[]) => string;
     readonly incompatibleRuntimeCapability: (kind: "integration" | "processor", name: string, runtime: RuntimeKind, reason: string) => string;
     readonly unsupportedRuntimeVersion: (kind: "integration" | "processor", name: string, runtime: RuntimeKind, current: string, min: string) => string;
     readonly invalidRuntimeVersion: (kind: "integration" | "processor", name: string, version: string) => string;
@@ -70,12 +70,7 @@ export declare class ConfigBuilder {
      *
      * - `'rolldown'` (default): Ecopages runs builds through
      *   {@link RolldownBuildAdapter}, creating a new `rolldown()` instance
-     *   per build. Best for one-shot production builds and benchmarks.
-     * - `'rolldown-dev'`: Ecopages runs builds through
-     *   {@link RolldownDevBuildAdapter}, which wraps Rolldown's experimental
-     *   `DevEngine` and reuses the cached module graph, resolver, and
-     *   transform cache across rebuilds. Best for HMR and watch mode where
-     *   the same entrypoints are rebuilt repeatedly.
+     *   per build.
      * - `'vite-host'`: a host runtime owns the build. Ecopages exposes a
      *   {@link ViteHostBuildAdapter} boundary marker that throws on direct
      *   use. Select this only for host-driven compatibility flows where
@@ -143,6 +138,24 @@ export declare class ConfigBuilder {
     setRobotsTxt(robotsTxt: {
         preferences: RobotsPreference;
     }): this;
+    /**
+     * Sets automatic sitemap.xml generation during static export.
+     *
+     * @remarks
+     * Merged over `{ enabled: false, fileName: 'sitemap.xml', extraUrls: [], exclude: [] }`.
+     * Existing apps stay unchanged until `enabled: true` is set. Page-level
+     * `metadata.robots.index: false` and metadata resolution failures are handled
+     * during static generation (not by this config merge).
+     */
+    setSitemap(sitemap: SitemapConfig): this;
+    /**
+     * Configures the in-browser development toolbar shown during watch mode.
+     *
+     * @remarks
+     * Requires `package` to point at a browser bootstrap module installed in the app.
+     * Prefer {@link defineDevTool} for config authoring.
+     */
+    setDevToolbar(devToolbar: NonNullable<EcoPagesAppConfig['devToolbar']>): this;
     /**
      * Sets the integration plugins to use.
      * These plugins provide additional functionality to the application.
@@ -185,6 +198,20 @@ export declare class ConfigBuilder {
      * @returns The ConfigBuilder instance for method chaining
      */
     setAdditionalWatchPaths(additionalWatchPaths: string[]): this;
+    /**
+     * Sets static paths to SSR-prewarm in development.
+     *
+     * @param devPrewarmPaths - Absolute URL pathnames such as `/` or `/docs`.
+     * @returns The ConfigBuilder instance for method chaining.
+     */
+    setDevPrewarmPaths(devPrewarmPaths: string[]): this;
+    /**
+     * Sets static paths to SSR-prewarm before the development server reports ready.
+     *
+     * @param devPrewarmBeforeReadyPaths - Critical absolute URL pathnames such as `/`.
+     * @returns The ConfigBuilder instance for method chaining.
+     */
+    setDevPrewarmBeforeReadyPaths(devPrewarmBeforeReadyPaths: string[]): this;
     /**
      * Sets the processors to use for the application.
      * This replaces any existing processors.
@@ -250,7 +277,10 @@ export declare class ConfigBuilder {
     private compareVersions;
     /**
      * Initializes default loaders that are required for EcoPages to function.
-     * This includes the eco-component-meta-plugin which auto-injects __eco metadata into component configs.
+     *
+     * @remarks
+     * Component identity attribution is a source transform so browser, HMR, and
+     * server module paths share one component-identity attribution mechanism.
      */
     private initializeDefaultLoaders;
     private reviewBaseUrl;