@tongue-core/engine 0.1.0-rc.2 → 0.1.0-rc.4

package/README.md

@@ -27,6 +27,10 @@ import raster from "@tongue-core/engine/raster.wasm";              // a WebAssem
 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.
 

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";

package/dist/layout/layout.js

@@ -8,6 +8,8 @@ const hExtra = (b) => b.style.padding[1] + b.style.padding[3] + b.style.border[1
 const vExtra = (b) => b.style.padding[0] + b.style.padding[2] + b.style.border[0].width + b.style.border[2].width;
 const clampTo = (v, min, max) => Math.max(min ?? -Infinity, Math.min(max ?? Infinity, v));
 // A grid with no column template is one flexible column.
+/** Slack for fitting a line: widths from percentages add up to a hair over the room they were cut from. */
+const FITS_WITHIN = 1e-6;
 const oneColumn = [{ kind: "fr", v: 1 }];
 const inFlow = (b) => b.style.display !== "none" && b.style.position !== "absolute";
 export function layout(root, width, height, env) {
@@ -31,11 +33,14 @@ class Engine {
             text: n.paragraph ? { paragraph: n.paragraph, x: x + n.textX, y: y + n.textY } : null,
         };
     }
-    fontFor(box, weight, size) {
-        const font = box.style.text.font;
-        if (!font)
+    fontFor(box, style) {
+        const family = style.font;
+        if (!family)
             throw new LayoutError(`<${box.tag}> has text but no fontFamily (set one on the Stage or an ancestor).`);
-        return this.env.fonts.resolve(font, weight, size);
+        const file = style.italic ? family.italic : family;
+        if (!file)
+            throw new LayoutError(`<${box.tag}> is italic, but font "${family.name}" has no italic file: declare it with font("${family.source}", { italic: "…" }).`);
+        return this.env.fonts.resolve(file, style.fontWeight, style.fontSize, style.axes);
     }
     runs(box) {
         if (box.content.kind !== "text")
@@ -43,7 +48,7 @@ class Engine {
         return box.content.runs.map((r) => ({
             text: r.text,
             style: r.style,
-            font: this.fontFor(box, r.style.fontWeight, r.style.fontSize),
+            font: this.fontFor(box, r.style),
             owner: r.owner,
             visible: r.visible,
         }));
@@ -55,7 +60,7 @@ class Engine {
             align: t.textAlign,
             whiteSpace: t.whiteSpace,
             ellipsis: box.style.textOverflow === "ellipsis" && box.style.overflowHidden,
-            strut: box.style.text.font ? { style: t, font: this.fontFor(box, t.fontWeight, t.fontSize) } : null,
+            strut: box.style.text.font ? { style: t, font: this.fontFor(box, t) } : null,
         });
     }
     natural(box) {
@@ -121,7 +126,8 @@ class Engine {
         else {
             const kids = box.content.children.filter(inFlow);
             const outer = (k) => this.minContent(k) + marginOf(k.style.margin[1], 0) + marginOf(k.style.margin[3], 0);
-            if (s.display === "flex" && s.direction === "row")
+            // A row that wraps can narrow until each item has a line of its own.
+            if (s.display === "flex" && s.direction === "row" && !s.wrap)
                 w = kids.reduce((sum, k) => sum + outer(k), 0) + s.columnGap * Math.max(0, kids.length - 1);
             else if (s.display === "grid")
                 w = this.gridIntrinsic(box, kids, (k) => this.minContent(k));
@@ -353,8 +359,11 @@ class Engine {
         const s = box.style;
         const row = s.direction === "row";
         const gap = row ? s.columnGap : s.rowGap;
+        const crossGap = row ? s.rowGap : s.columnGap;
         const mainAvail = row ? innerW : innerH;
         const crossAvail = row ? innerH : innerW;
+        // A column with no height has nothing to wrap against: everything fits.
+        const wraps = s.wrap && mainAvail !== null;
         const alignOf = (k) => (k.style.alignSelf === "auto" ? s.align : k.style.alignSelf);
         const items = kids.map((k) => {
             const ks = k.style;
@@ -367,7 +376,8 @@ class Engine {
             const crossFor = () => {
                 if (row)
                     return 0;
-                const stretch = alignOf(k) === "stretch" && ks.width.kind === "auto";
+                // Wrapped columns are as wide as their widest item, so an item can't fill one yet.
+                const stretch = !wraps && alignOf(k) === "stretch" && ks.width.kind === "auto";
                 return stretch ? Math.max(0, innerW - crossMargin) : this.widthIn(k, innerW, "fit");
             };
             let basis = px(ks.basis, mainAvail) ?? specifiedMain;
@@ -383,83 +393,121 @@ class Engine {
             const autoMin = minMain ?? (ks.overflowHidden ? 0 : row ? this.minContent(k) : 0);
             return { box: k, basis, hyp: clampTo(basis, autoMin, maxMain), minMain: autoMin, maxMain, mainMargin, crossMargin, m, crossFor };
         });
-        const totalGap = gap * Math.max(0, items.length - 1);
-        const sizes = items.map((i) => i.hyp);
-        if (mainAvail !== null) {
-            const free = mainAvail - totalGap - items.reduce((sum, i, n) => sum + (sizes[n] ?? 0) + i.mainMargin, 0);
-            const growTotal = items.reduce((sum, i) => sum + i.box.style.grow, 0);
-            const shrinkTotal = items.reduce((sum, i) => sum + i.box.style.shrink * i.basis, 0);
-            if (free > 0 && growTotal > 0)
-                items.forEach((i, n) => { sizes[n] = clampTo((sizes[n] ?? 0) + (free * i.box.style.grow) / growTotal, i.minMain, i.maxMain); });
-            else if (free < 0 && shrinkTotal > 0)
-                items.forEach((i, n) => { sizes[n] = clampTo((sizes[n] ?? 0) + (free * i.box.style.shrink * i.basis) / shrinkTotal, i.minMain, i.maxMain); });
-        }
-        // Lay out each item at its main size to learn its cross size.
-        const first = items.map((i, n) => {
-            const main = sizes[n] ?? 0;
-            if (row)
-                return this.layout(i.box, { width: innerW, height: innerH }, { w: main });
-            return this.layout(i.box, { width: innerW, height: innerH }, { w: i.crossFor(), h: main });
+        // Each line sizes its own items along the main axis, then lays them out to learn its cross size.
+        const lines = (s.wrap && mainAvail !== null ? breakLines(items, mainAvail, gap) : [items]).map((line) => {
+            const totalGap = gap * Math.max(0, line.length - 1);
+            const sizes = line.map((i) => i.hyp);
+            if (mainAvail !== null) {
+                const free = mainAvail - totalGap - line.reduce((sum, i, n) => sum + (sizes[n] ?? 0) + i.mainMargin, 0);
+                const growTotal = line.reduce((sum, i) => sum + i.box.style.grow, 0);
+                const shrinkTotal = line.reduce((sum, i) => sum + i.box.style.shrink * i.basis, 0);
+                if (free > 0 && growTotal > 0)
+                    line.forEach((i, n) => { sizes[n] = clampTo((sizes[n] ?? 0) + (free * i.box.style.grow) / growTotal, i.minMain, i.maxMain); });
+                else if (free < 0 && shrinkTotal > 0)
+                    line.forEach((i, n) => { sizes[n] = clampTo((sizes[n] ?? 0) + (free * i.box.style.shrink * i.basis) / shrinkTotal, i.minMain, i.maxMain); });
+            }
+            const first = line.map((i, n) => {
+                const main = sizes[n] ?? 0;
+                if (row)
+                    return this.layout(i.box, { width: innerW, height: innerH }, { w: main });
+                return this.layout(i.box, { width: innerW, height: innerH }, { w: i.crossFor(), h: main });
+            });
+            const natural = first.reduce((mx, node, n) => Math.max(mx, (row ? node.h : node.w) + (line[n]?.crossMargin ?? 0)), 0);
+            return { items: line, first, totalGap, natural };
         });
-        const crossSize = crossAvail ?? first.reduce((mx, node, n) => Math.max(mx, (row ? node.h : node.w) + (items[n]?.crossMargin ?? 0)), 0);
-        const nodes = items.map((i, n) => {
-            const node = first[n];
-            if (!node)
-                throw new LayoutError("flex item missing");
-            const stretch = alignOf(i.box) === "stretch" && (row ? i.box.style.height.kind === "auto" : i.box.style.width.kind === "auto");
-            if (!stretch)
+        // A line that can't wrap fills the box. Wrapped lines take their tallest item, then share what
+        // is left of a definite size equally (CSS's align-content: stretch, the default).
+        const naturalTotal = lines.reduce((sum, l) => sum + l.natural, 0) + crossGap * Math.max(0, lines.length - 1);
+        const share = wraps && crossAvail !== null && lines.length > 0 ? Math.max(0, crossAvail - naturalTotal) / lines.length : 0;
+        const crossSizes = lines.map((l) => (wraps ? l.natural + share : crossAvail ?? l.natural));
+        const placed = [];
+        let lineStart = 0, mainEnd = 0;
+        lines.forEach((line, lineIndex) => {
+            const crossSize = crossSizes[lineIndex] ?? 0;
+            const nodes = line.items.map((i, n) => {
+                const node = line.first[n];
+                if (!node)
+                    throw new LayoutError("flex item missing");
+                const stretch = alignOf(i.box) === "stretch" && (row ? i.box.style.height.kind === "auto" : i.box.style.width.kind === "auto");
+                if (!stretch)
+                    return node;
+                const target = Math.max(0, crossSize - i.crossMargin);
+                if (row && node.h !== target)
+                    return this.layout(i.box, { width: innerW, height: target }, { w: node.w, h: target });
+                if (!row && node.w !== target)
+                    return this.layout(i.box, { width: innerW, height: innerH }, { w: target, h: node.h });
                 return node;
-            const target = Math.max(0, crossSize - i.crossMargin);
-            if (row && node.h !== target)
-                return this.layout(i.box, { width: innerW, height: target }, { w: node.w, h: target });
-            return node;
-        });
-        const used = nodes.reduce((sum, node, n) => sum + (row ? node.w : node.h) + (items[n]?.mainMargin ?? 0), 0) + totalGap;
-        const space = mainAvail === null ? 0 : mainAvail - used;
-        const autoMargins = items.reduce((c, i) => c + (row ? [i.box.style.margin[1], i.box.style.margin[3]] : [i.box.style.margin[0], i.box.style.margin[2]]).filter((d) => d.kind === "auto").length, 0);
-        let pos = 0, between = gap;
-        if (autoMargins === 0 && space > 0) {
-            const count = items.length;
-            if (s.justify === "center")
-                pos = space / 2;
-            else if (s.justify === "end")
-                pos = space;
-            else if (s.justify === "space-between" && count > 1)
-                between = gap + space / (count - 1);
-            else if (s.justify === "space-around" && count > 0) {
-                pos = space / count / 2;
-                between = gap + space / count;
-            }
-            else if (s.justify === "space-evenly" && count > 0) {
-                pos = space / (count + 1);
-                between = gap + space / (count + 1);
-            }
-        }
-        const perAuto = autoMargins > 0 && space > 0 ? space / autoMargins : 0;
-        nodes.forEach((node, n) => {
-            const i = items[n];
-            if (!i)
-                return;
-            const ms = i.box.style.margin;
-            const [before, after] = row ? [ms[3], ms[1]] : [ms[0], ms[2]];
-            const lead = (row ? (i.m[3] ?? 0) : (i.m[0] ?? 0)) + (before.kind === "auto" ? perAuto : 0);
-            const trail = (row ? (i.m[1] ?? 0) : (i.m[2] ?? 0)) + (after.kind === "auto" ? perAuto : 0);
-            const main = row ? node.w : node.h;
-            const cross = row ? node.h : node.w;
-            const crossLead = row ? (i.m[0] ?? 0) : (i.m[3] ?? 0);
-            const a = alignOf(i.box);
-            const crossOffset = a === "center" ? (crossSize - cross - i.crossMargin) / 2 : a === "end" ? crossSize - cross - i.crossMargin : 0;
-            if (row) {
-                node.x = left + pos + lead;
-                node.y = top + crossLead + crossOffset;
-            }
-            else {
-                node.y = top + pos + lead;
-                node.x = left + crossLead + crossOffset;
+            });
+            const used = nodes.reduce((sum, node, n) => sum + (row ? node.w : node.h) + (line.items[n]?.mainMargin ?? 0), 0) + line.totalGap;
+            const space = mainAvail === null ? 0 : mainAvail - used;
+            const autoMargins = line.items.reduce((c, i) => c + (row ? [i.box.style.margin[1], i.box.style.margin[3]] : [i.box.style.margin[0], i.box.style.margin[2]]).filter((d) => d.kind === "auto").length, 0);
+            let pos = 0, between = gap;
+            if (autoMargins === 0 && space > 0) {
+                const count = line.items.length;
+                if (s.justify === "center")
+                    pos = space / 2;
+                else if (s.justify === "end")
+                    pos = space;
+                else if (s.justify === "space-between" && count > 1)
+                    between = gap + space / (count - 1);
+                else if (s.justify === "space-around" && count > 0) {
+                    pos = space / count / 2;
+                    between = gap + space / count;
+                }
+                else if (s.justify === "space-evenly" && count > 0) {
+                    pos = space / (count + 1);
+                    between = gap + space / (count + 1);
+                }
             }
-            pos += lead + main + trail + (n < nodes.length - 1 ? between : 0);
+            const perAuto = autoMargins > 0 && space > 0 ? space / autoMargins : 0;
+            nodes.forEach((node, n) => {
+                const i = line.items[n];
+                if (!i)
+                    return;
+                const ms = i.box.style.margin;
+                const [before, after] = row ? [ms[3], ms[1]] : [ms[0], ms[2]];
+                const lead = (row ? (i.m[3] ?? 0) : (i.m[0] ?? 0)) + (before.kind === "auto" ? perAuto : 0);
+                const trail = (row ? (i.m[1] ?? 0) : (i.m[2] ?? 0)) + (after.kind === "auto" ? perAuto : 0);
+                const main = row ? node.w : node.h;
+                const cross = row ? node.h : node.w;
+                const crossLead = lineStart + (row ? (i.m[0] ?? 0) : (i.m[3] ?? 0));
+                const a = alignOf(i.box);
+                const crossOffset = a === "center" ? (crossSize - cross - i.crossMargin) / 2 : a === "end" ? crossSize - cross - i.crossMargin : 0;
+                if (row) {
+                    node.x = left + pos + lead;
+                    node.y = top + crossLead + crossOffset;
+                }
+                else {
+                    node.y = top + pos + lead;
+                    node.x = left + crossLead + crossOffset;
+                }
+                pos += lead + main + trail + (n < nodes.length - 1 ? between : 0);
+            });
+            mainEnd = Math.max(mainEnd, pos);
+            lineStart += crossSize + crossGap;
+            placed.push(...nodes);
         });
-        const height = row ? crossSize : innerH ?? pos;
-        return { nodes, height };
+        const crossTotal = crossSizes.reduce((sum, size) => sum + size, 0) + crossGap * Math.max(0, lines.length - 1);
+        const height = row ? innerH ?? crossTotal : innerH ?? mainEnd;
+        return { nodes: placed, height };
+    }
+}
+/** CSS's line breaking: an item starts a new line when it wouldn't fit on this one, and every line
+ *  holds at least one item, however wide. */
+function breakLines(items, room, gap) {
+    const lines = [];
+    let used = 0;
+    for (const item of items) {
+        const outer = item.hyp + item.mainMargin;
+        const line = lines.at(-1);
+        if (line && used + gap + outer <= room + FITS_WITHIN) {
+            line.push(item);
+            used += gap + outer;
+        }
+        else {
+            lines.push([item]);
+            used = outer;
+        }
     }
+    return lines;
 }

package/dist/paint/geometry.d.ts

@@ -9,7 +9,7 @@ export declare const apply: (m: Affine, x: number, y: number) => {
     x: number;
     y: number;
 };
-/** Scale, rotate about a point (CSS transform-origin at the box center). */
+/** Scale, rotate about a point (CSS transform-origin). */
 export declare function about(cx: number, cy: number, scale: number, rotate: number): Affine;
 /** The transform that maps rectangle `from` onto rectangle `to`. */
 export declare const fitRect: (from: Rect, to: Rect) => Affine;
@@ -21,6 +21,14 @@ export declare const inflate: (r: Rect, by: number) => Rect;
 export declare const contains: (r: Rect, x: number, y: number) => boolean;
 /** Uniform scale of an affine (for radii and blur under a camera). */
 export declare const scaleOf: (m: Affine) => number;
-/** The rect → quad homography for a CSS rotateY(turn)/rotateX(tilt) with perspective `depth`,
- *  about the rect's center, in the same coordinate space. */
-export declare function perspective(r: Rect, turn: number, tilt: number, depth: number): Homography;
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** The rect → quad homography for a CSS rotateY(turn)/rotateX(tilt) with perspective `depth`, in
+ *  the same coordinate space. It pivots on `pivot` and looks at `vanish`, both by default the
+ *  rect's center. */
+export declare function perspective(r: Rect, turn: number, tilt: number, depth: number, pivot?: Point, vanish?: Point): Homography;
+/** The homography putting a rect on a four-sided shape; null when the shape has collapsed to a
+ *  line or a point, which nothing can be drawn on. */
+export declare function ontoQuad(r: Rect, quad: ReadonlyArray<Point>): Homography | null;