From 8d7d8f5501b4e24015c3c7734af65f13dbc81d55 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Mon, 24 Aug 2026 20:16:45 -0400
Subject: [PATCH] =?UTF-8?q?feat(media-use):=20paint=20=E2=80=94=20compile?=
 =?UTF-8?q?=20images=20into=20brushstroke-code=20compositions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a media-use capability that compiles an image (or one frame of a
video) into a standalone HyperFrames composition whose generated code
repaints the subject in brushstrokes. The artifact is the code: the
stroke list ships as an editable data module (strokes.js), and the
inlined runtime reveals it over the timeline.

- scripts/paint.mjs: CLI entry. Decodes via ffmpeg rawvideo (images and
  video frames), compiles, emits, prints a JSON summary. Deterministic:
  same input + seed produces byte-identical stroke data.
- scripts/lib/paint-compiler.mjs: pure compiler. Sobel flow field,
  circular smoothing, seeded k-means palette with saturation restore,
  layered jittered-grid placement coarse to fine, variance-gated detail
  layers. low/medium/high presets calibrated on The Great Wave off
  Kanagawa, Girl with a Pearl Earring, and The Scream.
- scripts/lib/paint-emit.mjs: emits the composition. The painter runtime
  is inlined so static analysis sees the timeline registration; the
  reveal is seek-safe by construction (band canvases are pure functions
  of their band index; per-frame cost is O(strokes/bands)).
- references/paint.md: capability doc (when to reach for it, invocation,
  output layout, mounting, editing the art).
- SKILL.md: routing row.

The emitted composition passes hyperframes check with zero findings.
Tests: 6 node:test cases covering compile determinism, geometry bounds,
the emit contract, emit determinism, and an end-to-end run against a
real fixture image including a same-seed byte-equality check.
---
 skills-manifest.json                          |   4 +-
 skills/media-use/SKILL.md                     |   1 +
 skills/media-use/references/paint.md          |  69 +++
 .../media-use/scripts/lib/paint-compiler.mjs  | 553 ++++++++++++++++++
 skills/media-use/scripts/lib/paint-emit.mjs   | 182 ++++++
 skills/media-use/scripts/paint.mjs            | 182 ++++++
 skills/media-use/scripts/paint.test.mjs       | 166 ++++++
 7 files changed, 1155 insertions(+), 2 deletions(-)
 create mode 100644 skills/media-use/references/paint.md
 create mode 100644 skills/media-use/scripts/lib/paint-compiler.mjs
 create mode 100644 skills/media-use/scripts/lib/paint-emit.mjs
 create mode 100644 skills/media-use/scripts/paint.mjs
 create mode 100644 skills/media-use/scripts/paint.test.mjs

diff --git a/skills-manifest.json b/skills-manifest.json
index e3860f309f..32c59f25c4 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -50,8 +50,8 @@
       "files": 12
     },
     "media-use": {
-      "hash": "1b0ce647f5c7df95",
-      "files": 152
+      "hash": "15f2c5759218773a",
+      "files": 157
     },
     "motion-graphics": {
       "hash": "69dc088b8e0d22fe",
diff --git a/skills/media-use/SKILL.md b/skills/media-use/SKILL.md
index 5655ccb439..7a27eb7fad 100644
--- a/skills/media-use/SKILL.md
+++ b/skills/media-use/SKILL.md
@@ -90,6 +90,7 @@ Rules that keep this a help, not nagware: **grounded, not generic** (no signal 
 | color grading, LUTs, smart grade (`--for`), grade-compare                 | `references/grading.md`          |
 | voiceover / TTS, music, SFX, captions, transcription (audio engine)       | `references/audio.md`            |
 | cut / reframe / transform existing media, exact error diffusion, HEVC     | `references/operations.md`       |
+| paint an image (or video frame) as brushstroke code (image-to-code)       | `references/paint.md`            |
 | source-aware creative treatments, realtime effects, overlays, reveals     | `references/media-treatments.md` |
 | install + auth, provider table, RAM ladders, `--local-only`, `--provider` | `references/setup-providers.md`  |
 | remembered preferences + frozen recipes (user memory)                     | `references/memory.md`           |
diff --git a/skills/media-use/references/paint.md b/skills/media-use/references/paint.md
new file mode 100644
index 0000000000..f9e9ea7790
--- /dev/null
+++ b/skills/media-use/references/paint.md
@@ -0,0 +1,69 @@
+# Paint — image-to-code compositions
+
+`paint` compiles an image (or one frame of a video) into a standalone
+HyperFrames composition whose **generated code repaints the subject in
+brushstrokes**. The artifact is the code: the stroke list ships as an editable
+data module (`strokes.js`), and the runtime reveals it over the timeline.
+Deterministic: same input + seed produces byte-identical output.
+
+## When to reach for it
+
+- A composition needs a painted, hand-marked look derived from a real image
+  (a portrait, a logo, a product shot, a frame of footage).
+- The brief says "paint this", "make it look brush-painted", or asks for the
+  image to draw itself on screen.
+- You want the image-to-code thesis artifact: code the user can edit.
+
+## Run it
+
+```bash
+node <SKILL_DIR>/scripts/paint.mjs --input photo.jpg --out paint-photo [options]
+```
+
+| Option                 | Default        | Meaning                                   |
+| ---------------------- | -------------- | ----------------------------------------- |
+| `--input <path>`       | required       | source image or video (one frame sampled) |
+| `--out <dir>`          | `paint-<name>` | output folder                             |
+| `--seed <n>`           | `1337`         | stroke randomness seed                    |
+| `--width <px>`         | `1100`         | emitted canvas width                      |
+| `--duration <s>`       | `12`           | reveal duration in seconds                |
+| `--detail <level>`     | `medium`       | `low` / `medium` / `high` stroke budget   |
+| `--video-position <s>` | `0`            | frame sample time for video inputs        |
+| `--json`               | off            | machine-readable summary                  |
+
+Requires `ffmpeg`/`ffprobe` on PATH (the same decode path as the rest of
+media-use's operations).
+
+## Output
+
+```
+paint-photo/
+  index.html   standalone composition (contract-correct root, clip, timeline)
+  strokes.js   editable stroke data — window.__PAINT_STROKES = [...]
+```
+
+The painter runtime is inlined in `index.html`. It reveals strokes in array
+order over `--duration` seconds and is **seek-safe by construction**: band
+canvases are pure functions of their index, so any seek order lands on
+identical pixels. `hyperframes check` passes on the emitted folder as-is.
+
+## Using the output
+
+- **As its own composition**: point `check` / `preview` / `render` at the
+  folder, or copy it into a project's `compositions/` and mount it.
+- **Inside an existing composition**: mount via
+  `data-composition-src` (wrap the emitted root in `<template>` per the
+  sub-composition contract), or paste the inline runtime + a `<canvas>` into
+  your scene and load `strokes.js` alongside it.
+- **Editing the art**: `strokes.js` is plain data. Reorder strokes to change
+  the reveal, delete strokes to simplify, tweak `color`/`weight`/`angle` per
+  stroke. The runtime never needs to change.
+
+## Tuning
+
+- `--detail high` resolves faces and fine texture (~60k strokes on a busy
+  image); `medium` is the balanced default; `low` suits backgrounds.
+- Same seed, same image → identical strokes. Change `--seed` for a different
+  interpretation of the same subject.
+- The reveal order IS the compile order (coarse underpainting first, fine
+  detail last). Reversing the array reverses the reveal.
diff --git a/skills/media-use/scripts/lib/paint-compiler.mjs b/skills/media-use/scripts/lib/paint-compiler.mjs
new file mode 100644
index 0000000000..5864aec8e6
--- /dev/null
+++ b/skills/media-use/scripts/lib/paint-compiler.mjs
@@ -0,0 +1,553 @@
+// paint-compiler.mjs — image-to-strokes compiler (pure, deterministic, seeded).
+// Pipeline: Sobel gradient field -> circular smoothing -> seeded k-means palette
+// (with saturation restore) -> layered jittered-grid stroke placement, coarse to
+// fine, fine layers gated on local variance. Emits an ordered stroke list whose
+// order doubles as reveal order for the generated painter.
+
+/**
+ * @typedef {Object} Stroke
+ * @property {number} x
+ * @property {number} y
+ * @property {number} len
+ * @property {number} angle
+ * @property {number} bend
+ * @property {[number, number, number]} color
+ * @property {number} weight
+ * @property {number} alpha
+ */
+
+/**
+ * @typedef {Object} PaintLayer
+ * @property {number} radius
+ * @property {number} [cellFactor]
+ * @property {number} [baseAngle]
+ * @property {number} [edgeThreshold]
+ * @property {number} [angleJitter]
+ * @property {number} [lenFactor]
+ * @property {number} [weightFactor]
+ * @property {number} [alpha]
+ * @property {boolean} [detailOnly]
+ * @property {number} [detailThreshold]
+ */
+
+/**
+ * @typedef {Object} CompileOptions
+ * @property {number} [seed]
+ * @property {number} width  display width of the emitted canvas in px
+ * @property {PaintLayer[]} layers
+ * @property {number} [paletteSize]
+ * @property {number} [angleSmoothing]
+ */
+
+/**
+ * @typedef {Object} CompileResult
+ * @property {number} width
+ * @property {number} height
+ * @property {Stroke[]} strokes
+ * @property {[number, number, number]} background  mean image color (ground prime)
+ */
+
+/** @param {number} seed */
+export function makeRng(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;
+  };
+}
+
+/**
+ * @param {Uint8ClampedArray | Uint8Array} px RGBA
+ * @param {number} w
+ * @param {number} h
+ */
+export function luminanceMap(px, w, h) {
+  const lum = new Float32Array(w * h);
+  for (let i = 0; i < w * h; i++) {
+    const r = px[i * 4] ?? 0;
+    const g = px[i * 4 + 1] ?? 0;
+    const b = px[i * 4 + 2] ?? 0;
+    lum[i] = 0.299 * r + 0.587 * g + 0.114 * b;
+  }
+  return lum;
+}
+
+/**
+ * @param {Float32Array} lum
+ * @param {number} w
+ * @param {number} h
+ */
+export function sobelField(lum, w, h) {
+  const mag = new Float32Array(w * h);
+  const gx = new Float32Array(w * h);
+  const gy = new Float32Array(w * h);
+  for (let y = 1; y < h - 1; y++) {
+    for (let x = 1; x < w - 1; x++) {
+      const i = y * w + x;
+      const tl = lum[i - w - 1] ?? 0;
+      const t = lum[i - w] ?? 0;
+      const tr = lum[i - w + 1] ?? 0;
+      const l = lum[i - 1] ?? 0;
+      const r = lum[i + 1] ?? 0;
+      const bl = lum[i + w - 1] ?? 0;
+      const b = lum[i + w] ?? 0;
+      const br = lum[i + w + 1] ?? 0;
+      gx[i] = tr + 2 * r + br - (tl + 2 * l + bl);
+      gy[i] = bl + 2 * b + br - (tl + 2 * t + tr);
+      mag[i] = Math.hypot(gx[i] ?? 0, gy[i] ?? 0);
+    }
+  }
+  return { mag, gx, gy };
+}
+
+/**
+ * Circular smoothing of the gradient vectors (magnitude-weighted average), then
+ * rotate 90 degrees so strokes follow contours instead of crossing them.
+ * @param {Float32Array} gx
+ * @param {Float32Array} gy
+ * @param {number} w
+ * @param {number} h
+ * @param {number} iterations
+ */
+export function smoothAngles(gx, gy, w, h, iterations) {
+  let ax = Float32Array.from(gx);
+  let ay = Float32Array.from(gy);
+  for (let it = 0; it < iterations; it++) {
+    const nx = new Float32Array(w * h);
+    const ny = new Float32Array(w * h);
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < w; x++) {
+        let sx = 0;
+        let sy = 0;
+        for (let dy = -1; dy <= 1; dy++) {
+          for (let dx = -1; dx <= 1; dx++) {
+            const xx = Math.min(w - 1, Math.max(0, x + dx));
+            const yy = Math.min(h - 1, Math.max(0, y + dy));
+            sx += ax[yy * w + xx] ?? 0;
+            sy += ay[yy * w + xx] ?? 0;
+          }
+        }
+        nx[y * w + x] = sx / 9;
+        ny[y * w + x] = sy / 9;
+      }
+    }
+    ax = nx;
+    ay = ny;
+  }
+  const dir = new Float32Array(w * h);
+  const mag = new Float32Array(w * h);
+  for (let i = 0; i < w * h; i++) {
+    dir[i] = Math.atan2(ay[i] ?? 0, ax[i] ?? 0) + Math.PI / 2;
+    mag[i] = Math.hypot(ax[i] ?? 0, ay[i] ?? 0);
+  }
+  return { dir, mag };
+}
+
+/**
+ * Seeded k-means palette in RGB, with a saturation restore pass: k-means
+ * averages mute vivid paintings, so centers are pushed back out in HSL space.
+ * @param {Uint8ClampedArray | Uint8Array} px
+ * @param {number} w
+ * @param {number} h
+ * @param {number} k
+ * @param {() => number} rng
+ * @param {number} [iterations]
+ */
+export function kmeansPalette(px, w, h, k, rng, iterations = 10) {
+  const n = w * h;
+  /** @type {[number, number, number][]} */
+  const centers = [];
+  for (let i = 0; i < k; i++) {
+    const idx = Math.floor(rng() * n);
+    centers.push([px[idx * 4] ?? 0, px[idx * 4 + 1] ?? 0, px[idx * 4 + 2] ?? 0]);
+  }
+  for (let it = 0; it < iterations; it++) {
+    /** @type {number[][]} */
+    const sums = Array.from({ length: centers.length }, () => [0, 0, 0, 0]);
+    for (let i = 0; i < n; i++) {
+      const r = px[i * 4] ?? 0;
+      const g = px[i * 4 + 1] ?? 0;
+      const b = px[i * 4 + 2] ?? 0;
+      let best = 0;
+      let bestD = Infinity;
+      for (let c = 0; c < centers.length; c++) {
+        const ctr = centers[c] ?? [0, 0, 0];
+        const dr = r - ctr[0];
+        const dg = g - ctr[1];
+        const db = b - ctr[2];
+        const d = dr * dr + dg * dg + db * db;
+        if (d < bestD) {
+          bestD = d;
+          best = c;
+        }
+      }
+      const s = sums[best];
+      if (s) {
+        s[0] += r;
+        s[1] += g;
+        s[2] += b;
+        s[3]++;
+      }
+    }
+    for (let c = 0; c < centers.length; c++) {
+      const s = sums[c];
+      if (s && s[3] > 0) {
+        centers[c] = [s[0] / s[3], s[1] / s[3], s[2] / s[3]];
+      } else {
+        const idx = Math.floor(rng() * n);
+        centers[c] = [px[idx * 4] ?? 0, px[idx * 4 + 1] ?? 0, px[idx * 4 + 2] ?? 0];
+      }
+    }
+  }
+  const boosted = centers.map((ctr) => boostSaturation(ctr[0] ?? 0, ctr[1] ?? 0, ctr[2] ?? 0));
+  return { centers: boosted };
+}
+
+/** @returns {[number, number, number]} */
+export function boostSaturation(r, g, b, factor = 1.25) {
+  const rf = r / 255;
+  const gf = g / 255;
+  const bf = b / 255;
+  const mx = Math.max(rf, gf, bf);
+  const mn = Math.min(rf, gf, bf);
+  const l = (mx + mn) / 2;
+  let s = mx === mn ? 0 : (mx - mn) / (1 - Math.abs(2 * l - 1));
+  let h = 0;
+  if (mx !== mn) {
+    const d = mx - mn;
+    if (mx === rf) h = ((gf - bf) / d + (gf < bf ? 6 : 0)) * 60;
+    else if (mx === gf) h = ((bf - rf) / d + 2) * 60;
+    else h = ((rf - gf) / d + 4) * 60;
+  }
+  s = Math.min(1, s * factor);
+  const c2 = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c2 * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - c2 / 2;
+  let rr = 0;
+  let gg = 0;
+  let bb = 0;
+  if (h < 60) {
+    rr = c2;
+    gg = x;
+  } else if (h < 120) {
+    rr = x;
+    gg = c2;
+  } else if (h < 180) {
+    gg = c2;
+    bb = x;
+  } else if (h < 240) {
+    gg = x;
+    bb = c2;
+  } else if (h < 300) {
+    rr = x;
+    bb = c2;
+  } else {
+    rr = c2;
+    bb = x;
+  }
+  return [
+    Math.round(Math.max(0, Math.min(255, (rr + m) * 255))),
+    Math.round(Math.max(0, Math.min(255, (gg + m) * 255))),
+    Math.round(Math.max(0, Math.min(255, (bb + m) * 255))),
+  ];
+}
+
+/**
+ * @param {[number, number, number][]} centers
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @returns {[number, number, number]}
+ */
+export function nearestPaletteColor(centers, r, g, b) {
+  let best = centers[0] ?? [0, 0, 0];
+  let bestD = Infinity;
+  for (const ctr of centers) {
+    const dr = r - ctr[0];
+    const dg = g - ctr[1];
+    const db = b - ctr[2];
+    const d = dr * dr + dg * dg + db * db;
+    if (d < bestD) {
+      bestD = d;
+      best = ctr;
+    }
+  }
+  return best;
+}
+
+/**
+ * Layer presets calibrated on The Great Wave, Girl with a Pearl Earring, and
+ * The Scream. `low` keeps stroke counts small; `high` resolves faces and foam.
+ * @type {Record<"low" | "medium" | "high", PaintLayer[]>}
+ */
+export const DETAIL_PRESETS = {
+  low: [
+    {
+      radius: 72,
+      cellFactor: 0.6,
+      baseAngle: -0.12,
+      edgeThreshold: 30,
+      angleJitter: 0.1,
+      lenFactor: 2.6,
+      weightFactor: 0.85,
+      alpha: 1,
+    },
+    {
+      radius: 36,
+      cellFactor: 0.6,
+      baseAngle: -0.06,
+      edgeThreshold: 18,
+      angleJitter: 0.14,
+      lenFactor: 2.3,
+      weightFactor: 0.75,
+      alpha: 0.96,
+    },
+    {
+      radius: 18,
+      cellFactor: 0.6,
+      baseAngle: 0,
+      edgeThreshold: 11,
+      angleJitter: 0.2,
+      lenFactor: 2,
+      weightFactor: 0.65,
+      alpha: 0.94,
+      detailOnly: true,
+      detailThreshold: 0.1,
+    },
+  ],
+  medium: [
+    {
+      radius: 64,
+      cellFactor: 0.55,
+      baseAngle: -0.12,
+      edgeThreshold: 30,
+      angleJitter: 0.1,
+      lenFactor: 2.8,
+      weightFactor: 0.9,
+      alpha: 1,
+    },
+    {
+      radius: 36,
+      cellFactor: 0.55,
+      baseAngle: -0.06,
+      edgeThreshold: 18,
+      angleJitter: 0.14,
+      lenFactor: 2.5,
+      weightFactor: 0.85,
+      alpha: 0.97,
+    },
+    {
+      radius: 20,
+      cellFactor: 0.55,
+      baseAngle: 0,
+      edgeThreshold: 11,
+      angleJitter: 0.2,
+      lenFactor: 2.2,
+      weightFactor: 0.75,
+      alpha: 0.95,
+      detailOnly: true,
+      detailThreshold: 0.08,
+    },
+    {
+      radius: 11,
+      cellFactor: 0.55,
+      baseAngle: 0,
+      edgeThreshold: 7,
+      angleJitter: 0.26,
+      lenFactor: 2,
+      weightFactor: 0.65,
+      alpha: 0.92,
+      detailOnly: true,
+      detailThreshold: 0.03,
+    },
+  ],
+  high: [
+    {
+      radius: 64,
+      cellFactor: 0.55,
+      baseAngle: -0.12,
+      edgeThreshold: 30,
+      angleJitter: 0.1,
+      lenFactor: 2.8,
+      weightFactor: 0.9,
+      alpha: 1,
+    },
+    {
+      radius: 36,
+      cellFactor: 0.55,
+      baseAngle: -0.06,
+      edgeThreshold: 18,
+      angleJitter: 0.14,
+      lenFactor: 2.5,
+      weightFactor: 0.85,
+      alpha: 0.97,
+    },
+    {
+      radius: 20,
+      cellFactor: 0.48,
+      baseAngle: 0,
+      edgeThreshold: 11,
+      angleJitter: 0.2,
+      lenFactor: 2.2,
+      weightFactor: 0.75,
+      alpha: 0.95,
+      detailOnly: true,
+      detailThreshold: 0.06,
+    },
+    {
+      radius: 11,
+      cellFactor: 0.45,
+      baseAngle: 0,
+      edgeThreshold: 7,
+      angleJitter: 0.26,
+      lenFactor: 2,
+      weightFactor: 0.65,
+      alpha: 0.92,
+      detailOnly: true,
+      detailThreshold: 0.02,
+    },
+    {
+      radius: 7,
+      cellFactor: 0.45,
+      baseAngle: 0,
+      edgeThreshold: 5,
+      angleJitter: 0.3,
+      lenFactor: 1.8,
+      weightFactor: 0.55,
+      alpha: 0.9,
+      detailOnly: true,
+      detailThreshold: 0.008,
+    },
+  ],
+};
+
+/**
+ * Compile RGBA pixels into an ordered stroke list.
+ * @param {Uint8ClampedArray | Uint8Array} px
+ * @param {number} w
+ * @param {number} h
+ * @param {CompileOptions} opts
+ * @returns {CompileResult}
+ */
+export function compileStrokes(px, w, h, opts) {
+  const rng = makeRng(opts.seed ?? 1337);
+  const outW = opts.width;
+  const outH = Math.round((h / w) * outW);
+
+  const lum = luminanceMap(px, w, h);
+  const { gx, gy } = sobelField(lum, w, h);
+  const { dir, mag } = smoothAngles(gx, gy, w, h, opts.angleSmoothing ?? 4);
+  const { centers } = kmeansPalette(px, w, h, opts.paletteSize ?? 22, rng);
+
+  const sx = outW / w;
+  const sy = outH / h;
+  /** @type {Stroke[]} */
+  const strokes = [];
+
+  // local variance for detail gating (5x5 window)
+  const variance = new Float32Array(w * h);
+  {
+    const R = 2;
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < w; x++) {
+        let sum = 0;
+        let sum2 = 0;
+        let count = 0;
+        for (let dy = -R; dy <= R; dy++) {
+          for (let dx = -R; dx <= R; dx++) {
+            const xx = Math.min(w - 1, Math.max(0, x + dx));
+            const yy = Math.min(h - 1, Math.max(0, y + dy));
+            const v = lum[yy * w + xx] ?? 0;
+            sum += v;
+            sum2 += v * v;
+            count++;
+          }
+        }
+        const mean = sum / count;
+        variance[y * w + x] = sum2 / count - mean * mean;
+      }
+    }
+  }
+  let varMax = 0;
+  for (let i = 0; i < variance.length; i++) {
+    const v = variance[i] ?? 0;
+    if (v > varMax) varMax = v;
+  }
+
+  let ar = 0;
+  let ag = 0;
+  let ab = 0;
+  const total = w * h;
+  for (let i = 0; i < total; i++) {
+    ar += px[i * 4] ?? 0;
+    ag += px[i * 4 + 1] ?? 0;
+    ab += px[i * 4 + 2] ?? 0;
+  }
+  const background = [Math.round(ar / total), Math.round(ag / total), Math.round(ab / total)];
+
+  for (const layer of opts.layers) {
+    const radius = layer.radius;
+    const cell = radius * (layer.cellFactor ?? 1);
+    const baseWeight = Math.max(1.6, radius * 0.75);
+    for (let gy2 = cell / 2; gy2 < outH; gy2 += cell) {
+      for (let gxi = cell / 2; gxi < outW; gxi += cell) {
+        const x = gxi + (rng() - 0.5) * cell * 0.9;
+        const y = gy2 + (rng() - 0.5) * cell * 0.9;
+        const wx = Math.min(w - 1, Math.max(0, Math.round(x / sx)));
+        const wy = Math.min(h - 1, Math.max(0, Math.round(y / sy)));
+        const widx = wy * w + wx;
+
+        if (layer.detailOnly) {
+          const v = (variance[widx] ?? 0) / (varMax || 1);
+          if (v < (layer.detailThreshold ?? 0)) continue;
+        }
+
+        const strong = (mag[widx] ?? 0) > (layer.edgeThreshold ?? 12);
+        const flowAngle = strong
+          ? (dir[widx] ?? 0)
+          : (layer.baseAngle ?? 0) + 0.15 * Math.sin((y / outH) * 3.1 + (x / outW) * 1.3);
+        const angle = flowAngle + (rng() - 0.5) * (layer.angleJitter ?? 0.14);
+
+        const ri = Math.min(w - 1, Math.max(0, Math.round(x / sx)));
+        const rj = Math.min(h - 1, Math.max(0, Math.round(y / sy)));
+        const pi = (rj * w + ri) * 4;
+        const col = nearestPaletteColor(centers, px[pi] ?? 0, px[pi + 1] ?? 0, px[pi + 2] ?? 0);
+        const jitter = 4;
+        const cr = clamp255(col[0] + (rng() - 0.5) * 2 * jitter);
+        const cg = clamp255(col[1] + (rng() - 0.5) * 2 * jitter);
+        const cb = clamp255(col[2] + (rng() - 0.5) * 2 * jitter);
+
+        const len = radius * (layer.lenFactor ?? 2.1) * (0.75 + rng() * 0.5);
+        strokes.push({
+          x: round1(x),
+          y: round1(y),
+          len: round1(len),
+          angle: round1((angle * 180) / Math.PI),
+          bend: round1(len * 0.14 * (rng() - 0.5)),
+          color: [cr, cg, cb],
+          weight: round2(baseWeight * (0.8 + rng() * 0.4) * (layer.weightFactor ?? 1)),
+          alpha: layer.alpha ?? 0.9,
+        });
+      }
+    }
+  }
+  return { width: outW, height: outH, strokes, background };
+}
+
+/** @param {number} v */
+function clamp255(v) {
+  return Math.round(Math.max(0, Math.min(255, v)));
+}
+
+/** @param {number} v */
+function round1(v) {
+  return Math.round(v * 10) / 10;
+}
+
+/** @param {number} v */
+function round2(v) {
+  return Math.round(v * 100) / 100;
+}
diff --git a/skills/media-use/scripts/lib/paint-emit.mjs b/skills/media-use/scripts/lib/paint-emit.mjs
new file mode 100644
index 0000000000..e67b087583
--- /dev/null
+++ b/skills/media-use/scripts/lib/paint-emit.mjs
@@ -0,0 +1,182 @@
+// paint-emit.mjs — emits a standalone HyperFrames composition from compiled
+// strokes: index.html (contract-correct root + clip + timeline), strokes.js
+// (editable data module), painter.js (seek-safe banded reveal runtime).
+
+/**
+ * @typedef {import("./paint-compiler.mjs").Stroke} Stroke
+ */
+
+/**
+ * @typedef {Object} EmitOptions
+ * @property {string} id  composition id (kebab-case)
+ * @property {Stroke[]} strokes
+ * @property {number} width
+ * @property {number} height
+ * @property {number} duration  seconds
+ * @property {[number, number, number]} background
+ */
+
+/**
+ * Emit the composition files. Returns a map of relative path -> file content.
+ * @param {EmitOptions} opts
+ * @returns {Record<string, string>}
+ */
+export function emitComposition(opts) {
+  const { id, strokes, width, height, duration, background } = opts;
+  const bands = Math.max(8, Math.min(32, Math.ceil(strokes.length / 1200)));
+  const config = {
+    id,
+    width,
+    height,
+    duration,
+    bands,
+    background: `rgb(${background[0]},${background[1]},${background[2]})`,
+  };
+  // The painter runtime is inlined into index.html so static analysis (and
+  // `hyperframes lint`) sees the timeline registration; strokes.js stays an
+  // external, editable data module.
+  return {
+    "index.html": indexHtml(config) + "<script>\n" + painterSource(config) + "</script>\n",
+    "strokes.js": strokesModule(strokes),
+  };
+}
+
+/** @param {Stroke[]} strokes */
+function strokesModule(strokes) {
+  const rows = strokes
+    .map(
+      (s) =>
+        `{"x":${s.x},"y":${s.y},"len":${s.len},"angle":${s.angle},"bend":${s.bend},"color":[${s.color[0]},${s.color[1]},${s.color[2]}],"weight":${s.weight},"alpha":${s.alpha}}`,
+    )
+    .join(",\n");
+  // Editable data module: reorder, retune, or delete strokes — the painter
+  // reveals them in array order.
+  return `window.__PAINT_STROKES = [\n${rows}\n];\n`;
+}
+
+/**
+ * @typedef {{ id: string, width: number, height: number, duration: number, bands: number, background: string }} PainterConfig
+ * @param {PainterConfig} cfg
+ */
+function indexHtml(cfg) {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=${cfg.width}, height=${cfg.height}" />
+    <title>paint — ${cfg.id}</title>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      html, body { width: ${cfg.width}px; height: ${cfg.height}px; overflow: hidden; background: #000; }
+      #root { position: relative; width: ${cfg.width}px; height: ${cfg.height}px; overflow: hidden; background: #000; }
+      .clip { position: absolute; inset: 0; }
+      canvas { display: block; width: 100%; height: 100%; }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="${cfg.id}"
+      data-start="0"
+      data-width="${cfg.width}"
+      data-height="${cfg.height}"
+      data-duration="${cfg.duration}"
+    >
+      <section id="paint-clip" class="clip" data-start="0" data-duration="${cfg.duration}" data-track-index="1">
+        <canvas id="paint-canvas" width="${cfg.width}" height="${cfg.height}"></canvas>
+      </section>
+    </div>
+    <script src="strokes.js"></script>
+  </body>
+</html>
+`;
+}
+
+/**
+ * The emitted runtime. Seek-safe by construction: band canvases are pure
+ * functions of their band index (drawn once, cached), and the partial band is
+ * redrawn from scratch on every update, so any seek order lands on identical
+ * pixels. Per-frame cost is O(strokes/bands) plus bandCount drawImage calls.
+ * @param {PainterConfig} cfg
+ */
+export function painterSource(cfg) {
+  return `// painter.js — generated by hyperframes media-use paint.
+// Reveals the stroke data in array order over ${cfg.duration}s. Seek-safe:
+// canvas state is a pure function of timeline progress. Edit strokes.js to
+// reshape the painting; this file never needs to change.
+(function () {
+  "use strict";
+  var strokes = window.__PAINT_STROKES || [];
+  var W = ${cfg.width};
+  var H = ${cfg.height};
+  var DURATION = ${cfg.duration};
+  var BANDS = ${cfg.bands};
+  var BG = ${JSON.stringify(cfg.background)};
+
+
+  var canvas = document.getElementById("paint-canvas");
+  var ctx = canvas.getContext("2d");
+  var per = Math.ceil(strokes.length / BANDS) || 1;
+  var bandCount = Math.max(1, Math.ceil(strokes.length / per));
+
+  function drawStroke(g, s) {
+    g.strokeStyle = "rgb(" + s.color[0] + "," + s.color[1] + "," + s.color[2] + ")";
+    g.lineWidth = s.weight;
+    g.globalAlpha = s.alpha;
+    var rad = (s.angle * Math.PI) / 180;
+    var dx = Math.cos(rad), dy = -Math.sin(rad);
+    var half = s.len / 2;
+    g.beginPath();
+    g.moveTo(s.x - dx * half, s.y - dy * half);
+    g.quadraticCurveTo(s.x - dy * s.bend, s.y + dx * s.bend, s.x + dx * half, s.y + dy * half);
+    g.stroke();
+  }
+
+  // band canvases: transparent, strokes only; drawn once per band index
+  var bands = [];
+  for (var b = 0; b < bandCount; b++) {
+    var bc = document.createElement("canvas");
+    bc.width = W;
+    bc.height = H;
+    var bctx = bc.getContext("2d");
+    bctx.lineCap = "round";
+    bctx.lineJoin = "round";
+    var start = b * per;
+    var end = Math.min(strokes.length, start + per);
+    for (var i = start; i < end; i++) drawStroke(bctx, strokes[i]);
+    bands.push(bc);
+  }
+
+  var scratch = document.createElement("canvas");
+  scratch.width = W;
+  scratch.height = H;
+  var sctx = scratch.getContext("2d");
+  sctx.lineCap = "round";
+  sctx.lineJoin = "round";
+
+  function paintAt(progress) {
+    var drawn = progress * strokes.length;
+    var full = Math.min(bandCount, Math.floor(drawn / per));
+    ctx.globalAlpha = 1;
+    ctx.fillStyle = BG;
+    ctx.fillRect(0, 0, W, H);
+    for (var b = 0; b < full; b++) ctx.drawImage(bands[b], 0, 0);
+    var cur = full;
+    if (cur < bandCount && drawn > cur * per) {
+      sctx.clearRect(0, 0, W, H);
+      var end = Math.min(strokes.length, Math.ceil(drawn));
+      for (var i = cur * per; i < end; i++) drawStroke(sctx, strokes[i]);
+      ctx.drawImage(scratch, 0, 0);
+    }
+  }
+
+  window.__timelines = window.__timelines || {};
+  var tl = gsap.timeline({ paused: true });
+  var proxy = { p: 0 };
+  tl.to(proxy, { p: 1, duration: DURATION, ease: "none", onUpdate: function () { paintAt(proxy.p); } }, 0);
+  window.__timelines[${JSON.stringify(cfg.id)}] = tl;
+  paintAt(0);
+})();
+`;
+}
diff --git a/skills/media-use/scripts/paint.mjs b/skills/media-use/scripts/paint.mjs
new file mode 100644
index 0000000000..8a8f2dd93b
--- /dev/null
+++ b/skills/media-use/scripts/paint.mjs
@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// paint.mjs — media-use paint: compile an image (or one video frame) into a
+// standalone HyperFrames composition whose generated code repaints it in
+// brushstrokes. Deterministic: same input + seed -> identical output files.
+//
+// Usage:
+//   node paint.mjs --input photo.jpg [--out paint-photo] [options]
+//
+// The emitted folder is a standalone composition: mount it in a project, open
+// it in Studio, or run `hyperframes check` on it as-is.
+
+import { execFileSync, spawn } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { compileStrokes, DETAIL_PRESETS } from "./lib/paint-compiler.mjs";
+import { emitComposition } from "./lib/paint-emit.mjs";
+
+const WORK_LONG_EDGE = 640;
+
+const { values: args } = parseArgs({
+  options: {
+    input: { type: "string", short: "i" },
+    out: { type: "string", short: "o" },
+    seed: { type: "string", default: "1337" },
+    width: { type: "string", default: "1100" },
+    duration: { type: "string", default: "12" },
+    detail: { type: "string", default: "medium" },
+    "video-position": { type: "string", default: "0" },
+    json: { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+  },
+  strict: true,
+});
+
+if (args.help || !args.input) {
+  console.log(`media-use paint — compile an image into a brushstroke-code composition
+
+Usage:
+  node paint.mjs --input photo.jpg [--out paint-photo] [options]
+
+The emitted folder is a standalone HyperFrames composition (index.html,
+strokes.js, painter.js). strokes.js is the editable stroke data; painter.js
+reveals it over --duration seconds and is seek-safe.
+
+Options:
+  --input <path>         source image or video (one frame is sampled)
+  --out <dir>            output folder (default: paint-<basename>)
+  --seed <n>             stroke randomness seed (default 1337)
+  --width <px>           emitted canvas width (default 1100)
+  --duration <s>         reveal duration in seconds (default 12)
+  --detail <level>       low | medium | high (default medium)
+  --video-position <s>   frame sample time for video inputs (default 0)
+  --json                 machine-readable summary
+  -h, --help`);
+  process.exit(args.help ? 0 : 1);
+}
+
+const inputPath = resolve(String(args.input));
+const detail = String(args.detail ?? "medium");
+const layers = DETAIL_PRESETS[/** @type {"low" | "medium" | "high"} */ (detail)];
+if (!layers) {
+  console.error(`unknown --detail "${detail}": use low, medium, or high`);
+  process.exit(1);
+}
+const seed = Number(args.seed);
+const displayWidth = Number(args.width);
+const duration = Number(args.duration);
+if (!Number.isFinite(seed) || !Number.isFinite(displayWidth) || !Number.isFinite(duration)) {
+  console.error("--seed, --width, and --duration must be numbers");
+  process.exit(1);
+}
+
+function fail(message) {
+  if (args.json) console.log(JSON.stringify({ error: message }));
+  else console.error("error: " + message);
+  process.exit(1);
+}
+
+function probe(path) {
+  const out = execFileSync(
+    "ffprobe",
+    [
+      "-v",
+      "error",
+      "-select_streams",
+      "v:0",
+      "-show_entries",
+      "stream=width,height",
+      "-of",
+      "json",
+      path,
+    ],
+    { maxBuffer: 1024 * 1024, encoding: "utf8" },
+  );
+  const parsed = JSON.parse(out);
+  const stream = parsed?.streams?.[0];
+  if (!stream?.width || !stream?.height) fail("no video stream found in input");
+  return { width: stream.width, height: stream.height };
+}
+
+async function decodeRgba(path, w, h, videoPosition) {
+  const seek = Number(videoPosition) > 0 ? ["-ss", String(Number(videoPosition))] : [];
+  const frameBytes = w * h * 4;
+  const chunks = [];
+  const child = spawn(
+    "ffmpeg",
+    [
+      ...seek,
+      "-i",
+      path,
+      "-frames:v",
+      "1",
+      "-vf",
+      `scale=${w}:${h}`,
+      "-f",
+      "rawvideo",
+      "-pix_fmt",
+      "rgba",
+      "-",
+    ],
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  child.stdout.on("data", (chunk) => chunks.push(chunk));
+  const code = await new Promise((resolvePromise) => {
+    child.on("exit", (c) => resolvePromise(c ?? 1));
+    child.on("error", () => resolvePromise(1));
+  });
+  if (code !== 0) fail("ffmpeg failed to decode the input");
+  const rgba = Buffer.concat(chunks);
+  if (rgba.length !== frameBytes) fail(`decoded ${rgba.length} bytes; expected ${frameBytes}`);
+  return new Uint8ClampedArray(rgba.buffer, rgba.byteOffset, rgba.byteLength);
+}
+
+const meta = probe(inputPath);
+const scale = Math.min(1, WORK_LONG_EDGE / Math.max(meta.width, meta.height));
+const workW = Math.max(2, Math.round(meta.width * scale));
+const workH = Math.max(2, Math.round(meta.height * scale));
+const px = await decodeRgba(inputPath, workW, workH, args["video-position"]);
+
+const compiled = compileStrokes(px, workW, workH, {
+  seed,
+  width: displayWidth,
+  layers,
+  paletteSize: 22,
+  angleSmoothing: 4,
+});
+
+const outDir = resolve(String(args.out ?? `paint-${basename(inputPath).replace(/\.[^.]+$/, "")}`));
+const files = emitComposition({
+  id: `paint-${basename(inputPath)
+    .replace(/\.[^.]+$/, "")
+    .replace(/[^a-z0-9-]+/gi, "-")
+    .toLowerCase()}`,
+  strokes: compiled.strokes,
+  width: compiled.width,
+  height: compiled.height,
+  duration,
+  background: compiled.background,
+});
+mkdirSync(outDir, { recursive: true });
+for (const [name, content] of Object.entries(files)) {
+  writeFileSync(join(outDir, name), content);
+}
+
+const summary = {
+  out: outDir,
+  files: Object.keys(files),
+  strokes: compiled.strokes.length,
+  width: compiled.width,
+  height: compiled.height,
+  duration,
+  seed,
+  detail,
+  next: [`npx hyperframes check ${outDir}`, `npx hyperframes preview ${outDir}`],
+};
+if (args.json) console.log(JSON.stringify(summary, null, 2));
+else {
+  console.log(`paint: ${compiled.strokes.length} strokes -> ${outDir}`);
+  console.log(`  ${Object.keys(files).join(", ")}`);
+  console.log(`  validate: npx hyperframes check ${outDir}`);
+}
diff --git a/skills/media-use/scripts/paint.test.mjs b/skills/media-use/scripts/paint.test.mjs
new file mode 100644
index 0000000000..81f7cb616a
--- /dev/null
+++ b/skills/media-use/scripts/paint.test.mjs
@@ -0,0 +1,166 @@
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { compileStrokes, DETAIL_PRESETS } from "./lib/paint-compiler.mjs";
+import { emitComposition } from "./lib/paint-emit.mjs";
+
+const SCRIPT = new URL("./paint.mjs", import.meta.url).pathname;
+const HAS_FFMPEG =
+  spawnSync("ffmpeg", ["-version"], { stdio: "ignore" }).status === 0 &&
+  spawnSync("ffprobe", ["-version"], { stdio: "ignore" }).status === 0;
+
+function fixturePixels(w, h) {
+  const px = new Uint8ClampedArray(w * h * 4);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const i = (y * w + x) * 4;
+      px[i] = (x * 255) / w;
+      px[i + 1] = (y * 255) / h;
+      px[i + 2] = 128;
+      px[i + 3] = 255;
+    }
+  }
+  return px;
+}
+
+test("compileStrokes is deterministic for a fixed seed", () => {
+  const a = compileStrokes(fixturePixels(96, 72), 96, 72, {
+    seed: 1337,
+    width: 400,
+    layers: DETAIL_PRESETS.medium,
+  });
+  const b = compileStrokes(fixturePixels(96, 72), 96, 72, {
+    seed: 1337,
+    width: 400,
+    layers: DETAIL_PRESETS.medium,
+  });
+  assert.equal(JSON.stringify(a), JSON.stringify(b));
+  assert.ok(a.strokes.length > 0);
+});
+
+test("compileStrokes varies with the seed", () => {
+  const a = compileStrokes(fixturePixels(96, 72), 96, 72, {
+    seed: 1,
+    width: 400,
+    layers: DETAIL_PRESETS.medium,
+  });
+  const b = compileStrokes(fixturePixels(96, 72), 96, 72, {
+    seed: 2,
+    width: 400,
+    layers: DETAIL_PRESETS.medium,
+  });
+  assert.notEqual(JSON.stringify(a), JSON.stringify(b));
+});
+
+test("stroke geometry stays on the canvas and weights stay positive", () => {
+  const r = compileStrokes(fixturePixels(96, 72), 96, 72, {
+    seed: 7,
+    width: 400,
+    layers: DETAIL_PRESETS.high,
+  });
+  const overhang = Math.max(...DETAIL_PRESETS.high.map((l) => l.radius));
+  for (const s of r.strokes) {
+    assert.ok(s.x >= -overhang && s.x <= r.width + overhang, "x within one-radius overhang");
+    assert.ok(s.y >= -overhang && s.y <= r.height + overhang, "y within one-radius overhang");
+    assert.ok(s.weight > 0, "positive weight");
+    assert.ok(s.len > 0, "positive length");
+    assert.ok(Array.isArray(s.color) && s.color.length === 3, "color triple");
+  }
+});
+
+test("emitted composition carries the HyperFrames contract", () => {
+  const compiled = compileStrokes(fixturePixels(96, 72), 96, 72, {
+    seed: 5,
+    width: 400,
+    layers: DETAIL_PRESETS.low,
+  });
+  const files = emitComposition({
+    id: "paint-test",
+    strokes: compiled.strokes,
+    width: compiled.width,
+    height: compiled.height,
+    duration: 10,
+    background: compiled.background,
+  });
+  assert.deepEqual(Object.keys(files).sort(), ["index.html", "strokes.js"]);
+  const html = files["index.html"];
+  assert.match(html, /data-composition-id="paint-test"/);
+  assert.match(html, /data-start="0"/);
+  assert.match(html, /data-width="400"/);
+  assert.match(html, /data-duration="10"/);
+  assert.match(html, /class="clip"/);
+  assert.match(html, /window.__timelines/);
+  assert.match(html, /gsap/);
+  const strokesSource = files["strokes.js"];
+  assert.match(strokesSource, /window\.__PAINT_STROKES = \[/);
+  const assigned = strokesSource.match(/window\.__PAINT_STROKES = \[([\s\S]*)\];/)?.[1] ?? "";
+  const parsed = JSON.parse(`[${assigned}]`);
+  assert.equal(parsed.length, compiled.strokes.length);
+  assert.match(html, /paintAt/);
+  assert.match(html, /drawImage/);
+  assert.match(html, /window\.__timelines\["paint-test"\]/);
+});
+
+test("emit is deterministic for identical inputs", () => {
+  const compiled = compileStrokes(fixturePixels(96, 72), 96, 72, {
+    seed: 9,
+    width: 400,
+    layers: DETAIL_PRESETS.low,
+  });
+  const opts = {
+    id: "paint-test",
+    strokes: compiled.strokes,
+    width: compiled.width,
+    height: compiled.height,
+    duration: 10,
+    background: compiled.background,
+  };
+  assert.deepEqual(emitComposition(opts), emitComposition(opts));
+});
+
+test("paint.mjs emits a composition from a real image", { skip: !HAS_FFMPEG }, (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "media-use-paint-"));
+  t.after(cleanup);
+  function cleanup() {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  const input = join(dir, "fixture.png");
+  execFileSync("ffmpeg", [
+    "-y",
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-f",
+    "lavfi",
+    "-i",
+    "gradients=s=160x120:c0=0x224488:c1=0xeecc66",
+    "-frames:v",
+    "1",
+    input,
+  ]);
+  const out = join(dir, "paint-fixture");
+  const run = spawnSync(process.execPath, [SCRIPT, "--input", input, "--out", out, "--json"], {
+    encoding: "utf8",
+  });
+  assert.equal(run.status, 0, run.stderr);
+  const summary = JSON.parse(run.stdout);
+  assert.ok(summary.strokes > 0);
+  for (const file of ["index.html", "strokes.js"]) {
+    assert.ok(existsSync(join(out, file)), file);
+  }
+  const strokesSource = readFileSync(join(out, "strokes.js"), "utf8");
+  assert.match(strokesSource, /window\.__PAINT_STROKES = \[/);
+  const run2 = spawnSync(
+    process.execPath,
+    [SCRIPT, "--input", input, "--out", join(dir, "paint-fixture-2"), "--json"],
+    {
+      encoding: "utf8",
+    },
+  );
+  assert.equal(run2.status, 0, run2.stderr);
+  const strokes2 = readFileSync(join(dir, "paint-fixture-2", "strokes.js"), "utf8");
+  assert.equal(strokesSource, strokes2, "same input + seed -> identical stroke data");
+});