@warp-drive-mirror/core 5.10.0-alpha.10 → 5.10.0-alpha.13

package/dist/{-private-CjK1Dmuh.js → -private-BpyvBYFj.js}

@@ -1,5 +1,5 @@
 import { getOrSetGlobal, peekTransient, setTransient } from "./types/-private.js";
-import { f as setPromiseResult, o as DOMError, u as getPromiseResult } from "./request-Di274pQz.js";
+import { f as setPromiseResult, o as DOMError, u as getPromiseResult } from "./request-MiwUbGdT.js";
 import { getGlobalConfig, macroCondition } from "@embroider/macros";
 
 //#region src/signals/reactivity/configure.ts
@@ -34,6 +34,8 @@ const OBJECT_SIGNAL = getOrSetGlobal("#{}", Symbol("#{}"));
 * scenarios you may also be interested in integrating with the {@link NotificationManager}
 * more directly.
 *
+* @summary The create, consume, notify, and memo hooks a framework or TC39 signals implementation
+* supplies to `setupSignals` to make WarpDrive data reactive.
 * @public
 */
 /**
@@ -49,6 +51,8 @@ const OBJECT_SIGNAL = getOrSetGlobal("#{}", Symbol("#{}"));
 * }
 * ```
 *
+* @summary The options passed to the `setupSignals` callback, including the well-known key WarpDrive
+* uses for an array's contents signal.
 * @public
 */
 /**
@@ -61,6 +65,8 @@ const OBJECT_SIGNAL = getOrSetGlobal("#{}", Symbol("#{}"));
 * See {@link SignalHooks} for the implementation the callback function should
 * return.
 *
+* @summary Registers the signal hooks WarpDrive uses for reactivity, built by a callback that receives
+* `HooksOptions`.
 * @public
 * @param buildConfig - a function that takes options and returns a configuration object
 */
@@ -615,6 +621,8 @@ async function watchStream(stream, loadingState) {
 * reactive properties that can be used to build UIs that respond
 * to the progress of a request.
 *
+* @summary Reactive download progress for a request, such as bytes loaded and timing, built by lazily
+* reading its response stream.
 * @hideconstructor
 */
 var RequestLoadingState = class {
@@ -833,9 +841,11 @@ defineNonEnumerableSignal(RequestLoadingState.prototype, "_lastPacketTime", 0);
 *
 */
 /**
-* The state of a request in the "cancelled" state.
-* This is the state of a promise that has been
-* cancelled.
+* The state of a request that was aborted before it settled.
+*
+* A cancelled request has `status: 'cancelled'` and its `reason` is an
+* `AbortError`. `isError` is also `true`, as for a {@link RejectedRequest},
+* so check `status` or `isCancelled` to tell the two apart.
 *
 */
 /**
@@ -869,6 +879,8 @@ defineNonEnumerableSignal(RequestLoadingState.prototype, "_lastPacketTime", 0);
 * - {@link RejectedRequest}
 * - {@link CancelledRequest}
 *
+* @summary The reactive pending, fulfilled, rejected, or cancelled state of a request `Future`, as
+* returned by `getRequestState`.
 */
 const RequestStateProto = {};
 function performRefresh(requester, request, isReload) {
@@ -923,7 +935,7 @@ function createRequestState(future) {
 		if (state.isError) {
 			promiseState.error = state.result;
 			promiseState.reason = state.result;
-			promiseState.status = "rejected";
+			promiseState.status = isAbortError(state.result) ? "cancelled" : "rejected";
 			promiseState.isError = true;
 			promiseState.isPending = false;
 			promiseState.isLoading = false;
@@ -959,7 +971,7 @@ function createRequestState(future) {
 		});
 		promiseState.error = error;
 		promiseState.reason = error;
-		promiseState.status = "rejected";
+		promiseState.status = isAbortError(error) ? "cancelled" : "rejected";
 		promiseState.isError = true;
 		promiseState.isPending = false;
 		promiseState.isLoading = false;
@@ -971,6 +983,26 @@ function createRequestState(future) {
 /**
 * `getRequestState` can be used in both JavaScript and Template contexts.
 *
+* It returns a {@link RequestState}: a reactive object that updates as the
+* request advances. Calling it again with the same {@link Future} returns the
+* same object. Check `status` to narrow it to one of four states:
+*
+* - {@link PendingRequest} (`'pending'`) is the initial state, before the
+*   request settles.
+* - {@link ResolvedRequest} (`'fulfilled'`) holds the response content on `value`.
+* - {@link RejectedRequest} (`'rejected'`) holds the error on `reason`.
+* - {@link CancelledRequest} (`'cancelled'`) is a request that was aborted.
+*   `isError` is also `true` for a cancelled request, so check `status` or
+*   `isCancelled` rather than `isError` if you handle it differently.
+*
+* Every state also exposes a {@link RequestLoadingState} on `loadingState`
+* for tracking the progress of the response stream.
+*
+* The [Reactive Control Flow](/guides/the-manual/reactivity/control-flow) guide shows
+* how to render request states with it, and
+* [Using The Response](/guides/the-manual/requests/using-the-response) covers the
+* `Future` it reads.
+*
 * ```ts
 * import { getRequestState } from '@warp-drive-mirror/ember';
 *
@@ -1017,6 +1049,10 @@ function createRequestState(future) {
 * which offers a number of additional capabilities for requests *beyond* what
 * `RequestState` provides.
 *
+* @param future - the request {@link Future} to track, as returned by `store.request` or `requestManager.request`
+* @return the cached {@link RequestState} for `future`
+* @summary Returns a cached, reactive state object tracking a request `Future` through pending, success,
+* error, and cancellation.
 */
 function getRequestState(future) {
 	let state = RequestCache.get(future);
@@ -1092,28 +1128,47 @@ function isNeverString(val) {
 /**
 * The individual autorefresh strategies a {@link RequestSubscription}
 * may combine, see {@link AutorefreshBehaviorCombos}.
+*
+* @summary One autorefresh trigger for a request subscription: on reconnecting (`online`), on a timer
+* (`interval`), or on store invalidation (`invalid`).
 */
 /**
 * The value accepted by {@link SubscriptionArgs.autorefresh}: either a
 * boolean, a single {@link AutorefreshBehaviorType}, or a comma-separated
 * combination of up to three of them.
+*
+* @summary The accepted values for a request subscription's `autorefresh` option: a boolean or a
+* comma-separated mix of `online`, `interval`, and `invalid`.
 */
 /**
 * Utilities to assist in recovering from the error.
+*
+* @summary The online and visibility state plus a `retry` function that a request subscription exposes
+* for recovering from a failed request.
 */
 /** @deprecated use {@link RecoveryFeatures} */
 /**
 * Utilities for keeping the request fresh
+*
+* @summary The online, visibility, and refreshing state plus `refresh`, `reload`, and `abort` functions a
+* request subscription exposes alongside successful content.
 */
 /**
 * The args accepted by the `<Request />` component.
+*
+* @summary The arguments of the `<Request />` component: the request or query to run, autorefresh
+* options, and an optional store or subscription.
 */
 /**
 * The args accepted by a {@link RequestSubscription}.
+*
+* @summary Options for a request subscription: the request or query to monitor and its autorefresh settings.
 */
 /**
 * A reactive class
 *
+* @summary Reactive subscription that monitors a request or query, tracking online, visibility and refresh state and
+* handling autorefresh, reload and retry.
 * @hideconstructor
 */
 var RequestSubscription = class {
@@ -1544,6 +1599,9 @@ function isStore(store) {
 /**
 * Creates a {@link RequestSubscription}, the reactive class powering the
 * `<Request />` component's autorefresh, retry, and refresh behaviors.
+*
+* @summary Creates a reactive subscription to a request or query that tracks its state and handles
+* autorefresh, retry, and refresh.
 */
 function createRequestSubscription(store, args) {
 	return new RequestSubscription(store, args);
@@ -1610,6 +1668,8 @@ function getHref(link) {
 * }
 * ```
 *
+* @summary Experimental: one page of a paginated collection, exposing its request, loading and error status, data,
+* and links to neighboring pages.
 * @since 5.9.0
 * @public
 * @hideconstructor
@@ -1792,63 +1852,209 @@ var PageCache = class {
 		decorateMethodV2(this.prototype, "isLinked", [memoized]);
 	}
 	async load(request) {
+		this.request = request;
+		this.state = getRequestState(this.request);
+		let content;
+		try {
+			content = (await this.request).content;
+		} catch {
+			return null;
+		}
+		this.applyDocument(content);
+		return content;
+	}
+	/**
+	* Re-applies an already-loaded page from a newer request for the same page
+	* (a reload, or a route-driven navigation back to it). The newer document is
+	* authoritative: its links and page hints replace the ones recorded from
+	* the earlier load, and the collection total is updated from it. The page
+	* keeps its current request until the newer one resolves, so a page on
+	* screen does not flash a loading state; a rejected request leaves the
+	* page untouched.
+	*
+	* @internal
+	*/
+	async update(request) {
+		const state = getRequestState(request);
+		let content;
 		try {
-			this.request = request;
-			this.state = getRequestState(this.request);
-			const content = (await this.request).content;
-			const self = getHref(content?.links?.self);
-			const first = getHref(content?.links?.first);
-			const last = getHref(content?.links?.last);
-			const next = getHref(content?.links?.next);
-			const prev = getHref(content?.links?.prev);
+			content = (await request).content;
+		} catch {
+			return null;
+		}
+		this.request = request;
+		this.state = state;
+		this.applyDocument(content);
+		return content;
+	}
+	/**
+	* Records a loaded document's links and page number, and links this page
+	* into the shared page graph.
+	*
+	* The document is authoritative for what it states: a link it names
+	* explicitly (including an explicit `null`) overwrites whatever a neighbor
+	* or an earlier load of this page recorded, and a link it omits is kept.
+	* `next`/`prev` name the adjacent pages; `first`/`last` name the ends of
+	* the collection, beyond which nothing may remain linked.
+	*
+	* For a numbered collection the document must also agree with the page
+	* numbers: `next` is the page after this one, `prev` the page before, a
+	* page without `prev` is page 1, a page without `next` is the last page,
+	* `first` is page 1 and `last` is page `totalPages`. A document that
+	* contradicts this is a server (or collection-mixing) bug and is asserted
+	* in development, before anything is recorded from it. A cursor collection
+	* has no numbers, so there its links are the only authority.
+	*
+	* @internal
+	*/
+	applyDocument(content) {
+		const links = content?.links ?? {};
+		const self = getHref(content?.links?.self);
+		const first = getHref(content?.links?.first);
+		const last = getHref(content?.links?.last);
+		const next = getHref(content?.links?.next);
+		const prev = getHref(content?.links?.prev);
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error("Expected the page to have a self link");
+		})(self);
+		const { currentPage, totalPages } = this.manager.readPageHints(content);
+		const firstPage = first ? this.manager.getPageCache(first) : null;
+		const lastPage = last ? this.manager.getPageCache(last) : null;
+		const prevPage = prev ? this.manager.getPageCache(prev) : null;
+		const nextPage = next ? this.manager.getPageCache(next) : null;
+		if (this.manager.isNumbered) {
+			const ownNumber = (page) => page === this ? currentPage : page.pageNumber;
 			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
-				if (!test) throw new Error("Expected the page to have a self link");
-			})(self);
-			const pageNumber = this.getPageNumber(content);
-			if (pageNumber) this.pageNumber = pageNumber;
-			const firstPage = first ? this.manager.getPageCache(first) : null;
-			const lastPage = last ? this.manager.getPageCache(last) : null;
-			const prevPage = prev ? this.manager.getPageCache(prev) : null;
-			const nextPage = next ? this.manager.getPageCache(next) : null;
-			if (firstPage) {
-				this.firstLink = first;
-				firstPage.setPageNumber(1);
-				if (!firstPage.after) firstPage.updateLinkage({ after: this });
-			}
-			if (lastPage) {
-				this.lastLink = last;
-				lastPage.setPageNumber(this.manager.totalPages);
-				if (!lastPage.before) lastPage.updateLinkage({ before: this });
-			}
-			if (nextPage) {
-				this.nextLink = next;
-				nextPage.setPageNumber(this.pageNumber + 1);
-				nextPage.updateLinks({ prev: self });
-			}
-			if (prevPage) {
-				this.prevLink = prev;
-				prevPage.setPageNumber(this.pageNumber - 1);
-				prevPage.updateLinks({ next: self });
-			}
-			if (this.isLinked) {
-				if (prevPage) prevPage.updateLinkage({ after: this });
-				if (nextPage) nextPage.updateLinkage({ before: this });
-			} else if (prevPage?.isLinked) {
-				this.updateLinkage({ before: prevPage });
-				if (nextPage) nextPage.updateLinkage({ before: this });
-			} else if (nextPage?.isLinked) {
-				this.updateLinkage({ after: nextPage });
-				if (prevPage) prevPage.updateLinkage({ after: this });
-			} else if ((prevPage || nextPage) && (firstPage || lastPage)) this.lookupLinkage(firstPage, lastPage);
-			else if (prevPage || nextPage) this.updateLinkage({
-				before: prevPage,
-				after: nextPage
-			});
-			return content;
-		} catch {}
-		return null;
+				if (!test) throw new Error(`Page ${self} is page ${currentPage} but the collection has ${totalPages} pages: it lies beyond the collection total`);
+			})(!currentPage || !totalPages || currentPage <= totalPages);
+			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+				if (!test) throw new Error(`Page ${self} is page ${currentPage} and has no prev link but is not the first page`);
+			})(!("prev" in links && !prev && currentPage > 1));
+			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+				if (!test) throw new Error(`Page ${self} is page ${currentPage} of ${totalPages} and has no next link but is not the last page`);
+			})(!("next" in links && !next && currentPage > 0 && totalPages > 0 && currentPage < totalPages));
+			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+				if (!test) throw new Error(`Page ${self} is page ${currentPage} but its next link names page ${nextPage ? ownNumber(nextPage) : 0}, expected page ${currentPage + 1}`);
+			})(!nextPage || !currentPage || !ownNumber(nextPage) || ownNumber(nextPage) === currentPage + 1);
+			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+				if (!test) throw new Error(`Page ${self} is page ${currentPage} but its prev link names page ${prevPage ? ownNumber(prevPage) : 0}, expected page ${currentPage - 1}`);
+			})(!prevPage || !currentPage || !ownNumber(prevPage) || ownNumber(prevPage) === currentPage - 1);
+			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+				if (!test) throw new Error(`Page ${self} has a first link that names page ${firstPage ? ownNumber(firstPage) : 0}, expected page 1`);
+			})(!firstPage || !ownNumber(firstPage) || ownNumber(firstPage) === 1);
+			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+				if (!test) throw new Error(`Page ${self} has a last link that names page ${lastPage ? ownNumber(lastPage) : 0}, expected the last page ${totalPages}`);
+			})(!lastPage || !totalPages || !ownNumber(lastPage) || ownNumber(lastPage) === totalPages);
+			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+				if (!test) throw new Error(`Page ${self} has a first link to ${first} but that first page has a page linked before it`);
+			})(!firstPage?.before);
+		}
+		if (currentPage) this.pageNumber = currentPage;
+		this.manager.totalPages = totalPages;
+		const stated = {};
+		if ("first" in links) stated.first = first;
+		if ("last" in links) stated.last = last;
+		if ("next" in links) stated.next = next;
+		if ("prev" in links) stated.prev = prev;
+		this.updateLinks(stated);
+		if ("next" in links && !next) {
+			const after = this.after;
+			this.detachAfter();
+			if (after?.prevLink === self) after.updateLinks({ prev: null });
+		}
+		if ("prev" in links && !prev) {
+			const before = this.before;
+			this.detachBefore();
+			if (before?.nextLink === self) before.updateLinks({ next: null });
+		}
+		if (lastPage) {
+			lastPage.detachAfter();
+			lastPage.updateLinks({ next: null });
+		}
+		if (firstPage) {
+			firstPage.detachBefore();
+			firstPage.updateLinks({ prev: null });
+		}
+		if (firstPage) {
+			firstPage.setPageNumber(1);
+			if (firstPage !== this && !firstPage.after) this.linkFirst(firstPage);
+		}
+		if (lastPage) {
+			lastPage.setPageNumber(this.manager.totalPages);
+			if (lastPage !== this && !lastPage.before) this.linkLast(lastPage);
+		}
+		if (nextPage) {
+			nextPage.setPageNumber(this.pageNumber + 1);
+			nextPage.updateLinks({ prev: self });
+		}
+		if (prevPage) {
+			prevPage.setPageNumber(this.pageNumber - 1);
+			prevPage.updateLinks({ next: self });
+		}
+		if (nextPage && this.after && this.after !== nextPage && this.after.pageNumber <= nextPage.pageNumber) this.detachAfter();
+		if (prevPage && this.before && this.before !== prevPage && this.before.pageNumber >= prevPage.pageNumber) this.detachBefore();
+		if (this.isLinked) {
+			if (prevPage) prevPage.updateLinkage({ after: this });
+			if (nextPage) nextPage.updateLinkage({ before: this });
+		} else if (prevPage?.isLinked) {
+			this.updateLinkage({ before: prevPage });
+			if (nextPage) nextPage.updateLinkage({ before: this });
+		} else if (nextPage?.isLinked) {
+			this.updateLinkage({ after: nextPage });
+			if (prevPage) prevPage.updateLinkage({ after: this });
+		} else if ((prevPage || nextPage) && (firstPage || lastPage)) this.lookupLinkage(firstPage, lastPage);
+		else if (prevPage || nextPage) this.updateLinkage({
+			before: prevPage,
+			after: nextPage
+		});
+	}
+	/** @internal */
+	detachAfter() {
+		const after = this.after;
+		if (after) {
+			if (after.before === this) after.setBefore(null);
+			this.setAfter(null);
+		}
 	}
 	/** @internal */
+	detachBefore() {
+		const before = this.before;
+		if (before) {
+			if (before.after === this) before.setAfter(null);
+			this.setBefore(null);
+		}
+	}
+	/**
+	* Links an unlinked `first` page before the earliest page reachable
+	* backwards from this one that must follow it.
+	*
+	* @internal
+	*/
+	linkFirst(firstPage) {
+		let head = this;
+		while (head.before && head.before !== firstPage && (!head.before.pageNumber || head.before.pageNumber > firstPage.pageNumber)) head = head.before;
+		firstPage.updateLinkage({ after: head });
+	}
+	/**
+	* Links an unlinked `last` page after the furthest page reachable forwards
+	* from this one that must precede it.
+	*
+	* @internal
+	*/
+	linkLast(lastPage) {
+		let tail = this;
+		while (tail.after && tail.after !== lastPage && (!tail.after.pageNumber || !lastPage.pageNumber || tail.after.pageNumber < lastPage.pageNumber)) tail = tail.after;
+		lastPage.updateLinkage({ before: tail });
+	}
+	/**
+	* Places this page between `before` and `after` in the graph (a missing side
+	* is taken from the given side's current neighbor, so a single side splices
+	* this page in). Pointers this page or the displaced neighbors held to their
+	* old positions are cleared first, so a page moved within the graph never
+	* leaves a dangling link behind that could close a cycle.
+	*
+	* @internal
+	*/
 	updateLinkage({ before, after }) {
 		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
 			if (!test) throw new Error("Expected at least one of before or after page states to link to this page");
@@ -1856,10 +2062,16 @@ var PageCache = class {
 		const leftSide = before ?? after?.before;
 		const rightSide = after ?? before?.after;
 		if (leftSide && leftSide !== this) {
+			if (this.before !== leftSide) this.detachBefore();
+			const displaced = leftSide.after;
+			if (displaced && displaced !== this && displaced !== rightSide && displaced.before === leftSide) displaced.setBefore(null);
 			leftSide.setAfter(this);
 			this.setBefore(leftSide);
 		}
 		if (rightSide && rightSide !== this) {
+			if (this.after !== rightSide) this.detachAfter();
+			const displaced = rightSide.before;
+			if (displaced && displaced !== this && displaced !== leftSide && displaced.after === rightSide) displaced.setAfter(null);
 			rightSide.setBefore(this);
 			this.setAfter(rightSide);
 		}
@@ -1899,16 +2111,18 @@ var PageCache = class {
 		})(page !== this);
 		this.after = page;
 	}
-	/** @internal */
-	getPageNumber(document) {
-		return this.manager.readPageHints(document).currentPage;
-	}
-	/** @internal */
-	updateLinks = ({ prev, next, first, last }) => {
-		if (prev) this.prevLink = prev;
-		if (next) this.nextLink = next;
-		if (first) this.firstLink = first;
-		if (last) this.lastLink = last;
+	/**
+	* Records the given links. Only the keys present are applied, so a caller
+	* states exactly what it knows: an explicit `null` clears a link, an
+	* omitted key leaves the recorded link alone.
+	*
+	* @internal
+	*/
+	updateLinks = (links) => {
+		if ("prev" in links) this.prevLink = links.prev ?? null;
+		if ("next" in links) this.nextLink = links.next ?? null;
+		if ("first" in links) this.firstLink = links.first ?? null;
+		if ("last" in links) this.lastLink = links.last ?? null;
 	};
 	/** @internal */
 	setPageNumber = (pageNumber) => {
@@ -1934,6 +2148,8 @@ const PaginationCacheMap = /* @__PURE__ */ new Map();
 * collection must provide the same function reference — define it once at module
 * scope and import it everywhere.
 *
+* @summary Experimental: a function you pass to `<Paginate />` that reads `currentPage` and `totalPages` from a
+* loaded document when they are not in the default `meta` locations.
 * @since 5.9.0
 * @public
 */
@@ -1942,6 +2158,8 @@ const PaginationCacheMap = /* @__PURE__ */ new Map();
 * document `meta`, matching the behavior used before `pageHints` was configurable.
 * Used whenever the consumer does not provide a `pageHints` function.
 *
+* @summary Experimental: the fallback page-hints function, reading `meta.page` or `meta.currentPage` and
+* `meta.totalPages` from a document, with `0` meaning unknown.
 * @since 5.9.0
 * @public
 */
@@ -1961,6 +2179,8 @@ const defaultPageHints = (document) => {
 * interact with — the cache itself is plumbing shared between the pagination
 * classes.
 *
+* @summary Experimental: the shared, app-wide store of loaded pages, page order, and `totalPages` for one paginated
+* collection, keyed by its `first` or `self` link.
 * @since 5.9.0
 * @public
 * @hideconstructor
@@ -2055,17 +2275,28 @@ var PaginationCache = class {
 		}
 		return page;
 	}
-	/** @internal */
-	loadPage(url, request) {
+	/**
+	* Loads the page at `url` with `request` when it is not loaded (or its load
+	* failed), or re-applies `request`'s document when it is a newer request
+	* for an already-loaded page (a reload, or navigating back to it: the newer
+	* document is authoritative for the page's links and the collection total,
+	* which may have changed since the first load).
+	*
+	* Resolves to the page once that has settled. A rejected request settles
+	* too — it is surfaced through the page's state, not thrown. The promise
+	* rejects only when the document contradicts the collection (see
+	* {@link PageCache.applyDocument}), so the caller that triggered the load
+	* is the one that hears about it.
+	*
+	* @internal
+	*/
+	async loadPage(url, request) {
 		const page = this.getPageCache(url);
 		if ((!page.isLoaded || page.isError) && request) {
-			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
-				if (!test) throw new Error("Expected a request to a load a page");
-			})(request);
-			page.load(request).then((document) => {
-				this.updateFirstPage(page);
-				if (document) this.totalPages = this.getTotalPages(document);
-			});
+			await page.load(request);
+			this.updateFirstPage(page);
+		} else if (request && page.isSuccess && request !== page.request) {
+			if (await page.update(request)) this.updateFirstPage(page);
 		}
 		return page;
 	}
@@ -2075,10 +2306,6 @@ var PaginationCache = class {
 		while (maybeFirstPage.before) maybeFirstPage = maybeFirstPage.before;
 		if (!this.firstPage || this.firstPage.pageNumber > maybeFirstPage.pageNumber) this.firstPage = maybeFirstPage;
 	}
-	/** @internal */
-	getTotalPages(document) {
-		return this.readPageHints(document).totalPages;
-	}
 	/**
 	* Every page known to the shared graph, in order — loaded pages and pages
 	* known only from links — across all components sharing the collection.
@@ -2094,14 +2321,13 @@ var PaginationCache = class {
 	* ```
 	*/
 	get pages() {
-		const self = this;
-		return { *[Symbol.iterator]() {
-			let page = self.firstPage;
-			while (page) {
-				yield page;
-				page = page.after;
-			}
-		} };
+		const pages = [];
+		let page = this.firstPage;
+		while (page) {
+			pages.push(page);
+			page = page.after;
+		}
+		return pages;
 	}
 	/**
 	* The items of every loaded page in the shared graph, flattened into one
@@ -2115,10 +2341,9 @@ var PaginationCache = class {
 		decorateMethodV2(this.prototype, "pages", [memoized]);
 	}
 	get data() {
-		const self = this;
-		return { *[Symbol.iterator]() {
-			for (const page of self.pages) if (page.data) yield* page.data;
-		} };
+		const items = [];
+		for (const page of this.pages) if (page.data) items.push(...page.data);
+		return items;
 	}
 	static {
 		decorateMethodV2(this.prototype, "data", [memoized]);
@@ -2129,6 +2354,8 @@ var PaginationCache = class {
 * `first` or `self` link). Returns the same instance for the same key for the
 * lifetime of the module.
 *
+* @summary Experimental: returns the shared pagination cache for a collection's `first` or `self` link, creating it
+* on first use.
 * @since 5.9.0
 * @public
 */
@@ -2145,6 +2372,7 @@ function getPaginationCache(key) {
 * Primarily intended for test isolation, since the cache is keyed by url and
 * otherwise persists for the lifetime of the module.
 *
+* @summary Experimental: discards every shared pagination cache, mainly so tests start from a clean state.
 * @since 5.9.0
 * @public
 */
@@ -2161,25 +2389,40 @@ function clearPaginationCache() {
 *
 * - `'paged'` — single-page view, see {@link PagedPaginationState}.
 * - `'infinite'` — accumulated view, see {@link InfinitePaginationState}.
+*
+* @summary Experimental: the `@mode` value of `<Paginate />`, either `'paged'` for a single-page view or
+* `'infinite'` for an accumulated view, which selects the yielded pagination API.
 */
 /**
 * The part of a {@link PaginationState} available to both navigation surfaces.
+*
+* @summary Experimental: the pagination state members available in both paged and infinite mode, namely
+* `totalPages` and `adoptPage`.
 */
 /**
 * The paged (single-page view) surface of a {@link PaginationState}: render
 * {@link PaginationState.activePageRequest | activePageRequest}, navigate with
 * {@link PaginationState.loadPage | loadPage}. This is what the `<Paginate />`
 * component yields in `'paged'` mode (the default).
+*
+* @summary Experimental: the pagination state `<Paginate />` yields in paged mode, exposing the active page, its
+* request, and `loadPage` for navigating to a page by URL.
 */
 /**
 * The infinite (accumulated view) surface of a {@link PaginationState}: render
 * {@link PaginationState.data | data}, grow it with
 * {@link PaginationState.loadNext | loadNext}/{@link PaginationState.loadPrev | loadPrev}.
 * This is what the `<Paginate />` component yields in `'infinite'` mode.
+*
+* @summary Experimental: the pagination state `<Paginate />` yields in infinite mode, exposing the accumulated
+* items and pages plus `loadNext` and `loadPrev` to extend them.
 */
 /**
 * Resolves a {@link PaginateMode} to the surface it exposes, so a component
 * generic over the mode can yield only that surface.
+*
+* @summary Experimental: resolves a pagination mode to its state type, the infinite-mode state for `'infinite'`
+* and the paged-mode state otherwise.
 */
 /**
 * The per-component, local pagination state. It houses the state that is unique
@@ -2203,6 +2446,8 @@ function clearPaginationCache() {
 * Instances are created via {@link getPaginationState} (or by the `<Paginate />`
 * component on your behalf), never constructed directly.
 *
+* @summary Experimental: one component's pagination state over a shared collection, tracking the active page and
+* the loaded run and providing paged and infinite navigation.
 * @since 5.9.0
 * @public
 * @hideconstructor
@@ -2233,10 +2478,23 @@ var PaginationState = class {
 	* them backward/forward. Both seed to {@link initialPage}; a purely paged
 	* consumer never extends them, so they stay put and are effectively unused.
 	*
+	* Only ever written through {@link extendRun} and {@link restartRun}, which
+	* keep {@link runMembers} in step.
+	*
 	* @internal
 	*/
 	/** @internal */
 	/**
+	* Every page this component has loaded into its run — what the frontier
+	* spanned each time it moved. Bounds the walk in {@link pages}: the shared
+	* graph may relink a page in the run to one that another component sharing
+	* the collection loaded, and that page is not part of this run until it is
+	* loaded through here. Untracked bookkeeping — it only changes together with
+	* the frontier signals, which carry the notification.
+	*
+	* @internal
+	*/
+	/**
 	* The request of the latest {@link adoptPage} call — only that call may
 	* commit. Later calls (or a {@link loadPage} navigation) claim the slot,
 	* superseding in-flight adoptions so the newest navigation always wins.
@@ -2249,6 +2507,7 @@ var PaginationState = class {
 		this.request = request;
 		this.pageHints = pageHints;
 		this._adoptTarget = null;
+		this.runMembers = /* @__PURE__ */ new Set();
 		this.setup();
 	}
 	/**
@@ -2297,21 +2556,44 @@ var PaginationState = class {
 	* same collection to different extents each see only what they have scrolled
 	* through. For every page known to the whole collection, see
 	* {@link PaginationCache.pages}.
+	*
+	* The run is walked through the shared graph, so it ends early when a page
+	* that was in it no longer follows the page before it — a reload that showed
+	* the collection now ends sooner, or that its next cursor moved. It also ends
+	* before a page this component never loaded: a reload may relink a page in
+	* the run to one another component sharing the collection scrolled to, and
+	* that page joins this run only through {@link loadNext}.
 	*/
 	static {
 		decorateMethodV2(this.prototype, "totalPages", [memoized]);
 	}
 	get pages() {
-		const self = this;
-		return { *[Symbol.iterator]() {
-			const end = self.frontierEnd;
-			let page = self.frontierStart;
-			while (page) {
-				yield page;
-				if (page === end) break;
-				page = page.after;
-			}
-		} };
+		const pages = [];
+		const end = this.frontierEnd;
+		let page = this.frontierStart;
+		while (page) {
+			pages.push(page);
+			if (page === end) break;
+			const next = page.after;
+			if (!next?.isSuccess || !this.runMembers.has(next)) break;
+			page = next;
+		}
+		return pages;
+	}
+	/**
+	* The last page of the run {@link pages} walks — the forward frontier, or
+	* the page before the first one that no longer follows in the graph or that
+	* this component never loaded.
+	*
+	* @internal
+	*/
+	static {
+		decorateMethodV2(this.prototype, "pages", [memoized]);
+	}
+	get runEnd() {
+		let end = null;
+		for (const page of this.pages) end = page;
+		return end;
 	}
 	/**
 	* The accumulated items across the loaded run, from the backward frontier to
@@ -2336,13 +2618,12 @@ var PaginationState = class {
 	* ```
 	*/
 	static {
-		decorateMethodV2(this.prototype, "pages", [memoized]);
+		decorateMethodV2(this.prototype, "runEnd", [memoized]);
 	}
 	get data() {
-		const self = this;
-		return { *[Symbol.iterator]() {
-			for (const page of self.pages) if (page.data) yield* page.data;
-		} };
+		const items = [];
+		for (const page of this.pages) if (page.data) items.push(...page.data);
+		return items;
 	}
 	/**
 	* Whether a page exists after the forward frontier — i.e. there is more to load
@@ -2358,7 +2639,7 @@ var PaginationState = class {
 		decorateMethodV2(this.prototype, "data", [memoized]);
 	}
 	get hasNext() {
-		return Boolean(this.frontierEnd?.nextLink);
+		return Boolean(this.runEnd?.nextLink);
 	}
 	/**
 	* Whether a page exists before the backward frontier.
@@ -2373,7 +2654,10 @@ var PaginationState = class {
 	* The request for the page just after the forward frontier, for the infinite
 	* surface. `null` until {@link loadNext} fires it (so a `<Request>` wrapping it
 	* renders its idle block), the in-flight `Future` while that page loads, then
-	* `null` again once the frontier advances onto it. Also `null` at end-of-list.
+	* `null` again once the frontier advances onto it. Also `null` at end-of-list,
+	* and while the page sits loaded in the shared cache (another component
+	* scrolled to it) but outside this run — {@link loadNext} then joins it
+	* without a request of its own.
 	*
 	* ```gts
 	* {{#if pages.hasNext}}
@@ -2388,9 +2672,9 @@ var PaginationState = class {
 		decorateMethodV2(this.prototype, "hasPrevious", [memoized]);
 	}
 	get nextRequest() {
-		const url = this.frontierEnd?.nextLink;
+		const url = this.runEnd?.nextLink;
 		if (!url) return null;
-		return this.paginationCache?.getPageCache(url).request ?? null;
+		return this.pendingRequest(url);
 	}
 	/**
 	* The request for the page just before the backward frontier. Mirror of
@@ -2402,12 +2686,24 @@ var PaginationState = class {
 	get previousRequest() {
 		const url = this.frontierStart?.prevLink;
 		if (!url) return null;
-		return this.paginationCache?.getPageCache(url).request ?? null;
+		return this.pendingRequest(url);
 	}
-	/** @internal */
+	/**
+	* The request of the page at `url` unless it already succeeded, in which
+	* case there is nothing pending: the page either sits in this run, or joins
+	* it on the next {@link loadNext}/{@link loadPrev} without a new request.
+	*
+	* @internal
+	*/
 	static {
 		decorateMethodV2(this.prototype, "previousRequest", [memoized]);
 	}
+	pendingRequest(url) {
+		const page = this.paginationCache?.getPageCache(url);
+		if (!page || page.isSuccess) return null;
+		return page.request ?? null;
+	}
+	/** @internal */
 	async setup() {
 		let document;
 		try {
@@ -2424,9 +2720,31 @@ var PaginationState = class {
 		const cache = getPaginationCache(firstLink ?? selfLink ?? "");
 		cache.installPageHints(this.pageHints);
 		this.paginationCache = cache;
-		cache.totalPages = cache.getTotalPages(content);
-		this.activePage = this.initialPage = cache.loadPage(selfLink, this.request);
-		this.frontierStart = this.frontierEnd = this.initialPage;
+		const page = cache.getPageCache(selfLink);
+		this.activePage = this.initialPage = page;
+		this.restartRun(page);
+		await cache.loadPage(selfLink, this.request);
+	}
+	/**
+	* Moves the frontier onto a page adjacent to the run, recording it as a
+	* member.
+	*
+	* @internal
+	*/
+	extendRun(dir, page) {
+		this.runMembers.add(page);
+		if (dir === "next") this.frontierEnd = page;
+		else this.frontierStart = page;
+	}
+	/**
+	* Restarts the run at a single page, forgetting every earlier member.
+	*
+	* @internal
+	*/
+	restartRun(page) {
+		this.runMembers.clear();
+		this.runMembers.add(page);
+		this.frontierStart = this.frontierEnd = page;
 	}
 	/**
 	* Commits a resolved, membership-proven page into this state, making it the
@@ -2443,9 +2761,9 @@ var PaginationState = class {
 	_activate(page, url) {
 		this.activePage = page;
 		for (const existing of this.pages) if (existing === page) return;
-		if (this.frontierEnd?.nextLink === url) this.frontierEnd = page;
-		else if (this.frontierStart?.prevLink === url) this.frontierStart = page;
-		else this.frontierStart = this.frontierEnd = page;
+		if (this.runEnd?.nextLink === url) this.extendRun("next", page);
+		else if (this.frontierStart?.prevLink === url) this.extendRun("prev", page);
+		else this.restartRun(page);
 	}
 	/**
 	* Adopts an externally-issued request into this pagination, making its page
@@ -2476,6 +2794,10 @@ var PaginationState = class {
 	* - this state has not finished setting up its own collection yet
 	* - the call was superseded by a newer navigation
 	*
+	* In development, a document that contradicts the collection's page
+	* numbers (a `next` that skips a page, a `first` that is not page 1, ...)
+	* rejects instead of resolving: the graph is not updated from it.
+	*
 	* ```ts
 	* const pages = getPaginationState(initialRequest);
 	* // later, e.g. in a route model hook reacting to a ?page= param:
@@ -2505,12 +2827,7 @@ var PaginationState = class {
 			if (!test) throw new Error("Expected the adopted document to have a self link");
 		})(selfLink);
 		if (!selfLink || (firstLink ?? selfLink) !== cache.key) return null;
-		const page = cache.loadPage(selfLink, request);
-		try {
-			await page.request;
-		} catch {
-			return null;
-		}
+		const page = await cache.loadPage(selfLink, request);
 		if (this._adoptTarget !== request) return null;
 		this._activate(page, selfLink);
 		return page.value;
@@ -2557,7 +2874,7 @@ var PaginationState = class {
 		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
 			if (!test) throw new Error("Expected the pagination cache to be set up before loading a page");
 		})(cache);
-		const frontier = dir === "next" ? this.frontierEnd : this.frontierStart;
+		const frontier = dir === "next" ? this.runEnd : this.frontierStart;
 		const url = dir === "next" ? frontier?.nextLink : frontier?.prevLink;
 		if (!url) return null;
 		const page = cache.getPageCache(url);
@@ -2570,15 +2887,12 @@ var PaginationState = class {
 				method: "GET",
 				url
 			});
-			cache.loadPage(url, request);
-		}
-		try {
+			await cache.loadPage(url, request);
+		} else try {
 			await page.request;
-		} catch {
-			return null;
-		}
-		if (dir === "next") this.frontierEnd = page;
-		else this.frontierStart = page;
+		} catch {}
+		if (!page.isSuccess) return null;
+		this.extendRun(dir, page);
 		return page.value;
 	};
 	/**
@@ -2597,7 +2911,9 @@ var PaginationState = class {
 	* On failure the page stays active and {@link activePageRequest} resolves to
 	* it, so a wrapping `<Request>` renders its error block. Calling again (for
 	* example clicking the page's link a second time) retries: the failed page
-	* is re-requested with a forced reload.
+	* is re-requested with a forced reload. In development, a document that
+	* contradicts the collection's page numbers rejects instead (see
+	* {@link adoptPage}).
 	*
 	* ```gts
 	* <EachLink @pages={{pages}}>
@@ -2624,12 +2940,8 @@ var PaginationState = class {
 				method: "GET",
 				url
 			});
-			cache.loadPage(url, request);
-			try {
-				await page.request;
-			} catch {
-				return null;
-			}
+			await cache.loadPage(url, request);
+			if (!page.isSuccess) return null;
 		}
 		return page.value;
 	};
@@ -2656,6 +2968,8 @@ const PaginationStateCache = /* @__PURE__ */ new WeakMap();
 * await pages.loadNext();
 * ```
 *
+* @summary Experimental: returns the pagination state for a request, creating it on first call and returning the
+* same instance for the same request thereafter.
 * @since 5.9.0
 * @public
 */
@@ -2689,6 +3003,8 @@ const PaginationLinksCache = /* @__PURE__ */ new WeakMap();
 * </EachLink>
 * ```
 *
+* @summary Experimental: a numbered page link with its page number, whether it is current, its distance from the
+* active page, and `setActive` to load and show that page.
 * @since 5.9.0
 * @public
 * @hideconstructor
@@ -2738,6 +3054,8 @@ var RealPaginationLink = class {
 * </EachLink>
 * ```
 *
+* @summary Experimental: a non-navigable gap marker in numbered pagination links, standing in for a range of
+* not-yet-loaded pages, usually shown as an ellipsis.
 * @since 5.9.0
 * @public
 * @hideconstructor
@@ -2790,6 +3108,8 @@ var PlaceholderPaginationLink = class {
 * </EachLink>
 * ```
 *
+* @summary Experimental: a `first`, `prev`, `next`, or `last` link relative to the active page, with `setActive`
+* to load it, and the only kind of link cursor-based pagination has.
 * @since 5.9.0
 * @public
 * @hideconstructor
@@ -2841,6 +3161,9 @@ var RelationalPaginationLink = class {
 *   }
 * }
 * ```
+*
+* @summary Experimental: an entry in the numbered pagination links list, either a navigable numbered link or a
+* placeholder for a gap, told apart by `isReal`.
 */
 /**
 * The reactive set of navigation links derived from a {@link PaginationState}.
@@ -2870,6 +3193,8 @@ var RelationalPaginationLink = class {
 * - {@link PlaceholderPaginationLink}
 * - {@link RelationalPaginationLink}
 *
+* @summary Experimental: the reactive navigation links for a pagination state, with numbered links and gap
+* placeholders plus `first`, `prev`, `next`, and `last` links for the active page.
 * @since 5.9.0
 * @public
 * @hideconstructor
@@ -2981,6 +3306,8 @@ var PaginationLinks = class {
 * }
 * ```
 *
+* @summary Experimental: returns the navigation links for a paged pagination state, creating them on first call and
+* returning the same instance for the same state.
 * @since 5.9.0
 * @public
 */
@@ -2998,29 +3325,46 @@ function getPaginationLinks(state) {
 /**
 * The content features available in both pagination modes: the state and
 * controls of the initial request.
+*
+* @summary Experimental: the request status flags and controls, like `isRefreshing`, `refresh`, and `reload`,
+* that `<Paginate />` yields to its content block in both modes.
 */
 /**
 * The content features yielded in `'paged'` mode: navigation happens by
 * loading a specific page.
+*
+* @summary Experimental: the request controls `<Paginate />` yields to its content block in paged mode, adding
+* `loadPage` to navigate to a page by URL.
 */
 /**
 * The content features yielded in `'infinite'` mode: navigation happens by
 * extending the loaded run at either end.
+*
+* @summary Experimental: the request controls `<Paginate />` yields to its content block in infinite mode, adding
+* `loadNext` and `loadPrev` to extend the loaded pages.
 */
 /**
 * The full set of content features a {@link PaginationSubscription} builds —
 * both modes' surfaces. The `<Paginate />` component narrows this to one mode
 * via {@link PaginationContentFeaturesFor} before yielding.
+*
+* @summary Experimental: the combined paged and infinite content features a pagination subscription builds, before
+* `<Paginate />` narrows them to one mode.
 */
 /**
 * Resolves a {@link PaginateMode} to the content features it exposes. Mirror of
 * {@link PaginationStateFor}.
+*
+* @summary Experimental: resolves a pagination mode to the content features `<Paginate />` yields, the infinite
+* set for `'infinite'` and the paged set otherwise.
 */
 /**
 * Lifecycle glue for the `<Paginate />` component. Owns the initial
 * {@link RequestSubscription} (loading/error state, autorefresh, disposal) and
 * the per-component {@link PaginationState} that it hands to the component.
 *
+* @summary Experimental: the lifecycle core of `<Paginate />`, owning the initial request subscription and the
+* component's pagination state.
 * @since 5.9.0
 * @public
 * @hideconstructor
@@ -3282,6 +3626,8 @@ defineSignal(PaginationSubscription.prototype, "_navRequest", null);
 * subscription[DISPOSE](); // tear down when the owning component unmounts
 * ```
 *
+* @summary Experimental: creates the subscription that manages a `<Paginate />` component's initial request
+* lifecycle and pagination state, for managing that lifecycle yourself.
 * @since 5.9.0
 * @public
 */
@@ -3313,6 +3659,8 @@ function _DISPOSE$1() {
 * `<Paginate />` component, so they stay in sync as pages load and the active
 * page changes.
 *
+* @summary Experimental: the framework-agnostic lifecycle core of a pagination links component such as
+* `<EachLink />`, exposing the navigation links for a paged pagination state.
 * @since 5.9.0
 * @public
 * @hideconstructor
@@ -3354,6 +3702,8 @@ var PaginationLinksSubscription = class {
 * subscription[DISPOSE](); // tear down when the owning component unmounts
 * ```
 *
+* @summary Experimental: creates the subscription a pagination links component such as `<EachLink />` uses to
+* derive navigation links from a paged pagination state.
 * @since 5.9.0
 * @public
 */
@@ -3375,18 +3725,24 @@ const PromiseCache = /* @__PURE__ */ new WeakMap();
 * The state of a promise in the "pending"
 * state. This is the default initial state.
 *
+* @summary The `getPromiseState` state for a promise that has not yet settled, with `isPending` true and
+* no value or reason.
 */
 /**
 * The state of a promise in the "fulfilled" state.
 * This is the state of a promise that has resolved
 * successfully.
 *
+* @summary The `getPromiseState` state for a promise that resolved, with `isSuccess` true and the
+* resolved `value`.
 */
 /**
 * The state of a promise in the "rejected" state.
 * This is the state of a promise that has rejected
 * with an error.
 *
+* @summary The `getPromiseState` state for a promise that rejected, with `isError` true and the
+* rejection `reason`.
 */
 /**
 * The state of a promise. This is the type that is returned
@@ -3397,6 +3753,8 @@ const PromiseCache = /* @__PURE__ */ new WeakMap();
 * - {@link ResolvedPromise}
 * - {@link RejectedPromise}
 *
+* @summary The reactive pending, fulfilled, or rejected state of a promise, as returned by
+* `getPromiseState`.
 */
 const PromiseStateProto = {};
 defineSignal(PromiseStateProto, "reason", null);
@@ -3462,6 +3820,9 @@ function getPromise(promise) {
 /**
 * Returns a reactive state-machine for the provided promise or awaitable.
 *
+* The [Async as Reactive State](/guides/the-manual/reactivity/derivation) guide shows
+* how to use it in place of tracked loading and error state.
+*
 * Repeat calls to `getPromiseState` with the same promise will return the same state object
 * making is safe and easy to use in templates and JavaScript code to produce reactive
 * behaviors around promises.
@@ -3511,6 +3872,9 @@ function getPromise(promise) {
 * If looking to use in a template, consider also the `<Await />` component.
 *
 * See also {@link PromiseState}
+*
+* @summary Returns a cached, reactive state object tracking whether a promise is pending, fulfilled, or
+* rejected, for use in JS or templates.
 */
 function getPromiseState(promise) {
 	macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
@@ -3527,4 +3891,4 @@ function getPromiseState(promise) {
 
 //#endregion
 export { ARRAY_SIGNAL as A, createInternalMemo as C, notifyInternalSignal as D, makeInitializer as E, setupSignals as M, waitFor as N, peekInternalSignal as O, willSyncFlushWatchers as P, consumeInternalSignal as S, getOrCreateInternalSignal as T, entangleSignal as _, getPaginationState as a, signal as b, getPaginationCache as c, getRequestState as d, createSignalDescriptor as f, entangleInitiallyStaleSignal as g, defineSignal as h, getPaginationLinks as i, OBJECT_SIGNAL as j, withSignalStore as k, DISPOSE as l, defineNonEnumerableSignal as m, createPaginationLinksSubscription as n, clearPaginationCache as o, defineGate as p, createPaginationSubscription as r, defaultPageHints as s, getPromiseState as t, createRequestSubscription as u, gate as v, createInternalSignal as w, Signals as x, memoized as y };
-//# sourceMappingURL=-private-CjK1Dmuh.js.map
+//# sourceMappingURL=-private-BpyvBYFj.js.map