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

package/dist/paint/geometry.js

@@ -19,7 +19,7 @@ export const rotation = (degrees) => {
     return { a: cs, b: sn, c: -sn, d: cs, e: 0, f: 0 };
 };
 export const apply = (m, x, y) => ({ x: m.a * x + m.c * y + m.e, y: m.b * x + m.d * y + m.f });
-/** Scale, rotate about a point (CSS transform-origin at the box center). */
+/** Scale, rotate about a point (CSS transform-origin). */
 export function about(cx, cy, scale, rotate) {
     let m = translate(cx, cy);
     if (rotate !== 0)
@@ -73,21 +73,35 @@ function mulH(m, n) {
     const [a = 0, b = 0, c = 0, d = 0, e = 0, f = 0, g = 0, h = 0, i = 1] = out;
     return [a, b, c, d, e, f, g, h, i];
 }
-/** 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 function perspective(r, turn, tilt, depth) {
-    const cx = r.x + r.w / 2, cy = r.y + r.h / 2;
+/** The homography taking a rect's corners (top left, clockwise) to a quad's. */
+function rectMap(r, quad) {
+    // Compose: rect → unit square, then unit square → quad.
+    const toUnit = [1 / r.w, 0, -r.x / r.w, 0, 1 / r.h, -r.y / r.h, 0, 0, 1];
+    return mulH(squareToQuad(quad), toUnit);
+}
+/** 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 function perspective(r, turn, tilt, depth, pivot, vanish) {
+    const center = { x: r.x + r.w / 2, y: r.y + r.h / 2 };
+    const { x: px, y: py } = pivot ?? center;
+    const { x: vx, y: vy } = vanish ?? center;
     const ty = radians(turn), tx = radians(tilt);
     const project = (x, y) => {
-        const lx = x - cx, ly = y - cy;
+        const lx = x - px, ly = y - py;
         // rotateY then rotateX, like `rotateY(turn) rotateX(tilt)`.
         const x1 = lx * cos(ty), z1 = -lx * sin(ty);
         const y2 = ly * cos(tx) - z1 * sin(tx), z2 = ly * sin(tx) + z1 * cos(tx);
         const w = 1 - z2 / depth;
-        return { x: cx + x1 / w, y: cy + y2 / w };
+        return { x: vx + (px + x1 - vx) / w, y: vy + (py + y2 - vy) / w };
     };
-    const quad = [project(r.x, r.y), project(r.x + r.w, r.y), project(r.x + r.w, r.y + r.h), project(r.x, r.y + r.h)];
-    // Compose: rect → unit square, then unit square → quad.
-    const toUnit = [1 / r.w, 0, -r.x / r.w, 0, 1 / r.h, -r.y / r.h, 0, 0, 1];
-    return mulH(squareToQuad(quad), toUnit);
+    return rectMap(r, [project(r.x, r.y), project(r.x + r.w, r.y), project(r.x + r.w, r.y + r.h), project(r.x, r.y + r.h)]);
+}
+/** 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 function ontoQuad(r, quad) {
+    if (!(r.w > 0) || !(r.h > 0))
+        return null;
+    const m = rectMap(r, quad);
+    return m.every((v) => Number.isFinite(v)) ? m : null;
 }

package/dist/paint/list.d.ts

@@ -1,6 +1,7 @@
+import type { BlendMode } from "@tongue-core/film/model";
 import type { PathVerb } from "../text/font-types.js";
 export declare const MAGIC = 1279544402;
-export declare const VERSION = 1;
+export declare const VERSION = 2;
 export declare const OP_END = 0;
 export declare const OP_TRANSFORM = 1;
 export declare const OP_FILL_RRECT = 2;
@@ -13,6 +14,7 @@ export declare const OP_PUSH_CLIP = 8;
 export declare const OP_POP_CLIP = 9;
 export declare const OP_PUSH_LAYER = 10;
 export declare const OP_POP_LAYER = 11;
+export declare const OP_POP_MASK = 12;
 /** Premultiplied color, each channel 0..1. */
 export interface Rgba {
     readonly r: number;
@@ -41,6 +43,17 @@ export type Paint = {
     readonly rx: number;
     readonly ry: number;
     readonly stops: ReadonlyArray<Stop>;
+}
+/** A color through noise. Solid: where the noise is below `threshold`, feathered by `soft`. Band:
+ *  only near the threshold, within `soft`. */
+ | {
+    readonly kind: "noise";
+    readonly ridged: boolean;
+    readonly band: boolean;
+    readonly size: number;
+    readonly threshold: number;
+    readonly soft: number;
+    readonly color: Rgba;
 };
 /** `x' = a·x + c·y + e`, `y' = b·x + d·y + f`. */
 export interface Affine {
@@ -65,11 +78,22 @@ export interface Radii {
 }
 /** Row-major 3×3 projective map. */
 export type Homography = readonly [number, number, number, number, number, number, number, number, number];
+/** How a layer lands on its parent. "plus" adds, for averaging samples; it isn't an author's mode. */
+export type LayerBlend = BlendMode | "plus";
 export interface LayerEffects {
     readonly opacity: number;
     readonly brightness: number;
     readonly saturate: number;
     readonly blur: number;
+    /** Default 1. */
+    readonly contrast?: number;
+    /** A hue rotation, as the cosine and sine of its angle (the raster has no trigonometry of its own). Default none. */
+    readonly hue?: {
+        readonly cos: number;
+        readonly sin: number;
+    };
+    /** Default "normal". */
+    readonly blend?: LayerBlend;
 }
 export interface PlacedGlyph {
     readonly glyph: number;
@@ -100,6 +124,9 @@ export declare class DisplayList {
     /** Composites the innermost layer: in place, or through `projective` (from where its pixels
      *  were drawn to where they land). */
     popLayer(projective?: Homography): void;
+    /** Pops the innermost layer as a mask: instead of drawing onto its parent, it multiplies the
+     *  parent's pixels by its alpha (or, inverted, by one minus its alpha). The parent stays open. */
+    popMask(invert: boolean): void;
     /** Appends END and returns the bytes. The writer is spent afterwards. */
     finish(): Uint8Array;
 }

package/dist/paint/list.js

@@ -1,5 +1,5 @@
 export const MAGIC = 0x4c444c52;
-export const VERSION = 1;
+export const VERSION = 2;
 export const OP_END = 0;
 export const OP_TRANSFORM = 1;
 export const OP_FILL_RRECT = 2;
@@ -12,6 +12,7 @@ export const OP_PUSH_CLIP = 8;
 export const OP_POP_CLIP = 9;
 export const OP_PUSH_LAYER = 10;
 export const OP_POP_LAYER = 11;
+export const OP_POP_MASK = 12;
 const VERB_MOVE = 0;
 const VERB_LINE = 1;
 const VERB_QUAD = 2;
@@ -20,6 +21,8 @@ const VERB_CLOSE = 4;
 const PAINT_SOLID = 0;
 const PAINT_LINEAR = 1;
 const PAINT_RADIAL = 2;
+const PAINT_NOISE = 3;
+const BLENDS = { normal: 0, multiply: 1, screen: 2, overlay: 3, "soft-light": 4, "color-dodge": 5, plus: 6 };
 /** A growable little-endian word buffer. Rejects non-finite numbers early, where the mistake is
  *  easy to trace, instead of letting the raster refuse the whole list. */
 class Words {
@@ -79,6 +82,14 @@ function writePaint(w, p) {
                 w.f32(v);
             writeStops(w, p.stops);
             return;
+        case "noise":
+            w.u32(PAINT_NOISE);
+            w.u32(p.ridged ? 1 : 0);
+            w.u32(p.band ? 1 : 0);
+            for (const v of [p.size, p.threshold, p.soft])
+                w.f32(v);
+            writeColor(w, p.color);
+            return;
     }
 }
 function writeStops(w, stops) {
@@ -210,8 +221,9 @@ export class DisplayList {
     }
     pushLayer(bounds, effects) {
         const w = this.op(OP_PUSH_LAYER);
-        for (const v of [bounds.x, bounds.y, bounds.w, bounds.h, effects.opacity, effects.brightness, effects.saturate, effects.blur])
+        for (const v of [bounds.x, bounds.y, bounds.w, bounds.h, effects.opacity, effects.brightness, effects.saturate, effects.blur, effects.contrast ?? 1, effects.hue?.cos ?? 1, effects.hue?.sin ?? 0])
             w.f32(v);
+        w.u32(BLENDS[effects.blend ?? "normal"]);
         this.layers += 1;
         this.clips.push(0);
     }
@@ -233,6 +245,18 @@ export class DisplayList {
         this.layers -= 1;
         this.clips.pop();
     }
+    /** Pops the innermost layer as a mask: instead of drawing onto its parent, it multiplies the
+     *  parent's pixels by its alpha (or, inverted, by one minus its alpha). The parent stays open. */
+    popMask(invert) {
+        if (this.layers < 2)
+            throw new Error("display list: popMask needs a mask layer and a layer to mask");
+        if ((this.clips.at(-1) ?? 0) > 0)
+            throw new Error("display list: popMask with clips still pushed inside the layer");
+        const w = this.op(OP_POP_MASK);
+        w.u32(invert ? 1 : 0);
+        this.layers -= 1;
+        this.clips.pop();
+    }
     /** Appends END and returns the bytes. The writer is spent afterwards. */
     finish() {
         if (this.layers !== 0)

package/dist/paint/morph.js

@@ -91,13 +91,17 @@ const scaleSide = (s, z) => ({ width: s.width * z, color: s.color });
 const mixSide = (a, b, t) => ({ width: lerp(a.width, b.width, t), color: mixColor(a.color, b.color, t) });
 /** Corners, borders and shadows blend; a solid background blends, anything else cross-fades. */
 function mixLook(a, b, t, tone) {
-    const count = Math.max(a.shadows.length, b.shadows.length);
-    const clear = { x: 0, y: 0, blur: 0, spread: 0, color: { r: 0, g: 0, b: 0, a: 0 } };
-    const shadows = Array.from({ length: count }, (_, i) => {
-        const sa = a.shadows[i] ?? { ...(b.shadows[i] ?? clear), color: { ...(b.shadows[i] ?? clear).color, a: 0 } };
-        const sb = b.shadows[i] ?? { ...sa, color: { ...sa.color, a: 0 } };
-        return { x: lerp(sa.x, sb.x, t), y: lerp(sa.y, sb.y, t), blur: lerp(sa.blur, sb.blur, t), spread: lerp(sa.spread, sb.spread, t), color: mixColor(sa.color, sb.color, t) };
-    });
+    // Outer shadows pair with outer ones and inset with inset: one can't become the other.
+    const mixed = (inset) => {
+        const from = a.shadows.filter((s) => s.inset === inset), to = b.shadows.filter((s) => s.inset === inset);
+        const clear = { x: 0, y: 0, blur: 0, spread: 0, color: { r: 0, g: 0, b: 0, a: 0 }, inset };
+        return Array.from({ length: Math.max(from.length, to.length) }, (_, i) => {
+            const sa = from[i] ?? { ...(to[i] ?? clear), color: { ...(to[i] ?? clear).color, a: 0 } };
+            const sb = to[i] ?? { ...sa, color: { ...sa.color, a: 0 } };
+            return { x: lerp(sa.x, sb.x, t), y: lerp(sa.y, sb.y, t), blur: lerp(sa.blur, sb.blur, t), spread: lerp(sa.spread, sb.spread, t), color: mixColor(sa.color, sb.color, t), inset };
+        });
+    };
+    const shadows = [...mixed(false), ...mixed(true)];
     const radii = { tl: lerp(a.radii.tl, b.radii.tl, t), tr: lerp(a.radii.tr, b.radii.tr, t), br: lerp(a.radii.br, b.radii.br, t), bl: lerp(a.radii.bl, b.radii.bl, t) };
     const border = [mixSide(a.border[0], b.border[0], t), mixSide(a.border[1], b.border[1], t), mixSide(a.border[2], b.border[2], t), mixSide(a.border[3], b.border[3], t)];
     const fa = a.background.length === 1 ? a.background[0] : undefined;

package/dist/paint/paint.d.ts

@@ -2,7 +2,7 @@ import { type FullPose } from "@tongue-core/film/model";
 import type { LBox } from "../layout/layout.js";
 import type { BackgroundLayer, Color, Computed, Shadow } from "../style/computed.js";
 import type { PlacedGlyph as LaidGlyph } from "../text/paragraph.js";
-import type { Affine, DisplayList, Homography, Radii, Rect, Rgba } from "./list.js";
+import type { Affine, DisplayList, Homography, LayerEffects, Paint, Radii, Rect, Rgba } from "./list.js";
 import { type SceneFrame, type ScreenGlyph } from "../evaluate/scene-frame.js";
 import type { Picture } from "../evaluate/tree.js";
 export interface Resources {
@@ -42,6 +42,8 @@ export declare class Painter {
     private lifted;
     /** Screen → surface for the scene being painted (render scale, plus any whole-scene move). */
     private screenBase;
+    /** The camera the children now being painted share (their parent's `perspective`), in surface pixels. */
+    private view;
     constructor(list: DisplayList, res: Resources, device: Affine);
     private setTransform;
     /** The stage → surface transform for a scene (camera, then render scale). */
@@ -49,12 +51,7 @@ export declare class Painter {
     /** Paints a whole scene; `outer` moves the whole picture in screen space (transitions). */
     scene(sf: SceneFrame, hooks?: PaintHooks, outer?: Affine): void;
     surfaceRect(): Rect;
-    layer(bounds: Rect, effects: {
-        readonly opacity: number;
-        readonly brightness: number;
-        readonly saturate: number;
-        readonly blur: number;
-    }): void;
+    layer(bounds: Rect, effects: LayerEffects): void;
     /** Paints children in z order; `childPose` adds a pose per child index (transition presets). */
     children(sf: SceneFrame, lb: LBox, m: Affine, cam: Affine, hooks: PaintHooks, childPose?: (index: number) => FullPose): void;
     /** Paints one box and its subtree. `m` maps stage to surface for this box (it includes any
@@ -66,6 +63,9 @@ export declare class Painter {
     paintWith(sf: SceneFrame, lb: LBox, base: Affine, cam: Affine, hooks: PaintHooks, pose: FullPose, look: Look, part: "full" | "content"): void;
     decorate(lb: LBox, m: Affine, look: Look, alpha?: number): void;
     decorateRect(rect: Rect, m: Affine, look: Look, alpha?: number): void;
+    /** A shadow cast inside a box: everything outside the box's shape, shifted and blurred, seen
+     *  through the box. */
+    private insetShadow;
     private paintOf;
     /** Identical text moving to a new place: each glyph flies from where it was to where it is
      *  going, resizing on the way (so text re-wraps smoothly). Null when the text differs. */
@@ -80,14 +80,25 @@ export declare class Painter {
     /** Clips what follows to a rectangle of the surface, in surface pixels (wipe transitions). */
     clipSurface(rect: Rect): void;
     unclip(): void;
+    /** Fills a rect of stage pixels with a paint (transitions). */
+    fillStage(rect: Rect, paint: Paint): void;
+    popMask(invert: boolean): void;
     popLayer(projective?: Homography): void;
     content(sf: SceneFrame, lb: LBox, m: Affine, cam: Affine, hooks: PaintHooks): void;
+    /** Motion blur: each sample in its own layer, added into one with its share of the weight. The
+     *  layers add rather than cover, so a partly transparent trail averages correctly. */
+    private sampleGroup;
+    /** The content in a layer, then the shape in another, which is multiplied into the first. Both
+     *  layers span at least the whole frame: anything inside may be transformed beyond its box. */
+    private maskGroup;
     image(lb: LBox, m: Affine, picture: Picture, alpha?: number): void;
     imageRect(picture: Picture, box: Rect, m: Affine, fit: Computed["objectFit"], pos: readonly [number, number], radius: number, alpha: number): void;
     svg(lb: LBox, m: Affine, alpha?: number): void;
     /** Paragraph text: glyph runs, Say words (each with its own pose) and the caret. */
     private text;
     textColor(sf: SceneFrame, lb: LBox): ((g: LaidGlyph) => Color);
+    /** Text shadows, each run's own, the last listed lowest (as in CSS). */
+    private textShadows;
     /** Draws glyphs (positions relative to a paragraph origin), batching runs that share a font,
      *  size and color. */
     glyphs(list: ReadonlyArray<LaidGlyph>, ox: number, oy: number, m: Affine, color: (g: LaidGlyph) => Color, alpha: number): void;

package/dist/paint/paint.js

@@ -1,6 +1,7 @@
 import { composePose, full, rest } from "@tongue-core/film/model";
 import { cos, lerp, radians, sin } from "@tongue-core/film/model";
-import { about, apply, bounds, fitRect, identity, inflate, lerpRect, mul, perspective, scaleOf, translate, union } from "./geometry.js";
+import { about, apply, bounds, fitRect, identity, inflate, lerpRect, mul, ontoQuad, perspective, scaleOf, translate, union } from "./geometry.js";
+import { strokeOutline } from "./stroke.js";
 import { screenGlyphs } from "../evaluate/scene-frame.js";
 export const premul = (c, alpha = 1) => {
     const a = c.a * alpha;
@@ -29,9 +30,16 @@ export function extentOf(lb) {
         return hit;
     let r = rectOf(lb);
     for (const s of lb.box.style.shadows)
-        r = union(r, inflate({ x: lb.x + s.x - s.spread, y: lb.y + s.y - s.spread, w: lb.w + 2 * s.spread, h: lb.h + 2 * s.spread }, s.blur * 1.5));
-    if (lb.text)
-        r = union(r, { x: lb.text.x, y: lb.text.y, w: lb.text.paragraph.width, h: lb.text.paragraph.height });
+        if (!s.inset)
+            r = union(r, inflate({ x: lb.x + s.x - s.spread, y: lb.y + s.y - s.spread, w: lb.w + 2 * s.spread, h: lb.h + 2 * s.spread }, s.blur * 1.5));
+    if (lb.text) {
+        const text = { x: lb.text.x, y: lb.text.y, w: lb.text.paragraph.width, h: lb.text.paragraph.height };
+        r = union(r, text);
+        if (lb.box.content.kind === "text")
+            for (const run of lb.box.content.runs)
+                for (const s of run.style.shadows)
+                    r = union(r, inflate({ ...text, x: text.x + s.x, y: text.y + s.y }, s.blur * 1.5));
+    }
     if (!lb.box.style.overflowHidden)
         for (const c of lb.children)
             r = union(r, extentOf(c));
@@ -72,6 +80,8 @@ export class Painter {
     lifted = null;
     /** Screen → surface for the scene being painted (render scale, plus any whole-scene move). */
     screenBase;
+    /** The camera the children now being painted share (their parent's `perspective`), in surface pixels. */
+    view = null;
     constructor(list, res, device) {
         this.list = list;
         this.res = res;
@@ -164,17 +174,31 @@ export class Painter {
         const opacity = s.opacity * pose.opacity;
         if (opacity <= 0.002)
             return;
+        // Perspective reaches only direct children: this element uses its parent's, and its own
+        // descendants start without one.
+        const view = this.view;
+        this.view = null;
         const blur = s.blur + pose.blur;
         const brightness = s.brightness * pose.brightness;
         const cx = lb.x + lb.w / 2, cy = lb.y + lb.h / 2;
-        const local = mul(about(cx, cy, scale, rotate), translate(t.x + pose.x, t.y + pose.y));
-        const m = mul(base, local);
-        const flat = turn === 0 && tilt === 0;
-        const layered = opacity < 0.998 || blur > 0.01 || Math.abs(brightness - 1) > 0.001 || Math.abs(s.saturate - 1) > 0.001 || !flat;
+        const ox = lb.x + lb.w * t.origin[0], oy = lb.y + lb.h * t.origin[1];
+        const local = mul(about(ox, oy, scale, rotate), translate(t.x + pose.x, t.y + pose.y));
+        const corners = lb.box.corners;
+        // A mapped element is drawn at the corner of its layer, wherever layout put it, then warped.
+        const moved = mul(base, local);
+        const source = corners ? bounds(moved, rectOf(lb)) : null;
+        const m = source ? mul(translate(-source.x, -source.y), moved) : moved;
+        const onto = corners && source ? ontoQuad({ ...source, x: 0, y: 0 }, corners.map(([x, y]) => apply(base, x, y))) : null;
+        if (corners && !onto) {
+            this.view = view;
+            return;
+        }
+        const flat = turn === 0 && tilt === 0 && !corners;
+        const layered = opacity < 0.998 || blur > 0.01 || Math.abs(brightness - 1) > 0.001 || Math.abs(s.saturate - 1) > 0.001 || Math.abs(s.contrast - 1) > 0.001 || s.hueRotate !== 0 || s.blend !== "normal" || !flat;
         const k = scaleOf(m);
         if (layered) {
             const area = inflate(bounds(m, extentOf(lb)), blur * 3 * k + 2);
-            this.layer(area, { opacity, brightness, saturate: s.saturate, blur: blur * k });
+            this.layer(area, { opacity, brightness, saturate: s.saturate, blur: blur * k, contrast: s.contrast, hue: s.hueRotate === 0 ? undefined : { cos: cos(radians(s.hueRotate)), sin: sin(radians(s.hueRotate)) }, blend: s.blend });
         }
         const iris = pose.iris < 0.999;
         if (iris) {
@@ -187,12 +211,16 @@ export class Painter {
         this.content(sf, lb, m, cam, hooks);
         if (iris)
             this.list.popClip();
+        this.view = view;
         if (layered) {
-            if (flat)
+            if (onto)
+                this.list.popLayer(onto);
+            else if (flat)
                 this.list.popLayer();
             else {
                 const box = bounds(m, rectOf(lb));
-                this.list.popLayer(perspective(box, turn, tilt, 1800 * k));
+                const custom = view !== null || t.origin[0] !== 0.5 || t.origin[1] !== 0.5;
+                this.list.popLayer(custom ? perspective(box, turn, tilt, view?.depth ?? 1800 * k, apply(m, ox, oy), view?.vanish) : perspective(box, turn, tilt, 1800 * k));
             }
             this.current = null;
         }
@@ -203,7 +231,7 @@ export class Painter {
     decorateRect(rect, m, look, alpha = 1) {
         this.setTransform(m);
         for (const sh of look.shadows) {
-            if (sh.color.a <= 0)
+            if (sh.color.a <= 0 || sh.inset)
                 continue;
             const r = { x: rect.x + sh.x - sh.spread, y: rect.y + sh.y - sh.spread, w: rect.w + 2 * sh.spread, h: rect.h + 2 * sh.spread };
             this.list.shadowRRect(r, Math.max(0, (look.radii.tl + look.radii.tr + look.radii.br + look.radii.bl) / 4 + sh.spread), Math.max(0.01, sh.blur / 2), premul(sh.color, alpha));
@@ -213,6 +241,10 @@ export class Painter {
             if (paint)
                 this.list.fillRRect(rect, look.radii, paint);
         }
+        for (const sh of look.shadows)
+            if (sh.inset && sh.color.a > 0)
+                this.insetShadow(rect, m, look.radii, sh, alpha);
+        this.setTransform(m);
         const [top, right, bottom, left] = look.border;
         const uniform = top.width === right.width && top.width === bottom.width && top.width === left.width &&
             [right, bottom, left].every((x) => x.color.r === top.color.r && x.color.g === top.color.g && x.color.b === top.color.b && x.color.a === top.color.a);
@@ -230,6 +262,31 @@ export class Painter {
                     this.list.fillRRect(r, { tl: 0, tr: 0, br: 0, bl: 0 }, { kind: "solid", color: premul(side.color, alpha) });
         }
     }
+    /** A shadow cast inside a box: everything outside the box's shape, shifted and blurred, seen
+     *  through the box. */
+    insetShadow(rect, m, radii, sh, alpha) {
+        const k = scaleOf(m);
+        const sigma = sh.blur / 2;
+        const reach = sigma * 3 + Math.abs(sh.x) + Math.abs(sh.y) + Math.abs(sh.spread) + 2;
+        const outer = inflate(rect, reach);
+        const hole = { x: rect.x + sh.x + sh.spread, y: rect.y + sh.y + sh.spread, w: Math.max(0, rect.w - 2 * sh.spread), h: Math.max(0, rect.h - 2 * sh.spread) };
+        const verbs = [
+            { kind: "move", x: outer.x, y: outer.y },
+            { kind: "line", x: outer.x + outer.w, y: outer.y },
+            { kind: "line", x: outer.x + outer.w, y: outer.y + outer.h },
+            { kind: "line", x: outer.x, y: outer.y + outer.h },
+            { kind: "close" },
+            ...rrectVerbs(hole, radii, -sh.spread),
+        ];
+        this.setTransform(m);
+        this.list.pushClip(rect, radii.tl);
+        this.layer(inflate(bounds(m, rect), reach * k), { opacity: 1, brightness: 1, saturate: 1, blur: sigma * k });
+        this.setTransform(m);
+        this.list.fillPath(verbs, "evenodd", { kind: "solid", color: premul(sh.color, alpha) });
+        this.popLayer();
+        this.setTransform(m);
+        this.list.popClip();
+    }
     paintOf(layer, r, alpha) {
         if (layer.kind === "color")
             return layer.color.a <= 0 ? null : { kind: "solid", color: premul(layer.color, alpha) };
@@ -302,6 +359,15 @@ export class Painter {
     unclip() {
         this.list.popClip();
     }
+    /** Fills a rect of stage pixels with a paint (transitions). */
+    fillStage(rect, paint) {
+        this.setTransform(this.device);
+        this.list.fillRRect(rect, { tl: 0, tr: 0, br: 0, bl: 0 }, paint);
+    }
+    popMask(invert) {
+        this.list.popMask(invert);
+        this.current = null;
+    }
     popLayer(projective) {
         if (projective)
             this.list.popLayer(projective);
@@ -332,10 +398,53 @@ export class Painter {
             this.setTransform(m);
             this.list.pushClip(inner, Math.max(0, radii.tl - s.border[0].width));
         }
-        this.children(sf, lb, m, cam, hooks);
+        if (b.style.perspective !== null) {
+            const [fx, fy] = b.style.perspectiveOrigin;
+            this.view = { depth: b.style.perspective * scaleOf(m), vanish: apply(m, lb.x + lb.w * fx, lb.y + lb.h * fy) };
+        }
+        if (b.group?.kind === "mask")
+            this.maskGroup(sf, lb, m, cam, hooks, b.group.invert);
+        else if (b.group?.kind === "samples")
+            this.sampleGroup(sf, lb, m, cam, hooks);
+        else
+            this.children(sf, lb, m, cam, hooks);
+        this.view = null;
         if (clip)
             this.list.popClip();
     }
+    /** Motion blur: each sample in its own layer, added into one with its share of the weight. The
+     *  layers add rather than cover, so a partly transparent trail averages correctly. */
+    sampleGroup(sf, lb, m, cam, hooks) {
+        const area = union(this.surfaceRect(), inflate(bounds(m, extentOf(lb)), 2));
+        const weight = 1 / lb.children.length;
+        this.layer(area, { opacity: 1, brightness: 1, saturate: 1, blur: 0 });
+        for (const sample of lb.children) {
+            this.layer(area, { opacity: weight, brightness: 1, saturate: 1, blur: 0, blend: "plus" });
+            this.box(sf, sample, m, cam, hooks);
+            this.popLayer();
+        }
+        this.popLayer();
+    }
+    /** The content in a layer, then the shape in another, which is multiplied into the first. Both
+     *  layers span at least the whole frame: anything inside may be transformed beyond its box. */
+    maskGroup(sf, lb, m, cam, hooks, invert) {
+        const [content, shape] = lb.children;
+        if (!content || !shape)
+            return;
+        const area = union(this.surfaceRect(), inflate(bounds(m, extentOf(lb)), 2));
+        const plain = { opacity: 1, brightness: 1, saturate: 1, blur: 0 };
+        // Keyed elements inside can't travel out from under the mask.
+        const lifted = this.lifted;
+        this.lifted = null;
+        this.layer(area, plain);
+        this.box(sf, content, m, cam, hooks);
+        this.layer(area, plain);
+        this.box(sf, shape, m, cam, hooks);
+        this.list.popMask(invert);
+        this.current = null;
+        this.popLayer();
+        this.lifted = lifted;
+    }
     image(lb, m, picture, alpha = 1) {
         const s = lb.box.style;
         const box = { x: lb.x + s.padding[3] + s.border[3].width, y: lb.y + s.padding[0] + s.border[0].width, w: lb.w - s.padding[1] - s.padding[3] - s.border[1].width - s.border[3].width, h: lb.h - s.padding[0] - s.padding[2] - s.border[0].width - s.border[2].width };
@@ -354,9 +463,17 @@ export class Painter {
         const box = { x: lb.x + s.padding[3], y: lb.y + s.padding[0], w: lb.w - s.padding[1] - s.padding[3], h: lb.h - s.padding[0] - s.padding[2] };
         const k = Math.min(box.w / vw, box.h / vh);
         const view = mul(translate(box.x + (box.w - vw * k) / 2, box.y + (box.h - vh * k) / 2), mul({ a: k, b: 0, c: 0, d: k, e: 0, f: 0 }, translate(-vx, -vy)));
-        this.setTransform(mul(m, view));
-        for (const p of lb.box.content.paths)
-            this.list.fillPath(p.verbs, p.rule, { kind: "solid", color: premul(p.fill, alpha) });
+        const full = mul(m, view);
+        this.setTransform(full);
+        for (const p of lb.box.content.paths) {
+            if (p.fill)
+                this.list.fillPath(p.verbs, p.rule, { kind: "solid", color: premul(p.fill, alpha) });
+            if (!p.stroke)
+                continue;
+            const outline = strokeOutline(p.verbs, p.stroke, scaleOf(full));
+            if (outline.length > 0)
+                this.list.fillPath(outline, "nonzero", { kind: "solid", color: premul(p.stroke.color, alpha) });
+        }
     }
     /** Paragraph text: glyph runs, Say words (each with its own pose) and the caret. */
     text(sf, lb, m, cam, hooks) {
@@ -394,6 +511,7 @@ export class Painter {
                 const layered = pose.opacity < 0.998 || pose.blur > 0.01;
                 if (layered)
                     this.layer(inflate(bounds(wm, wr), pose.blur * 3 * scaleOf(wm) + wr.h * 0.3), { opacity: pose.opacity, brightness: 1, saturate: 1, blur: pose.blur * scaleOf(wm) });
+                this.textShadows(c.runs, glyphs, laid.x, laid.y, wm, wr);
                 this.glyphs(glyphs, laid.x, laid.y, wm, color, 1);
                 if (layered) {
                     this.list.popLayer();
@@ -402,6 +520,7 @@ export class Painter {
             }
         }
         else {
+            this.textShadows(c.runs, visible, laid.x, laid.y, m, { x: laid.x, y: laid.y, w: laid.paragraph.width, h: laid.paragraph.height });
             this.glyphs(visible, laid.x, laid.y, m, color, 1);
         }
         // Keyed text moving to a new place inside the scene draws at its travelling position.
@@ -438,6 +557,31 @@ export class Painter {
             return col;
         };
     }
+    /** Text shadows, each run's own, the last listed lowest (as in CSS). */
+    textShadows(runs, list, ox, oy, m, box) {
+        runs.forEach((run, index) => {
+            if (run.style.shadows.length === 0)
+                return;
+            const glyphs = list.filter((g) => g.run === index);
+            if (glyphs.length === 0)
+                return;
+            const size = run.style.fontSize;
+            for (const sh of [...run.style.shadows].reverse()) {
+                if (sh.color.a <= 0)
+                    continue;
+                const moved = mul(m, translate(sh.x, sh.y));
+                const k = scaleOf(moved);
+                const sigma = sh.blur / 2;
+                const layered = sigma > 0.05;
+                // Glyphs reach past their line boxes, so the layer allows for a font size all round.
+                if (layered)
+                    this.layer(inflate(bounds(moved, box), size * k + sigma * 3 * k + 2), { opacity: 1, brightness: 1, saturate: 1, blur: sigma * k });
+                this.glyphs(glyphs, ox, oy, moved, () => sh.color, 1);
+                if (layered)
+                    this.popLayer();
+            }
+        });
+    }
     /** Draws glyphs (positions relative to a paragraph origin), batching runs that share a font,
      *  size and color. */
     glyphs(list, ox, oy, m, color, alpha) {
@@ -486,6 +630,27 @@ export class Painter {
         return apply(m, x, y);
     }
 }
+/** A rounded rect as path verbs. Corner radii follow the shape as it grows or shrinks by `grow`. */
+function rrectVerbs(r, radii, grow) {
+    const fit = Math.min(r.w, r.h) / 2;
+    const at = (v) => Math.min(fit, Math.max(0, v + grow));
+    const [tl, tr, br, bl] = [at(radii.tl), at(radii.tr), at(radii.br), at(radii.bl)];
+    // A quarter circle as one cubic.
+    const K = 1 - 0.5522847498;
+    const [x0, y0, x1, y1] = [r.x, r.y, r.x + r.w, r.y + r.h];
+    return [
+        { kind: "move", x: x0 + tl, y: y0 },
+        { kind: "line", x: x1 - tr, y: y0 },
+        { kind: "cubic", c1x: x1 - tr * K, c1y: y0, c2x: x1, c2y: y0 + tr * K, x: x1, y: y0 + tr },
+        { kind: "line", x: x1, y: y1 - br },
+        { kind: "cubic", c1x: x1, c1y: y1 - br * K, c2x: x1 - br * K, c2y: y1, x: x1 - br, y: y1 },
+        { kind: "line", x: x0 + bl, y: y1 },
+        { kind: "cubic", c1x: x0 + bl * K, c1y: y1, c2x: x0, c2y: y1 - bl * K, x: x0, y: y1 - bl },
+        { kind: "line", x: x0, y: y0 + tl },
+        { kind: "cubic", c1x: x0, c1y: y0 + tl * K, c2x: x0 + tl * K, c2y: y0, x: x0 + tl, y: y0 },
+        { kind: "close" },
+    ];
+}
 /** An arrow cursor in a unit box, inset by `inset` for the dark inner shape. */
 function arrow(inset) {
     const pts = inset === 0

package/dist/paint/stroke.d.ts

@@ -0,0 +1,26 @@
+import type { PathVerb } from "../text/font-types.js";
+export type StrokeCap = "butt" | "round" | "square";
+export type StrokeJoin = "miter" | "round" | "bevel";
+export interface StrokeOptions {
+    readonly width: number;
+    readonly cap: StrokeCap;
+    readonly join: StrokeJoin;
+    /** The stretch to draw, as fractions of the outline's whole length. */
+    readonly trim: readonly [number, number];
+}
+interface Point {
+    readonly x: number;
+    readonly y: number;
+    /** Inside a flattened curve: the angle here is tiny, not a corner the author drew. */
+    readonly smooth: boolean;
+}
+interface Line {
+    readonly points: ReadonlyArray<Point>;
+    readonly closed: boolean;
+}
+/** The path as polylines, one per subpath, with repeated points removed. */
+export declare function flatten(verbs: ReadonlyArray<PathVerb>, tolerance: number): ReadonlyArray<Line>;
+/** The outline of a stroked path as fillable verbs (nonzero rule). `scale` is how many surface
+ *  pixels one path unit covers: it sets how finely curves and round ends are drawn. */
+export declare function strokeOutline(verbs: ReadonlyArray<PathVerb>, stroke: StrokeOptions, scale: number): ReadonlyArray<PathVerb>;
+export {};