@maniclang/workbench 0.1.11

package/examples/circle-in-three.manic

@@ -0,0 +1,156 @@
+// circle-in-three — a story-driven textbook plate: divide one round cake among
+// three friends using exactly two straight cuts. Wrong ideas first, then the
+// lemma (crossing cuts always give four pieces), then the transcendental
+// equation, solved on a graph, then the fair cut - live percentages throughout.
+// The solved height: cos^-1(u) - u sqrt(1-u^2) = pi/3  =>  u = a/R = 0.2649.
+title("Split a Circle in Three - with Two Lines");
+canvas("16:9");
+template("paper");
+masthead("The Problem Book", "Plate VII");
+
+// ---------- layout ----------
+let R = 205;
+let ox = 400;
+let oy = 400;
+let dyE = R/3;          // "evenly spaced" cut height (the wrong guess)
+let dyS = 0.2649*R;     // the solved cut height
+let sf = 1.0228;        // chord length ratio: sqrt(1-0.2649^2)/sqrt(8/9)
+
+// ---------- HUD ----------
+text(head, (cx, 100), "Split a Circle in Three - with Two Lines"); display(head); cursor(head); sticky(head);
+text(cap, (cx, h - 40), ""); size(cap, 26); sticky(cap);
+text(fig, (ox, 648), ""); size(fig, 24); color(fig, dim); sticky(fig);
+
+// ---------- the cake ----------
+circle(cake, (ox, oy), R); outlined(cake); stroke(cake, 3); untraced(cake);
+
+// attempt 1: two diameters
+line(d1, (ox, oy - R), (ox, oy + R)); untraced(d1); stroke(d1, 3);
+line(d2, (ox - R, oy), (ox + R, oy)); untraced(d2); stroke(d2, 3);
+text(q1, (ox + 70, oy - 70), "1"); size(q1, 30); hidden(q1); tag(q1, qlab);
+text(q2, (ox - 70, oy - 70), "2"); size(q2, 30); hidden(q2); tag(q2, qlab);
+text(q3, (ox - 70, oy + 70), "3"); size(q3, 30); hidden(q3); tag(q3, qlab);
+text(q4, (ox + 70, oy + 70), "4"); size(q4, 30); hidden(q4); tag(q4, qlab);
+
+// attempt 2: parallel cuts at thirds (they will SLIDE to the true height later)
+line(cA1, (ox - R*0.94281, oy - dyE), (ox + R*0.94281, oy - dyE)); untraced(cA1); stroke(cA1, 4); color(cA1, red);
+line(cB1, (ox - R*0.94281, oy + dyE), (ox + R*0.94281, oy + dyE)); untraced(cB1); stroke(cB1, 4); color(cB1, red);
+
+// boolean sources (hidden): the disc and the horizontal bands
+circle(disc, (ox, oy), R); hidden(disc);
+rect(rT2, (ox, oy - dyE - 75), 430, 150); hidden(rT2);
+rect(rM2, (ox, oy), 430, 2*dyE); hidden(rM2);
+rect(rB2, (ox, oy + dyE + 75), 430, 150); hidden(rB2);
+rect(rT3, (ox, oy - dyS - 75), 430, 150); hidden(rT3);
+rect(rM3, (ox, oy), 430, 2*dyS); hidden(rM3);
+rect(rB3, (ox, oy + dyS + 75), 430, 150); hidden(rB3);
+
+// the three shares, evenly-spaced version (29.2 / 41.7 / 29.2)
+intersect(capT2, disc, rT2); color(capT2, cyan); opacity(capT2, 0.45); hidden(capT2); tag(capT2, att2);
+intersect(mid2, disc, rM2); color(mid2, gold); opacity(mid2, 0.45); hidden(mid2); tag(mid2, att2);
+intersect(capB2, disc, rB2); color(capB2, magenta); opacity(capB2, 0.45); hidden(capB2); tag(capB2, att2);
+
+// the three shares, solved version (33.3 each)
+intersect(capT3, disc, rT3); color(capT3, cyan); opacity(capT3, 0.45); hidden(capT3); tag(capT3, att3);
+intersect(mid3, disc, rM3); color(mid3, gold); opacity(mid3, 0.45); hidden(mid3); tag(mid3, att3);
+intersect(capB3, disc, rB3); color(capB3, magenta); opacity(capB3, 0.45); hidden(capB3); tag(capB3, att3);
+
+// live percentages, one per share
+counter(pcT, (ox, oy - 128), 0, 1, "", "%"); hidden(pcT);
+counter(pcM, (ox, oy), 0, 1, "", "%"); hidden(pcM);
+counter(pcB, (ox, oy + 128), 0, 1, "", "%"); hidden(pcB);
+
+// ---------- the mathematics panel (right side) ----------
+equation(eqA, (960, 205), `A_{\text{cap}}(a) \;=\; R^2\cos^{-1}\!\frac{a}{R} \;-\; a\sqrt{R^2-a^2}`, 32); hidden(eqA); sticky(eqA);
+equation(eqG, (960, 430), `f(u)=\cos^{-1}u \;-\; u\sqrt{1-u^2} \;-\; \tfrac{\pi}{3}`, 26); hidden(eqG); sticky(eqG);
+arrow(gxa, (850, 560), (1195, 560)); untraced(gxa); stroke(gxa, 2);
+arrow(gya, (880, 655), (880, 495)); untraced(gya); stroke(gya, 2);
+plot(pf, (880, 560), 300, 90, "acos(x)-x*sqrt(1-x^2)-1.047198", (0.01, 0.99));
+untraced(pf); stroke(pf, 3); color(pf, blue);
+roots(rt, pf, magenta); hidden(rt);
+text(rlab, (1040, 596), "u ≈ 0.2649"); size(rlab, 24); color(rlab, magenta); hidden(rlab);
+
+// ================= timeline =================
+
+// ---- the problem
+type(head, 1.1);
+say(cap, "Three friends. One round cake. Two straight cuts. Make it fair.", 0.6);
+draw(cake, 1.2);
+say(fig, "Fig. 1 - the cake", 0.3);
+wait(0.5);
+
+// ---- attempt 1: through the middle, twice
+cue(whoosh);
+say(cap, "First idea: cut through the middle - twice.", 0.5);
+par { draw(d1, 0.7); draw(d2, 0.7); }
+stagger(0.12) { show(q1, 0.3); show(q2, 0.3); show(q3, 0.3); show(q4, 0.3); }
+say(cap, "Four pieces. Perfectly equal - and perfectly useless. We are THREE.", 0.5);
+wait(0.6);
+
+// ---- the lemma: crossing cuts always make four
+say(cap, "Tilt a cut, slide it anywhere: two CROSSING cuts always make four pieces.", 0.5);
+rotate(d2, 38, 1.0, smooth);
+shift(d2, (55, 35), 1.0, smooth);
+pulse(qlab, 0.8);
+say(cap, "Lemma: the two cuts must never cross inside the cake. They must be PARALLEL.", 0.5);
+cue(tick);
+par { fade(d1, 0.5); fade(d2, 0.5); fade(qlab, 0.4); }
+
+// ---- attempt 2: parallel, evenly spaced
+say(fig, "Fig. 2 - parallel cuts at thirds", 0.3);
+say(cap, "Second idea: space the parallel cuts evenly - at thirds of the diameter.", 0.5);
+par { draw(cA1, 0.7); draw(cB1, 0.7); }
+stagger(0.15) { show(capT2, 0.5); show(mid2, 0.5); show(capB2, 0.5); }
+par { show(pcT, 0.3); show(pcM, 0.3); show(pcB, 0.3); }
+par { to(pcT, value, 29.2, 1.3, smooth); to(pcM, value, 41.7, 1.3, smooth); to(pcB, value, 29.2, 1.3, smooth); }
+cue(pop);
+flash(mid2, gold);
+say(cap, "The middle friend grins: 41.7 percent. Evenly SPACED is not evenly SHARED.", 0.5);
+wait(0.8);
+
+// ---- the mathematics: ask the cake
+say(cap, "So ask the cake: how much lies beyond a cut at height a?", 0.5);
+show(eqA, 0.6);
+wait(0.8);
+cue(tick);
+rewrite(eqA, `R^2\cos^{-1}\!\frac{a}{R} - a\sqrt{R^2-a^2} \;=\; \frac{\pi R^2}{3}`, 0.9);
+say(cap, "Each outer piece must hold a third of the cake. Divide out the radius...", 0.5);
+cue(tick);
+rewrite(eqA, `\cos^{-1}u \;-\; u\sqrt{1-u^2} \;=\; \frac{\pi}{3}, \qquad u=\frac{a}{R}`, 0.9);
+say(cap, "No algebra unties this knot - it is transcendental. Let the graph solve it.", 0.5);
+say(fig, "Fig. 3 - solving f(u) = 0", 0.3);
+par { draw(gxa, 0.5); draw(gya, 0.5); }
+par { draw(pf, 1.3); show(eqG, 0.7); }
+show(rt, 0.4); show(rlab, 0.4);
+par { cam((959, 545), 1.0, smooth); zoom(1.6, 1.0, smooth); }
+flash(rt, magenta);
+say(cap, "One root. The cuts belong at u = 0.2649 - about a quarter of the radius.", 0.5);
+wait(0.7);
+par { cam((cx, cy), 1.0, smooth); zoom(1, 1.0, smooth); }
+cue(tick);
+rewrite(eqA, `u \;=\; \frac{a}{R} \;\approx\; 0.2649`, 0.9);
+
+// ---- the fair cut: slide the knives home
+say(cap, "Nudge each cut toward the centre: from 0.333 R in to 0.2649 R.", 0.5);
+cue(whoosh);
+par {
+  shift(cA1, (0, dyE - dyS), 1.4, smooth); scale(cA1, sf, 1.4, smooth);
+  shift(cB1, (0, dyS - dyE), 1.4, smooth); scale(cB1, sf, 1.4, smooth);
+  fade(att2, 1.2); show(capT3, 1.2); show(mid3, 1.2); show(capB3, 1.2);
+}
+par { to(pcT, value, 33.3, 1.3, smooth); to(pcM, value, 33.3, 1.3, smooth); to(pcB, value, 33.3, 1.3, smooth); }
+cue(chime);
+par { flash(capT3, cyan); flash(mid3, gold); flash(capB3, magenta); }
+say(cap, "33.3 - 33.3 - 33.3. Fair, to the crumb.", 0.5);
+say(fig, "Fig. 4 - the fair cut: a = 0.2649 R", 0.3);
+wait(0.8);
+
+// ---- closing plate
+cue(tick);
+rewrite(eqA, `\boxed{\;a \;=\; 0.2649\,R\;}`, 1.0);
+par {
+  breathe(eqA, 3, 0.05, 0, 5);
+  seq { pulse(capT3, 0.7); pulse(mid3, 0.7); pulse(capB3, 0.7); }
+}
+say(cap, "Two cuts. Three equal shares. One transcendental number.", 0.6);
+wait(2.5);

package/examples/circle-thirds-no-triangle.manic

@@ -0,0 +1,161 @@
+// circle-thirds-no-triangle — Plate VIII of the Problem Book: cut a circle
+// into three EQUAL areas, but the classic three-sector answer (and the
+// equilateral triangle hiding inside it) is banned. Two triangle-free answers:
+//   1. the bullseye: concentric circles at r1 = R/sqrt(3), r2 = R sqrt(2/3)
+//   2. the waves: S-curves of semicircular arcs on a thirds-divided diameter;
+//      piece_k = (pi/2)(r_k^2 - r_{k-1}^2) + (pi/2)(s_{k-1}^2 - s_k^2)
+//              = (pi R^2/18)[(2k-1) + (7-2k)] = pi R^2 / 3  for EVERY k.
+title("Three Equal Parts - No Triangles Allowed");
+canvas("16:9");
+template("paper");
+masthead("The Problem Book", "Plate VIII");
+
+// ---------- layout ----------
+let R = 205;
+let ox = 400;
+let oy = 400;
+let r1 = R*0.57735;   // R / sqrt 3
+let r2 = R*0.8165;    // R sqrt(2/3)
+
+// ---------- HUD ----------
+text(head, (cx, 100), "Three Equal Parts - No Triangles Allowed"); display(head); cursor(head); sticky(head);
+text(cap, (cx, h - 40), ""); size(cap, 26); sticky(cap);
+text(fig, (ox, 648), ""); size(fig, 24); color(fig, dim); sticky(fig);
+
+// ---------- the cake ----------
+circle(cake, (ox, oy), R); outlined(cake); stroke(cake, 3); untraced(cake);
+circle(disc, (ox, oy), R); hidden(disc);   // hidden filled source for booleans
+
+// ---------- act 1: the banned answer ----------
+line(m1, (ox, oy), (ox, oy - R)); untraced(m1); stroke(m1, 3); tag(m1, merc);
+line(m2, (ox, oy), (ox - R*0.866, oy + R*0.5)); untraced(m2); stroke(m2, 3); tag(m2, merc);
+line(m3, (ox, oy), (ox + R*0.866, oy + R*0.5)); untraced(m3); stroke(m3, 3); tag(m3, merc);
+line(e1, (ox, oy - R), (ox - R*0.866, oy + R*0.5)); dashed(e1); stroke(e1, 3); color(e1, red); untraced(e1); tag(e1, tri);
+line(e2, (ox - R*0.866, oy + R*0.5), (ox + R*0.866, oy + R*0.5)); dashed(e2); stroke(e2, 3); color(e2, red); untraced(e2); tag(e2, tri);
+line(e3, (ox + R*0.866, oy + R*0.5), (ox, oy - R)); dashed(e3); stroke(e3, 3); color(e3, red); untraced(e3); tag(e3, tri);
+
+// ---------- act 2: the bullseye ----------
+circle(c1, (ox, oy), r1); outlined(c1); stroke(c1, 3); untraced(c1); tag(c1, bull);
+circle(c2, (ox, oy), r2); outlined(c2); stroke(c2, 3); untraced(c2); tag(c2, bull);
+circle(c1d, (ox, oy), r1); hidden(c1d);
+circle(c2d, (ox, oy), r2); hidden(c2d);
+circle(fin, (ox, oy), r1); color(fin, cyan); opacity(fin, 0.45); hidden(fin); tag(fin, bull);
+difference(ringM, c2d, c1d); color(ringM, gold); opacity(ringM, 0.45); hidden(ringM); tag(ringM, bull);
+difference(ringO, disc, c2d); color(ringO, magenta); opacity(ringO, 0.45); hidden(ringO); tag(ringO, bull);
+counter(pb1, (ox, oy), 0, 1, "", "%"); hidden(pb1); tag(pb1, bull);
+counter(pb2, (ox, oy - 143), 0, 1, "", "%"); hidden(pb2); tag(pb2, bull);
+counter(pb3, (ox, oy + 186), 0, 1, "", "%"); hidden(pb3); tag(pb3, bull);
+equation(eqB, (960, 210), `\pi r_1^2 \;=\; \pi\big(r_2^2-r_1^2\big) \;=\; \pi\big(R^2-r_2^2\big) \;=\; \frac{\pi R^2}{3}`, 26); hidden(eqB); sticky(eqB);
+
+// ---------- act 3: the waves ----------
+// construction guides: the diameter, divided into thirds
+line(diam, (ox - R, oy), (ox + R, oy)); dashed(diam); stroke(diam, 2); color(diam, dim); untraced(diam); tag(diam, guide);
+dot(dv1, (ox - R/3, oy), 6); color(dv1, gold); hidden(dv1); tag(dv1, guide);
+dot(dv2, (ox + R/3, oy), 6); color(dv2, gold); hidden(dv2); tag(dv2, guide);
+// cut 1: semicircle r = R/3 above on the first third + r = 2R/3 below on the rest
+plot(pU1, (ox, oy), R, R, "sqrt(abs(0.111111-(x+0.666667)^2))", (-1, -0.3333));
+untraced(pU1); stroke(pU1, 4); color(pU1, red); tag(pU1, waves);
+plot(pL1, (ox, oy), R, R, "0-sqrt(abs(0.444444-(x-0.333333)^2))", (-0.3333, 1));
+untraced(pL1); stroke(pL1, 4); color(pL1, red); tag(pL1, waves);
+// cut 2: semicircle r = 2R/3 above on the first two thirds + r = R/3 below
+plot(pU2, (ox, oy), R, R, "sqrt(abs(0.444444-(x+0.333333)^2))", (-1, 0.3333));
+untraced(pU2); stroke(pU2, 4); color(pU2, red); tag(pU2, waves);
+plot(pL2, (ox, oy), R, R, "0-sqrt(abs(0.111111-(x-0.666667)^2))", (0.3333, 1));
+untraced(pL2); stroke(pL2, 4); color(pL2, red); tag(pL2, waves);
+// boolean sources: half-disc sectors + the four construction circles.
+// key fact: consecutive half-discs are INTERNALLY TANGENT, so every wave piece is
+// either a plain sector or ONE difference(sector, circle) - no nesting needed.
+sector(sLoB, (ox, oy), R, 180, 360); hidden(sLoB);
+sector(sHiB, (ox, oy), R, 0, 180); hidden(sHiB);
+sector(sU2s, (ox - R/3, oy), 2*R/3, 0, 180); hidden(sU2s);
+sector(sL1s, (ox + R/3, oy), 2*R/3, 180, 360); hidden(sL1s);
+circle(dU1c, (ox - 2*R/3, oy), R/3); hidden(dU1c);
+circle(dU2c, (ox - R/3, oy), 2*R/3); hidden(dU2c);
+circle(dL1c, (ox + R/3, oy), 2*R/3); hidden(dL1c);
+circle(dL2c, (ox + 2*R/3, oy), R/3); hidden(dL2c);
+// region 1 (cyan): lower-left crescent + its little bump above the diameter
+difference(w1a, sLoB, dL1c); color(w1a, cyan); opacity(w1a, 0.45); filled(w1a); tag(w1a, wave1); tag(w1a, waves);
+sector(sU1f, (ox - 2*R/3, oy), R/3, 0, 180); color(sU1f, cyan); opacity(sU1f, 0.45); filled(sU1f); tag(sU1f, wave1); tag(sU1f, waves);
+// region 2 (gold): the S in the middle - one piece above the axis, one below
+difference(w2a, sU2s, dU1c); color(w2a, gold); opacity(w2a, 0.45); filled(w2a); tag(w2a, wave2); tag(w2a, waves);
+difference(w2b, sL1s, dL2c); color(w2b, gold); opacity(w2b, 0.45); filled(w2b); tag(w2b, wave2); tag(w2b, waves);
+// region 3 (magenta): upper-right crescent + its little bump below
+difference(w3a, sHiB, dU2c); color(w3a, magenta); opacity(w3a, 0.45); filled(w3a); tag(w3a, wave3); tag(w3a, waves);
+sector(sL2f, (ox + 2*R/3, oy), R/3, 180, 360); color(sL2f, magenta); opacity(sL2f, 0.45); filled(sL2f); tag(sL2f, wave3); tag(sL2f, waves);
+hidden(wave1); hidden(wave2); hidden(wave3);
+counter(pc1, (300, 492), 0, 1, "", "%"); hidden(pc1);
+counter(pc2, (370, 360), 0, 1, "", "%"); hidden(pc2);
+counter(pc3, (508, 308), 0, 1, "", "%"); hidden(pc3);
+equation(eqW, (960, 210), `\text{piece}_k=\frac{\pi}{2}\big(r_k^2-r_{k-1}^2\big)+\frac{\pi}{2}\big(s_{k-1}^2-s_k^2\big)`, 26); hidden(eqW); sticky(eqW); z(eqW, 10);
+
+// ================= timeline =================
+
+// ---- the challenge
+type(head, 1.1);
+say(cap, "Cut a circle into three equal parts. Everyone knows the answer...", 0.6);
+draw(cake, 1.2);
+say(fig, "Fig. 1 - the answer everyone knows", 0.3);
+par { draw(m1, 0.5); draw(m2, 0.5); draw(m3, 0.5); }
+say(cap, "Three cuts from the centre, 120 degrees apart. Equal - by symmetry.", 0.5);
+wait(0.5);
+say(cap, "But look what hides inside it...", 0.5);
+par { draw(e1, 0.5); draw(e2, 0.5); draw(e3, 0.5); }
+flash(tri, red);
+cue(pop);
+say(cap, "An equilateral triangle. And today, triangles are BANNED.", 0.5);
+wait(0.5);
+par { disintegrate(e1, 0.7); disintegrate(e2, 0.7); disintegrate(e3, 0.7); disintegrate(m1, 0.7); disintegrate(m2, 0.7); disintegrate(m3, 0.7); }
+
+// ---- answer one: the bullseye
+cue(whoosh);
+say(fig, "Fig. 2 - the bullseye", 0.3);
+say(cap, "Answer one: forget cuts across - aim for the BULLSEYE.", 0.5);
+par { draw(c1, 0.8); draw(c2, 0.8); }
+stagger(0.15) { show(fin, 0.5); show(ringM, 0.5); show(ringO, 0.5); }
+par { show(pb1, 0.3); show(pb2, 0.3); show(pb3, 0.3); }
+par { to(pb1, value, 33.3, 1.2, smooth); to(pb2, value, 33.3, 1.2, smooth); to(pb3, value, 33.3, 1.2, smooth); }
+show(eqB, 0.6);
+cue(tick);
+rewrite(eqB, `r_1=\frac{R}{\sqrt{3}}\approx 0.577\,R \qquad r_2=R\sqrt{\tfrac{2}{3}}\approx 0.816\,R`, 0.9);
+say(cap, "A disc and two rings, each exactly a third. No corners anywhere.", 0.5);
+wait(1.2);
+par { fade(bull, 0.6); disintegrate(eqB, 0.8); }
+
+// ---- answer two: the waves
+cue(whoosh);
+say(fig, "Fig. 3 - the waves", 0.3);
+say(cap, "Answer two: let the cuts WAVE. Divide the diameter into thirds...", 0.5);
+draw(diam, 0.7);
+par { show(dv1, 0.4); show(dv2, 0.4); }
+say(cap, "...then each cut is two half-circles: one arching over, one diving under.", 0.5);
+par { cam((ox, oy), 1.0, smooth); zoom(1.25, 1.0, smooth); }
+seq { draw(pU1, 0.9); draw(pL1, 0.9); }
+cue(tick);
+seq { draw(pU2, 0.9); draw(pL2, 0.9); }
+stagger(0.15) { show(wave1, 0.6); show(wave2, 0.6); show(wave3, 0.6); }
+par { show(pc1, 0.3); show(pc2, 0.3); show(pc3, 0.3); }
+par { to(pc1, value, 33.3, 1.2, smooth); to(pc2, value, 33.3, 1.2, smooth); to(pc3, value, 33.3, 1.2, smooth); }
+par { cam((cx, cy), 1.0, smooth); zoom(1, 1.0, smooth); }
+
+// the telescoping proof
+show(eqW, 0.6);
+say(cap, "Why equal? Each piece is half-circles added and subtracted...", 0.5);
+cue(tick);
+rewrite(eqW, `\text{piece}_k=\frac{\pi R^2}{18}\Big[(2k-1)+(7-2k)\Big]`, 0.9);
+say(cap, "...and the k cancels itself. Every wave weighs the same.", 0.5);
+cue(tick);
+rewrite(eqW, `\boxed{\;\text{piece}_k=\frac{\pi R^2}{3}\quad\text{for every }k\;}`, 1.0);
+cue(chime);
+par { flash(wave1, cyan); flash(wave2, gold); flash(wave3, magenta); }
+wait(0.8);
+
+// ---- finale: still fair, whichever way it turns
+say(fig, "Fig. 4 - still fair, spinning", 0.3);
+par { fade(pc1, 0.4); fade(pc2, 0.4); fade(pc3, 0.4); fade(guide, 0.4); }
+say(cap, "And a third stays a third, whichever way you turn the plate.", 0.5);
+par {
+  turn(waves, (ox, oy), 120, 5.0, smooth);
+  breathe(eqW, 3, 0.05, 0, 5);
+}
+say(cap, "Three equal parts - and not a triangle in sight.", 0.6);
+wait(2.0);

package/examples/clip-window.manic

@@ -0,0 +1,34 @@
+// clip-window.manic — T1 rectangular clip: reveal-through-a-window / crop-to-panel.
+//
+// `clip(id, region)` scissors an entity (or a whole tagged group) to another
+// entity's rectangular bounds. The scissor is resolved every frame, so the window
+// FOLLOWS the region — move the window and the reveal tracks it. Here a spotlight
+// window sweeps across a big imported vector, revealing it piece by piece.
+//
+//   manic examples/clip-window.manic
+title("Clip — reveal through a window");
+canvas("16:9");
+template("blank");
+
+// a big imported vector that overflows what one window can show
+svg(art, (cx, cy), "asset:svg/flags/br.svg", 940);
+
+// the spotlight window — hollow frame so the clipped vector shows through
+// (declared BEFORE the clip that references it)
+rect(win, (cx - 380, cy), 320, 300); outlined(win); outline(win, fg); stroke(win, 5); glow(win, 0.7);
+
+// clip the whole vector to the window — nothing shows outside it
+clip(art, win);
+
+text(cap, (cx, h*0.9), "clip(id, window) — the scissor follows the window");
+size(cap, 26); color(cap, dim); display(cap);
+
+// sweep the window across → the flag is revealed only where the window is
+seq {
+  wait(0.4);
+  move(win, (cx + 380, cy), 2.4, smooth);
+  wait(0.3);
+  move(win, (cx, cy), 1.0, smooth);
+  pulse(win);
+  wait(0.6);
+}

package/examples/cloud-feathers.manic

@@ -0,0 +1,50 @@
+// cloud-feathers — another @yuruyurau art-tweet in ONE `cloud`: 20,000 points in
+// FOUR layers (`mod(i,4)`) fan into feathery plumes that flutter over time. A
+// polar plot (radius `q`, angle `c`) whose amplitude switches on a conditional —
+// the original's `(y<5 ? … : 11)` becomes a `sign()` blend, since cloud formulas
+// have no ternary. `mag(k,e)` here (not squared); coloured per point and bloomed
+// on a 9:16 Short. The parameter is renamed `s` (the required output is `y`).
+//
+// Original idea by @yuruyurau (https://x.com/yuruyurau). Our hue'd, annotated
+// take — pure in (i, t), so it scrubs and records; the p5 original can't.
+//
+//   manic examples/cloud-feathers.manic
+title("Four feathers from one formula");
+canvas("9:16");
+template("black");
+
+cloud(feathers, 20000, #ffffff, 0.6) {
+  let s = i/500;                          // reference's "y"
+  let m = mod(i, 4) * 8;                  // four layers
+  let sw = 0.5*(1 + sign(5 - s));         // (y<5 ? … : …) via sign
+  let kamp = sw*(sin(t/8 + s)*35) + (1 - sw)*11;
+  let k = cos(s*9) * kamp;
+  let e = s/8 - 13;
+  let o = hypot(k, e)/6;
+  let q = k*s/19 + 49 + k*sin(s)*sin(o*2 - e/5 - t);
+  let c = o/3 - e/5 - t/8 + m;
+  let px = q*sin(c) - 79*cos(c/3);
+  let py = (q + 70)*cos(c);
+  let grow = tanh(t*0.5 + 0.12);
+  let x = 540 + px * 1.9 * grow;
+  let y = 960 + py * 1.9 * grow;
+  let hue = mod(m*45 + i*0.04 + t*14, 360);
+}
+
+// ---- textbook annotations ----
+caption(head, "Four feathers from one formula", (540, 138), 34);
+caption(sub, "20,000 points, no simulation", (540, 206), 22);
+hidden(head);
+hidden(sub);
+equation(eq, (540, 1706), `p = (q\sin c,\;\; (q{+}70)\cos c)`, 30);
+caption(lab, "a polar plot in four layers (mod i,4)", (540, 1786), 20);
+hidden(eq);
+hidden(lab);
+
+show(head);
+wait(1.4);
+show(sub);
+wait(2.6);
+show(eq);
+show(lab);
+wait(25);

package/examples/cloud-jellyfish-v2.manic

@@ -0,0 +1,87 @@
+// cloud-jellyfish-v2 — the @yuruyurau jellyfish `cloud` (20,000 points, two layers,
+// pulsing bells + tendrils), now SWIMMING IN A SHADER AQUARIUM. The bells are the same
+// particle system as v1; everything around them is one per-pixel `shader`: a depth
+// gradient (teal surface → deep navy), animated caustics rippling near the top, and soft
+// god-rays falling from the surface. A third element — rising bubbles — is a second tiny
+// `cloud`. Particle art + a per-pixel ocean + generic captions, all in one 9:16 frame,
+// all pure in (i, t) so the whole aquarium scrubs and records exactly.
+//
+//   manic examples/cloud-jellyfish-v2.manic
+title("Jellyfish in a shader aquarium");
+canvas("9:16");
+template("black");
+
+// ===================== the aquarium — one shader, per pixel =====================
+shader(water) {
+  let x = (u - 0.5) * asp;
+  let y = v;                                   // 0 = surface (top), 1 = deep (bottom)
+  let depth = smoothstep(0.0, 1.0, y);
+
+  // deep-water colour ramp: bright teal near the surface, deep blue below
+  let hue = mix(186, 216, depth);
+  let base = mix(0.26, 0.045, depth);
+
+  // caustics — warped interference, bright veins that fade with depth
+  let wx = x * 4.0 + 0.5 * sin(y * 6.0 + t * 0.4);
+  let wy = y * 7.0 + 0.5 * sin(x * 5.0 - t * 0.5);
+  let cc = sin(wx + t * 0.7) + sin(wy - t * 0.6) + sin((wx + wy) * 0.7 + t * 0.5);
+  let b = 0.5 + 0.5 * sin(cc * 1.5);
+  let caust = b * b * b * (1.0 - depth * 0.75);
+
+  // god-rays — soft vertical light shafts from the surface, strongest up top
+  let ray = 0.5 + 0.5 * sin(x * 3.0 + 0.6 * sin(t * 0.2));
+  let r2 = ray * ray;
+  let rays = r2 * r2 * (1.0 - smoothstep(0.0, 0.65, y)) * 0.45;
+
+  let val = clamp(base + caust * 0.5 + rays, 0.0, 0.95);
+  let sat = mix(0.85, 0.62, caust);            // bright veins read a touch whiter
+}
+
+// ===================== the jellyfish — the v1 cloud, re-lit ====================
+// same polar formula as v1; the hue is pulled into a cyan↔magenta bioluminescent band
+// so the bells glow like sea creatures against the water instead of full-spectrum.
+cloud(jelly, 20000, #ffffff, 0.6) {
+  let s = i/99;                 // reference's "y" parameter
+  let m = mod(i, 2) * 3;        // two layers
+  let k = 9*cos(s*2);
+  let e = s/8 - 12;
+  let d = (k*k + e*e)/79 + 1;
+  let q = 79 - e*sin(k) + k/d*(8 + 4*sin(sin(d*d + e/9 - t)));
+  let c = d/2 - cos(d*2)/5 - t/16 + m;
+  let px = q*sin(c);
+  let py = (q + 40)*cos(c);
+  let grow = tanh(t*0.5 + 0.12);
+  let x = 540 + px * 2.2 * grow;
+  let y = 960 + py * 2.2 * grow;
+  let hue = mod(198 + m*30 + 46*sin(s*0.18 + t*0.35), 360);   // cyan ↔ magenta glow
+}
+
+// ---- rising bubbles — a second tiny cloud drifting up the tank ----
+cloud(bubbles, 130, #dff4ff, 0.5) {
+  let sp = 0.05 + 0.06 * rand2(i, 1.3);        // per-bubble rise speed
+  let ph = rand2(i, 2.7);
+  let prog = fract(ph + t * sp);               // 0 → 1 rise progress
+  let x = 1080 * rand2(i, 4.1) + 24 * sin(prog * tau * 2.0 + i);
+  let y = 1920 * (1.0 - prog);                 // bottom → top
+  let r = 2.0 + 5.0 * rand2(i, 5.5);
+  let hue = 196;
+  let alpha = 0.5 * sin(prog * pi);            // fade in low, fade out near the surface
+}
+
+// ---- textbook annotations ----
+caption(head, "Jellyfish in a shader aquarium", (540, 138), 33);
+caption(sub, "a 20,000-point cloud + a per-pixel ocean", (540, 206), 22);
+hidden(head);
+hidden(sub);
+equation(eq, (540, 1706), `p = (q\sin c,\;\; (q{+}40)\cos c)`, 30);
+caption(lab, "bells: a polar cloud · water: one shader · bubbles: a second cloud", (540, 1786), 19);
+hidden(eq);
+hidden(lab);
+
+show(head);
+wait(1.4);
+show(sub);
+wait(2.6);
+show(eq);
+show(lab);
+wait(25);

package/examples/cloud-jellyfish.manic

@@ -0,0 +1,48 @@
+// cloud-jellyfish — another @yuruyurau art-tweet in ONE `cloud`: 20,000 points in
+// two layers (`mod(i,2)`) drift into jellyfish-like bells with trailing tendrils
+// and pulse over time. A polar plot (radius `q`, angle `c`) with a nested
+// `sin(sin(...))` that gives the bell its soft ripple; coloured per point and
+// bloomed from the centre on a 9:16 Short. `mag(k,e)^2` → `k*k+e*e`; the
+// parameter is renamed `s` (the required output is `y`).
+//
+// Original idea by @yuruyurau (https://x.com/yuruyurau). Our hue'd, annotated
+// take — pure in (i, t), so it scrubs and records; the p5 original can't.
+//
+//   manic examples/cloud-jellyfish.manic
+title("Two jellyfish from one formula");
+canvas("9:16");
+template("black");
+
+cloud(jelly, 20000, #ffffff, 0.6) {
+  let s = i/99;                 // reference's "y" parameter
+  let m = mod(i, 2) * 3;        // two layers
+  let k = 9*cos(s*2);
+  let e = s/8 - 12;
+  let d = (k*k + e*e)/79 + 1;
+  let q = 79 - e*sin(k) + k/d*(8 + 4*sin(sin(d*d + e/9 - t)));
+  let c = d/2 - cos(d*2)/5 - t/16 + m;
+  let px = q*sin(c);
+  let py = (q + 40)*cos(c);
+  let grow = tanh(t*0.5 + 0.12);
+  let x = 540 + px * 2.2 * grow;
+  let y = 960 + py * 2.2 * grow;
+  let hue = mod(m*70 + i*0.05 + t*15, 360);
+}
+
+// ---- textbook annotations ----
+caption(head, "Two jellyfish from one formula", (540, 138), 34);
+caption(sub, "20,000 points, no simulation", (540, 206), 22);
+hidden(head);
+hidden(sub);
+equation(eq, (540, 1706), `p = (q\sin c,\;\; (q{+}40)\cos c)`, 30);
+caption(lab, "a polar plot: radius q, angle c, per point", (540, 1786), 20);
+hidden(eq);
+hidden(lab);
+
+show(head);
+wait(1.4);
+show(sub);
+wait(2.6);
+show(eq);
+show(lab);
+wait(25);

package/examples/cloud-kaleidoscope.manic

@@ -0,0 +1,48 @@
+// cloud-kaleidoscope — a 14-fold kaleidoscope in ONE `cloud`. The @yuruyurau
+// original uses canvas FEEDBACK (get() + rotate + image()) — a raster/Droste
+// trick manic doesn't have (it's vector & deterministic). But the OUTCOME is a
+// 14-fold rotational symmetry, which `cloud` gets by layer-replication: one base
+// field, copied at 14 angles via a layer index `L = floor(i/bn)` and rotated by
+// `L·π/7`. So the picture is the same, but it scrubs and records (the p5 can't).
+//
+// Original idea by @yuruyurau (https://x.com/yuruyurau). Our hue'd, annotated take.
+//
+//   manic examples/cloud-kaleidoscope.manic
+title("A kaleidoscope from one formula");
+canvas("9:16");
+template("black");
+
+cloud(kaleido, 56000, #ffffff, 0.6) {
+  let bn = 4000;                        // points per copy (14 copies = 56k, smooth)
+  let L = floor(i / bn);                // copy 0..13
+  let j = mod(i, bn);                   // base index
+  let k = mod(j, 50) - 25;
+  let e = j/222;
+  let d = 5*cos(hypot(k, e) - t + mod(j, 2));
+  let bx = k + k*d/6*sin(d + e/3 + t);
+  let by = 90 + e*d - e/d*2*cos(d + t);
+  let ang = L * pi/7;                    // 14-fold rotation of the base field
+  let grow = tanh(t*0.5 + 0.12);
+  let x = 540 + (bx*cos(ang) - by*sin(ang)) * 2.2 * grow;
+  let y = 960 + (bx*sin(ang) + by*cos(ang)) * 2.2 * grow;
+  let r = 0.8;
+  let hue = mod(L*26 + by*2 + t*12, 360);   // a colour per sector + radial
+}
+
+// ---- textbook annotations ----
+caption(head, "A kaleidoscope from one formula", (540, 138), 34);
+caption(sub, "one field, copied at 14 angles", (540, 206), 22);
+hidden(head);
+hidden(sub);
+equation(eq, (540, 1706), `\vec p_L = R\!\left(L\tfrac{2\pi}{14}\right)\,\vec p_0`, 34);
+caption(lab, "14-fold symmetry, no mirrors — pure rotation", (540, 1786), 20);
+hidden(eq);
+hidden(lab);
+
+show(head);
+wait(1.4);
+show(sub);
+wait(2.6);
+show(eq);
+show(lab);
+wait(25);

package/examples/cloud-koi.manic

@@ -0,0 +1,51 @@
+// cloud-koi — another @yuruyurau art-tweet in ONE `cloud`: 10,000 points in two
+// layers (`mod(i,2)`) swirl into koi-like forms chasing each other, rippling over
+// time. A polar plot (radius `q`, angle `c`); `cos(i+t/4)` on the raw index gives
+// the fine scale texture. One JS-ism: the original's `y^9` is bitwise XOR (a
+// per-band scramble), which manic has no operator for — approximated here with
+// `noise()`, visually equivalent. `mag` = `hypot`; parameter renamed `s`.
+//
+// Original idea by @yuruyurau (https://x.com/yuruyurau). Our hue'd, annotated
+// take — pure in (i, t), so it scrubs and records; the p5 original can't.
+//
+//   manic examples/cloud-koi.manic
+title("Two koi from one formula");
+canvas("9:16");
+template("black");
+
+cloud(koi, 10000, #ffffff, 0.6) {
+  let s = i/790;
+  let m = mod(i, 2);
+  let sw = 0.5*(1 + sign(8 - s));                 // (y<8 ? … : …)
+  let scr = noise(s*2, 0);                         // ~ the JS y^9 XOR scramble
+  let kbase = sw*(9 + scr*6) + (1 - sw)*(4 + cos(s));
+  let k = kbase * cos(i + t/4);
+  let e = s/3 - 13;
+  let d = hypot(k, e) + cos(e + t*2 + m*4);
+  let q = s*k/5*(2 + sin(d*2 + s - t*4)) + 80;
+  let c = d/4 - t/2 + m*3;
+  let px = q*cos(c);
+  let py = q*sin(c) + d*9 - 130;                   // recentre the d*9+60 offset
+  let grow = tanh(t*0.5 + 0.12);
+  let x = 540 + px * 2.1 * grow;
+  let y = 960 + py * 2.1 * grow;
+  let hue = mod(m*90 + i*0.03 + t*14, 360);
+}
+
+// ---- textbook annotations ----
+caption(head, "Two koi from one formula", (540, 138), 36);
+caption(sub, "10,000 points, no simulation", (540, 206), 22);
+hidden(head);
+hidden(sub);
+equation(eq, (540, 1706), `p = (q\cos c,\;\; q\sin c)`, 32);
+caption(lab, "a polar plot: radius q, angle c, per point", (540, 1786), 20);
+hidden(eq);
+hidden(lab);
+
+show(head);
+wait(1.4);
+show(sub);
+wait(2.6);
+show(eq);
+show(lab);
+wait(25);

package/examples/cloud-lissajous.manic

@@ -0,0 +1,23 @@
+// cloud-lissajous — the SAME `cloud` primitive as popkorn, a completely
+// different picture: a Lissajous curve traced by 600 points, its horizontal
+// phase drifting with time so the figure slowly folds through itself. Pure math,
+// no donut in sight — proof that `cloud` is a generic point field. On a 9:16
+// Short, held 20s so you can watch it evolve.
+//
+//   manic examples/cloud-lissajous.manic
+title("cloud — a breathing Lissajous figure");
+canvas("9:16");
+template("black");
+
+cloud(liss, 600, #46e2c8, 0.95) {
+  let u = i / 600 * tau;           // parameter around the curve
+  let x = 540 + 460 * sin(3 * u + t);
+  let y = 960 + 760 * sin(2 * u);
+  let r = 3;
+  // colour reveal: starts near cyan (hue 180), fans into a rotating rainbow
+  // around the curve as `spread` grows 0 -> 1 over the first several seconds
+  let spread = tanh(t * 0.3);
+  let hue = mod(180 + u * 57 * spread + t * 35, 360);
+}
+
+wait(25);