@texel/yyz-cli

The yyz command line for yyz. It's an npm package run with Deno (chosen for Deno's first‑class headless canvas2d + webgpu). The CLI is written with only node: + npm: imports; the few Deno‑specific touchpoints (Deno.serve, Deno.upgradeWebSocket, the deno‑canvas surface, git via node:child_process) are isolated, so a node/bun port is additive.

Install

deno install -gA -n yyz npm:@texel/yyz-cli

Commands

yyz [serve] sketch.js          # dev server + live reload   (-o / --open to open the browser)
yyz build  sketch.js           # folder build (index.html + bundle.js) -> --dir (default ./dist)
yyz build  sketch.js --inline  # a single self-contained .html
yyz render sketch.js                   # headless render (Deno) -> --output (default ./output)
yyz render sketch.js --frames=120      # ...render an explicit number of frames (from 0)
yyz render sketch.js --format=gif      # ...a single animated GIF (pure-JS gifenc; no ffmpeg)
yyz render sketch.js --format=mp4      # ...mp4 / webm video (ffmpeg) at highest quality
yyz render sketch.js --target ./r2.js  # ...or pipe frames to a custom Sink module
yyz new    sketch.js --template default|print|svg
yyz commit                     # git add/commit, print the short hash

Flags: -o/--open, --port (9966; if taken, the next free port is used — pass --no-portfind to fail instead), --host (127.0.0.1; 0.0.0.0 to expose on the LAN), --logging=rich|simple (terminal output; see below), --output, --target, --dir, --inline, --frames=N (how many to render, from 0; defaults to one loop), --format=png|jpeg|webp|gif|mp4|webm, --encoder=js|ffmpeg (gif: js=gifenc default or ffmpeg 2‑pass; mp4/webm use ffmpeg headless), --quality=0..1 (video CRF/bitrate, default 1 = highest), --pixelRatio/--exportPixelRatio, --fps, --duration, and any --key=value as a sketch param (e.g. --seed=mint). A param overrides the matching key in the sketch's top‑level params (coerced to its default's type); if settings is a (params) => settings function, that param can drive the config itself — e.g. --pixelsPerInch=300 to render a 72‑DPI working sketch at print resolution.

In the terminal (serve): on a TTY the dev server shows a sticky banner — yyz X.Y.Z <entry>, the local + network URLs (the network line reads not exposed (pass --host) until you pass --host), the output dir, and an h + enter → shortcuts hint. Each repaint faux‑clears the screen (prior output scrolls into history, recoverable; the visible area stays clean). A build error repaints to the error frame; a fix repaints back to the banner. Line‑buffered shortcuts (press the key, then enter): h help · u show url · o open browser · c clear · q quit. Pass --logging=simple (or set logging: "simple" in config) for plain append‑only logging with no screen clearing or stdin capture — handy for long‑running servers, piped logs, and CI; this is also the automatic behavior when stdout isn't a TTY.

In the browser (serve or a built page): Cmd/Ctrl+S exports the current frame; Cmd/Ctrl+Shift+S records the loop (default mp4) — via WebCodecs natively, or the dev server's ffmpeg with settings.export = { encoder: "ffmpeg" }. window.yyzRecord({ format, encoder, quality, frames }) does the same from the console.

How it works

• serve — esbuild bundles your sketch + the engine + a tiny client; Deno.serve hosts it; Deno.upgradeWebSocket drives a full‑page live reload on rebuild. Cmd+S exports a frame to disk (git tag, -unstaged when uncommitted; Cmd+K commits first); Cmd+Shift+S records video — WebCodecs in the page, or streamed to the server's ffmpeg (/__yyz/record/*).
• render — imports your sketch directly (no bundler), draws each frame on a Skia canvas (@napi-rs/canvas), streams to the resolved Sink (a file sequence, or an encoder: gifenc / ffmpeg mp4·webm·gif), with a TTY progress bar (muted by --silent).
• config — ~/.config/yyz/config.json (global) and yyz.config.js (project) set the output dir, etc.

Dependencies: esbuild (bundling), Deno.watchFs (the runtime's native FS watcher), png-tools (PNG DPI metadata), @napi-rs/canvas (the headless Skia canvas, loaded on demand), gifenc + mp4-muxer/webm-muxer (small pure‑JS encoders), and @texel/yyz-core. ffmpeg (mp4/webm + hi‑q gif) is found on PATH — never bundled, so it stays out of the base install.