From b54637ad4822343fcf8ec8ddd05db96e46b61968 Mon Sep 17 00:00:00 2001
From: simien <simienap@gmail.com>
Date: Sun, 13 Sep 2026 17:25:48 -0400
Subject: [PATCH 1/2] perf: build a shape mask once per composition, and give
 Motion its own section

A layer's mask is a pure function of the shape, its direction, the grid
size and the layer's seed; nothing in it moves with the phase. It was
recomputed for every cell on every frame, for both layers, and for the
radial shapes each cell allocated a corner list and took four square
roots. On the default canvas that doubled an animated frame, from 103ms
to 220ms with a vignette. The mask is now built once as a keep/drop byte
per cell and cached the way the field is, and a masked frame costs what
an unmasked one does.

The random stream is read in the same cell order as before, so the
output is unchanged: 1620 generate() calls across twelve mask and
direction pairs, three sizes, three texture pairings, five motions and
three phases hash identically against the previous generator.

Motion moves out from under Settings into its own section, second in
the General tab. It is what the site leads with, so it should be
findable as a heading, and it is one of the four controls that drive
animation rather than a canvas setting. Second rather than first because
size, colors and mask come before how it moves, a still is the default,
and the flash warning should not be the first line a new visitor reads.
The guide's tab table says where it sits.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 animated-backgrounds/index.html |  2 +-
 flow-fields/index.html          |  2 +-
 generator.js                    | 43 +++++++++++++++++++++++++++++----
 guide/index.html                |  2 +-
 index.html                      | 17 ++++++++++---
 seamless-backgrounds/index.html |  2 +-
 6 files changed, 55 insertions(+), 13 deletions(-)

diff --git a/animated-backgrounds/index.html b/animated-backgrounds/index.html
index 5753943..0ae292e 100644
--- a/animated-backgrounds/index.html
+++ b/animated-backgrounds/index.html
@@ -258,7 +258,7 @@ <h2 id="try">Try it</h2>
     </footer>
   </main>
 
-  <script src="../generator.js?v=11"></script>
+  <script src="../generator.js?v=12"></script>
   <script>
     // Phosphor's own path data, the same two glyphs and the same
     // flield-theme key the app and the guide use, so a choice made on any
diff --git a/flow-fields/index.html b/flow-fields/index.html
index c027fb0..f5a9efa 100644
--- a/flow-fields/index.html
+++ b/flow-fields/index.html
@@ -276,7 +276,7 @@ <h2 id="try">Try it</h2>
     </footer>
   </main>
 
-  <script src="../generator.js?v=11"></script>
+  <script src="../generator.js?v=12"></script>
   <script>
     // Phosphor's own path data, the same two glyphs and the same
     // flield-theme key the app and the guide use, so a choice made on any
diff --git a/generator.js b/generator.js
index 581915f..b49ae91 100644
--- a/generator.js
+++ b/generator.js
@@ -1122,8 +1122,20 @@ function maskKeepProbability(shape, direction, x, y, cols, rows) {
   return 1;
 }
 
-function applyShapeMask(grid, cols, rows, shape, seed, direction) {
-  if (!shape || shape === "none") return;
+// A layer's mask is a pure function of the shape, its direction, the grid
+// size and the layer's seed: nothing in it moves with the phase. It used
+// to be recomputed for every cell on every frame, and for the radial
+// shapes each cell allocated a corner list and took four square roots,
+// which doubled the cost of an animated frame. It is built once here as a
+// keep/drop byte per cell and reused. The random stream is read in the
+// same cell order as before, so a masked grid comes out bit-identical to
+// what the per-frame version drew. Same shape of cache as the field's: a
+// few entries cover both layers, the tutorial demos and the favicon.
+const SHAPE_MASK_CACHE_LIMIT = 6;
+const shapeMaskCache = new Map();
+
+function buildShapeMask(cols, rows, shape, seed, direction) {
+  const keep = new Uint8Array(cols * rows).fill(1);
   const rand = seededRandom(seed + "|mask");
 
   if (GRADIENT_SHAPE_MASKS.has(shape)) {
@@ -1131,11 +1143,11 @@ function applyShapeMask(grid, cols, rows, shape, seed, direction) {
       const row = y * cols;
       for (let x = 0; x < cols; x++) {
         if (rand() > maskKeepProbability(shape, direction, x, y, cols, rows)) {
-          grid[row + x] = 0;
+          keep[row + x] = 0;
         }
       }
     }
-    return;
+    return keep;
   }
 
   const inner = 1 - SHAPE_MASK_FEATHER;
@@ -1146,10 +1158,31 @@ function applyShapeMask(grid, cols, rows, shape, seed, direction) {
       const d = shapeDistance(shape, x, y, cols, rows);
       if (d <= inner) continue;
       if (d >= outer || rand() > 1 - (d - inner) / (outer - inner)) {
-        grid[row + x] = 0;
+        keep[row + x] = 0;
       }
     }
   }
+  return keep;
+}
+
+function shapeMaskFor(cols, rows, shape, seed, direction) {
+  const key = `${cols}|${rows}|${shape}|${direction || ""}|${seed}`;
+  const cached = shapeMaskCache.get(key);
+  if (cached) return cached;
+  const keep = buildShapeMask(cols, rows, shape, seed, direction);
+  if (shapeMaskCache.size >= SHAPE_MASK_CACHE_LIMIT) {
+    shapeMaskCache.delete(shapeMaskCache.keys().next().value);
+  }
+  shapeMaskCache.set(key, keep);
+  return keep;
+}
+
+function applyShapeMask(grid, cols, rows, shape, seed, direction) {
+  if (!shape || shape === "none") return;
+  const keep = shapeMaskFor(cols, rows, shape, seed, direction);
+  for (let i = 0; i < grid.length; i++) {
+    if (!keep[i]) grid[i] = 0;
+  }
 }
 
 function layerOptionsToField(layer) {
diff --git a/guide/index.html b/guide/index.html
index 57aadf7..8b1f851 100644
--- a/guide/index.html
+++ b/guide/index.html
@@ -178,7 +178,7 @@ <h3>Tabs</h3>
         <tbody>
           <tr>
             <td><strong>General</strong></td>
-            <td>Canvas width and height, with Web, Tablet, Mobile and Tile presets. A preset's chip stays lit while the values still match it. Also background color, grid resolution (block size), shape mask, motion, speed and the Auto-randomize interval</td>
+            <td>Canvas width and height, with Web, Tablet, Mobile and Tile presets. A preset's chip stays lit while the values still match it. Also background color, grid resolution (block size) and shape mask, then a Motion section with its Speed slider, the Auto-randomize interval, and three save slots</td>
           </tr>
           <tr>
             <td><strong>Layer A</strong> / <strong>Layer B</strong></td>
diff --git a/index.html b/index.html
index 6f97df5..1b98373 100644
--- a/index.html
+++ b/index.html
@@ -548,6 +548,15 @@ <h2 class="section-title">Settings</h2>
         <select id="shapeMaskDirection"></select>
       </div>
 
+      <!-- Its own section rather than the last field under Settings:
+           motion is what the site leads with, so it should be findable
+           as a heading, and it is one of the four controls that drive
+           animation (see AGENTS.md) rather than a canvas setting. Second
+           in the tab, not first: size, colors and mask come before how
+           it moves, a still is the default, and the flash warning below
+           should not be the first line a new visitor reads. -->
+      <h2 class="section-title">Motion</h2>
+
       <div class="field">
         <label for="motion">Motion</label>
         <p class="hint">Plays on the canvas as soon as you pick one.</p>
@@ -563,9 +572,9 @@ <h2 class="section-title">Settings</h2>
 
       <!-- Revealed with a motion, the same way the shape mask's
            direction is revealed with a shape that has one. A cycle
-           length means nothing without a cycle, and holding the pair
-           together is what keeps it from reading as part of the
-           Auto-randomize interval below. -->
+           length means nothing without a cycle, and keeping the pair
+           under one heading is what keeps it from reading as part of
+           the Auto-randomize interval in the next section. -->
       <div class="field" id="speedField" hidden>
         <label for="speed">Speed <span class="field-value" id="speedVal"></span></label>
         <p class="hint">How long a cycle takes on screen and in GIFs.</p>
@@ -909,7 +918,7 @@ <h1 class="brand"><a href="./">Flield<span class="sr-only">: seamless animated b
     </script>
   </div>
 
-  <script src="generator.js?v=11"></script>
+  <script src="generator.js?v=12"></script>
   <script>
     // Inline replacements for the icons that used to come from the
     // Phosphor webfont (224KB for the ~19 glyphs this app actually uses).
diff --git a/seamless-backgrounds/index.html b/seamless-backgrounds/index.html
index 655b877..97df92d 100644
--- a/seamless-backgrounds/index.html
+++ b/seamless-backgrounds/index.html
@@ -198,7 +198,7 @@ <h2 id="try">Try it</h2>
     </footer>
   </main>
 
-  <script src="../generator.js?v=11"></script>
+  <script src="../generator.js?v=12"></script>
   <script>
     // Phosphor's own path data, the same two glyphs and the same
     // flield-theme key the app and the guide use, so a choice made on any

From 68fd8e3693f21f91b4ba435430277298f196577c Mon Sep 17 00:00:00 2001
From: simien <simienap@gmail.com>
Date: Sun, 13 Sep 2026 17:39:35 -0400
Subject: [PATCH 2/2] fix: head the new section Animation, so it does not read
 Motion twice

The heading sat directly over a field labelled Motion. The section is
the topic and the field is the choice, the way Auto-randomize sits over
Reroll every, and the site already calls the thing animated backgrounds.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 guide/index.html | 2 +-
 index.html       | 5 +++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/guide/index.html b/guide/index.html
index 8b1f851..82e8626 100644
--- a/guide/index.html
+++ b/guide/index.html
@@ -178,7 +178,7 @@ <h3>Tabs</h3>
         <tbody>
           <tr>
             <td><strong>General</strong></td>
-            <td>Canvas width and height, with Web, Tablet, Mobile and Tile presets. A preset's chip stays lit while the values still match it. Also background color, grid resolution (block size) and shape mask, then a Motion section with its Speed slider, the Auto-randomize interval, and three save slots</td>
+            <td>Canvas width and height, with Web, Tablet, Mobile and Tile presets. A preset's chip stays lit while the values still match it. Also background color, grid resolution (block size) and shape mask, then an Animation section holding Motion and its Speed slider, the Auto-randomize interval, and three save slots</td>
           </tr>
           <tr>
             <td><strong>Layer A</strong> / <strong>Layer B</strong></td>
diff --git a/index.html b/index.html
index 1b98373..b8fe7a7 100644
--- a/index.html
+++ b/index.html
@@ -548,14 +548,15 @@ <h2 class="section-title">Settings</h2>
         <select id="shapeMaskDirection"></select>
       </div>
 
-      <!-- Its own section rather than the last field under Settings:
+      <!-- Its own section rather than the last field under Settings,
+           headed Animation so it does not repeat the field's own label:
            motion is what the site leads with, so it should be findable
            as a heading, and it is one of the four controls that drive
            animation (see AGENTS.md) rather than a canvas setting. Second
            in the tab, not first: size, colors and mask come before how
            it moves, a still is the default, and the flash warning below
            should not be the first line a new visitor reads. -->
-      <h2 class="section-title">Motion</h2>
+      <h2 class="section-title">Animation</h2>
 
       <div class="field">
         <label for="motion">Motion</label>