@johnmorrisdotca/uchusen-rockets 0.1.0 → 0.2.1

package/dist/element/scene.js

@@ -7,8 +7,9 @@ import { LineMaterial } from "three/addons/lines/LineMaterial.js";
 import { LineSegments2 } from "three/addons/lines/LineSegments2.js";
 import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry.js";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
-import { FOV_DEG, frameFor, PICTURE_H } from "../framing.js";
+import { directionOf, FOV_DEG, frameFor, PICTURE_H, turnedBy } from "../framing.js";
 import { LOOKS } from "../looks.js";
+import { pixelRatioFor } from "../pixels.js";
 import { MATERIALS } from "../model/materials.js";
 import { paintGlow, paintSky, paintSteel, paintTiles } from "./paint.js";
 const IDLE_STOP_MS = 90_000;
@@ -69,7 +70,11 @@ void main() {
   gl_FragColor = vec4(color, 1.0);
   #include <colorspace_fragment>
 }`;
+/** The materials of an engine's bell, in this package's own meshes. */
+const NOZZLE_MATERIALS = new Set(["bell", "bell-inside", "engine-metal"]);
 const asVec = (v) => [v.x, v.y, v.z];
+/** The pictures a licensed model's material may hold (the shared sky it reflects is not one of them). */
+const MODEL_PICTURES = ["map", "normalMap", "roughnessMap", "metalnessMap", "aoMap", "emissiveMap"];
 export class RocketViewer {
     canvas;
     frames = 0;
@@ -99,13 +104,15 @@ export class RocketViewer {
     needsDraw = true;
     pose = null;
     tilt = { azimuth: 0, polar: 0, applied: { azimuth: 0, polar: 0 } };
+    driven = null;
+    drivenDirty = false;
+    lastDistance = 0;
     resize;
     disposed = false;
     constructor(holder, options) {
         this.holder = holder;
         this.options = options;
         this.renderer = new WebGLRenderer({ antialias: true, alpha: true, powerPreference: "low-power" });
-        this.renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
         this.renderer.outputColorSpace = SRGBColorSpace;
         this.renderer.toneMapping = ACESFilmicToneMapping;
         this.renderer.toneMappingExposure = 1;
@@ -162,7 +169,10 @@ export class RocketViewer {
         this.canvas.addEventListener("focus", () => (this.controls.enableZoom = true));
         this.canvas.addEventListener("blur", () => (this.controls.enableZoom = false));
         this.canvas.addEventListener("pointerdown", () => this.canvas.focus({ preventScroll: true }));
-        this.canvas.addEventListener("dblclick", () => this.setAngle(this.homeAngle, true));
+        this.canvas.addEventListener("dblclick", () => {
+            if (!this.driven)
+                this.setAngle(this.homeAngle, true);
+        });
         this.canvas.addEventListener("keydown", (event) => this.key(event));
         document.addEventListener("visibilitychange", this.onVisibility);
         this.resize = new ResizeObserver(() => this.fit());
@@ -180,9 +190,7 @@ export class RocketViewer {
         const gltf = await new GLTFLoader().parseAsync(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength), "");
         if (this.disposed || generation !== this.generation)
             return;
-        for (const part of this.parts)
-            part.holder.removeFromParent();
-        this.disposeTree(this.root);
+        this.disposeParts();
         this.root.clear();
         this.parts = [];
         this.built = built;
@@ -202,7 +210,9 @@ export class RocketViewer {
                 code,
                 model: null,
                 modelFile: part.record.painted?.file ?? null,
+                ownNozzle: Boolean(part.record.painted?.ownNozzle),
                 modelState: "none",
+                nozzleShown: false,
                 faces: [],
                 outlines: [],
                 feature: [],
@@ -223,6 +233,7 @@ export class RocketViewer {
         this.frameTo(angle ?? this.currentAngle(), false);
         this.canvas.dataset.ready = "true";
         this.canvas.dataset.parts = this.parts.map((part) => part.slot).join(" ");
+        this.drivenDirty = this.driven !== null;
         this.wake();
     }
     /** Moves the parts from the packed nodes into `into`, keeping each mesh's own placement. */
@@ -394,7 +405,7 @@ export class RocketViewer {
             return;
         if (part.model) {
             part.model.visible = painted;
-            part.code.visible = !painted;
+            this.showCode(part, painted);
             return;
         }
         part.code.visible = true;
@@ -430,11 +441,26 @@ export class RocketViewer {
             this.reportPainted();
         });
     }
+    /** Behind a licensed model this package's code shows nothing, except the nozzle the model lacks, and not while the stage is nested in the one below. */
+    showCode(part, painted) {
+        const nozzleOnly = painted && part.ownNozzle;
+        part.code.visible = !painted || nozzleOnly;
+        const nozzle = nozzleOnly && this.show !== "together";
+        for (const { mesh, name } of part.faces)
+            mesh.visible = !nozzleOnly || (nozzle && NOZZLE_MATERIALS.has(name));
+        for (const lines of [...part.feature, ...part.weld])
+            lines.visible = !nozzleOnly;
+        part.nozzleShown = nozzle;
+        this.canvas.dataset.nozzle = this.parts.some((one) => one.nozzleShown) ? "own" : "";
+    }
     /** Together, apart, or one part alone: an animated move, or a cut under reduced motion. */
     setShow(show) {
         if (!this.built || show === this.show)
             return;
         this.show = show;
+        for (const part of this.parts)
+            if (part.model)
+                this.showCode(part, this.look === "painted");
         const places = this.built.placesOf(show);
         const fromAngle = this.currentAngle();
         const framing = this.framingFor(fromAngle);
@@ -541,6 +567,11 @@ export class RocketViewer {
     setAngle(angle, animate) {
         if (!this.built)
             return;
+        if (this.driven) {
+            this.homeAngle = angle;
+            this.syncDriven();
+            return;
+        }
         this.controls.autoRotate = false;
         const framing = this.framingFor(angle);
         if (animate && !this.options.reducedMotion)
@@ -572,10 +603,65 @@ export class RocketViewer {
     }
     setSpin(spin) {
         this.controls.autoRotateSpeed = autoRotateOf(spin);
-        this.controls.autoRotate = !this.options.reducedMotion && spin.seconds > 0;
+        this.controls.autoRotate = !this.driven && !this.options.reducedMotion && spin.seconds > 0;
         this.canvas.dataset.spin = `${spin.seconds}${spin.way}`;
         this.wake();
     }
+    /** Hands the turn, tip, zoom and pan to the page, as the family's view controls report them: this view's own hands (drag, wheel, keys, spin) stand down, and the camera is the chosen view's angle turned and tipped by them. `null` takes them back. */
+    drive(choice) {
+        const same = choice !== null && this.driven !== null && Object.keys(choice).every((key) => choice[key] === this.driven?.[key]);
+        if (same)
+            return;
+        this.driven = choice;
+        this.controls.enabled = choice === null;
+        if (choice)
+            this.controls.autoRotate = false;
+        this.canvas.style.touchAction = choice ? "auto" : "pan-y";
+        this.syncDriven();
+    }
+    /** The camera is put where the choice says at once, seen or not, so a page that asks where it looks from is told the truth; a move between parts moves it by itself. */
+    syncDriven() {
+        this.drivenDirty = false;
+        this.lens();
+        if (!this.pose)
+            this.applyDriven();
+        this.needsDraw = true;
+        this.wake();
+    }
+    drivenAngle() {
+        if (!this.driven)
+            return null;
+        const turned = turnedBy(this.homeAngle, this.driven.yaw, this.driven.tilt);
+        const lean = this.tilt.applied;
+        return { az: turned.az + MathUtils.radToDeg(lean.azimuth), el: MathUtils.clamp(turned.el - MathUtils.radToDeg(lean.polar), -87, 87) };
+    }
+    /** The camera stands where the view's angle, turned and tipped, puts it, as far off as the whole rocket needs from the view's own angle, so turning never makes it breathe. */
+    applyDriven() {
+        const angle = this.drivenAngle();
+        if (!angle || !this.built)
+            return;
+        const framing = this.framingFor(this.homeAngle);
+        const direction = directionOf(angle);
+        this.camera.position.set(framing.target[0] + direction[0] * framing.distance, framing.target[1] + direction[1] * framing.distance, framing.target[2] + direction[2] * framing.distance);
+        this.controls.target.set(...framing.target);
+        if (Math.abs(framing.distance - this.lastDistance) > 1e-6) {
+            this.lastDistance = framing.distance;
+            this.limits(framing.distance);
+        }
+        this.controls.update();
+    }
+    /** Zoom is the camera's, and the pan moves the picture by pixels, so the view stays sharp at any zoom. */
+    lens() {
+        const { zoom = 1, panX = 0, panY = 0 } = this.driven ?? {};
+        const w = Math.max(1, this.holder.clientWidth);
+        const h = Math.max(1, this.holder.clientHeight);
+        this.camera.zoom = zoom;
+        if (panX !== 0 || panY !== 0)
+            this.camera.setViewOffset(w, h, -panX, -panY, w, h);
+        else
+            this.camera.clearViewOffset();
+        this.camera.updateProjectionMatrix();
+    }
     setTilt(azimuthDeg, polarDeg) {
         this.tilt.azimuth = MathUtils.degToRad(MathUtils.clamp(azimuthDeg, -25, 25));
         this.tilt.polar = MathUtils.degToRad(MathUtils.clamp(polarDeg, -12, 12));
@@ -587,7 +673,9 @@ export class RocketViewer {
         document.removeEventListener("visibilitychange", this.onVisibility);
         this.resize.disconnect();
         this.controls.dispose();
-        this.disposeTree(this.root);
+        this.disposeParts();
+        this.glow?.geometry.dispose();
+        this.glow?.material?.dispose();
         for (const material of this.materialCache.values())
             material.dispose();
         this.outlineMaterial.dispose();
@@ -598,13 +686,25 @@ export class RocketViewer {
         this.renderer.forceContextLoss();
         this.canvas.remove();
     }
-    disposeTree(tree) {
-        tree.traverse((node) => {
-            const geometry = node.geometry;
-            geometry?.dispose();
-            if (node instanceof LineSegments2)
-                node.material.dispose();
-        });
+    /** Lets the graphics card have back what the parts took: geometries, the thick lines' materials and a licensed model's own materials and pictures. */
+    disposeParts() {
+        for (const part of this.parts) {
+            part.holder.traverse((node) => {
+                node.geometry?.dispose();
+                if (node instanceof LineSegments2)
+                    node.material.dispose();
+            });
+            part.model?.traverse((node) => {
+                if (!(node instanceof Mesh))
+                    return;
+                for (const material of Array.isArray(node.material) ? node.material : [node.material]) {
+                    for (const slot of MODEL_PICTURES)
+                        material[slot]?.dispose();
+                    material.dispose();
+                }
+            });
+            part.holder.removeFromParent();
+        }
     }
     addGlow() {
         if (!this.built || this.glow)
@@ -654,11 +754,21 @@ export class RocketViewer {
         const dA = (t.azimuth - t.applied.azimuth) * 0.12;
         const dP = (t.polar - t.applied.polar) * 0.12;
         if (Math.abs(dA) > 1e-5 || Math.abs(dP) > 1e-5) {
-            this.orbit(dA, dP);
+            if (this.driven)
+                this.drivenDirty = true;
+            else
+                this.orbit(dA, dP);
             t.applied.azimuth += dA;
             t.applied.polar += dP;
             this.needsDraw = true;
         }
+        if (this.drivenDirty) {
+            this.drivenDirty = false;
+            this.lens();
+            if (!this.pose)
+                this.applyDriven();
+            this.needsDraw = true;
+        }
         if (this.pose) {
             const { from, to, start, ms, moveParts } = this.pose;
             const k = Math.min(1, (performance.now() - start) / ms);
@@ -673,6 +783,9 @@ export class RocketViewer {
             while (dTheta < -Math.PI)
                 dTheta += 2 * Math.PI;
             const s = new Spherical(MathUtils.lerp(a.radius, b.radius, e), MathUtils.lerp(a.phi, b.phi, e), a.theta + dTheta * e);
+            const aim = this.drivenAngle();
+            if (aim)
+                s.setFromVector3(new Vector3(...directionOf(aim)).setLength(s.radius));
             this.camera.position.copy(this.controls.target).add(new Vector3().setFromSpherical(s));
             if (moveParts)
                 for (const part of this.parts) {
@@ -686,6 +799,7 @@ export class RocketViewer {
                 this.pose = null;
                 if (done)
                     this.finishParts();
+                this.drivenDirty = this.driven !== null;
             }
         }
         if (!ambient)
@@ -701,10 +815,15 @@ export class RocketViewer {
             this.canvas.dataset.azimuth = angle.az.toFixed(2);
             this.canvas.dataset.elevation = angle.el.toFixed(2);
             this.canvas.dataset.moving = this.pose ? "true" : "false";
+            if (this.driven) {
+                this.canvas.dataset.zoom = this.driven.zoom.toFixed(2);
+                this.canvas.dataset.pan = `${Math.round(this.driven.panX)},${Math.round(this.driven.panY)}`;
+            }
             if (this.glow)
                 this.glow.visible = this.look !== "painted" && this.camera.position.y > 0;
         }
-        if ((ambient && this.controls.autoRotate) || changed || this.pose || this.needsDraw || Math.abs(dA) > 1e-5)
+        // the controls' own change event may already have asked for the next frame (wake): one frame is asked for, never two, or each frame would double the next
+        if (!this.frame && ((ambient && this.controls.autoRotate) || changed || this.pose || this.needsDraw || Math.abs(dA) > 1e-5))
             this.frame = requestAnimationFrame(this.tick);
     };
     syncSizes() {
@@ -714,9 +833,11 @@ export class RocketViewer {
     fit() {
         const w = Math.max(1, this.holder.clientWidth);
         const h = Math.max(1, this.holder.clientHeight);
+        this.renderer.setPixelRatio(pixelRatioFor(w, h, window.devicePixelRatio));
         this.renderer.setSize(w, h, false);
+        this.outlineMaterial.uniforms.width.value = LOOKS[this.look].outlinePx * this.renderer.getPixelRatio();
         this.camera.aspect = w / h;
-        this.camera.updateProjectionMatrix();
+        this.lens();
         this.syncSizes();
         if (this.built && !this.pose)
             this.applyFraming(this.framingFor(this.currentAngle()));
@@ -730,6 +851,8 @@ export class RocketViewer {
         this.camera.position.copy(this.controls.target).add(new Vector3().setFromSpherical(s));
     }
     key(event) {
+        if (this.driven)
+            return;
         const step = MathUtils.degToRad(15);
         const moves = {
             ArrowLeft: () => this.orbit(-step, 0),

package/dist/element.d.ts

@@ -1,5 +1,5 @@
 import type { Description, FitReport } from "./fit.ts";
-import { type Angle } from "./framing.ts";
+import { type Angle, type ViewChoice } from "./framing.ts";
 import { ROCKETS } from "./rockets.ts";
 export type RocketState = "picture" | "loading" | "3d" | "fallback" | "error";
 declare const HTMLBase: typeof HTMLElement;
@@ -13,7 +13,6 @@ export declare class UchusenRocket extends HTMLBase {
     private drawing;
     private viewer;
     private watch;
-    private cleanups;
     private releaseTimer;
     private revealTimer;
     private generation;
@@ -23,6 +22,13 @@ export declare class UchusenRocket extends HTMLBase {
     private shownAt;
     private starting;
     private key;
+    private driven;
+    private placeFrame;
+    private placedAt;
+    private stale;
+    private onScreen;
+    private drawn;
+    private tiltCleanups;
     /** What is showing now. */
     get state(): RocketState;
     /** What the fit check said about what is showing: its label, parts and credits. */
@@ -32,6 +38,11 @@ export declare class UchusenRocket extends HTMLBase {
     set description(value: Description | null);
     /** Where the camera is looking from, while there is a 3D view. */
     get angle(): Angle | null;
+    /** Lets a page choose the turn, tip, zoom and pan, as the family's `<kazoku-view-controls>` reports them in `kazoku-viewchange` (`element.drive(event.detail)`): the element's own drag, wheel, keys and spin stand down, and the 3D view and the drawing both follow. `null` takes them back. */
+    drive(choice: Partial<ViewChoice> | null): void;
+    /** The drawing, turned and moved to the chosen view. The 3D view moves itself, so only the drawing needs it, and only until the 3D view shows. It is drawn at most about 20 times a second and never while out of sight: it is made again when it comes back. */
+    private place;
+    private seen;
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, before: string | null, after: string | null): void;
@@ -45,13 +56,14 @@ export declare class UchusenRocket extends HTMLBase {
     private settings;
     private update;
     private renderShell;
-    /** The drawing for what the attributes say now. It is made from code, so it needs no file. */
+    /** The drawing for what the attributes say now. It is made from code, so it needs no file. A zoom or a move only changes which part of it the box shows (its viewBox), so the drawing is as sharp as the box and never grows past it. */
     private redraw;
     private mark;
     private applyRocket;
     private lastView;
     private applySettings;
     private startWatching;
+    private stopTilt;
     private fallBack;
     private start;
     private startTilt;

package/dist/element.js

@@ -4,7 +4,7 @@
 import { build, FitError } from "./build/index.js";
 import { lineupSvg } from "./build/lineup.js";
 import { CROSSFADE_MS, REDUCED_FADE_MS, revealDelay } from "./crossfade.js";
-import { cleanView, VIEWS } from "./framing.js";
+import { cleanView, turnedBy, VIEWS } from "./framing.js";
 import { cleanShow } from "./layout.js";
 import { cleanLook } from "./looks.js";
 import { ROCKETS } from "./rockets.js";
@@ -14,6 +14,8 @@ const HTMLBase = typeof HTMLElement === "undefined" ? class {
 /** A view out of sight keeps its WebGL canvas this long before letting it go (a browser allows only a few at a time). */
 const RELEASE_MS = 30_000;
 const DEFAULT_SPIN = { seconds: 180, way: "cw" };
+/** The drawing, followed along a turn, is made again at most this often. */
+const PLACE_MS = 50;
 let assetBase = null;
 /** Where the licensed models are, for every element with no `assets` attribute of its own. Left unset: beside this module, in ./assets/. */
 export function setAssetBase(url) {
@@ -27,6 +29,7 @@ const CSS = `
 .drawing, .drawing svg { display: block; width: 100%; height: 100%; }
 .drawing, .canvas { transition: opacity var(--uchusen-fade, 1500ms) ease-in-out, filter var(--uchusen-fade, 1500ms) ease-in-out; }
 .stage { position: absolute; inset: 0; }
+:host([data-driven]) .picture { overflow: hidden; }
 .canvas { display: block; width: 100%; height: 100%; opacity: 0; filter: blur(3px); cursor: grab; border-radius: inherit; }
 .canvas:active { cursor: grabbing; }
 .canvas:focus-visible { outline: 2px solid currentColor; outline-offset: -2px; }
@@ -87,7 +90,6 @@ export class UchusenRocket extends HTMLBase {
     drawing = null;
     viewer = null;
     watch = null;
-    cleanups = [];
     releaseTimer = 0;
     revealTimer = 0;
     generation = 0;
@@ -97,6 +99,13 @@ export class UchusenRocket extends HTMLBase {
     shownAt = 0;
     starting = false;
     key = "";
+    driven = null;
+    placeFrame = 0;
+    placedAt = 0;
+    stale = false;
+    onScreen = true;
+    drawn = { key: "", box: [0, 0, 1, 1] };
+    tiltCleanups = [];
     /** What is showing now. */
     get state() {
         return this.stateNow;
@@ -117,12 +126,62 @@ export class UchusenRocket extends HTMLBase {
     get angle() {
         return this.viewer?.currentAngle() ?? null;
     }
+    /** Lets a page choose the turn, tip, zoom and pan, as the family's `<kazoku-view-controls>` reports them in `kazoku-viewchange` (`element.drive(event.detail)`): the element's own drag, wheel, keys and spin stand down, and the 3D view and the drawing both follow. `null` takes them back. */
+    drive(choice) {
+        const before = this.driven;
+        if (choice === null) {
+            this.driven = null;
+            delete this.dataset.driven;
+        }
+        else {
+            const number = (value, fallback, lo, hi) => (typeof value === "number" && Number.isFinite(value) ? Math.min(hi, Math.max(lo, value)) : fallback);
+            this.driven = {
+                yaw: number(choice.yaw, this.driven?.yaw ?? 0, -3600, 3600),
+                tilt: number(choice.tilt, this.driven?.tilt ?? 0, -90, 90),
+                zoom: number(choice.zoom, this.driven?.zoom ?? 1, 0.25, 8),
+                panX: number(choice.panX, this.driven?.panX ?? 0, -5000, 5000),
+                panY: number(choice.panY, this.driven?.panY ?? 0, -5000, 5000),
+            };
+            this.dataset.driven = "true";
+        }
+        const now = this.driven;
+        if (before && now && Object.keys(now).every((key) => before[key] === now[key]))
+            return;
+        this.viewer?.drive(this.driven);
+        this.place();
+    }
+    /** The drawing, turned and moved to the chosen view. The 3D view moves itself, so only the drawing needs it, and only until the 3D view shows. It is drawn at most about 20 times a second and never while out of sight: it is made again when it comes back. */
+    place() {
+        if (this.stateNow === "3d" && this.viewer)
+            return;
+        if (!this.onScreen || document.hidden) {
+            this.stale = true;
+            return;
+        }
+        window.cancelAnimationFrame(this.placeFrame);
+        const frame = (time) => {
+            if (time - this.placedAt < PLACE_MS) {
+                this.placeFrame = window.requestAnimationFrame(frame);
+                return;
+            }
+            this.placedAt = time;
+            this.stale = false;
+            this.redraw();
+        };
+        this.placeFrame = window.requestAnimationFrame(frame);
+    }
+    seen = () => {
+        if (!document.hidden && this.stale)
+            this.place();
+    };
     connectedCallback() {
         if (!this.shadowRoot)
             adopt(this.attachShadow({ mode: "open" }), CSS, rocketSheet);
+        document.addEventListener("visibilitychange", this.seen);
         this.queue();
     }
     disconnectedCallback() {
+        document.removeEventListener("visibilitychange", this.seen);
         this.teardown();
         this.key = "";
     }
@@ -173,8 +232,8 @@ export class UchusenRocket extends HTMLBase {
         this.watch = null;
         window.clearTimeout(this.releaseTimer);
         window.clearTimeout(this.revealTimer);
-        for (const clean of this.cleanups.splice(0))
-            clean();
+        window.cancelAnimationFrame(this.placeFrame);
+        this.stopTilt();
         this.viewer?.dispose();
         this.viewer = null;
     }
@@ -243,21 +302,35 @@ export class UchusenRocket extends HTMLBase {
         this.holder = holder;
         this.startWatching();
     }
-    /** The drawing for what the attributes say now. It is made from code, so it needs no file. */
+    /** The drawing for what the attributes say now. It is made from code, so it needs no file. A zoom or a move only changes which part of it the box shows (its viewBox), so the drawing is as sharp as the box and never grows past it. */
     redraw() {
         if (!this.builtNow || !this.drawing)
             return;
         const { look, show, angle } = this.settings(this.builtNow);
         // when a 3D view is showing, a drawing of the same angle is ready behind it
-        const from = this.viewer?.currentAngle() ?? angle;
-        const svg = this.builtNow.svg({ look, show, view: from });
-        const template = document.createElement("template");
-        template.innerHTML = svg;
-        const node = template.content.firstElementChild;
-        if (!node)
-            return;
-        node.setAttribute("aria-label", this.getAttribute("label") ?? this.builtNow.report.label);
-        this.drawing.replaceChildren(node);
+        const from = this.driven ? turnedBy(angle, this.driven.yaw, this.driven.tilt) : (this.viewer?.currentAngle() ?? angle);
+        const label = this.getAttribute("label") ?? this.builtNow.report.label;
+        const key = `${this.key}|${look}|${show}|${from.az.toFixed(2)}|${from.el.toFixed(2)}|${label}`;
+        let node = this.drawing.firstElementChild;
+        if (key !== this.drawn.key || !node) {
+            const template = document.createElement("template");
+            template.innerHTML = this.builtNow.svg({ look, show, view: from });
+            node = template.content.firstElementChild;
+            if (!node)
+                return;
+            node.setAttribute("aria-label", label);
+            this.drawing.replaceChildren(node);
+            const [x = 0, y = 0, w = 1, h = 1] = (node.getAttribute("viewBox") ?? "").split(/[\s,]+/).map(Number);
+            this.drawn = { key, box: [x, y, w, h] };
+        }
+        const { zoom = 1, panX = 0, panY = 0 } = this.driven ?? {};
+        const [x, y, w, h] = this.drawn.box;
+        // the picture fits the box (meet), so a user unit is `unit` pixels; the zoom is about the box's middle and the move is in pixels
+        const unit = Math.min(this.drawing.clientWidth / w, this.drawing.clientHeight / h) || 1;
+        const view = zoom === 1 && panX === 0 && panY === 0 ? [x, y, w, h] : [x + w / 2 - w / (2 * zoom) - panX / (unit * zoom), y + h / 2 - h / (2 * zoom) - panY / (unit * zoom), w / zoom, h / zoom];
+        node.setAttribute("viewBox", view.map((n) => +n.toFixed(3)).join(" "));
+        this.drawing.dataset.zoom = zoom.toFixed(2);
+        this.drawing.dataset.pan = `${Math.round(panX)},${Math.round(panY)}`;
     }
     mark() {
         if (!this.builtNow)
@@ -278,7 +351,7 @@ export class UchusenRocket extends HTMLBase {
             const { look, show, viewName, angle } = this.settings(this.builtNow);
             this.viewer.setLabel(this.getAttribute("label") ?? this.builtNow.report.label);
             // a new rocket keeps the angle, unless the same change named another view
-            const from = viewName !== this.lastView ? angle : this.viewer.currentAngle();
+            const from = viewName !== this.lastView || this.driven ? angle : this.viewer.currentAngle();
             this.lastView = viewName;
             await this.viewer.load(this.builtNow, show, look, from);
             this.emit("uchusen-change", { report: this.builtNow.report });
@@ -307,10 +380,15 @@ export class UchusenRocket extends HTMLBase {
             this.setState(reason === "off" ? "picture" : "fallback", reason);
             if (reason !== "off")
                 this.emit("uchusen-fallback", { reason });
-            return;
         }
-        this.setState("picture");
+        else
+            this.setState("picture");
         this.watch = new IntersectionObserver(([seen]) => {
+            this.onScreen = seen.isIntersecting;
+            if (seen.isIntersecting && this.stale)
+                this.place();
+            if (reason)
+                return;
             if (seen.isIntersecting) {
                 this.shownAt ||= performance.now();
                 window.clearTimeout(this.releaseTimer);
@@ -325,14 +403,23 @@ export class UchusenRocket extends HTMLBase {
                 this.releaseTimer = window.setTimeout(() => {
                     this.viewer?.dispose();
                     this.viewer = null;
-                    if (generation === this.generation)
+                    this.stopTilt();
+                    if (generation === this.generation) {
                         this.setState("picture");
+                        if (this.driven)
+                            this.place();
+                    }
                 }, RELEASE_MS);
             }
         }, { rootMargin: "200px 0px" });
         this.watch.observe(this);
     }
+    stopTilt() {
+        for (const clean of this.tiltCleanups.splice(0))
+            clean();
+    }
     fallBack(why) {
+        this.stopTilt();
         this.viewer?.dispose();
         this.viewer = null;
         this.setState("fallback", why);
@@ -363,6 +450,8 @@ export class UchusenRocket extends HTMLBase {
                 },
             });
             this.viewer = made;
+            if (this.driven)
+                made.drive(this.driven);
             made.setVisible(true);
             const { look, show, viewName, angle } = this.settings(this.builtNow ?? built);
             this.lastView = viewName;
@@ -390,6 +479,7 @@ export class UchusenRocket extends HTMLBase {
         }
     }
     startTilt() {
+        this.stopTilt();
         const Orientation = (typeof DeviceOrientationEvent === "undefined" ? undefined : DeviceOrientationEvent);
         const mode = tiltMode({
             reducedMotion: media("(prefers-reduced-motion: reduce)"),
@@ -400,6 +490,8 @@ export class UchusenRocket extends HTMLBase {
         const listen = () => {
             let rest = null;
             const onTilt = (event) => {
+                if (!this.onScreen || document.hidden)
+                    return;
                 const reading = { beta: event.beta, gamma: event.gamma };
                 rest ??= reading;
                 const turn = tiltTurn(reading, rest, window.screen.orientation?.angle ?? 0);
@@ -407,7 +499,7 @@ export class UchusenRocket extends HTMLBase {
                     this.viewer?.setTilt(turn.azimuth, turn.polar);
             };
             window.addEventListener("deviceorientation", onTilt);
-            this.cleanups.push(() => window.removeEventListener("deviceorientation", onTilt));
+            this.tiltCleanups.push(() => window.removeEventListener("deviceorientation", onTilt));
         };
         if (mode === "on")
             listen();
@@ -428,7 +520,7 @@ export class UchusenRocket extends HTMLBase {
                 }
             });
             this.picture.appendChild(button);
-            this.cleanups.push(() => button.remove());
+            this.tiltCleanups.push(() => button.remove());
         }
     }
 }

package/dist/framing.d.ts

@@ -15,6 +15,16 @@ export interface Angle {
 export declare const VIEWS: Readonly<Record<ViewName, Angle>>;
 export declare const cleanView: (value: unknown) => ViewName;
 export declare const deg: (d: number) => number;
+/** What the family's view controls report: the turn and tip in degrees, the zoom (1 is the whole rocket in the picture) and the pan in pixels. */
+export interface ViewChoice {
+    yaw: number;
+    tilt: number;
+    zoom: number;
+    panX: number;
+    panY: number;
+}
+/** What the family's view controls choose: the turn and tip, in degrees, from a base angle. Dragging right makes `yaw` larger, which carries the camera the other way round; `tilt` larger tips the top away, which lowers the camera. */
+export declare function turnedBy(base: Angle, yaw: number, tilt: number): Angle;
 /** The unit vector from what is looked at towards the camera. */
 export declare function directionOf({ az, el }: Angle): Vec3;
 export interface Framing {

package/dist/framing.js

@@ -15,6 +15,10 @@ export const VIEWS = {
 };
 export const cleanView = (value) => (VIEW_NAMES.includes(value) ? value : DEFAULT_VIEW);
 export const deg = (d) => (d * Math.PI) / 180;
+/** What the family's view controls choose: the turn and tip, in degrees, from a base angle. Dragging right makes `yaw` larger, which carries the camera the other way round; `tilt` larger tips the top away, which lowers the camera. */
+export function turnedBy(base, yaw, tilt) {
+    return { az: base.az - yaw, el: Math.min(87, Math.max(-87, base.el - tilt)) };
+}
 /** The unit vector from what is looked at towards the camera. */
 export function directionOf({ az, el }) {
     const c = Math.cos(deg(el));