@bubo-squared/gyroview 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 What changed for a page using the package, newest first. Until 1.0, a minor version may change
 the API.
 
+## 0.3.0 (2026-09-30)
+
+What a page may notice:
+
+- A recording named by URL is downloaded in file order as it plays, the picture and the sound
+  from the same bytes, each fetched about once (ADR 0029). Over a simulated link a little
+  slower than an X5 recording at its highest setting (200 Mbit/s against 210), it starts in
+  half the time, fetches under half the bytes, and after a seek shows the target in half the
+  time, asking for nothing of the old position.
+
+  | State                  | What it downloads                                                     |
+  | ---------------------- | --------------------------------------------------------------------- |
+  | Loaded, never played   | What opening and the first frame need; with `preload="none"` no frame |
+  | Playing                | Up to 10 s or 128 MiB ahead, whichever is less, topped up as it plays |
+  | Paused after playing   | On up to that budget, then nothing                                    |
+  | A seek                 | The old position's requests end at once; the target first             |
+  | Starved by the network | Waits until the next 4 s are downloaded, then plays on                |
+
+- A range that breaks off or brings nothing for 10 s is asked for again from its next byte.
+
+New:
+
+- The `source-changed` error: the recording at the URL was replaced while it played, as its
+  `ETag` tells, or else its `Last-Modified` and size. Exposing `ETag` across origins is
+  optional, and now named in the CORS advice.
+
 ## 0.2.0 (2026-09-29)
 
 What a page may notice:

package/README.md

@@ -42,10 +42,10 @@ A page without a bundler loads the standalone file, which has Three.js and media
 ```html
 <script
   type="module"
-  src="https://cdn.jsdelivr.net/npm/@bubo-squared/gyroview@0.2/dist/standalone.js"
+  src="https://cdn.jsdelivr.net/npm/@bubo-squared/gyroview@0.3/dist/standalone.js"
 ></script>
 <script type="module">
-  import { inspectRecording } from 'https://cdn.jsdelivr.net/npm/@bubo-squared/gyroview@0.2/dist/standalone.js';
+  import { inspectRecording } from 'https://cdn.jsdelivr.net/npm/@bubo-squared/gyroview@0.3/dist/standalone.js';
 </script>
 ```
 
@@ -116,8 +116,19 @@ player.lookAt(90, 0);
 
 The canvas keeps no picture once the browser has shown it: a snapshot (`drawImage`, `toBlob`)
 is taken in a `frame` listener, which runs right after each picture is drawn. There are no
-buffered ranges to show, since the player reads the recording as it plays, and no playback
-rates other than 1.
+buffered ranges to show yet, and no playback rates other than 1.
+
+## How a recording is downloaded
+
+A recording named by URL is read in byte ranges, in file order, as it plays: the lenses and
+the sound come from the same bytes, each fetched about once. Until the first play the player
+reads only what opening it and showing the first frame need (no frame with `preload="none"`).
+Playing, it keeps up to 10 s or 128 MiB ahead, whichever is less, shared by the two files of a
+split recording; paused, it reads on to that budget and stops. A seek ends the old position's
+requests at once. When the network falls behind the recording, playback waits until the next
+4 s are downloaded, and plays on in stretches rather than a frame at a time. A range that
+breaks off or stalls for 10 s is asked for again from its next byte, and a recording replaced at
+its URL while it plays fails with `source-changed`.
 
 `@bubo-squared/gyroview` also exports `GyroViewError`, the list of its codes
 (`GYRO_VIEW_ERROR_CODES`, with `isGyroViewErrorCode` to check a string against it), and the
@@ -185,7 +196,7 @@ loads a recording only for the player in view, removing `src` from the others.
   Access-Control-Allow-Origin: https://your-site.example
   Access-Control-Allow-Methods: GET, HEAD
   Access-Control-Allow-Headers: Range
-  Access-Control-Expose-Headers: Content-Range, Content-Length, Accept-Ranges
+  Access-Control-Expose-Headers: Content-Range, Content-Length, Accept-Ranges, ETag
   ```
 
   Recordings kept behind the visitor's cookies take `crossorigin="use-credentials"` on the

package/dist/index.d.ts

@@ -284,6 +284,7 @@ export declare const GYRO_VIEW_ERROR_CODES: readonly [
 	"playback-blocked",
 	"range-unsupported",
 	"render-unavailable",
+	"source-changed",
 	"source-truncated",
 	"source-unreadable",
 	"unsupported-calibration",

package/dist/packages/adapters/fetch/src/HttpByteStream.js

@@ -0,0 +1,174 @@
+import { GyroViewError, isAbortError } from "../../../core/src/shared/errors/GyroViewError.js";
+import { ByteRange } from "../../../core/src/shared/binary/ByteRange.js";
+import { Ending, ITERATION_END } from "../../../core/src/shared/async/iteration.js";
+import "../../../core/src/index.js";
+import { contentRangeOf } from "./contentRange.js";
+import { passing } from "./passingFailures.js";
+import { brokenOff, truncated } from "./rangeFailures.js";
+//#region ../../packages/adapters/fetch/src/HttpByteStream.ts
+/**
+* Long enough for a slow mobile network to deliver its next packet, short enough that playback
+* waiting on a dead connection recovers well before the viewer gives up.
+*/
+var DEFAULT_STALL_TIMEOUT_MS = 1e4;
+/**
+* ByteStream over HTTP: a range is one request, its body handed on a chunk at a time as it
+* comes, and given up by aborting the request. A body that breaks off or stalls is asked for
+* again from its next byte, as the resource's retry rules allow.
+*/
+var HttpByteStream = class {
+	resource;
+	stallTimeoutMs;
+	constructor(resource, options = {}) {
+		this.resource = resource;
+		this.stallTimeoutMs = options.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+	}
+	stream(range) {
+		return { [Symbol.asyncIterator]: () => new RangeReading({
+			resource: this.resource,
+			range,
+			stallTimeoutMs: this.stallTimeoutMs
+		}) };
+	}
+};
+/**
+* One range's requests and bodies. The answer must be the bytes asked for, every one and no
+* more; returning the iteration aborts the request at once, a chunk still awaited coming as the
+* end.
+*/
+var RangeReading = class {
+	parts;
+	attempt;
+	received = 0;
+	ending = new Ending();
+	constructor(parts) {
+		this.parts = parts;
+	}
+	async next() {
+		try {
+			const chunk = await this.parts.resource.askingAgain(() => this.readChunk());
+			if (chunk) return {
+				done: false,
+				value: chunk
+			};
+		} catch (error) {
+			if (!this.ending.hasEnded()) {
+				this.end();
+				throw error;
+			}
+		}
+		this.end();
+		return ITERATION_END;
+	}
+	return() {
+		this.end();
+		return Promise.resolve(ITERATION_END);
+	}
+	/**
+	* The next chunk; none at the range's end. An attempt that fails is dropped, so the next
+	* asks anew for the rest of the range.
+	*/
+	async readChunk() {
+		const { resource, range } = this.parts;
+		await resource.ensureFits(range);
+		if (this.ending.hasEnded() || range.length === 0) return void 0;
+		this.attempt ??= this.attemptAtTheRest();
+		const { attempt } = this;
+		try {
+			const read = await this.withinStallTimeout(this.readFrom(attempt));
+			return this.taken(read);
+		} catch (error) {
+			this.drop(attempt);
+			throw error;
+		}
+	}
+	attemptAtTheRest() {
+		const { range } = this.parts;
+		const rest = ByteRange.of(range.offset + this.received, range.length - this.received);
+		const request = new AbortController();
+		return {
+			request,
+			body: this.bodyOf(rest, request.signal)
+		};
+	}
+	async bodyOf(rest, signal) {
+		const response = await this.parts.resource.rangeAnswer(rest, signal);
+		this.ensureAnswers(response, rest);
+		return response.body?.getReader() ?? new ReadableStream().getReader();
+	}
+	/**
+	* A server may answer other bytes than asked (a cache serving a range it holds); the answer
+	* says which in its Content-Range, where the page may read it.
+	*/
+	ensureAnswers(response, rest) {
+		const answered = contentRangeOf(response);
+		if (!answered) return;
+		const asked = `${rest.offset}-${rest.end - 1}`;
+		const given = `${answered.first}-${answered.last}`;
+		if (given === asked) return;
+		throw new GyroViewError("source-unreadable", `${this.parts.resource.url} answered bytes ${given} to a request for bytes ${asked}`);
+	}
+	async readFrom(attempt) {
+		const body = await attempt.body;
+		try {
+			return await body.read();
+		} catch (error) {
+			if (isAbortError(error)) throw error;
+			throw brokenOff(this.parts.resource.url, this.parts.range, error);
+		}
+	}
+	/**
+	* A request that brings no byte for the stall timeout, answer or body, is taken for stalled:
+	* a connection a network change left dead never fails by itself.
+	*/
+	async withinStallTimeout(pending) {
+		let timer;
+		const stalled = new Promise((_, reject) => {
+			timer = setTimeout(() => {
+				reject(this.stalled());
+			}, this.parts.stallTimeoutMs);
+		});
+		try {
+			return await Promise.race([pending, stalled]);
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+	stalled() {
+		const { resource, range, stallTimeoutMs } = this.parts;
+		const message = `${resource.url} sent nothing of the ${range.length}-byte range at ${range.offset} for ${stallTimeoutMs} ms`;
+		return passing(new GyroViewError("source-unreadable", message));
+	}
+	taken(read) {
+		if (read.done) {
+			this.ensureWhole();
+			return;
+		}
+		this.count(read.value);
+		return read.value;
+	}
+	count(chunk) {
+		const { resource, range } = this.parts;
+		this.received += chunk.byteLength;
+		if (this.received <= range.length) return;
+		throw new GyroViewError("source-unreadable", `${resource.url} sent more than the ${range.length}-byte range at ${range.offset}`);
+	}
+	ensureWhole() {
+		const { resource, range } = this.parts;
+		if (this.received !== range.length) throw truncated(resource.url, this.received, range);
+	}
+	drop(attempt) {
+		attempt.request.abort();
+		if (this.attempt === attempt) this.attempt = void 0;
+	}
+	/**
+	* Aborting the request once it is over, however it ended, also lets go of the listeners it
+	* put on the resource's own signal.
+	*/
+	end() {
+		this.ending.end();
+		if (this.attempt) this.drop(this.attempt);
+	}
+};
+//#endregion
+export { HttpByteStream };

package/dist/packages/adapters/fetch/src/HttpRangeSource.js

@@ -1,194 +1,38 @@
-import { GyroViewError, hasErrorCode, isAbortError } from "../../../core/src/shared/errors/GyroViewError.js";
+import { isAbortError } from "../../../core/src/shared/errors/GyroViewError.js";
 import "../../../core/src/index.js";
-import { EXPOSED_HEADERS_ADVICE, FIRST_BYTE_RANGE, discardBody, httpRequest, plainHttpRequest, withAbortSignal } from "./httpRequest.js";
+import { brokenOff, truncated } from "./rangeFailures.js";
 //#region ../../packages/adapters/fetch/src/HttpRangeSource.ts
-var HTTP_OK = 200;
-var HTTP_PARTIAL_CONTENT = 206;
-var HTTP_SERVER_ERROR = 500;
-var DEFAULT_RETRY_DELAYS_MS = [250, 1e3];
 /**
-* The failures on the way, which asking again may cure; any other fails the read at once. They
-* are `source-unreadable` errors like any other, so a caller that gets one after the retries
-* cannot tell, and need not: only the retry loop asks.
-*/
-var passingFailures = /* @__PURE__ */ new WeakSet();
-function passing(failure) {
-	passingFailures.add(failure);
-	return failure;
-}
-var CONTENT_RANGE_TOTAL = /\/(\d+)$/u;
-/**
-* RandomAccessSource over HTTP. The server must answer `Range` requests with 206 and, for
-* cross-origin use, send CORS headers that expose `Content-Range`; both are hard requirements
-* of playing a remote recording and are reported with distinct error codes.
+* RandomAccessSource over HTTP: each range read whole, in one request, asked for again when it
+* fails on the way. It shares its resource with the recording's byte stream, so both know one
+* size, one proof of CORS and one version.
 */
 var HttpRangeSource = class {
-	url;
-	options;
-	retryDelaysMs;
-	sizePromise;
-	/**
-	* A range has come through: CORS is proven for this source, so a request that fails from here
-	* on failed on the way, whatever the diagnosis says of an error page without CORS headers.
-	*/
-	hasReadRange = false;
-	/**
-	* `signal` ends every request the source makes, with the host's own `requestInit` signal.
-	*/
-	constructor(url, options = {}, signal) {
-		this.url = url;
-		this.options = signal ? withAbortSignal(options, signal) : options;
-		this.retryDelaysMs = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+	resource;
+	constructor(resource) {
+		this.resource = resource;
 	}
-	/**
-	* One HEAD request (or a one-byte range where HEAD is refused or gives no length), cached for
-	* the lifetime of the source once it succeeded; a failed lookup is retried on the next call.
-	*/
 	size() {
-		this.sizePromise ??= this.rememberSize();
-		return this.sizePromise;
+		return this.resource.size();
 	}
 	async read(range) {
-		await this.ensureFits(range);
-		return range.length === 0 ? /* @__PURE__ */ new Uint8Array() : this.readAskingAgain(range);
-	}
-	/**
-	* A range that failed on the way is asked for again after a short wait, a few times: one
-	* dropped connection must not end a long playback. What asking again cannot change (an abort,
-	* a refusal, a server ignoring ranges, CORS) fails at once.
-	*/
-	async readAskingAgain(range) {
-		for (const delayMs of this.retryDelaysMs) {
-			try {
-				return await this.readOnce(range);
-			} catch (error) {
-				if (!(error instanceof GyroViewError && passingFailures.has(error))) throw error;
-			}
-			await wait(delayMs, this.options.requestInit?.signal);
-		}
-		return this.readOnce(range);
+		await this.resource.ensureFits(range);
+		return range.length === 0 ? /* @__PURE__ */ new Uint8Array() : this.resource.askingAgain(() => this.readOnce(range));
 	}
 	async readOnce(range) {
-		const response = await this.requestRange(range);
-		if (response.status !== HTTP_PARTIAL_CONTENT) {
-			discardBody(response);
-			throw this.refusalOf(response.status);
-		}
-		this.hasReadRange = true;
+		const response = await this.resource.rangeAnswer(range);
 		const bytes = await this.bodyOf(response, range);
-		if (bytes.byteLength !== range.length) throw new GyroViewError("source-truncated", `${this.url} returned ${bytes.byteLength} bytes for a ${range.length}-byte range at ${range.offset}`);
+		if (bytes.byteLength !== range.length) throw truncated(this.resource.url, bytes.byteLength, range);
 		return bytes;
 	}
-	/**
-	* A request that did not get through for want of a network is worth another try; one CORS
-	* refused before any range came through is not.
-	*/
-	async requestRange(range) {
-		const headers = { Range: `bytes=${range.offset}-${range.end - 1}` };
-		try {
-			return this.hasReadRange ? await plainHttpRequest(this.url, {
-				method: "GET",
-				headers
-			}, this.options) : await this.request("GET", headers);
-		} catch (error) {
-			throw this.hasReadRange ? this.passingOnceAnswered(error) : passingIfUnreachable(error);
-		}
-	}
-	passingOnceAnswered(error) {
-		const message = `${this.url} could not be reached for a byte range`;
-		return isAbortError(error) ? error : passing(new GyroViewError("source-unreadable", message, { cause: error }));
-	}
-	refusalOf(status) {
-		if (status === HTTP_OK) return new GyroViewError("range-unsupported", `${this.url} ignores Range requests (answered 200 to a byte range)`);
-		const message = `${this.url} answered ${status} to a byte range`;
-		return status >= HTTP_SERVER_ERROR ? passing(new GyroViewError("source-unreadable", message)) : new GyroViewError("source-unreadable", message);
-	}
-	/**
-	* The bytes of a range, which a dropped connection can break off after the headers: the most
-	* common way a network fails during long playback, so it is `source-unreadable` as a refused
-	* request is, not a bug or a bad file, and worth another try.
-	*/
 	async bodyOf(response, range) {
 		try {
 			return new Uint8Array(await response.arrayBuffer());
 		} catch (error) {
 			if (isAbortError(error)) throw error;
-			throw passing(new GyroViewError("source-unreadable", `${this.url} broke off the ${range.length}-byte range at ${range.offset}`, { cause: error }));
+			throw brokenOff(this.resource.url, range, error);
 		}
 	}
-	/**
-	* Servers clamp out-of-range requests instead of failing them; the port contract wants a
-	* typed error, so the range is checked against the (cached) size first.
-	*/
-	async ensureFits(range) {
-		range.ensureWithin(await this.size(), `resource ${this.url}`);
-	}
-	async rememberSize() {
-		try {
-			return await this.fetchSize();
-		} catch (error) {
-			this.sizePromise = void 0;
-			throw error;
-		}
-	}
-	async fetchSize() {
-		const response = await this.request("HEAD");
-		discardBody(response);
-		if (!response.ok) return this.sizeFromContentRange();
-		const contentLength = Number(response.headers.get("content-length"));
-		return Number.isSafeInteger(contentLength) && contentLength > 0 ? contentLength : this.sizeFromContentRange();
-	}
-	/**
-	* Some servers omit Content-Length on HEAD or refuse HEAD; a one-byte range reveals the total.
-	*/
-	async sizeFromContentRange() {
-		const response = await this.request("GET", { Range: FIRST_BYTE_RANGE });
-		discardBody(response);
-		if (response.status !== HTTP_PARTIAL_CONTENT) throw new GyroViewError("source-unreadable", `${this.url} answered ${response.status} to a byte range; cannot determine the file size`);
-		this.hasReadRange = true;
-		const contentRange = response.headers.get("content-range");
-		if (contentRange === null && response.type === "cors") throw this.hiddenContentRange();
-		const total = CONTENT_RANGE_TOTAL.exec(contentRange ?? "")?.[1];
-		if (total === void 0) throw new GyroViewError("source-unreadable", `${this.url} reports neither Content-Length nor Content-Range; cannot determine the file size`);
-		return Number(total);
-	}
-	hiddenContentRange() {
-		return new GyroViewError("cors", `${this.url} answered a byte range but hides its Content-Range from this origin; add ${EXPOSED_HEADERS_ADVICE}`);
-	}
-	request(method, headers) {
-		return httpRequest(this.url, {
-			method,
-			...headers && { headers }
-		}, this.options);
-	}
 };
-/**
-* A pause before asking again, which an abort of the source's requests ends at once.
-*/
-function wait(ms, signal) {
-	return new Promise((resolve, reject) => {
-		signal?.throwIfAborted();
-		const settled = new AbortController();
-		const timer = setTimeout(() => {
-			settled.abort();
-			resolve();
-		}, ms);
-		const onAbort = () => {
-			clearTimeout(timer);
-			reject(abortErrorOf(signal));
-		};
-		signal?.addEventListener("abort", onAbort, {
-			once: true,
-			signal: settled.signal
-		});
-	});
-}
-function passingIfUnreachable(error) {
-	return hasErrorCode(error, "source-unreadable") && error instanceof Error ? passing(new GyroViewError("source-unreadable", error.message, { cause: error.cause })) : error;
-}
-function abortErrorOf(signal) {
-	const reason = signal?.reason;
-	return reason instanceof Error ? reason : new DOMException("the read was aborted", "AbortError");
-}
 //#endregion
 export { HttpRangeSource };

package/dist/packages/adapters/fetch/src/HttpResource.js

@@ -0,0 +1,192 @@
+import { GyroViewError, isAbortError } from "../../../core/src/shared/errors/GyroViewError.js";
+import "../../../core/src/index.js";
+import { contentRangeOf } from "./contentRange.js";
+import { isPassing, passing, passingIfUnreachable } from "./passingFailures.js";
+import { EXPOSED_HEADERS_ADVICE, FIRST_BYTE_RANGE, discardBody, httpRequest, plainHttpRequest, withAbortSignal } from "./httpRequest.js";
+import { isSameVersion, versionOf } from "./recordingVersion.js";
+//#region ../../packages/adapters/fetch/src/HttpResource.ts
+var HTTP_OK = 200;
+var HTTP_PARTIAL_CONTENT = 206;
+var HTTP_SERVER_ERROR = 500;
+var DEFAULT_RETRY_DELAYS_MS = [250, 1e3];
+/**
+* One recording at a URL, as every reader of it sees it: its size, whether its server has shown
+* it lets this page read it (CORS), the version its first answer told of (ADR 0029), and how a
+* range that failed on the way is asked for again.
+* The server must answer `Range` requests with 206 and, for cross-origin use, send CORS headers
+* that expose `Content-Range`; both are hard requirements of playing a remote recording and are
+* reported with distinct error codes.
+*/
+var HttpResource = class {
+	url;
+	options;
+	retryDelaysMs;
+	sizePromise;
+	/**
+	* A range has come through: CORS is proven for this resource, so a request that fails from
+	* here on failed on the way, whatever the diagnosis says of an error page without CORS headers.
+	*/
+	hasReadRange = false;
+	version;
+	/**
+	* `signal` ends every request made for the resource, with the host's own `requestInit` signal.
+	*/
+	constructor(url, options = {}, signal) {
+		this.url = url;
+		this.options = signal ? withAbortSignal(options, signal) : options;
+		this.retryDelaysMs = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+	}
+	/**
+	* One HEAD request (or a one-byte range where HEAD is refused or gives no length), cached for
+	* the lifetime of the resource once it succeeded; a failed lookup is retried on the next call.
+	*/
+	size() {
+		this.sizePromise ??= this.rememberSize();
+		return this.sizePromise;
+	}
+	/**
+	* Servers clamp out-of-range requests instead of failing them; the port contracts want a
+	* typed error, so the range is checked against the (cached) size first.
+	*/
+	async ensureFits(range) {
+		range.ensureWithin(await this.size(), `resource ${this.url}`);
+	}
+	/**
+	* Runs `attempt`, and after a short wait again, a few times, while it fails on the way: one
+	* dropped connection must not end a long playback. What asking again cannot change (an abort,
+	* a refusal, a server ignoring ranges, CORS) fails at once.
+	*/
+	async askingAgain(attempt) {
+		for (const delayMs of this.retryDelaysMs) {
+			try {
+				return await attempt();
+			} catch (error) {
+				if (!isPassing(error)) throw error;
+			}
+			await wait(delayMs, this.options.requestInit?.signal);
+		}
+		return attempt();
+	}
+	/**
+	* The server's answer to a byte range, its body still to be read: a 206, or the refusal it
+	* amounts to. `signal` ends this request alone.
+	*/
+	async rangeAnswer(range, signal) {
+		const options = signal ? withAbortSignal(this.options, signal) : this.options;
+		const response = await this.requestRange(range, options);
+		if (response.status !== HTTP_PARTIAL_CONTENT) {
+			discardBody(response);
+			throw this.refusalOf(response.status);
+		}
+		this.hasReadRange = true;
+		this.ensureUnchanged(response);
+		return response;
+	}
+	/**
+	* Every answer is of the version the first one told of: bytes of a recording replaced while it
+	* plays must not be put together with the old ones'.
+	*/
+	ensureUnchanged(response) {
+		const seen = versionOf(response);
+		this.version ??= seen;
+		if (isSameVersion(this.version, seen)) return;
+		discardBody(response);
+		throw new GyroViewError("source-changed", `${this.url} was replaced while it played; load it again`);
+	}
+	/**
+	* A request that did not get through for want of a network is worth another try; one CORS
+	* refused before any range came through is not.
+	*/
+	async requestRange(range, options) {
+		const headers = { Range: `bytes=${range.offset}-${range.end - 1}` };
+		try {
+			return this.hasReadRange ? await plainHttpRequest(this.url, {
+				method: "GET",
+				headers
+			}, options) : await httpRequest(this.url, {
+				method: "GET",
+				headers
+			}, options);
+		} catch (error) {
+			throw this.hasReadRange ? this.passingOnceAnswered(error) : passingIfUnreachable(error);
+		}
+	}
+	passingOnceAnswered(error) {
+		const message = `${this.url} could not be reached for a byte range`;
+		return isAbortError(error) ? error : passing(new GyroViewError("source-unreadable", message, { cause: error }));
+	}
+	refusalOf(status) {
+		if (status === HTTP_OK) return new GyroViewError("range-unsupported", `${this.url} ignores Range requests (answered 200 to a byte range)`);
+		const message = `${this.url} answered ${status} to a byte range`;
+		return status >= HTTP_SERVER_ERROR ? passing(new GyroViewError("source-unreadable", message)) : new GyroViewError("source-unreadable", message);
+	}
+	async rememberSize() {
+		try {
+			return await this.fetchSize();
+		} catch (error) {
+			this.sizePromise = void 0;
+			throw error;
+		}
+	}
+	async fetchSize() {
+		const response = await this.request("HEAD");
+		discardBody(response);
+		if (!response.ok) return this.sizeFromContentRange();
+		this.ensureUnchanged(response);
+		const contentLength = Number(response.headers.get("content-length"));
+		return Number.isSafeInteger(contentLength) && contentLength > 0 ? contentLength : this.sizeFromContentRange();
+	}
+	/**
+	* Some servers omit Content-Length on HEAD or refuse HEAD; a one-byte range reveals the total.
+	*/
+	async sizeFromContentRange() {
+		const response = await this.request("GET", { Range: FIRST_BYTE_RANGE });
+		discardBody(response);
+		if (response.status !== HTTP_PARTIAL_CONTENT) throw new GyroViewError("source-unreadable", `${this.url} answered ${response.status} to a byte range; cannot determine the file size`);
+		this.hasReadRange = true;
+		this.ensureUnchanged(response);
+		return this.totalOf(response);
+	}
+	totalOf(response) {
+		if (!response.headers.has("content-range") && response.type === "cors") throw this.hiddenContentRange();
+		const total = contentRangeOf(response)?.total;
+		if (total === void 0) throw new GyroViewError("source-unreadable", `${this.url} reports neither Content-Length nor Content-Range; cannot determine the file size`);
+		return total;
+	}
+	hiddenContentRange() {
+		return new GyroViewError("cors", `${this.url} answered a byte range but hides its Content-Range from this origin; add ${EXPOSED_HEADERS_ADVICE}`);
+	}
+	request(method, headers) {
+		return httpRequest(this.url, {
+			method,
+			...headers && { headers }
+		}, this.options);
+	}
+};
+/**
+* A pause before asking again, which an abort of the resource's requests ends at once.
+*/
+function wait(ms, signal) {
+	return new Promise((resolve, reject) => {
+		signal?.throwIfAborted();
+		const settled = new AbortController();
+		const timer = setTimeout(() => {
+			settled.abort();
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(abortErrorOf(signal));
+		};
+		signal?.addEventListener("abort", onAbort, {
+			once: true,
+			signal: settled.signal
+		});
+	});
+}
+function abortErrorOf(signal) {
+	const reason = signal?.reason;
+	return reason instanceof Error ? reason : new DOMException("the read was aborted", "AbortError");
+}
+//#endregion
+export { HttpResource };

package/dist/packages/adapters/fetch/src/contentRange.js

@@ -0,0 +1,15 @@
+//#region ../../packages/adapters/fetch/src/contentRange.ts
+var CONTENT_RANGE = /^bytes (\d+)-(\d+)\/(\d+|\*)$/u;
+var UNKNOWN_TOTAL = "*";
+function contentRangeOf(response) {
+	const match = CONTENT_RANGE.exec(response.headers.get("content-range") ?? "");
+	if (!match) return void 0;
+	const [, first, last, total] = match;
+	return {
+		first: Number(first),
+		last: Number(last),
+		total: total === UNKNOWN_TOTAL ? void 0 : Number(total)
+	};
+}
+//#endregion
+export { contentRangeOf };