@woosh/meep-engine 3.28.0 → 3.30.0

package/src/format/image/avif/av1/util/round2.d.ts

@@ -7,8 +7,9 @@
  * guard is not cosmetic: `1 << -1` is `1 << 31` under JavaScript's shift-count masking, which would
  * silently produce garbage.
  *
- * `x` must fit in a signed 32-bit integer, which every intermediate the specification feeds to this
- * function does.
+ * `x + 2^(n-1)` must fit in a signed 32-bit integer — the rounding term is added before the shift, so
+ * the bound is slightly tighter than `x` itself. Most intermediates the specification feeds this do;
+ * the self-guided restoration box filter's do not, and use {@link round2_wide} instead.
  *
  * @param {number} x
  * @param {number} n number of bits to shift away, `>= 0`
@@ -19,4 +20,20 @@
  * @copyright Company Named Limited (c) 2026
  */
 export function round2(x: number, n: number): number;
+/**
+ * {@link round2} for operands that run past a signed 32-bit integer.
+ *
+ * `>>` applies ToInt32 to its left operand, so the shifted form silently wraps above 2^31 and comes
+ * back negative — the self-guided restoration box filter's `p * s` reaches 3.8e9 on an ordinary
+ * black/white edge, where `round2` returned -484 against an exact 3612. Every JavaScript number is
+ * already a double, so the product itself is exact to 2^53; only the shift needs replacing with a
+ * floor division, which is what the specification's Round2 says in the first place. Same shape as
+ * `round2_12` in the inverse transform, which hit this earlier.
+ *
+ * @param {number} x
+ * @param {number} n number of bits to shift away, `>= 0`
+ * @returns {number}
+ * @see AV1 spec 4.7 "Mathematical functions"
+ */
+export function round2_wide(x: number, n: number): number;
 //# sourceMappingURL=round2.d.ts.map

package/src/format/image/avif/av1/util/round2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"round2.d.ts","sourceRoot":"","sources":["../../../../../../../src/format/image/avif/av1/util/round2.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0BARW,MAAM,KACN,MAAM,GACJ,MAAM,CAYlB"}
+{"version":3,"file":"round2.d.ts","sourceRoot":"","sources":["../../../../../../../src/format/image/avif/av1/util/round2.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,0BARW,MAAM,KACN,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;;;;;;;;GAcG;AACH,+BALW,MAAM,KACN,MAAM,GACJ,MAAM,CASlB"}

package/src/format/image/avif/av1/util/round2.js

@@ -1,27 +1,51 @@
-/**
- * `Round2( x, n )` from the AV1 specification: divide by `2^n` and round half up, rounding towards
- * negative infinity on the halfway case for negative inputs.
- *
- * The specification defines this with real division and a floor; JavaScript's `>>` is an arithmetic
- * shift, which is exactly that floor, so the integer form transliterates directly. The `n === 0`
- * guard is not cosmetic: `1 << -1` is `1 << 31` under JavaScript's shift-count masking, which would
- * silently produce garbage.
- *
- * `x` must fit in a signed 32-bit integer, which every intermediate the specification feeds to this
- * function does.
- *
- * @param {number} x
- * @param {number} n number of bits to shift away, `>= 0`
- * @returns {number}
- * @see AV1 spec 4.7 "Mathematical functions"
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export function round2(x, n) {
-    if (n === 0) {
-        return x;
-    }
-
-    return (x + (1 << (n - 1))) >> n;
-}
+/**
+ * `Round2( x, n )` from the AV1 specification: divide by `2^n` and round half up, rounding towards
+ * negative infinity on the halfway case for negative inputs.
+ *
+ * The specification defines this with real division and a floor; JavaScript's `>>` is an arithmetic
+ * shift, which is exactly that floor, so the integer form transliterates directly. The `n === 0`
+ * guard is not cosmetic: `1 << -1` is `1 << 31` under JavaScript's shift-count masking, which would
+ * silently produce garbage.
+ *
+ * `x + 2^(n-1)` must fit in a signed 32-bit integer — the rounding term is added before the shift, so
+ * the bound is slightly tighter than `x` itself. Most intermediates the specification feeds this do;
+ * the self-guided restoration box filter's do not, and use {@link round2_wide} instead.
+ *
+ * @param {number} x
+ * @param {number} n number of bits to shift away, `>= 0`
+ * @returns {number}
+ * @see AV1 spec 4.7 "Mathematical functions"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function round2(x, n) {
+    if (n === 0) {
+        return x;
+    }
+
+    return (x + (1 << (n - 1))) >> n;
+}
+
+/**
+ * {@link round2} for operands that run past a signed 32-bit integer.
+ *
+ * `>>` applies ToInt32 to its left operand, so the shifted form silently wraps above 2^31 and comes
+ * back negative — the self-guided restoration box filter's `p * s` reaches 3.8e9 on an ordinary
+ * black/white edge, where `round2` returned -484 against an exact 3612. Every JavaScript number is
+ * already a double, so the product itself is exact to 2^53; only the shift needs replacing with a
+ * floor division, which is what the specification's Round2 says in the first place. Same shape as
+ * `round2_12` in the inverse transform, which hit this earlier.
+ *
+ * @param {number} x
+ * @param {number} n number of bits to shift away, `>= 0`
+ * @returns {number}
+ * @see AV1 spec 4.7 "Mathematical functions"
+ */
+export function round2_wide(x, n) {
+    if (n === 0) {
+        return x;
+    }
+
+    return Math.floor((x + 2 ** (n - 1)) / 2 ** n);
+}

package/src/format/image/avif/heif/parse_avif_file.js

@@ -170,6 +170,22 @@ function read_iloc(file, cursor) {
 
     check_count(item_count, "iloc");
 
+    /**
+     * What one extent record costs in the file. `uint_of_size(0)` returns 0 without consuming a
+     * byte, so with all three widths at zero an extent is free in the file and an `ItemExtent` in
+     * memory — 644 bytes asked for 6.5 million of them, and a full `item_count` asks for 4.3
+     * billion, which is an OOM. Every other width is self-limiting, because the cursor throws when
+     * it runs out; this one is not, so it is refused outright. An extent that carries neither an
+     * offset nor a length describes nothing anyway.
+     */
+    const extent_record_bytes = index_size + offset_size + length_size;
+
+    /**
+     * Across the whole box, not per item. `check_count` bounds each `extent_count` on its own, and
+     * nothing bounded the product — which is the other half of the same arithmetic.
+     */
+    let total_extent_count = 0;
+
     for (let i = 0; i < item_count; i++) {
         const id = version < 2 ? cursor.u16() : cursor.u32();
 
@@ -186,6 +202,14 @@ function read_iloc(file, cursor) {
 
         check_count(extent_count, "iloc extents");
 
+        if (extent_count > 0 && extent_record_bytes === 0) {
+            throw new Error(`iloc declares ${extent_count} extents of zero width, which cannot be represented`);
+        }
+
+        total_extent_count += extent_count;
+
+        check_count(total_extent_count, "iloc extents in total");
+
         for (let j = 0; j < extent_count; j++) {
             if (index_size > 0) {
                 cursor.uint_of_size(index_size);

package/src/shade/RENDERER_CONTRACT.md

@@ -483,16 +483,21 @@ Order is **declared**, never emergent:
 ```js
 class DecalExtension extends RenderExtension {
     phase = FramePhase.AfterGBuffer;
-    after = [TerrainSplatExtension];   // classes, not instances
-    before = [];
+    relative_order = 1;   // a decal composites over surfaces already written
 }
 ```
 
-Constraints name classes, so you do not need a reference to another system's object to state an
-order, and a class nobody registered is simply not a constraint. Two extensions on one phase with no
-path between them record in **ascending `name` order** — reproducible rather than correct, and chosen
-precisely so that adding an `await` to a system's startup cannot change the picture. A cycle is
-reported with the names on it.
+`relative_order` defaults to `0`; lower records first, and any finite number will do — negative to
+pull forward, positive to push back. Two extensions on one phase with the same value record in
+**ascending `name` order**, which is reproducible rather than correct and is chosen precisely so
+that adding an `await` to a system's startup cannot change the picture.
+
+**It names nothing.** An extension states where it belongs from what it does — a fog conceals, so it
+is late; a debug overlay must not be concealed, so it is later still — and needs no import of, or
+reference to, whatever else is on the phase. That is deliberately less precise than a dependency
+would be: it cannot say "immediately after that one", and there is no cycle to report because there
+is no graph. An effect that genuinely needs one particular extension's result should read a record
+that extension published, which is a real dependency rather than a positional one.
 
 ### What keeps your work alive