squishjs 1.3.8 → 1.4.0

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//Users/josephgarcia/homegames/homegames-client/**)",
+      "Read(//Users/josephgarcia/homegames/homegames-web/**)"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squishjs",
-  "version": "1.3.8",
+  "version": "1.4.0",
   "description": "squish & unsquish stuff",
   "scripts": {
     "test": "node testRunner.js"

package/src/Squisher.js

@@ -23,6 +23,13 @@ class Squisher {
         this.playerFrames = {};
 
         this.listeners = new Set();
+        // Coalescing: a single tick often mutates many nodes, each firing
+        // onStateChange. Instead of re-squishing the whole tree + broadcasting
+        // per mutation, we mark dirty and flush once at the end of the event
+        // loop turn. Consumers that need the current state synchronously (e.g.
+        // sending an initial frame to a player who just joined) call flush().
+        this._dirty = false;
+        this._flushScheduled = false;
         this.scale = scale || {x: 1, y: 1};
         this.state = this.squish(this.game.getLayers());
 
@@ -281,10 +288,25 @@ class Squisher {
     }
 
     handleStateChange(node, layerName) {
-        if (this.listeners.size > 0) {
-            this.state = this.squish(this.game.getLayers());
-            this.broadcast();
-        }
+        if (this.listeners.size === 0) return;
+        this._dirty = true;
+        if (this._flushScheduled) return;
+        this._flushScheduled = true;
+        const schedule = (typeof setImmediate === 'function')
+            ? setImmediate
+            : (fn) => setTimeout(fn, 0);
+        schedule(() => this.flush());
+    }
+
+    // Squish + broadcast any pending state changes synchronously. Safe to call
+    // when nothing is pending (no-op). Coalesces a burst of mutations into a
+    // single squish + single broadcast carrying the latest state.
+    flush() {
+        this._flushScheduled = false;
+        if (!this._dirty) return;
+        this._dirty = false;
+        this.state = this.squish(this.game.getLayers());
+        this.broadcast();
     }
 
     broadcast() {

package/src/squishHelpers/asset.js

@@ -6,7 +6,7 @@ const squishAsset = {
 	type: ASSET_SUBTYPE,
 	squish: (a, scale) => {
 		const assetKey = Object.keys(a)[0];
-		const squishedAssets = new Array(10 + assetKey.length);
+		const squishedAssets = new Array(18 + assetKey.length);
 
 		const asset = a[assetKey];
 
@@ -18,6 +18,15 @@ const squishAsset = {
 
 		const startTimeSecond = asset.startTime || 0;
 
+		// Crop values are percentages (0-100) of the source image, expressed as
+		// the amount removed from each edge. They sample a sub-region of the
+		// source and are independent of layer scale (which affects pos/size, i.e.
+		// where the cropped region lands on screen). Default to 0 (no crop).
+		const cropLeft = asset.cropLeft || 0;
+		const cropTop = asset.cropTop || 0;
+		const cropRight = asset.cropRight || 0;
+		const cropBottom = asset.cropBottom || 0;
+
 		squishedAssets[0] = Math.floor(posX);
 		squishedAssets[1] = getFractional(posX);
 
@@ -33,8 +42,20 @@ const squishAsset = {
 		squishedAssets[8] = Math.floor(startTimeSecond);
 		squishedAssets[9] = getFractional(startTimeSecond);
 
+		squishedAssets[10] = Math.floor(cropLeft);
+		squishedAssets[11] = getFractional(cropLeft);
+
+		squishedAssets[12] = Math.floor(cropTop);
+		squishedAssets[13] = getFractional(cropTop);
+
+		squishedAssets[14] = Math.floor(cropRight);
+		squishedAssets[15] = getFractional(cropRight);
+
+		squishedAssets[16] = Math.floor(cropBottom);
+		squishedAssets[17] = getFractional(cropBottom);
+
 		for (let i = 0; i < assetKey.length; i++) {
-			squishedAssets[10 + i] = assetKey.codePointAt(i);
+			squishedAssets[18 + i] = assetKey.codePointAt(i);
 		}
 
 		return squishedAssets;
@@ -48,7 +69,12 @@ const squishAsset = {
 
 		const startTime = squished[8] + squished[9] / 100;
 
-		const assetKey = String.fromCodePoint.apply(null, squished.slice(10));
+		const cropLeft = squished[10] + squished[11] / 100;
+		const cropTop = squished[12] + squished[13] / 100;
+		const cropRight = squished[14] + squished[15] / 100;
+		const cropBottom = squished[16] + squished[17] / 100;
+
+		const assetKey = String.fromCodePoint.apply(null, squished.slice(18));
 
 		return {
 			[assetKey]: {
@@ -60,7 +86,11 @@ const squishAsset = {
 					x: assetSizeX,
 					y: assetSizeY
 				},
-				startTime
+				startTime,
+				cropLeft,
+				cropTop,
+				cropRight,
+				cropBottom
 			}
 		}
 	}
@@ -69,4 +99,4 @@ const squishAsset = {
 module.exports = {
     ASSET_SUBTYPE,
     squishAsset
-};
+};

package/src/util/views.js

@@ -23,6 +23,10 @@ const getView = (plane, view, playerIds, translation = {}, scale = {}) => {
             let shouldInclude = true;
 
             const translatedCoords = [];
+            // Same vertices as translatedCoords but WITHOUT the [0,100] viewport
+            // clamp. Needed for asset crop math: to know how much of an image
+            // falls outside the viewport we need its true (unclamped) extent.
+            const rawTranslatedCoords = [];
 
             // same hack as geometry utils
             const vertices = node.node.coordinates2d || [
@@ -70,6 +74,22 @@ const getView = (plane, view, playerIds, translation = {}, scale = {}) => {
                 }
 
                 translatedCoords.push([translatedX, translatedY]);
+
+                // Unclamped transform of the same vertex (scale + translation,
+                // but no clamp to [0,100]). Used only for asset crop below.
+                let rawX = (scale.x || 1) * (x - view.x);
+                let rawY = (scale.y || 1) * (y - view.y);
+
+                if (shouldTranslate) {
+                    if (translation.x) {
+                        rawX += translation.x;
+                    }
+                    if (translation.y) {
+                        rawY += translation.y;
+                    }
+                }
+
+                rawTranslatedCoords.push([rawX, rawY]);
             }
 
             if (shouldInclude) {
@@ -89,10 +109,35 @@ const getView = (plane, view, playerIds, translation = {}, scale = {}) => {
                         const thirdPoint = copied.node.coordinates2d[2];
                         const width = secondPoint[0] - firstPoint[0];
                         const height = thirdPoint[1] - secondPoint[1];
-                        Object.values(copied.node.asset)[0].pos.x = firstPoint[0];
-                        Object.values(copied.node.asset)[0].pos.y = firstPoint[1];
-                        Object.values(copied.node.asset)[0].size.x = width;
-                        Object.values(copied.node.asset)[0].size.y = height;   
+
+                        const assetObj = Object.values(copied.node.asset)[0];
+
+                        // pos/size = the clamped, on-screen visible box.
+                        assetObj.pos.x = firstPoint[0];
+                        assetObj.pos.y = firstPoint[1];
+                        assetObj.size.x = width;
+                        assetObj.size.y = height;
+
+                        // Crop the source image to the portion clipped by the
+                        // viewport. Without this the renderer squashes the whole
+                        // image into the (smaller) visible box instead of cutting
+                        // off the off-screen part. Using the unclamped corners we
+                        // measure how much of the image fell outside [0,100] on
+                        // each edge, as a percentage of the image's full span.
+                        const rawFirst = rawTranslatedCoords[0]; // top-left
+                        const rawThird = rawTranslatedCoords[2]; // bottom-right
+                        const fullWidth = rawThird[0] - rawFirst[0];
+                        const fullHeight = rawThird[1] - rawFirst[1];
+
+                        if (fullWidth > 0) {
+                            assetObj.cropLeft = Math.max(0, (0 - rawFirst[0]) / fullWidth) * 100;
+                            assetObj.cropRight = Math.max(0, (rawThird[0] - 100) / fullWidth) * 100;
+                        }
+
+                        if (fullHeight > 0) {
+                            assetObj.cropTop = Math.max(0, (0 - rawFirst[1]) / fullHeight) * 100;
+                            assetObj.cropBottom = Math.max(0, (rawThird[1] - 100) / fullHeight) * 100;
+                        }
                     }
                 } 
                 copied.node.playerIds = playerIds || [];

package/test/Layers.test.js

@@ -56,6 +56,8 @@ test("test layer with child added", () => {
 
     // adding a child should trigger an update in the squisher and result in a new state
     layer.addChild(child);
+    // state changes are coalesced; flush to materialize them synchronously
+    squisher.flush();
 
     const expectedLayerValue = [squish(layer), squish(child)].flat();
     const stateWithChild = Array.from(squisher.state);

package/test/Squisher.test.js

@@ -5,48 +5,49 @@ const { unsquish } = require('../src/squish');
 
 const { FakeGame, verifyArrayEquality, rectNode, textNode, polygonNode, circleNode, lineNode } = require('./utils');
 
-test("squisher listener", () => {
+test("squisher listener coalesces state changes", () => {
 
     const root = lineNode({coords: [[20, 20], [80, 80]], color: COLORS.ORANGE});
-    
-    const game = new FakeGame([ 
+
+    const game = new FakeGame([
         {
             root,
             scale: {
                 x: 1,
                 y: 1
             }
-        } 
+        }
     ]);
 
     const squisher = new Squisher({ game });
 
     let timesInvoked = 0;
+    let lastState = null;
 
     squisher.addListener((newSquishedState) => {
-        if (timesInvoked === 0) {
-            assert(newSquishedState.length == 1);
-            const updatedRoot = unsquish(newSquishedState[0]);
-            verifyArrayEquality(updatedRoot.node.color, COLORS.BLACK);
-        } else if (timesInvoked === 1) {
-            assert(newSquishedState.length == 1);
-            const updatedRoot = unsquish(newSquishedState[0]);
-            verifyArrayEquality(updatedRoot.node.color, COLORS.GREEN);
-        }
         timesInvoked++;
+        lastState = newSquishedState;
     });
 
     assert(timesInvoked === 0);
 
+    // A burst of mutations in the same turn is deferred — nothing broadcast yet.
     root.node.color = COLORS.BLACK;
     root.node.onStateChange();
-
-    assert(timesInvoked === 1);
-
     root.node.color = COLORS.GREEN;
     root.node.onStateChange();
 
-    assert(timesInvoked === 2);
+    assert(timesInvoked === 0);
+
+    // flush() coalesces the burst into a single broadcast with the final state.
+    squisher.flush();
+    assert(timesInvoked === 1);
+    assert(lastState.length == 1);
+    verifyArrayEquality(unsquish(lastState[0]).node.color, COLORS.GREEN);
+
+    // flush() with nothing pending is a no-op.
+    squisher.flush();
+    assert(timesInvoked === 1);
 });
 
 

package/test/main.test.js

@@ -435,6 +435,7 @@ test("Simple shape with updates", () => {
     base.update({
         fill: COLORS.BLUE
     });
+    squisher.flush();
 
     const state2 = Array.from(squisher.state);
     verifyArrayEquality(unsquish(state2[0]).node.fill, COLORS.BLUE);
@@ -442,6 +443,7 @@ test("Simple shape with updates", () => {
     base.update({
         fill: COLORS.GREEN
     });
+    squisher.flush();
 
     const state3 = Array.from(squisher.state);
     verifyArrayEquality(unsquish(state3[0]).node.fill, COLORS.GREEN);