@bubo-squared/gyroview 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 What changed for a page using the package, newest first. Until 1.0, a minor version may change
 the API.
 
+## 0.3.1 (2026-09-30)
+
+New:
+
+- Every error has a `category`, derived from its code, that says whose side the failure is on:
+  `browser`, `recording`, `source`, `usage` or `internal`; `GYRO_VIEW_ERROR_CATEGORIES` and the
+  type `GyroViewErrorCategory` list them. The README's "When a recording cannot play" gives the
+  codes of each, and what a `<video>` fallback can and cannot do (ADR 0030).
+- The `webcodecs-unavailable` error: the browser has no WebCodecs, on a page not served over
+  HTTPS or in an old browser.
+
+What a page may notice:
+
+- A page on plain HTTP, or a browser without WebCodecs, hears `webcodecs-unavailable` where it
+  heard `codec-unsupported`, whose message blamed the codec.
+
+## 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

@@ -5,6 +5,9 @@ camera's dual-fisheye file directly, over HTTP byte ranges or from a local file,
 lenses in hardware with WebCodecs, and stitches and gyro-stabilizes them on the GPU. No Insta360
 Studio export step.
 
+**Try it first:** [insv-player.com](https://insv-player.com/) plays `.insv` files with this
+package. Drop your own recording to check that your camera and browser work before you install.
+
 ## Install
 
 ```sh
@@ -42,10 +45,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 +119,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
@@ -177,7 +191,8 @@ loads a recording only for the player in view, removing `src` from the others.
 
 ## Requirements
 
-- **A secure page.** WebCodecs exists only on `https://` pages, or `http://localhost`.
+- **A secure page.** WebCodecs exists only on `https://` pages, or `http://localhost`; elsewhere
+  the player fails with `webcodecs-unavailable`.
 - **Recordings served in byte ranges.** The server answers `Range` requests with `206`, and
   sends CORS headers when the recordings live on another origin than the page:
 
@@ -185,7 +200,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
@@ -194,17 +209,20 @@ loads a recording only for the player in view, removing `src` from the others.
   `Access-Control-Allow-Credentials: true`.
 
 - **A hardware HEVC decoder.** 5.7K plays on recent laptops and phones; 8K needs a Level 6
-  decoder (Apple Silicon, recent NVIDIA and Intel). A recording the browser cannot decode fails
-  with the `codec-unsupported` error.
+  decoder (Apple Silicon, recent NVIDIA and Intel). On Linux, Chrome reaches the decoder only
+  through VA-API: an Intel or AMD GPU whose driver offers HEVC, not NVIDIA's own driver or a
+  virtual machine (`chrome://gpu` lists `Decode hevc main` under Video Acceleration
+  Information when it can). H.264 recordings do not need it. A recording the browser cannot
+  decode fails with the `codec-unsupported` error.
 
 The supported browsers, with the oldest versions that have what the player uses (WebCodecs,
 WebGL 2, container queries, and on iPhone `ManagedMediaSource` for the sound):
 
-| Browser               | From | Notes                                                    |
-| --------------------- | ---- | -------------------------------------------------------- |
-| Chrome, Edge desktop  | 107  | HEVC is decoded in hardware from this version on.        |
-| Safari on macOS       | 16.4 |                                                          |
-| Safari on iPhone/iPad | 17.1 | 16.4 to 17.0 play without sound, with a `warning` event. |
+| Browser               | From | Notes                                                             |
+| --------------------- | ---- | ----------------------------------------------------------------- |
+| Chrome, Edge desktop  | 107  | HEVC is decoded in hardware from this version on (Linux: VA-API). |
+| Safari on macOS       | 16.4 |                                                                   |
+| Safari on iPhone/iPad | 17.1 | 16.4 to 17.0 play without sound, with a `warning` event.          |
 
 Firefox and Chrome on Android are untested: they play what their decoders accept.
 
@@ -213,8 +231,10 @@ Until 1.0, a minor version may change the API; [CHANGELOG.md](./CHANGELOG.md) sa
 ## Reference
 
 Every attribute, method, event and keyboard shortcut is in the
-[project README](https://github.com/bubo-squared/GyroView#using-the-player); hosting and the
-error codes are in [docs/DEPLOYMENT.md](https://github.com/bubo-squared/GyroView/blob/main/docs/DEPLOYMENT.md).
+[project README](https://github.com/bubo-squared/GyroView#using-the-player), and what a failure
+tells a page, with what a `<video>` fallback can do, under
+[When a recording cannot play](https://github.com/bubo-squared/GyroView#when-a-recording-cannot-play);
+hosting and the error codes are in [docs/DEPLOYMENT.md](https://github.com/bubo-squared/GyroView/blob/main/docs/DEPLOYMENT.md).
 
 ## License
 

package/dist/index.d.ts

@@ -261,7 +261,7 @@ interface DragDelta {
 export type ViewMode = "raw-lenses" | "equirectangular" | "normal";
 export declare const VIEW_MODES: readonly ViewMode[];
 /**
- * Stable machine-readable failure categories. Embedders switch on these; messages are for humans.
+ * Stable machine-readable failure codes. Embedders switch on these; messages are for humans.
  */
 export declare const GYRO_VIEW_ERROR_CODES: readonly [
 	"binary-out-of-bounds",
@@ -284,18 +284,37 @@ export declare const GYRO_VIEW_ERROR_CODES: readonly [
 	"playback-blocked",
 	"range-unsupported",
 	"render-unavailable",
+	"source-changed",
 	"source-truncated",
 	"source-unreadable",
 	"unsupported-calibration",
 	"unsupported-container",
 	"unsupported-gyro-record",
 	"unsupported-info-format",
-	"unsupported-layout"
+	"unsupported-layout",
+	"webcodecs-unavailable"
 ];
 export type GyroViewErrorCode = (typeof GYRO_VIEW_ERROR_CODES)[number];
+/**
+ * Whose side a failure is on, for embedders that handle failures by kind: the browser cannot
+ * decode or draw the recording, the file is not one the player can play, its bytes could not be
+ * read, the page misused the API, or the player failed in a way it did not expect.
+ */
+export declare const GYRO_VIEW_ERROR_CATEGORIES: readonly [
+	"browser",
+	"recording",
+	"source",
+	"usage",
+	"internal"
+];
+export type GyroViewErrorCategory = (typeof GYRO_VIEW_ERROR_CATEGORIES)[number];
 export declare function isGyroViewErrorCode(value: unknown): value is GyroViewErrorCode;
 export declare class GyroViewError extends Error {
 	readonly code: GyroViewErrorCode;
+	/**
+	 * Its own property rather than a getter, so a serialized or logged copy of the error keeps it.
+	 */
+	readonly category: GyroViewErrorCategory;
 	constructor(code: GyroViewErrorCode, message: string, options?: ErrorOptions);
 }
 export declare function hasErrorCode(error: unknown, code: GyroViewErrorCode): boolean;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { GYRO_VIEW_ERROR_CODES, GyroViewError, hasErrorCode, isGyroViewErrorCode } from "./packages/core/src/shared/errors/GyroViewError.js";
+import { GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GyroViewError, hasErrorCode, isGyroViewErrorCode } from "./packages/core/src/shared/errors/GyroViewError.js";
 import { STABILIZATION_MODES } from "./packages/core/src/domain/motion/stabilization/Stabilizer.js";
 import { PICTURE_QUALITIES } from "./packages/core/src/domain/view/PictureQuality.js";
 import { VIEW_MODES } from "./packages/core/src/domain/view/ViewMode.js";
@@ -10,4 +10,4 @@ import { inspectRecording } from "./packages/player/src/inspectRecording.js";
 import { GyroViewElement } from "./packages/player/src/element/GyroViewElement.js";
 import { GYRO_VIEW_TAG, defineGyroView } from "./packages/player/src/element/defineGyroView.js";
 import "./packages/player/src/index.js";
-export { GYRO_VIEW_ERROR_CODES, GYRO_VIEW_TAG, GyroViewElement, GyroViewError, PICTURE_QUALITIES, Player, STABILIZATION_MODES, VIEW_MODES, attachKeyboard, attachViewGestures, createBrowserPlayer, defineGyroView, hasErrorCode, inspectRecording, isGyroViewErrorCode };
+export { GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GYRO_VIEW_TAG, GyroViewElement, GyroViewError, PICTURE_QUALITIES, Player, STABILIZATION_MODES, VIEW_MODES, attachKeyboard, attachViewGestures, createBrowserPlayer, defineGyroView, hasErrorCode, inspectRecording, isGyroViewErrorCode };

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 };