@ogygia/core 0.12.2 → 0.13.0

package/dist/runtime/router-nav.d.ts

@@ -1,4 +1,4 @@
-import { SpaRouter } from "./router.js";
+import { HistoryEntry, SpaRouter } from "./router.js";
 /**
  * Why a page fetch is happening — sent to the server so it can skip side effects a speculative or
  * restorative fetch must not fire (analytics beacons, "last seen" writes, one-time banners):
@@ -34,18 +34,31 @@ export declare function install_head_style(source: Element, head?: HTMLHeadEleme
  *  script in the streamed head does this progressively during parse — this is the swap-path
  *  twin. Islands inside the adopted content are custom elements: they connect and wake alone. */
 export declare function apply_late_templates(root: ParentNode): void;
+/** A page as a fetch got it: its HTML and the address it belongs to (where the fetch landed, after
+ *  the server's redirects; the requested href when there were none). */
+export type FetchedPage = {
+  html: string;
+  url: string;
+};
+/** Moves the world the cached pages are made in: what is kept goes, and a fetch that started before
+ *  the move (a prefetch out when a remote mutation lands) never fills the cache after it with the
+ *  page as it was (#208), and a navigation that waited on it fetches again. (No pages yet: none to
+ *  put out of date.) */
 export declare function bust_page_cache(): void;
-export declare function page_cache_size(): number;
-export declare function fetch_page(href: string, signal?: AbortSignal, purpose?: NavPurpose): Promise<string | null>;
-export declare function navigate(r: SpaRouter, url: URL, from: URL, { push, pop_scroll, type, replace }?: {
+/**
+ * The page at `href`, as HTML plus the address it belongs to: a server redirect (a Kit `redirect()`
+ * in load, a trailing-slash canonicalization) is followed by `fetch` transparently, and
+ * `response.url` is its only trace. The landing travels WITH the HTML, through the cache and to the
+ * navigation that reads it, so nothing else (a cache clear, another fetch) can take it away.
+ */
+export declare function fetch_page(href: string, signal?: AbortSignal, purpose?: NavPurpose): Promise<FetchedPage | null>;
+export declare function navigate(r: SpaRouter, url: URL, from: URL, { push, pop, type, replace }?: {
   push?: boolean;
-  pop_scroll?: {
-    x: number;
-    y: number;
-  } | null;
+  /** the entry a back or forward step is on (./router.ts `RouterHistory`) */
+  pop?: HistoryEntry;
   type?: string;
   replace?: boolean;
-}): Promise<void>;
+}, claim?: SpaRouter["nav"]["now"]): Promise<void>;
 /**
  * Soft invalidate: refresh page/remote seeds for the current URL without navigation.
  *
@@ -57,7 +70,14 @@ export declare function navigate(r: SpaRouter, url: URL, from: URL, { push, pop_
  * that need query updates use `.refresh()`, or `submit().updates(q)` with server
  * `requested(q).refreshAll()` (updates alone does not populate response `q`).
  *
- * Uses a separate abort/generation from hard `navigate()` so soft fetches never cancel
- * an in-flight click navigation (and vice versa).
+ * Its own machine (`soft`, ./soft-refresh.ts, which the boot holds: a page without the router
+ * refreshes too) so soft fetches never cancel an in-flight click navigation; a real navigation's
+ * commit ends a soft refresh in flight.
+ *
+ * It refreshes the PAGE ON SCREEN (`on_screen`: the router's, which knows it; the address bar
+ * without the router), never the page a navigation is still bringing (#268). The refreshed page is
+ * staged like a navigation's (`stage`): fetched and parsed off to the side, merged in one commit,
+ * which a navigation that went in first refuses (its commit ended this refresh). A refresh whose
+ * devalue fails to load ends, and says so to its caller.
  */
-export declare function invalidate_all(): Promise<void>;
+export declare function invalidate_all(on_screen?: URL | null): Promise<void>;