@bubo-squared/gyroview 0.1.0

package/dist/packages/core/src/domain/view/normalView.js

@@ -0,0 +1,29 @@
+import { degrees } from "../../shared/units/angle.js";
+import { DEFAULT_VIEW, viewRotation } from "./ViewState.js";
+import { WHOLE_SCREEN, aspectOf } from "./screenLayout.js";
+import { lookAt, panView, zoomViewAt } from "./viewGestures.js";
+import { withView } from "./Framing.js";
+//#region ../../packages/core/src/domain/view/normalView.ts
+/**
+* A rectilinear window into the stitched sphere over the whole viewport, turned by drags and
+* arrows and zoomed by its field of view toward the pointer.
+*/
+var NORMAL_VIEW = {
+	isStabilized: true,
+	canPan: () => true,
+	pan: (framing, delta, { viewport }) => withView(framing, panView(framing.view, delta, viewport.width)),
+	turn: (framing, turn) => {
+		const { view } = framing;
+		return withView(framing, lookAt(view, degrees(view.yaw + turn.yaw), degrees(view.pitch + turn.pitch)));
+	},
+	zoom: (framing, zoom, { viewport }) => withView(framing, zoomViewAt(framing.view, zoom, aspectOf(viewport))),
+	reset: (framing) => withView(framing, DEFAULT_VIEW),
+	picture: ({ view }) => ({
+		kind: "rectilinear",
+		rotation: viewRotation(view),
+		fieldOfView: view.fieldOfView,
+		area: WHOLE_SCREEN
+	})
+};
+//#endregion
+export { NORMAL_VIEW };

package/dist/packages/core/src/domain/view/panoramaView.js

@@ -0,0 +1,99 @@
+import { FULL_TURN, HALF_TURN, degrees, degreesToRadians } from "../../shared/units/angle.js";
+import { rotationAboutY } from "../../shared/math/Matrix3.js";
+import { HALF, aspectOf, fittedRectangle, pictureAt, shiftOf } from "./screenLayout.js";
+import { lookAt } from "./viewGestures.js";
+import { FITTED, clampMagnification, magnifiedArea, magnifyAt, panMagnification, pictureShiftOf } from "./magnification.js";
+import { withView } from "./Framing.js";
+//#region ../../packages/core/src/domain/view/panoramaView.ts
+/**
+* An equirectangular picture spans a full turn across for a half turn from top to bottom.
+*/
+var EQUIRECTANGULAR_ASPECT = 2;
+function levelled(fitted, magnification) {
+	const clamped = clampMagnification(fitted, magnification);
+	return {
+		...clamped,
+		centre: {
+			x: HALF,
+			y: clamped.centre.y
+		}
+	};
+}
+function shownPanorama(framing, { viewport }) {
+	const fitted = fittedRectangle(EQUIRECTANGULAR_ASPECT, aspectOf(viewport));
+	return {
+		fitted,
+		panorama: levelled(fitted, framing.panorama)
+	};
+}
+function withPanorama(framing, panorama, yawDelta) {
+	const { view } = framing;
+	return {
+		...withView(framing, lookAt(view, degrees(view.yaw + yawDelta), view.pitch)),
+		panorama
+	};
+}
+/**
+* A drag turns the panorama a whole turn per width of the picture as shown, and moves it up and
+* down once it is taller than the viewport.
+*/
+function panPanorama(framing, delta, context) {
+	const { fitted, panorama } = shownPanorama(framing, context);
+	const shift = shiftOf(delta, context.viewport);
+	const moved = panMagnification(fitted, panorama, {
+		across: 0,
+		down: shift.down
+	});
+	const turned = pictureShiftOf(fitted, panorama, shift).across * FULL_TURN;
+	return withPanorama(framing, moved, degrees(-turned));
+}
+/**
+* Sideways the arrows turn it; up and down they move a panorama taller than the viewport by the
+* angle they name, the picture spanning a half turn from top to bottom.
+*/
+function turnPanorama(framing, turn, context) {
+	const { fitted, panorama } = shownPanorama(framing, context);
+	return withPanorama(framing, levelled(fitted, {
+		...panorama,
+		centre: {
+			x: HALF,
+			y: panorama.centre.y - turn.pitch / HALF_TURN
+		}
+	}), turn.yaw);
+}
+/**
+* Keeps the point under the pointer where it is: up and down by the magnification's own rule,
+* sideways by turning the panorama as far as the pointer's longitude moved.
+*/
+function zoomPanorama(framing, zoom, context) {
+	const { fitted, panorama } = shownPanorama(framing, context);
+	const zoomed = levelled(fitted, magnifyAt(fitted, panorama, zoom));
+	const before = pictureAt(magnifiedArea(fitted, panorama), zoom.focus);
+	const after = pictureAt(magnifiedArea(fitted, zoomed), zoom.focus);
+	return withPanorama(framing, zoomed, degrees((before.x - after.x) * FULL_TURN));
+}
+/**
+* Level, as an exported equirectangular video: the yaw picks the direction at the centre, and the
+* panorama magnifies up to four times and moves up and down within itself.
+*/
+var PANORAMA_VIEW = {
+	isStabilized: true,
+	canPan: () => true,
+	pan: panPanorama,
+	turn: turnPanorama,
+	zoom: zoomPanorama,
+	reset: (framing) => ({
+		...withView(framing, lookAt(framing.view, degrees(0), framing.view.pitch)),
+		panorama: FITTED
+	}),
+	picture: (framing, context) => {
+		const { fitted, panorama } = shownPanorama(framing, context);
+		return {
+			kind: "equirectangular",
+			rotation: rotationAboutY(degreesToRadians(framing.view.yaw)),
+			area: magnifiedArea(fitted, panorama)
+		};
+	}
+};
+//#endregion
+export { PANORAMA_VIEW };

package/dist/packages/core/src/domain/view/rectilinear.js

@@ -0,0 +1,40 @@
+import { degrees, degreesToRadians } from "../../shared/units/angle.js";
+import { magnitudeOf, scaleVector } from "../../shared/math/Vector3.js";
+import { transformVector } from "../../shared/math/Matrix3.js";
+import { viewRotation } from "./ViewState.js";
+//#region ../../packages/core/src/domain/view/rectilinear.ts
+/**
+* Half the width of the image plane at unit distance, so that a rectilinear picture spans the
+* given horizontal field of view across its width. The renderer's shader takes it as it is.
+*/
+function planeHalfExtentOf(fieldOfView) {
+	return Math.tan(degreesToRadians(degrees(fieldOfView / 2)));
+}
+/**
+* Width over height of an area of a viewport with the given aspect.
+*/
+function aspectOfArea(area, viewportAspect) {
+	return viewportAspect * area.width / area.height;
+}
+/**
+* The view-space direction (x right, y down, z forward) through a point of a rectilinear picture,
+* given as fractions of the picture; `rectilinearRays.glsl` computes the same for every pixel.
+*/
+function rayThroughPicture(fieldOfView, point, pictureAspect) {
+	const halfExtent = planeHalfExtentOf(fieldOfView);
+	const plane = [
+		(point.x * 2 - 1) * halfExtent,
+		(point.y * 2 - 1) * halfExtent / pictureAspect,
+		1
+	];
+	return scaleVector(plane, 1 / magnitudeOf(plane));
+}
+/**
+* The camera body direction seen through a point of the normal view's picture, which fills the
+* viewport, so its points are the viewport's.
+*/
+function directionAt(view, point, viewportAspect) {
+	return transformVector(viewRotation(view), rayThroughPicture(view.fieldOfView, point, viewportAspect));
+}
+//#endregion
+export { aspectOfArea, directionAt, planeHalfExtentOf, rayThroughPicture };

package/dist/packages/core/src/domain/view/screenLayout.js

@@ -0,0 +1,113 @@
+import { ensureInvariant } from "../../shared/errors/GyroViewError.js";
+//#region ../../packages/core/src/domain/view/screenLayout.ts
+/**
+* Half of a length along one axis, as a fraction of it: the middle of the viewport or of a
+* picture.
+*/
+var HALF = .5;
+var WHOLE_SCREEN = {
+	x: 0,
+	y: 0,
+	width: 1,
+	height: 1
+};
+var SCREEN_CENTRE = {
+	x: HALF,
+	y: HALF
+};
+/**
+* An empty viewport counts as one unit wide and high, so no measure of it divides by zero.
+*/
+function measured(length) {
+	return Math.max(length, 1);
+}
+/**
+* Width over height.
+*/
+function aspectOf(viewport) {
+	return viewport.width / measured(viewport.height);
+}
+/**
+* A drag as fractions of the viewport it happened on.
+*/
+function shiftOf(delta, viewport) {
+	return {
+		across: delta.x / measured(viewport.width),
+		down: delta.y / measured(viewport.height)
+	};
+}
+/**
+* The point of a picture shown at a point of the viewport, as fractions of the picture.
+*/
+function pictureAt(area, point) {
+	return {
+		x: (point.x - area.x) / area.width,
+		y: (point.y - area.y) / area.height
+	};
+}
+/**
+* One square tile per lens, in a row or in a column, whichever gives the larger tiles on this
+* viewport, centred with bars around. Square because every lens layout the player accepts has
+* square lens images: square tracks, or the halves of a 2:1 packed frame.
+*/
+function lensTiles(lensCount, viewportAspect) {
+	const row = fittedRectangle(lensCount, viewportAspect);
+	const column = fittedRectangle(1 / lensCount, viewportAspect);
+	return row.height >= column.height / lensCount ? tilesAcross(row, lensCount) : tilesDown(column, lensCount);
+}
+function tilesAcross(area, count) {
+	const width = area.width / count;
+	return Array.from({ length: count }, (_unused, index) => ({
+		...area,
+		x: area.x + index * width,
+		width
+	}));
+}
+function tilesDown(area, count) {
+	const height = area.height / count;
+	return Array.from({ length: count }, (_unused, index) => ({
+		...area,
+		y: area.y + index * height,
+		height
+	}));
+}
+/**
+* The smallest rectangle holding every one of the given rectangles.
+*/
+function boundsOf(rectangles) {
+	ensureInvariant(rectangles.length > 0, "bounds need at least one rectangle");
+	const left = Math.min(...rectangles.map((rectangle) => rectangle.x));
+	const top = Math.min(...rectangles.map((rectangle) => rectangle.y));
+	const right = Math.max(...rectangles.map((rectangle) => rectangle.x + rectangle.width));
+	const bottom = Math.max(...rectangles.map((rectangle) => rectangle.y + rectangle.height));
+	return {
+		x: left,
+		y: top,
+		width: right - left,
+		height: bottom - top
+	};
+}
+/**
+* The largest centred rectangle of the content's shape inside the viewport. Both aspects are
+* width over height; the bars it leaves go above and below wider content, beside narrower.
+*/
+function fittedRectangle(contentAspect, viewportAspect) {
+	if (contentAspect >= viewportAspect) {
+		const height = viewportAspect / contentAspect;
+		return {
+			x: 0,
+			y: (1 - height) * HALF,
+			width: 1,
+			height
+		};
+	}
+	const width = contentAspect / viewportAspect;
+	return {
+		x: (1 - width) * HALF,
+		y: 0,
+		width,
+		height: 1
+	};
+}
+//#endregion
+export { HALF, SCREEN_CENTRE, WHOLE_SCREEN, aspectOf, boundsOf, fittedRectangle, lensTiles, pictureAt, shiftOf };

package/dist/packages/core/src/domain/view/viewGestures.js

@@ -0,0 +1,98 @@
+import { degrees, degreesToRadians, radians, radiansToDegrees, wrapHalfTurn } from "../../shared/units/angle.js";
+import { rotationAboutX, transformVector } from "../../shared/math/Matrix3.js";
+import { clampView } from "./ViewState.js";
+import { SCREEN_CENTRE } from "./screenLayout.js";
+import { directionAt, rayThroughPicture } from "./rectilinear.js";
+//#region ../../packages/core/src/domain/view/viewGestures.ts
+/**
+* How much each wheel notch or pinch step magnifies, in every view mode.
+*/
+var ZOOM_STEP = 1.1;
+/**
+* The magnification `steps` zoom steps make: above 1 zooms in, below 1 out.
+*/
+function zoomFactor(steps) {
+	return ZOOM_STEP ** steps;
+}
+/**
+* Angle covered by one pixel across the viewport: the field of view spread over its width.
+*/
+function degreesPerPixel(view, viewportWidth) {
+	return degrees(view.fieldOfView / Math.max(viewportWidth, 1));
+}
+/**
+* Turns the view by a drag: dragging the picture to the right turns the viewer to the left, as
+* grabbing a globe does, by as many degrees as the drag covers at the current field of view.
+*/
+function panView(view, delta, viewportWidth) {
+	const perPixel = degreesPerPixel(view, viewportWidth);
+	return clampView({
+		...view,
+		yaw: degrees(view.yaw - delta.x * perPixel),
+		pitch: degrees(view.pitch + delta.y * perPixel)
+	});
+}
+/**
+* Narrows the field of view by `steps` zoom steps (negative widens), within its bounds.
+*/
+function zoomView(view, steps) {
+	return clampView({
+		...view,
+		fieldOfView: degrees(view.fieldOfView / zoomFactor(steps))
+	});
+}
+/**
+* Zooms the normal view toward a point of the viewport: the field of view narrows or widens by
+* the zoom's steps within its bounds, and the view turns so that the direction under the point
+* stays under it. When the poles leave no such turn, it zooms about the centre.
+*/
+function zoomViewAt(view, zoom, viewportAspect) {
+	const zoomed = zoomView(view, zoom.steps);
+	if (zoom.focus.x === SCREEN_CENTRE.x && zoom.focus.y === SCREEN_CENTRE.y || zoomed.fieldOfView === view.fieldOfView) return zoomed;
+	const direction = directionAt(view, zoom.focus, viewportAspect);
+	const ray = rayThroughPicture(zoomed.fieldOfView, zoom.focus, viewportAspect);
+	const pitch = pitchRaising(ray, direction[1], view.pitch);
+	if (pitch === void 0) return zoomed;
+	const tilted = transformVector(rotationAboutX(degreesToRadians(pitch)), ray);
+	const yaw = radiansToDegrees(radians(Math.atan2(direction[0], direction[2]) - Math.atan2(tilted[0], tilted[2])));
+	return clampView({
+		...zoomed,
+		yaw,
+		pitch
+	});
+}
+/**
+* The pitch that brings `ray` to the height `height` of the target direction, which the yaw
+* applied after it leaves alone: `y cos θ - z sin θ` is `reach cos(θ + phase)`. Of the two
+* solutions the one nearer `current`; none when no pitch reaches that height.
+*/
+function pitchRaising(ray, height, current) {
+	const [, y, z] = ray;
+	const cosine = height / Math.hypot(y, z);
+	if (Math.abs(cosine) > 1) return void 0;
+	const phase = radiansToDegrees(radians(Math.atan2(z, y)));
+	const spread = radiansToDegrees(radians(Math.acos(cosine)));
+	const rising = wrapHalfTurn(degrees(spread - phase));
+	const falling = wrapHalfTurn(degrees(-spread - phase));
+	return Math.abs(rising - current) <= Math.abs(falling - current) ? rising : falling;
+}
+/**
+* How many zoom steps a pinch from `previousDistance` to `distance` is worth, in the same steps
+* as a wheel notch: positive when the fingers spread (zoom in), zero when either distance is
+* degenerate.
+*/
+function zoomStepsForPinch(previousDistance, distance) {
+	return previousDistance <= 0 || distance <= 0 ? 0 : Math.log(distance / previousDistance) / Math.log(ZOOM_STEP);
+}
+/**
+* Points the view at a direction, clamped like every other change.
+*/
+function lookAt(view, yaw, pitch) {
+	return clampView({
+		...view,
+		yaw,
+		pitch
+	});
+}
+//#endregion
+export { lookAt, panView, zoomFactor, zoomStepsForPinch, zoomViewAt };

package/dist/packages/core/src/domain/view/viewModes.js

@@ -0,0 +1,14 @@
+import { LENS_TILES_VIEW } from "./lensTilesView.js";
+import { NORMAL_VIEW } from "./normalView.js";
+import { PANORAMA_VIEW } from "./panoramaView.js";
+//#region ../../packages/core/src/domain/view/viewModes.ts
+var RULES = {
+	normal: NORMAL_VIEW,
+	equirectangular: PANORAMA_VIEW,
+	"raw-lenses": LENS_TILES_VIEW
+};
+function viewModeRulesFor(mode) {
+	return RULES[mode];
+}
+//#endregion
+export { viewModeRulesFor };

package/dist/packages/core/src/index.js

@@ -0,0 +1,59 @@
+import { degrees } from "./shared/units/angle.js";
+import "./domain/optics/EquidistantModel.js";
+import "./domain/format/calibration/CalibrationVersion.js";
+import { GYRO_VIEW_ERROR_CODES, GyroViewError, asGyroViewError, ensureIndexInRange, ensureInvariant, hasErrorCode, isAbortError, isGyroViewErrorCode, messageOf } from "./shared/errors/GyroViewError.js";
+import { lazy } from "./shared/lazy.js";
+import { microseconds, microsecondsToSeconds, milliseconds, seconds, secondsToMicroseconds } from "./shared/units/time.js";
+import "./domain/motion/exposure/ExposureRecord.js";
+import "./shared/math/Vector3.js";
+import { ByteRange } from "./shared/binary/ByteRange.js";
+import "./domain/motion/timing/CaptureClock.js";
+import { readRecording } from "./application/recording/readRecording.js";
+import "./application/recording/inspectLayout.js";
+import { inspectRecording } from "./application/recording/inspectRecording.js";
+import { clamp } from "./shared/math/clamp.js";
+import "./domain/motion/timing/FrameTimes.js";
+import { IDENTITY_MATRIX3 } from "./shared/math/Matrix3.js";
+import "./domain/motion/imu/ImuFrame.js";
+import "./shared/math/Quaternion.js";
+import "./domain/motion/orientation/OrientationTrack.js";
+import { timeRecording } from "./application/recording/timeRecording.js";
+import "./domain/format/naming/RecordingFileName.js";
+import { fileNameOfUrl } from "./shared/text/urlPath.js";
+import { locateOtherLensFile } from "./application/recording/locateOtherLensFile.js";
+import "./domain/stitching/LensLayout.js";
+import { detectLensLayout } from "./domain/format/layout/detectLensLayout.js";
+import { DEFAULT_STABILIZATION_MODE, STABILIZATION_MODES } from "./domain/motion/stabilization/Stabilizer.js";
+import { stabilizerFor } from "./domain/motion/stabilization/stabilizers.js";
+import "./domain/optics/lensPose.js";
+import "./domain/optics/gainMatch.js";
+import { clampView, isSameView } from "./domain/view/ViewState.js";
+import { DEFAULT_PICTURE_QUALITY, PICTURE_QUALITIES, pixelRatioCapOf } from "./domain/view/PictureQuality.js";
+import { DEFAULT_VIEW_MODE, VIEW_MODES } from "./domain/view/ViewMode.js";
+import { SCREEN_CENTRE, aspectOf } from "./domain/view/screenLayout.js";
+import { aspectOfArea, planeHalfExtentOf } from "./domain/view/rectilinear.js";
+import { lookAt, zoomStepsForPinch } from "./domain/view/viewGestures.js";
+import "./domain/view/magnification.js";
+import { DEFAULT_FRAMING, isSameFraming } from "./domain/view/Framing.js";
+import { viewModeRulesFor } from "./domain/view/viewModes.js";
+import "./domain/stitching/seamRing.js";
+import { buildStitchingSetup, lensFrameOrder } from "./domain/stitching/StitchingSetup.js";
+import { StabilizingFrameSink } from "./application/stabilization/StabilizingFrameSink.js";
+import { GainMatchingFrameSink } from "./application/gainMatching/GainMatchingFrameSink.js";
+import "./domain/stitching/seamStrip.js";
+import "./domain/stitching/seamMismatch.js";
+import "./domain/stitching/seamDisparity.js";
+import "./domain/stitching/seamDisparityField.js";
+import "./domain/stitching/seamJoin.js";
+import { keysOf } from "./shared/keysOf.js";
+import { Outbox } from "./shared/events/Outbox.js";
+import "./application/playback/FramePairQueue.js";
+import { Deferred } from "./shared/async/Deferred.js";
+import { RunStop, STOPPED } from "./shared/async/RunStop.js";
+import "./application/playback/DecodePipeline.js";
+import { probeDecoding } from "./application/playback/probeDecoding.js";
+import { WallClock } from "./application/playback/WallClock.js";
+import { isFlowing } from "./domain/playback/PlayerState.js";
+import { TypedEmitter } from "./shared/events/TypedEmitter.js";
+import { PlaybackSession } from "./application/playback/PlaybackSession.js";
+export { ByteRange, DEFAULT_FRAMING, DEFAULT_PICTURE_QUALITY, DEFAULT_STABILIZATION_MODE, DEFAULT_VIEW_MODE, Deferred, GYRO_VIEW_ERROR_CODES, GainMatchingFrameSink, GyroViewError, IDENTITY_MATRIX3, Outbox, PICTURE_QUALITIES, PlaybackSession, RunStop, SCREEN_CENTRE, STABILIZATION_MODES, STOPPED, StabilizingFrameSink, TypedEmitter, VIEW_MODES, WallClock, asGyroViewError, aspectOf, aspectOfArea, buildStitchingSetup, clamp, clampView, degrees, detectLensLayout, ensureIndexInRange, ensureInvariant, fileNameOfUrl, hasErrorCode, inspectRecording, isAbortError, isFlowing, isGyroViewErrorCode, isSameFraming, isSameView, keysOf, lazy, lensFrameOrder, locateOtherLensFile, lookAt, messageOf, microseconds, microsecondsToSeconds, milliseconds, pixelRatioCapOf, planeHalfExtentOf, probeDecoding, readRecording, seconds, secondsToMicroseconds, stabilizerFor, timeRecording, viewModeRulesFor, zoomStepsForPinch };

package/dist/packages/core/src/ports/FramePair.js

@@ -0,0 +1,6 @@
+//#region ../../packages/core/src/ports/FramePair.ts
+function closeFramePair(pair) {
+	for (const frame of pair.frames) frame.close();
+}
+//#endregion
+export { closeFramePair };

package/dist/packages/core/src/shared/async/Deferred.js

@@ -0,0 +1,42 @@
+//#region ../../packages/core/src/shared/async/Deferred.ts
+/**
+* A promise settled from outside, once: later settlements are ignored. Lets a producer report
+* an outcome to whoever is waiting without knowing them.
+*/
+var Deferred = class {
+	promise;
+	isSettledNow = false;
+	resolvePromise;
+	rejectPromise;
+	constructor() {
+		this.promise = new Promise((resolve, reject) => {
+			this.resolvePromise = resolve;
+			this.rejectPromise = reject;
+		});
+	}
+	get isSettled() {
+		return this.isSettledNow;
+	}
+	resolve(value) {
+		if (this.isSettledNow) return;
+		this.isSettledNow = true;
+		this.resolvePromise?.(value);
+	}
+	reject(reason) {
+		if (this.isSettledNow) return;
+		this.isSettledNow = true;
+		this.rejectPromise?.(reason);
+	}
+	/**
+	* Settles as `outcome` does, once it has: hands work begun elsewhere to whoever waits here.
+	*/
+	async follow(outcome) {
+		try {
+			this.resolve(await outcome);
+		} catch (error) {
+			this.reject(error);
+		}
+	}
+};
+//#endregion
+export { Deferred };

package/dist/packages/core/src/shared/async/RunStop.js

@@ -0,0 +1,40 @@
+import { ensureInvariant } from "../errors/GyroViewError.js";
+//#region ../../packages/core/src/shared/async/RunStop.ts
+var STOPPED = Symbol("stopped");
+/**
+* Stops a run that waits for one thing at a time. `race` settles with `STOPPED` as soon as `stop`
+* is called; only the wait in progress is remembered, so an hour-long run of short waits keeps
+* nothing of the ones that finished. Once stopped it starts no work at all: work started and left
+* unwatched could fail later with nobody to hear it.
+*/
+var RunStop = class {
+	isStopped = false;
+	wakeWaiter;
+	get wasStopped() {
+		return this.isStopped;
+	}
+	stop() {
+		this.isStopped = true;
+		this.wakeWaiter?.();
+	}
+	/**
+	* The waiter is in place before `start` runs, so a stop that `start` itself causes (a decoder
+	* failing at once) ends the wait too.
+	*/
+	async race(start) {
+		if (this.isStopped) return STOPPED;
+		ensureInvariant(this.wakeWaiter === void 0, "a run stop races one wait at a time");
+		const stopped = new Promise((resolve) => {
+			this.wakeWaiter = () => {
+				resolve(STOPPED);
+			};
+		});
+		try {
+			return await Promise.race([start(), stopped]);
+		} finally {
+			this.wakeWaiter = void 0;
+		}
+	}
+};
+//#endregion
+export { RunStop, STOPPED };

package/dist/packages/core/src/shared/binary/ByteRange.js

@@ -0,0 +1,38 @@
+import { GyroViewError } from "../errors/GyroViewError.js";
+//#region ../../packages/core/src/shared/binary/ByteRange.ts
+/**
+* A contiguous span of bytes in a source: `offset` is inclusive, `end` is exclusive.
+*/
+var ByteRange = class ByteRange {
+	offset;
+	length;
+	constructor(offset, length) {
+		this.offset = offset;
+		this.length = length;
+	}
+	static of(offset, length) {
+		if (!Number.isSafeInteger(offset) || offset < 0) throw new GyroViewError("invalid-byte-range", `offset must be a non-negative integer, got ${offset}`);
+		if (!Number.isSafeInteger(length) || length < 0) throw new GyroViewError("invalid-byte-range", `length must be a non-negative integer, got ${length}`);
+		return new ByteRange(offset, length);
+	}
+	/**
+	* The last `length` bytes of a source of `totalSize` bytes.
+	*/
+	static lastOf(totalSize, length) {
+		if (length > totalSize) throw new GyroViewError("invalid-byte-range", `cannot take ${length} bytes from a ${totalSize}-byte source`);
+		return this.of(totalSize - length, length);
+	}
+	get end() {
+		return this.offset + this.length;
+	}
+	/**
+	* Refuses a range that runs past the end of a `totalSize`-byte source with the error the
+	* `RandomAccessSource` contract asks for; `source` names the source in the message.
+	*/
+	ensureWithin(totalSize, source) {
+		if (this.end <= totalSize) return;
+		throw new GyroViewError("invalid-byte-range", `range ${this.offset}+${this.length} exceeds the ${totalSize}-byte ${source}`);
+	}
+};
+//#endregion
+export { ByteRange };

package/dist/packages/core/src/shared/binary/ByteReader.js

@@ -0,0 +1,77 @@
+import { GyroViewError } from "../errors/GyroViewError.js";
+//#region ../../packages/core/src/shared/binary/ByteReader.ts
+var UINT8_SIZE = 1;
+var UINT16_SIZE = 2;
+var UINT32_SIZE = 4;
+var UINT64_SIZE = 8;
+var FLOAT64_SIZE = 8;
+var IS_LITTLE_ENDIAN = true;
+var IS_BIG_ENDIAN = false;
+/**
+* Bounds-checked, little-endian reads over a byte array. Every read is positional, so callers
+* express the record layouts they parse as named offsets rather than as a moving cursor.
+*/
+var ByteReader = class {
+	bytes;
+	view;
+	constructor(bytes) {
+		this.bytes = bytes;
+		this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	}
+	get length() {
+		return this.bytes.byteLength;
+	}
+	uint8At(offset) {
+		this.ensureAvailable(offset, UINT8_SIZE);
+		return this.view.getUint8(offset);
+	}
+	uint16LeAt(offset) {
+		this.ensureAvailable(offset, UINT16_SIZE);
+		return this.view.getUint16(offset, IS_LITTLE_ENDIAN);
+	}
+	uint32LeAt(offset) {
+		this.ensureAvailable(offset, UINT32_SIZE);
+		return this.view.getUint32(offset, IS_LITTLE_ENDIAN);
+	}
+	uint32BeAt(offset) {
+		this.ensureAvailable(offset, UINT32_SIZE);
+		return this.view.getUint32(offset, IS_BIG_ENDIAN);
+	}
+	/**
+	* Reads an unsigned 64-bit integer as a JavaScript number; rejects values beyond 2^53 - 1.
+	*/
+	uint64LeAt(offset) {
+		this.ensureAvailable(offset, UINT64_SIZE);
+		return this.toSafeNumber(this.view.getBigUint64(offset, IS_LITTLE_ENDIAN), offset);
+	}
+	/**
+	* Reads a big-endian unsigned 64-bit integer (ISOBMFF box sizes) as a safe JavaScript number.
+	*/
+	uint64BeAt(offset) {
+		this.ensureAvailable(offset, UINT64_SIZE);
+		return this.toSafeNumber(this.view.getBigUint64(offset, IS_BIG_ENDIAN), offset);
+	}
+	float64LeAt(offset) {
+		this.ensureAvailable(offset, FLOAT64_SIZE);
+		return this.view.getFloat64(offset, IS_LITTLE_ENDIAN);
+	}
+	/**
+	* Returns a view (not a copy) of `length` bytes starting at `offset`.
+	*/
+	bytesAt(offset, length) {
+		this.ensureAvailable(offset, length);
+		return this.bytes.subarray(offset, offset + length);
+	}
+	asciiAt(offset, length) {
+		return Array.from(this.bytesAt(offset, length), (byte) => String.fromCodePoint(byte)).join("");
+	}
+	toSafeNumber(value, offset) {
+		if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new GyroViewError("binary-unsafe-integer", `uint64 at offset ${offset} (${value.toString()}) exceeds the safe integer range`);
+		return Number(value);
+	}
+	ensureAvailable(offset, length) {
+		if (offset < 0 || length < 0 || offset + length > this.bytes.byteLength) throw new GyroViewError("binary-out-of-bounds", `read of ${length} byte(s) at offset ${offset} exceeds ${this.bytes.byteLength} available`);
+	}
+};
+//#endregion
+export { ByteReader };