@flogeez/murmuration 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Florian Etourneau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# murmuration
 
-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.
+A flock of birds that draws shapes. The birds land on a list of points, settle tight on a shape's outline and sparse inside it, circle a zone above it, shy away from the pointer, and follow the page section by section. One canvas, plain ES modules, no build, no dependency.
+
+It is the engine behind the starlings of [florian-etourneau.dev](https://florian-etourneau.dev). Birds are only the default: give it a fish, a leaf or a dot and it becomes a school, a gust or a swarm of fireflies. **[Try the demo](https://flogeez.github.io/murmuration/demo/)**: type a word, draw a line, change the glyph, tune the flock and copy the code.
+
+```sh
+npm i @flogeez/murmuration
+```
+
+## A flock in a canvas
+
+```js
+import { createMurmuration, sampleShape, fitShape, solid, hollow } from '@flogeez/murmuration';
+
+const ring = (g) => { solid(g); g.beginPath(); g.arc(360, 320, 260, 0, 6.2832); g.fill(); hollow(g); g.beginPath(); g.arc(360, 320, 150, 0, 6.2832); g.fill(); solid(g); };
+
+const m = createMurmuration(canvas, { frame: 'canvas', count: 320 });
+m.perch(fitShape(sampleShape(ring, 288), { width: canvas.clientWidth, height: canvas.clientHeight }), {
+  rest: 'circle', zone: () => ({ x: canvas.clientWidth / 2, y: 40, rx: canvas.clientWidth * 0.3, ry: 20 }),
+});
+```
+
+`m.fly()` lets the flock fly freely, `m.scatter()` sends it away, `m.setColors(colors)` and `m.setGlyph(glyph)` restyle it, `m.setCount(n)` adds or removes birds (perch again to share the places out), `m.destroy()` stops it and removes its listeners.
+
+A glyph is any SVG path facing right. Birds, fish and leaves work, and so does plain geometry: a dot, a square, or a triangle that travels nose first, the classic way of drawing boids.
+
+```js
+const TRIANGLE = { path: 'M20 10 L0 2 L4 10 L0 18 Z', anchor: [8, 10], scale: 0.55, flight: 'glyph' };
+m.setGlyph(TRIANGLE);
+```
+
+## With a framework
+
+The engine owns a canvas and nothing else, so any framework only has to create it after mounting and destroy it on unmount.
+
+```jsx
+// React
+function Flock({ shape }) {
+  const ref = useRef(null);
+  useEffect(() => {
+    const canvas = ref.current, m = createMurmuration(canvas, { frame: 'canvas' });
+    m.perch(fitShape(sampleShape(shape, 240), { width: canvas.clientWidth, height: canvas.clientHeight }));
+    return () => m.destroy();
+  }, [shape]);
+  return <canvas ref={ref} style={{ width: '100%', aspectRatio: '9 / 8' }} />;
+}
+```
+
+```js
+// Vue
+onMounted(() => { m = createMurmuration(canvas.value, { frame: 'canvas' }); });
+onUnmounted(() => m.destroy());
+```
+
+## Options
+
+`createMurmuration(canvas, options)`:
+
+| Option | Default | |
+| --- | --- | --- |
+| `frame` | `'page'` | `'page'`: a fixed canvas over the whole page, the birds in document coordinates. `'canvas'`: the flock lives inside the canvas, in its own coordinates, with soft walls |
+| `count` | `170` | How many birds |
+| `colors` | two greys | The birds' colours, in turn |
+| `glyph` | `PLAIN_BIRD` | The perched bird: `{ path, anchor, scale, flight }`, an SVG path facing right, the point that sits on its place, its scale, and how it travels: `'wings'` (default, flapping wings) or `'glyph'` (the glyph itself, turned towards its heading) |
+| `scale` | the glyph's | Overrides the glyph's scale |
+| `debug` | `false` | Shows the places, the swarm's zone and the current scene |
+
+`m.perch(points, options)`:
+
+| Option | |
+| --- | --- |
+| `rest` | Birds without a place: `'fly'` (default), `'double'` (squeeze next to a perched one), `'circle'` (in `zone`), `'leave'` |
+| `zone` | Function returning an ellipse `{ x, y, rx, ry }` or a path `{ path: [[x, y], …] }` where the swarm circles |
+| `keep` | With `'circle'`: how many birds circle; the others leave |
+| `anchor` | Function returning the origin `[x, y]` of the points: the shape follows a moving element |
+| `shy` | Perched birds fly off when the pointer comes close, then land again |
+| `instant` | Land at once |
+
+`prefers-reduced-motion` is honoured: the birds are placed without moving.
+
+## Shapes
+
+A shape is a function that draws on a 720 × 640 canvas: fill the matter (`solid`), hollow out the holes (`hollow`). `sampleShape(draw, count)` turns it into about `count` landing points, cached per shape; `fitShape(points, { width, height }, { zoom, dx, dy })` centres them in a box. A shape that changes over time gives its cache key, as `draw.key()` or the `{ key }` option.
+
+## A page in scenes
+
+```js
+import { createScenes } from '@flogeez/murmuration';
+
+const scenes = createScenes(m, [
+  { name: 'hero', active: () => scrollY < 300, pose: ({ first }) => ({ points: wirePoints(), instant: first, rest: 'circle', zone: heroOrbit }) },
+  { name: 'story', active: () => inView(story), variant: () => step.dataset.shape, pose: ({ variant }) => ({ points: shapePoints(variant), anchor: origin }) },
+]);
+addEventListener('scroll', () => requestAnimationFrame(() => scenes.update()), { passive: true });
+```
+
+The first active scene wins; no active scene, the flock flies freely. `variant()` re-lands the flock when a scene changes without scrolling; `update(true)` lands it again after a resize.
+
+`animate(update)` is a shared animation loop for anything else that moves: `update(dt)` returns `false` to stop.
+
+## Demo
+
+`npx serve .`, then open `demo/`.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/index.js

@@ -0,0 +1,5 @@
+/* @flogeez/murmuration — a flock of birds that draws shapes, follows the page section by section, and its scene engine. */
+export { createMurmuration, PLAIN_BIRD } from './murmuration.js';
+export { createScenes } from './scenes.js';
+export { sampleShape, fitShape, SHAPE_WIDTH, SHAPE_HEIGHT, roundRect, solid, hollow, stroke } from './shapes.js';
+export { animate } from './loop.js';

package/loop.js

@@ -0,0 +1,15 @@
+/* One animation loop for every animated bird (or anything else) on the page.
+   animate(update): update(dt) is called on each frame, dt in seconds, capped at 50 ms. It returns false to stop.
+   The loop goes to sleep as soon as nothing moves. Returns a function that stops this update. */
+const updates = new Set();
+let raf = 0, prev = 0;
+const tick = (now) => {
+  const dt = Math.min(0.05, Math.max(0, (now - prev) / 1000)); prev = now;
+  for (const update of [...updates]) if (update(dt) === false) updates.delete(update);
+  raf = updates.size ? requestAnimationFrame(tick) : 0;
+};
+export function animate(update) {
+  updates.add(update);
+  if (!raf) { prev = performance.now(); raf = requestAnimationFrame(tick); }
+  return () => updates.delete(update);
+}

package/murmuration.js

@@ -0,0 +1,261 @@
+/* The murmuration — a flock of birds that goes along the whole page, or lives inside a canvas.
+ * A fixed canvas behind the content; the birds live in document coordinates.
+ *   const m = createMurmuration(canvas, { count: 170, colors: ['#2B2A33', '#5E5C6B'], frame: 'page', glyph, debug: false });
+ *   frame: 'page' (default) — a fixed canvas over the whole page, the birds in document coordinates;
+ *          'canvas' — the flock lives inside the canvas itself (a plate, a slide), in the canvas's own coordinates
+ *   glyph: the perched bird, { path: SVG path d, anchor: [x, y] (the point that sits on its place), scale, flight }; a plain bird by default
+ *          flight: 'wings' (default) draws flying birds as flapping wings; 'glyph' draws the glyph itself, turned towards its heading (a fish, a leaf)
+ *   m.perch(points, options)  // land on a list of [x, y] points (document coordinates); options: see perch
+ *   (choosing the scene, section by section, is the scene engine's job: scenes.js)
+ *   m.fly()          // fly freely in the viewport's margin
+ *   m.scatter()      // leave the screen
+ *   m.setGlyph(glyph) // change the glyph of the whole flock
+ *   m.setCount(n)    // add or remove birds; perch again to share the places out
+ *   m.destroy()      // stop and remove every listener
+ */
+// Flock speeds (1 = the original setting at 60 frames/s):
+// SPEED_PERCH for birds on their way to a place (shapes, wire, path); SPEED_FREE for the circling flock, slower:
+// it stays on screen during the whole read and must not draw the eye; SPEED_AWAY for those leaving the screen.
+const SPEED_PERCH = 2, SPEED_FREE = 0.8, SPEED_AWAY = 1;
+// the default perched bird: a plain songbird in profile, about 12 px high, its feet on its place
+export const PLAIN_BIRD = { path: 'M66 14 C56 8 44 12 41 24 C39 33 39 42 33 52 C27 62 18 70 8 78 L22 77 C30 72 38 66 46 63 C60 58 70 46 70 32 L84 30 L70 25 C69 20 68 17 66 14 Z', anchor: [44, 64], scale: 0.17 };
+export function createMurmuration(canvas, opts = {}) {
+  const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  const ctx = canvas.getContext('2d');
+  let colors = opts.colors || ['#2B2A33', '#5E5C6B'];
+  let glyph, GLYPH, GX, GY, S;
+  const useGlyph = (g) => { glyph = g; GLYPH = new Path2D(g.path); [GX, GY] = g.anchor; S = opts.scale || g.scale; };
+  useGlyph(opts.glyph || PLAIN_BIRD);
+  // every listener goes through this signal, so that destroy() removes them all
+  const life = new AbortController(), signal = life.signal;
+  // the view: the viewport scrolled over the page, or the canvas itself
+  const inCanvas = opts.frame === 'canvas';
+  const viewX = () => (inCanvas ? 0 : scrollX), viewY = () => (inCanvas ? 0 : scrollY);
+  let zoneFn = null, Z = null, anchor = null, origin = [0, 0], prevAnchor = null, prevOrigin = [0, 0], waitEnd = 0, vw = inCanvas ? canvas.clientWidth : innerWidth, vh = inCanvas ? canvas.clientHeight : innerHeight, dpr = 1, raf = 0, mx = null, my = null, running = true;
+  const resize = () => {
+    dpr = Math.min(2, window.devicePixelRatio || 1);
+    if (inCanvas) { vw = canvas.clientWidth; vh = canvas.clientHeight; } else { vw = innerWidth; vh = innerHeight; canvas.style.width = vw + 'px'; canvas.style.height = vh + 'px'; }
+    canvas.width = vw * dpr; canvas.height = vh * dpr;
+    if (reduced) draw();
+  };
+  const B = [], grid = new Map();
+  const bird = (k) => ({ x: viewX() + vw * (0.2 + Math.random() * 0.6), y: viewY() + vh * Math.random() * 0.5, vx: Math.random() - 0.5, vy: Math.random() - 0.5, t: null, perched: false, away: false, ph: Math.random() * 6.283, c: colors[k % colors.length] });
+  for (let k = 0; k < (opts.count || 170); k++) B.push(bird(k));
+  resize(); addEventListener('resize', resize, { signal });
+  const sizeWatch = inCanvas && 'ResizeObserver' in window ? new ResizeObserver(resize) : null;
+  if (sizeWatch) sizeWatch.observe(canvas);
+  // the pointer, in the view's coordinates: recomputed on scroll too (the pointer stays still, the page moves)
+  let px0 = null, py0 = null;
+  const track = () => {
+    if (px0 == null) return;
+    if (inCanvas) { const r = canvas.getBoundingClientRect(); mx = px0 - r.left; my = py0 - r.top; } else { mx = px0 + scrollX; my = py0 + scrollY; }
+    if (shy) dirty = true;
+  };
+  addEventListener('pointermove', (e) => { px0 = e.clientX; py0 = e.clientY; track(); }, { passive: true, signal });
+  addEventListener('scroll', track, { passive: true, signal });
+  document.addEventListener('pointerleave', () => { px0 = mx = null; }, { signal });
+  // shy: perched birds fly off when the pointer comes close, circle above their place, then land on it again
+  let shy = false;
+  function startle(b, ms) { b.perched = false; const a = Math.atan2(b.y - my, b.x - mx); b.vx = Math.cos(a) * 2.5 + (Math.random() - 0.5); b.vy = -2.5 - Math.random() * 1.5; b.fright = ms + 900 + Math.random() * 500; }
+
+  function takeOff(b) { b.wait = 0; b.orb = false; b.fright = 0; if (b.perched) { b.vy -= 2 + Math.random() * 1.5; b.vx += (Math.random() - 0.5) * 2; } b.perched = false; b.t = null; }
+  // birds that left come back from the side the page comes from: from the top when scrolling up, from the bottom when scrolling down
+  let prevScroll = scrollY, goingUp = false;
+  addEventListener('scroll', () => { if (scrollY !== prevScroll) goingUp = scrollY < prevScroll; prevScroll = scrollY; }, { passive: true, signal });
+  function comeBack(b) {
+    if (!b.away) return; b.away = false;
+    b.x = viewX() + vw * (0.1 + Math.random() * 0.8);
+    b.y = viewY() + (goingUp ? -20 - Math.random() * 60 : vh + 20 + Math.random() * 60);
+    b.vx = (Math.random() - 0.5) * 2; b.vy = goingUp ? 2 + Math.random() : -2 - Math.random();
+  }
+  // Leaving the screen: the whole flock leaves the same way, up and to the right (±20°), not in a star from the centre
+  function leave(b) { b.away = true; const a = -Math.PI / 3 + (Math.random() - 0.5) * 0.7; b.ex = Math.cos(a); b.ey = Math.sin(a); }
+  // The attraction point of a path: it goes back and forth along the polyline, at 70 px/s, with a slight float
+  function alongPath(pts, now) {
+    const lg = pts.slice(1).map((p, i) => Math.hypot(p[0] - pts[i][0], p[1] - pts[i][1])), total = lg.reduce((a, l) => a + l, 0) || 1;
+    let s = (now * 70) % (2 * total); if (s > total) s = 2 * total - s;
+    let i = 0; while (i < lg.length - 1 && s > lg[i]) { s -= lg[i]; i++; }
+    const u = lg[i] ? Math.min(1, s / lg[i]) : 0, a = pts[i], z = pts[i + 1] || a;
+    return [a[0] + (z[0] - a[0]) * u + Math.cos(now * 0.87) * 14, a[1] + (z[1] - a[1]) * u + Math.sin(now * 1.13) * 14];
+  }
+  // Land on the points T. Options:
+  //   instant: the birds land at once (first display, resize)
+  //   rest: what do birds without a place do? 'fly' (default), 'double' (squeeze next to another one), 'circle' (in the zone), 'leave'
+  //   anchor: function returning the origin [x, y] (document) of the points T; the shape then follows a moving element (position sticky…)
+  //   zone: function returning the ellipse {x, y, rx, ry} (document) where birds without a place circle (rest = 'circle'),
+  //         or a path {path: [[x, y], …]} (document) along which they go back and forth
+  //   keep: with 'circle', how many birds without a place circle; the others leave (all of them circle by default)
+  //   shy: perched birds fly off when the pointer comes close (see startle)
+  function perch(T, { instant = false, rest = 'fly', anchor: anc = null, zone = null, keep = Infinity, shy: isShy = false } = {}) {
+    idle = false; shy = isShy;
+    zoneFn = rest === 'circle' ? zone : null;
+    // the flock re-forms: perched birds fly off one after the other, from left to right
+    const now = performance.now(), before = B.map((b) => (b.perched && b.t && !reduced && !instant ? b.t : null));
+    prevAnchor = anchor; prevOrigin = anchor ? anchor() : [0, 0];
+    anchor = anc; origin = anc ? anc() : [0, 0];
+    B.forEach(takeOff);
+    // more places than birds: keep places spread over the whole shape, not only its left part
+    const spread = T.length > B.length ? Array.from({ length: B.length }, (_, j) => T[Math.floor(j * T.length / B.length)]) : [...T];
+    const tg = spread.sort((a, c) => a[0] - c[0]);
+    const n = Math.min(tg.length, B.length), taken = new Set();
+    // places go first to the birds on screen: birds that left only come back if some are missing
+    const present = B.map((b, k) => k).filter((k) => !B[k].away);
+    const order = (present.length >= n ? present : B.map((b, k) => k)).sort((a, c) => B[a].x - B[c].x), stride = order.length / n;
+    for (let j = 0; j < n; j++) { const k = order[Math.floor(j * stride)]; B[k].t = tg[j]; taken.add(k); }
+    let kept = 0;
+    B.forEach((b, k) => {
+      if (!taken.has(k) && n && n < B.length) {
+        if (rest === 'double') { const p = tg[Math.floor(Math.random() * n)]; b.t = [p[0] + (Math.random() < 0.5 ? -4 : 4), p[1]]; }
+        else if (rest === 'circle' && zone && kept < keep) { b.orb = true; kept++; }
+        else if (rest === 'leave' || (rest === 'circle' && zone)) { if (!b.away) leave(b); return; } // already gone: they stay gone
+      }
+      comeBack(b);
+    });
+    const waiting = B.map((b, k) => k).filter((k) => before[k]).sort((a, c) => before[a][0] - before[c][0]);
+    waiting.forEach((k, r) => { const b = B[k]; b.ot = before[k]; b.wait = now + (r / waiting.length) * 500 + Math.random() * 140; b.perched = true; b.vx = b.vy = 0; });
+    waitEnd = now + 700;
+    if (reduced || instant) { B.forEach((b) => { if (b.t) { b.x = b.t[0] + origin[0]; b.y = b.t[1] + origin[1]; b.perched = true; } }); draw(); }
+  }
+  function fly() { idle = false; shy = false; anchor = null; zoneFn = null; B.forEach((b) => { takeOff(b); comeBack(b); }); if (reduced) draw(); }
+  function scatter() {
+    idle = false; shy = false;
+    anchor = null; zoneFn = null;
+    B.forEach((b) => { takeOff(b); leave(b); });
+    if (reduced) draw();
+  }
+  function offscreen(b) { const x = viewX(), y = viewY(); return b.x < x - 60 || b.x > x + vw + 60 || b.y < y - 60 || b.y > y + vh + 60; }
+  // dt: the elapsed time, in "frames at 60 Hz"; each bird multiplies it by its speed (k)
+  function step(dt = 1) {
+    const now = performance.now() / 1000;
+    // free-flight zone: on a page, the right margin of the viewport, a little above the middle; in a canvas, around its centre
+    const ax = inCanvas ? vw / 2 + Math.cos(now * 0.33) * vw * 0.2 : scrollX + vw * (vw > 900 ? 0.86 : 0.66) + Math.cos(now * 0.33) * vw * 0.1;
+    const ay = inCanvas ? vh / 2 + Math.sin(now * 0.51) * vh * 0.1 : scrollY + vh * 0.3 + Math.sin(now * 0.51) * vh * 0.15;
+    origin = anchor ? anchor() : [0, 0];
+    Z = zoneFn ? zoneFn() : null;
+    if (Z && Z.path) Z.point = alongPath(Z.path, now);
+    const ms = performance.now(); if (prevAnchor && ms < waitEnd) prevOrigin = prevAnchor();
+    // neighbourhood: a 40 px grid for the free birds (the flock counts several hundred birds)
+    grid.clear();
+    for (const o of B) { if (o.perched || o.away || o.t) continue; const c = Math.floor(o.x / 40) * 100003 + Math.floor(o.y / 40); const l = grid.get(c); if (l) l.push(o); else grid.set(c, [o]); }
+    for (const b of B) {
+      if (b.perched) {
+        if (b.wait) {
+          if (ms < b.wait) { b.x = b.ot[0] + prevOrigin[0]; b.y = b.ot[1] + prevOrigin[1]; continue; }
+          b.wait = 0; b.perched = false; b.vy = -(1.5 + Math.random() * 2); b.vx = (Math.random() - 0.5) * 2;
+        } else {
+          if (anchor && b.t) { b.x = b.t[0] + origin[0]; b.y = b.t[1] + origin[1]; }
+          if (!(shy && b.t && mx != null && Math.hypot(b.x - mx, b.y - my) < 56)) continue;
+          startle(b, ms);
+        }
+      }
+      const k = dt * (b.away ? SPEED_AWAY : b.t && !b.fright ? SPEED_PERCH : SPEED_FREE);
+      if (b.away) { if (offscreen(b)) continue; b.vx += b.ex * 0.14 * k; b.vy += b.ey * 0.14 * k; const v = Math.hypot(b.vx, b.vy); if (v > 4.5) { b.vx = b.vx / v * 4.5; b.vy = b.vy / v * 4.5; } b.x += b.vx * k; b.y += b.vy * k; continue; }
+      let fx = 0, fy = 0;
+      // scrolling is faster than the birds: those that fall behind come back in through the nearest edge
+      if (!b.t) {
+        const y0 = viewY();
+        if (b.y < y0 - 220) { b.y = y0 - 30; b.vy = Math.abs(b.vy) + 1; }
+        else if (b.y > y0 + vh + 220) { b.y = y0 + vh + 30; b.vy = -Math.abs(b.vy) - 1; }
+      } else {
+        const ty = b.t[1] + origin[1];
+        if (Math.abs(b.y - ty) > vh * 0.9) { b.y = ty + (b.y < ty ? -vh * 0.6 : vh * 0.6); }
+      }
+      const tx = b.t ? b.t[0] + origin[0] : 0, ty = b.t ? b.t[1] + origin[1] : 0;
+      if (b.fright && b.t && (ms < b.fright || (mx != null && Math.hypot(tx - mx, ty - my) < 90))) {
+        // startled: it circles above its place while the pointer is there, then comes back to land on it
+        if (ms >= b.fright) b.fright = ms + 300;
+        const px = tx + Math.cos(now * 1.6 + b.ph) * 36, py = ty - 64 + Math.sin(now * 2.1 + b.ph) * 18;
+        fx = (px - b.x) * 0.006 - b.vx * 0.04; fy = (py - b.y) * 0.006 - b.vy * 0.04;
+      } else if (b.t) {
+        b.fright = 0;
+        const dx = tx - b.x, dy = ty - b.y, d = Math.hypot(dx, dy);
+        if (d < 1.2) { b.perched = true; b.x = b.t[0] + origin[0]; b.y = b.t[1] + origin[1]; b.vx = b.vy = 0; continue; }
+        const sp = Math.min(d > 300 ? 12 : 5.5, d * 0.08);
+        // on the way, the flock swirls a little before landing
+        const swirl = Math.min(0.75, Math.max(0, (d - 50) / 380)), ca = Math.cos(swirl), sa = Math.sin(swirl), ux = dx / d, uy = dy / d;
+        fx = (ux * ca - uy * sa) * sp - b.vx; fy = (ux * sa + uy * ca) * sp - b.vy;
+        const lim = d > 300 ? 1.2 : 0.45, f = Math.hypot(fx, fy); if (f > lim) { fx = fx / f * lim; fy = fy / f * lim; }
+      } else {
+        let sx = 0, sy = 0, axx = 0, ayy = 0, cx = 0, cy = 0, n = 0;
+        const gx = Math.floor(b.x / 40), gy = Math.floor(b.y / 40);
+        for (let i = -1; i <= 1; i++) for (let j = -1; j <= 1; j++) { const l = grid.get((gx + i) * 100003 + gy + j); if (l) for (const o of l) {
+          if (o === b) continue;
+          const dx = o.x - b.x, dy = o.y - b.y, d2 = dx * dx + dy * dy;
+          if (d2 < 1600) { n++; axx += o.vx; ayy += o.vy; cx += o.x; cy += o.y; if (d2 < 420) { const d = Math.sqrt(d2) || 1; sx -= dx / d * (1 - d / 20.5); sy -= dy / d * (1 - d / 20.5); } }
+        } }
+        if (n) { fx += (axx / n - b.vx) * 0.05 + (cx / n - b.x) * 0.0007; fy += (ayy / n - b.vy) * 0.05 + (cy / n - b.y) * 0.0007; }
+        if (b.orb && Z) {
+          // like the whole flock: an attraction point wandering in the zone, and the swarm's rules do the rest
+          let px, py;
+          if (Z.path) { [px, py] = Z.point; b.far = Math.hypot(b.x - px, b.y - py) > 220; }
+          else {
+            px = Z.x + Math.cos(now * 0.33) * Z.rx * 0.7 + Math.cos(now * 0.87) * Z.rx * 0.2; py = Z.y + Math.sin(now * 0.51) * Z.ry * 0.7 + Math.sin(now * 1.13) * Z.ry * 0.2;
+            b.far = Math.hypot((b.x - Z.x) / Z.rx, (b.y - Z.y) / Z.ry) > 1.8;
+          }
+          const pull = b.far ? 0.004 : 0.0011;
+          fx += sx * 0.35 + (px - b.x) * pull; fy += sy * 0.35 + (py - b.y) * pull;
+        } else { fx += sx * 0.35 + (ax - b.x) * 0.0006; fy += sy * 0.35 + (ay - b.y) * 0.0006; }
+        // in a canvas, soft walls: a free bird nearing an edge is turned back inside, so the flock is never cut by the frame
+        if (inCanvas) { const M = 48; if (b.x < M) fx += (M - b.x) * 0.01; else if (b.x > vw - M) fx -= (b.x - vw + M) * 0.01; if (b.y < M) fy += (M - b.y) * 0.01; else if (b.y > vh - M) fy -= (b.y - vh + M) * 0.01; }
+      }
+      if (mx != null) { const dx = b.x - mx, dy = b.y - my, d2 = dx * dx + dy * dy; if (d2 < 7000 && (!b.t || b.fright)) { const d = Math.sqrt(d2) || 1, f = (1 - d / 84) * 1.4; fx += dx / d * f; fy += dy / d * f; } }
+      b.vx += fx * k; b.vy += fy * k;
+      const v = Math.hypot(b.vx, b.vy), vmax = b.fright ? 3.2 : b.t ? 12 : b.orb && b.far ? 9 : 3.2, vmin = b.t && !b.fright ? 0 : 1.3;
+      if (v > vmax) { b.vx = b.vx / v * vmax; b.vy = b.vy / v * vmax; } else if (v < vmin && v > 0) { b.vx = b.vx / v * vmin; b.vy = b.vy / v * vmin; }
+      b.x += b.vx * k; b.y += b.vy * k;
+    }
+    draw(now);
+  }
+  function draw(now = 0) {
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0); ctx.clearRect(0, 0, vw, vh);
+    ctx.translate(-viewX(), -viewY()); ctx.lineCap = 'round'; ctx.lineJoin = 'round';
+    for (const b of B) {
+      if (offscreen(b)) continue;
+      if (b.perched) {
+        ctx.globalAlpha = 1; ctx.save(); ctx.translate(b.x - GX * S, b.y - GY * S); ctx.scale(S, S); ctx.fillStyle = b.c; ctx.fill(GLYPH); ctx.restore();
+      } else if (!reduced && glyph.flight === 'glyph') {
+        ctx.globalAlpha = b.t ? 0.95 : 0.5; ctx.save(); ctx.translate(b.x, b.y); ctx.rotate(Math.atan2(b.vy, b.vx)); ctx.scale(S, S); ctx.translate(-GX, -GY); ctx.fillStyle = b.c; ctx.fill(GLYPH); ctx.restore();
+      } else if (!reduced) {
+        ctx.globalAlpha = b.t ? 0.95 : 0.5;
+        const w = Math.sin(now * 16 + b.ph) * 2.4; ctx.save(); ctx.translate(b.x, b.y); ctx.rotate(Math.atan2(b.vy, b.vx) * 0.25);
+        ctx.strokeStyle = b.c; ctx.lineWidth = 1.6; ctx.beginPath(); ctx.moveTo(-5, w); ctx.quadraticCurveTo(-2.4, -1.2, 0, 0.9); ctx.quadraticCurveTo(2.4, -1.2, 5, w); ctx.stroke(); ctx.restore();
+      }
+    }
+    ctx.globalAlpha = 1;
+    if (opts.debug) drawDebug();
+  }
+  // debug: the places (crosses), the zone where the swarm circles (ellipse or path) and its attraction point
+  function drawDebug() {
+    ctx.save(); ctx.lineWidth = 1; ctx.strokeStyle = '#C8612E'; ctx.fillStyle = '#C8612E';
+    for (const b of B) if (b.t) { const x = b.t[0] + origin[0], y = b.t[1] + origin[1]; ctx.beginPath(); ctx.moveTo(x - 2, y - 2); ctx.lineTo(x + 2, y + 2); ctx.moveTo(x + 2, y - 2); ctx.lineTo(x - 2, y + 2); ctx.stroke(); }
+    if (Z) {
+      ctx.setLineDash([4, 4]); ctx.beginPath();
+      if (Z.path) Z.path.forEach(([x, y], i) => (i ? ctx.lineTo(x, y) : ctx.moveTo(x, y)));
+      else ctx.ellipse(Z.x, Z.y, Z.rx, Z.ry, 0, 0, Math.PI * 2);
+      ctx.stroke(); ctx.setLineDash([]);
+      if (Z.point) { ctx.beginPath(); ctx.arc(Z.point[0], Z.point[1], 4, 0, Math.PI * 2); ctx.fill(); }
+    }
+    ctx.restore();
+  }
+  // at rest (all perched, nothing moves) nothing is recomputed: the flock is only redrawn on scroll or resize
+  let idle = false, dirty = true;
+  const wake = () => { dirty = true; };
+  addEventListener('scroll', wake, { passive: true, signal }); addEventListener('resize', wake, { signal });
+  // The step follows real time, not the number of frames: same speed at 60, 120 or 144 Hz.
+  // Capped at 3 frames so that a hiccup (throttled tab, garbage collector) does not teleport the flock.
+  let prevT = 0;
+  const loop = (t) => {
+    const dt = prevT ? Math.min(3, (t - prevT) / (1000 / 60)) : 1; prevT = t;
+    if (running && (!idle || dirty)) { dirty = false; step(dt); idle = B.every((b) => (b.perched && !b.wait) || (b.away && offscreen(b))); }
+    raf = requestAnimationFrame(loop);
+  };
+  if (reduced) { addEventListener('scroll', () => { if (anchor) { origin = anchor(); B.forEach((b) => { if (b.perched && b.t) { b.x = b.t[0] + origin[0]; b.y = b.t[1] + origin[1]; } }); } draw(); }, { passive: true, signal }); draw(); } else loop();
+  document.addEventListener('visibilitychange', () => { running = !document.hidden; }, { signal });
+  return {
+    perch, fly, scatter,
+    setColors(c) { idle = false; colors = c; B.forEach((b, k) => { b.c = colors[k % colors.length]; }); if (reduced) draw(); },
+    setGlyph(g) { idle = false; useGlyph(g); if (reduced) draw(); },
+    setCount(n) { idle = false; while (B.length < n) B.push(bird(B.length)); B.length = Math.max(0, n); if (reduced) draw(); },
+    destroy() { cancelAnimationFrame(raf); life.abort(); if (sizeWatch) sizeWatch.disconnect(); },
+  };
+}

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@flogeez/murmuration",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A flock of birds that draws shapes on a canvas: lands on points, circles a zone, shies away from the pointer, follows the page section by section. Plain ES modules, no build, no dependency.",
+  "keywords": ["murmuration", "flock", "boids", "canvas", "animation", "starlings"],
+  "author": "Florian Etourneau",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FloGeez/murmuration.git"
+  },
+  "homepage": "https://github.com/FloGeez/murmuration#readme",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./index.js",
+    "./murmuration": "./murmuration.js",
+    "./scenes": "./scenes.js",
+    "./shapes": "./shapes.js",
+    "./loop": "./loop.js"
+  },
+  "files": [
+    "*.js"
+  ]
+}

package/scenes.js

@@ -0,0 +1,55 @@
+/* The scene engine: each section of the page describes a scene; the engine picks the one on screen and lands the flock on it.
+ *
+ *   const scenes = createScenes(murmuration, [
+ *     { name: 'wire', active: () => scrollY < 300, pose: () => ({ points: wirePoints(), rest: 'circle', zone: orbit }) },
+ *     …
+ *   ]);
+ *   scenes.update()      // on scroll: switches scene if needed
+ *   scenes.update(true)  // the page moved (resize, fonts): lands the flock again on the current scene
+ *
+ * A scene:
+ *   name: its name (shown in debug mode)
+ *   active(): true when the scene is on screen; the first active scene, in array order, wins
+ *   variant(): optional, for a scene that changes without scrolling (the current step's shape); the engine checks it
+ *              twice a second and lands the flock again when it changes
+ *   pose({ variant, first, force, same }): the points to land on (points) and the options of murmuration.perch (rest, zone,
+ *              anchor, keep, shy, instant). By default, the flock lands at once on the first scene, or when the same scene
+ *              is forced again; otherwise it flies to its places.
+ * No active scene: the flock flies freely.
+ */
+export function createScenes(murmuration, scenes, { debug = false } = {}) {
+  let key = '', current = null, first = true;
+  const label = debug ? createLabel() : null;
+
+  function update(force = false) {
+    const scene = scenes.find((s) => s.active());
+    const variant = scene && scene.variant ? scene.variant() : '';
+    const k = scene ? scene.name + (variant ? ':' + variant : '') : 'fly';
+    if (k !== key || force) {
+      const same = k === key;
+      key = k; current = scene;
+      if (!scene) murmuration.fly();
+      else {
+        const { points, ...options } = scene.pose({ variant, first, force, same });
+        murmuration.perch(points, { instant: first || (force && same), ...options });
+      }
+      if (label) label.textContent = k;
+    }
+    first = false;
+  }
+  const timer = setInterval(() => { if (current && current.variant) update(); }, 500);
+
+  return {
+    update,
+    get scene() { return current ? current.name : 'fly'; },
+    destroy() { clearInterval(timer); if (label) label.remove(); },
+  };
+}
+
+// debug: the current scene's name, bottom left
+function createLabel() {
+  const e = document.createElement('div');
+  e.style.cssText = 'position:fixed;left:8px;bottom:8px;z-index:9999;padding:4px 8px;border-radius:6px;background:#1F1E24;color:#FF8A3D;font:500 12px/1.4 "JetBrains Mono",monospace;pointer-events:none';
+  document.body.append(e);
+  return e;
+}

package/shapes.js

@@ -0,0 +1,58 @@
+/* Shapes the flock draws, and their sampling into landing points.
+   A shape is a function that draws on a 720 × 640 canvas: fill (black), then hollow out (destination-out). The birds fill
+   the matter, and the shape reads through mass and holes, like a real murmuration. Each shape must read in one second.
+
+     const ring = (g) => { solid(g); g.beginPath(); g.arc(360, 320, 260, 0, 6.2832); g.fill(); hollow(g); g.beginPath(); g.arc(360, 320, 150, 0, 6.2832); g.fill(); solid(g); };
+     const points = sampleShape(ring, 300);                     // [[x, y], …] in the 720 × 640 frame
+     m.perch(fitShape(points, box), { anchor: () => [box.left + scrollX, box.top + scrollY] }); */
+export const SHAPE_WIDTH = 720, SHAPE_HEIGHT = 640;
+const W = SHAPE_WIDTH, H = SHAPE_HEIGHT;
+
+/* ——— Drawing helpers, for writing shapes ——— */
+export const roundRect = (g, x, y, w, h, r) => { g.beginPath(); g.roundRect(x, y, w, h, r); };
+export const solid = (g) => { g.globalCompositeOperation = 'source-over'; };
+export const hollow = (g) => { g.globalCompositeOperation = 'destination-out'; };
+export const stroke = (g, x1, y1, x2, y2, width) => { g.lineWidth = width; g.lineCap = 'round'; g.beginPath(); g.moveTo(x1, y1); g.lineTo(x2, y2); g.stroke(); };
+
+/* ——— Sampling ——— */
+const mask = (draw) => {
+  const c = document.createElement('canvas'); c.width = W; c.height = H;
+  const g = c.getContext('2d', { willReadFrequently: true }); g.fillStyle = '#000'; g.strokeStyle = '#000'; draw(g);
+  return g.getImageData(0, 0, W, H).data;
+};
+const inside = (d, x, y) => { x = Math.round(x); y = Math.round(y); return x >= 0 && y >= 0 && x < W && y < H && d[(y * W + x) * 4 + 3] > 128; };
+const fill = (d, De) => {
+  const pts = [], cell = new Map(), C = De;
+  const key = (i, j) => i * 1000 + j;
+  const add = (x, y) => { const k = key(Math.floor(x / C), Math.floor(y / C)); (cell.get(k) || cell.set(k, []).get(k)).push([x, y]); pts.push([x, y]); };
+  const near = (x, y, r) => { const cx = Math.floor(x / C), cy = Math.floor(y / C), n = Math.ceil(r / C); for (let i = -n; i <= n; i++) for (let j = -n; j <= n; j++) { const l = cell.get(key(cx + i, cy + j)); if (l) for (const q of l) if ((q[0] - x) ** 2 + (q[1] - y) ** 2 < r * r) return true; } return false; };
+  // the outline, tight, for legibility…
+  for (let y = 0; y < H; y += 2) for (let x = 0; x < W; x += 2) {
+    if (!inside(d, x, y) || (inside(d, x + 4, y) && inside(d, x - 4, y) && inside(d, x, y + 4) && inside(d, x, y - 4))) continue;
+    if (!near(x, y, De)) add(x, y);
+  }
+  // …and the inside, sparse, for the matter (a triangular grid)
+  const Di = De * 2.1, dy = Di * 0.866;
+  for (let y = Di / 2, r = 0; y < H; y += dy, r++) for (let x = (r % 2 ? Di / 2 : 0) + Di / 4; x < W; x += Di) if (inside(d, x, y) && !near(x, y, De * 1.1)) add(x, y);
+  return pts;
+};
+const fontsReady = () => !document.fonts || document.fonts.status === 'loaded';
+const cache = new Map();
+/** Landing points that draw the shape `draw` (720 × 640 frame), about `count` of them.
+    The result is cached per shape and count; a shape that changes gives its key, as `draw.key()`
+    or as the `key` option (a clock: key = the current minute). A shape that writes text is only cached once the fonts are loaded. */
+export const sampleShape = (draw, count, { key = draw.key ? draw.key() : '' } = {}) => {
+  let perShape = cache.get(draw); if (!perShape) cache.set(draw, (perShape = new Map()));
+  const k = key + '/' + count;
+  if (perShape.has(k)) return perShape.get(k);
+  const d = mask(draw); let lo = 4, hi = 64, best = fill(d, 30);
+  for (let i = 0; i < 8; i++) { const D = (lo + hi) / 2, p = fill(d, D); if (p.length > count) lo = D; else { hi = D; best = p; } }
+  if (fontsReady()) perShape.set(k, best);
+  return best;
+};
+/** Fits shape points (720 × 640 frame) into a box of width × height, centred: points relative to the box's top-left corner.
+    zoom > 1 lets the shape overflow the box a little. */
+export const fitShape = (points, { width, height }, { zoom = 1, dx = 0, dy = 0 } = {}) => {
+  const k = Math.min(width / W, height / H) * zoom, ox = (width - W * k) / 2 + dx, oy = (height - H * k) / 2 + dy;
+  return points.map(([x, y]) => [ox + x * k, oy + y * k]);
+};