@bvdmitri/gyroview 0.0.0-stage → 0.9.0-cutaway.2

package/dist/index.js

@@ -0,0 +1,12 @@
+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";
+import { attachKeyboard, attachViewGestures } from "./packages/player/src/controls/customControls.js";
+import { Player } from "./packages/player/src/player/Player.js";
+import { createBrowserPlayer } from "./packages/player/src/browserPlayer.js";
+import { inspectRecording } from "./packages/player/src/inspectRecording.js";
+import { openRendition } from "./packages/player/src/rendition.js";
+import { GyroViewElement } from "./packages/player/src/element/GyroViewElement.js";
+import { GYRO_VIEW_TAG, defineGyroView } from "./packages/player/src/element/defineGyroView.js";
+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, openRendition };

package/dist/packages/adapters/blob/src/BlobRandomAccessSource.js

@@ -0,0 +1,36 @@
+import { GyroViewError } from "../../../core/src/shared/errors/GyroViewError.js";
+//#region ../../packages/adapters/blob/src/BlobRandomAccessSource.ts
+/**
+* RandomAccessSource over a `Blob` (a `File` from a picker or a drop). Each read slices the
+* blob, which browsers serve from disk without loading the whole file, so multi-gigabyte
+* recordings play from local storage the same way they play from a URL.
+*/
+var BlobRandomAccessSource = class {
+	blob;
+	constructor(blob) {
+		this.blob = blob;
+	}
+	size() {
+		return Promise.resolve(this.blob.size);
+	}
+	async read(range) {
+		range.ensureWithin(this.blob.size, "blob");
+		if (range.length === 0) return /* @__PURE__ */ new Uint8Array();
+		const bytes = await this.bytesOf(this.blob.slice(range.offset, range.end));
+		if (bytes.byteLength !== range.length) throw new GyroViewError("source-truncated", `the blob yielded ${bytes.byteLength} bytes for a ${range.length}-byte range at ${range.offset}; the file may have changed on disk`);
+		return bytes;
+	}
+	/**
+	* Reading is what fails, with a `NotReadableError`, when a picked file has changed or gone on
+	* disk; slicing only clamps its arguments.
+	*/
+	async bytesOf(slice) {
+		try {
+			return new Uint8Array(await slice.arrayBuffer());
+		} catch (error) {
+			throw new GyroViewError("source-unreadable", "the blob could not be read", { cause: error });
+		}
+	}
+};
+//#endregion
+export { BlobRandomAccessSource };

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

@@ -0,0 +1,173 @@
+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 { 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

@@ -0,0 +1,37 @@
+import { isAbortError } from "../../../core/src/shared/errors/GyroViewError.js";
+import { brokenOff, truncated } from "./rangeFailures.js";
+//#region ../../packages/adapters/fetch/src/HttpRangeSource.ts
+/**
+* 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 {
+	resource;
+	constructor(resource) {
+		this.resource = resource;
+	}
+	size() {
+		return this.resource.size();
+	}
+	async read(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.resource.rangeAnswer(range);
+		const bytes = await this.bodyOf(response, range);
+		if (bytes.byteLength !== range.length) throw truncated(this.resource.url, bytes.byteLength, range);
+		return bytes;
+	}
+	async bodyOf(response, range) {
+		try {
+			return new Uint8Array(await response.arrayBuffer());
+		} catch (error) {
+			if (isAbortError(error)) throw error;
+			throw brokenOff(this.resource.url, range, error);
+		}
+	}
+};
+//#endregion
+export { HttpRangeSource };

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

@@ -0,0 +1,227 @@
+import { GyroViewError, isAbortError } from "../../../core/src/shared/errors/GyroViewError.js";
+import { milliseconds, millisecondsToSeconds } from "../../../core/src/shared/units/time.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_TOO_MANY_REQUESTS = 429;
+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;
+	now;
+	shortestAnswerMs;
+	/**
+	* `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;
+		this.now = options.now ?? (() => performance.now());
+	}
+	/**
+	* How long its server took to answer a byte range, from asking to the answer's headers: the
+	* shortest wait of the ranges answered so far, so a first one slowed by a new connection, a
+	* CORS preflight or a cold cache counts for nothing (ADR 0044). A HEAD, which a server may
+	* answer from what it knows of the file without reading it, and a refusal tell nothing.
+	* Undefined until a range was answered.
+	*/
+	answerWait() {
+		const shortest = this.shortestAnswerMs;
+		return shortest === void 0 ? void 0 : millisecondsToSeconds(milliseconds(shortest));
+	}
+	/**
+	* 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, nor a server's 5xx or its 429 asking the
+	* player to slow down. What asking again cannot change (an abort, any other 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 await this.timed(() => this.hasReadRange ? plainHttpRequest(this.url, {
+				method: "GET",
+				headers
+			}, options) : 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 isPassingStatus(status) ? 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 this.timed(() => httpRequest(this.url, {
+			method,
+			...headers && { headers }
+		}, this.options));
+	}
+	/**
+	* The request, its wait noted when it brought a range's bytes (206); one that failed, was
+	* given up or was refused tells nothing.
+	*/
+	async timed(send) {
+		const askedAt = this.now();
+		const response = await send();
+		if (response.status !== HTTP_PARTIAL_CONTENT) return response;
+		const waitMs = this.now() - askedAt;
+		this.shortestAnswerMs = Math.min(waitMs, this.shortestAnswerMs ?? waitMs);
+		return response;
+	}
+};
+/**
+* A server error, or a server asking the player to slow down (429, as rate-limited APIs answer):
+* both may pass by the time the range is asked for again. Any other refusal stands.
+*/
+function isPassingStatus(status) {
+	return status >= HTTP_SERVER_ERROR || status === HTTP_TOO_MANY_REQUESTS;
+}
+/**
+* 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/HttpResourceLocator.js

@@ -0,0 +1,35 @@
+import { FIRST_BYTE_RANGE, discardBody, plainHttpRequest } from "./httpRequest.js";
+//#region ../../packages/adapters/fetch/src/HttpResourceLocator.ts
+/**
+* How a server refuses HEAD: a 405, or a 403 from a URL signed for GET alone. The first byte
+* then answers what HEAD would.
+*/
+var REFUSED_HEAD = /* @__PURE__ */ new Set([405, 403]);
+/**
+* ResourceLocator over HTTP: one HEAD request, or a one-byte GET when the server refuses HEAD.
+* Every failure, including a missing CORS header, means "not available"; the file looked for is
+* optional, so nothing here throws, and no request is spent explaining a failure.
+*/
+var HttpResourceLocator = class {
+	options;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	async exists(url) {
+		try {
+			const head = await plainHttpRequest(url, { method: "HEAD" }, this.options);
+			discardBody(head);
+			if (!REFUSED_HEAD.has(head.status)) return head.ok;
+			const firstByte = await plainHttpRequest(url, {
+				method: "GET",
+				headers: { Range: FIRST_BYTE_RANGE }
+			}, this.options);
+			discardBody(firstByte);
+			return firstByte.ok;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { HttpResourceLocator };

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

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

@@ -0,0 +1,136 @@
+import { GyroViewError, isAbortError } from "../../../core/src/shared/errors/GyroViewError.js";
+//#region ../../packages/adapters/fetch/src/httpRequest.ts
+/**
+* The Range header value that asks for the first byte only: enough to learn whether a resource
+* is there, or its total size from Content-Range.
+*/
+var FIRST_BYTE_RANGE = "bytes=0-0";
+/**
+* The response headers a cross-origin page must be let read, as the fix a CORS failure names;
+* `ETag` is optional, and tells a recording replaced while it plays more surely than
+* `Last-Modified`, which a page may always read.
+*/
+var EXPOSED_HEADERS_ADVICE = "Access-Control-Expose-Headers: Content-Range, Content-Length, Accept-Ranges, ETag";
+/**
+* What a server must add for a page to read it across origins. A request that carries the
+* visitor's cookies is held to more: the Fetch standard refuses a wildcard origin for it.
+*/
+var ANONYMOUS_CORS_ADVICE = `Access-Control-Allow-Origin, ${EXPOSED_HEADERS_ADVICE}`;
+var CREDENTIALED_CORS_ADVICE = `Access-Control-Allow-Origin naming this page's origin, not *; Access-Control-Allow-Credentials: true; ${EXPOSED_HEADERS_ADVICE}`;
+/**
+* Browsers keep byte ranges of one URL as a sparse cache entry and revalidate them with
+* conditional requests. A 304 to such a request makes the browser answer from that entry, and
+* Chrome has been seen to hand back an empty body for a range it believed it held (ADR 0013).
+* The download holds what it needs itself, so nothing is lost by leaving the cache out.
+*/
+var CACHE_MODE = "no-store";
+/**
+* One request with the shared settings merged in, failures explained: a request that fails
+* outright is told apart from one the browser blocked for want of CORS headers (the latter is
+* `cors`, the former `source-unreadable`). A caller's abort is passed on as it is.
+*/
+async function httpRequest(url, request, options) {
+	try {
+		return await plainHttpRequest(url, request, options);
+	} catch (error) {
+		if (isAbortError(error)) throw error;
+		throw await diagnoseFailure(url, options, error);
+	}
+}
+/**
+* One request with the shared settings merged in and its failure left as the platform reported
+* it, for callers to whom any failure means the same.
+*/
+function plainHttpRequest(url, request, options) {
+	return (options.fetch ?? fetch)(url, {
+		cache: CACHE_MODE,
+		...options.requestInit,
+		method: request.method,
+		headers: {
+			...headersOf(options.requestInit),
+			...request.headers
+		}
+	});
+}
+/**
+* The options with `signal` ending their requests too, beside any signal the host gave: made once
+* per source, so the listeners it adds do not pile up per request.
+*/
+function withAbortSignal(options, signal) {
+	const hostSignal = options.requestInit?.signal ?? void 0;
+	const either = hostSignal ? eitherSignal(hostSignal, signal) : signal;
+	return {
+		...options,
+		requestInit: {
+			...options.requestInit,
+			signal: either
+		}
+	};
+}
+/**
+* Fires when either does. `AbortSignal.any` would do, but iOS Safari has it only from 17.4.
+* Whichever fires takes both listeners along, so a long-lived host signal keeps none.
+*/
+function eitherSignal(first, second) {
+	const controller = new AbortController();
+	for (const signal of [first, second]) {
+		if (signal.aborted) controller.abort(signal.reason);
+		signal.addEventListener("abort", () => {
+			controller.abort(signal.reason);
+		}, {
+			once: true,
+			signal: controller.signal
+		});
+	}
+	return controller.signal;
+}
+/**
+* Browsers report a CORS refusal and a network failure alike, as a rejected fetch. A request
+* that asks for no CORS answer at all (an opaque response) still succeeds when the server is
+* reachable, so its outcome tells the two apart.
+*/
+async function diagnoseFailure(url, options, cause) {
+	return await isReachableWithoutCors(url, options) ? new GyroViewError("cors", `${url} answered, but its server does not allow this page's origin to read it; add CORS headers (${corsAdviceFor(options)})`, { cause }) : new GyroViewError("source-unreadable", `${url} could not be fetched; check the URL and the network`, { cause });
+}
+function corsAdviceFor(options) {
+	return options.requestInit?.credentials === "include" ? CREDENTIALED_CORS_ADVICE : ANONYMOUS_CORS_ADVICE;
+}
+/**
+* The probe ends with the request it diagnoses: an abort of the load ends it too.
+*/
+async function isReachableWithoutCors(url, options) {
+	const doFetch = options.fetch ?? fetch;
+	const signal = options.requestInit?.signal ?? null;
+	try {
+		discardBody(await doFetch(url, {
+			method: "HEAD",
+			mode: "no-cors",
+			signal
+		}));
+		return true;
+	} catch (error) {
+		if (isAbortError(error)) throw error;
+		return false;
+	}
+}
+/**
+* Lets the browser stop streaming a body that will not be read, for example a whole file
+* answered to a byte range.
+*/
+function discardBody(response) {
+	cancelBody(response);
+}
+/**
+* A body the request's abort already ended refuses the cancel with that abort: there is nothing
+* left to stop, and the abort reaches the caller through the request itself.
+*/
+async function cancelBody(response) {
+	try {
+		await response.body?.cancel();
+	} catch {}
+}
+function headersOf(init) {
+	return Object.fromEntries(new Headers(init?.headers).entries());
+}
+//#endregion
+export { EXPOSED_HEADERS_ADVICE, FIRST_BYTE_RANGE, discardBody, httpRequest, plainHttpRequest, withAbortSignal };