@woosh/meep-engine 3.11.3 → 3.13.0

package/src/engine/graphics3/highlight/shader_highlight_outline.js

@@ -1,150 +1,150 @@
-import { BlendState } from "../../../shade/descriptor/blend/BlendState.js";
-import { CodeChunk } from "../../../shade/renderer/shader/compiler/CodeChunk.js";
-import { ImageShader } from "../../../shade/renderer/shader/ImageShader.js";
-import {
-    ShaderResourceSetDescriptor
-} from "../../../shade/renderer/shader/resource/ShaderResourceSetDescriptor.js";
-import { ShaderDescriptor } from "../../../shade/renderer/shader/ShaderDescriptor.js";
-import { f32, u32, vec2u } from "../../../shade/renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../../shade/renderer/shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../../../shade/renderer/shader/type/WebGPUStruct.js";
-import { chunk_highlight_lookup } from "./chunk_highlight_lookup.js";
-
-export const HIGHLIGHT_OUTLINE_SETTINGS = WebGPUStruct.from({
-    screen_resolution: vec2u,
-
-    /**
-     * How many rows the lookup table has, which is one past the highest mesh row that was
-     * highlighted when it was packed.
-     */
-    table_size: u32,
-
-    /**
-     * Outline width in pixels.
-     */
-    thickness: f32,
-});
-
-const resources = new ShaderResourceSetDescriptor();
-
-resources.createGroup()
-    .addUniform("settings", HIGHLIGHT_OUTLINE_SETTINGS);
-
-resources.createGroup()
-    .addTexture("viz_mesh", "uint");
-
-resources.createGroup()
-    .addStorageBuffer("highlight_table", WebGPUArray.u32);
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-@fragment
-fn main(
-    @builtin(position) coord : vec4<f32>,
-) -> @location(0) vec4<f32> {
-
-    let here = vec2<i32>(coord.xy);
-
-    let resolution = vec2<i32>(settings.screen_resolution);
-
-    let table_size = settings.table_size;
-
-    let own = highlight_of_mesh(&highlight_table, textureLoad(viz_mesh, here, 0).r, table_size);
-
-    /*
-     The outline sits **outside** the silhouette. A pixel that is itself the highlighted mesh is left
-     alone — a highlight marks a unit without painting over it, which is the whole reason the legacy
-     path dilated its mask outwards before compositing.
-    */
-    if (own.a > 0.0) {
-        discard;
-    }
-
-    let thickness = settings.thickness;
-
-    let radius = i32(ceil(thickness));
-
-    /*
-     The strongest highlight within reach, by coverage. Nearest would need a second comparison and
-     would look the same: two highlights close enough to overlap an outline this thin are the same
-     size on screen, and the brighter one is the one the eye follows.
-    */
-    var found = vec4<f32>(0.0);
-
-    for (var dy = -radius; dy <= radius; dy++) {
-        for (var dx = -radius; dx <= radius; dx++) {
-            let offset = vec2<f32>(f32(dx), f32(dy));
-
-            // a disc rather than a square, so the outline is the same width in every direction
-            if (dot(offset, offset) > thickness * thickness) {
-                continue;
-            }
-
-            let at = here + vec2<i32>(dx, dy);
-
-            if (any(at < vec2<i32>(0)) || any(at >= resolution)) {
-                continue;
-            }
-
-            let neighbour = highlight_of_mesh(&highlight_table, textureLoad(viz_mesh, at, 0).r, table_size);
-
-            if (neighbour.a > found.a) {
-                found = neighbour;
-            }
-        }
-    }
-
-    if (found.a <= 0.0) {
-        discard;
-    }
-
-    // premultiplied, which is how the table stores it and how the blend state consumes it
-    return found;
-}
-    `, [
-        chunk_highlight_lookup
-    ]
-);
-
-/**
- * Paints an outline around every highlighted mesh, straight off the visibility buffer.
- *
- * **There is no second geometry pass, no dilation and no blur.** The renderer this replaces drew
- * every highlighted object again into an id target of its own, ping-ponged two render targets to
- * dilate the mask, blurred it, and decoded ids back to colours to composite — five render targets, a
- * duplicated scene graph and its own skinned material variant. Shade already writes a per-pixel mesh
- * id while drawing the frame, so an outline is a neighbourhood test on an integer texture and
- * nothing more.
- *
- * **What that costs is the contract change in D27**: the visibility buffer knows only what was
- * rasterized, so a unit standing behind a building is outlined where it can be seen and nowhere
- * else. The old mask was drawn with the depth buffer cleared and showed through everything.
- *
- * @type {ImageShader}
- */
-export const shader_highlight_outline = ImageShader.from({
-    descriptor: ShaderDescriptor.from({
-        label: "Highlight outline",
-        resources,
-        body
-    }),
-    targets: [
-        {
-            label: "outlined",
-            format: "rgba16float",
-            blend: BlendState.from({
-                color: {
-                    operation: "add",
-                    srcFactor: "one",
-                    dstFactor: "one-minus-src-alpha"
-                },
-                alpha: {
-                    operation: "add",
-                    srcFactor: "one",
-                    dstFactor: "one-minus-src-alpha"
-                }
-            })
-        }
-    ]
-});
+import { BlendState } from "../../../shade/descriptor/blend/BlendState.js";
+import { CodeChunk } from "../../../shade/renderer/shader/compiler/CodeChunk.js";
+import { ImageShader } from "../../../shade/renderer/shader/ImageShader.js";
+import {
+    ShaderResourceSetDescriptor
+} from "../../../shade/renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../../shade/renderer/shader/ShaderDescriptor.js";
+import { f32, u32, vec2u } from "../../../shade/renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shade/renderer/shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shade/renderer/shader/type/WebGPUStruct.js";
+import { chunk_highlight_lookup } from "./chunk_highlight_lookup.js";
+
+export const HIGHLIGHT_OUTLINE_SETTINGS = WebGPUStruct.from({
+    screen_resolution: vec2u,
+
+    /**
+     * How many rows the lookup table has, which is one past the highest mesh row that was
+     * highlighted when it was packed.
+     */
+    table_size: u32,
+
+    /**
+     * Outline width in pixels.
+     */
+    thickness: f32,
+});
+
+const resources = new ShaderResourceSetDescriptor();
+
+// per-draw, 16 bytes, read-only: immediate data rather than a uniform buffer
+resources.setImmediate("settings", HIGHLIGHT_OUTLINE_SETTINGS);
+
+resources.createGroup()
+    .addTexture("viz_mesh", "uint");
+
+resources.createGroup()
+    .addStorageBuffer("highlight_table", WebGPUArray.u32);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@fragment
+fn main(
+    @builtin(position) coord : vec4<f32>,
+) -> @location(0) vec4<f32> {
+
+    let here = vec2<i32>(coord.xy);
+
+    let resolution = vec2<i32>(settings.screen_resolution);
+
+    let table_size = settings.table_size;
+
+    let own = highlight_of_mesh(&highlight_table, textureLoad(viz_mesh, here, 0).r, table_size);
+
+    /*
+     The outline sits **outside** the silhouette. A pixel that is itself the highlighted mesh is left
+     alone — a highlight marks a unit without painting over it, which is the whole reason the legacy
+     path dilated its mask outwards before compositing.
+    */
+    if (own.a > 0.0) {
+        discard;
+    }
+
+    let thickness = settings.thickness;
+
+    let radius = i32(ceil(thickness));
+
+    /*
+     The strongest highlight within reach, by coverage. Nearest would need a second comparison and
+     would look the same: two highlights close enough to overlap an outline this thin are the same
+     size on screen, and the brighter one is the one the eye follows.
+    */
+    var found = vec4<f32>(0.0);
+
+    for (var dy = -radius; dy <= radius; dy++) {
+        for (var dx = -radius; dx <= radius; dx++) {
+            let offset = vec2<f32>(f32(dx), f32(dy));
+
+            // a disc rather than a square, so the outline is the same width in every direction
+            if (dot(offset, offset) > thickness * thickness) {
+                continue;
+            }
+
+            let at = here + vec2<i32>(dx, dy);
+
+            if (any(at < vec2<i32>(0)) || any(at >= resolution)) {
+                continue;
+            }
+
+            let neighbour = highlight_of_mesh(&highlight_table, textureLoad(viz_mesh, at, 0).r, table_size);
+
+            if (neighbour.a > found.a) {
+                found = neighbour;
+            }
+        }
+    }
+
+    if (found.a <= 0.0) {
+        discard;
+    }
+
+    // premultiplied, which is how the table stores it and how the blend state consumes it
+    return found;
+}
+    `, [
+        chunk_highlight_lookup
+    ]
+);
+
+/**
+ * Paints an outline around every highlighted mesh, straight off the visibility buffer.
+ *
+ * **There is no second geometry pass, no dilation and no blur.** The renderer this replaces drew
+ * every highlighted object again into an id target of its own, ping-ponged two render targets to
+ * dilate the mask, blurred it, and decoded ids back to colours to composite — five render targets, a
+ * duplicated scene graph and its own skinned material variant. Shade already writes a per-pixel mesh
+ * id while drawing the frame, so an outline is a neighbourhood test on an integer texture and
+ * nothing more.
+ *
+ * **What that costs is the contract change in D27**: the visibility buffer knows only what was
+ * rasterized, so a unit standing behind a building is outlined where it can be seen and nowhere
+ * else. The old mask was drawn with the depth buffer cleared and showed through everything.
+ *
+ * @type {ImageShader}
+ */
+export const shader_highlight_outline = ImageShader.from({
+    descriptor: ShaderDescriptor.from({
+        label: "Highlight outline",
+        resources,
+        body
+    }),
+    targets: [
+        {
+            label: "outlined",
+            format: "rgba16float",
+            blend: BlendState.from({
+                color: {
+                    operation: "add",
+                    srcFactor: "one",
+                    dstFactor: "one-minus-src-alpha"
+                },
+                alpha: {
+                    operation: "add",
+                    srcFactor: "one",
+                    dstFactor: "one-minus-src-alpha"
+                }
+            })
+        }
+    ]
+});

package/src/engine/graphics3/pose/query_entity_node_world_pose.d.ts

@@ -5,7 +5,7 @@
  * where does this projectile leave from, where does that effect anchor, where does the floating UI
  * hang. **The answer is computed, never read back** — GPU readback is a frame late and asynchronous,
  * so an outcome that depended on it would depend on frame pacing, and determinism and replay would
- * go with it (`EXECUTION.md` I-4).
+ * go with it: no GPU readback on a gameplay-affecting path.
  *
  * The pose is {@link pose_evaluate_world} over the clips the animation systems are driving: a pure
  * function of (clip set, time, weights), off the same clock the renderer is written from, which is

package/src/engine/graphics3/pose/query_entity_node_world_pose.js

@@ -1,101 +1,101 @@
-import { assert } from "../../../core/assert.js";
-import { PosePlayback } from "../../../shade/renderer/animation/pose/PosePlayback.js";
-import { pose_evaluate_world } from "../../../shade/renderer/animation/pose/pose_evaluate_world.js";
-import { AnimationGraphSystem3 } from "../AnimationGraphSystem3.js";
-import { AnimationSystem3 } from "../AnimationSystem3.js";
-import { MeshSystem3 } from "../MeshSystem3.js";
-
-/**
- * The clip set handed to the evaluator, rebuilt per call from the systems' own entries. Nothing in
- * here outlives the call — the query is on a per-frame path and allocates nothing.
- *
- * @type {PosePlayback[]}
- */
-const PLAYBACKS = [];
-
-/**
- * Where a named part of an entity's model is, in world space.
- *
- * This is the question gameplay asks of an animated model and the only sanctioned way to ask it:
- * where does this projectile leave from, where does that effect anchor, where does the floating UI
- * hang. **The answer is computed, never read back** — GPU readback is a frame late and asynchronous,
- * so an outcome that depended on it would depend on frame pacing, and determinism and replay would
- * go with it (`EXECUTION.md` I-4).
- *
- * The pose is {@link pose_evaluate_world} over the clips the animation systems are driving: a pure
- * function of (clip set, time, weights), off the same clock the renderer is written from, which is
- * what keeps a socket on the mesh that is drawn.
- *
- * The result carries both its matrix and its components.
- *
- * @param {Transform64} result
- * @param {EntityManager} entity_manager
- * @param {number} entity
- * @param {string} node_name name the asset gave the node — a bone, a socket's bone, an effector
- * @returns {boolean} `false` when there is no such node to answer about: no mesh system is
- * registered, the model has not loaded yet, the entity has none, or the name is not in it. None of
- * the four is an error
- */
-export function query_entity_node_world_pose(result, entity_manager, entity, node_name) {
-    assert.defined(result, 'result');
-    assert.defined(entity_manager, 'entity_manager');
-    assert.isNonNegativeInteger(entity, 'entity');
-    assert.isString(node_name, 'node_name');
-
-    const meshes = entity_manager.getSystem(MeshSystem3);
-
-    if (meshes === null) {
-        // nothing draws models here, so nothing holds one to answer about
-        return false;
-    }
-
-    const instance = meshes.instance_of(entity);
-
-    if (instance === null) {
-        return false;
-    }
-
-    const node = instance.nodes.get(node_name);
-
-    if (node === undefined) {
-        return false;
-    }
-
-    const playbacks = PLAYBACKS;
-
-    playbacks.length = 0;
-
-    write_playbacks(playbacks, entity_manager, entity);
-
-    pose_evaluate_world(result, node, playbacks);
-
-    playbacks.length = 0;
-
-    return true;
-}
-
-/**
- * Collect what every animation driver is playing on the entity.
- *
- * Both are asked because either may be the one driving it — a combat unit runs a state machine, a
- * building runs a clip list — and an entity has one of them, so the two sets do not overlap in
- * practice. What they hand back is one entry per clip of the model, silent clips included, because
- * that is what the GPU's accumulator is summing.
- *
- * @param {PosePlayback[]} target
- * @param {EntityManager} entity_manager
- * @param {number} entity
- */
-function write_playbacks(target, entity_manager, entity) {
-    const graphs = entity_manager.getSystem(AnimationGraphSystem3);
-
-    if (graphs !== null) {
-        graphs.write_pose_playbacks(target, entity);
-    }
-
-    const clips = entity_manager.getSystem(AnimationSystem3);
-
-    if (clips !== null) {
-        clips.write_pose_playbacks(target, entity);
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { PosePlayback } from "../../../shade/renderer/animation/pose/PosePlayback.js";
+import { pose_evaluate_world } from "../../../shade/renderer/animation/pose/pose_evaluate_world.js";
+import { AnimationGraphSystem } from "../AnimationGraphSystem.js";
+import { AnimationSystem } from "../AnimationSystem.js";
+import { MeshSystem } from "../MeshSystem.js";
+
+/**
+ * The clip set handed to the evaluator, rebuilt per call from the systems' own entries. Nothing in
+ * here outlives the call — the query is on a per-frame path and allocates nothing.
+ *
+ * @type {PosePlayback[]}
+ */
+const PLAYBACKS = [];
+
+/**
+ * Where a named part of an entity's model is, in world space.
+ *
+ * This is the question gameplay asks of an animated model and the only sanctioned way to ask it:
+ * where does this projectile leave from, where does that effect anchor, where does the floating UI
+ * hang. **The answer is computed, never read back** — GPU readback is a frame late and asynchronous,
+ * so an outcome that depended on it would depend on frame pacing, and determinism and replay would
+ * go with it: no GPU readback on a gameplay-affecting path.
+ *
+ * The pose is {@link pose_evaluate_world} over the clips the animation systems are driving: a pure
+ * function of (clip set, time, weights), off the same clock the renderer is written from, which is
+ * what keeps a socket on the mesh that is drawn.
+ *
+ * The result carries both its matrix and its components.
+ *
+ * @param {Transform64} result
+ * @param {EntityManager} entity_manager
+ * @param {number} entity
+ * @param {string} node_name name the asset gave the node — a bone, a socket's bone, an effector
+ * @returns {boolean} `false` when there is no such node to answer about: no mesh system is
+ * registered, the model has not loaded yet, the entity has none, or the name is not in it. None of
+ * the four is an error
+ */
+export function query_entity_node_world_pose(result, entity_manager, entity, node_name) {
+    assert.defined(result, 'result');
+    assert.defined(entity_manager, 'entity_manager');
+    assert.isNonNegativeInteger(entity, 'entity');
+    assert.isString(node_name, 'node_name');
+
+    const meshes = entity_manager.getSystem(MeshSystem);
+
+    if (meshes === null) {
+        // nothing draws models here, so nothing holds one to answer about
+        return false;
+    }
+
+    const instance = meshes.instance_of(entity);
+
+    if (instance === null) {
+        return false;
+    }
+
+    const node = instance.nodes.get(node_name);
+
+    if (node === undefined) {
+        return false;
+    }
+
+    const playbacks = PLAYBACKS;
+
+    playbacks.length = 0;
+
+    write_playbacks(playbacks, entity_manager, entity);
+
+    pose_evaluate_world(result, node, playbacks);
+
+    playbacks.length = 0;
+
+    return true;
+}
+
+/**
+ * Collect what every animation driver is playing on the entity.
+ *
+ * Both are asked because either may be the one driving it — a combat unit runs a state machine, a
+ * building runs a clip list — and an entity has one of them, so the two sets do not overlap in
+ * practice. What they hand back is one entry per clip of the model, silent clips included, because
+ * that is what the GPU's accumulator is summing.
+ *
+ * @param {PosePlayback[]} target
+ * @param {EntityManager} entity_manager
+ * @param {number} entity
+ */
+function write_playbacks(target, entity_manager, entity) {
+    const graphs = entity_manager.getSystem(AnimationGraphSystem);
+
+    if (graphs !== null) {
+        graphs.write_pose_playbacks(target, entity);
+    }
+
+    const clips = entity_manager.getSystem(AnimationSystem);
+
+    if (clips !== null) {
+        clips.write_pose_playbacks(target, entity);
+    }
+}

package/src/engine/graphics3/preview/make_model_thumbnail.d.ts

@@ -3,19 +3,19 @@
  *
  * The four steps are each somebody's: where the model is (`shade_bundle_bounds`), how to frame it
  * (`model_preview_framing`), what a scene of one model looks like (`make_model_preview_scene`), and
- * how a frame becomes pixels (`GraphicsEngine3.render_to_sampler`). This is only the order.
+ * how a frame becomes pixels (`GraphicsEngine.render_to_sampler`). This is only the order.
  *
  * **A model with nothing to draw has no picture, and that is data rather than a fault**: a glTF of
  * empties, or one whose every mesh is skinned — a preview scene registers no skin, so a skinned
  * mesh is not in it. The answer then is `null`, and a caller showing icons shows none for that
  * asset rather than a blank square that reads as a broken renderer.
  *
- * @param {GraphicsEngine3} graphics
+ * @param {GraphicsEngine} graphics
  * @param {SceneBundle} bundle
  * @param {number} width texels
  * @param {number} height texels
  * @param {number} [margin] fraction of the frame's height left clear around the model
  * @returns {Promise<Sampler2D|null>}
  */
-export function make_model_thumbnail(graphics: GraphicsEngine3, bundle: SceneBundle, width: number, height: number, margin?: number): Promise<Sampler2D | null>;
+export function make_model_thumbnail(graphics: GraphicsEngine, bundle: SceneBundle, width: number, height: number, margin?: number): Promise<Sampler2D | null>;
 //# sourceMappingURL=make_model_thumbnail.d.ts.map

package/src/engine/graphics3/preview/make_model_thumbnail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make_model_thumbnail.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/preview/make_model_thumbnail.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;GAkBG;AACH,4FALW,MAAM,UACN,MAAM,WACN,MAAM,GACJ,QAAQ,YAAU,IAAI,CAAC,CAuBnC"}
+{"version":3,"file":"make_model_thumbnail.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/preview/make_model_thumbnail.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;GAkBG;AACH,2FALW,MAAM,UACN,MAAM,WACN,MAAM,GACJ,QAAQ,YAAU,IAAI,CAAC,CAuBnC"}

package/src/engine/graphics3/preview/make_model_thumbnail.js

@@ -1,48 +1,48 @@
-import { assert } from "../../../core/assert.js";
-import { AABB3 } from "../../../core/geom/3d/aabb/AABB3.js";
-import { shade_bundle_bounds } from "../shade_bundle_bounds.js";
-import { make_model_preview_scene, MODEL_PREVIEW_FOV } from "./make_model_preview_scene.js";
-import { model_preview_framing } from "./model_preview_framing.js";
-import { ModelPreviewFraming } from "./ModelPreviewFraming.js";
-
-/**
- * A picture of a loaded model, framed on itself.
- *
- * The four steps are each somebody's: where the model is (`shade_bundle_bounds`), how to frame it
- * (`model_preview_framing`), what a scene of one model looks like (`make_model_preview_scene`), and
- * how a frame becomes pixels (`GraphicsEngine3.render_to_sampler`). This is only the order.
- *
- * **A model with nothing to draw has no picture, and that is data rather than a fault**: a glTF of
- * empties, or one whose every mesh is skinned — a preview scene registers no skin, so a skinned
- * mesh is not in it. The answer then is `null`, and a caller showing icons shows none for that
- * asset rather than a blank square that reads as a broken renderer.
- *
- * @param {GraphicsEngine3} graphics
- * @param {SceneBundle} bundle
- * @param {number} width texels
- * @param {number} height texels
- * @param {number} [margin] fraction of the frame's height left clear around the model
- * @returns {Promise<Sampler2D|null>}
- */
-export async function make_model_thumbnail(graphics, bundle, width, height, margin = 0) {
-    assert.defined(graphics, 'graphics');
-    assert.defined(bundle, 'bundle');
-
-    // held locally rather than in module scratch: a caller may have several thumbnails in flight,
-    // and what each of them is framing must not be what the last one was
-    const bounds = new AABB3();
-
-    if (!shade_bundle_bounds(bounds, bundle)) {
-        return null;
-    }
-
-    const framing = model_preview_framing(new ModelPreviewFraming(), bounds, MODEL_PREVIEW_FOV, margin);
-
-    const { scene, camera, drawn } = make_model_preview_scene(bundle, framing, width / height);
-
-    if (drawn === 0) {
-        return null;
-    }
-
-    return graphics.render_to_sampler(scene, camera, width, height);
-}
+import { assert } from "../../../core/assert.js";
+import { AABB3 } from "../../../core/geom/3d/aabb/AABB3.js";
+import { shade_bundle_bounds } from "../shade_bundle_bounds.js";
+import { make_model_preview_scene, MODEL_PREVIEW_FOV } from "./make_model_preview_scene.js";
+import { model_preview_framing } from "./model_preview_framing.js";
+import { ModelPreviewFraming } from "./ModelPreviewFraming.js";
+
+/**
+ * A picture of a loaded model, framed on itself.
+ *
+ * The four steps are each somebody's: where the model is (`shade_bundle_bounds`), how to frame it
+ * (`model_preview_framing`), what a scene of one model looks like (`make_model_preview_scene`), and
+ * how a frame becomes pixels (`GraphicsEngine.render_to_sampler`). This is only the order.
+ *
+ * **A model with nothing to draw has no picture, and that is data rather than a fault**: a glTF of
+ * empties, or one whose every mesh is skinned — a preview scene registers no skin, so a skinned
+ * mesh is not in it. The answer then is `null`, and a caller showing icons shows none for that
+ * asset rather than a blank square that reads as a broken renderer.
+ *
+ * @param {GraphicsEngine} graphics
+ * @param {SceneBundle} bundle
+ * @param {number} width texels
+ * @param {number} height texels
+ * @param {number} [margin] fraction of the frame's height left clear around the model
+ * @returns {Promise<Sampler2D|null>}
+ */
+export async function make_model_thumbnail(graphics, bundle, width, height, margin = 0) {
+    assert.defined(graphics, 'graphics');
+    assert.defined(bundle, 'bundle');
+
+    // held locally rather than in module scratch: a caller may have several thumbnails in flight,
+    // and what each of them is framing must not be what the last one was
+    const bounds = new AABB3();
+
+    if (!shade_bundle_bounds(bounds, bundle)) {
+        return null;
+    }
+
+    const framing = model_preview_framing(new ModelPreviewFraming(), bounds, MODEL_PREVIEW_FOV, margin);
+
+    const { scene, camera, drawn } = make_model_preview_scene(bundle, framing, width / height);
+
+    if (drawn === 0) {
+        return null;
+    }
+
+    return graphics.render_to_sampler(scene, camera, width, height);
+}

package/src/engine/graphics3/shade_camera_projection_ray.d.ts

@@ -6,7 +6,7 @@
  * where it used to be.
  *
  * `x` and `y` are **clip-space**, in −1…1 with +Y up, which is what
- * `GraphicsEngine3.normalizeViewportPoint` produces from pixels.
+ * `GraphicsEngine.normalizeViewportPoint` produces from pixels.
  *
  * The origin is the camera's own position, which is right for a perspective camera and is also what
  * the three-based engine did for both kinds. A true orthographic pick wants parallel rays from the