@ogygia/core 0.12.2 → 0.13.0

package/dist/runtime/router.d.ts

@@ -1,3 +1,5 @@
+import { FetchedPage } from "./router-nav.js";
+import { Navigation } from "./navigation.js";
 /**
  * The `<a>` a pointer event is about — through SHADOW ROOTS. A click inside a web component's
  * shadow tree (a web component such as `<x-link>`, `<x-button href>`, a breadcrumb item)
@@ -60,24 +62,63 @@ export declare function same_document_link(url: URL, current: URL, in_flight: st
 export declare function document_key(url: URL): string;
 /** Instant scroll to a hash target (or top). Ignores CSS `scroll-behavior: smooth`. */
 export declare function jump_to_hash(hash: string): void;
+/** One entry of the visitor's history the router made (or took over): its address, and where the
+ *  page was when the visitor left it: its scroll, and the id of the element that had focus. */
+export interface HistoryEntry {
+  readonly id: string;
+  url: URL;
+  scroll: {
+    x: number;
+    y: number;
+  } | null;
+  focus: string | null;
+}
+/** How a navigation writes history: a new entry, the current one's address, or the entry a back or
+ *  forward step is already on. */
+export type HistoryMove = "push" | "replace" | "pop";
+export declare class RouterHistory {
+  #private;
+  /** The entry of the page on screen. */
+  get current(): HistoryEntry;
+  /** Takes over the entry the browser is on as the router starts: its state names it now. */
+  start(): void;
+  /** The entry a history state names: this model's, `'foreign'` (another document's), or null
+   *  (no id: an entry the browser or the app made). */
+  find(state: unknown): HistoryEntry | "foreign" | null;
+  /** The page on screen is being left: keep where it is. */
+  leave(): void;
+  /** A page goes in at `url` (the browser's entry is written now). `push`: a new entry after the
+   *  one left; `replace`: the current one at a new address; `pop`: `to`, the entry a back or
+   *  forward step is on. */
+  commit(url: URL, move: HistoryMove, to?: HistoryEntry): HistoryEntry;
+  /** The entry the browser stepped to, which no id names: this model's from now on. */
+  adopt(url: URL): HistoryEntry;
+}
 export declare class SpaRouter {
   #private;
-  /** href of the navigation in flight (set before the fetch, cleared when applied or aborted) */
-  nav_target: string | null;
-  /** The in-flight navigation's cancel handle: router-nav bumps `nav_gen` and sets `nav_abort` for
-   *  each navigation it starts, and stops at its next step once `nav_gen` moved on. */
-  nav_gen: number;
-  nav_abort: AbortController | null;
-  /** pathname+search of the document currently in the DOM (hash ignored). */
-  doc_key: string;
   /**
-   * Full URL of the document currently displayed in the DOM. `navigate()` uses this as its `from`
+   * THE NAVIGATION, one machine (./navigation.ts): idle, claimed (the click, while the navigation
+   * chunk loads), loading (its fetch through its swap), settling (swapped: the last steps run). A
+   * new click is a new visit, so whatever the old one still had in flight sees it is not current
+   * (`nav.now !== mine`) and stops, and its fetch is aborted. It was three fields kept by hand; two
+   * clicks during the first chunk load once held the same generation and the last one was lost.
+   */
+  readonly nav: Navigation;
+  /** href of the router's navigation in flight (claimed or loading; cleared once it applied,
+   *  ended, or went to the browser: `hand_off`) */
+  get nav_target(): string | null;
+  /** The visitor's history, as the router keeps it (`RouterHistory`): the rest is read from it. */
+  readonly history: RouterHistory;
+  /**
+   * Full URL of the page on screen: its history entry's. `navigate()` uses this as its `from`
    * instead of `location.href`, because on a `popstate` (back/forward) the browser has ALREADY
    * changed `location` to the target — so `location.href` would equal the target and the
    * same-document guard would wrongly bail into the hash-only branch, never swapping the body
    * (browser back left the old page's DOM in place). POP-FROM.
    */
-  current_url: URL | null;
+  get current_url(): URL;
+  /** pathname+search of the page on screen (hash ignored). */
+  get doc_key(): string;
   beforeNavigate(fn: BeforeNavigateCallback): () => boolean;
   afterNavigate(fn: AfterNavigateCallback): () => boolean;
   /**
@@ -88,15 +129,38 @@ export declare class SpaRouter {
    * swapping left the URL on the old page and `/plain` in the DOM).
    */
   supersede(): void;
+  /**
+   * GIVE `visit`'s NAVIGATION TO THE BROWSER — a page the router will not render (a csr=true Kit
+   * page, a page that is not ogygia's, another build), or one it could not fetch or load its code
+   * for: a document navigation to `url`, from the document on screen (`from`).
+   *
+   * It ENDS the visit, on every path: from here on the navigation is the browser's, never the
+   * router's in flight. The browser may well keep this page on screen (a file download, a 204, a
+   * body it does not show), and then nothing else ends it: left `loading`, every later click on the
+   * link joined it and was swallowed (#266). A visit already left (a newer click took over, or back
+   * to the page on screen) hands nothing off: the browser never goes where the visitor no longer is.
+   *
+   * The router writes an entry only when a page goes in, so a click handed off has none: the
+   * browser's navigation is a new entry of its own, and one it keeps the page on screen for adds
+   * none (#297). A back or forward step is already on its entry, and a refresh on the one on
+   * screen: the browser's navigation REPLACES it, so its document holds the entry alone, never
+   * shares it with the router's page (back from a csr=true page then loads the router page, #259).
+   * So does a commit that failed after it wrote the entry (the address is already `url`).
+   *
+   * `error`: the navigation failed part way (its devalue did not load, its swap threw, #276). It
+   * is said (the page's error handler, as an uncaught throw would be), and the browser loads the
+   * page whole.
+   */
+  hand_off(url: URL, visit: Navigation["now"], move: HistoryMove, error?: unknown): void;
   bust_page_cache(): void;
-  _page_cache_size(): number;
-  fetch_page(href: string, signal?: AbortSignal, purpose?: "nav" | "prefetch" | "history"): Promise<string | null>;
+  /** The page at `href`, or `null` when there is none to have: the fetch failed (./router-nav.ts
+   *  `fetch_page`), or the navigation code itself did not load. The prefetches (a hover, a
+   *  viewport link, `preloadData`) start it and never wait on it: a rejection here was uncaught. */
+  fetch_page(href: string, signal?: AbortSignal, purpose?: "nav" | "prefetch" | "history"): Promise<FetchedPage | null>;
   navigate(url: URL, opts?: {
     push?: boolean;
-    pop_scroll?: {
-      x: number;
-      y: number;
-    } | null;
+    /** the entry a back or forward step is on */
+    pop?: HistoryEntry;
     type?: string;
     replace?: boolean;
   }): Promise<void>;
@@ -122,7 +186,9 @@ export declare class SpaRouter {
    * After start + every navigation, in IDLE: eager links warm now; viewport links get observed.
    * Only anchors under a preload-marked element are read — an unmarked anchor has no trigger. Idle,
    * because the scan competes with the freshly swapped page's own islands for the main thread and
-   * a warm is speculation by definition.
+   * a warm is speculation by definition. The scan and its observer are the page visit's
+   * (./session.ts `PageVisit`): the next page's swap disconnects it, so the anchors of a page left
+   * behind are never held, and a scan still waiting for idle time when its page is left never runs.
    */
   scan_preload_links(): void;
 }
@@ -140,8 +206,6 @@ export declare function beforeNavigate(fn: BeforeNavigateCallback): () => boolea
 export declare function afterNavigate(fn: AfterNavigateCallback): () => boolean;
 /** Drop all warmed page HTML (call after mutations / auth changes). */
 export declare function bust_page_cache(): void;
-/** Test helper — current warmed entry count. */
-export declare function _page_cache_size(): number;
 /**
  * Programmatic same-origin navigation. Mirrors Kit's `goto()` subset.
  * @param url - Absolute or relative URL (http(s) only).