@ecopages/core 0.2.0-beta.32 → 0.2.0-beta.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.32",
+  "version": "0.2.0-beta.34",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.32",
+    "@ecopages/file-system": "0.2.0-beta.34",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",
@@ -32,7 +32,7 @@
     "@standard-schema/utils": "^0.3.0"
   },
   "peerDependencies": {
-    "@ecopages/dev-toolbar": "0.2.0-beta.32"
+    "@ecopages/dev-toolbar": "0.2.0-beta.34"
   },
   "peerDependenciesMeta": {
     "@ecopages/dev-toolbar": {
@@ -88,6 +88,10 @@
       "types": "./src/router/client/navigation-coordinator.d.ts",
       "default": "./src/router/client/navigation-coordinator.js"
     },
+    "./router/navigation-lifecycle": {
+      "types": "./src/router/client/navigation-lifecycle.d.ts",
+      "default": "./src/router/client/navigation-lifecycle.js"
+    },
     "./router/link-intent": {
       "types": "./src/router/client/link-intent.d.ts",
       "default": "./src/router/client/link-intent.js"
@@ -357,6 +361,10 @@
       "types": "./src/router/client/navigation-coordinator.d.ts",
       "default": "./src/router/client/navigation-coordinator.js"
     },
+    "./router/navigation-lifecycle.ts": {
+      "types": "./src/router/client/navigation-lifecycle.d.ts",
+      "default": "./src/router/client/navigation-lifecycle.js"
+    },
     "./router/link-intent.ts": {
       "types": "./src/router/client/link-intent.d.ts",
       "default": "./src/router/client/link-intent.js"

package/src/router/README.md

@@ -22,6 +22,7 @@ router/
 │   └── route-registry.ts        # Owns template routes, request matching, static expansion, and reload
 └── client/                      # Browser-side navigation coordination
     ├── navigation-coordinator.ts # Singleton runtime coordinator
+    ├── navigation-lifecycle.ts   # Shared document lifecycle events
     └── link-intent.ts           # Shared anchor detection and intent recovery helpers
 ```
 
@@ -79,6 +80,28 @@ The coordinator is framework-agnostic. Browser runtimes (e.g. `browser-router`,
 - **Reload** — `reloadCurrentPage` delegates to whichever runtime currently owns the document.
 - **Events** — `subscribe` lets runtimes react to `owner-change` and `registration-change` events.
 
+### Navigation Lifecycle (`navigation-lifecycle.ts`)
+
+Shared document lifecycle events emitted by browser runtimes after a client navigation commits.
+
+Access it with:
+
+```ts
+import {
+	completeNavigationLifecycle,
+	dispatchBeforeSwap,
+	type EcoNavigationEvent,
+} from '@ecopages/core/router/navigation-lifecycle';
+```
+
+`browser-router` and `react-router` call these helpers around their own commit implementations. Use `completeNavigationLifecycle` for the paired post-commit signals. Listeners use the DOM contract:
+
+- `eco:before-swap` — pre-commit hook with `newDocument` and `reload()`
+- `eco:after-swap` — post-commit signal after the runtime has applied the new page
+- `eco:page-load` — scheduled on the next animation frame after `eco:after-swap`
+
+This is separate from coordinator `subscribe()` events, which track runtime ownership rather than page lifecycle.
+
 ### Link Intent (`link-intent.ts`)
 
 Shared helpers for locating anchors and recovering stale navigation intent.

package/src/router/client/navigation-lifecycle.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared document navigation lifecycle events for browser runtimes.
+ *
+ * @remarks
+ * `eco:before-swap`, `eco:after-swap`, and `eco:page-load` are the public
+ * contract consumed by dev tooling, global injectors, and layout scripts.
+ * Dispatch helpers live here so browser-router and react-router stay aligned.
+ *
+ * @module
+ */
+import type { EcoNavigationDirection } from './navigation-coordinator.js';
+export declare const ECO_NAVIGATION_LIFECYCLE_EVENTS: {
+    readonly BEFORE_SWAP: "eco:before-swap";
+    readonly AFTER_SWAP: "eco:after-swap";
+    readonly PAGE_LOAD: "eco:page-load";
+};
+/** Base detail shared by navigation lifecycle events. */
+export interface EcoNavigationEvent {
+    url: URL;
+    direction: EcoNavigationDirection;
+}
+/** Detail for the pre-commit lifecycle event. */
+export interface EcoBeforeSwapEvent extends EcoNavigationEvent {
+    newDocument: Document;
+    reload: () => void;
+}
+/** Detail for the post-commit lifecycle event. */
+export interface EcoAfterSwapEvent extends EcoNavigationEvent {
+}
+/** Typed document event map for navigation lifecycle listeners. */
+export interface EcoNavigationLifecycleEventMap {
+    'eco:before-swap': CustomEvent<EcoBeforeSwapEvent>;
+    'eco:after-swap': CustomEvent<EcoAfterSwapEvent>;
+    'eco:page-load': CustomEvent<EcoNavigationEvent>;
+}
+export type DispatchBeforeSwapResult = {
+    requestedReload: boolean;
+};
+export type SchedulePageLoadOptions = {
+    isStale?: () => boolean;
+    schedule?: (callback: FrameRequestCallback) => number;
+};
+/**
+ * Dispatches `eco:before-swap` and reports whether a listener requested reload.
+ */
+export declare function dispatchBeforeSwap(doc: Document, input: Omit<EcoBeforeSwapEvent, 'reload'>): DispatchBeforeSwapResult;
+/** Dispatches `eco:after-swap`. */
+export declare function dispatchAfterSwap(doc: Document, detail: EcoAfterSwapEvent): void;
+export type CompleteNavigationLifecycleOptions = SchedulePageLoadOptions;
+/** Dispatches `eco:after-swap` and schedules `eco:page-load`. */
+export declare function completeNavigationLifecycle(doc: Document, detail: EcoNavigationEvent, options?: CompleteNavigationLifecycleOptions): void;
+/**
+ * Schedules `eco:page-load` on the next animation frame unless navigation is stale.
+ */
+export declare function schedulePageLoad(doc: Document, detail: EcoNavigationEvent, options?: SchedulePageLoadOptions): void;

package/src/router/client/navigation-lifecycle.js

@@ -0,0 +1,50 @@
+/**
+ * Shared document navigation lifecycle events for browser runtimes.
+ *
+ * @remarks
+ * `eco:before-swap`, `eco:after-swap`, and `eco:page-load` are the public
+ * contract consumed by dev tooling, global injectors, and layout scripts.
+ * Dispatch helpers live here so browser-router and react-router stay aligned.
+ *
+ * @module
+ */
+export const ECO_NAVIGATION_LIFECYCLE_EVENTS = {
+    BEFORE_SWAP: 'eco:before-swap',
+    AFTER_SWAP: 'eco:after-swap',
+    PAGE_LOAD: 'eco:page-load',
+};
+/**
+ * Dispatches `eco:before-swap` and reports whether a listener requested reload.
+ */
+export function dispatchBeforeSwap(doc, input) {
+    let requestedReload = false;
+    const detail = {
+        ...input,
+        reload: () => {
+            requestedReload = true;
+        },
+    };
+    doc.dispatchEvent(new CustomEvent(ECO_NAVIGATION_LIFECYCLE_EVENTS.BEFORE_SWAP, { detail }));
+    return { requestedReload };
+}
+/** Dispatches `eco:after-swap`. */
+export function dispatchAfterSwap(doc, detail) {
+    doc.dispatchEvent(new CustomEvent(ECO_NAVIGATION_LIFECYCLE_EVENTS.AFTER_SWAP, { detail }));
+}
+/** Dispatches `eco:after-swap` and schedules `eco:page-load`. */
+export function completeNavigationLifecycle(doc, detail, options = {}) {
+    dispatchAfterSwap(doc, detail);
+    schedulePageLoad(doc, detail, options);
+}
+/**
+ * Schedules `eco:page-load` on the next animation frame unless navigation is stale.
+ */
+export function schedulePageLoad(doc, detail, options = {}) {
+    const schedule = options.schedule ?? ((callback) => requestAnimationFrame(callback));
+    schedule(() => {
+        if (options.isStale?.()) {
+            return;
+        }
+        doc.dispatchEvent(new CustomEvent(ECO_NAVIGATION_LIFECYCLE_EVENTS.PAGE_LOAD, { detail }));
+    });
+}

package/src/router/client/navigation-lifecycle.test.browser.d.ts

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

package/src/router/client/navigation-lifecycle.test.browser.js

@@ -0,0 +1,118 @@
+import { describe, expect, it, vi } from 'vitest';
+import { completeNavigationLifecycle, dispatchAfterSwap, dispatchBeforeSwap, ECO_NAVIGATION_LIFECYCLE_EVENTS, schedulePageLoad, } from './navigation-lifecycle.js';
+describe('navigation lifecycle dispatch', () => {
+    it('dispatches before-swap with newDocument and reload hook', () => {
+        const beforeSwapSpy = vi.fn();
+        document.addEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.BEFORE_SWAP, beforeSwapSpy);
+        try {
+            const newDocument = new DOMParser().parseFromString('<html><body>Next</body></html>', 'text/html');
+            const url = new URL('https://example.test/next');
+            const { requestedReload } = dispatchBeforeSwap(document, {
+                url,
+                direction: 'forward',
+                newDocument,
+            });
+            expect(requestedReload).toBe(false);
+            expect(beforeSwapSpy).toHaveBeenCalledTimes(1);
+            const detail = beforeSwapSpy.mock.calls[0][0].detail;
+            expect(detail.url).toBe(url);
+            expect(detail.direction).toBe('forward');
+            expect(detail.newDocument).toBe(newDocument);
+            expect(typeof detail.reload).toBe('function');
+        }
+        finally {
+            document.removeEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.BEFORE_SWAP, beforeSwapSpy);
+        }
+    });
+    it('reports reload requests from before-swap listeners', () => {
+        const beforeSwapSpy = vi.fn((event) => {
+            event.detail.reload();
+        });
+        document.addEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.BEFORE_SWAP, beforeSwapSpy);
+        try {
+            const { requestedReload } = dispatchBeforeSwap(document, {
+                url: new URL('https://example.test/reload'),
+                direction: 'forward',
+                newDocument: document,
+            });
+            expect(requestedReload).toBe(true);
+        }
+        finally {
+            document.removeEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.BEFORE_SWAP, beforeSwapSpy);
+        }
+    });
+    it('dispatches after-swap with url and direction', () => {
+        const afterSwapSpy = vi.fn();
+        document.addEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.AFTER_SWAP, afterSwapSpy);
+        try {
+            const url = new URL('https://example.test/after');
+            dispatchAfterSwap(document, { url, direction: 'replace' });
+            expect(afterSwapSpy).toHaveBeenCalledTimes(1);
+            const detail = afterSwapSpy.mock.calls[0][0].detail;
+            expect(detail.url).toBe(url);
+            expect(detail.direction).toBe('replace');
+        }
+        finally {
+            document.removeEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.AFTER_SWAP, afterSwapSpy);
+        }
+    });
+    it('completes navigation lifecycle with after-swap and page-load', () => {
+        const afterSwapSpy = vi.fn();
+        const pageLoadSpy = vi.fn();
+        const scheduleSpy = vi.fn((callback) => {
+            callback(0);
+            return 1;
+        });
+        document.addEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.AFTER_SWAP, afterSwapSpy);
+        document.addEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.PAGE_LOAD, pageLoadSpy);
+        try {
+            const url = new URL('https://example.test/complete');
+            completeNavigationLifecycle(document, { url, direction: 'forward' }, { schedule: scheduleSpy });
+            expect(afterSwapSpy).toHaveBeenCalledTimes(1);
+            expect(pageLoadSpy).toHaveBeenCalledTimes(1);
+            expect(scheduleSpy).toHaveBeenCalledTimes(1);
+        }
+        finally {
+            document.removeEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.AFTER_SWAP, afterSwapSpy);
+            document.removeEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.PAGE_LOAD, pageLoadSpy);
+        }
+    });
+    it('schedules page-load on the next animation frame', () => {
+        const pageLoadSpy = vi.fn();
+        const scheduleSpy = vi.fn((callback) => {
+            callback(0);
+            return 1;
+        });
+        document.addEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.PAGE_LOAD, pageLoadSpy);
+        try {
+            const url = new URL('https://example.test/page-load');
+            schedulePageLoad(document, { url, direction: 'forward' }, { schedule: scheduleSpy });
+            expect(scheduleSpy).toHaveBeenCalledTimes(1);
+            expect(pageLoadSpy).toHaveBeenCalledTimes(1);
+            const detail = pageLoadSpy.mock.calls[0][0].detail;
+            expect(detail.url).toBe(url);
+            expect(detail.direction).toBe('forward');
+        }
+        finally {
+            document.removeEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.PAGE_LOAD, pageLoadSpy);
+        }
+    });
+    it('skips page-load when navigation becomes stale before the frame callback', () => {
+        const pageLoadSpy = vi.fn();
+        let stale = true;
+        document.addEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.PAGE_LOAD, pageLoadSpy);
+        try {
+            schedulePageLoad(document, { url: new URL('https://example.test/stale'), direction: 'forward' }, {
+                isStale: () => stale,
+                schedule: (callback) => {
+                    callback(0);
+                    return 1;
+                },
+            });
+            expect(pageLoadSpy).not.toHaveBeenCalled();
+        }
+        finally {
+            document.removeEventListener(ECO_NAVIGATION_LIFECYCLE_EVENTS.PAGE_LOAD, pageLoadSpy);
+        }
+    });
+});