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

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/store.d.ts

@@ -76,6 +76,11 @@ export declare class AssetShelf implements LoadedAssets {
     /** Whether the file at `path` is on the shelf. */
     has(path: string): boolean;
 }
+/** 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;
 export declare function audioOf(assets: LoadedAssets, asset: AudioAsset): PcmAudio | null;

package/dist/assets/store.js

@@ -119,10 +119,18 @@ export class AssetShelf {
         return this.held.has(path);
     }
 }
+/** 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/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,7 @@
 export { FilmRenderer, sizeAtScale, type FrameOptions, type FrameSize, type DrawnFrame, type ImageUpload } from "./render/renderer.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 { 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";

package/dist/index.js

@@ -4,7 +4,7 @@
 export { FilmRenderer, sizeAtScale } from "./render/renderer.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 { 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";