@woosh/meep-engine 3.27.0 → 3.28.0

package/src/engine/graphics3/GraphicsEngine.js

@@ -1,830 +1,834 @@
-import { assert } from "../../core/assert.js";
-import Signal from "../../core/events/signal/Signal.js";
-import { Vector2 } from "../../core/geom/Vector2.js";
-import { max2 } from "../../core/math/max2.js";
-import { TextureDescriptor } from "../../shade/descriptor/texture/TextureDescriptor.js";
-import { PerspectiveCamera } from "../../shade/renderer/camera/PerspectiveCamera.js";
-import { DynamicResolutionScaling } from "../../shade/renderer/DynamicResolutionScaling.js";
-import { Renderer } from "../../shade/renderer/Renderer.js";
-import { Scene } from "../../shade/renderer/scene/Scene.js";
-import { Sampler2D } from "../graphics/texture/sampler/Sampler2D.js";
-import EmptyView from "../../view/elements/EmptyView.js";
-import { make_default_environment } from "./make_default_environment.js";
-import { shade_camera_projection_ray } from "./shade_camera_projection_ray.js";
-import { ShadeCameraAdapter } from "./ShadeCameraAdapter.js";
-
-/**
- * @typedef {import("../../core/geom/Vector3.js").Vector3} Vector3
- * @typedef {import("../../shade/renderer/extension/FramePhase.js").FramePhase} FramePhase
- * @typedef {import("../../shade/renderer/extension/RenderExtension.js").RenderExtension} RenderExtension
- * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
- * @typedef {import("../../shade/renderer/texture/ShadeTexture.js").ShadeTexture} ShadeTexture
- * @typedef {import("../graphics/ecs/camera/Camera.js").Camera} Camera
- */
-
-/**
- * What an offscreen picture is drawn into. Not the canvas's presentation format on purpose: a
- * caller reading pixels back wants a channel order it can name, and the presentation format is
- * whatever the platform prefers.
- *
- * @type {string}
- */
-const OFFSCREEN_FORMAT = "rgba8unorm";
-
-/**
- * Frames an offscreen picture is drawn before it is read.
- *
- * More than one because the frame is temporal: anti-aliasing, and every effect that reads last
- * frame's depth, need a history to have been written before what they produce is the picture rather
- * than the first draft of it. Small because the history is dropped by the resize that precedes it,
- * so this is how long convergence takes from nothing rather than how long it takes to forget a
- * previous subject.
- *
- * @type {number}
- */
-const OFFSCREEN_FRAMES = 8;
-
-/**
- * The frame rate dynamic resolution scaling holds, in frames per second.
- *
- * Thirty, by the sponsor's decision (D39). It is a **floor**, not a target the game aims to sit at:
- * the controller is silent while frames are cheaper than 33 ms, and everything it does happens on
- * hardware that cannot hold that. Raising it would mean trading resolution away on machines that
- * were coping.
- *
- * @type {number}
- */
-const TARGET_FRAME_RATE = 30;
-
-/**
- * The renderer meep 3 talks to: Shade behind the shape `GraphicsEngine` presented.
- *
- * It implements the **bootstrap seam** and nothing else — `{viewport, domElement, camera,
- * on.{preRender, postRender, contextLost, contextRestored, contextFailed}, needDraw, autoDraw,
- * start(), stop(), render(), updateSize()}` — because that is what `Engine` needs in order to boot,
- * and because the facade is deliberately not allowed to grow past §4.2 (D14).
- *
- * **Three things have been let through since, each by name.** {@link add_extension} /
- * {@link remove_extension} (E9), because an extension has to survive the restart that replaces the
- * renderer holding it, and
- * {@link scene_context} (E13, D29), because the managers a system needs — animation above all —
- * hang off Shade's per-scene GPU state and there is no other door to them. Both take or return
- * something the caller already owns; neither hands out the renderer.
- *
- * {@link renderer} is the third, and much the widest: it hands the renderer straight out, so
- * everything the other two are shaped to avoid is reachable through it. It is an escape hatch for
- * callers that have no other route, not a migration target — the old engine's 44
- * `.renderer`/`getRenderer()` call sites are each still a migration item.
- *
- * What is deliberately absent, and stays absent: `getRenderer()` (the old engine's accessor, and
- * the shape those call sites are being ported off), `layers` (CPU visibility dies with GPU
- * culling), `scene` (entities reach the scene through the mesh system, not through the facade),
- * and the three-shaped material manager.
- *
- * **Lifecycle differs from the old engine on purpose.** `GraphicsEngine` starts inside the `Engine`
- * constructor, which is why stopping an engine used to leave a restarted one with no renderer at
- * all. This one starts from `Engine.start()` and stops symmetrically, so `start → stop → start`
- * returns a working renderer (E1).
- */
-export class GraphicsEngine {
-    /**
-     * Duck-type the rest of the engine checks instead of `instanceof`, which is the convention
-     * the legacy `CameraSystem` already used and `HeadsUpDisplaySystem` was moved onto in Phase 0.
-     *
-     * @returns {boolean}
-     */
-    get isGraphicsEngine() {
-        return true;
-    }
-
-    /**
-     * Shade's renderer. `null` before a successful {@link start} and again after {@link stop} —
-     * the states a caller has to tolerate, which is why {@link render} checks rather than assumes.
-     *
-     * @type {Renderer|null}
-     */
-    #renderer = null;
-
-    /**
-     * Danger zone.
-     * Be careful with what you do, with great Renderer comes great responsibility.
-     * @returns {Renderer|null}
-     */
-    get renderer(){
-        return this.#renderer;
-    }
-
-    /**
-     * Trades internal resolution for frame time — see {@link dynamic_resolution}.
-     *
-     * @type {DynamicResolutionScaling}
-     */
-    #dynamic_resolution = new DynamicResolutionScaling();
-
-    /**
-     * When the previous frame was drawn, in the clock {@link performance} keeps. Seeded by
-     * {@link start} so that the first frame after one has a real interval behind it rather than a
-     * special case.
-     *
-     * @type {number}
-     */
-    #last_render_timestamp = 0;
-
-    /**
-     * Extensions registered through {@link add_extension}, in the order they were added — which is
-     * not the order they record in: that is resolved from their own declarations, per phase, by the
-     * registry the renderer holds.
-     *
-     * The engine holds them rather than the renderer because a renderer is replaced by every
-     * restart while the systems that registered are not, and because a system has to be able to
-     * register before a device exists.
-     *
-     * @type {RenderExtension[]}
-     */
-    #extensions = [];
-
-    /**
-     * The scene Shade draws.
-     *
-     * There is no getter, deliberately. The old engine handed its scene out and the editor wrote
-     * into the graph directly — 14 call sites of coupling that §2.1 retires. Content reaches the
-     * renderer through the system that owns it, which tells the facade *which* scene to draw and
-     * keeps the graph to itself.
-     *
-     * @type {Scene}
-     */
-    #scene = new Scene();
-
-    /**
-     * @type {HTMLCanvasElement|null}
-     */
-    #canvas = null;
-
-    /**
-     * The camera the frame is drawn from. Owned here rather than handed in, because it is Shade's
-     * and a caller building one would have to know that; what drives it is
-     * {@link camera_sync_from_transform}, from whatever transform the active camera entity has.
-     *
-     * @type {PerspectiveCamera}
-     */
-    #camera = new PerspectiveCamera();
-
-    constructor() {
-        /**
-         * The camera, in the shape the engine's existing consumers read it — `projectionMatrix` and
-         * `matrixWorldInverse`, which is what `HeadsUpDisplaySystem` multiplies together. The real
-         * Shade camera is on its `camera` property.
-         *
-         * @type {ShadeCameraAdapter}
-         */
-        this.camera = new ShadeCameraAdapter(this.#camera);
-
-        this.on = {
-            /**
-             * **The camera-finalized phase.** Camera matrices are final and the frame has not been
-             * submitted — which is what §2.1 already defines `preRender` to mean, so the old
-             * engine's `visibilityConstructionStarted` / `visibilityConstructionEnded` do not
-             * survive as signals of their own. Their subscribers — the legacy camera and light
-             * systems, the editor's symbolic display — landed here when their systems were ported.
-             *
-             * @type {Signal}
-             */
-            preRender: new Signal(),
-
-            /**
-             * The frame has been submitted. Note that submitted is not finished — the GPU is still
-             * working when this fires, on this renderer as on the last one.
-             *
-             * @type {Signal}
-             */
-            postRender: new Signal(),
-
-            /**
-             * The GPU device was lost. Nothing renders after this.
-             *
-             * @type {Signal}
-             */
-            contextLost: new Signal(),
-
-            /**
-             * **Never fires.** Kept because the contract has it and subscribers expect the shape,
-             * but Shade does not recover a lost device (R6): everything the renderer built lived on
-             * it, and a message plus a reload is the honest response. A subscriber here is waiting
-             * for something that will not happen.
-             *
-             * @type {Signal<number>}
-             */
-            contextRestored: new Signal(),
-
-            /**
-             * There will be no rendering — no WebGPU, no adapter, or hardware below the floor.
-             * Carries a {@link ShadeDeviceFailure}, whose `message` is written to be shown.
-             *
-             * @type {Signal<ShadeDeviceFailure>}
-             */
-            contextFailed: new Signal(),
-        };
-
-
-
-        /**
-         * Final render resolution in whole device pixels. Zero until the viewport has a size.
-         *
-         * @readonly
-         * @type {Vector2}
-         */
-        this.output_resolution = new Vector2(0, 0);
-
-        /**
-         * The DOM element the canvas lives in. Created here rather than in {@link start} so that
-         * layout can be wired before a device exists — and so a failed start still leaves something
-         * to put a message in.
-         *
-         * @type {EmptyView}
-         */
-        this.viewport = new EmptyView();
-        this.viewport.size.onChanged.add(this.updateSize, this);
-
-        /**
-         * @type {HTMLCanvasElement|null}
-         */
-        this.domElement = null;
-
-        /**
-         * Whether the next frame has anything new to show. With {@link autoDraw} off, this is what
-         * gates rendering at all.
-         *
-         * @type {boolean}
-         */
-        this.needDraw = true;
-
-        /**
-         * Draw every tick regardless of {@link needDraw}. On-demand rendering — menus and the
-         * editor that should not burn frames — is turning this off.
-         *
-         * @type {boolean}
-         */
-        this.autoDraw = true;
-
-        /**
-         * @type {number}
-         */
-        this.frameIndex = 0;
-
-        /*
-         Wired here rather than in `start`, because the closures read the field and the field is
-         re-assigned on every start: a controller that captured one renderer would keep steering it
-         after a context restart replaced it.
-        */
-        this.#dynamic_resolution.get_scale = () => this.#renderer.internal_resolution_scale;
-        this.#dynamic_resolution.set_scale = v => {
-            this.#renderer.internal_resolution_scale = v;
-        };
-
-        /*
-         Stated rather than inherited. It happens to equal the controller's own default today, and
-         that is not a reason to leave it unsaid: the game's target is the game's decision (D39), and
-         a library default is free to move without anybody meaning the game to follow it.
-        */
-        this.#dynamic_resolution.target_frame_rate = TARGET_FRAME_RATE;
-    }
-
-    /**
-     * Trades internal resolution for frame time, and is the only thing in this engine that does.
-     *
-     * Exposed so that it can be turned off or re-targeted — a measurement that wants a fixed
-     * resolution, or a settings screen that offers the choice — and for no other reason: it drives
-     * itself from {@link render}, and nothing has to call it.
-     *
-     * **It targets {@link TARGET_FRAME_RATE}**, which makes it a floor-holder rather than a
-     * frame-rate governor: it does nothing at all until a frame costs more than 33 ms, and on
-     * hardware that clears the budget it sits at full resolution and never engages.
-     *
-     * @returns {DynamicResolutionScaling}
-     */
-    get dynamic_resolution() {
-        return this.#dynamic_resolution;
-    }
-
-    /**
-     * Draw this scene from now on.
-     *
-     * The narrowest seam that works: the facade is told what to draw, rather than handing out a
-     * graph for anyone to write into. Shade's own `render` takes the scene as an argument, so this
-     * matches how the renderer underneath already thinks about it.
-     *
-     * @param {Scene} scene
-     */
-    set_scene(scene) {
-        assert.defined(scene, 'scene');
-        assert.equal(scene.isScene, true, 'scene.isScene !== true');
-
-        this.#scene = scene;
-
-        /*
-         Shade lights with indirect by default and a scene without an environment renders unlit, so
-         the engine supplies one rather than leaving every caller to. Turning global illumination off
-         is the thing that takes a decision, not turning it on.
-
-         A scene that arrives with an environment keeps it: the scene owns its lighting and this only
-         fills in what is missing. Otherwise handing over a scene would silently discard the
-         environment it was built with, and the fix would be to call things in a particular order.
-         */
-        if (scene.lights.environment === undefined) {
-            scene.lights.environment = make_default_environment();
-        }
-    }
-
-    /**
-     * Set the scene's image-based-lighting source, replacing whatever it was lighting with.
-     *
-     * No prefiltering happens here, unlike the equivalent on the old engine: Shade convolves the map
-     * into its irradiance and roughness mips on the GPU, notices when the texture it was given has
-     * been swapped, and redoes that work itself. So this is an assignment and the renderer catches up
-     * on the next frame — safe before startup as well as after.
-     *
-     * The texture must be **octahedral**, which is the projection Shade samples the environment with.
-     * `load_environment_map` and `resample_equirectangular_to_octahedral` are the ways in; a cube or
-     * equirectangular texture handed over directly would sample as garbage rather than fail.
-     *
-     * There is deliberately no `set_environment_texture` counterpart. On the old engine that meant
-     * "and show it as the skybox too", and Shade has no background of its own to show it on — the
-     * visible sky is its own piece of work rather than a second line here.
-     *
-     * @param {ShadeTexture} texture octahedral-encoded spherical radiance
-     */
-    set_environment_map(texture) {
-        assert.defined(texture, 'texture');
-        assert.equal(texture.isShadeTexture, true, 'texture.isShadeTexture !== true');
-
-        this.#scene.lights.environment = texture;
-
-        this.needDraw = true;
-    }
-
-    /**
-     * Record work into the frame at a named point in it — §4.8's extensibility surface, and the
-     * honest replacement for the old engine's `preRender` / `buffersRendered` / `postRender`
-     * signals, each of which maps to a phase.
-     *
-     * The extension is handed a `FrameContext` when its phase comes round and records with the
-     * `graph_*` helpers, exactly as the built-in passes do. Resource handles come from the frame's
-     * records rather than from a renderer: the frame graph is what knows which resources a pass
-     * touched, and work recorded around it cannot be ordered or aliased against the rest of the
-     * frame.
-     *
-     * **Registering does not require a device.** Extensions are held here and applied to the
-     * renderer when one exists, and again after a restart — a system registers at startup without
-     * knowing where in the lifecycle it is.
-     *
-     * @param {RenderExtension} extension
-     * @returns {RenderExtension} `extension`, for handing back to {@link remove_extension}
-     */
-    add_extension(extension) {
-        assert.defined(extension, 'extension');
-        assert.isFunction(extension.record, 'extension.record');
-
-        this.#extensions.push(extension);
-
-        if (this.#renderer !== null) {
-            this.#renderer.add_extension(extension);
-        }
-
-        return extension;
-    }
-
-    /**
-     * How many extensions are registered against a phase.
-     *
-     * Read-only, and here because a system that registers one otherwise has no way to say that it
-     * did: the extension is private to the system that owns it, and "start → stop → start leaks
-     * nothing" is a property a gate has to be able to state. It says how many, not what they are,
-     * and hands out nothing.
-     *
-     * @param {FramePhase} phase
-     * @returns {number}
-     */
-    extension_count(phase) {
-        assert.isNonNegativeInteger(phase, 'phase');
-
-        let count = 0;
-
-        for (let i = 0; i < this.#extensions.length; i++) {
-            if (this.#extensions[i].phase === phase) {
-                count++;
-            }
-        }
-
-        return count;
-    }
-
-    /**
-     * Take an extension back out. Identity is the object, so the phase does not have to be
-     * repeated.
-     *
-     * @param {RenderExtension} extension
-     * @returns {boolean} whether it was registered
-     */
-    remove_extension(extension) {
-        const index = this.#extensions.indexOf(extension);
-
-        if (index === -1) {
-            return false;
-        }
-
-        this.#extensions.splice(index, 1);
-
-        if (this.#renderer !== null) {
-            this.#renderer.remove_extension(extension);
-        }
-
-        return true;
-    }
-
-    /**
-     * Shade's GPU-side state for a scene the caller already owns — and with it the managers that
-     * hang off it, of which the animation manager is the one Phase 4 needs.
-     *
-     * **The one thing D14 lets through, and D29 is why** (E13). The alternative was a system
-     * registering a frame pass that draws nothing, purely to be handed `context.view.scene` when
-     * its phase came round — which would have made the animation system claim a moment in drawing
-     * for work that is not drawing. A named method costs one line of surface and says what it is.
-     *
-     * **This still hands out no graph.** `scene` is an argument, not a getter: only the system that
-     * owns a scene can ask about it, so the coupling §2.1 retires — the facade handing its graph to
-     * anyone who asks — is not what this is. What comes back is the renderer's own bookkeeping for
-     * that scene, which is Shade's to shape and no one else's.
-     *
-     * @param {Scene} scene
-     * @returns {GPUSceneContext|null} `null` while there is no device — before a successful
-     * {@link start} and again after {@link stop}. A restart builds a **new** context, so a caller
-     * holding ids the old one issued has to notice the object changed and register again.
-     */
-    scene_context(scene) {
-        assert.defined(scene, 'scene');
-        assert.equal(scene.isScene, true, 'scene.isScene !== true');
-
-        const renderer = this.#renderer;
-
-        if (renderer === null) {
-            return null;
-        }
-
-        return renderer.scenes.obtain(scene);
-    }
-
-    /**
-     * Draw a scene of somebody else's into a texture of that size, and hand back its pixels.
-     *
-     * **Tooling only.** This is a GPU readback and I-4 forbids those on any gameplay-affecting path;
-     * what it is here for is pictures of things — an asset library's icons, a thumbnail, a capture.
-     *
-     * **No renderer and no device leave the facade** (D14). What the caller brings is a scene and a
-     * camera, both of which it built; what it gets back is a `Sampler2D`. The frame itself goes
-     * through `Renderer.render_to_target` (D50), so the picture is drawn by the renderer that is
-     * already running, with the geometry and the textures it already holds resident.
-     *
-     * **The renderer is resized for the call and put back afterwards.** Everything a frame is built
-     * out of is sized from the output resolution, so a 64 x 64 picture means a 64 x 64 frame; the
-     * temporal history that costs is dropped either way by the resize.
-     *
-     * @param {Scene} scene
-     * @param {Camera} camera
-     * @param {number} width texels
-     * @param {number} height texels
-     * @returns {Promise<Sampler2D>} RGBA, one byte a channel
-     * @throws {Error} when there is no device — before a successful {@link start}, or after
-     * {@link stop}
-     */
-    async render_to_sampler(scene, camera, width, height) {
-        assert.defined(scene, 'scene');
-        assert.defined(camera, 'camera');
-        assert.isNonNegativeInteger(width, 'width');
-        assert.isNonNegativeInteger(height, 'height');
-        assert.greaterThan(width, 0, 'width');
-        assert.greaterThan(height, 0, 'height');
-
-        const renderer = this.#renderer;
-
-        if (renderer === null) {
-            throw new Error('cannot render without a device — start() has not run, or stop() has');
-        }
-
-        const target = renderer.graphics.textures.contextFromDescriptor(TextureDescriptor.from({
-            label: "GraphicsEngine/offscreen",
-            size: [width, height, 1],
-            format: OFFSCREEN_FORMAT,
-            usage: GPUTextureUsage.RENDER_ATTACHMENT
-                | GPUTextureUsage.TEXTURE_BINDING
-                | GPUTextureUsage.COPY_SRC
-        }));
-
-        const pixel_ratio = renderer.pixel_ratio;
-        const automatic_exposure = renderer.feature_automatic_exposure_enabled;
-
-        try {
-            renderer.pixel_ratio = 1;
-            renderer.resize(width, height);
-
-            /*
-             A picture of one object against nothing has no scene to read an exposure off, and an
-             adapting one would take the frames it adapts over — so a preview is drawn at the fixed
-             exposure instead, which is what a studio light rig is for.
-            */
-            renderer.feature_automatic_exposure_enabled = false;
-
-            for (let i = 0; i < OFFSCREEN_FRAMES; i++) {
-                renderer.render_to_target(camera, scene, 1 / 60, target);
-            }
-
-            const data = await target.download();
-
-            return new Sampler2D(data, 4, width, height);
-        } finally {
-            target.destroy();
-
-            renderer.feature_automatic_exposure_enabled = automatic_exposure;
-            renderer.pixel_ratio = pixel_ratio;
-
-            this.updateSize();
-        }
-    }
-
-    /**
-     * Whether there is a device to render with.
-     *
-     * @returns {boolean}
-     */
-    get is_running() {
-        return this.#renderer !== null;
-    }
-
-    /**
-     * Stand a device up and attach its canvas to the viewport.
-     *
-     * Asynchronous because acquiring a WebGPU device is — there is no synchronous form of it — and
-     * because failing to get one is a normal outcome that has to be reported rather than thrown
-     * into a constructor. A failure raises `on.contextFailed` with a message written for a person
-     * and rethrows, so a caller that wants to handle it can and one that does not still fails
-     * loudly.
-     *
-     * @returns {Promise<void>}
-     */
-    async start() {
-        if (this.#renderer !== null) {
-            // already running; starting twice is a caller error rather than a no-op worth hiding
-            throw new Error('GraphicsEngine is already started');
-        }
-
-        const canvas = document.createElement("canvas");
-
-        canvas.classList.add("graphics-engine-render-canvas");
-
-        const style = canvas.style;
-
-        style.userSelect = style.webkitUserSelect = style.mozUserSelect = "none";
-        // see https://www.w3.org/TR/pointerevents/#the-touch-action-css-property
-        style.touchAction = "none";
-
-        this.#canvas = canvas;
-
-        const renderer = new Renderer();
-
-        try {
-            await renderer.initialize({ context: canvas.getContext('webgpu') });
-        } catch (failure) {
-            this.#canvas = null;
-
-            this.on.contextFailed.send1(failure);
-
-            throw failure;
-        }
-
-        renderer.onDeviceFailure.add(this.#handle_device_failure, this);
-
-        // Extensions outlive the device: they are registered against the engine, not against a
-        // renderer that a restart replaces. This is what makes a system able to register once, at
-        // startup, without knowing whether a device exists yet.
-        for (let i = 0; i < this.#extensions.length; i++) {
-            renderer.add_extension(this.#extensions[i]);
-        }
-
-        this.#renderer = renderer;
-        this.domElement = canvas;
-
-        this.adopt_canvas(canvas);
-
-        this.updateSize();
-
-        // so the first frame's interval is a real one rather than the whole of the boot
-        this.#last_render_timestamp = performance.now();
-    }
-
-    /**
-     * Re-point the viewport at a canvas, and the page with it. This is the wrinkle E1 named:
-     * `start` builds a *new* canvas, so a restart would otherwise leave the dead one mounted and
-     * the live one detached. `View.el` is read unguarded all over the view layer, so it is replaced
-     * rather than cleared — it always holds an element.
-     *
-     * The inline `pointer-events` of the element being replaced comes along: the engine opts the
-     * viewport back in (`auto`) under a game view that lets clicks fall through (`none`), and it
-     * does so on the placeholder element before there is a canvas. A canvas that did not inherit
-     * the opt-in inherited the fall-through instead, and every pointer device bound to the canvas
-     * — the editor's tools — was deaf to every press.
-     *
-     * Public so that the swap can be driven without a device.
-     *
-     * @param {HTMLCanvasElement} canvas
-     */
-    adopt_canvas(canvas) {
-        const previous = this.viewport.el;
-
-        if (previous != null && previous !== canvas && previous.style !== undefined && previous.style.pointerEvents !== "") {
-            canvas.style.pointerEvents = previous.style.pointerEvents;
-        }
-
-        this.viewport.el = canvas;
-
-        if (previous != null && previous !== canvas && previous.parentNode !== null) {
-            previous.parentNode.replaceChild(canvas, previous);
-        }
-    }
-
-    /**
-     * Tear the device down and let go of the canvas.
-     *
-     * Symmetric with {@link start}, and that symmetry is the point: the old engine started in a
-     * constructor and could not be restarted.
-     */
-    stop() {
-        const renderer = this.#renderer;
-
-        if (renderer === null) {
-            // never started, or stopped twice — nothing to undo
-            return;
-        }
-
-        renderer.onDeviceFailure.remove(this.#handle_device_failure, this);
-        renderer.destroy();
-
-        this.#renderer = null;
-        this.#canvas = null;
-        this.domElement = null;
-
-        // `viewport.el` is deliberately left pointing at the spent canvas rather than cleared: the
-        // view layer reads it without checking, and the next `start` swaps it for a live one.
-    }
-
-    /**
-     * @param {ShadeDeviceFailure} failure
-     */
-    #handle_device_failure(failure) {
-        this.on.contextLost.dispatch(failure);
-    }
-
-    /**
-     * A pointer position in viewport pixels, as a clip-space point.
-     *
-     * Unchanged from the old engine, down to writing into a caller's vector: it is arithmetic on the
-     * viewport size and has nothing to do with which renderer is underneath.
-     *
-     * @param {Vector2|Vector3} input viewport pixels, origin top-left
-     * @param {Vector2|Vector3} result written with −1…1, +Y up
-     */
-    normalizeViewportPoint(input, result) {
-        const size = this.viewport.size;
-
-        // shifted by half a pixel, so the value names the centre of the pixel rather than its corner
-        result.x = ((input.x + 0.5) / size.x) * 2 - 1;
-        result.y = -((input.y + 0.5) / size.y) * 2 + 1;
-    }
-
-    /**
-     * A ray from the eye through a point on the viewport, in world space.
-     *
-     * Same name, same arguments, same meaning as on the old engine — and the same expectation that
-     * `x` and `y` are **clip-space**, which {@link normalizeViewportPoint} is what produces. What is
-     * behind it is Shade's camera rather than three's; see {@link shade_camera_projection_ray}.
-     *
-     * This is the only picking primitive the game actually needs. Every gameplay pick is a terrain
-     * raycast — an exact query against the terrain's own representation, which no part of the renderer
-     * is involved in — so a working ray is the whole of the renderer's contribution to it.
-     *
-     * @param {number} x clip space, −1…1
-     * @param {number} y clip space, −1…1, +Y up
-     * @param {Vector3} source written with the ray's origin
-     * @param {Vector3} direction written with a unit direction
-     */
-    viewportProjectionRay(x, y, source, direction) {
-        shade_camera_projection_ray(this.#camera, x, y, source, direction);
-    }
-
-    /**
-     * Size the drawing buffer to the viewport.
-     *
-     * Shade's `resize` takes a **CSS** size and applies the device pixel ratio itself, which is the
-     * opposite of what the old engine's renderer wanted. `output_resolution` is then the
-     * device-pixel figure, for everything that has to land on the same texel grid.
-     *
-     * **There is no engine-level `pixelRatio` any more, and that is the answer to GAP-027 rather
-     * than an oversight.** The field was a public `Vector1` that `updateSize` read, and nothing
-     * bound its `onChanged` — the constructor bound `viewport.size.onChanged` and stopped — so
-     * writing it changed nothing until the window happened to be resized, which on a full-screen
-     * game is never. The first symptom is a setting that appears dead and then works perfectly the
-     * moment somebody drags the window. Calling `updateSize()` by hand did not rescue it either:
-     * `Renderer.resize` asserts whole pixels and the product was passed unfloored, so any
-     * fractional ratio threw. Between the two, the property had no working use at any point in its
-     * life.
-     *
-     * Render resolution belongs to the renderer, which already has the hooks for it —
-     * `internal_resolution_scale` takes any positive number, floors internally, and is upscaled
-     * back by the renderer's own TAA rather than by the browser stretching a smaller canvas, which
-     * is the better answer on quality grounds as well. It is reachable through the `renderer`
-     * getter. A second, half-wired knob on this facade was only ever going to be found by someone
-     * who then had to discover why it did nothing.
-     */
-    updateSize() {
-        const size = this.viewport.size;
-
-        const css_width = max2(0, size.x);
-        const css_height = max2(0, size.y);
-
-        const renderer = this.#renderer;
-
-        if (renderer !== null) {
-            renderer.resize(css_width, css_height);
-        }
-
-        if (this.domElement !== null) {
-            this.domElement.style.width = size.x + "px";
-            this.domElement.style.height = size.y + "px";
-        }
-
-        const device_pixel_ratio = window.devicePixelRatio;
-
-        // clamped to 1 for the same reason the old engine clamped it: a collapsed viewport still
-        // allocates attachments, and a zero-sized one is not a legal target
-        this.output_resolution.set(
-            max2(1, Math.floor(css_width * device_pixel_ratio)),
-            max2(1, Math.floor(css_height * device_pixel_ratio))
-        );
-    }
-
-    /**
-     * Draw a frame, if there is anything to draw it with.
-     *
-     * @param {number} [time_delta_seconds]
-     * @returns {boolean} whether a frame was submitted
-     */
-    render(time_delta_seconds = 1 / 60) {
-        const renderer = this.#renderer;
-
-        if (renderer === null) {
-            return false;
-        }
-
-        const viewport_size = this.viewport.size;
-
-        if (viewport_size.x <= 0 || viewport_size.y <= 0) {
-            /*
-             There is no surface to draw into. Every boot passes through this — the renderer starts
-             before the game view is laid out — and so does any collapsed or unmounted view.
-             Drawing anyway is worse than drawing nothing: `output_resolution` and the renderer's
-             own resolutions both floor at one texel, and a one-texel target is a size the frame's
-             mip chains cannot be built from, so what a frame produces here is a run of invalid
-             textures rather than a picture. `needDraw` is left set, so the next frame retries.
-            */
-            return false;
-        }
-
-        /*
-         The **refresh** interval, measured here rather than taken from `time_delta_seconds`. What
-         the controller steers by has to be how long a frame actually took, wall clock, including
-         everything outside this call; the argument is the simulation's delta, which is clamped and
-         is not the same quantity. Measuring between calls is also what makes this correct for any
-         driver — the engine's animation frame, or a probe calling `render` directly.
-        */
-        const now = performance.now();
-
-        this.#dynamic_resolution.notify_frame((now - this.#last_render_timestamp) / 1000);
-
-        this.#last_render_timestamp = now;
-
-        // Aspect follows the surface being drawn to, so it is refreshed here rather than left to
-        // whoever last resized: a camera describing a viewport that has since changed shape is the
-        // classic source of a stretched frame.
-        this.#camera.aspect = renderer.aspect_ratio;
-        this.#camera.update();
-
-        this.on.preRender.dispatch();
-
-        const submitted = renderer.render(this.#camera, this.#scene, time_delta_seconds);
-
-        this.frameIndex++;
-        this.needDraw = false;
-
-        this.on.postRender.dispatch();
-
-        return submitted;
-    }
-}
+import { assert } from "../../core/assert.js";
+import Signal from "../../core/events/signal/Signal.js";
+import { Vector2 } from "../../core/geom/Vector2.js";
+import { max2 } from "../../core/math/max2.js";
+import { TextureDescriptor } from "../../shade/descriptor/texture/TextureDescriptor.js";
+import { PerspectiveCamera } from "../../shade/renderer/camera/PerspectiveCamera.js";
+import { DynamicResolutionScaling } from "../../shade/renderer/DynamicResolutionScaling.js";
+import { Renderer } from "../../shade/renderer/Renderer.js";
+import { Scene } from "../../shade/renderer/scene/Scene.js";
+import { Sampler2D } from "../graphics/texture/sampler/Sampler2D.js";
+import EmptyView from "../../view/elements/EmptyView.js";
+import { make_default_environment } from "./make_default_environment.js";
+import { shade_camera_projection_ray } from "./shade_camera_projection_ray.js";
+import { ShadeCameraAdapter } from "./ShadeCameraAdapter.js";
+
+/**
+ * @typedef {import("../../core/geom/Vector3.js").Vector3} Vector3
+ * @typedef {import("../../shade/renderer/extension/FramePhase.js").FramePhase} FramePhase
+ * @typedef {import("../../shade/renderer/extension/RenderExtension.js").RenderExtension} RenderExtension
+ * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../../shade/renderer/texture/ShadeTexture.js").ShadeTexture} ShadeTexture
+ * @typedef {import("../graphics/ecs/camera/Camera.js").Camera} Camera
+ */
+
+/**
+ * What an offscreen picture is drawn into. Not the canvas's presentation format on purpose: a
+ * caller reading pixels back wants a channel order it can name, and the presentation format is
+ * whatever the platform prefers.
+ *
+ * @type {string}
+ */
+const OFFSCREEN_FORMAT = "rgba8unorm";
+
+/**
+ * Frames an offscreen picture is drawn before it is read.
+ *
+ * More than one because the frame is temporal: anti-aliasing, and every effect that reads last
+ * frame's depth, need a history to have been written before what they produce is the picture rather
+ * than the first draft of it. Small because the history is dropped by the resize that precedes it,
+ * so this is how long convergence takes from nothing rather than how long it takes to forget a
+ * previous subject.
+ *
+ * @type {number}
+ */
+const OFFSCREEN_FRAMES = 8;
+
+/**
+ * The frame rate dynamic resolution scaling holds, in frames per second.
+ *
+ * Thirty, by the sponsor's decision (D39). It is a **floor**, not a target the game aims to sit at:
+ * the controller is silent while frames are cheaper than 33 ms, and everything it does happens on
+ * hardware that cannot hold that. Raising it would mean trading resolution away on machines that
+ * were coping.
+ *
+ * @type {number}
+ */
+const TARGET_FRAME_RATE = 30;
+
+/**
+ * The renderer meep 3 talks to: Shade behind the shape `GraphicsEngine` presented.
+ *
+ * It implements the **bootstrap seam** and nothing else — `{viewport, domElement, camera,
+ * on.{preRender, postRender, contextLost, contextRestored, contextFailed}, needDraw, autoDraw,
+ * start(), stop(), render(), updateSize()}` — because that is what `Engine` needs in order to boot,
+ * and because the facade is deliberately not allowed to grow past §4.2 (D14).
+ *
+ * **Three things have been let through since, each by name.** {@link add_extension} /
+ * {@link remove_extension} (E9), because an extension has to survive the restart that replaces the
+ * renderer holding it, and
+ * {@link scene_context} (E13, D29), because the managers a system needs — animation above all —
+ * hang off Shade's per-scene GPU state and there is no other door to them. Both take or return
+ * something the caller already owns; neither hands out the renderer.
+ *
+ * {@link renderer} is the third, and much the widest: it hands the renderer straight out, so
+ * everything the other two are shaped to avoid is reachable through it. It is an escape hatch for
+ * callers that have no other route, not a migration target — the old engine's 44
+ * `.renderer`/`getRenderer()` call sites are each still a migration item.
+ *
+ * What is deliberately absent, and stays absent: `getRenderer()` (the old engine's accessor, and
+ * the shape those call sites are being ported off), `layers` (CPU visibility dies with GPU
+ * culling), `scene` (entities reach the scene through the mesh system, not through the facade),
+ * and the three-shaped material manager.
+ *
+ * **Lifecycle differs from the old engine on purpose.** `GraphicsEngine` starts inside the `Engine`
+ * constructor, which is why stopping an engine used to leave a restarted one with no renderer at
+ * all. This one starts from `Engine.start()` and stops symmetrically, so `start → stop → start`
+ * returns a working renderer (E1).
+ */
+export class GraphicsEngine {
+    /**
+     * Duck-type the rest of the engine checks instead of `instanceof`, which is the convention
+     * the legacy `CameraSystem` already used and `HeadsUpDisplaySystem` was moved onto in Phase 0.
+     *
+     * @returns {boolean}
+     */
+    get isGraphicsEngine() {
+        return true;
+    }
+
+    /**
+     * Shade's renderer. `null` before a successful {@link start} and again after {@link stop} —
+     * the states a caller has to tolerate, which is why {@link render} checks rather than assumes.
+     *
+     * @type {Renderer|null}
+     */
+    #renderer = null;
+
+    /**
+     * Danger zone.
+     * Be careful with what you do, with great Renderer comes great responsibility.
+     * @returns {Renderer|null}
+     */
+    get renderer(){
+        return this.#renderer;
+    }
+
+    /**
+     * Trades internal resolution for frame time — see {@link dynamic_resolution}.
+     *
+     * @type {DynamicResolutionScaling}
+     */
+    #dynamic_resolution = new DynamicResolutionScaling();
+
+    /**
+     * When the previous frame was drawn, in the clock {@link performance} keeps. Seeded by
+     * {@link start} so that the first frame after one has a real interval behind it rather than a
+     * special case.
+     *
+     * @type {number}
+     */
+    #last_render_timestamp = 0;
+
+    /**
+     * Extensions registered through {@link add_extension}, in the order they were added — which is
+     * not the order they record in: that is resolved from their own declarations, per phase, by the
+     * registry the renderer holds.
+     *
+     * The engine holds them rather than the renderer because a renderer is replaced by every
+     * restart while the systems that registered are not, and because a system has to be able to
+     * register before a device exists.
+     *
+     * @type {RenderExtension[]}
+     */
+    #extensions = [];
+
+    /**
+     * The scene Shade draws.
+     *
+     * There is no getter, deliberately. The old engine handed its scene out and the editor wrote
+     * into the graph directly — 14 call sites of coupling that §2.1 retires. Content reaches the
+     * renderer through the system that owns it, which tells the facade *which* scene to draw and
+     * keeps the graph to itself.
+     *
+     * @type {Scene}
+     */
+    #scene = new Scene();
+
+    /**
+     * @type {HTMLCanvasElement|null}
+     */
+    #canvas = null;
+
+    /**
+     * The camera the frame is drawn from. Owned here rather than handed in, because it is Shade's
+     * and a caller building one would have to know that; what drives it is
+     * {@link camera_sync_from_transform}, from whatever transform the active camera entity has.
+     *
+     * @type {PerspectiveCamera}
+     */
+    #camera = new PerspectiveCamera();
+
+    constructor() {
+        /**
+         * The camera, in the shape the engine's existing consumers read it — `projectionMatrix` and
+         * `matrixWorldInverse`, which is what `HeadsUpDisplaySystem` multiplies together. The real
+         * Shade camera is on its `camera` property.
+         *
+         * @type {ShadeCameraAdapter}
+         */
+        this.camera = new ShadeCameraAdapter(this.#camera);
+
+        this.on = {
+            /**
+             * **The camera-finalized phase.** Camera matrices are final and the frame has not been
+             * submitted — which is what §2.1 already defines `preRender` to mean, so the old
+             * engine's `visibilityConstructionStarted` / `visibilityConstructionEnded` do not
+             * survive as signals of their own. Their subscribers — the legacy camera and light
+             * systems, the editor's symbolic display — landed here when their systems were ported.
+             *
+             * @type {Signal}
+             */
+            preRender: new Signal(),
+
+            /**
+             * The frame has been submitted. Note that submitted is not finished — the GPU is still
+             * working when this fires, on this renderer as on the last one.
+             *
+             * @type {Signal}
+             */
+            postRender: new Signal(),
+
+            /**
+             * The GPU device was lost. Nothing renders after this.
+             *
+             * @type {Signal}
+             */
+            contextLost: new Signal(),
+
+            /**
+             * **Never fires.** Kept because the contract has it and subscribers expect the shape,
+             * but Shade does not recover a lost device (R6): everything the renderer built lived on
+             * it, and a message plus a reload is the honest response. A subscriber here is waiting
+             * for something that will not happen.
+             *
+             * @type {Signal<number>}
+             */
+            contextRestored: new Signal(),
+
+            /**
+             * There will be no rendering — no WebGPU, no adapter, or hardware below the floor.
+             * Carries a {@link ShadeDeviceFailure}, whose `message` is written to be shown.
+             *
+             * @type {Signal<ShadeDeviceFailure>}
+             */
+            contextFailed: new Signal(),
+        };
+
+
+
+        /**
+         * Final render resolution in whole device pixels. Zero until the viewport has a size.
+         *
+         * @readonly
+         * @type {Vector2}
+         */
+        this.output_resolution = new Vector2(0, 0);
+
+        /**
+         * The DOM element the canvas lives in. Created here rather than in {@link start} so that
+         * layout can be wired before a device exists — and so a failed start still leaves something
+         * to put a message in.
+         *
+         * @type {EmptyView}
+         */
+        this.viewport = new EmptyView();
+        this.viewport.size.onChanged.add(this.updateSize, this);
+
+        /**
+         * @type {HTMLCanvasElement|null}
+         */
+        this.domElement = null;
+
+        /**
+         * Whether the next frame has anything new to show. With {@link autoDraw} off, this is what
+         * gates rendering at all.
+         *
+         * @type {boolean}
+         */
+        this.needDraw = true;
+
+        /**
+         * Draw every tick regardless of {@link needDraw}. On-demand rendering — menus and the
+         * editor that should not burn frames — is turning this off.
+         *
+         * @type {boolean}
+         */
+        this.autoDraw = true;
+
+        /**
+         * @type {number}
+         */
+        this.frameIndex = 0;
+
+        /*
+         Wired here rather than in `start`, because the closures read the field and the field is
+         re-assigned on every start: a controller that captured one renderer would keep steering it
+         after a context restart replaced it.
+        */
+        this.#dynamic_resolution.get_scale = () => this.#renderer.internal_resolution_scale;
+        this.#dynamic_resolution.set_scale = v => {
+            this.#renderer.internal_resolution_scale = v;
+        };
+
+        /*
+         Stated rather than inherited. It happens to equal the controller's own default today, and
+         that is not a reason to leave it unsaid: the game's target is the game's decision (D39), and
+         a library default is free to move without anybody meaning the game to follow it.
+        */
+        this.#dynamic_resolution.target_frame_rate = TARGET_FRAME_RATE;
+    }
+
+    /**
+     * Trades internal resolution for frame time, and is the only thing in this engine that does.
+     *
+     * Exposed so that it can be turned off or re-targeted — a measurement that wants a fixed
+     * resolution, or a settings screen that offers the choice — and for no other reason: it drives
+     * itself from {@link render}, and nothing has to call it.
+     *
+     * **It targets {@link TARGET_FRAME_RATE}**, which makes it a floor-holder rather than a
+     * frame-rate governor: it does nothing at all until a frame costs more than 33 ms, and on
+     * hardware that clears the budget it sits at full resolution and never engages.
+     *
+     * @returns {DynamicResolutionScaling}
+     */
+    get dynamic_resolution() {
+        return this.#dynamic_resolution;
+    }
+
+    /**
+     * Draw this scene from now on.
+     *
+     * The narrowest seam that works: the facade is told what to draw, rather than handing out a
+     * graph for anyone to write into. Shade's own `render` takes the scene as an argument, so this
+     * matches how the renderer underneath already thinks about it.
+     *
+     * @param {Scene} scene
+     */
+    set_scene(scene) {
+        assert.defined(scene, 'scene');
+        assert.equal(scene.isScene, true, 'scene.isScene !== true');
+
+        this.#scene = scene;
+
+        /*
+         Shade lights with indirect by default and a scene without an environment renders unlit, so
+         the engine supplies one rather than leaving every caller to. Turning global illumination off
+         is the thing that takes a decision, not turning it on.
+
+         A scene that arrives with an environment keeps it: the scene owns its lighting and this only
+         fills in what is missing. Otherwise handing over a scene would silently discard the
+         environment it was built with, and the fix would be to call things in a particular order.
+         */
+        if (scene.lights.environment === undefined) {
+            scene.lights.environment = make_default_environment();
+        }
+    }
+
+    /**
+     * Set the scene's image-based-lighting source, replacing whatever it was lighting with.
+     *
+     * No prefiltering happens here, unlike the equivalent on the old engine: Shade convolves the map
+     * into its irradiance and roughness mips on the GPU, notices when the texture it was given has
+     * been swapped, and redoes that work itself. So this is an assignment and the renderer catches up
+     * on the next frame — safe before startup as well as after.
+     *
+     * The texture must be **octahedral**, which is the projection Shade samples the environment with.
+     * `load_environment_map` and `resample_equirectangular_to_octahedral` are the ways in; a cube or
+     * equirectangular texture handed over directly would sample as garbage rather than fail.
+     *
+     * There is deliberately no `set_environment_texture` counterpart. On the old engine that meant
+     * "and show it as the skybox too", and Shade has no background of its own to show it on — the
+     * visible sky is its own piece of work rather than a second line here.
+     *
+     * @param {ShadeTexture} texture octahedral-encoded spherical radiance
+     */
+    set_environment_map(texture) {
+        assert.defined(texture, 'texture');
+        assert.equal(texture.isShadeTexture, true, 'texture.isShadeTexture !== true');
+
+        this.#scene.lights.environment = texture;
+
+        this.needDraw = true;
+    }
+
+    /**
+     * Record work into the frame at a named point in it — §4.8's extensibility surface, and the
+     * honest replacement for the old engine's `preRender` / `buffersRendered` / `postRender`
+     * signals, each of which maps to a phase.
+     *
+     * The extension is handed a `FrameContext` when its phase comes round and records with the
+     * `graph_*` helpers, exactly as the built-in passes do. Resource handles come from the frame's
+     * records rather than from a renderer: the frame graph is what knows which resources a pass
+     * touched, and work recorded around it cannot be ordered or aliased against the rest of the
+     * frame.
+     *
+     * **Registering does not require a device.** Extensions are held here and applied to the
+     * renderer when one exists, and again after a restart — a system registers at startup without
+     * knowing where in the lifecycle it is.
+     *
+     * @param {RenderExtension} extension
+     * @returns {RenderExtension} `extension`, for handing back to {@link remove_extension}
+     */
+    add_extension(extension) {
+        assert.defined(extension, 'extension');
+        assert.isFunction(extension.record, 'extension.record');
+
+        this.#extensions.push(extension);
+
+        if (this.#renderer !== null) {
+            this.#renderer.add_extension(extension);
+        }
+
+        return extension;
+    }
+
+    /**
+     * How many extensions are registered against a phase.
+     *
+     * Read-only, and here because a system that registers one otherwise has no way to say that it
+     * did: the extension is private to the system that owns it, and "start → stop → start leaks
+     * nothing" is a property a gate has to be able to state. It says how many, not what they are,
+     * and hands out nothing.
+     *
+     * @param {FramePhase} phase
+     * @returns {number}
+     */
+    extension_count(phase) {
+        assert.isNonNegativeInteger(phase, 'phase');
+
+        let count = 0;
+
+        for (let i = 0; i < this.#extensions.length; i++) {
+            if (this.#extensions[i].phase === phase) {
+                count++;
+            }
+        }
+
+        return count;
+    }
+
+    /**
+     * Take an extension back out. Identity is the object, so the phase does not have to be
+     * repeated.
+     *
+     * @param {RenderExtension} extension
+     * @returns {boolean} whether it was registered
+     */
+    remove_extension(extension) {
+        const index = this.#extensions.indexOf(extension);
+
+        if (index === -1) {
+            return false;
+        }
+
+        this.#extensions.splice(index, 1);
+
+        if (this.#renderer !== null) {
+            this.#renderer.remove_extension(extension);
+        }
+
+        return true;
+    }
+
+    /**
+     * Shade's GPU-side state for a scene the caller already owns — and with it the managers that
+     * hang off it, of which the animation manager is the one Phase 4 needs.
+     *
+     * **The one thing D14 lets through, and D29 is why** (E13). The alternative was a system
+     * registering a frame pass that draws nothing, purely to be handed `context.view.scene` when
+     * its phase came round — which would have made the animation system claim a moment in drawing
+     * for work that is not drawing. A named method costs one line of surface and says what it is.
+     *
+     * **This still hands out no graph.** `scene` is an argument, not a getter: only the system that
+     * owns a scene can ask about it, so the coupling §2.1 retires — the facade handing its graph to
+     * anyone who asks — is not what this is. What comes back is the renderer's own bookkeeping for
+     * that scene, which is Shade's to shape and no one else's.
+     *
+     * @param {Scene} scene
+     * @returns {GPUSceneContext|null} `null` while there is no device — before a successful
+     * {@link start} and again after {@link stop}. A restart builds a **new** context, so a caller
+     * holding ids the old one issued has to notice the object changed and register again.
+     */
+    scene_context(scene) {
+        assert.defined(scene, 'scene');
+        assert.equal(scene.isScene, true, 'scene.isScene !== true');
+
+        const renderer = this.#renderer;
+
+        if (renderer === null) {
+            return null;
+        }
+
+        return renderer.scenes.obtain(scene);
+    }
+
+    /**
+     * Draw a scene of somebody else's into a texture of that size, and hand back its pixels.
+     *
+     * **Tooling only.** This is a GPU readback and I-4 forbids those on any gameplay-affecting path;
+     * what it is here for is pictures of things — an asset library's icons, a thumbnail, a capture.
+     *
+     * **No renderer and no device leave the facade** (D14). What the caller brings is a scene and a
+     * camera, both of which it built; what it gets back is a `Sampler2D`. The frame itself goes
+     * through `Renderer.render_to_target` (D50), so the picture is drawn by the renderer that is
+     * already running, with the geometry and the textures it already holds resident.
+     *
+     * **The renderer is resized for the call and put back afterwards.** Everything a frame is built
+     * out of is sized from the output resolution, so a 64 x 64 picture means a 64 x 64 frame; the
+     * temporal history that costs is dropped either way by the resize.
+     *
+     * @param {Scene} scene
+     * @param {Camera} camera
+     * @param {number} width texels
+     * @param {number} height texels
+     * @returns {Promise<Sampler2D>} RGBA, one byte a channel
+     * @throws {Error} when there is no device — before a successful {@link start}, or after
+     * {@link stop}
+     */
+    async render_to_sampler(scene, camera, width, height) {
+        assert.defined(scene, 'scene');
+        assert.defined(camera, 'camera');
+        assert.isNonNegativeInteger(width, 'width');
+        assert.isNonNegativeInteger(height, 'height');
+        assert.greaterThan(width, 0, 'width');
+        assert.greaterThan(height, 0, 'height');
+
+        const renderer = this.#renderer;
+
+        if (renderer === null) {
+            throw new Error('cannot render without a device — start() has not run, or stop() has');
+        }
+
+        const target = renderer.graphics.textures.contextFromDescriptor(TextureDescriptor.from({
+            label: "GraphicsEngine/offscreen",
+            size: [width, height, 1],
+            format: OFFSCREEN_FORMAT,
+            usage: GPUTextureUsage.RENDER_ATTACHMENT
+                | GPUTextureUsage.TEXTURE_BINDING
+                | GPUTextureUsage.COPY_SRC
+        }));
+
+        const pixel_ratio = renderer.pixel_ratio;
+        const automatic_exposure = renderer.feature_automatic_exposure_enabled;
+
+        try {
+            renderer.pixel_ratio = 1;
+            renderer.resize(width, height);
+
+            /*
+             A picture of one object against nothing has no scene to read an exposure off, and an
+             adapting one would take the frames it adapts over — so a preview is drawn at the fixed
+             exposure instead, which is what a studio light rig is for.
+            */
+            renderer.feature_automatic_exposure_enabled = false;
+
+            for (let i = 0; i < OFFSCREEN_FRAMES; i++) {
+                renderer.render_to_target(camera, scene, 1 / 60, target);
+            }
+
+            const data = await target.download();
+
+            return new Sampler2D(data, 4, width, height);
+        } finally {
+            target.destroy();
+
+            renderer.feature_automatic_exposure_enabled = automatic_exposure;
+            renderer.pixel_ratio = pixel_ratio;
+
+            this.updateSize();
+        }
+    }
+
+    /**
+     * Whether there is a device to render with.
+     *
+     * @returns {boolean}
+     */
+    get is_running() {
+        return this.#renderer !== null;
+    }
+
+    /**
+     * Stand a device up and attach its canvas to the viewport.
+     *
+     * Asynchronous because acquiring a WebGPU device is — there is no synchronous form of it — and
+     * because failing to get one is a normal outcome that has to be reported rather than thrown
+     * into a constructor. A failure raises `on.contextFailed` with a message written for a person
+     * and rethrows, so a caller that wants to handle it can and one that does not still fails
+     * loudly.
+     *
+     * @returns {Promise<void>}
+     */
+    async start() {
+        if (this.#renderer !== null) {
+            // already running; starting twice is a caller error rather than a no-op worth hiding
+            throw new Error('GraphicsEngine is already started');
+        }
+
+        const canvas = document.createElement("canvas");
+
+        canvas.classList.add("graphics-engine-render-canvas");
+
+        const style = canvas.style;
+
+        style.userSelect = style.webkitUserSelect = style.mozUserSelect = "none";
+        // see https://www.w3.org/TR/pointerevents/#the-touch-action-css-property
+        style.touchAction = "none";
+
+        this.#canvas = canvas;
+
+        const renderer = new Renderer();
+
+        try {
+            await renderer.initialize({ context: canvas.getContext('webgpu') });
+        } catch (failure) {
+            this.#canvas = null;
+
+            this.on.contextFailed.send1(failure);
+
+            throw failure;
+        }
+
+        renderer.onDeviceFailure.add(this.#handle_device_failure, this);
+
+        // Extensions outlive the device: they are registered against the engine, not against a
+        // renderer that a restart replaces. This is what makes a system able to register once, at
+        // startup, without knowing whether a device exists yet.
+        for (let i = 0; i < this.#extensions.length; i++) {
+            renderer.add_extension(this.#extensions[i]);
+        }
+
+        this.#renderer = renderer;
+        this.domElement = canvas;
+
+        this.adopt_canvas(canvas);
+
+        this.updateSize();
+
+        // so the first frame's interval is a real one rather than the whole of the boot
+        this.#last_render_timestamp = performance.now();
+    }
+
+    /**
+     * Re-point the viewport at a canvas, and the page with it. This is the wrinkle E1 named:
+     * `start` builds a *new* canvas, so a restart would otherwise leave the dead one mounted and
+     * the live one detached. `View.el` is read unguarded all over the view layer, so it is replaced
+     * rather than cleared — it always holds an element.
+     *
+     * The inline `pointer-events` of the element being replaced comes along: the engine opts the
+     * viewport back in (`auto`) under a game view that lets clicks fall through (`none`), and it
+     * does so on the placeholder element before there is a canvas. A canvas that did not inherit
+     * the opt-in inherited the fall-through instead, and every pointer device bound to the canvas
+     * — the editor's tools — was deaf to every press.
+     *
+     * Public so that the swap can be driven without a device.
+     *
+     * @param {HTMLCanvasElement} canvas
+     */
+    adopt_canvas(canvas) {
+        const previous = this.viewport.el;
+
+        if (previous != null && previous !== canvas && previous.style !== undefined && previous.style.pointerEvents !== "") {
+            canvas.style.pointerEvents = previous.style.pointerEvents;
+        }
+
+        this.viewport.el = canvas;
+
+        if (previous != null && previous !== canvas && previous.parentNode !== null) {
+            previous.parentNode.replaceChild(canvas, previous);
+        }
+    }
+
+    /**
+     * Tear the device down and let go of the canvas.
+     *
+     * Symmetric with {@link start}, and that symmetry is the point: the old engine started in a
+     * constructor and could not be restarted.
+     */
+    stop() {
+        const renderer = this.#renderer;
+
+        if (renderer === null) {
+            // never started, or stopped twice — nothing to undo
+            return;
+        }
+
+        renderer.onDeviceFailure.remove(this.#handle_device_failure, this);
+        renderer.destroy();
+
+        this.#renderer = null;
+        this.#canvas = null;
+        this.domElement = null;
+
+        // `viewport.el` is deliberately left pointing at the spent canvas rather than cleared: the
+        // view layer reads it without checking, and the next `start` swaps it for a live one.
+    }
+
+    /**
+     * @param {ShadeDeviceFailure} failure
+     */
+    #handle_device_failure(failure) {
+        this.on.contextLost.dispatch(failure);
+    }
+
+    /**
+     * A pointer position in viewport pixels, as a clip-space point.
+     *
+     * Unchanged from the old engine, down to writing into a caller's vector: it is arithmetic on the
+     * viewport size and has nothing to do with which renderer is underneath.
+     *
+     * @param {Vector2|Vector3} input viewport pixels, origin top-left
+     * @param {Vector2|Vector3} result written with −1…1, +Y up
+     */
+    normalizeViewportPoint(input, result) {
+        const size = this.viewport.size;
+
+        // shifted by half a pixel, so the value names the centre of the pixel rather than its corner
+        result.x = ((input.x + 0.5) / size.x) * 2 - 1;
+        result.y = -((input.y + 0.5) / size.y) * 2 + 1;
+    }
+
+    /**
+     * A ray from the eye through a point on the viewport, in world space.
+     *
+     * Same name, same arguments, same meaning as on the old engine — and the same expectation that
+     * `x` and `y` are **clip-space**, which {@link normalizeViewportPoint} is what produces. What is
+     * behind it is Shade's camera rather than three's; see {@link shade_camera_projection_ray}.
+     *
+     * This is the only picking primitive the game actually needs. Every gameplay pick is a terrain
+     * raycast — an exact query against the terrain's own representation, which no part of the renderer
+     * is involved in — so a working ray is the whole of the renderer's contribution to it.
+     *
+     * @param {number} x clip space, −1…1
+     * @param {number} y clip space, −1…1, +Y up
+     * @param {Vector3} source written with the ray's origin
+     * @param {Vector3} direction written with a unit direction
+     */
+    viewportProjectionRay(x, y, source, direction) {
+        shade_camera_projection_ray(this.#camera, x, y, source, direction);
+    }
+
+    /**
+     * Size the drawing buffer to the viewport.
+     *
+     * Shade's `resize` takes a **CSS** size and applies the device pixel ratio itself, which is the
+     * opposite of what the old engine's renderer wanted. `output_resolution` is then the
+     * device-pixel figure, for everything that has to land on the same texel grid.
+     *
+     * **There is no engine-level `pixelRatio` any more, and that is the answer to GAP-027 rather
+     * than an oversight.** The field was a public `Vector1` that `updateSize` read, and nothing
+     * bound its `onChanged` — the constructor bound `viewport.size.onChanged` and stopped — so
+     * writing it changed nothing until the window happened to be resized, which on a full-screen
+     * game is never. The first symptom is a setting that appears dead and then works perfectly the
+     * moment somebody drags the window. Calling `updateSize()` by hand did not rescue it either:
+     * `Renderer.resize` asserts whole pixels and the product was passed unfloored, so any
+     * fractional ratio threw. Between the two, the property had no working use at any point in its
+     * life.
+     *
+     * Render resolution belongs to the renderer, which already has the hooks for it —
+     * `internal_resolution_scale` takes any positive number, floors internally, and is upscaled
+     * back by the renderer's own TAA rather than by the browser stretching a smaller canvas, which
+     * is the better answer on quality grounds as well. It is reachable through the `renderer`
+     * getter. A second, half-wired knob on this facade was only ever going to be found by someone
+     * who then had to discover why it did nothing.
+     */
+    updateSize() {
+        const size = this.viewport.size;
+
+        const css_width = max2(0, size.x);
+        const css_height = max2(0, size.y);
+
+        const renderer = this.#renderer;
+
+        if (renderer !== null) {
+            renderer.resize(css_width, css_height);
+        }
+
+        if (this.domElement !== null) {
+            this.domElement.style.width = size.x + "px";
+            this.domElement.style.height = size.y + "px";
+        }
+
+        const device_pixel_ratio = window.devicePixelRatio;
+
+        // clamped to 1 for the same reason the old engine clamped it: a collapsed viewport still
+        // allocates attachments, and a zero-sized one is not a legal target
+        this.output_resolution.set(
+            max2(1, Math.floor(css_width * device_pixel_ratio)),
+            max2(1, Math.floor(css_height * device_pixel_ratio))
+        );
+    }
+
+    /**
+     * Draw a frame, if there is anything to draw it with.
+     *
+     * @param {number} [time_delta_seconds] simulation seconds to advance the frame by — GPU
+     * particles, the animation tick and exposure adaptation all step by this. Defaults to zero, so
+     * a caller that just wants the current state on screen (a scene transition, a preview) draws it
+     * without moving anything. It deliberately does NOT default to a frame's worth of time: doing
+     * that silently ran the simulation at a fixed 60 Hz regardless of the real clock.
+     * @returns {boolean} whether a frame was submitted
+     */
+    render(time_delta_seconds = 0) {
+        const renderer = this.#renderer;
+
+        if (renderer === null) {
+            return false;
+        }
+
+        const viewport_size = this.viewport.size;
+
+        if (viewport_size.x <= 0 || viewport_size.y <= 0) {
+            /*
+             There is no surface to draw into. Every boot passes through this — the renderer starts
+             before the game view is laid out — and so does any collapsed or unmounted view.
+             Drawing anyway is worse than drawing nothing: `output_resolution` and the renderer's
+             own resolutions both floor at one texel, and a one-texel target is a size the frame's
+             mip chains cannot be built from, so what a frame produces here is a run of invalid
+             textures rather than a picture. `needDraw` is left set, so the next frame retries.
+            */
+            return false;
+        }
+
+        /*
+         The **refresh** interval, measured here rather than taken from `time_delta_seconds`. What
+         the controller steers by has to be how long a frame actually took, wall clock, including
+         everything outside this call; the argument is the simulation's delta, which is clamped and
+         is not the same quantity. Measuring between calls is also what makes this correct for any
+         driver — the engine's animation frame, or a probe calling `render` directly.
+        */
+        const now = performance.now();
+
+        this.#dynamic_resolution.notify_frame((now - this.#last_render_timestamp) / 1000);
+
+        this.#last_render_timestamp = now;
+
+        // Aspect follows the surface being drawn to, so it is refreshed here rather than left to
+        // whoever last resized: a camera describing a viewport that has since changed shape is the
+        // classic source of a stretched frame.
+        this.#camera.aspect = renderer.aspect_ratio;
+        this.#camera.update();
+
+        this.on.preRender.dispatch();
+
+        const submitted = renderer.render(this.#camera, this.#scene, time_delta_seconds);
+
+        this.frameIndex++;
+        this.needDraw = false;
+
+        this.on.postRender.dispatch();
+
+        return submitted;
+    }
+}