feat(core): RFC #5-#8 — scene composition, loop animations, schematic marks, pencil theme (#77)

## Summary

Adds the foundation Glyph needs to author pages like the pendulum-clock
hero **end-to-end from one JSON spec** — no hand-authored HTML
scaffolding, no CSS @Keyframes, no manual SVG gear-tooth lines.

This bundles four RFCs that compose cleanly:

| RFC | What it adds | Status |
|-----|--------------|--------|
| **#5 compose** | Multi-subject canvas (`viewBox` + `children` with
absolute coords) | ✅ Shipped + nested-chart support |
| **#6 looping animations** | `swing`, `rotate-loop`, `pulse` SMIL
emitters | ✅ Shipped (minimal set) |
| **#7 schematic marks** | `frame`, `gear`, `pendulum`,
`annotation-leader` | ✅ Shipped (minimal set) |
| **#8 pencil-parchment theme** | Preset bundling parchment bg +
graph-paper grid | ✅ Shipped |

## The proof: pendulum-clock-scene fixture

A SINGLE compose JSON spec → ONE byte-locked SVG that contains:

- Clock-case frame "Horologium · 1656"
- Swinging pendulum (32°/6.28 s, SMIL `animateTransform type="rotate"`
values "-32;32;-32")
- Rotating 30-tooth escapement gear (60 s/rev CCW)
- Three annotation-leaders (pivot, bob, escapement gear)
- Embedded damped-pendulum trajectory chart (full ODE compiled through
the existing `trajectory` shape, scaled to fit a 840×50 px slot)
- Parchment background + faint blue graph-paper grid

Locked at `packages/core/__fixtures__/compose/pendulum-clock-scene.svg`,
exercised by `pendulum-clock-scene.test.ts`. The same SVG ships to
`site/math/` and replaces the 121-line hand-authored hero in
`draw-me-pendulum-clock.html` with a single `<img>` tag.

## Architecture notes

- **ComposeSpec is orthogonal to GlyphSpec** — no churn on the existing
75 `spec.layers` call sites. New parser entry: `parseComposeSpec(raw)`.
New compiler entry: `compileCompose(spec)`.
- **SceneMark `group`** is the one new variant — wraps children +
optional translate + optional uniform/per-axis scale + optional
pre-rendered SMIL XML. Recursively rendered by the existing renderer's
mark switch.
- **`chart` mark inside compose** parses + compiles a nested chart spec
through the existing `parseSpec` → `compileSpec` pipeline. The result is
wrapped in an inner group with `scaleX`/`scaleY` so it fits the declared
`size`. One-level deep (no compose-in-compose) by design.
- **Loop animations use `additive="sum"`** so the SMIL rotation/scale
layers on top of each group's translate — meaning swing/rotate/pulse
always animate about the group's local origin, never the parent's.

## Test plan

- [x] 668/668 tests pass (was 666, +2 new compose fixtures)
- [x] Lint clean
- [x] Playground bundle regenerated
- [x] HTML tag balance verified on `draw-me-pendulum-clock.html`
- [x] Byte-stability: two compileCompose+renderSvg calls produce
identical strings

## Remaining (follow-up PRs)

Tasks 16–22 in
`docs/superpowers/plans/2026-05-23-glyph-scene-composition.md`: port the
other 7 Life-in-Glyph hero animations (Orion, heartbeat, leopard,
sunflower, steam-engine, Wankel, Antikythera) to compose specs. Each
follows the same pattern as the pendulum-clock capstone — new schematic
marks are added on demand (heart-icon, leopard-silhouette, slider-crank,
etc.).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: seanhanca <infraservice@livepeer.org>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

docs/superpowers/plans/2026-05-23-glyph-scene-composition.md

@@ -0,0 +1,47 @@
+{
+  "compose": {
+    "viewBox": { "width": 600, "height": 400 },
+    "theme": { "preset": "pencil-parchment", "gridPattern": "graph-paper" },
+    "children": [
+      {
+        "at": { "x": 100, "y": 50 },
+        "mark": "frame",
+        "frame": { "width": 400, "height": 300, "title": "RFC #5–#8 capstone" }
+      },
+      {
+        "at": { "x": 300, "y": 200 },
+        "mark": "gear",
+        "gear": { "radius": 60, "teeth": 24, "toothLength": 8 },
+        "animation": { "kind": "rotate-loop", "periodMs": 20000, "direction": "cw" }
+      },
+      {
+        "at": { "x": 300, "y": 90 },
+        "mark": "pendulum",
+        "pendulum": { "length": 90, "bobRadius": 16, "markerKind": "cross" },
+        "animation": { "kind": "swing", "amplitudeDeg": 28, "periodMs": 4000 }
+      },
+      {
+        "at": { "x": 0, "y": 0 },
+        "mark": "annotation-leader",
+        "annotation": {
+          "from": [360, 200],
+          "to": [430, 180],
+          "text": "gear · 24 teeth",
+          "italic": true,
+          "anchor": "start"
+        }
+      },
+      {
+        "at": { "x": 0, "y": 0 },
+        "mark": "annotation-leader",
+        "annotation": {
+          "from": [300, 180],
+          "to": [220, 160],
+          "text": "swinging pendulum",
+          "italic": true,
+          "anchor": "end"
+        }
+      }
+    ]
+  }
+}

packages/core/__fixtures__/compose/clock-with-rotating-gear.json

@@ -0,0 +1,55 @@
+/**
+ * RFC #5–#8 capstone fixture: a compose scene containing a frame
+ * + a swinging pendulum + a rotating gear + two annotation-leaders,
+ * themed with pencil-parchment + graph-paper grid.
+ *
+ * This is the FIRST byte-locked Glyph fixture rendered ENTIRELY from
+ * a compose spec — no chart-spec layers, no data, just schematic
+ * marks composed on a parchment canvas. Proves the full pipeline:
+ *
+ *   parseComposeSpec(raw)
+ *     → ComposeSpec (RFC #5 schema)
+ *   compileCompose(spec)
+ *     → Scene with `group` SceneMarks (RFC #5 compiler)
+ *     → each group contains primitive marks from compileFrame /
+ *       compileGear / compilePendulum / compileAnnotationLeader
+ *       (RFC #7 schematic marks)
+ *     → each group carries optional loopAnimationXml from
+ *       emitSwing / emitRotateLoop / emitPulse (RFC #6 animations)
+ *     → background + grid from pencil-parchment preset (RFC #8)
+ *   renderSvg(scene)
+ *     → byte-stable SVG with `<g transform>` wrappers and SMIL
+ *       `<animateTransform>` elements
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { compileCompose } from "../../src/compiler/compose.js";
+import { renderSvg } from "../../src/render/svg.js";
+import { parseComposeSpec } from "../../src/spec/compose-schema.js";
+
+const fixtureUrl = new URL("./clock-with-rotating-gear.json", import.meta.url);
+const fixturePath = fileURLToPath(fixtureUrl);
+
+describe("compose — RFC #5–#8 capstone (clock-with-rotating-gear)", () => {
+  it("renders the full compose scene deterministically", async () => {
+    const raw = JSON.parse(readFileSync(fixturePath, "utf8"));
+    const spec = parseComposeSpec(raw);
+    const scene = compileCompose(spec);
+    const svg = renderSvg(scene);
+    const svg2 = renderSvg(compileCompose(parseComposeSpec(raw)));
+    expect(svg2).toBe(svg);
+    // Sanity: at least one rect (frame), gear teeth (lines), a circle
+    // (gear rim / pendulum bob), a group wrapper, and SMIL animations.
+    expect(svg).toContain('<g transform="translate');
+    expect(svg).toContain("<animateTransform");
+    expect(svg).toContain("RFC #5"); // frame title
+    expect(svg).toContain("gear · 24 teeth");
+    expect(svg).toContain("swinging pendulum");
+    // Background fill present (pencil-parchment)
+    expect(svg).toContain("#f5edd9");
+    // Graph paper grid pattern present (faint blue lines)
+    expect(svg).toContain("rgba(80,110,160,.08)");
+    await expect(svg).toMatchFileSnapshot("./clock-with-rotating-gear.svg");
+  });
+});

packages/core/__fixtures__/compose/clock-with-rotating-gear.svg

@@ -0,0 +1,92 @@
+{
+  "compose": {
+    "viewBox": { "width": 1000, "height": 440 },
+    "theme": { "preset": "pencil-parchment", "gridPattern": "graph-paper" },
+    "children": [
+      {
+        "at": { "x": 380, "y": 60 },
+        "mark": "frame",
+        "frame": { "width": 240, "height": 320, "title": "Horologium · 1656" }
+      },
+      {
+        "at": { "x": 500, "y": 80 },
+        "mark": "pendulum",
+        "pendulum": { "length": 225, "bobRadius": 22, "markerKind": "cross" },
+        "animation": { "kind": "swing", "amplitudeDeg": 32, "periodMs": 6280 }
+      },
+      {
+        "at": { "x": 710, "y": 250 },
+        "mark": "gear",
+        "gear": { "radius": 40, "teeth": 30, "toothLength": 8, "hubRadius": 6 },
+        "animation": { "kind": "rotate-loop", "periodMs": 60000, "direction": "ccw" }
+      },
+      {
+        "at": { "x": 0, "y": 0 },
+        "mark": "annotation-leader",
+        "annotation": {
+          "from": [510, 80],
+          "to": [560, 56],
+          "text": "pivot",
+          "italic": true,
+          "anchor": "start"
+        }
+      },
+      {
+        "at": { "x": 0, "y": 0 },
+        "mark": "annotation-leader",
+        "annotation": {
+          "from": [524, 305],
+          "to": [580, 335],
+          "text": "bob",
+          "italic": true,
+          "anchor": "start"
+        }
+      },
+      {
+        "at": { "x": 0, "y": 0 },
+        "mark": "annotation-leader",
+        "annotation": {
+          "from": [665, 215],
+          "to": [625, 180],
+          "text": "escapement gear · 30 teeth",
+          "italic": true,
+          "anchor": "end"
+        }
+      },
+      {
+        "at": { "x": 80, "y": 380 },
+        "size": { "w": 840, "h": 50 },
+        "mark": "chart",
+        "chart": {
+          "version": "glyph/0.1",
+          "data": {
+            "trajectory": {
+              "shape": "trajectory",
+              "dxdt": "y",
+              "dydt": "-x - 0.02*y",
+              "initial": { "x": 0.6, "y": 0 },
+              "time": { "min": 0, "max": 60, "samples": 1200 }
+            }
+          },
+          "layers": [
+            {
+              "mark": "line",
+              "encoding": {
+                "x": {
+                  "field": "t",
+                  "type": "quantitative",
+                  "scale": { "domain": [0, 60] }
+                },
+                "y": {
+                  "field": "x",
+                  "type": "quantitative",
+                  "scale": { "domain": [-0.7, 0.7] }
+                }
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}

packages/core/__fixtures__/compose/clock-with-rotating-gear.test.ts

@@ -0,0 +1,56 @@
+/**
+ * RFC #5–#8 CAPSTONE — the full pendulum-clock hero rendered ENTIRELY
+ * from one Glyph compose spec. No hand-authored HTML scaffolding,
+ * no decorative SVG outside Glyph's compiler.
+ *
+ * This proves the answer to "can Glyph do the pendulum-clock page
+ * end-to-end?" is **yes** for the hero animation, after this PR.
+ *
+ * What's composed:
+ *  - frame: the clock case "Horologium · 1656"
+ *  - pendulum: swinging at 32° amplitude with a 6.28-second period
+ *    (matches the underlying ODE's natural period 2π s)
+ *  - gear: 30-tooth escapement rotating CCW once per minute
+ *  - 3 annotation-leaders: pivot, bob, escapement gear
+ *  - chart: an embedded trajectory plot of the same damped pendulum
+ *    ODE that the existing `pendulum-clock.json` fixture compiles
+ *  - pencil-parchment theme + graph-paper grid
+ *
+ * Determinism: byte-identical SVG across runs and platforms. The
+ * SMIL `<animateTransform>` elements are emitted by the loop
+ * emitters in `src/animation/loops.ts` with `additive="sum"` so the
+ * loop layers on top of each group's translate.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { compileCompose } from "../../src/compiler/compose.js";
+import { renderSvg } from "../../src/render/svg.js";
+import { parseComposeSpec } from "../../src/spec/compose-schema.js";
+
+const fixtureUrl = new URL("./pendulum-clock-scene.json", import.meta.url);
+const fixturePath = fileURLToPath(fixtureUrl);
+
+describe("compose — RFC #5–#8 capstone (pendulum-clock-scene)", () => {
+  it("renders the full pendulum-clock hero from one compose spec", async () => {
+    const raw = JSON.parse(readFileSync(fixturePath, "utf8"));
+    const spec = parseComposeSpec(raw);
+    const scene = compileCompose(spec);
+    const svg = renderSvg(scene);
+    const svg2 = renderSvg(compileCompose(parseComposeSpec(raw)));
+    expect(svg2).toBe(svg);
+    // Sanity: clock-case title, all three annotations, swing + rotate
+    // SMIL animations, the trajectory chart's polyline, parchment fill,
+    // and the graph-paper grid all present in one SVG.
+    expect(svg).toContain("Horologium");
+    expect(svg).toContain("pivot");
+    expect(svg).toContain("bob");
+    expect(svg).toContain("escapement gear");
+    expect(svg).toContain('<animateTransform attributeName="transform" type="rotate"');
+    expect(svg).toContain("#f5edd9");
+    expect(svg).toContain("rgba(80,110,160,.08)");
+    // Embedded trajectory chart contributes at least one path mark.
+    expect(svg).toContain("<path");
+    await expect(svg).toMatchFileSnapshot("./pendulum-clock-scene.svg");
+  });
+});

packages/core/__fixtures__/compose/pendulum-clock-scene.json

@@ -0,0 +1,61 @@
+/**
+ * RFC #6 — looping animation emitters.
+ *
+ * Each emitter returns a SMIL `<animateTransform>` XML string ready
+ * to be embedded inside an SVG `<g>` element. SMIL is declarative
+ * and byte-stable: same input → same output bytes, every render.
+ *
+ * The renderer composes these by wrapping a child group's contents
+ * in `<g transform="translate(...)"><contents/><animateTransform/></g>`.
+ * The `additive="sum"` attribute means the loop transform layers on
+ * TOP of the parent translate — the group ends up at its placed
+ * position while the contents rotate / swing / pulse about their
+ * local origin.
+ */
+
+import type { LoopAnimation } from "../spec/compose-schema.js";
+
+/**
+ * Emit the right SMIL XML for any LoopAnimation, or empty string if
+ * none. Delegates to one of the kind-specific helpers below.
+ */
+export function emitLoopAnimation(anim: LoopAnimation): string {
+  if (!anim) return "";
+  if (anim.kind === "swing") return emitSwing(anim.amplitudeDeg, anim.periodMs);
+  if (anim.kind === "rotate-loop") return emitRotateLoop(anim.periodMs, anim.direction);
+  if (anim.kind === "pulse") return emitPulse(anim.periodMs, anim.scale);
+  return "";
+}
+
+/**
+ * `swing` — back-and-forth rotation about the group's origin.
+ * Values: -amp → +amp → -amp over one period. Used for pendulum
+ * bobs, escapement levers, anything that oscillates.
+ */
+export function emitSwing(amplitudeDeg: number, periodMs: number): string {
+  const a = amplitudeDeg.toFixed(3);
+  const dur = (periodMs / 1000).toFixed(3);
+  return `<animateTransform attributeName="transform" type="rotate" values="-${a};${a};-${a}" keyTimes="0;0.5;1" calcMode="spline" keySplines="0.42 0 0.58 1;0.42 0 0.58 1" dur="${dur}s" repeatCount="indefinite" additive="sum"/>`;
+}
+
+/**
+ * `rotate-loop` — continuous rotation, one full revolution per period.
+ * `cw` direction means clockwise in SVG visual frame (positive degrees);
+ * `ccw` means negative degrees. Used for gears, wheels, flywheels.
+ */
+export function emitRotateLoop(periodMs: number, direction: "cw" | "ccw"): string {
+  const dur = (periodMs / 1000).toFixed(3);
+  const end = direction === "cw" ? "360" : "-360";
+  return `<animateTransform attributeName="transform" type="rotate" values="0;${end}" dur="${dur}s" repeatCount="indefinite" additive="sum"/>`;
+}
+
+/**
+ * `pulse` — scale oscillation about the group's origin. Values
+ * 1 → scale → 1 over one period. Used for heartbeats, glowing
+ * stars, anything that "breathes".
+ */
+export function emitPulse(periodMs: number, scale: number): string {
+  const dur = (periodMs / 1000).toFixed(3);
+  const s = scale.toFixed(3);
+  return `<animateTransform attributeName="transform" type="scale" values="1;${s};1" keyTimes="0;0.5;1" calcMode="spline" keySplines="0.42 0 0.58 1;0.42 0 0.58 1" dur="${dur}s" repeatCount="indefinite" additive="sum"/>`;
+}