@tongue-core/engine 0.1.0-rc.1 → 0.1.0-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Backpine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -17,6 +17,23 @@ renderer.render(120, { scale: 0.5 });
 const rgba = renderer.rgba8();                                  // or yuv420(), png()
 ```
 
+**In a Cloudflare Worker**, which may not compile WebAssembly from bytes, import the raster as a
+module (`@tongue-core/engine/raster.wasm`, the same bytes as the embedded copy) and pass it in:
+
+```ts
+import { FilmRenderer, Raster } from "@tongue-core/engine";
+import raster from "@tongue-core/engine/raster.wasm";              // a WebAssembly.Module in a Worker
+
+const renderer = await FilmRenderer.create(plan, assets, await Raster.create(raster));
+```
+
+With little memory (a Worker), hold only what each frame draws: `displayList` throws `ImageNotLoaded`
+naming the image a frame needs, and `renderer.keepOnly(list)` frees the rest from the raster before
+`renderer.draw(list)`. `apps/frames-worker/src/runner.ts` does this.
+
+TypeScript needs `declare module "*.wasm" { const module: WebAssembly.Module; export default module; }`
+somewhere in the Worker's sources.
+
 - **Frames are independent.** Nothing carries over between frames except caches, so frames
   render in any order, on any number of machines.
 - **Video frames come from the host** (`FrameOptions.video`, a `VideoFrameSource`): ffmpeg on a

package/dist/assets/codecs/types.d.ts

@@ -6,6 +6,8 @@ export interface RgbaImage {
 }
 /** Planar float audio in -1..1. Every channel has the same length. */
 export interface PcmAudio {
+    /** Source sample represented by channels[0][0], for a window decoded from segmented audio. */
+    readonly offset?: number;
     readonly sampleRate: number;
     readonly channels: ReadonlyArray<Float32Array>;
 }

package/dist/assets/codecs/wav.d.ts

@@ -1,3 +1,6 @@
 import type { PcmAudio } from "./types.js";
 export declare function readWav(bytes: Uint8Array): PcmAudio;
+/** 32-bit float WAV: every sample kept exactly as it is, with no dither and no clipping. For audio
+ *  between steps (a stem on its way to a processor), where 16 bits would round it each time. */
+export declare function writeFloatWav(audio: PcmAudio): Uint8Array;
 export declare function writeWav(audio: PcmAudio, seed?: number): Uint8Array;

package/dist/assets/codecs/wav.js

@@ -96,7 +96,9 @@ function random(seed) {
         return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
     };
 }
-export function writeWav(audio, seed = 0x5eed) {
+/** A WAV header for `frames` of `channels` samples of `bits` each, in the given format; the
+ *  samples go after it, at byte 44. */
+function header(audio, format, bits) {
     const channels = audio.channels.length;
     const frames = audio.channels[0]?.length ?? 0;
     if (channels === 0)
@@ -105,21 +107,39 @@ export function writeWav(audio, seed = 0x5eed) {
         fail("channels have different lengths");
     if (!Number.isInteger(audio.sampleRate) || audio.sampleRate <= 0)
         fail(`bad sample rate ${audio.sampleRate}`);
-    const dataLength = frames * channels * 2;
+    const bytes = bits / 8;
+    const dataLength = frames * channels * bytes;
     const out = new Uint8Array(44 + dataLength);
     const view = new DataView(out.buffer);
     out.set([0x52, 0x49, 0x46, 0x46]); // RIFF
     view.setUint32(4, 36 + dataLength, true);
     out.set([0x57, 0x41, 0x56, 0x45, 0x66, 0x6d, 0x74, 0x20], 8); // WAVEfmt␠
     view.setUint32(16, 16, true);
-    view.setUint16(20, FORMAT_PCM, true);
+    view.setUint16(20, format, true);
     view.setUint16(22, channels, true);
     view.setUint32(24, audio.sampleRate, true);
-    view.setUint32(28, audio.sampleRate * channels * 2, true);
-    view.setUint16(32, channels * 2, true);
-    view.setUint16(34, 16, true);
+    view.setUint32(28, audio.sampleRate * channels * bytes, true);
+    view.setUint16(32, channels * bytes, true);
+    view.setUint16(34, bits, true);
     out.set([0x64, 0x61, 0x74, 0x61], 36); // data
     view.setUint32(40, dataLength, true);
+    return { out, view, frames };
+}
+/** 32-bit float WAV: every sample kept exactly as it is, with no dither and no clipping. For audio
+ *  between steps (a stem on its way to a processor), where 16 bits would round it each time. */
+export function writeFloatWav(audio) {
+    const { out, view, frames } = header(audio, FORMAT_FLOAT, 32);
+    let at = 44;
+    for (let f = 0; f < frames; f++) {
+        for (const channel of audio.channels) {
+            view.setFloat32(at, channel[f] ?? 0, true);
+            at += 4;
+        }
+    }
+    return out;
+}
+export function writeWav(audio, seed = 0x5eed) {
+    const { view, out, frames } = header(audio, FORMAT_PCM, 16);
     // TPDF dither: the difference of two uniform variables spans ±1 LSB with a triangular
     // distribution, which decorrelates the rounding error from the signal.
     const next = random(seed);

package/dist/assets/store.d.ts

@@ -21,6 +21,7 @@ export interface LoadedVideo {
     readonly poster: LoadedImage | null;
 }
 export interface LoadedAssets {
+    readonly audioWindow?: (name: string, fromSeconds: number, toSeconds: number) => PcmAudio | null;
     readonly fonts: FontLibrary;
     readonly images: ReadonlyMap<string, LoadedImage>;
     readonly audio: ReadonlyMap<string, PcmAudio>;
@@ -65,6 +66,9 @@ export declare function loadAssets(assets: ReadonlyArray<Asset> | undefined, fet
  *  need): the maps a renderer reads at draw time, filled as files come. Drawing a frame whose
  *  files aren't here yet throws, as with any missing asset; nothing is drawn half loaded. */
 export declare class AssetShelf implements LoadedAssets {
+    private readonly pendingPosters;
+    private readonly audioInfo;
+    private readonly audioParts;
     readonly fonts: FontLibrary;
     readonly images: Map<string, LoadedImage>;
     readonly audio: Map<string, PcmAudio>;
@@ -75,6 +79,20 @@ export declare class AssetShelf implements LoadedAssets {
     add(asset: Asset, path: string, bytes: Uint8Array, audio?: boolean): void;
     /** Whether the file at `path` is on the shelf. */
     has(path: string): boolean;
+    remove(path: string): void;
+    readonly audioWindow: (name: string, fromSeconds: number, toSeconds: number) => PcmAudio | null;
+}
+export declare function parseAudioInfo(bytes: Uint8Array): {
+    readonly sampleRate: number;
+    readonly segments: ReadonlyArray<{
+        readonly first: number;
+        readonly samples: number;
+    }>;
+};
+/** A frame needs an image that isn't here: a host loading on demand fetches `asset` and draws again. */
+export declare class ImageNotLoaded extends AssetError {
+    readonly asset: ImageAsset;
+    constructor(asset: ImageAsset);
 }
 export declare function imageOf(assets: LoadedAssets, asset: ImageAsset): LoadedImage;
 export declare function videoOf(assets: LoadedAssets, asset: VideoAsset): LoadedVideo;

package/dist/assets/store.js

@@ -82,6 +82,9 @@ export async function loadAssets(assets = declaredAssets(), fetch, options = {})
  *  need): the maps a renderer reads at draw time, filled as files come. Drawing a frame whose
  *  files aren't here yet throws, as with any missing asset; nothing is drawn half loaded. */
 export class AssetShelf {
+    pendingPosters = new Map();
+    audioInfo = new Map();
+    audioParts = new Map();
     fonts = new FontLibrary();
     images = new Map();
     audio = new Map();
@@ -97,18 +100,33 @@ export class AssetShelf {
             case "image":
                 this.images.set(asset.name, { qoi: bytes, ...qoiSize(bytes) });
                 break;
-            case "audio":
-                if (audio)
+            case "audio": {
+                if (!audio)
+                    break;
+                if (path.endsWith("/info.json"))
+                    this.audioInfo.set(asset.name, parseAudioInfo(bytes));
+                else if (path.includes(`/audio/${asset.name}/`) || path.startsWith(`audio/${asset.name}/`)) {
+                    const index = Number(/\/(\d+)\.wav$/.exec(path)?.[1]);
+                    if (!Number.isInteger(index))
+                        throw new AssetError(`Invalid audio segment ${path}.`);
+                    const parts = this.audioParts.get(asset.name) ?? new Map();
+                    parts.set(index, readWav(bytes));
+                    this.audioParts.set(asset.name, parts);
+                }
+                else
                     this.audio.set(asset.name, readWav(bytes));
                 break;
+            }
             case "video": {
                 const known = this.videos.get(asset.name);
-                if (path === videoInfoPath(asset))
-                    this.videos.set(asset.name, { info: parseVideoInfo(bytes, asset.name), poster: known?.poster ?? null });
+                if (path === videoInfoPath(asset)) {
+                    this.videos.set(asset.name, { info: parseVideoInfo(bytes, asset.name), poster: known?.poster ?? this.pendingPosters.get(asset.name) ?? null });
+                    this.pendingPosters.delete(asset.name);
+                }
                 else if (path === videoPosterPath(asset) && known)
                     this.videos.set(asset.name, { info: known.info, poster: { qoi: bytes, ...qoiSize(bytes) } });
                 else if (path === videoPosterPath(asset))
-                    throw new AssetError(`video "${asset.name}": its poster came before its info.json.`);
+                    this.pendingPosters.set(asset.name, { qoi: bytes, ...qoiSize(bytes) });
                 break;
             }
         }
@@ -118,11 +136,69 @@ export class AssetShelf {
     has(path) {
         return this.held.has(path);
     }
+    remove(path) {
+        this.held.delete(path);
+        const image = /^images\/([^/]+)\.qoi$/.exec(path)?.[1];
+        if (image !== undefined)
+            this.images.delete(image);
+        const poster = /^video\/([^/]+)\/poster\.qoi$/.exec(path)?.[1];
+        const video = poster === undefined ? undefined : this.videos.get(poster);
+        if (poster !== undefined)
+            this.pendingPosters.delete(poster);
+        if (poster !== undefined && video)
+            this.videos.set(poster, { ...video, poster: null });
+        const audio = /^audio\/([^/]+)\/(\d+)\.wav$/.exec(path);
+        if (audio?.[1] !== undefined)
+            this.audioParts.get(audio[1])?.delete(Number(audio[2]));
+    }
+    audioWindow = (name, fromSeconds, toSeconds) => {
+        const info = this.audioInfo.get(name);
+        if (!info)
+            return this.audio.get(name) ?? null;
+        const first = Math.max(0, Math.floor(fromSeconds * info.sampleRate));
+        const end = Math.ceil(toSeconds * info.sampleRate);
+        const channels = [new Float32Array(Math.max(0, end - first)), new Float32Array(Math.max(0, end - first))];
+        for (let k = 0; k < info.segments.length; k++) {
+            const segment = info.segments[k];
+            if (!segment || segment.first >= end || segment.first + segment.samples <= first)
+                continue;
+            const part = this.audioParts.get(name)?.get(k);
+            if (!part)
+                throw new AssetError(`audio "${name}": segment ${k} is not loaded.`);
+            if (part.sampleRate !== info.sampleRate || part.channels.length !== 2 || part.channels.some((channel) => channel.length !== segment.samples))
+                throw new AssetError(`audio "${name}": segment ${k} has a different rate, channel count or length from its metadata.`);
+            const a = Math.max(first, segment.first), b = Math.min(end, segment.first + segment.samples);
+            channels.forEach((channel, c) => channel.set(part.channels[c]?.subarray(a - segment.first, b - segment.first) ?? new Float32Array(b - a), a - first));
+        }
+        return { sampleRate: info.sampleRate, channels, offset: first };
+    };
+}
+export function parseAudioInfo(bytes) {
+    const value = JSON.parse(new TextDecoder().decode(bytes));
+    if (!isRecord(value) || value["sampleRate"] !== 48000 || value["channels"] !== 2 || !Array.isArray(value["segments"]))
+        throw new AssetError("Invalid segmented audio metadata.");
+    let end = 0;
+    const segments = value["segments"].map((entry) => {
+        if (!isRecord(entry) || entry["first"] !== end || typeof entry["samples"] !== "number" || !Number.isInteger(entry["samples"]) || entry["samples"] <= 0)
+            throw new AssetError("Audio segments must be contiguous and have a positive sample count.");
+        const segment = { first: end, samples: entry["samples"] };
+        end += segment.samples;
+        return segment;
+    });
+    return { sampleRate: 48000, segments };
+}
+/** A frame needs an image that isn't here: a host loading on demand fetches `asset` and draws again. */
+export class ImageNotLoaded extends AssetError {
+    asset;
+    constructor(asset) {
+        super(`Image "${asset.name}" is not loaded (was it declared with image() and imported?).`);
+        this.asset = asset;
+    }
 }
 export function imageOf(assets, asset) {
     const image = assets.images.get(asset.name);
     if (!image)
-        throw new AssetError(`Image "${asset.name}" is not loaded (was it declared with image() and imported?).`);
+        throw new ImageNotLoaded(asset);
     return image;
 }
 export function videoOf(assets, asset) {

package/dist/audio/mix.d.ts

@@ -43,4 +43,10 @@ export interface WindowInput {
 /** The part of the soundtrack between two frames: what a player mixes a few seconds at a time, so
  *  an hour-long film never needs its whole soundtrack in memory. Exactly that part of `mix`, except
  *  where a clip changes speed (time-stretching is padded, not continued from the window before). */
-export declare function mixWindow({ fps, clips, sounds, from, to }: WindowInput): PcmAudio;
+export declare function mixWindow(input: WindowInput): PcmAudio;
+/** The peak limiter the soundtrack ends with, on audio summed some other way (stems mixed
+ *  separately, then added together). Per sample, so `limitAudio(busWindow(x))` is `mixWindow(x)`. */
+export declare function limitAudio(audio: PcmAudio): PcmAudio;
+/** What `mixWindow` sums before it limits: the clips and sounds between two frames, stereo at
+ *  48 kHz, unlimited. A stem (some of a film's clips, mixed on their own) is this over those clips. */
+export declare function busWindow({ fps, clips, sounds, from, to }: WindowInput): PcmAudio;

package/dist/audio/mix.js

@@ -94,9 +94,10 @@ function channelAt(pcm, channel, fromSeconds, length) {
         return out;
     const ratio = pcm.sampleRate / SAMPLE_RATE;
     const offset = fromSeconds * pcm.sampleRate;
+    const windowOffset = pcm.offset ?? 0;
     for (let i = 0; i < length; i++) {
         const pos = offset + i * ratio;
-        const j = Math.floor(pos), f = pos - j;
+        const index = Math.floor(pos), j = index - windowOffset, f = pos - index;
         out[i] = (src[j] ?? 0) * (1 - f) + (src[j + 1] ?? 0) * f;
     }
     return out;
@@ -216,7 +217,17 @@ const STRETCH_PAD = 4 * WINDOW;
 /** The part of the soundtrack between two frames: what a player mixes a few seconds at a time, so
  *  an hour-long film never needs its whole soundtrack in memory. Exactly that part of `mix`, except
  *  where a clip changes speed (time-stretching is padded, not continued from the window before). */
-export function mixWindow({ fps, clips, sounds, from, to }) {
+export function mixWindow(input) {
+    return limitAudio(busWindow(input));
+}
+/** The peak limiter the soundtrack ends with, on audio summed some other way (stems mixed
+ *  separately, then added together). Per sample, so `limitAudio(busWindow(x))` is `mixWindow(x)`. */
+export function limitAudio(audio) {
+    return { sampleRate: audio.sampleRate, channels: audio.channels.map(limit) };
+}
+/** What `mixWindow` sums before it limits: the clips and sounds between two frames, stereo at
+ *  48 kHz, unlimited. A stem (some of a film's clips, mixed on their own) is this over those clips. */
+export function busWindow({ fps, clips, sounds, from, to }) {
     const start = Math.round((from / fps) * SAMPLE_RATE);
     const length = Math.max(0, Math.ceil((to / fps) * SAMPLE_RATE) - start);
     const left = new Float32Array(length), right = new Float32Array(length);
@@ -242,5 +253,5 @@ export function mixWindow({ fps, clips, sounds, from, to }) {
         add(left, sound, at, gain);
         add(right, sound, at, gain);
     }
-    return { sampleRate: SAMPLE_RATE, channels: [limit(left), limit(right)] };
+    return { sampleRate: SAMPLE_RATE, channels: [left, right] };
 }

package/dist/evaluate/evaluate.js

@@ -1,4 +1,4 @@
-import { composePose, easeOf, enterPose, enterSpec, exitLength, exitPose, exitSpec, flatten, frameOf, isAt, isImageAsset, isVideoAsset, keysOf, rest, timeAt, withTime, } from "@tongue-core/film/model";
+import { composePose, easeOf, enterPose, enterSpec, exitLength, exitPose, exitSpec, flatten, frameOf, isAt, isImageAsset, isVideoAsset, keysOf, node, rest, timeAt, withTime, } from "@tongue-core/film/model";
 import { schedule, typedAt } from "./typing.js";
 import { parseColor, StyleError } from "../style/parse.js";
 import { computeStyle, defaults, overrideOf, recordOf, rootText, textStyleOf } from "../style/resolve.js";
@@ -25,6 +25,7 @@ export function evaluate(content, frame, env) {
 class Evaluator {
     frame;
     env;
+    parent;
     camera = null;
     pointer = null;
     sounds = [];
@@ -33,14 +34,23 @@ class Evaluator {
     keyStack = [];
     /** Where each narration's word matching has got to (Says match words in order). */
     sayCursors = new Map();
-    constructor(frame, env) {
+    /** Set for one of MotionBlur's samples: it is a moment between frames, not the frame. */
+    sampling;
+    /** `parent`: the evaluator a MotionBlur sample passes its sounds to; `null` drops them. */
+    constructor(frame, env, parent = undefined) {
         this.frame = frame;
         this.env = env;
+        this.parent = parent;
+        this.sampling = parent !== undefined;
     }
     controls() {
         return { camera: this.camera, pointer: this.pointer, sounds: this.sounds, switches: this.switches };
     }
     sound(kind, at) {
+        if (this.sampling) {
+            this.parent?.sound(kind, at);
+            return;
+        }
         if (at >= this.frame && at < this.frame + this.env.soundWindow)
             this.sounds.push({ kind, at });
     }
@@ -78,6 +88,8 @@ class Evaluator {
             case "element": return this.element(c.tag, c.props, c.children, ctx);
             case "show": return this.show(c, ctx);
             case "camera": {
+                if (this.sampling)
+                    throw new EvalError("<Camera> can't go inside <MotionBlur>: put the MotionBlur inside the camera's world.");
                 this.camera = { node: c, shots: nodesOf(c.children).flatMap((s) => (s.kind === "shot" ? [s] : [])) };
                 return [];
             }
@@ -91,6 +103,8 @@ class Evaluator {
                 return [{ kind: "box", box: { ...this.stageBox(c.style, kids, ctx.text), pose: ctx.pose } }];
             }
             case "center": return this.center(c.style, c.children, ctx);
+            case "mask": return this.mask(c, ctx);
+            case "motion-blur": return this.motionBlur(c, ctx);
             case "shot":
             case "move":
             case "click": return [];
@@ -104,7 +118,8 @@ class Evaluator {
     element(tag, props, children, ctx) {
         const styleRecord = recordOf(props["style"], `<${tag}> style`);
         const id = typeof props["id"] === "string" ? props["id"] : null;
-        const morph = typeof props["morph"] === "string" ? props["morph"] : null;
+        // Every sample would hold the same key, and a key means one element. Inside a blur there is none.
+        const morph = !this.sampling && typeof props["morph"] === "string" ? props["morph"] : null;
         this.noteKey(morph);
         const style = computeStyle(styleRecord, ctx.text, tag);
         if (style.display === "none")
@@ -129,7 +144,7 @@ class Evaluator {
         }
         const hovered = overrideOf(props["hovered"], `<${tag}> hovered`);
         const pressed = overrideOf(props["pressed"], `<${tag}> pressed`);
-        const shell = { tag, id, morph, style, hovered, pressed, pose: ctx.pose, screen: false, grow: ctx.grow };
+        const shell = { tag, id, morph, style, hovered, pressed, pose: ctx.pose, screen: false, grow: ctx.grow, corners: cornersOf(props["corners"], style, tag) };
         if (tag === "img") {
             const src = props["src"];
             if (!isImageAsset(src))
@@ -145,10 +160,7 @@ class Evaluator {
             const paths = flatten(children).flatMap((k) => {
                 if (typeof k === "string" || k.kind !== "element" || k.tag !== "path")
                     return [];
-                const d = k.props["d"], fill = k.props["fill"], rule = k.props["fillRule"];
-                if (typeof d !== "string")
-                    throw new StyleError("<path> needs d.");
-                return [{ verbs: parsePath(d), fill: typeof fill === "string" ? parseColor(fill) : style.text.color, rule: rule === "evenodd" ? "evenodd" : "nonzero" }];
+                return [pathOf(k.props, style.text)];
             });
             return [{ kind: "box", box: { ...shell, content: { kind: "svg", view: parseViewBox(view), paths } } }];
         }
@@ -158,6 +170,8 @@ class Evaluator {
     /** The frame a <video> shows now: playback starts at `start` (scene frames) and runs through
      *  the file from `in` to `out` at `speed`, optionally reversed, looped or frozen. */
     videoPicture(props) {
+        if (this.sampling)
+            throw new EvalError("<video> can't go inside <MotionBlur>: footage has its own blur. Put it beside the MotionBlur.");
         const src = props["src"];
         if (!isVideoAsset(src))
             throw new EvalError("<video> needs src={a video asset}.");
@@ -253,6 +267,8 @@ class Evaluator {
         return out;
     }
     pointerNode(p) {
+        if (this.sampling)
+            throw new EvalError("<Pointer> can't go inside <MotionBlur>: it belongs to the scene.");
         const steps = nodesOf(p.steps);
         const moves = steps.flatMap((s) => (s.kind === "move" ? [s] : []));
         const clicks = steps.flatMap((s) => (s.kind === "click" ? [s] : []));
@@ -340,10 +356,52 @@ class Evaluator {
         const from = f.from === null ? -Infinity : frameOf(f.from);
         if (this.frame < from)
             return [];
-        this.noteKey(f.morph);
+        const morph = this.sampling ? null : f.morph;
+        this.noteKey(morph);
         const pose = composePose(ctx.pose, enterPose(enterSpec(f.enter), this.frame - from, this.env.fps));
         const style = computeStyle({ position: "absolute", inset: 0, background: f.color }, ctx.text, "div");
-        return [{ kind: "box", box: { tag: "fill", id: null, morph: f.morph, hovered: null, pressed: null, pose, screen: true, grow: 1, style, content: { kind: "boxes", children: [] } } }];
+        return [{ kind: "box", box: { tag: "fill", id: null, morph, hovered: null, pressed: null, pose, screen: true, grow: 1, style, content: { kind: "boxes", children: [] } } }];
+    }
+    mask(m, ctx) {
+        const style = computeStyle({ position: "absolute", inset: 0, ...m.style }, ctx.text, "div");
+        const inner = { text: style.text, pose: rest, grow: 1 };
+        const part = (content, tag) => ({
+            tag, id: null, morph: null, hovered: null, pressed: null, pose: rest, screen: false, grow: 1,
+            style: computeStyle({ position: "absolute", inset: 0, display: "stack" }, style.text, "div"),
+            content: { kind: "boxes", children: this.asBoxes(this.children(content, inner), style.text) },
+        });
+        const box = {
+            tag: "mask", id: null, morph: null, hovered: null, pressed: null, pose: ctx.pose, screen: false, grow: ctx.grow, style,
+            content: { kind: "boxes", children: [part(m.children, "mask-content"), part([m.by], "mask-shape")] },
+            group: { kind: "mask", invert: m.invert },
+        };
+        return [{ kind: "box", box }];
+    }
+    /** The same content at several moments around this frame, centered on it. Each sample has its own
+     *  evaluator at its own time. Only the middle one's sounds count: the rest are the same sounds. */
+    motionBlur(n, ctx) {
+        if (!(n.shutter >= 0 && n.shutter <= 720))
+            throw new EvalError(`<MotionBlur> shutter: expected 0 to 720 degrees, got ${n.shutter}.`);
+        if (!Number.isInteger(n.samples) || n.samples < 2 || n.samples > 64)
+            throw new EvalError(`<MotionBlur> samples: expected a whole number from 2 to 64, got ${n.samples}.`);
+        const style = computeStyle({ position: "absolute", inset: 0, ...n.style }, ctx.text, "div");
+        const inner = { text: style.text, pose: rest, grow: 1 };
+        const open = n.shutter / 360;
+        const children = Array.from({ length: n.samples }, (_, i) => {
+            const at = this.frame + (i / (n.samples - 1) - 0.5) * open;
+            const ev = new Evaluator(at, this.env, i === n.samples >> 1 ? this : null);
+            const items = withTime(timeAt(at, this.env.fps), () => ev.children([node({ kind: "component", name: "MotionBlur", render: n.render })], inner));
+            return {
+                tag: "motion-sample", id: null, morph: null, hovered: null, pressed: null, pose: rest, screen: false, grow: 1,
+                style: computeStyle({ position: "absolute", inset: 0, display: "stack" }, style.text, "div"),
+                content: { kind: "boxes", children: ev.asBoxes(items, style.text) },
+            };
+        });
+        const box = {
+            tag: "motion-blur", id: null, morph: null, hovered: null, pressed: null, pose: ctx.pose, screen: false, grow: ctx.grow, style,
+            content: { kind: "boxes", children }, group: { kind: "samples" },
+        };
+        return [{ kind: "box", box }];
     }
     center(styleRecord, children, ctx) {
         const style = computeStyle(styleRecord, ctx.text, "div");
@@ -361,6 +419,61 @@ class Evaluator {
     }
 }
 const rootTextFallback = rootText;
+const point = (v) => Array.isArray(v) && v.length === 2 && typeof v[0] === "number" && Number.isFinite(v[0]) && typeof v[1] === "number" && Number.isFinite(v[1]) ? [v[0], v[1]] : null;
+function cornersOf(v, style, tag) {
+    if (v === undefined)
+        return undefined;
+    const list = Array.isArray(v) ? v : [];
+    const [a, b, c, d] = list.map(point);
+    if (list.length !== 4 || !a || !b || !c || !d)
+        throw new StyleError(`<${tag}> corners: expected four [x, y] points, top left, top right, bottom right, bottom left; got ${JSON.stringify(v)}.`);
+    if (style.transform.turn !== 0 || style.transform.tilt !== 0)
+        throw new StyleError(`<${tag}> has corners and turn or tilt: corners already say where it lands, so remove turn and tilt.`);
+    return [a, b, c, d];
+}
+const CAPS = ["butt", "round", "square"];
+const JOINS = ["miter", "round", "bevel"];
+function oneOf(v, options, fallback, what) {
+    if (v === undefined)
+        return fallback;
+    const found = options.find((o) => o === v);
+    if (found === undefined)
+        throw new StyleError(`<path> ${what}: expected one of ${options.join(", ")}, got ${JSON.stringify(v)}.`);
+    return found;
+}
+function trimOf(v) {
+    if (v === undefined)
+        return [0, 1];
+    if (typeof v === "number" && Number.isFinite(v))
+        return [0, v];
+    if (Array.isArray(v) && v.length === 2 && typeof v[0] === "number" && Number.isFinite(v[0]) && typeof v[1] === "number" && Number.isFinite(v[1]))
+        return [v[0], v[1]];
+    throw new StyleError(`<path> trim: expected a fraction or [from, to], got ${JSON.stringify(v)}.`);
+}
+/** One `<path>`, its props read once. Paths aren't styled elements, so this is their boundary. */
+function pathOf(props, text) {
+    const d = props["d"], fill = props["fill"], rule = props["fillRule"], stroke = props["stroke"], width = props["strokeWidth"];
+    if (typeof d !== "string")
+        throw new StyleError("<path> needs d.");
+    if (stroke !== undefined && typeof stroke !== "string")
+        throw new StyleError("<path> stroke: expected a color.");
+    if (width !== undefined && (typeof width !== "number" || !Number.isFinite(width) || width < 0))
+        throw new StyleError(`<path> strokeWidth: expected a number of at least 0, got ${JSON.stringify(width)}.`);
+    if (props["trim"] !== undefined && stroke === undefined)
+        throw new StyleError("<path> trim needs a stroke: it says how much of the outline to draw.");
+    return {
+        verbs: parsePath(d),
+        fill: fill === "none" ? null : typeof fill === "string" ? parseColor(fill) : stroke === undefined ? text.color : null,
+        rule: rule === "evenodd" ? "evenodd" : "nonzero",
+        stroke: stroke === undefined ? null : {
+            color: parseColor(stroke),
+            width: width ?? 1,
+            cap: oneOf(props["strokeCap"], CAPS, "butt", "strokeCap"),
+            join: oneOf(props["strokeJoin"], JOINS, "miter", "strokeJoin"),
+            trim: trimOf(props["trim"]),
+        },
+    };
+}
 function textOf(n) {
     switch (n.kind) {
         case "element":

package/dist/evaluate/tree.d.ts

@@ -1,6 +1,7 @@
 import type { FullPose, ImageAsset, VideoAsset } from "@tongue-core/film/model";
 import type { PathVerb } from "../text/font-types.js";
 import type { Color, Computed, Override, TextStyle } from "../style/computed.js";
+import type { StrokeCap, StrokeJoin } from "../paint/stroke.js";
 export interface Owner {
     readonly id: string | null;
     readonly morph: string | null;
@@ -21,10 +22,19 @@ export interface SayState {
     /** Pose of each word, in order; words past the end of the list are at rest. */
     readonly words: ReadonlyArray<FullPose>;
 }
+export interface SvgStroke {
+    readonly color: Color;
+    readonly width: number;
+    readonly cap: StrokeCap;
+    readonly join: StrokeJoin;
+    /** The stretch of the outline to draw, as fractions of its length. */
+    readonly trim: readonly [number, number];
+}
 export interface SvgPath {
     readonly verbs: ReadonlyArray<PathVerb>;
-    readonly fill: Color;
+    readonly fill: Color | null;
     readonly rule: "nonzero" | "evenodd";
+    readonly stroke: SvgStroke | null;
 }
 /** What an image box shows: a photo, or one frame of a video. */
 export type Picture = {
@@ -68,4 +78,17 @@ export interface Box {
     /** Fraction of its laid-out height the box takes (Show `expand`); below 1 it clips. */
     readonly grow: number;
     readonly content: Content;
+    /** Drawn onto this four-sided shape, in its parent's coordinates. */
+    readonly corners?: Quad;
+    /** Paints its children as a group instead of one after another. */
+    readonly group?: BoxGroup;
 }
+export type Quad = readonly [readonly [number, number], readonly [number, number], readonly [number, number], readonly [number, number]];
+export type BoxGroup = {
+    readonly kind: "mask";
+    readonly invert: boolean;
+}
+/** Motion blur: its children are the same content at different moments, averaged. */
+ | {
+    readonly kind: "samples";
+};

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-export { FilmRenderer, sizeAtScale, type FrameOptions, type FrameSize, type DrawnFrame, type ImageUpload } from "./render/renderer.js";
+export { FilmRenderer, type FrameOptions, type DrawnFrame, type ImageUpload } from "./render/renderer.js";
+export { sizeAtScale, type FrameSize } from "./render/size.js";
 export { collectSounds, audioClips } from "./render/sounds.js";
-export { mix, mixWindow, SAMPLE_RATE, SOUND_SECONDS, type MixInput, type WindowInput, type ClipAudio } from "./audio/mix.js";
-export { loadAssets, AssetShelf, imageOf, videoOf, audioOf, parseVideoInfo, parseProxyInfo, qoiSize, imageSize, AssetError, type LoadedAssets, type LoadedImage, type LoadedVideo, type VideoInfo, type ProxyInfo, type Fetcher, type LoadOptions } from "./assets/store.js";
+export { mix, mixWindow, busWindow, limitAudio, SAMPLE_RATE, SOUND_SECONDS, type MixInput, type WindowInput, type ClipAudio } from "./audio/mix.js";
+export { loadAssets, AssetShelf, ImageNotLoaded, imageOf, videoOf, audioOf, parseVideoInfo, parseProxyInfo, qoiSize, imageSize, AssetError, type LoadedAssets, type LoadedImage, type LoadedVideo, type VideoInfo, type ProxyInfo, type Fetcher, type LoadOptions } from "./assets/store.js";
 export { importedPath, importedFiles, videoInfoPath, videoPosterPath, videoProxyDir, videoProxyPath, PROXY_SEGMENT_SECONDS, PROXY_KEYFRAME_SECONDS, type AssetKey } from "./assets/paths.js";
 export { demuxMp4, sampleData, Mp4Error, type Mp4Video, type Mp4Sample } from "./media/mp4.js";
 export { yuvToRgba, yuvSize, packedPlanes, encodeYuvImage, isYuvImage, yuvImageSize, yuvImageLayout, writeYuvHeader, YUV_HEADER, type YuvFrame, type YuvFormat, type YuvPlane } from "./media/yuv.js";
@@ -15,7 +16,7 @@ export { decodePng } from "./assets/codecs/png.js";
 export { decodeJpeg } from "./assets/codecs/jpeg.js";
 export { encodeQoi, decodeQoi } from "./assets/codecs/qoi.js";
 export { resizeImage } from "./assets/codecs/resize.js";
-export { readWav, writeWav } from "./assets/codecs/wav.js";
+export { readWav, writeWav, writeFloatWav } from "./assets/codecs/wav.js";
 export { woff2ToSfnt } from "./text/woff2.js";
 export { parseFont } from "./text/ttf.js";
 export type { RgbaImage, PcmAudio } from "./assets/codecs/types.js";

package/dist/index.js

@@ -1,10 +1,11 @@
 // @tongue-core/engine: turns a planned film (from @tongue-core/film) into pixels and sound. Evaluate →
 // layout → paint → rasterize, deterministic and plain TypeScript (plus an embedded WebAssembly
 // raster), so the same frame is byte-identical in Bun, browsers and Workers.
-export { FilmRenderer, sizeAtScale } from "./render/renderer.js";
+export { FilmRenderer } from "./render/renderer.js";
+export { sizeAtScale } from "./render/size.js";
 export { collectSounds, audioClips } from "./render/sounds.js";
-export { mix, mixWindow, SAMPLE_RATE, SOUND_SECONDS } from "./audio/mix.js";
-export { loadAssets, AssetShelf, imageOf, videoOf, audioOf, parseVideoInfo, parseProxyInfo, qoiSize, imageSize, AssetError } from "./assets/store.js";
+export { mix, mixWindow, busWindow, limitAudio, SAMPLE_RATE, SOUND_SECONDS } from "./audio/mix.js";
+export { loadAssets, AssetShelf, ImageNotLoaded, imageOf, videoOf, audioOf, parseVideoInfo, parseProxyInfo, qoiSize, imageSize, AssetError } from "./assets/store.js";
 export { importedPath, importedFiles, videoInfoPath, videoPosterPath, videoProxyDir, videoProxyPath, PROXY_SEGMENT_SECONDS, PROXY_KEYFRAME_SECONDS } from "./assets/paths.js";
 export { demuxMp4, sampleData, Mp4Error } from "./media/mp4.js";
 export { yuvToRgba, yuvSize, packedPlanes, encodeYuvImage, isYuvImage, yuvImageSize, yuvImageLayout, writeYuvHeader, YUV_HEADER } from "./media/yuv.js";
@@ -16,6 +17,6 @@ export { decodePng } from "./assets/codecs/png.js";
 export { decodeJpeg } from "./assets/codecs/jpeg.js";
 export { encodeQoi, decodeQoi } from "./assets/codecs/qoi.js";
 export { resizeImage } from "./assets/codecs/resize.js";
-export { readWav, writeWav } from "./assets/codecs/wav.js";
+export { readWav, writeWav, writeFloatWav } from "./assets/codecs/wav.js";
 export { woff2ToSfnt } from "./text/woff2.js";
 export { parseFont } from "./text/ttf.js";