npm - @ecopages/browser-router - Versions diffs - 0.2.0-alpha.3 → 0.2.0-alpha.31 - Mend

@ecopages/browser-router 0.2.0-alpha.3 → 0.2.0-alpha.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (67) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -8,19 +8,20 @@ All notable changes to `@ecopages/browser-router` are documented here.
 ### Features
-- **Light-DOM custom element support in `dom-swapper`** — `morphdom` morphing process now correctly handles light-DOM custom elements during page transitions (`fce8080c`).
-- **Improved `morphHead` script injection** — New scripts from the incoming page's `<head>` are now injected and executed correctly during client-side navigation, even when not marked with `data-eco-rerun` (`08e15e99`).
-- **Global injector lifecycle management** — Enhanced global injector with structured lifecycle hooks and tests for hydration script handling (`2ba35aa4`).
+- Added cross-router handoff hooks, configurable `<html>` attribute syncing, and public document sync helpers.
 ### Bug Fixes
-- Published npm package metadata now includes validated declaration exports for generated dist entrypoints.
-- Registered a current-page HMR refresh hook that invalidates cached HTML before re-fetching the active route.
+- Fixed navigation races, duplicate script injection, and stale cleanup during repeated page swaps.
+- Fixed mixed-runtime document ownership, script reruns, persisted head scripts, and client-managed `<html>` state during browser-router navigations.
+- Fixed skipped View Transition lifecycle aborts leaking as unhandled browser-router test errors.
+- Fixed body morph swaps retaining stale content when pages contain duplicate `id` attributes by limiting morphdom keying to explicitly persisted nodes.
+- Fixed browser-router stylesheet prefetching to warm future page CSS without injecting unused `preload` hints that trigger browser console warnings.
 ### Refactoring
-- Removed unused `@types/morphdom` dev dependency (`ceb243d0`).
+- Routed handoff and current-page reload behavior through the shared navigation coordinator.
 ### Documentation
-- README updated with new API usage examples.
+- Updated the README examples for the current router API.

package/README.md CHANGED Viewed

@@ -1,34 +1,38 @@
 # @ecopages/browser-router
-Client-side navigation and view transitions for Ecopages. Intercepts same-origin link clicks to provide smooth page transitions without full page reloads.
+Client-side navigation and view transitions for Ecopages. It intercepts same-origin link clicks to provide smooth page transitions without full page reloads.
 ## Features
-- **Client-side navigation** - Intercepts `<a>` clicks for fast navigation
-- **Efficient DOM diffing** - Uses [morphdom](https://github.com/patrick-steele-idem/morphdom) to update only what changed, preserving scroll positions and internal state
-- **State persistence** - Elements with `data-eco-persist` are never recreated, preserving internal state
-- **View Transitions** - Optional integration with the View Transition API
-- **Lifecycle events** - Hook into navigation with `eco:before-swap`, `eco:after-swap`, `eco:page-load`
+- **Client-side navigation**: Intercepts `<a>` clicks for robust, fast navigation.
+- **Efficient DOM diffing**: Uses [morphdom](https://github.com/patrick-steele-idem/morphdom) to update only what changed, preserving scroll positions and internal state.
+- **State persistence**: Elements with `data-eco-persist` are never recreated, preserving Web Component state, event listeners, and form values.
+- **View Transitions**: Optional integration with the View Transition API.
+- **Lifecycle events**: Hook into navigation with `eco:before-swap`, `eco:after-swap`, `eco:page-load`.
 ## Compatibility
-This package works with MPA-style rendering (KitaJS, Lit, vanilla JS) where the server returns full HTML pages.
+This package is designed for MPA-style rendering where the server returns full HTML pages (e.g., KitaJS, Lit, vanilla JS, or component-level React islands).
-**Not compatible with React/Preact** - These frameworks manage their own virtual DOM and component trees. Replacing the DOM breaks hydration, state, and event handlers. For React apps, use a framework-specific routing solution.
+> [!WARNING]
+> **Not compatible with full React applications.**
+> If you are building a React application, use [@ecopages/react-router](../react-router/README.md) instead, as React manages its own virtual DOM and hydration lifecycle.
-Component-level islands are a narrower case: small interactive roots emitted by another integration (for example a React island inside an otherwise MPA-style page) can work with `@ecopages/browser-router`, because ownership stays scoped to the island root instead of the full document.
+> [!NOTE]
+> `@ecopages/browser-router` can still participate in mixed sites that contain both React-router pages and non-React pages. In that setup, browser-router remains responsible for DOM-swapping non-React documents, and React-router can hand off already-fetched non-React pages to it through the shared navigation coordinator.
 ## Installation
 ```bash
-bunx jsr add @ecopages/browser-router
+bun add @ecopages/browser-router
 ```
 ## Usage
 Create and start the router in a **global** client-side script (e.g., `src/layouts/base-layout.script.ts`).
-> **Important**: Ensure the router script is injected in a **consistent order** within the `<head>` across all pages. Inconsistent ordering (e.g. script between styles on one page but after on another) causes `morphdom` to reload styles, leading to a "Flash of Unstyled Content" (FOUC).
+> [!IMPORTANT]
+> Ensure the router script is injected in a **consistent order** within the `<head>` across all pages. Inconsistent ordering causes `morphdom` to reload styles, leading to a "Flash of Unstyled Content" (FOUC).
 ```ts
 import { createRouter } from '@ecopages/browser-router/client';
@@ -45,54 +49,71 @@ import { createRouter } from '@ecopages/browser-router/client';
 const router = createRouter({
 	viewTransitions: true,
 	scrollBehavior: 'auto',
+	documentElementAttributesToSync: ['lang', 'dir', 'data-theme'],
 });
 ```
+By default, browser-router only syncs root `<html>` metadata it owns. Client-managed attributes and classes such as theme state are preserved unless you explicitly include them in `documentElementAttributesToSync`.
+For advanced cases, browser-router also exports low-level document sync tooling without changing the router instance API:
+```ts
+import {
+	createRouter,
+	defaultDocumentElementAttributesToSync,
+	syncDocumentElementAttributes,
+} from '@ecopages/browser-router';
+const router = createRouter();
+document.addEventListener('eco:before-swap', (event) => {
+	syncDocumentElementAttributes(document, event.detail.newDocument, [
+		...defaultDocumentElementAttributesToSync,
+		'data-theme',
+	]);
+});
+```
+Loading the router script is the opt-in point for browser-router-managed navigation on that page shell. Pages without the router script continue to use normal document navigation.
 ## Configuration
-| Option             |              Type               |       Default        | Description                                    |
-| :----------------- | :-----------------------------: | :------------------: | :--------------------------------------------- |
-| `linkSelector`     |            `string`             |     `'a[href]'`      | Selector for links to intercept                |
-| `persistAttribute` |            `string`             | `'data-eco-persist'` | Attribute to mark elements for DOM persistence |
-| `reloadAttribute`  |            `string`             | `'data-eco-reload'`  | Attribute to force full page reload            |
-| `updateHistory`    |            `boolean`            |        `true`        | Whether to update browser history              |
-| `scrollBehavior`   | `'top' \| 'preserve' \| 'auto'` |       `'top'`        | Scroll behavior after navigation               |
-| `viewTransitions`  |            `boolean`            |       `false`        | Use View Transition API for animations         |
-| `smoothScroll`     |            `boolean`            |       `false`        | Use smooth scrolling during navigation         |
+| Option                            | Type                            | Default                                      | Description                                                                                 |
+| :-------------------------------- | :------------------------------ | :------------------------------------------- | :------------------------------------------------------------------------------------------ |
+| `linkSelector`                    | `string`                        | `'a[href]'`                                  | Selector for links to intercept                                                             |
+| `documentElementAttributesToSync` | `string[]`                      | `['lang', 'dir', 'data-eco-document-owner']` | `<html>` attributes to sync from the incoming document; other root attributes are preserved |
+| `persistAttribute`                | `string`                        | `'data-eco-persist'`                         | Attribute to mark elements for DOM persistence                                              |
+| `reloadAttribute`                 | `string`                        | `'data-eco-reload'`                          | Attribute to force full page reload                                                         |
+| `updateHistory`                   | `boolean`                       | `true`                                       | Whether to update browser history                                                           |
+| `scrollBehavior`                  | `'top' \| 'preserve' \| 'auto'` | `'top'`                                      | Scroll behavior after navigation                                                            |
+| `viewTransitions`                 | `boolean`                       | `false`                                      | Use View Transition API for animations                                                      |
+| `smoothScroll`                    | `boolean`                       | `false`                                      | Use smooth scrolling during navigation                                                      |
 ## Persistence
-Mark elements to preserve across navigations. These elements are never recreated during navigation, morphdom skips them entirely, preserving their internal state (event listeners, web component state, form values, etc.):
+Mark elements to preserve across navigations. These elements are never recreated during navigation; morphdom skips them entirely.
 ```html
-<!-- This counter keeps its state across all navigations -->
+<!-- This counter keeps its internal state across all navigations -->
 <radiant-counter data-eco-persist="counter"></radiant-counter>
 ```
 ## Script Re-execution
-To force a script to re-execute on every navigation (e.g. analytics, hydration), add `data-eco-rerun` and `data-eco-script-id`:
+To force a script to re-execute on every navigation (e.g., analytics), add `data-eco-rerun`:
 ```html
-<script data-eco-rerun="true" data-eco-script-id="analytics">
-	// This runs on every navigation
+<script data-eco-rerun="true">
 	trackPageview();
 </script>
 ```
-### React islands with `@ecopages/browser-router`
-When `@ecopages/browser-router` is used in an MPA-style app that also renders component-level React islands:
-- island hydration scripts may need to run again after `eco:after-swap`
-- hydration bootstraps should carry stable `data-eco-script-id` metadata
-- `data-eco-rerun` allows those bootstraps to be re-executed safely during head reconciliation
-This note is specific to DOM-swapping navigation with `@ecopages/browser-router`. It does **not** apply to full React applications using [@ecopages/react-router](../react-router/README.md), where page routing and hydration are handled by the React router runtime itself.
+> [!NOTE]
+> `data-eco-script-id` is optional. Use it when you want an explicit stable identity for a rerun script. Otherwise the router falls back to matching by original `src` and inline content.
 ## Force Full Reload
-Use `data-eco-reload` to force a full page reload:
+Use `data-eco-reload` on an anchor tag to bypass the router and force a full page reload:
 ```html
 <a href="/logout" data-eco-reload>Logout</a>
@@ -100,12 +121,12 @@ Use `data-eco-reload` to force a full page reload:
 ## Events
-Listen to navigation lifecycle events:
+Listen to navigation lifecycle events on the `document`:
 ```ts
 document.addEventListener('eco:before-swap', (e) => {
 	console.log('Navigating to:', e.detail.url);
-	// Call e.detail.reload() to abort and do full reload
+	// Call e.detail.reload() to abort client-side navigation and do a full reload
 });
 document.addEventListener('eco:after-swap', (e) => {
@@ -119,6 +140,8 @@ document.addEventListener('eco:page-load', (e) => {
 ## Programmatic Navigation
+Use the router instance to navigate programmatically:
 ```ts
 import { createRouter } from '@ecopages/browser-router/client';

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/browser-router",
-  "version": "0.2.0-alpha.3",
+  "version": "0.2.0-alpha.31",
   "description": "Client-side router for Ecopages with view transitions support",
   "keywords": [
     "ecopages",
@@ -32,8 +32,10 @@
     "directory": "packages/browser-router"
   },
   "dependencies": {
-    "@ecopages/core": "0.2.0-alpha.3",
     "morphdom": "^2.7.8"
   },
+  "peerDependencies": {
+    "@ecopages/core": "0.2.0-alpha.31"
+  },
   "types": "./src/index.d.ts"
 }

package/src/client/document-element-sync.d.ts ADDED Viewed

@@ -0,0 +1,24 @@
+/**
+ * Helpers for synchronizing selected root `<html>` attributes during client-side navigation.
+ * @module
+ */
+/**
+ * Default root `<html>` attributes that browser-router treats as document-owned.
+ *
+ * These attributes are synchronized from the incoming document during navigation.
+ * Other root attributes are preserved unless explicitly included.
+ */
+export declare const defaultDocumentElementAttributesToSync: string[];
+/**
+ * Synchronizes a selected set of root `<html>` attributes from an incoming document
+ * onto the current live document.
+ *
+ * Attributes listed here are treated as document-owned metadata. Attributes not
+ * listed remain untouched on the live document so client-managed state can survive
+ * across navigation swaps.
+ *
+ * @param currentDocument - The live document being updated
+ * @param newDocument - The parsed incoming document for the next page
+ * @param attributes - Root `<html>` attributes to synchronize
+ */
+export declare function syncDocumentElementAttributes(currentDocument: Document, newDocument: Document, attributes: readonly string[]): void;

package/src/client/document-element-sync.js ADDED Viewed

@@ -0,0 +1,20 @@
+import { DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC } from "./types.js";
+const defaultDocumentElementAttributesToSync = DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC;
+function syncDocumentElementAttributes(currentDocument, newDocument, attributes) {
+  const currentHtml = currentDocument.documentElement;
+  const nextHtml = newDocument.documentElement;
+  for (const attributeName of attributes) {
+    const nextValue = nextHtml.getAttribute(attributeName);
+    if (nextValue === null) {
+      currentHtml.removeAttribute(attributeName);
+      continue;
+    }
+    if (currentHtml.getAttribute(attributeName) !== nextValue) {
+      currentHtml.setAttribute(attributeName, nextValue);
+    }
+  }
+}
+export {
+  defaultDocumentElementAttributesToSync,
+  syncDocumentElementAttributes
+};

package/src/client/eco-router.d.ts CHANGED Viewed

@@ -9,12 +9,36 @@ import type { EcoRouterOptions } from './types.js';
  */
 export declare class EcoRouter {
     private options;
-    private abortController;
+    private unregisterNavigationRuntime;
+    private started;
+    private pendingNavigations;
+    private pendingPointerNavigation;
+    private pendingHoverNavigation;
+    private queuedNavigationHref;
     private domSwapper;
     private scrollManager;
     private viewTransitionManager;
     private prefetchManager;
     constructor(options?: EcoRouterOptions);
+    private getLinkFromEvent;
+    private canInterceptLink;
+    private getRecoveredPointerHref;
+    private getRecoveredHoverHref;
+    private isAnotherNavigationRuntimeActive;
+    private getDocumentOwner;
+    private adoptDocumentOwner;
+    private syncDocumentElementAttributes;
+    private reloadDocument;
+    /**
+     * Commits a fully fetched document into the live page.
+     *
+     * When browser-router accepts a handoff from another runtime, it delays source
+     * runtime cleanup until the incoming document has been prepared and is ready to
+     * commit. That ordering avoids the blank-page window we previously hit when a
+     * delegated navigation went stale after the source runtime had already torn
+     * itself down.
+     */
+    private commitDocumentNavigation;
     /**
      * Starts the router and begins intercepting navigation.
      *
@@ -51,6 +75,8 @@ export declare class EcoRouter {
      * Uses `event.composedPath()` to correctly detect clicks on anchors inside
      * Shadow DOM boundaries (Web Components).
      */
+    private handlePointerDown;
+    private handleHoverIntent;
     private handleClick;
     /**
      * Handles browser back/forward navigation.
@@ -62,6 +88,8 @@ export declare class EcoRouter {
      * Cross-origin navigation always falls back to full page reload.
      */
     private isSameOrigin;
+    private cancelNavigationTransaction;
+    private beginNavigationTransaction;
     /**
      * Executes the core navigation flow.
      *
@@ -91,6 +119,12 @@ export declare class EcoRouter {
 }
 /**
  * Creates and starts a router instance.
+ *
+ * Stops the previously active router (if any) before creating a new one so
+ * click listeners and coordinator registrations from earlier instances are
+ * cleaned up on re-execution (e.g. when the layout script is re-run via
+ * `data-eco-rerun` after a browser-router page commit).
+ *
  * @param options - Configuration options for the router
  * @returns A started EcoRouter instance
  */