@bubo-squared/gyroview 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -3,6 +3,53 @@
 What changed for a page using the package, newest first. Until 1.0, a minor version may change
 the API.
 
+## 0.6.1 (2026-10-05)
+
+Fixed:
+
+- Where the browser has no fullscreen for the element (iPhone Safari), the pinned player covers
+  the whole viewport from inside a modal, a carousel or any container with a transform, a filter
+  or containment: it is shown in the top layer, as the browser's own fullscreen is (ADR 0041).
+  It filled only that container, and the page showed around it. It also stays above the page's
+  own layers, whatever their `z-index`, and keeps none of the page's corners, `translate`,
+  `rotate` or `scale` for it.
+
+What a page may notice:
+
+- While pinned, the element has `popover="manual"` beside `data-fill`; a page never sets the
+  attribute itself. A popover or dialog the page opens meanwhile shows above it, as over the
+  browser's fullscreen. Where the browser has no popovers of its own (Safari before 17), the
+  element is pinned in place as before.
+- While pinned, the element's background, colour, font and overflow are its own: a page's styles
+  for every `[popover]`, and the page's own `background`, `color` or `font-family` on
+  `gyro-view`, no longer reach it; the `--gyro-view-*` properties still theme it. A page's
+  shadow or opacity for every popover would.
+- An element the page removes while pinned leaves the fill, as one in the browser's fullscreen
+  does. One it moves within the same task, taken out and put back before a microtask runs, stays
+  pinned.
+
+## 0.6.0 (2026-10-05)
+
+New:
+
+- Motion look: on a phone or tablet, a toggle in the normal view lets the device turn the view, the
+  screen a window into the recording with its horizon level with the real one (ADR 0040). The
+  element and the player have `motionLook` (`on`, `off` or `unavailable`), `startMotionLook()`,
+  which iOS honours only from a tap's handler, and `stopMotionLook()`; `motionlookchange` reports
+  it, and the warnings `motion-look-refused` and `motion-look-needs-gesture` say why it did not
+  start.
+
+What a page may notice:
+
+- `PlayerEvents`, `GyroViewElementEventMap` and `WarningCode` have the new event and codes; a
+  record keyed on every event or code needs them.
+- `view` and `viewchange` give a fresh object of `yaw`, `pitch` and `fieldOfView` each time.
+- The iframe the snippet creates allows `accelerometer; gyroscope; magnetometer`; a hand-written
+  iframe needs them for motion look. Without them, Chromium offers no toggle; iOS offers it and
+  refuses at the first press (`motion-look-refused`).
+- On the narrowest players with the motion look toggle shown, the Stabilization menu gives way
+  to it.
+
 ## 0.5.0 (2026-10-03)
 
 New:

package/README.md

@@ -45,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.5/dist/standalone.js"
+  src="https://cdn.jsdelivr.net/npm/@bubo-squared/gyroview@0.6/dist/standalone.js"
 ></script>
 <script type="module">
-  import { inspectRecording } from 'https://cdn.jsdelivr.net/npm/@bubo-squared/gyroview@0.5/dist/standalone.js';
+  import { inspectRecording } from 'https://cdn.jsdelivr.net/npm/@bubo-squared/gyroview@0.6/dist/standalone.js';
 </script>
 ```
 

package/dist/index.d.ts

@@ -418,8 +418,9 @@ export interface ViewAngles {
 	readonly fieldOfView: number;
 }
 /**
- * What concerns one load only. The settings (view, view mode, stabilization, gain matching,
- * sound, loop) belong to the player and carry over from load to load; set them on the player.
+ * What concerns one load only. The settings (view, view mode, motion look, stabilization, gain
+ * matching, sound, loop) belong to the player and carry over from load to load; set them on the
+ * player.
  */
 export interface LoadOptions {
 	/**
@@ -436,6 +437,11 @@ export interface LoadOptions {
  * The session's states plus the two only the player knows: nothing loaded, and loading.
  */
 export type PlayerStatus = "idle" | "loading" | PlayerState;
+/**
+ * Motion look as it stands: `unavailable` where the device reports no attitude or access was
+ * refused, `off`, or `on`, the device turning the normal view (ADR 0040).
+ */
+export type MotionLookState = "unavailable" | "off" | "on";
 /**
  * The sound as it is now: volume from 0 to 1, and whether it is muted.
  */
@@ -453,8 +459,12 @@ export interface SoundLevel {
  * - `playback-failed`: a start (a press, autoplay, the loop) or the seek bar's preview failed.
  * - `ignored-attribute`: an attribute's value names nothing the element knows; the setting stays.
  * - `refused-property`: a property set before the element was defined was refused.
+ * - `motion-look-refused`: the viewer, or an iframe's `allow`, refused access to the device's
+ *   attitude; motion look is unavailable.
+ * - `motion-look-needs-gesture`: motion look was started outside a user gesture, where iOS does
+ *   not ask; it stays off.
  */
-export type WarningCode = "recording-degraded" | "no-sound" | "autoplay-blocked" | "playback-failed" | "ignored-attribute" | "refused-property";
+export type WarningCode = "recording-degraded" | "no-sound" | "autoplay-blocked" | "playback-failed" | "ignored-attribute" | "refused-property" | "motion-look-refused" | "motion-look-needs-gesture";
 export interface PlayerWarning {
 	readonly code: WarningCode;
 	/**
@@ -488,6 +498,7 @@ export interface PlayerEvents {
 	readonly frame: number;
 	readonly viewchange: ViewAngles;
 	readonly viewmodechange: ViewMode;
+	readonly motionlookchange: MotionLookState;
 	readonly stabilizationchange: StabilizationMode;
 	/**
 	 * The picture quality changed, to the one named.
@@ -506,8 +517,8 @@ export interface PlayerEvents {
 /**
  * The player without the element, which `createBrowserPlayer` gives: it plays one recording at a
  * time on the canvas and audio element it was handed, reports in media-element events, and keeps
- * its settings (view, view mode, stabilization, gain matching, sound, loop) from load to load.
- * `<gyro-view>` is a facade over it.
+ * its settings (view, view mode, motion look, stabilization, gain matching, sound, loop) from
+ * load to load. `<gyro-view>` is a facade over it.
  */
 export declare class Player {
 	private readonly parts;
@@ -519,6 +530,7 @@ export declare class Player {
 	private readonly loop;
 	private phase;
 	private readonly viewing;
+	private readonly motion;
 	private readonly picture;
 	/**
 	 * A seek asked for before a recording was ready, where the next one starts.
@@ -526,7 +538,7 @@ export declare class Player {
 	private pendingStartTime;
 	private readonly sound;
 	private readonly relay;
-	private isLoopingValue;
+	private readonly starts;
 	/**
 	 * Past `dispose`: a listener of the idle it announces must not load again.
 	 */
@@ -549,6 +561,11 @@ export declare class Player {
 	 * Whether a drag moves the picture as it is framed now; the view mode decides.
 	 */
 	get canPan(): boolean;
+	/**
+	 * Whether turning the device turns the normal view: `unavailable` where the device reports no
+	 * attitude or access was refused.
+	 */
+	get motionLook(): MotionLookState;
 	get stabilization(): StabilizationMode;
 	get quality(): PictureQuality;
 	get isLooping(): boolean;
@@ -604,6 +621,17 @@ export declare class Player {
 	zoom(steps: number, focus?: ScreenPoint): void;
 	resetView(): void;
 	setViewMode(mode: ViewMode): void;
+	/**
+	 * Lets the device turn the normal view, as a window into the recording: its tilt and roll
+	 * hold the pitch and keep the horizon level, drags turn the heading alone. Call it from a tap's
+	 * handler: iOS asks the viewer for access there and refuses it anywhere else. Resolves with the
+	 * state it ends in; a refusal is a warning, never a rejection.
+	 */
+	startMotionLook(): Promise<MotionLookState>;
+	/**
+	 * Gives the view back to the pointer, level, looking where it looked.
+	 */
+	stopMotionLook(): void;
 	setStabilization(mode: StabilizationMode): void;
 	/**
 	 * How finely the lens images are read and how many device pixels are drawn; kept across loads.
@@ -626,12 +654,6 @@ export declare class Player {
 	private complete;
 	private startAtPendingTime;
 	private attach;
-	/**
-	 * A refused start leaves the recording loaded and paused: a warning, never a failed load.
-	 */
-	private autoplay;
-	private onEnded;
-	private replay;
 	/**
 	 * Lets go of whatever is loading or loaded, announcing nothing.
 	 */
@@ -664,6 +686,10 @@ export interface GyroViewLabels {
 	readonly mute: string;
 	readonly volume: string;
 	readonly resetView: string;
+	/**
+	 * The toggle that lets the device's own turns turn the normal view.
+	 */
+	readonly motionLook: string;
 	readonly stabilization: string;
 	readonly viewMode: string;
 	readonly fullscreen: string;
@@ -792,9 +818,9 @@ export interface BrowserPortsOptions {
 	readonly probeTimeoutMs?: number;
 }
 /**
- * A player composed for a browser: HTTP, blob and WebCodecs ports and the GPU pipeline, drawing
- * on the host's canvas and sounding through its audio element. What `<gyro-view>` plays with,
- * and where a page that wants the player without the element starts.
+ * A player composed for a browser: HTTP, blob and WebCodecs ports, the GPU pipeline and the
+ * device's attitude, drawing on the host's canvas and sounding through its audio element. What
+ * `<gyro-view>` plays with, and where a page that wants the player without the element starts.
  */
 export declare function createBrowserPlayer(host: PipelineHost, options?: BrowserPortsOptions): Player;
 export interface InspectOptions extends Pick<BrowserPortsOptions, "http"> {
@@ -903,6 +929,11 @@ export declare class GyroViewElement extends TypedEventElement implements LiveSe
 	 * Where the normal view looks: yaw and pitch in degrees, and the horizontal field of view.
 	 */
 	get view(): ViewAngles;
+	/**
+	 * Whether turning the device turns the normal view: `on`, `off`, or `unavailable` where the
+	 * device reports no attitude or access was refused.
+	 */
+	get motionLook(): MotionLookState;
 	/**
 	 * Every word the element shows or says to assistive technology. Setting it replaces any of
 	 * them, table by table (`labels`, `stabilizationModes`, `viewModes`, `errors`); the others keep
@@ -949,6 +980,16 @@ export declare class GyroViewElement extends TypedEventElement implements LiveSe
 	 * when none is given.
 	 */
 	zoom(steps: number, focus?: ScreenPoint): void;
+	/**
+	 * Lets the device turn the normal view, as a window into the recording. Call it from a tap's
+	 * handler: iOS asks the viewer for access there and refuses it anywhere else. Resolves with the
+	 * state it ends in (`motionLook`); a refusal is a `warning`, never a rejection.
+	 */
+	startMotionLook(): Promise<MotionLookState>;
+	/**
+	 * Gives the view back to the pointer, level, looking where it looked.
+	 */
+	stopMotionLook(): void;
 	/**
 	 * Stabilizes the picture in `mode` (`off`, `lock`, `horizon`, `follow`); any other value,
 	 * an unset one included, is refused.
@@ -979,6 +1020,12 @@ export declare class GyroViewElement extends TypedEventElement implements LiveSe
 	 * Plays local files instead of the `src` attributes, until `src` or `src2` change.
 	 */
 	loadFiles(files: FileSource): void;
+	/**
+	 * A move within the document disconnects and connects again at once: only an element still out
+	 * of it a microtask later was removed. It lets its recording go, and leaves the pinned fill as
+	 * the browser's fullscreen element leaves fullscreen.
+	 */
+	private leaveIfRemoved;
 	/**
 	 * What the controls and the keyboard ask of the element. They live as long as the element:
 	 * their listeners sit on its own shadow tree and host, and on its player.

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

@@ -1,4 +1,4 @@
-import { DEFAULT_VIEW, isSameView } from "./ViewState.js";
+import { DEFAULT_VIEW, clampView, isSameView } from "./ViewState.js";
 import { FITTED, isSameMagnification } from "./magnification.js";
 //#region ../../packages/core/src/domain/view/Framing.ts
 var DEFAULT_FRAMING = {
@@ -19,6 +19,12 @@ function withView(framing, view) {
 	};
 }
 /**
+* The framing with a page's view taken as it is given, within the sphere.
+*/
+function withPlacedView(framing, view) {
+	return withView(framing, clampView(view));
+}
+/**
 * The framing with the lens tiles' magnification replaced, the other parts kept.
 */
 function withLenses(framing, lenses) {
@@ -28,4 +34,4 @@ function withLenses(framing, lenses) {
 	};
 }
 //#endregion
-export { DEFAULT_FRAMING, isSameFraming, withLenses, withView };
+export { DEFAULT_FRAMING, isSameFraming, withLenses, withPlacedView, withView };

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

@@ -1,7 +1,7 @@
 import { degrees, degreesToRadians, wrapHalfTurn } from "../../shared/units/angle.js";
 import { ensureInvariant } from "../../shared/errors/GyroViewError.js";
 import { clamp } from "../../shared/math/clamp.js";
-import { multiplyMatrices, rotationAboutX, rotationAboutY } from "../../shared/math/Matrix3.js";
+import { multiplyMatrices, rotationAboutX, rotationAboutY, rotationAboutZ } from "../../shared/math/Matrix3.js";
 //#region ../../packages/core/src/domain/view/ViewState.ts
 /**
 * From a short telephoto to a wide angle: past 120 degrees a rectilinear view stretches its
@@ -14,35 +14,40 @@ var MAX_PITCH_DEGREES = 90;
 var DEFAULT_VIEW = {
 	yaw: degrees(0),
 	pitch: degrees(0),
+	roll: degrees(0),
 	fieldOfView: degrees(DEFAULT_FIELD_OF_VIEW_DEGREES)
 };
 /**
-* Keeps the view inside the sphere: yaw wrapped to (-180, 180], pitch within the poles, field
-* of view within its bounds. Non-finite angles are a programming error.
+* Keeps the view inside the sphere: yaw and roll wrapped to (-180, 180], pitch within the poles,
+* field of view within its bounds. Non-finite angles are a programming error.
 */
 function clampView(view) {
 	ensureInvariant([
 		view.yaw,
 		view.pitch,
+		view.roll,
 		view.fieldOfView
 	].every((angle) => Number.isFinite(angle)), "view angles must be finite");
 	return {
 		...view,
 		yaw: wrapHalfTurn(view.yaw),
+		roll: wrapHalfTurn(view.roll),
 		pitch: degrees(clamp(view.pitch, -90, MAX_PITCH_DEGREES)),
 		fieldOfView: degrees(clamp(view.fieldOfView, NARROWEST_DEGREES, WIDEST_DEGREES))
 	};
 }
 function isSameView(a, b) {
-	return a.yaw === b.yaw && a.pitch === b.pitch && a.fieldOfView === b.fieldOfView;
+	return a.yaw === b.yaw && a.pitch === b.pitch && a.roll === b.roll && a.fieldOfView === b.fieldOfView;
 }
 /**
-* Turns view-space directions (z forward) into camera body directions: pitch about the body's
-* lateral axis first, then yaw about its vertical axis. Body y points down, so a positive
-* rotation about x tilts the forward direction upwards.
+* Turns view-space directions (x right, y down, z forward) into camera body directions: roll
+* about the line of sight first, then pitch about the body's lateral axis, then yaw about its
+* vertical axis. Body y points down, so a positive rotation about x tilts the forward direction
+* upwards, and one about z turns the screen's right toward its bottom: clockwise.
 */
 function viewRotation(view) {
-	return multiplyMatrices(rotationAboutY(degreesToRadians(view.yaw)), rotationAboutX(degreesToRadians(view.pitch)));
+	const pointed = multiplyMatrices(rotationAboutY(degreesToRadians(view.yaw)), rotationAboutX(degreesToRadians(view.pitch)));
+	return multiplyMatrices(pointed, rotationAboutZ(degreesToRadians(view.roll)));
 }
 //#endregion
 export { DEFAULT_VIEW, clampView, isSameView, viewRotation };

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

@@ -1,6 +1,6 @@
 import { aspectOf, boundsOf, lensTiles, shiftOf } from "./screenLayout.js";
 import { FITTED, clampMagnification, magnifiedArea, magnifyAt, panMagnification } from "./magnification.js";
-import { withLenses } from "./Framing.js";
+import { withLenses, withPlacedView } from "./Framing.js";
 //#region ../../packages/core/src/domain/view/lensTilesView.ts
 /**
 * An arrow's angle moves zoomed tiles as a drag across the viewport would move them, a 90-degree
@@ -54,6 +54,7 @@ var LENS_TILES_VIEW = {
 	turn: turnLenses,
 	zoom: (framing, zoom, context) => withLenses(framing, magnifyAt(fittedTiles(context).bounds, framing.lenses, zoom)),
 	reset: (framing) => withLenses(framing, FITTED),
+	place: withPlacedView,
 	picture: (framing, context) => ({
 		kind: "lens-tiles",
 		tiles: magnifiedTiles(framing, context)

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

@@ -0,0 +1,103 @@
+import { degrees, degreesToRadians, wrapHalfTurn } from "../../shared/units/angle.js";
+import { milliseconds } from "../../shared/units/time.js";
+import { angleBetweenRotations } from "../../shared/math/Matrix3.js";
+import { DEFAULT_VIEW, clampView, viewRotation } from "./ViewState.js";
+import { SCREEN_CENTRE, aspectOf } from "./screenLayout.js";
+import { lookAt, panView, zoomViewAt } from "./viewGestures.js";
+import { withView } from "./Framing.js";
+import { rectilinearPicture } from "./normalView.js";
+//#region ../../packages/core/src/domain/view/motionLookView.ts
+var READING_GAP = milliseconds(500);
+var UNSEEN_TURN = degreesToRadians(degrees(.01));
+/**
+* Where a reading turns a view the device holds. The yaw only turns by as much as the device
+* turned since the reading it continues, so a drag, Reset view or a page's yaw move the heading
+* and the device carries on from there; after a gap, and at the first reading, the yaw stays.
+* The pitch and roll are the device's, level with the real horizon. A turn too small to see
+* leaves the view as it is and keeps counting from the look last shown, at the new reading's
+* time: a phone at rest draws nothing, and a slow drift lands in full once it shows.
+*/
+function followReading(view, previous, reading) {
+	const { pitch, roll } = reading.look;
+	if (!isOneMovement(previous, reading)) return {
+		view: clampView({
+			...view,
+			pitch,
+			roll
+		}),
+		reading
+	};
+	const yaw = degrees(view.yaw + wrapHalfTurn(degrees(reading.look.yaw - previous.look.yaw)));
+	const turned = clampView({
+		...view,
+		yaw,
+		pitch,
+		roll
+	});
+	return isUnseenTurn(view, turned) ? {
+		view,
+		reading: {
+			look: previous.look,
+			at: reading.at
+		}
+	} : {
+		view: turned,
+		reading
+	};
+}
+function isOneMovement(previous, reading) {
+	return previous !== void 0 && reading.at - previous.at <= READING_GAP;
+}
+function isUnseenTurn(view, turned) {
+	return angleBetweenRotations(viewRotation(view), viewRotation(turned)) < UNSEEN_TURN;
+}
+/**
+* The view once the device lets go of it: level, looking where it looked.
+*/
+function withoutRoll(view) {
+	return {
+		...view,
+		roll: degrees(0)
+	};
+}
+/**
+* The normal view while the device holds it (ADR 0040): the device gives the pitch and the roll,
+* so drags and the arrows turn the heading alone, a zoom narrows about the centre, and a page's
+* view sets the heading and the zoom.
+*/
+var MOTION_LOOK_VIEW = {
+	isStabilized: true,
+	canPan: () => true,
+	pan: (framing, delta, { viewport }) => withView(framing, panView(framing.view, {
+		x: delta.x,
+		y: 0
+	}, viewport.width)),
+	turn: (framing, turn) => {
+		const { view } = framing;
+		return withView(framing, lookAt(view, degrees(view.yaw + turn.yaw), view.pitch));
+	},
+	zoom: (framing, zoom, { viewport }) => withView(framing, zoomViewAt(framing.view, {
+		steps: zoom.steps,
+		focus: SCREEN_CENTRE
+	}, aspectOf(viewport))),
+	reset: (framing) => withHeading(framing, {
+		...framing.view,
+		yaw: degrees(0),
+		fieldOfView: DEFAULT_VIEW.fieldOfView
+	}),
+	place: withHeading,
+	picture: rectilinearPicture
+};
+/**
+* The held view with the yaw and field of view of `view`, the device's pitch and roll kept.
+*/
+function withHeading(framing, view) {
+	const { yaw, fieldOfView } = view;
+	return withView(framing, clampView({
+		...framing.view,
+		yaw,
+		fieldOfView
+	}));
+}
+//#endregion
+export { MOTION_LOOK_VIEW, followReading, withoutRoll };

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

@@ -2,7 +2,7 @@ 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";
+import { withPlacedView, 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
@@ -18,12 +18,19 @@ var NORMAL_VIEW = {
 	},
 	zoom: (framing, zoom, { viewport }) => withView(framing, zoomViewAt(framing.view, zoom, aspectOf(viewport))),
 	reset: (framing) => withView(framing, DEFAULT_VIEW),
-	picture: ({ view }) => ({
+	place: withPlacedView,
+	picture: rectilinearPicture
+};
+/**
+* The view's rectilinear picture over the whole viewport, turned by its whole rotation.
+*/
+function rectilinearPicture({ view }) {
+	return {
 		kind: "rectilinear",
 		rotation: viewRotation(view),
 		fieldOfView: view.fieldOfView,
 		area: WHOLE_SCREEN
-	})
-};
+	};
+}
 //#endregion
-export { NORMAL_VIEW };
+export { NORMAL_VIEW, rectilinearPicture };

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

@@ -3,7 +3,7 @@ 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";
+import { withPlacedView, 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.
@@ -86,6 +86,7 @@ var PANORAMA_VIEW = {
 		...withView(framing, lookAt(framing.view, degrees(0), framing.view.pitch)),
 		panorama: FITTED
 	}),
+	place: withPlacedView,
 	picture: (framing, context) => {
 		const { fitted, panorama } = shownPanorama(framing, context);
 		return {

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

@@ -0,0 +1,74 @@
+import { degrees, degreesToRadians, radians, radiansToDegrees } from "../../shared/units/angle.js";
+import { clamp } from "../../shared/math/clamp.js";
+import { multiplyMatrices, rotationAboutX, rotationAboutY, rotationAboutZ } from "../../shared/math/Matrix3.js";
+//#region ../../packages/core/src/domain/view/screenLook.ts
+/**
+* View space (x right, y down, z into the screen) into the screen's frame (x right, y up, z out
+* of the screen): the viewer looks through the screen, out of its back.
+*/
+var VIEW_TO_SCREEN = [
+	1,
+	0,
+	0,
+	0,
+	-1,
+	0,
+	0,
+	0,
+	-1
+];
+/**
+* The browser's world (x east, y north, z up) into the view's (x right, y down, z forward), north
+* standing for forward: the yaw only counts changes, so any horizontal direction would do.
+*/
+var WORLD_TO_VIEW = [
+	1,
+	0,
+	0,
+	0,
+	0,
+	-1,
+	0,
+	1,
+	0
+];
+/**
+* Below this cosine of the pitch the screen looks straight up or down, where only the sum or the
+* difference of yaw and roll is defined, and each one alone would be read from rounding noise:
+* the look then takes the turn as yaw alone, within a millionth of a radian of the screen.
+*/
+var POLE_COSINE = 1e-6;
+/**
+* The rotation that turns view-space directions into the view's world for a device held this
+* way, as `viewRotation` turns them for a view.
+*/
+function screenRotationOf(attitude) {
+	const device = multiplyMatrices(multiplyMatrices(rotationAbout(rotationAboutZ, attitude.alpha), rotationAbout(rotationAboutX, attitude.beta)), rotationAbout(rotationAboutY, attitude.gamma));
+	const screen = multiplyMatrices(rotationAbout(rotationAboutZ, degrees(-attitude.screenAngle)), VIEW_TO_SCREEN);
+	return multiplyMatrices(multiplyMatrices(WORLD_TO_VIEW, device), screen);
+}
+/**
+* The yaw, pitch and roll whose `viewRotation` is the screen's rotation: the rotation
+* `Ry(yaw) Rx(pitch) Rz(roll)` read back from its entries.
+*/
+function screenLookOf(attitude) {
+	const [m00, , m02, m10, m11, m12, m20, , m22] = screenRotationOf(attitude);
+	const pitch = angleOf(Math.asin(-clamp(m12, -1, 1)));
+	return Math.hypot(m10, m11) < POLE_COSINE ? {
+		yaw: angleOf(Math.atan2(-m20, m00)),
+		pitch,
+		roll: degrees(0)
+	} : {
+		yaw: angleOf(Math.atan2(m02, m22)),
+		pitch,
+		roll: angleOf(Math.atan2(m10, m11))
+	};
+}
+function rotationAbout(rotation, angle) {
+	return rotation(degreesToRadians(angle));
+}
+function angleOf(value) {
+	return radiansToDegrees(radians(value));
+}
+//#endregion
+export { screenLookOf, screenRotationOf };

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

@@ -1,5 +1,6 @@
 import { LENS_TILES_VIEW } from "./lensTilesView.js";
 import { NORMAL_VIEW } from "./normalView.js";
+import { MOTION_LOOK_VIEW } from "./motionLookView.js";
 import { PANORAMA_VIEW } from "./panoramaView.js";
 //#region ../../packages/core/src/domain/view/viewModes.ts
 var RULES = {
@@ -10,5 +11,21 @@ var RULES = {
 function viewModeRulesFor(mode) {
 	return RULES[mode];
 }
+/**
+* Motion look turns the normal view alone: the flat pictures show the whole sphere or the raw
+* lenses, which a phone held up as a window has nothing to turn.
+*/
+var MOTION_LOOK_RULES = {
+	normal: MOTION_LOOK_VIEW,
+	equirectangular: void 0,
+	"raw-lenses": void 0
+};
+/**
+* The rules of a mode while the device holds the view, or none for a mode the device does not
+* turn.
+*/
+function motionLookRulesFor(mode) {
+	return MOTION_LOOK_RULES[mode];
+}
 //#endregion
-export { viewModeRulesFor };
+export { motionLookRulesFor, viewModeRulesFor };

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

@@ -33,7 +33,7 @@ import { DEFAULT_STABILIZATION_MODE, STABILIZATION_MODES } from "./domain/motion
 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 "./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";
@@ -41,7 +41,9 @@ 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 { followReading, withoutRoll } from "./domain/view/motionLookView.js";
+import { motionLookRulesFor, viewModeRulesFor } from "./domain/view/viewModes.js";
+import { screenLookOf } from "./domain/view/screenLook.js";
 import "./domain/stitching/seamRing.js";
 import { buildStitchingSetup, lensFrameOrder } from "./domain/stitching/StitchingSetup.js";
 import { StabilizingFrameSink } from "./application/stabilization/StabilizingFrameSink.js";
@@ -71,4 +73,4 @@ 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 { BT709_LUMINANCE, ByteRange, COLOUR_PRIMARIES, DEFAULT_FRAMING, DEFAULT_PICTURE_QUALITY, DEFAULT_STABILIZATION_MODE, DEFAULT_VIEW_MODE, Deferred, Ending, GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GainMatchingFrameSink, GyroViewError, HLG_OETF, IDENTITY_MATRIX3, ITERATION_END, MATRIX_COEFFICIENTS, MEI_TERM_CAPACITY, Outbox, PICTURE_QUALITIES, PlaybackSession, RecordingBuffer, RunStop, SCREEN_CENTRE, STABILIZATION_MODES, STOPPED, SourceByteStream, StabilizingFrameSink, TRANSFER_CHARACTERISTICS, TypedEmitter, UPRIGHT_MOUNTING, VIEW_MODES, WallClock, asGyroViewError, aspectOf, aspectOfArea, buildStitchingSetup, clamp, clampView, degrees, detectLensLayout, displayConversionsOf, downloadPolicyFor, ensureIndexInRange, ensureInvariant, fileNameOfUrl, hasErrorCode, hevcCodecStringOf, inspectRecording, isAbortError, isFlowing, isGyroViewErrorCode, isSameFraming, isSameView, keysOf, lazy, lensFrameOrder, locateOtherLensFile, lookAt, matrixCorrectionOf, messageOf, microseconds, microsecondsToSeconds, milliseconds, namedOrUnspecified, pixelRatioCapOf, planeHalfExtentOf, probeDecoding, readRecording, readSampleTable, seconds, secondsToMicroseconds, stabilizerFor, startFileDownload, timeRecording, viewModeRulesFor, zoomStepsForPinch };
+export { BT709_LUMINANCE, ByteRange, COLOUR_PRIMARIES, DEFAULT_FRAMING, DEFAULT_PICTURE_QUALITY, DEFAULT_STABILIZATION_MODE, DEFAULT_VIEW_MODE, Deferred, Ending, GYRO_VIEW_ERROR_CATEGORIES, GYRO_VIEW_ERROR_CODES, GainMatchingFrameSink, GyroViewError, HLG_OETF, IDENTITY_MATRIX3, ITERATION_END, MATRIX_COEFFICIENTS, MEI_TERM_CAPACITY, Outbox, PICTURE_QUALITIES, PlaybackSession, RecordingBuffer, RunStop, SCREEN_CENTRE, STABILIZATION_MODES, STOPPED, SourceByteStream, StabilizingFrameSink, TRANSFER_CHARACTERISTICS, TypedEmitter, UPRIGHT_MOUNTING, VIEW_MODES, WallClock, asGyroViewError, aspectOf, aspectOfArea, buildStitchingSetup, clamp, degrees, detectLensLayout, displayConversionsOf, downloadPolicyFor, ensureIndexInRange, ensureInvariant, fileNameOfUrl, followReading, hasErrorCode, hevcCodecStringOf, inspectRecording, isAbortError, isFlowing, isGyroViewErrorCode, isSameFraming, keysOf, lazy, lensFrameOrder, locateOtherLensFile, lookAt, matrixCorrectionOf, messageOf, microseconds, microsecondsToSeconds, milliseconds, motionLookRulesFor, namedOrUnspecified, pixelRatioCapOf, planeHalfExtentOf, probeDecoding, readRecording, readSampleTable, screenLookOf, seconds, secondsToMicroseconds, stabilizerFor, startFileDownload, timeRecording, viewModeRulesFor, withoutRoll, zoomStepsForPinch };

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

@@ -1,3 +1,5 @@
+import { radians } from "../units/angle.js";
+import { clamp } from "./clamp.js";
 //#region ../../packages/core/src/shared/math/Matrix3.ts
 var IDENTITY_MATRIX3 = [
 	1,
@@ -106,5 +108,14 @@ 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);
 }
+/**
+* How far rotation `b` turns from rotation `a`: the angle of `aᵀ b`, from its trace
+* (`1 + 2 cos θ`), which is the sum of the two matrices' entrywise products; clamped against
+* rounding.
+*/
+function angleBetweenRotations(a, b) {
+	const trace = a.reduce((sum, entry, index) => sum + entry * (b[index] ?? 0), 0);
+	return radians(Math.acos(clamp((trace - 1) / 2, -1, 1)));
+}
 //#endregion
-export { IDENTITY_MATRIX3, determinantOf, multiplyMatrices, rotationAboutX, rotationAboutY, rotationAboutZ, transformVector, transposeMatrix };
+export { IDENTITY_MATRIX3, angleBetweenRotations, determinantOf, multiplyMatrices, rotationAboutX, rotationAboutY, rotationAboutZ, transformVector, transposeMatrix };