Author an anim
An anim is one file, <kebab-name>@<major>.<minor>.yaml, with exactly four keys: t (the literal c), j (an ES module), s (CSS), h (HTML/SVG). A host player runs it with a global G API that delivers the song's syllables, words, lines, sections and beats. Your job: turn a brief into one such file that is correct under seek/pause/resize/theme, legible, and beautiful. Paths below are relative to this skill/ directory.
The rules that matter most
- A frame is a pure function of playback time.
render(t)must draw the same picture whether playback reachedtor the user scrubbed to it. NoMath.random,Date.now, accumulated integration or "what happened last frame" state that a seek would skip. Derive everything from song data, the seed andt. - Two halves. An exported, DOM-free pure half (
buildPlan,frameAt, helpers; unit-testable) above a banner comment, then a thin browser half (export default function (G, shadowRoot, config)) that only wires and draws. Seeguides/architecture.md. - Register in
default, read song data inINIT.G.on/G.off/G.onFrameonly insidedefault.G.map/forEach/lookup/iterator/relayoutonly onceINIThas fired (anINIThandler, or later callbacks such asrender), never indefaultitself. SubscribeG.on(G.TYPE.TICK, render)for playback;G.onFrame({ render, reset })covers SEEK/PLAY/PAUSE/RESIZE and UNINIT. - Clean up with
G.dispose/G.listen. A function returned fromdefaultis ignored. Release WebGL (forceContextLoss), listeners, timers, camera. - Colours live in CSS, not in
c.v. Light values on:host, dark overrides in[data-bs-theme=dark] { }; canvas reads them back with g-libcssColors. Both themes must look intentional. - Never hand-roll what g-lib has (clamp, lerp, easing, seeded RNG, canvas fitting, springs, text layout, pools...). Import from the exact-tag pin; check
pitfalls/dont-hand-roll.mdandspec/g-lib.mdbefore writing any helper. - Legibility beats effect. The active syllable is readable in light and dark, on phone and laptop, for long lines, CJK, RTL and Myanmar. Large flashes stay under 3 Hz (
guides/accessibility.md). - Few typed options.
candcSchemaare plain literals; each option does something visible.
Workflow (with the repo tools)
- Brief. Write the design brief from
guides/design-brief.md: one strong, physical picture; the mechanism; which events drive what (the sync map); structure (verse/chorus/beat); legibility plan; options; traps. Pick the backend with its selection table. Reject ideas that cannot stay legible. - Scaffold.
npm run new -- <name> --backend canvas2d|svg|dom|three(or copytemplates/<backend>.yamlby hand and replace__NAME__). - Read once:
spec/module-format.md,pitfalls/general.md, your backend's section inpitfalls/backends.md,pitfalls/dont-hand-roll.md. Open anything else only through the routing table below. - Implement the pure half first (time to state), then the thin browser half.
- Validate.
npm run validate -- anims/<file>.yaml. Fix every error; justify every warning in the docblock or fix it. - Check.
npm run check -- anims/<file>.yamlmounts 13 edge-case songs headlessly, scores the conformance table and writes PNGs toout/<name>/. Open the PNGs (phone/laptop, light/dark). A green table over an ugly or illegible frame is a fail. A WARN on a seek-purity row means the picture depends on history: fix it, or justify it in the docblock (a deliberate simulation). - Preview (optional).
npm run preview -- anims/<file>.yamlto play, scrub, flip theme and tweak options. - Review against
guides/quality-rubric.md(20 questions), then deliver the one YAML file and a short report (filename, final check table, decisions the brief left open, what you deliberately did not do). Do not shipout/or the harness.
Tool-less mode (chat models, no shell)
Skip steps 2, 5-7. Start from the matching template text, write the design brief in your reasoning, then walk pitfalls/general.md, the backend section and the 20-question rubric line by line against your own code before answering. Output only the YAML file in one fenced block, and mention which rubric items you could not verify without running it (seek purity, theme flip, resize).
Routing table: open a doc only when its trigger applies
| When you are about to... | Read |
|---|---|
| decide what to build; choose a backend | guides/design-brief.md |
| lay out the file; name stages; write the docblock | guides/architecture.md |
use any G.* call, event option or id range | spec/events.md, spec/event-shapes.md, spec/g.d.ts |
| add options, colours, theming | spec/config.md |
| use time utilities, text measuring, canvas helpers, lifecycle | spec/utilities.md |
| split lines into display lines, wrap text | spec/relayout.md, guides/patterns-text.md |
| trigger things on syllables/lines/beats; pre-spawn; pause; springs | guides/patterns-timing.md |
| fit, highlight or style text; non-Latin scripts | guides/patterns-text.md |
| write rendering code (DOM, SVG, canvas, three, simulation, layers) | guides/patterns-render.md, pitfalls/backends.md |
| camera, terrain, swarms, packing, procedural 3D | guides/techniques.md, pitfalls/techniques.md |
| use a photo or camera | spec/image-input.md |
| build a game (autoPlay false, score, states) | guides/games.md |
| use any g-lib helper | spec/g-lib.md |
| feel unsure about flashing, motion, contrast | guides/accessibility.md |
| finish | guides/quality-rubric.md |
Minimal shape (do not ship this; start from a template)
"t": |-
c
"j": |
import { hash01 } from 'https://cdn.jsdelivr.net/gh/prjctg/[email protected]/index.js';
/* [email protected]: <one line>
* 1. <numbered design claim: the mechanism and the tempting wrong answer it rejects> */
export function frameAt(plan, t) { /* pure */ }
/* Browser half. Everything above this line is DOM-free on purpose. */
export default function (G, shadowRoot, config) {
const cfg = G.cfg(config, { channel: G.cfg.int(0) });
let ready = false;
const render = (t) => { if (!ready) return; /* draw frameAt(plan, t) */ };
G.on(G.TYPE.INIT, () => { ready = true; /* G.map(...) is valid here */ });
G.on(G.TYPE.TICK, render);
G.onFrame({ render, reset() { ready = false; } });
}
export const c = { v: { fadeMs: 150 }, m: [{ s: 'fadeMs', t: 'fadeMs' }] };
export const cSchema = [{ i: 'fadeMs', n: 'Fade (ms)', t: 'int', mn: 0, mx: 2000 }];
"s": |
:host { display: block; --ink: var(--inkColor, #111); }
[data-bs-theme=dark] { --ink: var(--inkColor, #eee); }
"h": |
<canvas id="c"></canvas>
j, s, h hold raw text (never wrapped in backticks or quotes). t uses |-. The file name carries the version; never edit a published version in place.