@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.1

package/src/router/client/link-navigation-policy.test.browser.js

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import { getLinkNavigationDecision, getNavigableHrefFromClick, isHtmlPageResponse, isSamePageHashNavigationHref, shouldPrefetchLink, } from './link-navigation-policy.js';
+function createLink(href, attributes = {}) {
+    const link = document.createElement('a');
+    link.href = href;
+    for (const [key, value] of Object.entries(attributes)) {
+        link.setAttribute(key, value);
+    }
+    document.body.append(link);
+    return link;
+}
+function createMouseEvent(button = 0, modifiers = {}) {
+    return new MouseEvent('click', { bubbles: true, cancelable: true, button, ...modifiers });
+}
+const policy = { reloadAttribute: 'data-eco-reload', noPrefetchAttribute: 'data-eco-no-prefetch' };
+describe('isSamePageHashNavigationHref', () => {
+    it('returns true for same pathname with a new hash', () => {
+        history.replaceState({}, '', '/docs/page');
+        expect(isSamePageHashNavigationHref('/docs/page#section')).toBe(true);
+    });
+});
+describe('getLinkNavigationDecision', () => {
+    it('allows same-origin page links', () => {
+        const link = createLink('/page');
+        const decision = getLinkNavigationDecision(createMouseEvent(), link, policy);
+        expect(decision).toEqual({ shouldIntercept: true, href: '/page' });
+    });
+    it('rejects static asset links', () => {
+        const link = createLink('/skill.txt');
+        expect(getLinkNavigationDecision(createMouseEvent(), link, policy)).toEqual({
+            shouldIntercept: false,
+            reason: 'static-asset',
+        });
+    });
+    it('rejects explicit reload links', () => {
+        const link = createLink('/logout', { 'data-eco-reload': '' });
+        expect(getLinkNavigationDecision(createMouseEvent(), link, policy)).toEqual({
+            shouldIntercept: false,
+            reason: 'explicit-reload',
+        });
+    });
+});
+describe('getNavigableHrefFromClick', () => {
+    it('returns href when navigation should be intercepted', () => {
+        const link = createLink('/page');
+        expect(getNavigableHrefFromClick(createMouseEvent(), link, policy)).toBe('/page');
+    });
+    it('returns null for static assets', () => {
+        const link = createLink('/llms.txt');
+        expect(getNavigableHrefFromClick(createMouseEvent(), link, policy)).toBeNull();
+    });
+});
+describe('shouldPrefetchLink', () => {
+    it('prefetches internal page links', () => {
+        history.replaceState({}, '', '/');
+        const link = createLink('/docs/intro');
+        expect(shouldPrefetchLink(link, policy)).toBe(true);
+    });
+    it('skips static assets and opt-outs', () => {
+        history.replaceState({}, '', '/');
+        expect(shouldPrefetchLink(createLink('/skill.txt'), policy)).toBe(false);
+        expect(shouldPrefetchLink(createLink('/page', { 'data-eco-no-prefetch': '' }), policy)).toBe(false);
+    });
+});
+describe('isHtmlPageResponse', () => {
+    it('accepts html content types', () => {
+        expect(isHtmlPageResponse(new Response('', { headers: { 'Content-Type': 'text/html; charset=utf-8' } }))).toBe(true);
+    });
+    it('rejects plain text responses', () => {
+        expect(isHtmlPageResponse(new Response('', { headers: { 'Content-Type': 'text/plain' } }))).toBe(false);
+    });
+});
+describe('isHtmlPageResponse', () => {
+    it('accepts html and xhtml content types', () => {
+        expect(isHtmlPageResponse(new Response('', { headers: { 'Content-Type': 'text/html' } }))).toBe(true);
+        expect(isHtmlPageResponse(new Response('', { headers: { 'Content-Type': 'application/xhtml+xml' } }))).toBe(true);
+    });
+    it('rejects plain text and markdown responses', () => {
+        expect(isHtmlPageResponse(new Response('text', { headers: { 'Content-Type': 'text/plain' } }))).toBe(false);
+        expect(isHtmlPageResponse(new Response('# doc', { headers: { 'Content-Type': 'text/markdown' } }))).toBe(false);
+    });
+});

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

@@ -96,7 +96,7 @@ export type EcoNavigationRuntimeRegistration = {
      * Implementations may honor `request.moduleUrl` to force a specific page entry
      * and `request.clearCache` to discard persisted runtime state before reloading.
      */
-    reloadCurrentPage?: (request?: EcoReloadRequest) => Promise<void>;
+    reloadCurrentPage?: (request?: EcoReloadRequest) => Promise<boolean | void>;
     /**
      * Releases runtime-owned client state before another runtime commits a new
      * document.

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

@@ -1,225 +1,249 @@
-const ECO_DOCUMENT_OWNER_ATTRIBUTE = "data-eco-document-owner";
-function getEcoDocumentOwner(doc) {
-  const owner = doc.documentElement.getAttribute(ECO_DOCUMENT_OWNER_ATTRIBUTE);
-  return owner && owner.length > 0 ? owner : null;
+/**
+ * Shared browser-side navigation coordinator.
+ *
+ * This module is the client runtime contract used by browser-router,
+ * react-router, and HMR code to coordinate ownership, cross-runtime handoff,
+ * current-page reloads, and stale-navigation cancellation.
+ *
+ * The coordinator stays framework-agnostic: browser runtimes register their
+ * capabilities here, and the coordinator arbitrates which runtime currently
+ * owns the document and which navigation transaction is still current.
+ *
+ * @module
+ */
+/** HTML attribute used to persist the rendered document owner across navigations. */
+export const ECO_DOCUMENT_OWNER_ATTRIBUTE = 'data-eco-document-owner';
+/**
+ * Reads the explicit browser document owner marker from a rendered HTML document.
+ *
+ * Documents without a marker return `null`, allowing runtimes to fall back to
+ * their local default behavior without scanning hydration scripts.
+ */
+export function getEcoDocumentOwner(doc) {
+    const owner = doc.documentElement.getAttribute(ECO_DOCUMENT_OWNER_ATTRIBUTE);
+    return owner && owner.length > 0 ? owner : null;
 }
 function getCandidateOwners(currentOwner, registrations, excludedOwner) {
-  const owners = [];
-  if (currentOwner !== "none" && currentOwner !== excludedOwner) {
-    owners.push(currentOwner);
-  }
-  for (const owner of registrations.keys()) {
-    if (owner === currentOwner || owner === excludedOwner) {
-      continue;
+    const owners = [];
+    if (currentOwner !== 'none' && currentOwner !== excludedOwner) {
+        owners.push(currentOwner);
     }
-    owners.push(owner);
-  }
-  return owners;
+    for (const owner of registrations.keys()) {
+        if (owner === currentOwner || owner === excludedOwner) {
+            continue;
+        }
+        owners.push(owner);
+    }
+    return owners;
 }
 function createEcoNavigationRuntime() {
-  const registrations = /* @__PURE__ */ new Map();
-  const listeners = /* @__PURE__ */ new Set();
-  let owner = "none";
-  let navigationSequence = 0;
-  let navigationAbortController = null;
-  const emit = (event) => {
-    for (const listener of listeners) {
-      listener(event);
-    }
-  };
-  const updateOwner = (nextOwner, reason) => {
-    if (owner === nextOwner) {
-      return;
-    }
-    const previousOwner = owner;
-    owner = nextOwner;
-    emit({
-      type: "owner-change",
-      owner: nextOwner,
-      previousOwner,
-      reason
-    });
-  };
-  const cancelNavigationTransaction = (navigationId, abortController) => {
-    if (navigationSequence !== navigationId || navigationAbortController !== abortController) {
-      return;
-    }
-    navigationSequence += 1;
-    navigationAbortController = null;
-    abortController.abort();
-  };
-  const completeNavigationTransaction = (navigationId, abortController) => {
-    if (navigationSequence !== navigationId || navigationAbortController !== abortController) {
-      return;
-    }
-    navigationAbortController = null;
-  };
-  const runtime = {
-    getOwnerState() {
-      const activeRuntime = registrations.get(owner);
-      return {
-        owner,
-        canHandleSpaNavigation: typeof activeRuntime?.navigate === "function"
-      };
-    },
-    hasPendingNavigationTransaction() {
-      return navigationAbortController !== null;
-    },
-    beginNavigationTransaction() {
-      navigationAbortController?.abort();
-      const abortController = new AbortController();
-      const navigationId = ++navigationSequence;
-      navigationAbortController = abortController;
-      return {
-        id: navigationId,
-        signal: abortController.signal,
-        isCurrent: () => navigationSequence === navigationId && navigationAbortController === abortController,
-        cancel: () => {
-          cancelNavigationTransaction(navigationId, abortController);
-        },
-        complete: () => {
-          completeNavigationTransaction(navigationId, abortController);
+    const registrations = new Map();
+    const listeners = new Set();
+    let owner = 'none';
+    let navigationSequence = 0;
+    let navigationAbortController = null;
+    const emit = (event) => {
+        for (const listener of listeners) {
+            listener(event);
         }
-      };
-    },
-    cancelCurrentNavigationTransaction() {
-      if (!navigationAbortController) {
-        return;
-      }
-      cancelNavigationTransaction(navigationSequence, navigationAbortController);
-    },
-    setOwner(nextOwner) {
-      updateOwner(nextOwner, "set");
-    },
-    claimOwnership(nextOwner) {
-      updateOwner(nextOwner, "claim");
-    },
-    releaseOwnership(currentOwner) {
-      if (owner !== currentOwner) {
-        return;
-      }
-      updateOwner("none", "release");
-    },
-    resolveDocumentOwner(doc, fallbackOwner = "none") {
-      return getEcoDocumentOwner(doc) ?? fallbackOwner;
-    },
-    adoptDocumentOwner(doc, fallbackOwner = "none") {
-      const nextOwner = runtime.resolveDocumentOwner(doc, fallbackOwner);
-      updateOwner(nextOwner, "document");
-      return nextOwner;
-    },
-    isOwnedByAnotherRuntime(candidateOwner) {
-      return owner !== "none" && owner !== candidateOwner;
-    },
-    subscribe(listener) {
-      listeners.add(listener);
-      return () => {
-        listeners.delete(listener);
-      };
-    },
-    register(registration) {
-      registrations.set(registration.owner, registration);
-      emit({
-        type: "registration-change",
-        owner: registration.owner,
-        status: "registered"
-      });
-      return () => {
-        const currentRegistration = registrations.get(registration.owner);
-        if (currentRegistration !== registration) {
-          return;
+    };
+    const updateOwner = (nextOwner, reason) => {
+        if (owner === nextOwner) {
+            return;
         }
-        registrations.delete(registration.owner);
+        const previousOwner = owner;
+        owner = nextOwner;
         emit({
-          type: "registration-change",
-          owner: registration.owner,
-          status: "unregistered"
+            type: 'owner-change',
+            owner: nextOwner,
+            previousOwner,
+            reason,
         });
-        if (owner === registration.owner) {
-          updateOwner("none", "unregister");
-        }
-      };
-    },
-    async requestNavigation(request) {
-      for (const candidateOwner of getCandidateOwners(owner, registrations, request.source)) {
-        const registration = registrations.get(candidateOwner);
-        if (!registration?.navigate) {
-          continue;
+    };
+    const cancelNavigationTransaction = (navigationId, abortController) => {
+        if (navigationSequence !== navigationId || navigationAbortController !== abortController) {
+            return;
         }
-        const handled = await registration.navigate(request);
-        if (handled !== false) {
-          return true;
+        navigationSequence += 1;
+        navigationAbortController = null;
+        abortController.abort();
+    };
+    const completeNavigationTransaction = (navigationId, abortController) => {
+        if (navigationSequence !== navigationId || navigationAbortController !== abortController) {
+            return;
         }
-      }
-      return false;
-    },
-    async requestHandoff(request) {
-      if (request.targetOwner === "none") {
-        return false;
-      }
-      if (request.isStaleSourceNavigation?.()) {
-        return true;
-      }
-      const registration = registrations.get(request.targetOwner);
-      if (!registration?.handoffNavigation) {
-        return false;
-      }
-      if (request.isStaleSourceNavigation?.()) {
-        return true;
-      }
-      const handled = await registration.handoffNavigation(request);
-      return handled !== false;
-    },
-    async reloadCurrentPage(request) {
-      for (const candidateOwner of getCandidateOwners(owner, registrations)) {
-        const registration = registrations.get(candidateOwner);
-        if (!registration?.reloadCurrentPage) {
-          continue;
-        }
-        await registration.reloadCurrentPage(request);
-        return true;
-      }
-      return false;
-    },
-    async cleanupOwner(targetOwner) {
-      if (targetOwner === "none") {
-        return;
-      }
-      const registration = registrations.get(targetOwner);
-      if (!registration?.cleanupBeforeHandoff) {
-        return;
-      }
-      await registration.cleanupBeforeHandoff();
-      if (owner === targetOwner) {
-        updateOwner("none", "release");
-      }
-    },
-    async cleanupCurrentOwner() {
-      await runtime.cleanupOwner(owner);
+        navigationAbortController = null;
+    };
+    const runtime = {
+        getOwnerState() {
+            const activeRuntime = registrations.get(owner);
+            return {
+                owner,
+                canHandleSpaNavigation: typeof activeRuntime?.navigate === 'function',
+            };
+        },
+        hasPendingNavigationTransaction() {
+            return navigationAbortController !== null;
+        },
+        beginNavigationTransaction() {
+            navigationAbortController?.abort();
+            const abortController = new AbortController();
+            const navigationId = ++navigationSequence;
+            navigationAbortController = abortController;
+            return {
+                id: navigationId,
+                signal: abortController.signal,
+                isCurrent: () => navigationSequence === navigationId && navigationAbortController === abortController,
+                cancel: () => {
+                    cancelNavigationTransaction(navigationId, abortController);
+                },
+                complete: () => {
+                    completeNavigationTransaction(navigationId, abortController);
+                },
+            };
+        },
+        cancelCurrentNavigationTransaction() {
+            if (!navigationAbortController) {
+                return;
+            }
+            cancelNavigationTransaction(navigationSequence, navigationAbortController);
+        },
+        setOwner(nextOwner) {
+            updateOwner(nextOwner, 'set');
+        },
+        claimOwnership(nextOwner) {
+            updateOwner(nextOwner, 'claim');
+        },
+        releaseOwnership(currentOwner) {
+            if (owner !== currentOwner) {
+                return;
+            }
+            updateOwner('none', 'release');
+        },
+        resolveDocumentOwner(doc, fallbackOwner = 'none') {
+            return getEcoDocumentOwner(doc) ?? fallbackOwner;
+        },
+        adoptDocumentOwner(doc, fallbackOwner = 'none') {
+            const nextOwner = runtime.resolveDocumentOwner(doc, fallbackOwner);
+            updateOwner(nextOwner, 'document');
+            return nextOwner;
+        },
+        isOwnedByAnotherRuntime(candidateOwner) {
+            return owner !== 'none' && owner !== candidateOwner;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        register(registration) {
+            registrations.set(registration.owner, registration);
+            emit({
+                type: 'registration-change',
+                owner: registration.owner,
+                status: 'registered',
+            });
+            return () => {
+                const currentRegistration = registrations.get(registration.owner);
+                if (currentRegistration !== registration) {
+                    return;
+                }
+                registrations.delete(registration.owner);
+                emit({
+                    type: 'registration-change',
+                    owner: registration.owner,
+                    status: 'unregistered',
+                });
+                if (owner === registration.owner) {
+                    updateOwner('none', 'unregister');
+                }
+            };
+        },
+        async requestNavigation(request) {
+            for (const candidateOwner of getCandidateOwners(owner, registrations, request.source)) {
+                const registration = registrations.get(candidateOwner);
+                if (!registration?.navigate) {
+                    continue;
+                }
+                const handled = await registration.navigate(request);
+                if (handled !== false) {
+                    return true;
+                }
+            }
+            return false;
+        },
+        async requestHandoff(request) {
+            if (request.targetOwner === 'none') {
+                return false;
+            }
+            if (request.isStaleSourceNavigation?.()) {
+                return true;
+            }
+            const registration = registrations.get(request.targetOwner);
+            if (!registration?.handoffNavigation) {
+                return false;
+            }
+            if (request.isStaleSourceNavigation?.()) {
+                return true;
+            }
+            const handled = await registration.handoffNavigation(request);
+            return handled !== false;
+        },
+        async reloadCurrentPage(request) {
+            for (const candidateOwner of getCandidateOwners(owner, registrations)) {
+                const registration = registrations.get(candidateOwner);
+                if (!registration?.reloadCurrentPage) {
+                    continue;
+                }
+                const handled = await registration.reloadCurrentPage(request);
+                return handled !== false;
+            }
+            return false;
+        },
+        async cleanupOwner(targetOwner) {
+            if (targetOwner === 'none') {
+                return;
+            }
+            const registration = registrations.get(targetOwner);
+            if (!registration?.cleanupBeforeHandoff) {
+                return;
+            }
+            await registration.cleanupBeforeHandoff();
+            if (owner === targetOwner) {
+                updateOwner('none', 'release');
+            }
+        },
+        async cleanupCurrentOwner() {
+            await runtime.cleanupOwner(owner);
+        },
+    };
+    if (typeof window !== 'undefined') {
+        window.addEventListener('pageshow', (event) => {
+            if (event.persisted) {
+                runtime.cancelCurrentNavigationTransaction();
+            }
+        });
+        window.addEventListener('pagehide', () => {
+            runtime.cancelCurrentNavigationTransaction();
+        });
     }
-  };
-  if (typeof window !== "undefined") {
-    window.addEventListener("pageshow", (event) => {
-      if (event.persisted) {
-        runtime.cancelCurrentNavigationTransaction();
-      }
-    });
-    window.addEventListener("pagehide", () => {
-      runtime.cancelCurrentNavigationTransaction();
-    });
-  }
-  return runtime;
+    return runtime;
 }
-function getEcoNavigationRuntime(windowObject = window) {
-  const runtimeWindow = windowObject;
-  runtimeWindow.__ECO_PAGES__ = runtimeWindow.__ECO_PAGES__ || {};
-  if (!runtimeWindow.__ECO_PAGES__.navigation) {
-    runtimeWindow.__ECO_PAGES__.navigation = createEcoNavigationRuntime();
-  }
-  return runtimeWindow.__ECO_PAGES__.navigation;
+/**
+ * Returns the singleton browser-side navigation coordinator.
+ *
+ * The coordinator centralizes ownership, handoff, and current-page reload
+ * requests across browser runtimes through one internal protocol.
+ *
+ * @param windowObject - Window-like object that stores the singleton runtime.
+ * @returns The shared browser navigation coordinator.
+ */
+export function getEcoNavigationRuntime(windowObject = window) {
+    const runtimeWindow = windowObject;
+    runtimeWindow.__ECO_PAGES__ = runtimeWindow.__ECO_PAGES__ || {};
+    if (!runtimeWindow.__ECO_PAGES__.navigation) {
+        runtimeWindow.__ECO_PAGES__.navigation = createEcoNavigationRuntime();
+    }
+    return runtimeWindow.__ECO_PAGES__.navigation;
 }
-export {
-  ECO_DOCUMENT_OWNER_ATTRIBUTE,
-  getEcoDocumentOwner,
-  getEcoNavigationRuntime
-};

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 {};