@bubo-squared/gyroview 0.1.0

package/dist/packages/core/src/shared/errors/GyroViewError.js

@@ -0,0 +1,81 @@
+//#region ../../packages/core/src/shared/errors/GyroViewError.ts
+/**
+* Stable machine-readable failure categories. Embedders switch on these; messages are for humans.
+*/
+var GYRO_VIEW_ERROR_CODES = [
+	"binary-out-of-bounds",
+	"binary-unsafe-integer",
+	"codec-unsupported",
+	"cors",
+	"decode",
+	"embed-destroyed",
+	"index-out-of-range",
+	"invalid-argument",
+	"invalid-byte-range",
+	"invalid-calibration",
+	"invalid-protobuf",
+	"invalid-trailer",
+	"invariant-violation",
+	"missing-second-file",
+	"no-calibration",
+	"no-info-record",
+	"no-key-frame",
+	"playback-blocked",
+	"range-unsupported",
+	"render-unavailable",
+	"source-truncated",
+	"source-unreadable",
+	"unsupported-calibration",
+	"unsupported-container",
+	"unsupported-gyro-record",
+	"unsupported-info-format",
+	"unsupported-layout"
+];
+function isGyroViewErrorCode(value) {
+	return typeof value === "string" && GYRO_VIEW_ERROR_CODES.includes(value);
+}
+var GyroViewError = class extends Error {
+	code;
+	constructor(code, message, options) {
+		super(message, options);
+		this.code = code;
+		this.name = "GyroViewError";
+	}
+};
+/**
+* `error` as a `GyroViewError`: one already typed as it is, anything else under `code`, kept as
+* the cause, so a failure crosses a boundary typed without losing what it was.
+*/
+function asGyroViewError(error, code, message) {
+	return error instanceof GyroViewError ? error : new GyroViewError(code, message, { cause: error });
+}
+/**
+* A caller's abort, as `AbortSignal` reports it (a `DOMException` named `AbortError`): passed on
+* as it is, never taken for a failure.
+*/
+function isAbortError(error) {
+	return error instanceof Error && error.name === "AbortError";
+}
+function hasErrorCode(error, code) {
+	return error instanceof GyroViewError && error.code === code;
+}
+/**
+* The human-readable part of anything thrown: an error's message, or the value as text.
+*/
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Guards a constructor or factory precondition with the shared error type.
+*/
+function ensureInvariant(isSatisfied, message) {
+	if (!isSatisfied) throw new GyroViewError("invariant-violation", message);
+}
+/**
+* Guards positional access into a fixed-length collection.
+*/
+function ensureIndexInRange(index, length, subject) {
+	if (!Number.isSafeInteger(index) || index < 0 || index >= length) throw new GyroViewError("index-out-of-range", `${subject} index ${index} is outside 0..${length - 1}`);
+}
+//#endregion
+export { GYRO_VIEW_ERROR_CODES, GyroViewError, asGyroViewError, ensureIndexInRange, ensureInvariant, hasErrorCode, isAbortError, isGyroViewErrorCode, messageOf };

package/dist/packages/core/src/shared/errors/reportLater.js

@@ -0,0 +1,11 @@
+//#region ../../packages/core/src/shared/errors/reportLater.ts
+/**
+* A failure nobody is waiting for surfaces as an unhandled rejection, where the platform reports
+* it, and leaves whoever met it to carry on.
+*/
+function reportLater(error) {
+	const reason = error instanceof Error ? error : new Error("a failure went unheard", { cause: error });
+	Promise.reject(reason);
+}
+//#endregion
+export { reportLater };

package/dist/packages/core/src/shared/events/Outbox.js

@@ -0,0 +1,68 @@
+//#region ../../packages/core/src/shared/events/Outbox.ts
+/**
+* Holds what a change announces until the change is complete, then delivers it in order. A
+* listener never runs in the middle of the change it hears, so the code making a change reads its
+* own state after announcing, never a state a listener left. A change a listener makes while it
+* hears one supersedes the older change: once the newer change announces, whatever the older one
+* still had to announce is dropped, since the newer change reports itself (ADR 0021).
+*/
+var Outbox = class {
+	emitter;
+	queue = [];
+	depth = 0;
+	isDelivering = false;
+	/**
+	* A listener's change is under way and has announced nothing yet.
+	*/
+	isSuperseding = false;
+	constructor(emitter) {
+		this.emitter = emitter;
+	}
+	/**
+	* Runs `make` as one change: what it announces goes out once the outermost change is complete.
+	*/
+	change(make) {
+		if (this.depth === 0 && this.isDelivering) this.isSuperseding = true;
+		this.depth += 1;
+		try {
+			return make();
+		} finally {
+			this.depth -= 1;
+			if (this.depth === 0) {
+				this.isSuperseding = false;
+				this.deliver();
+			}
+		}
+	}
+	emit(name, payload) {
+		this.post(() => {
+			this.emitter.emit(name, payload);
+		});
+	}
+	/**
+	* Announces: at once outside a change, and once it is complete within one. What is announced
+	* is decided when it is delivered, for an announcement that reads the state then.
+	*/
+	post(announce) {
+		if (this.isSuperseding) {
+			this.queue.length = 0;
+			this.isSuperseding = false;
+		}
+		this.queue.push(announce);
+		if (this.depth === 0) this.deliver();
+	}
+	/**
+	* Announcements made while delivering, by a listener, join the end of the line.
+	*/
+	deliver() {
+		if (this.isDelivering) return;
+		this.isDelivering = true;
+		try {
+			for (let next = this.queue.shift(); next; next = this.queue.shift()) next();
+		} finally {
+			this.isDelivering = false;
+		}
+	}
+};
+//#endregion
+export { Outbox };

package/dist/packages/core/src/shared/events/TypedEmitter.js

@@ -0,0 +1,55 @@
+import { reportLater } from "../errors/reportLater.js";
+//#region ../../packages/core/src/shared/events/TypedEmitter.ts
+/**
+* Minimal typed observer: one payload type per event name, unsubscribe through the returned
+* function. No platform EventTarget so it works in the dependency-free core.
+*
+* A listener that throws, a page's among them, is reported and skipped, as `dispatchEvent`
+* does: the code that emitted, a frame loop or a load, carries on, and so do the other listeners.
+*
+* Listeners are stored with their payload type erased to `never`, which every listener type is
+* assignable to; `emit` restores the type its event name guarantees.
+*/
+var TypedEmitter = class {
+	reportListenerError;
+	listeners = /* @__PURE__ */ new Map();
+	constructor(reportListenerError = reportLater) {
+		this.reportListenerError = reportListenerError;
+	}
+	on(name, listener) {
+		const set = this.listeners.get(name) ?? /* @__PURE__ */ new Set();
+		set.add(listener);
+		this.listeners.set(name, set);
+		return () => {
+			set.delete(listener);
+		};
+	}
+	/**
+	* The listeners there when the emit began hear it, as `dispatchEvent` delivers: one added
+	* meanwhile waits for the next emit, so a listener that subscribes itself again runs once, and
+	* one removed meanwhile hears no more.
+	*/
+	emit(name, payload) {
+		const listeners = this.listeners.get(name);
+		if (!listeners) return;
+		const listening = [...listeners];
+		for (const listener of listening) {
+			if (!listeners.has(listener)) continue;
+			try {
+				listener(payload);
+			} catch (error) {
+				this.reportListenerError(error);
+			}
+		}
+	}
+	/**
+	* The listeners of an event under way are dropped too, as an unsubscribe drops one: whoever
+	* removed them is past hearing from them.
+	*/
+	removeAll() {
+		for (const set of this.listeners.values()) set.clear();
+		this.listeners.clear();
+	}
+};
+//#endregion
+export { TypedEmitter };

package/dist/packages/core/src/shared/keysOf.js

@@ -0,0 +1,10 @@
+//#region ../../packages/core/src/shared/keysOf.ts
+/**
+* The keys of a record that names each of `Key` once, as a list to use at run time: the record's
+* type makes the compiler refuse a missing or an unknown key, which a list alone would not.
+*/
+function keysOf(every) {
+	return Object.keys(every);
+}
+//#endregion
+export { keysOf };

package/dist/packages/core/src/shared/lazy.js

@@ -0,0 +1,11 @@
+//#region ../../packages/core/src/shared/lazy.ts
+/**
+* A value made on first request and kept: for what costs work to build and may never be asked
+* for, such as an element's parsed markup on a page that renders none.
+*/
+function lazy(make) {
+	let made;
+	return () => (made ??= { value: make() }).value;
+}
+//#endregion
+export { lazy };

package/dist/packages/core/src/shared/math/Matrix3.js

@@ -0,0 +1,93 @@
+//#region ../../packages/core/src/shared/math/Matrix3.ts
+var IDENTITY_MATRIX3 = [
+	1,
+	0,
+	0,
+	0,
+	1,
+	0,
+	0,
+	0,
+	1
+];
+function rotationAboutX(angle) {
+	const c = Math.cos(angle);
+	const s = Math.sin(angle);
+	return [
+		1,
+		0,
+		0,
+		0,
+		c,
+		-s,
+		0,
+		s,
+		c
+	];
+}
+function rotationAboutY(angle) {
+	const c = Math.cos(angle);
+	const s = Math.sin(angle);
+	return [
+		c,
+		0,
+		s,
+		0,
+		1,
+		0,
+		-s,
+		0,
+		c
+	];
+}
+function rotationAboutZ(angle) {
+	const c = Math.cos(angle);
+	const s = Math.sin(angle);
+	return [
+		c,
+		-s,
+		0,
+		s,
+		c,
+		0,
+		0,
+		0,
+		1
+	];
+}
+/**
+* `a * b`: applying the product to a vector applies `b` first, then `a`.
+*/
+function multiplyMatrices(a, b) {
+	const [a00, a01, a02, a10, a11, a12, a20, a21, a22] = a;
+	const [b00, b01, b02, b10, b11, b12, b20, b21, b22] = b;
+	return [
+		a00 * b00 + a01 * b10 + a02 * b20,
+		a00 * b01 + a01 * b11 + a02 * b21,
+		a00 * b02 + a01 * b12 + a02 * b22,
+		a10 * b00 + a11 * b10 + a12 * b20,
+		a10 * b01 + a11 * b11 + a12 * b21,
+		a10 * b02 + a11 * b12 + a12 * b22,
+		a20 * b00 + a21 * b10 + a22 * b20,
+		a20 * b01 + a21 * b11 + a22 * b21,
+		a20 * b02 + a21 * b12 + a22 * b22
+	];
+}
+function transformVector(m, v) {
+	const [m00, m01, m02, m10, m11, m12, m20, m21, m22] = m;
+	const [x, y, z] = v;
+	return [
+		m00 * x + m01 * y + m02 * z,
+		m10 * x + m11 * y + m12 * z,
+		m20 * x + m21 * y + m22 * z
+	];
+}
+/**
+* Positive one for a proper rotation, minus one for a reflection, zero when singular.
+*/
+function determinantOf(m) {
+	const [m00, m01, m02, m10, m11, m12, m20, m21, m22] = m;
+	return m00 * (m11 * m22 - m12 * m21) - m01 * (m10 * m22 - m12 * m20) + m02 * (m10 * m21 - m11 * m20);
+}
+//#endregion
+export { IDENTITY_MATRIX3, determinantOf, multiplyMatrices, rotationAboutX, rotationAboutY, rotationAboutZ, transformVector };

package/dist/packages/core/src/shared/math/Quaternion.js

@@ -0,0 +1,133 @@
+import { radians } from "../units/angle.js";
+import { magnitudeOf } from "./Vector3.js";
+//#region ../../packages/core/src/shared/math/Quaternion.ts
+var IDENTITY_QUATERNION = [
+	0,
+	0,
+	0,
+	1
+];
+/**
+* Rotations smaller than this, in radians, are treated as no rotation by the exponential map.
+*/
+var NEGLIGIBLE_ANGLE = 1e-12;
+/**
+* Below this dot product two quaternions are far enough apart for a real spherical interpolation.
+*/
+var NEARLY_PARALLEL = .9995;
+function quaternionFromAxisAngle(axis, angle) {
+	const length = magnitudeOf(axis);
+	if (length === 0) return IDENTITY_QUATERNION;
+	const half = angle / 2;
+	const scale = Math.sin(half) / length;
+	return [
+		axis[0] * scale,
+		axis[1] * scale,
+		axis[2] * scale,
+		Math.cos(half)
+	];
+}
+/**
+* Exponential map: the rotation of `|omega|` radians about `omega`, for example an angular
+* velocity times a time step.
+*/
+function quaternionFromRotationVector(omega) {
+	const angle = magnitudeOf(omega);
+	return angle < NEGLIGIBLE_ANGLE ? IDENTITY_QUATERNION : quaternionFromAxisAngle(omega, radians(angle));
+}
+/**
+* `a * b`: applying the product to a vector applies `b` first, then `a`.
+*/
+function multiplyQuaternions(a, b) {
+	const [ax, ay, az, aw] = a;
+	const [bx, by, bz, bw] = b;
+	return [
+		aw * bx + ax * bw + ay * bz - az * by,
+		aw * by - ax * bz + ay * bw + az * bx,
+		aw * bz + ax * by - ay * bx + az * bw,
+		aw * bw - ax * bx - ay * by - az * bz
+	];
+}
+/**
+* The inverse rotation of a unit quaternion.
+*/
+function conjugateQuaternion(q) {
+	const [x, y, z, w] = q;
+	return [
+		-x,
+		-y,
+		-z,
+		w
+	];
+}
+function normalizeQuaternion(q) {
+	const [x, y, z, w] = q;
+	const length = Math.hypot(x, y, z, w);
+	return length === 0 ? IDENTITY_QUATERNION : [
+		x / length,
+		y / length,
+		z / length,
+		w / length
+	];
+}
+function rotateVector(q, v) {
+	const [qx, qy, qz, qw] = q;
+	const [vx, vy, vz] = v;
+	const tx = 2 * (qy * vz - qz * vy);
+	const ty = 2 * (qz * vx - qx * vz);
+	const tz = 2 * (qx * vy - qy * vx);
+	return [
+		vx + qw * tx + (qy * tz - qz * ty),
+		vy + qw * ty + (qz * tx - qx * tz),
+		vz + qw * tz + (qx * ty - qy * tx)
+	];
+}
+/**
+* Spherical interpolation from `a` (t = 0) to `b` (t = 1) along the shorter arc.
+*/
+function slerpQuaternions(a, b, t) {
+	const [ax, ay, az, aw] = a;
+	let [bx, by, bz, bw] = b;
+	let dot = ax * bx + ay * by + az * bz + aw * bw;
+	if (dot < 0) {
+		dot = -dot;
+		[bx, by, bz, bw] = [
+			-bx,
+			-by,
+			-bz,
+			-bw
+		];
+	}
+	if (dot > NEARLY_PARALLEL) return normalizeQuaternion([
+		ax + (bx - ax) * t,
+		ay + (by - ay) * t,
+		az + (bz - az) * t,
+		aw + (bw - aw) * t
+	]);
+	const theta = Math.acos(dot);
+	const sinTheta = Math.sin(theta);
+	const weightA = Math.sin((1 - t) * theta) / sinTheta;
+	const weightB = Math.sin(t * theta) / sinTheta;
+	return [
+		ax * weightA + bx * weightB,
+		ay * weightA + by * weightB,
+		az * weightA + bz * weightB,
+		aw * weightA + bw * weightB
+	];
+}
+function quaternionToMatrix(q) {
+	const [x, y, z, w] = q;
+	return [
+		1 - 2 * (y * y + z * z),
+		2 * (x * y - z * w),
+		2 * (x * z + y * w),
+		2 * (x * y + z * w),
+		1 - 2 * (x * x + z * z),
+		2 * (y * z - x * w),
+		2 * (x * z - y * w),
+		2 * (y * z + x * w),
+		1 - 2 * (x * x + y * y)
+	];
+}
+//#endregion
+export { IDENTITY_QUATERNION, conjugateQuaternion, multiplyQuaternions, normalizeQuaternion, quaternionFromAxisAngle, quaternionFromRotationVector, quaternionToMatrix, rotateVector, slerpQuaternions };

package/dist/packages/core/src/shared/math/Vector3.js

@@ -0,0 +1,54 @@
+//#region ../../packages/core/src/shared/math/Vector3.ts
+var ZERO_VECTOR3 = [
+	0,
+	0,
+	0
+];
+function magnitudeOf(vector) {
+	return Math.hypot(vector[0], vector[1], vector[2]);
+}
+function dotProduct(a, b) {
+	return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+/**
+* Right-handed: x cross y is z.
+*/
+function crossProduct(a, b) {
+	return [
+		a[1] * b[2] - a[2] * b[1],
+		a[2] * b[0] - a[0] * b[2],
+		a[0] * b[1] - a[1] * b[0]
+	];
+}
+function isFiniteVector(vector) {
+	return vector.every((component) => Number.isFinite(component));
+}
+function addVectors(a, b) {
+	return [
+		a[0] + b[0],
+		a[1] + b[1],
+		a[2] + b[2]
+	];
+}
+function subtractVectors(a, b) {
+	return [
+		a[0] - b[0],
+		a[1] - b[1],
+		a[2] - b[2]
+	];
+}
+function scaleVector(vector, factor) {
+	return [
+		vector[0] * factor,
+		vector[1] * factor,
+		vector[2] * factor
+	];
+}
+/**
+* The point `weight` of the way from `from` to `to`: `from` at 0, `to` at 1.
+*/
+function interpolateVectors(from, to, weight) {
+	return addVectors(from, scaleVector(subtractVectors(to, from), weight));
+}
+//#endregion
+export { ZERO_VECTOR3, addVectors, crossProduct, dotProduct, interpolateVectors, isFiniteVector, magnitudeOf, scaleVector, subtractVectors };

package/dist/packages/core/src/shared/math/clamp.js

@@ -0,0 +1,9 @@
+//#region ../../packages/core/src/shared/math/clamp.ts
+/**
+* `value` held within `low` and `high`.
+*/
+function clamp(value, low, high) {
+	return Math.min(Math.max(value, low), high);
+}
+//#endregion
+export { clamp };

package/dist/packages/core/src/shared/protobuf/ProtobufMessage.js

@@ -0,0 +1,157 @@
+import { GyroViewError } from "../errors/GyroViewError.js";
+import { ByteReader } from "../binary/ByteReader.js";
+import { decodeUtf8 } from "../text/utf8.js";
+//#region ../../packages/core/src/shared/protobuf/ProtobufMessage.ts
+/**
+* Protocol Buffers wire types this decoder understands. Groups (3, 4) are obsolete and rejected.
+*/
+var WireType = {
+	Varint: 0,
+	Fixed64: 1,
+	LengthDelimited: 2,
+	Fixed32: 5
+};
+var FIELD_NUMBER_SHIFT = 3;
+var WIRE_TYPE_MASK = 7;
+var VARINT_PAYLOAD_BITS = 7n;
+var VARINT_PAYLOAD_MASK = 127n;
+var VARINT_CONTINUATION_BIT = 128;
+var FIXED64_SIZE = 8;
+var FIXED32_SIZE = 4;
+var MAX_VARINT_BYTES = 10;
+var MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+/**
+* A schema-less view of one encoded protobuf message: fields are looked up by number and unknown
+* fields are simply carried along. Varints stay exact (bigint) until a caller asks for a number,
+* so an oversized value in a field nobody reads cannot break the whole record.
+*/
+var ProtobufMessage = class ProtobufMessage {
+	decoded;
+	constructor(decoded) {
+		this.decoded = decoded;
+	}
+	static decode(bytes) {
+		const cursor = new Cursor(bytes);
+		const fields = [];
+		while (!cursor.atEnd) fields.push(cursor.readField());
+		return new ProtobufMessage(fields);
+	}
+	varint(number) {
+		const value = this.valueOf(number);
+		if (value === void 0) return void 0;
+		if (value.kind !== "varint") throw this.wrongType(number, "varint", value.kind);
+		if (value.value > MAX_SAFE) throw new GyroViewError("binary-unsafe-integer", `field ${number} holds ${value.value.toString()}, beyond the safe integer range`);
+		return Number(value.value);
+	}
+	boolean(number) {
+		const value = this.varint(number);
+		return value === void 0 ? void 0 : value !== 0;
+	}
+	double(number) {
+		const value = this.valueOf(number);
+		if (value === void 0) return void 0;
+		if (value.kind !== "fixed64") throw this.wrongType(number, "fixed64", value.kind);
+		return new ByteReader(value.bytes).float64LeAt(0);
+	}
+	bytes(number) {
+		const value = this.valueOf(number);
+		if (value === void 0) return void 0;
+		if (value.kind !== "bytes") throw this.wrongType(number, "bytes", value.kind);
+		return value.bytes;
+	}
+	string(number) {
+		const bytes = this.bytes(number);
+		return bytes === void 0 ? void 0 : decodeUtf8(bytes);
+	}
+	message(number) {
+		const bytes = this.bytes(number);
+		return bytes === void 0 ? void 0 : ProtobufMessage.decode(bytes);
+	}
+	/**
+	* Scalar accessors follow protobuf merge semantics: the last occurrence of a field wins.
+	*/
+	valueOf(number) {
+		return this.decoded.findLast((field) => field.number === number)?.value;
+	}
+	wrongType(number, expected, actual) {
+		return new GyroViewError("invalid-protobuf", `field ${number} is encoded as ${actual}, expected ${expected}`);
+	}
+};
+/**
+* Sequential reader over the wire format; kept private to the message decoder.
+*/
+var Cursor = class {
+	bytes;
+	position = 0;
+	reader;
+	constructor(bytes) {
+		this.bytes = bytes;
+		this.reader = new ByteReader(bytes);
+	}
+	get atEnd() {
+		return this.position >= this.bytes.byteLength;
+	}
+	readField() {
+		const key = this.readVarint();
+		const number = Number(key >> BigInt(FIELD_NUMBER_SHIFT));
+		const wireType = Number(key & BigInt(WIRE_TYPE_MASK));
+		return {
+			number,
+			value: this.readValue(wireType, number)
+		};
+	}
+	readValue(wireType, fieldNumber) {
+		switch (wireType) {
+			case WireType.Varint: return {
+				kind: "varint",
+				value: this.readVarint()
+			};
+			case WireType.Fixed64: return {
+				kind: "fixed64",
+				bytes: this.readBytes(FIXED64_SIZE)
+			};
+			case WireType.Fixed32: return {
+				kind: "fixed32",
+				bytes: this.readBytes(FIXED32_SIZE)
+			};
+			case WireType.LengthDelimited: return {
+				kind: "bytes",
+				bytes: this.readBytes(this.readLength())
+			};
+			default: throw new GyroViewError("invalid-protobuf", `field ${fieldNumber} uses unsupported wire type ${wireType}`);
+		}
+	}
+	readVarint() {
+		let result = 0n;
+		let shift = 0n;
+		for (let consumed = 0; consumed < MAX_VARINT_BYTES; consumed += 1) {
+			const byte = this.readByte();
+			result |= (BigInt(byte) & VARINT_PAYLOAD_MASK) << shift;
+			if ((byte & VARINT_CONTINUATION_BIT) === 0) return result;
+			shift += VARINT_PAYLOAD_BITS;
+		}
+		throw new GyroViewError("invalid-protobuf", `varint longer than ${MAX_VARINT_BYTES} bytes at byte ${this.position}`);
+	}
+	readLength() {
+		const length = this.readVarint();
+		if (length > BigInt(this.bytes.byteLength)) throw new GyroViewError("invalid-protobuf", `length ${length.toString()} exceeds the message at byte ${this.position}`);
+		return Number(length);
+	}
+	readByte() {
+		this.ensureRemaining(1);
+		const byte = this.reader.uint8At(this.position);
+		this.position += 1;
+		return byte;
+	}
+	readBytes(length) {
+		this.ensureRemaining(length);
+		const bytes = this.reader.bytesAt(this.position, length);
+		this.position += length;
+		return bytes;
+	}
+	ensureRemaining(length) {
+		if (this.position + length > this.bytes.byteLength) throw new GyroViewError("invalid-protobuf", `message truncated at byte ${this.position}`);
+	}
+};
+//#endregion
+export { ProtobufMessage };