@woosh/meep-engine 3.28.0 → 3.30.0

package/src/shade/renderer/geometry/virtual/build/mesh/VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.d.ts

@@ -0,0 +1,74 @@
+/**
+ * What a full unit of each channel is worth in position error, as a fraction of the geometry's own
+ * bounding-box diagonal. See {@link VGeoBuildOptions#attribute_weight_ratios}.
+ *
+ * ## What the number does and does not control
+ *
+ * It does **not** control the value a coarse vertex carries. That is a least-squares fit to the
+ * accumulated fields, and the weight cancels out of it exactly — multiplied in when the quadric is
+ * built, divided out when it is solved. The fit is the larger of the two wins by a long way and it
+ * needs no tuning at all.
+ *
+ * What the number controls is how much the channels get to move the vertex and price the collapse.
+ * A collapse that would smear a crease is charged for it, in units of length, at exactly the rate
+ * this names.
+ *
+ * ## How it was chosen — and why that needs doing again
+ *
+ * Swept from `1e-9` — the term effectively off — to `1/2`, measuring how far the shipped normal field
+ * sits from the source's and what happened to `self_error`, which is the number the runtime's cut is
+ * driven by.
+ *
+ * **The `self_error` column below is a reading this metric no longer takes.** It was swept when the
+ * error was one post-hoc sweep of the surviving vertices, over quadrics that weighed a plane count —
+ * a mean that diluted with DAG depth and tracked tessellation rather than surface. Both are fixed
+ * (`VIRTUAL_GEOMETRY_DESIGN.md` §4), which moved the number the sweep was reading and changed the
+ * matrix that decides where a collapse puts the vertex, which is what this ratio trades against. The
+ * *shape* of the finding is unlikely to have moved — above `1/64` it was not a trade on smooth
+ * content by an order of magnitude — but the cliff's position is not known any more, and `1/1024`
+ * stands here because it was left deliberately untouched rather than because it has been re-measured
+ * against the metric that now ships. Re-sweeping it is its own work.
+ *
+ * On a 31,874-triangle Zorah primitive, the content the defect was found on:
+ *
+ * ```
+ * ratio      normal error, mean over the DAG      self_error at the root
+ * 1e-9       2.076 deg                            1.00x
+ * 1/1024     1.857 deg                            1.08x
+ * 1/64       1.807 deg                            1.35x
+ * 1/8        2.059 deg                           18.09x
+ * 1/4        2.191 deg                            6.81x
+ * 1/2        2.326 deg                           14.02x
+ * ```
+ *
+ * Above `1/64` it is not a trade, it is a loss: eighteen times the geometric error for a normal field
+ * that is *worse* than leaving the term off. The reason is that this content is mostly smooth, and on
+ * smooth geometry there is no crease for the term to defend — a 48x24 sphere reads 5.29 degrees of
+ * worst-case normal error at every ratio from `1e-9` to `1/4`, unchanged to three figures.
+ *
+ * So `1/1024`: inside the 20% the plan allows `self_error` to move, worth about a tenth of a degree,
+ * and far enough below the cliff that no content falls off it by accident.
+ *
+ * ## When to raise it
+ *
+ * Content with hard creases, which is what the term is actually for. A cube subdivided sixteen ways
+ * per face — flat faces meeting at right angles, where collapsing *within* a face costs exactly zero
+ * geometric error and the metric has nothing else to say — goes from 14.9 degrees of worst-case
+ * normal error to **1.38** at `1/4`. (Subdivided twenty-four ways it reads a hundredth of a degree at
+ * every ratio, which is how sharply this depends on the geometry rather than on the setting.) That
+ * is the trade the number exists to make, and it is a per-asset decision rather than a default,
+ * because the same setting on Zorah costs seven times the error for nothing.
+ *
+ * The other channels take the same ratio for want of their own measurement. A texture coordinate and
+ * a colour are bounded the way a normal component is — roughly `[0, 1]`, roughly `[-1, 1]` — so the
+ * number is at least in the right place, and none of the content this was measured on carries them.
+ * Naming that here rather than implying they were each swept.
+ *
+ * @readonly
+ * @type {number[]}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS: number[];
+//# sourceMappingURL=VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.d.ts.map

package/src/shade/renderer/geometry/virtual/build/mesh/VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,mDALU,MAAM,EAAE,CAOhB"}

package/src/shade/renderer/geometry/virtual/build/mesh/VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.js

@@ -0,0 +1,78 @@
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
+import { VGEO_ATTRIBUTES } from "../../format/attribute/VGEO_ATTRIBUTES.js";
+
+/**
+ * What a full unit of each channel is worth in position error, as a fraction of the geometry's own
+ * bounding-box diagonal. See {@link VGeoBuildOptions#attribute_weight_ratios}.
+ *
+ * ## What the number does and does not control
+ *
+ * It does **not** control the value a coarse vertex carries. That is a least-squares fit to the
+ * accumulated fields, and the weight cancels out of it exactly — multiplied in when the quadric is
+ * built, divided out when it is solved. The fit is the larger of the two wins by a long way and it
+ * needs no tuning at all.
+ *
+ * What the number controls is how much the channels get to move the vertex and price the collapse.
+ * A collapse that would smear a crease is charged for it, in units of length, at exactly the rate
+ * this names.
+ *
+ * ## How it was chosen — and why that needs doing again
+ *
+ * Swept from `1e-9` — the term effectively off — to `1/2`, measuring how far the shipped normal field
+ * sits from the source's and what happened to `self_error`, which is the number the runtime's cut is
+ * driven by.
+ *
+ * **The `self_error` column below is a reading this metric no longer takes.** It was swept when the
+ * error was one post-hoc sweep of the surviving vertices, over quadrics that weighed a plane count —
+ * a mean that diluted with DAG depth and tracked tessellation rather than surface. Both are fixed
+ * (`VIRTUAL_GEOMETRY_DESIGN.md` §4), which moved the number the sweep was reading and changed the
+ * matrix that decides where a collapse puts the vertex, which is what this ratio trades against. The
+ * *shape* of the finding is unlikely to have moved — above `1/64` it was not a trade on smooth
+ * content by an order of magnitude — but the cliff's position is not known any more, and `1/1024`
+ * stands here because it was left deliberately untouched rather than because it has been re-measured
+ * against the metric that now ships. Re-sweeping it is its own work.
+ *
+ * On a 31,874-triangle Zorah primitive, the content the defect was found on:
+ *
+ * ```
+ * ratio      normal error, mean over the DAG      self_error at the root
+ * 1e-9       2.076 deg                            1.00x
+ * 1/1024     1.857 deg                            1.08x
+ * 1/64       1.807 deg                            1.35x
+ * 1/8        2.059 deg                           18.09x
+ * 1/4        2.191 deg                            6.81x
+ * 1/2        2.326 deg                           14.02x
+ * ```
+ *
+ * Above `1/64` it is not a trade, it is a loss: eighteen times the geometric error for a normal field
+ * that is *worse* than leaving the term off. The reason is that this content is mostly smooth, and on
+ * smooth geometry there is no crease for the term to defend — a 48x24 sphere reads 5.29 degrees of
+ * worst-case normal error at every ratio from `1e-9` to `1/4`, unchanged to three figures.
+ *
+ * So `1/1024`: inside the 20% the plan allows `self_error` to move, worth about a tenth of a degree,
+ * and far enough below the cliff that no content falls off it by accident.
+ *
+ * ## When to raise it
+ *
+ * Content with hard creases, which is what the term is actually for. A cube subdivided sixteen ways
+ * per face — flat faces meeting at right angles, where collapsing *within* a face costs exactly zero
+ * geometric error and the metric has nothing else to say — goes from 14.9 degrees of worst-case
+ * normal error to **1.38** at `1/4`. (Subdivided twenty-four ways it reads a hundredth of a degree at
+ * every ratio, which is how sharply this depends on the geometry rather than on the setting.) That
+ * is the trade the number exists to make, and it is a per-asset decision rather than a default,
+ * because the same setting on Zorah costs seven times the error for nothing.
+ *
+ * The other channels take the same ratio for want of their own measurement. A texture coordinate and
+ * a colour are bounded the way a normal component is — roughly `[0, 1]`, roughly `[-1, 1]` — so the
+ * number is at least in the right place, and none of the content this was measured on carries them.
+ * Naming that here rather than implying they were each swept.
+ *
+ * @readonly
+ * @type {number[]}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS = Object.freeze(
+    VGEO_ATTRIBUTES.map((_, attribute) => attribute === VGEO_ATTRIBUTE.POSITION ? 0 : 1 / 1024)
+);

package/src/shade/renderer/geometry/virtual/build/mesh/VirtualGeometryMesh.d.ts

@@ -2,11 +2,15 @@
  * A level of geometry as the builder handles it: a `BinaryTopology` carrying the positions, the
  * connectivity, and the per-vertex attributes all together.
  *
- * Everything per-vertex lives in the topology. It has to: an edge collapse moves and removes
- * vertices, and the topology is the only thing that knows which. A vertex data layer is addressed
- * by vertex id and sized by the vertex pool, so a channel cannot fall out of step with the mesh it
- * describes — there is no second array to resize, no invariant to assert, and no way for the
- * simplifier to leave a live vertex without a slot.
+ * Everything per-element lives in the topology. It has to: a collapse moves and removes vertices and
+ * kills faces, and the topology is the only thing that knows which. A data layer is sized by its own
+ * pool, so a channel cannot fall out of step with the mesh it describes — there is no second array
+ * to resize, no invariant to assert, and no way for the simplifier to leave a live element without a
+ * slot.
+ *
+ * **Position is the vertex's; appearance is the corner's.** A hard edge and a texture seam are both
+ * one geometric vertex that shades two ways, and no per-vertex record can hold that — so the
+ * channels are loop data. See `WEDGE_PLAN_2026_09_18.md` §2.
  *
  * The channels are named by their index into {@link VGEO_ATTRIBUTES}, which is the format's frozen
  * table — {@link layers} has one slot per entry, holding a layer or null.
@@ -42,9 +46,10 @@ export class VirtualGeometryMesh {
      */
     topology: BinaryTopology;
     /**
-     * One slot per {@link VGEO_ATTRIBUTES} entry, holding the vertex data layer that carries that
+     * One slot per {@link VGEO_ATTRIBUTES} entry, holding the **loop** data layer that carries that
      * channel or null where this geometry does not carry it.
-     * {@link VGEO_ATTRIBUTE.POSITION}'s slot is always null — position is the topology's own.
+     * {@link VGEO_ATTRIBUTE.POSITION}'s slot is always null — position is the topology's own, and is
+     * the one value that really is a vertex's rather than a corner's.
      * @type {(BinaryDataLayer|null)[]}
      */
     layers: (BinaryDataLayer | null)[];

package/src/shade/renderer/geometry/virtual/build/mesh/VirtualGeometryMesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualGeometryMesh.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/VirtualGeometryMesh.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;GAeG;AACH;IA6CI;;;;;;;;;;;;;;OAcG;IACH,0CAFa,mBAAmB,CA8G/B;IAzID;;;OAGG;IACH,sBAHW,cAAc,UACd,CAAC,kBAAgB,IAAI,CAAC,EAAE,EAUlC;IA1CD;;;OAGG;IACH,UAFU,cAAc,CAER;IAEhB;;;;;OAKG;IACH,QAFU,CAAC,kBAAgB,IAAI,CAAC,EAAE,CAEtB;IAEZ;;;;;;;;;;;;;OAaG;IACH,aAFU,OAAO,EAAE,CAEyC;IA6I5D;;;OAGG;IACH,YAFa,MAAM,EAAE,CAcpB;CACJ;+BApN8B,yEAAyE"}
+{"version":3,"file":"VirtualGeometryMesh.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/VirtualGeometryMesh.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IA8CI;;;;;;;;;;;;;;OAcG;IACH,0CAFa,mBAAmB,CA+H/B;IA1JD;;;OAGG;IACH,sBAHW,cAAc,UACd,CAAC,kBAAgB,IAAI,CAAC,EAAE,EAUlC;IA3CD;;;OAGG;IACH,UAFU,cAAc,CAER;IAEhB;;;;;;OAMG;IACH,QAFU,CAAC,kBAAgB,IAAI,CAAC,EAAE,CAEtB;IAEZ;;;;;;;;;;;;;OAaG;IACH,aAFU,OAAO,EAAE,CAEyC;IA8J5D;;;OAGG;IACH,YAFa,MAAM,EAAE,CAcpB;CACJ;+BA1O8B,yEAAyE"}

package/src/shade/renderer/geometry/virtual/build/mesh/VirtualGeometryMesh.js

@@ -12,11 +12,15 @@ import { VGEO_ATTRIBUTES } from "../../format/attribute/VGEO_ATTRIBUTES.js";
  * A level of geometry as the builder handles it: a `BinaryTopology` carrying the positions, the
  * connectivity, and the per-vertex attributes all together.
  *
- * Everything per-vertex lives in the topology. It has to: an edge collapse moves and removes
- * vertices, and the topology is the only thing that knows which. A vertex data layer is addressed
- * by vertex id and sized by the vertex pool, so a channel cannot fall out of step with the mesh it
- * describes — there is no second array to resize, no invariant to assert, and no way for the
- * simplifier to leave a live vertex without a slot.
+ * Everything per-element lives in the topology. It has to: a collapse moves and removes vertices and
+ * kills faces, and the topology is the only thing that knows which. A data layer is sized by its own
+ * pool, so a channel cannot fall out of step with the mesh it describes — there is no second array
+ * to resize, no invariant to assert, and no way for the simplifier to leave a live element without a
+ * slot.
+ *
+ * **Position is the vertex's; appearance is the corner's.** A hard edge and a texture seam are both
+ * one geometric vertex that shades two ways, and no per-vertex record can hold that — so the
+ * channels are loop data. See `WEDGE_PLAN_2026_09_18.md` §2.
  *
  * The channels are named by their index into {@link VGEO_ATTRIBUTES}, which is the format's frozen
  * table — {@link layers} has one slot per entry, holding a layer or null.
@@ -32,9 +36,10 @@ export class VirtualGeometryMesh {
     topology = null;
 
     /**
-     * One slot per {@link VGEO_ATTRIBUTES} entry, holding the vertex data layer that carries that
+     * One slot per {@link VGEO_ATTRIBUTES} entry, holding the **loop** data layer that carries that
      * channel or null where this geometry does not carry it.
-     * {@link VGEO_ATTRIBUTE.POSITION}'s slot is always null — position is the topology's own.
+     * {@link VGEO_ATTRIBUTE.POSITION}'s slot is always null — position is the topology's own, and is
+     * the one value that really is a vertex's rather than a corner's.
      * @type {(BinaryDataLayer|null)[]}
      */
     layers = [];
@@ -163,14 +168,17 @@ export class VirtualGeometryMesh {
 
         const topology = new BinaryTopology();
 
-        // Declared before the vertices exist: adding a layer widens every record already in the
-        // block, so a channel set is cheapest to state while there is nothing to widen.
+        // Declared before the mesh exists: adding a layer widens every record already in the block,
+        // and the block these go in is the *loop* block, which a triangulated source fills three
+        // records at a time. Cheapest to state while there is nothing to widen.
         const layers = vgeo_layers_declare(topology, carried);
 
         bt_mesh_from_indexed_geometry(
             topology, indices.subarray(0, triangle_count * 3), position.data
         );
 
+        const loop_pool = topology.loops;
+
         for (let attribute = 0; attribute < VGEO_ATTRIBUTES.length; attribute++) {
             const layer = layers[attribute];
 
@@ -182,8 +190,22 @@ export class VirtualGeometryMesh {
             const source = sources[attribute];
             const components = VGEO_ATTRIBUTES[attribute].components;
 
-            for (let vertex = 0; vertex < vertex_count; vertex++) {
-                layer.write(vertex, source.data, vertex * components);
+            /*
+             Per corner, through the vertex it names. A geometry's own attributes are per vertex,
+             which is the representation that cannot hold a seam — what a source splits, it splits by
+             *duplicating the vertex*, and the weld in `vgeo_normalize_source` is what then throws
+             that away. Reading them out per corner here is what gives the weld something to preserve
+             (`WEDGE_PLAN_2026_09_18.md` §6.2); until it does, every corner of a vertex gets the same
+             value and nothing downstream can tell.
+             */
+            for (let loop = 0; loop < loop_pool.size; loop++) {
+                if (!loop_pool.is_allocated(loop)) {
+                    continue;
+                }
+
+                layer.write(
+                    loop, source.data, topology.loop_read_vertex(loop) * components
+                );
             }
         }
 

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_layout.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Which of a mesh's channels travel through a collapse as plain numbers, and where each one sits in
+ * the flat vector that carries them.
+ *
+ * The simplifier moves vertices and merges them, and whatever a merged vertex is to shade as has to
+ * be decided *at the collapse*, from the values being merged — not re-derived afterwards from the
+ * coarse mesh, which is a different surface (`ATTRIBUTE_PLAN_2026_09_18.md` §1.2). So the channels
+ * are flattened into one array indexed by vertex, handed to the simplifier, and written back.
+ *
+ * Two channels are not simply `components` wide here:
+ *
+ * - **Position** is not in the vector at all. It lives in the topology, where the quadric solve
+ *   moves it.
+ * - **Tangent** contributes its `xyz` to the fitted vector and its fourth component to a second,
+ *   **verbatim** one. That component is a handedness flag — a discrete `±1` — and the average of
+ *   `+1` and `-1` is a number that means nothing, so it is carried rather than fitted: a survivor
+ *   keeps the flag it had.
+ *
+ *   It has to be *carried*, and leaving the stored record alone is not enough. A collapse re-points
+ *   the victim's corners onto the survivor and they arrive with the victim's flag, so "the
+ *   survivor's" has to be written back over them — which is what the verbatim vector is for. Left
+ *   alone, one vertex of a cube-sphere comes out of a cut with two different tangents in two
+ *   payloads, and that is the seam invariant broken.
+ *
+ * And the tangent is here **only when the mesh carries `UV0`**. A tangent is a direction in the
+ * texture parameterization; with no parameterization there is nothing for it to be tangent to, and
+ * the frame is an arbitrary well-conditioned basis around the normal — which
+ * {@link vgeo_compute_vertex_tangents} already builds, on this same condition, and which is a *pure
+ * function of the normal*. Deriving it is therefore both cheaper and safer than carrying it:
+ * Frisvad's basis turns discontinuously with the normal, so two neighbours' tangents can be nearly
+ * opposite and average to nothing at all.
+ *
+ * @param {(BinaryDataLayer|null)[]} layers channel set, as {@link vgeo_layers_declare} builds one
+ * @returns {{components: number, channels: {attribute: number, offset: number, source: number, count: number}[], verbatim_components: number, verbatim: {attribute: number, offset: number, source: number, count: number}[]}}
+ *     two vectors: the one the simplifier fits, and the one it never touches. `source` is where a
+ *     channel's run starts *within the layer's own record*, which is `0` for everything but the
+ *     handedness. A mesh carrying no travelling channel at all comes back with zero of both.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_attribute_vector_layout(layers: (BinaryDataLayer | null)[]): {
+    components: number;
+    channels: {
+        attribute: number;
+        offset: number;
+        source: number;
+        count: number;
+    }[];
+    verbatim_components: number;
+    verbatim: {
+        attribute: number;
+        offset: number;
+        source: number;
+        count: number;
+    }[];
+};
+//# sourceMappingURL=vgeo_attribute_vector_layout.d.ts.map

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_attribute_vector_layout.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_layout.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qDATW,CAAC,kBAAgB,IAAI,CAAC,EAAE,GACtB;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,EAAE,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,EAAE,CAAA;CAAC,CA0C7N"}

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_layout.js

@@ -0,0 +1,79 @@
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
+import { VGEO_ATTRIBUTES } from "../../format/attribute/VGEO_ATTRIBUTES.js";
+
+/**
+ * Which of a mesh's channels travel through a collapse as plain numbers, and where each one sits in
+ * the flat vector that carries them.
+ *
+ * The simplifier moves vertices and merges them, and whatever a merged vertex is to shade as has to
+ * be decided *at the collapse*, from the values being merged — not re-derived afterwards from the
+ * coarse mesh, which is a different surface (`ATTRIBUTE_PLAN_2026_09_18.md` §1.2). So the channels
+ * are flattened into one array indexed by vertex, handed to the simplifier, and written back.
+ *
+ * Two channels are not simply `components` wide here:
+ *
+ * - **Position** is not in the vector at all. It lives in the topology, where the quadric solve
+ *   moves it.
+ * - **Tangent** contributes its `xyz` to the fitted vector and its fourth component to a second,
+ *   **verbatim** one. That component is a handedness flag — a discrete `±1` — and the average of
+ *   `+1` and `-1` is a number that means nothing, so it is carried rather than fitted: a survivor
+ *   keeps the flag it had.
+ *
+ *   It has to be *carried*, and leaving the stored record alone is not enough. A collapse re-points
+ *   the victim's corners onto the survivor and they arrive with the victim's flag, so "the
+ *   survivor's" has to be written back over them — which is what the verbatim vector is for. Left
+ *   alone, one vertex of a cube-sphere comes out of a cut with two different tangents in two
+ *   payloads, and that is the seam invariant broken.
+ *
+ * And the tangent is here **only when the mesh carries `UV0`**. A tangent is a direction in the
+ * texture parameterization; with no parameterization there is nothing for it to be tangent to, and
+ * the frame is an arbitrary well-conditioned basis around the normal — which
+ * {@link vgeo_compute_vertex_tangents} already builds, on this same condition, and which is a *pure
+ * function of the normal*. Deriving it is therefore both cheaper and safer than carrying it:
+ * Frisvad's basis turns discontinuously with the normal, so two neighbours' tangents can be nearly
+ * opposite and average to nothing at all.
+ *
+ * @param {(BinaryDataLayer|null)[]} layers channel set, as {@link vgeo_layers_declare} builds one
+ * @returns {{components: number, channels: {attribute: number, offset: number, source: number, count: number}[], verbatim_components: number, verbatim: {attribute: number, offset: number, source: number, count: number}[]}}
+ *     two vectors: the one the simplifier fits, and the one it never touches. `source` is where a
+ *     channel's run starts *within the layer's own record*, which is `0` for everything but the
+ *     handedness. A mesh carrying no travelling channel at all comes back with zero of both.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_attribute_vector_layout(layers) {
+    const channels = [];
+    const verbatim = [];
+
+    let components = 0;
+    let verbatim_components = 0;
+
+    for (let attribute = 0; attribute < VGEO_ATTRIBUTES.length; attribute++) {
+        if (attribute === VGEO_ATTRIBUTE.POSITION || layers[attribute] === null) {
+            continue;
+        }
+
+        if (attribute === VGEO_ATTRIBUTE.TANGENT && layers[VGEO_ATTRIBUTE.UV0] === null) {
+            continue;
+        }
+
+        const count = attribute === VGEO_ATTRIBUTE.TANGENT
+            ? 3
+            : VGEO_ATTRIBUTES[attribute].components;
+
+        channels.push({ attribute, offset: components, source: 0, count });
+
+        components += count;
+
+        if (attribute === VGEO_ATTRIBUTE.TANGENT) {
+            verbatim.push({
+                attribute, offset: verbatim_components, source: 3, count: 1,
+            });
+
+            verbatim_components += 1;
+        }
+    }
+
+    return { components, channels, verbatim_components, verbatim };
+}

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_read.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Lift a mesh's travelling channels out of its layers and into one flat vector the simplifier can
+ * carry through a collapse.
+ *
+ * Indexed by **wedge id**, holes and all, so a set with merged-away slots needs no compaction and
+ * no remap — the simplifier addresses wedges by id and nothing else would line up. A dead slot
+ * holds whatever the wedge that used to be a root left behind, which nothing reads.
+ *
+ * The values are stored per *corner* and read per *wedge*, and a wedge is by definition a set of
+ * corners that carry the same value. Each corner of a wedge writes over the last and it does not
+ * matter which one wins — **which is a checkable claim rather than an assumed one**, and the
+ * difference from §6.1 is exactly that: there, a *vertex* was asserted to have one appearance, and
+ * a hard edge is a vertex that does not.
+ *
+ * Float64 rather than the layers' float32: a value is blended at every collapse it survives, dozens
+ * of times over a deep DAG, and rounding to storage precision at each step is error the vector has
+ * no reason to accumulate. It is narrowed once, on the way back out
+ * ({@link vgeo_attribute_vector_write}).
+ *
+ * Takes a stride and a channel list rather than the whole layout, because there are two vectors and
+ * they differ only in which list they are over — the one the simplifier fits, and the one it never
+ * touches (`vgeo_attribute_vector_layout`'s `verbatim`).
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {number} components stride of one wedge's record
+ * @param {{attribute: number, offset: number, source: number, count: number}[]} channels
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one
+ * @returns {Float64Array} `wedges.count * components` elements
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_attribute_vector_read(mesh: VirtualGeometryMesh, components: number, channels: {
+    attribute: number;
+    offset: number;
+    source: number;
+    count: number;
+}[], wedges: BtWedgeSet): Float64Array;
+//# sourceMappingURL=vgeo_attribute_vector_read.d.ts.map

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_attribute_vector_read.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_read.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,kFARW,MAAM,YACN;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,EAAE,uBAElE,YAAY,CAgCxB"}

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_read.js

@@ -0,0 +1,68 @@
+import { assert } from "../../../../../../core/assert.js";
+
+/**
+ * One vertex's widest channel record on its way out of a layer.
+ * @type {Float32Array}
+ */
+const scratch_record = new Float32Array(4);
+
+/**
+ * Lift a mesh's travelling channels out of its layers and into one flat vector the simplifier can
+ * carry through a collapse.
+ *
+ * Indexed by **wedge id**, holes and all, so a set with merged-away slots needs no compaction and
+ * no remap — the simplifier addresses wedges by id and nothing else would line up. A dead slot
+ * holds whatever the wedge that used to be a root left behind, which nothing reads.
+ *
+ * The values are stored per *corner* and read per *wedge*, and a wedge is by definition a set of
+ * corners that carry the same value. Each corner of a wedge writes over the last and it does not
+ * matter which one wins — **which is a checkable claim rather than an assumed one**, and the
+ * difference from §6.1 is exactly that: there, a *vertex* was asserted to have one appearance, and
+ * a hard edge is a vertex that does not.
+ *
+ * Float64 rather than the layers' float32: a value is blended at every collapse it survives, dozens
+ * of times over a deep DAG, and rounding to storage precision at each step is error the vector has
+ * no reason to accumulate. It is narrowed once, on the way back out
+ * ({@link vgeo_attribute_vector_write}).
+ *
+ * Takes a stride and a channel list rather than the whole layout, because there are two vectors and
+ * they differ only in which list they are over — the one the simplifier fits, and the one it never
+ * touches (`vgeo_attribute_vector_layout`'s `verbatim`).
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {number} components stride of one wedge's record
+ * @param {{attribute: number, offset: number, source: number, count: number}[]} channels
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one
+ * @returns {Float64Array} `wedges.count * components` elements
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_attribute_vector_read(mesh, components, channels, wedges) {
+    assert.greaterThan(components, 0, 'components');
+
+    const topology = mesh.topology;
+
+    const values = new Float64Array(wedges.count * components);
+
+    const loop_pool = topology.loops;
+
+    for (let loop = 0; loop < loop_pool.size; loop++) {
+        if (!loop_pool.is_allocated(loop)) {
+            continue;
+        }
+
+        const base = wedges.find(wedges.of_loop[loop]) * components;
+
+        for (const channel of channels) {
+            mesh.layers[channel.attribute].read(scratch_record, 0, loop);
+
+            for (let component = 0; component < channel.count; component++) {
+                values[base + channel.offset + component] =
+                    scratch_record[channel.source + component];
+            }
+        }
+    }
+
+    return values;
+}

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_write.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Put the simplifier's vector back into the mesh's layers, and square up the frame it describes.
+ *
+ * **Nothing is *derived* for a pinned vertex.** That is the whole of what pinning means here and it
+ * is what lets a cut place two levels of detail side by side: a vertex two groups share must carry
+ * byte-identical values in both payloads, or the seam that is watertight in geometry shades as a
+ * crease (`ATTRIBUTE_PLAN_2026_09_18.md` §3, invariant 2).
+ *
+ * Its corners are still *written*, with what the vector says it already had, and that is not a
+ * loophole — it is the same guarantee under corner storage. A collapse re-points the victim's corners
+ * onto the survivor and they arrive carrying the victim's appearance, so leaving a pinned vertex
+ * alone no longer means leaving its value alone. The write is exact: those float32 records are where
+ * the vector was read from.
+ *
+ * Two channels need more than a copy:
+ *
+ * - **The normal** is renormalized. A blend of two unit vectors is not one, and a normal that is
+ *   not unit is not a normal. Two exactly opposing normals blend to nothing, which has no direction
+ *   to report and so keeps whatever the vertex already carried, the same answer
+ *   {@link bt_mesh_compute_vertex_normals} gives for a vertex whose faces cancel.
+ * - **The colour** is clamped to `[0, 1]`. The value a collapse carries is a *fit*, not an average,
+ *   and a fit extrapolates — which is right for a texture coordinate and wrong for a channel with a
+ *   range. The encoder saturates anyway, so what this stops is not a corrupt word but the drift:
+ *   an out-of-range value left in the layer is what the next level's field is fitted from, and it
+ *   would walk further out at every round.
+ * - **The tangent** is re-orthogonalized against that normal and renormalized, and its fourth
+ *   component — handedness, a discrete `±1` — is left exactly as the survivor had it, because it is
+ *   a flag rather than a quantity and there is no average of `+1` and `-1`. A tangent that has
+ *   blended its way onto the normal has no perpendicular component left to keep, and falls back to
+ *   Frisvad's basis rather than to a zero vector the octahedral encoder cannot represent.
+ *
+ * @param {VirtualGeometryMesh} mesh mutated in place
+ * @param {{components: number, channels: {attribute: number, offset: number, count: number}[]}} layout
+ *     from {@link vgeo_attribute_vector_layout}, the same one {@link vgeo_attribute_vector_read} used
+ * @param {Float64Array} values indexed by wedge id, as the simplifier left it
+ * @param {Float64Array|null} verbatim indexed by wedge id, as it was read — the simplifier does not
+ *     take it and has nothing to say about it. `null` where the layout has no such component, which
+ *     is every mesh whose tangent is derived rather than carried.
+ * @param {Set<number>} pinned vertex ids nothing may be *derived* for
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one, as the simplifier left it
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_attribute_vector_write(mesh: VirtualGeometryMesh, layout: {
+    components: number;
+    channels: {
+        attribute: number;
+        offset: number;
+        count: number;
+    }[];
+}, values: Float64Array, verbatim: Float64Array | null, pinned: Set<number>, wedges: BtWedgeSet): void;
+//# sourceMappingURL=vgeo_attribute_vector_write.d.ts.map

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_attribute_vector_write.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_write.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,+EAZW;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,EAAE,CAAA;CAAC,UAEpF,YAAY,YACZ,YAAY,GAAC,IAAI,UAGjB,IAAI,MAAM,CAAC,4BAiHrB"}