@kolkrabbi/kol-growth 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @kolkrabbi/kol-growth
+
+## 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
+  growing line moved in so fxr and every other app grow the same line from one engine.
+- `Growth` · `densityFrom` · `SIM_W` — kol-fxr `src/loops/growth/engine.js`, carried verbatim.
+- `mulberry32` — kol-fxr `src/loops/gl/rng.js`, verbatim.
+- `orbCanvas` (fxr's `sourceCanvas('orb')`, verbatim) and `pathCanvas` (new: any SVG path `d` as a density source).
+- `src/selftest.mjs` — grows to the cap, a seed repeats, `poke` moves the line.

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @kolkrabbi/kol-growth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The growing line: differential growth — one closed line that grows, folds and never crosses itself, packing tighter
+where a density field is darker. Plain ESM, no React, no dependencies. Engine tier (ARCHITECTURE §3): the stage that
+draws it on a page is kol-component's `GrowthLineStage`; kol-fxr's generator and effect run it in their own loops.
+
+```js
+import { Growth, densityFrom, mulberry32, orbCanvas, pathCanvas } from '@kolkrabbi/kol-growth'
+
+const sim = new Growth({ w, h, density: densityFrom(pathCanvas(d, w / h, 0.6)), rand: mulberry32(7), cap: 14000 })
+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.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`
+```
+
+| 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 |
+| `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 |
+| `orbCanvas(aspect)` | the built-in orb, dark at the centre |
+| `pathCanvas(d, aspect, fit?)` | any SVG path `d`, solid black on white, centred at `fit` of the frame |
+
+`densityFrom`, `orbCanvas` and `pathCanvas` draw on a canvas, so they need a browser; the sim itself runs anywhere
+(`pnpm --filter @kolkrabbi/kol-growth test`). Proved in `apps/growth`.

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@kolkrabbi/kol-growth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "The growing line engine, differential growth into shapes",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "kol",
+    "kolkrabbi",
+    "design-system",
+    "generative",
+    "differential-growth",
+    "engine"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tor-Grimsson/kol-ds.git",
+    "directory": "packages/growth"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node src/selftest.mjs"
+  }
 }

package/src/engine.js

@@ -0,0 +1,221 @@
+// The growing line (plan 43 W4) — differential growth: ONE closed line that grows, folds and never crosses itself,
+// packing tighter where a density field is darker. The reference is algorigraph's plotted portraits (user 2026-10-28:
+// *"a single elastic loop morphs into the shapes of a…"*). The generator (growthLine.js) feeds it a built-in image;
+// the effect (filters/fxGrowth.js) feeds it the layer's own photo. Both draw it the same way: one path, ink on paper.
+//
+// A step: every node is pulled toward its neighbours' midpoint (smooth), pushed off every non-adjacent node closer than
+// the local spacing (no crossings, even gaps), held inside the frame; edges longer than half the spacing split, shorter
+// 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.
+// 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.
+
+export const SIM_W = 1000
+
+/* 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) {
+  const rows = Math.max(1, Math.round(cols * canvas.height / canvas.width))
+  const c = document.createElement('canvas')
+  c.width = cols; c.height = rows
+  const g = c.getContext('2d', { willReadFrequently: true })
+  g.filter = 'blur(1px)'
+  g.drawImage(canvas, 0, 0, cols, rows)
+  const d = g.getImageData(0, 0, cols, rows).data
+  const out = new Float32Array(cols * rows)
+  for (let i = 0; i < out.length; i++) {
+    const j = i * 4
+    const a = d[j + 3] / 255
+    /* transparent reads as paper */
+    const lum = ((0.2126 * d[j] + 0.7152 * d[j + 1] + 0.0722 * d[j + 2]) / 255) * a + (1 - a)
+    out[i] = invert ? lum : 1 - lum
+  }
+  return { cols, rows, data: out }
+}
+
+export class Growth {
+  constructor({ w = SIM_W, h = SIM_W, density = null, rand = Math.random, cap = 6000 }) {
+    this.w = w; this.h = h
+    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 = []
+  }
+
+  setParams({ minGap, maxGap, contrast, growth, cap, bleed }) {
+    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
+  }
+
+  /* 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
+    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 */
+  seed(cx, cy, r = 14) {
+    if (cx == null && this.density) {
+      const { cols, rows, data } = this.density
+      let sx = 0, sy = 0, sw = 0
+      for (let i = 0; i < data.length; i++) { const v = data[i] * data[i]; sx += v * (i % cols); sy += v * Math.floor(i / cols); sw += v }
+      if (sw > 0) { cx = (sx / sw + 0.5) / cols; cy = (sy / sw + 0.5) / rows }
+    }
+    cx = (cx ?? 0.5) * this.w; cy = (cy ?? 0.5) * this.h
+    const n = 24
+    this.x = []; this.y = []
+    for (let i = 0; i < n; i++) {
+      const a = (i / n) * Math.PI * 2
+      this.x.push(cx + Math.cos(a) * r); this.y.push(cy + Math.sin(a) * r)
+    }
+  }
+
+  dens(x, y) {
+    const D = this.density
+    if (!D) return 0.5
+    const c = Math.min(D.cols - 1, Math.max(0, Math.floor((x / this.w) * D.cols)))
+    const r = Math.min(D.rows - 1, Math.max(0, Math.floor((y / this.h) * D.rows)))
+    return D.data[r * D.cols + c]
+  }
+
+  gap(x, y) {
+    const d = Math.pow(Math.min(1, Math.max(0, this.dens(x, y))), 1 / this.contrast)
+    return this.maxGap + (this.minGap - this.maxGap) * d
+  }
+
+  step(zone = null) {
+    const { x, y, w, h } = this
+    let n = x.length
+    if (n < 3) return
+    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 + b) / R))) * cols + Math.min(cols - 1, Math.max(0, Math.floor((px + b) / R)))
+    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++) { 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)
+    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] + 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
+        for (let ox = -1; ox <= 1; ox++) {
+          const rx = cx + ox
+          if (rx < 0 || rx >= cols) continue
+          for (let j = head[ry * cols + rx]; j !== -1; j = next[j]) {
+            if (j === i || j === ip || j === inx) continue
+            const dx = x[i] - x[j], dy = y[i] - y[j]
+            const g = (gi + gaps[j]) / 2
+            const d2 = dx * dx + dy * dy
+            if (d2 >= g * g || d2 === 0) continue
+            const d = Math.sqrt(d2)
+            const push = ((g - d) / g) * 0.5
+            fx[i] += (dx / d) * push * g * 0.5
+            fy[i] += (dy / d) * push * g * 0.5
+          }
+        }
+      }
+    }
+    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]))))
+    }
+    /* resample: split long edges, merge short ones, then grow */
+    const nx = [], ny = []
+    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]); 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-- }
+    }
+    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
+      /* 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)
+    }
+    this.x = nx; this.y = ny
+  }
+
+  /* THE POINTER AS A FORCE (sim units) — penrose/common.js's verbs on this line: a move pushes the nodes out of a ring
+   * around (px, py), a press blasts (3× reach, 6× strength, capped at 3% of the frame a step so it reads as a shove, not
+   * 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 = 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 || 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))
+    }
+  }
+
+  /* the one path, scaled onto a w × h frame */
+  draw(ctx, fw, fh, { ink = '#111', paper = null, width = 1.2 } = {}) {
+    if (paper) { ctx.fillStyle = paper; ctx.fillRect(0, 0, fw, fh) }
+    const { x, y } = this
+    const n = x.length
+    if (n < 3) return
+    const sx = fw / this.w, sy = fh / this.h
+    ctx.beginPath()
+    /* through the edge midpoints with the nodes as control points — a smooth closed curve */
+    const mx = (i) => ((x[i] + x[(i + 1) % n]) / 2) * sx, my = (i) => ((y[i] + y[(i + 1) % n]) / 2) * sy
+    ctx.moveTo(mx(n - 1), my(n - 1))
+    for (let i = 0; i < n; i++) ctx.quadraticCurveTo(x[i] * sx, y[i] * sy, mx(i), my(i))
+    ctx.closePath()
+    ctx.strokeStyle = ink
+    ctx.lineWidth = width
+    ctx.lineJoin = 'round'
+    ctx.stroke()
+  }
+
+  /* the same path as one SVG `d`, in frame units */
+  pathD(fw, fh) {
+    const { x, y } = this
+    const n = x.length
+    if (n < 3) return ''
+    const sx = fw / this.w, sy = fh / this.h, f = (v) => v.toFixed(2)
+    const mx = (i) => f(((x[i] + x[(i + 1) % n]) / 2) * sx), my = (i) => f(((y[i] + y[(i + 1) % n]) / 2) * sy)
+    let d = `M${mx(n - 1)} ${my(n - 1)}`
+    for (let i = 0; i < n; i++) d += `Q${f(x[i] * sx)} ${f(y[i] * sy)} ${mx(i)} ${my(i)}`
+    return d + 'Z'
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { Growth, densityFrom, SIM_W } from './engine.js'
+export { mulberry32 } from './rng.js'
+export { orbCanvas, pathCanvas } from './shapes.js'

package/src/rng.js

@@ -0,0 +1,13 @@
+// rng — the seeded PRNG the growing line takes as `rand`, carried verbatim from kol-fxr (src/loops/gl/rng.js).
+
+/** Deterministic 0..1 PRNG seeded by an integer. Same seed → same sequence. */
+export function mulberry32(seed) {
+  let a = seed >>> 0
+  return function () {
+    a |= 0
+    a = (a + 0x6D2B79F5) | 0
+    let t = Math.imul(a ^ (a >>> 15), 1 | a)
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}

package/src/selftest.mjs

@@ -0,0 +1,31 @@
+// node src/selftest.mjs — the engine with no density field (no DOM): it grows to the cap, a seed repeats, poke moves nodes.
+import assert from 'node:assert/strict'
+import { Growth, mulberry32 } from './index.js'
+
+const grow = (seed) => {
+  const g = new Growth({ w: 400, h: 300, rand: mulberry32(seed), cap: 600 })
+  g.setParams({ minGap: 6, maxGap: 24, contrast: 1.4, growth: 8 })
+  g.seed()
+  for (let i = 0; i < 400 && g.x.length < g.cap; i++) g.step()
+  return g
+}
+const a = grow(7), b = grow(7)
+assert.ok(a.x.length >= a.cap - 8, `grows to the cap (${a.x.length}/${a.cap})`)
+assert.deepEqual(a.x, b.x, 'same seed, same line')
+assert.ok(a.x.every((v, i) => v >= 2 && v <= 398 && a.y[i] >= 2 && a.y[i] <= 298), 'held inside the frame')
+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')
+/* 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')

package/src/shapes.js

@@ -0,0 +1,40 @@
+// Shapes — the density sources the growing line reads with `densityFrom`: dark on light, at the frame's aspect.
+// The one DOM in this engine (as `densityFrom` itself): a shape is a canvas, so these run in a browser.
+
+/* the built-in orb, kol-fxr's `sourceCanvas('orb')` carried verbatim: a radial gradient, black at the centre */
+export function orbCanvas(aspect) {
+  const W = 400, H = Math.max(1, Math.round(W / aspect))
+  const c = document.createElement('canvas')
+  c.width = W; c.height = H
+  const g = c.getContext('2d')
+  g.fillStyle = '#fff'; g.fillRect(0, 0, W, H)
+  const r = Math.min(W, H) * 0.46
+  const grd = g.createRadialGradient(W / 2, H / 2, 0, W / 2, H / 2, r)
+  grd.addColorStop(0, '#000'); grd.addColorStop(1, '#fff')
+  g.fillStyle = grd; g.fillRect(0, 0, W, H)
+  return c
+}
+
+/* any SVG path `d`, filled solid black on white, centred and scaled to `fit` of the frame — kol-fxr's `vectorCanvas`
+ * for a bare path: synchronous (no image decode), the bounds measured by the browser's own SVG `getBBox` */
+export function pathCanvas(d, aspect, fit = 0.6) {
+  const W = 400, H = Math.max(1, Math.round(W / aspect))
+  const c = document.createElement('canvas')
+  c.width = W; c.height = H
+  const g = c.getContext('2d')
+  g.fillStyle = '#fff'; g.fillRect(0, 0, W, H)
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
+  svg.setAttribute('style', 'position:absolute;width:0;height:0;overflow:hidden')
+  const path = document.createElementNS('http://www.w3.org/2000/svg', 'path')
+  path.setAttribute('d', d)
+  svg.appendChild(path)
+  document.body.appendChild(svg)
+  let b
+  try { b = path.getBBox() } finally { svg.remove() }
+  if (!b.width || !b.height) return c
+  const k = Math.min(W / b.width, H / b.height) * fit
+  g.setTransform(k, 0, 0, k, (W - b.width * k) / 2 - b.x * k, (H - b.height * k) / 2 - b.y * k)
+  g.fillStyle = '#000'
+  g.fill(new Path2D(d))
+  return c
+}