@texel/yyz-core

@texel/yyz-core

The agnostic engine behind yyz — zero runtime dependencies, plain modern ESM JavaScript (types via JSDoc‑generated .d.ts).

It owns the sketch lifecycle, the timeline/sizing/filename/params math, and the Host / Surface / Sink seams. It never touches window / document / Deno / node: — every platform interaction is injected.

Entries

• @texel/yyz-core — createSketch(module, host, runtime?), the pure helpers (createTimeline, computeSize, resolveFilename, convertDistance, resolveParams, logParams, resolveEncoder, …), the seam types, the headless default Host, and create2dSurface / webgpuSurface (shared by every platform).
• @texel/yyz-core/web — the browser Host (rAF, devicePixelRatio, viewport fit, keyboard shortcuts, download sink) plus the browser 2d/webgpu surface resolver.

Authoring a sketch

A sketch module exports a sketch factory and (optionally) a settings object:

export const settings = { dimensions: [1080, 1080], animate: true, duration: 4 };

export function sketch(props) {
  // setup runs once; closure-held state lives here
  return ({ context, width, height, playhead }) => {
    context.fillStyle = "#111";
    context.fillRect(0, 0, width, height);
    context.fillStyle = "#e54";
    context.beginPath();
    context.arc(
      width / 2,
      height / 2,
      width * 0.2 * (1 + Math.sin(playhead * 2 * Math.PI)),
      0,
      Math.PI * 2,
    );
    context.fill();
  };
}

The factory may return a render function, a hooks object ({ tick, render, resize, begin, end, export, teardown }), or nothing (a static one‑shot). tick advances state once per frame; render draws (and may run more than once per frame — resize, export, multi‑resolution). Render is sync by default; return a Promise to opt into async/incremental rendering (props.progress() for sub‑progress, props.raf() to yield portably, props.signal to cancel).

The usual entry is the CLI. To run standalone (no CLI), wire the host yourself:

import { createSketch } from "@texel/yyz-core";
import { browserHost } from "@texel/yyz-core/web";
import * as mod from "./sketch.js";

// boots, renders frame 0, and auto-plays when settings.animate; returns the live instance
const m = await createSketch(mod, browserHost(document.body));

Surfaces & export

settings.surface: "2d" (default) · "webgpu" · "svg" (a presented SVG surface — the browser host mounts a live <svg> as props.svg and mirrors returned markup on screen; degrades to data‑only off the DOM, e.g. Deno) · "none" / false (data‑only, e.g. SVG/JSON/gcode) · or a custom resolver. Exports are return‑value driven: return nothing for the default image, or { data, ext } (one or many) for arbitrary files.

A presenting surface may expose an optional present(result) seam: the engine calls it after each render with the latest return value so the surface can display it (the "svg" surface uses this for its text mode). It's display‑only and never affects export.

The Sink seam is a streaming frame consumer (begin → write → end): a per‑frame file sequence, or an encoder that finalizes one file (GIF via gifenc, mp4/webm via ffmpeg or WebCodecs). resolveEncoder(format, encoder, capabilities) picks the right one per environment, so --format=mp4 targets ffmpeg on the CLI and WebCodecs in the browser.

Status: v0 — canvas2d + webgpu + data surfaces all work; webgl is a possible future surface.