@kolkrabbi/kol-growth 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # @kolkrabbi/kol-growth
 
+## 0.3.0 — 2026-10-30
+
+- **`settle` — the line rests** (kol-fxr plan 44 6.1 — user: *"it doesnt need to be so active when nothing is happening, its just the mouse interaction and the growth edges that are subject to constant change"*). 0.2.0 still jittered: a packed line never comes to rest (strands two nodes apart push along it), and growth split edges anywhere, so every split shoved the whole line. With `settle` > 0 a node with packed neighbours (14+ strands within 1.5 gaps) freezes after `settle` steps, growth splits only the front, and `poke` re-heats what it touches. Measured on a 1440×900 orb: 98% of the line moving every step → 8–13% while growing, 3% when grown, ~10× cheaper a step. Default 0 = 0.2.0's behaviour.
+- **`step(zone)` retired** — `settle` does its job everywhere, not only around the pointer. kol-fxr's `engine.js`, carried verbatim.
+
 ## 0.2.0 — 2026-10-30
 
 - **`bleed` and `step(zone)`** (SignedOutStageStill, kol-fxr — a finished line jittered at the edges). `bleed` (default 0, today's framed clamp) lets nodes run that many units past every edge; a node outside the frame is frozen — no force, split or merge — and the spatial hash spans the bled frame. `step(zone)` with `{ x, y, r }` freezes every node outside the zone the same way. kol-fxr's fixed `engine.js`, carried verbatim; framed consumers are unchanged.

package/README.md

@@ -11,7 +11,7 @@ const sim = new Growth({ w, h, density: densityFrom(pathCanvas(d, w / h, 0.6)),
 sim.setParams({ minGap: 6, maxGap: 24, contrast: 1.4, growth: 8 })
 sim.seed()                       // a small ring at the field's centre of darkness
 sim.step()                       // one step: smooth, repel, resample, grow — call per frame until x.length hits cap
-sim.step({ x, y, r })            // a finished line: only nodes inside the zone move, the rest stay frozen
+sim.setParams({ settle: 120 })    // the packed interior rests; only the growing front and the pointer move
 sim.poke(px, py, down)           // the pointer as a force: a push, or a blast when down
 sim.draw(ctx, w, h, { ink, width: 1 })   // the one path onto a canvas
 sim.pathD(w, h)                  // the same path as an SVG `d`
@@ -19,7 +19,7 @@ sim.pathD(w, h)                  // the same path as an SVG `d`
 
 | export | does |
 |---|---|
-| `Growth` | the sim — `step`, `seed`, `poke`, `draw`, `pathD`, `setParams({ minGap, maxGap, contrast, growth, cap, bleed })` — `bleed` (default 0, the framed clamp) lets the line run that far past every edge, where it freezes |
+| `Growth` | the sim — `step`, `seed`, `poke`, `draw`, `pathD`, `setParams({ minGap, maxGap, contrast, growth, cap, bleed, settle })` — `bleed` (default 0, the framed clamp) lets the line run that far past every edge, where it freezes; `settle` (default 0, off) cools a packed node after that many steps so it stops, grows only the front, and `poke` re-heats what it touches |
 | `densityFrom(canvas, cols?, invert?)` | 1 − luma on a grid, lightly blurred — the field the spacing reads |
 | `SIM_W` | 1000, the sim width kol-fxr's loops use |
 | `mulberry32(seed)` | the seeded 0..1 PRNG; pass as `rand` and the same seed grows the same line |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-growth",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The growing line engine, differential growth into shapes",
   "license": "MIT",
   "type": "module",

package/src/engine.js

@@ -13,10 +13,15 @@
 // sits still, not this jittering"*). By default the line is held 2 units inside the frame — the effect and the generator
 // draw on framed paper. `bleed` lets it run that far past every edge instead, and a node outside the frame FREEZES: no
 // force, no split, no merge, no growth. The wall the line piled into is gone; what leaves the frame sits still.
-// A finished line never settles on its own (merges and splits trade nodes forever), so `step(zone)` freezes everything
-// outside `zone` `{ x, y, r }` the same way — the pointer moves the line around it, the rest stays put.
+// THE LINE RESTS (plan 44 6.1, user 2026-10-30: *"it doesnt need to be so active when nothing is happening, its just the
+// mouse interaction and the growth edges that are subject to constant change"*). A packed line never comes to rest on
+// its own — strands two nodes apart push along it, so it always wants to lengthen. With `settle` > 0 a node COOLS: off
+// the front (FRONT, below) it freezes after `settle` steps; on the front it stays live; the pointer (`poke`) re-heats
+// what it touches. Growth splits only the front — so only the growing front and the pointer move.
 
 export const SIM_W = 1000
+/* fewer close strands than this, and a node is on the growing front */
+const FRONT = 14
 
 /* density from any canvas: 1 − luma, on a grid `cols` wide, lightly blurred so the spacing changes smoothly */
 export function densityFrom(canvas, cols = 160, invert = false) {
@@ -44,22 +49,22 @@ export class Growth {
     this.density = density
     this.rand = rand
     this.cap = cap
-    this.minGap = 5; this.maxGap = 22; this.contrast = 1.4; this.growth = 4; this.bleed = 0
-    this.x = []; this.y = []
+    this.minGap = 5; this.maxGap = 22; this.contrast = 1.4; this.growth = 4; this.bleed = 0; this.settle = 0
+    this.x = []; this.y = []; this.r = []
   }
 
-  setParams({ minGap, maxGap, contrast, growth, cap, bleed }) {
+  setParams({ minGap, maxGap, contrast, growth, cap, bleed, settle }) {
     if (minGap != null) this.minGap = minGap
     if (maxGap != null) this.maxGap = Math.max(maxGap, this.minGap + 0.5)
     if (contrast != null) this.contrast = contrast
     if (growth != null) this.growth = growth
     if (cap != null) this.cap = cap
     if (bleed != null) this.bleed = bleed
+    if (settle != null) this.settle = settle
   }
 
   /* off the frame, with a bleed: frozen */
-  out(x, y, zone) {
-    if (zone && (x - zone.x) ** 2 + (y - zone.y) ** 2 > zone.r * zone.r) return true
+  out(x, y) {
     return this.bleed > 0 && (x < 0 || y < 0 || x > this.w || y > this.h)
   }
 
@@ -78,6 +83,7 @@ export class Growth {
       const a = (i / n) * Math.PI * 2
       this.x.push(cx + Math.cos(a) * r); this.y.push(cy + Math.sin(a) * r)
     }
+    this.r = new Array(n).fill(0)
   }
 
   dens(x, y) {
@@ -93,7 +99,7 @@ export class Growth {
     return this.maxGap + (this.minGap - this.maxGap) * d
   }
 
-  step(zone = null) {
+  step() {
     const { x, y, w, h } = this
     let n = x.length
     if (n < 3) return
@@ -103,12 +109,14 @@ export class Growth {
     const head = new Int32Array(cols * rows).fill(-1)
     const next = new Int32Array(n)
     const cell = (px, py) => Math.min(rows - 1, Math.max(0, Math.floor((py + b) / R))) * cols + Math.min(cols - 1, Math.max(0, Math.floor((px + b) / R)))
+    /* 1 = off the frame (for good), 2 = cooled (the pointer re-heats it) */
+    const rest = this.r.length === n ? this.r : (this.r = new Array(n).fill(0)), S = this.settle
     const frozen = new Uint8Array(n)
-    for (let i = 0; i < n; i++) frozen[i] = this.out(x[i], y[i], zone) ? 1 : 0
+    for (let i = 0; i < n; i++) frozen[i] = this.out(x[i], y[i]) ? 1 : S > 0 && rest[i] >= S ? 2 : 0
     for (let i = 0; i < n; i++) { const c = cell(x[i], y[i]); next[i] = head[c]; head[c] = i }
     const gaps = new Float32Array(n)
     for (let i = 0; i < n; i++) gaps[i] = this.gap(x[i], y[i])
-    const fx = new Float32Array(n), fy = new Float32Array(n)
+    const fx = new Float32Array(n), fy = new Float32Array(n), crowd = new Uint8Array(n)
     for (let i = 0; i < n; i++) {
       if (frozen[i]) continue
       const ip = (i - 1 + n) % n, inx = (i + 1) % n
@@ -129,6 +137,8 @@ export class Growth {
             const dx = x[i] - x[j], dy = y[i] - y[j]
             const g = (gi + gaps[j]) / 2
             const d2 = dx * dx + dy * dy
+            /* a strand of line within 1.5 gaps — packed; the front has none on its open side */
+            if (d2 < 2.25 * g * g && crowd[i] < 255) crowd[i]++
             if (d2 >= g * g || d2 === 0) continue
             const d = Math.sqrt(d2)
             const push = ((g - d) / g) * 0.5
@@ -142,11 +152,13 @@ export class Growth {
     for (let i = 0; i < n; i++) {
       if (frozen[i]) continue
       const lim = gaps[i] * 0.25
-      x[i] = Math.min(w - m, Math.max(m, x[i] + Math.max(-lim, Math.min(lim, fx[i]))))
-      y[i] = Math.min(h - m, Math.max(m, y[i] + Math.max(-lim, Math.min(lim, fy[i]))))
+      const mx = Math.max(-lim, Math.min(lim, fx[i])), my = Math.max(-lim, Math.min(lim, fy[i]))
+      x[i] = Math.min(w - m, Math.max(m, x[i] + mx))
+      y[i] = Math.min(h - m, Math.max(m, y[i] + my))
+      rest[i] = crowd[i] < FRONT ? 0 : rest[i] + 1
     }
     /* resample: split long edges, merge short ones, then grow */
-    const nx = [], ny = []
+    const nx = [], ny = [], nr = [], nc = []
     let budget = this.cap - n
     for (let i = 0; i < n; i++) {
       const j = (i + 1) % n
@@ -154,21 +166,34 @@ export class Growth {
       const dx = x[j] - x[i], dy = y[j] - y[i]
       const len = Math.hypot(dx, dy)
       /* an edge with a frozen end keeps its nodes as they are */
-      if (frozen[i] || frozen[j]) { nx.push(x[i]); ny.push(y[i]); continue }
+      if (frozen[i] || frozen[j]) { nx.push(x[i]); ny.push(y[i]); nr.push(rest[i]); nc.push(255); continue }
       if (len < g * 0.2 && n > 8) continue
-      nx.push(x[i]); ny.push(y[i])
-      if (len > g * 0.5 && budget > 0) { nx.push(x[i] + dx / 2); ny.push(y[i] + dy / 2); budget-- }
+      nx.push(x[i]); ny.push(y[i]); nr.push(rest[i]); nc.push(crowd[i])
+      if (len > g * 0.5 && budget > 0) { nx.push(x[i] + dx / 2); ny.push(y[i] + dy / 2); nr.push(0); nc.push(crowd[i]); budget-- }
+    }
+    /* WHERE IT GROWS: anywhere (the default), or — resting on — only the FRONT: active edges with room around them (fewer
+     * than FRONT strands within 1.5 gaps; measured, the front holds ~10, the packed interior ~20). Grown anywhere, every
+     * split shoves the whole line and nothing ever rests */
+    const front = []
+    if (S > 0) for (let i = 0; i < nx.length; i++) {
+      const j = (i + 1) % nx.length
+      if (nr[i] < S && nr[j] < S && nc[i] < FRONT && nc[j] < FRONT && !this.out(nx[i], ny[i]) && !this.out(nx[j], ny[j])) front.push(i)
     }
     for (let k = 0; k < this.growth && nx.length < this.cap; k++) {
-      const i = Math.floor(this.rand() * nx.length), j = (i + 1) % nx.length
-      if (this.out(nx[i], ny[i], zone) || this.out(nx[j], ny[j], zone)) continue
+      if (S > 0 && !front.length) break
+      /* ponytail: front indices drift by the splits made before them this step — a neighbouring edge, harmless */
+      let i = S > 0 ? front[Math.floor(this.rand() * front.length)] : Math.floor(this.rand() * nx.length)
+      i = Math.min(i, nx.length - 1)
+      const j = (i + 1) % nx.length
+      if (S === 0 && (this.out(nx[i], ny[i]) || this.out(nx[j], ny[j]))) continue
       /* a split nudged sideways starts a new fold */
       const dx = nx[j] - nx[i], dy = ny[j] - ny[i]
       const s = (this.rand() - 0.5) * 0.6
       nx.splice(i + 1, 0, nx[i] + dx / 2 - dy * s)
       ny.splice(i + 1, 0, ny[i] + dy / 2 + dx * s)
+      nr.splice(i + 1, 0, 0); nc.splice(i + 1, 0, nc[i])
     }
-    this.x = nx; this.y = ny
+    this.x = nx; this.y = ny; this.r = nr; this.c = nc
   }
 
   /* THE POINTER AS A FORCE (sim units) — penrose/common.js's verbs on this line: a move pushes the nodes out of a ring
@@ -185,6 +210,7 @@ export class Growth {
       const d = Math.sqrt(d2), f = (1 - d / reach) * strength
       x[i] = Math.min(w - m, Math.max(m, x[i] + (dx / d) * f))
       y[i] = Math.min(h - m, Math.max(m, y[i] + (dy / d) * f))
+      if (this.r.length === x.length) this.r[i] = 0
     }
   }
 

package/src/selftest.mjs

@@ -17,11 +17,18 @@ const before = a.x.slice()
 a.poke(a.x[0], a.y[0] + 1, true)
 assert.notDeepEqual(a.x, before, 'poke moves the line')
 assert.match(a.pathD(400, 300), /^M.*Z$/, 'one closed path')
-/* a zone step freezes everything outside it */
-const zone = { x: 200, y: 150, r: 40 }, out = a.x.map((v, i) => (v - 200) ** 2 + (a.y[i] - 150) ** 2 > 1600)
-const px = a.x.slice(), py = a.y.slice(), pn = a.x.length
-a.step(zone)
-if (a.x.length === pn) assert.ok(out.every((o, i) => !o || (a.x[i] === px[i] && a.y[i] === py[i])), 'outside the zone stays put')
+/* resting (`settle`): the packed interior cools and stops — once grown, a step moves only the front */
+const r = new Growth({ w: 400, h: 300, rand: mulberry32(5), cap: 1500 })
+r.setParams({ minGap: 6, maxGap: 24, contrast: 1.4, growth: 8, bleed: 30, settle: 40 })
+r.seed()
+for (let i = 0; i < 3000 && r.x.length < r.cap; i++) r.step()
+for (let i = 0; i < 60; i++) r.step()
+const rx = r.x.slice(), ry = r.y.slice(), rn = r.x.length
+r.step()
+if (r.x.length === rn) {
+  const still = rx.filter((v, i) => v === r.x[i] && ry[i] === r.y[i]).length
+  assert.ok(still / rn > 0.8, `a grown line rests (${still}/${rn} still)`)
+}
 /* with a bleed the line may leave the frame, and stays inside the bled frame */
 const c = new Growth({ w: 200, h: 150, rand: mulberry32(3), cap: 900 })
 c.setParams({ minGap: 6, maxGap: 24, contrast: 1.4, growth: 8, bleed: 30 })