@kolkrabbi/kol-growth 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @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.
+
 ## 0.1.0 — 2026-10-30
 
 - **First release — the engine tier's fourth package** (ARCHITECTURE §3, GrowthLineStage from kol-atlas). kol-fxr's

package/README.md

@@ -11,6 +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.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`
@@ -18,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 })` |
+| `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.1.0",
+  "version": "0.3.0",
   "description": "The growing line engine, differential growth into shapes",
   "license": "MIT",
   "type": "module",

package/src/engine.js

@@ -8,8 +8,20 @@
 // than a fifth merge, and `growth` random edges split per step so the line keeps lengthening until the node cap.
 // Spacing is local: `minGap` where the density is 1, `maxGap` where it is 0. Units are sim px — the sim is 1000 wide
 // and as tall as the frame's aspect, scaled to the frame at draw.
+//
+// THE EDGE (plan 44 6.1, user 2026-10-30: *"allow growth outside of viewport and limit it in some other way so it just
+// 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.
+// 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) {
@@ -37,16 +49,23 @@ 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.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 }) {
+  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) {
+    return this.bleed > 0 && (x < 0 || y < 0 || x > this.w || y > this.h)
   }
 
   /* a small ring of nodes — at (cx, cy) in 0..1, or at the field's centre of darkness */
@@ -64,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) {
@@ -83,24 +103,29 @@ export class Growth {
     const { x, y, w, h } = this
     let n = x.length
     if (n < 3) return
-    const R = this.maxGap
-    /* spatial hash on the largest gap */
-    const cols = Math.ceil(w / R) + 1, rows = Math.ceil(h / R) + 1
+    const R = this.maxGap, b = this.bleed
+    /* spatial hash on the largest gap, over the frame and its bleed */
+    const cols = Math.ceil((w + 2 * b) / R) + 1, rows = Math.ceil((h + 2 * b) / R) + 1
     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 / R))) * cols + Math.min(cols - 1, Math.max(0, Math.floor(px / R)))
+    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]) ? 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
       /* smooth: toward the neighbours' midpoint */
       fx[i] += ((x[ip] + x[inx]) / 2 - x[i]) * 0.35
       fy[i] += ((y[ip] + y[inx]) / 2 - y[i]) * 0.35
       /* repel: every non-adjacent node inside the local gap */
       const gi = gaps[i]
-      const cx = Math.floor(x[i] / R), cy = Math.floor(y[i] / R)
+      const cx = Math.floor((x[i] + b) / R), cy = Math.floor((y[i] + b) / R)
       for (let oy = -1; oy <= 1; oy++) {
         const ry = cy + oy
         if (ry < 0 || ry >= rows) continue
@@ -112,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
@@ -121,33 +148,52 @@ export class Growth {
         }
       }
     }
-    const m = 2
+    const m = b > 0 ? -b : 2
     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
       const g = this.gap(x[i], y[i])
       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]); 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 (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
@@ -155,15 +201,16 @@ export class Growth {
    * a teleport). The line's own smoothing and spacing refold the crater; `amount` 0 turns it off. */
   poke(px, py, down = false, amount = 1) {
     if (!amount) return
-    const { x, y, w, h } = this, s = Math.min(w, h), m = 2
+    const { x, y, w, h } = this, s = Math.min(w, h), m = this.bleed > 0 ? -this.bleed : 2
     const reach = s * 0.08 * (down ? 3 : 1), r2 = reach * reach
     const strength = Math.min(s * 0.03, s * 0.006 * amount * (down ? 6 : 1))
     for (let i = 0; i < x.length; i++) {
       const dx = x[i] - px, dy = y[i] - py, d2 = dx * dx + dy * dy
-      if (d2 >= r2 || d2 < 1e-6) continue
+      if (d2 >= r2 || d2 < 1e-6 || this.out(x[i], y[i])) continue
       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,4 +17,22 @@ 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')
+/* 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 })
+c.seed()
+for (let i = 0; i < 600 && c.x.length < c.cap; i++) c.step()
+assert.ok(c.x.every((v, i) => v >= -30 && v <= 230 && c.y[i] >= -30 && c.y[i] <= 180), 'held inside the bled frame')
 console.log('kol-growth selftest ok')