@toonstrip/core 0.1.0

package/dist/balloon.js

@@ -0,0 +1,335 @@
+/**
+ * The one font every balloon is measured and drawn in. Exported because
+ * measurement happens in more than one place (the renderer, and any
+ * caller-side pre-check), and both must break lines identically.
+ */
+export const BALLOON_FONT = '13px "Comic Sans MS", "Comic Neue", ui-rounded, cursive';
+const PADDING = 10;
+/**
+ * A thought balloon's scallops bulge outward from its text box, so the text
+ * is inset by a bump radius or the first/last words sit under the cloud's
+ * own outline. A speech balloon and a caption need no such allowance.
+ */
+const THINK_INSET = 9;
+export const LINE_HEIGHT = 15;
+/** How far a tail must clear its balloon's edge before angling toward its speaker. */
+const TAIL_MIN_EXIT = 2;
+/**
+ * The balloon outline ripples instead of running dead straight: each edge is
+ * walked and alternate waypoints pushed outward along the edge normal, then
+ * the whole ring (corners included) is splined through one closed curve —
+ * what makes the outline read hand-drawn instead of a rounded rect.
+ *
+ * `WAVE_INTERVAL` is the spacing between bumps, `WAVE_AMP` their outward depth.
+ */
+const WAVE_INTERVAL = 22;
+const WAVE_AMP = 6;
+/** Cardinal-spline tension for the outline — 0.5 is the Catmull-Rom value. */
+const SPLINE_TENSION = 0.5;
+/** Below this one-line width, a balloon stays a single line rather than being wrapped for shape. */
+export const ONE_LINE_THRESHOLD = 100;
+/** The width:height a wrapped balloon trends toward — square-ish but a touch wide. */
+const TARGET_ASPECT = 1.9;
+/** Ink-area fudge factor used when estimating a compact wrap width. */
+export const AREA_FUDGE = 1.3;
+/** How far the compact goal is pushed toward the free width. */
+const WIDTH_BIAS = 0.5;
+/** Widest single word, the floor a balloon may not wrap below. */
+export function widestWord(ctx, text) {
+    const words = text.split(/\s+/).filter((w) => w.length > 0);
+    return words.length === 0 ? 0 : Math.max(...words.map((w) => ctx.measureText(w).width));
+}
+/**
+ * The width a balloon *wants* to wrap at. Short text stays one line; longer
+ * text is sized from its ink area so the balloon is compact rather than a
+ * wide flat strip, floored by the widest word and capped at the free width.
+ * Wrapping at this width is what makes a balloon read as a balloon shape
+ * rather than a text block.
+ */
+export function goalWidth(ctx, text, maxWidth) {
+    const oneLine = ctx.measureText(text).width;
+    if (oneLine <= ONE_LINE_THRESHOLD)
+        return Math.min(oneLine, maxWidth);
+    // area ~= ink area laid on one line; for a box of width W the height is ~= area/W,
+    // so aspect W/(area/W) = W^2/area = TARGET_ASPECT => W = sqrt(TARGET_ASPECT * area).
+    const area = AREA_FUDGE * oneLine * LINE_HEIGHT;
+    const compact = Math.sqrt(TARGET_ASPECT * area);
+    // Spread toward the free width, but never past the one-line width.
+    const ceiling = Math.min(maxWidth, oneLine);
+    const goal = compact + WIDTH_BIAS * (ceiling - compact);
+    return Math.min(Math.max(goal, widestWord(ctx, text)), ceiling);
+}
+/**
+ * Greedy fit: pack words onto a line until the next would overflow, then
+ * break. A word longer than the whole width is kept intact on its own line
+ * rather than split mid-character.
+ */
+function greedyWrap(ctx, text, maxWidth) {
+    const lines = [];
+    let line = "";
+    for (const word of text.split(/\s+/).filter((w) => w.length > 0)) {
+        const candidate = line === "" ? word : `${line} ${word}`;
+        if (line !== "" && ctx.measureText(candidate).width > maxWidth) {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = candidate;
+        }
+    }
+    if (line !== "")
+        lines.push(line);
+    return lines;
+}
+export function measureBalloon(ctx, balloon, maxWidth) {
+    const pad = PADDING + (balloon.balloon === "thought" ? THINK_INSET : 0);
+    const lines = greedyWrap(ctx, balloon.text, goalWidth(ctx, balloon.text, maxWidth - pad * 2));
+    const width = Math.min(maxWidth, Math.max(...lines.map((line) => ctx.measureText(line).width)) + pad * 2);
+    return { lines, width, height: lines.length * LINE_HEIGHT + pad * 2 };
+}
+/** The chrome a balloon kind puts between its outline and its text, each side. */
+export function chromeFor(balloon) {
+    return PADDING + (balloon.balloon === "thought" ? THINK_INSET : 0);
+}
+/**
+ * Wrap and measure at a width the *caller* chose, rather than at the width
+ * {@link goalWidth} would pick. The entry point the multi-balloon layout
+ * driver needs, once the free rect and intervening routes have narrowed a
+ * balloon's span below its own preferred width.
+ */
+export function measureAtWidth(ctx, balloon, boxWidth) {
+    const pad = chromeFor(balloon);
+    const inner = Math.max(1, boxWidth - pad * 2);
+    const lines = greedyWrap(ctx, balloon.text, inner);
+    const width = Math.min(boxWidth, Math.max(...lines.map((line) => ctx.measureText(line).width)) + pad * 2);
+    return { lines, width, height: lines.length * LINE_HEIGHT + pad * 2 };
+}
+/** Appended to the part of a too-tall balloon that fit, prepended to the rest. */
+export const CONTINUATION = "...";
+/**
+ * Reflow the text at `boxWidth`, keep as many lines as `boxHeight` holds, and
+ * hand the rest back for the caller to re-add. Lets a balloon too tall for
+ * its free rect force-fit into it and split rather than being refused
+ * outright — the layout driver's ({@link "./balloon-layout.js".layoutBalloons})
+ * last resort for a lone balloon in an otherwise empty panel.
+ *
+ * At least one word is always kept: a word that fits nowhere is drawn
+ * clipped rather than handing back a leftover identical to the input.
+ */
+export function splitHeight(ctx, balloon, boxWidth, boxHeight) {
+    const pad = chromeFor(balloon);
+    const inner = Math.max(1, boxWidth - pad * 2);
+    const lines = greedyWrap(ctx, balloon.text, inner);
+    const maxLines = Math.max(1, Math.floor(boxHeight / LINE_HEIGHT));
+    if (lines.length < maxLines)
+        return { text: balloon.text, rest: null };
+    const words = balloon.text.split(/\s+/).filter((w) => w.length > 0);
+    // Whole lines above the one being broken.
+    let kept = lines.slice(0, maxLines - 1)
+        .reduce((n, line) => n + line.split(/\s+/).filter((w) => w.length > 0).length, 0);
+    // ...then as much of that line as fits beside the continuation mark.
+    const room = inner - ctx.measureText(CONTINUATION).width;
+    let line = "";
+    for (const word of lines[maxLines - 1]?.split(/\s+/).filter((w) => w.length > 0) ?? []) {
+        const candidate = line === "" ? word : `${line} ${word}`;
+        if (line !== "" && ctx.measureText(candidate).width > room)
+            break;
+        line = candidate;
+        kept += 1;
+    }
+    kept = Math.max(1, Math.min(kept, words.length));
+    if (kept >= words.length)
+        return { text: balloon.text, rest: null };
+    return {
+        text: `${words.slice(0, kept).join(" ")}${CONTINUATION}`,
+        rest: `${CONTINUATION}${words.slice(kept).join(" ")}`,
+    };
+}
+/**
+ * Draw a balloon in its kind's shape, with a tail toward `target` when the
+ * kind has one. Captions do not: a box is the narrator's, spoken by nobody.
+ */
+export function drawBalloon(ctx, balloon, box, lines, target) {
+    ctx.save();
+    ctx.lineJoin = "round";
+    ctx.strokeStyle = "#000";
+    ctx.fillStyle = "#fff";
+    ctx.lineWidth = 1.5;
+    switch (balloon.balloon) {
+        case "caption":
+            ctx.beginPath();
+            ctx.rect(box.x, box.y, box.width, box.height);
+            ctx.fill();
+            ctx.stroke();
+            break;
+        case "thought":
+            cloud(ctx, box);
+            ctx.fill();
+            ctx.stroke();
+            if (target)
+                bubbleTrail(ctx, box, target);
+            break;
+        case "speech":
+            roundedSpeech(ctx, box, target);
+            ctx.fill();
+            ctx.stroke();
+            break;
+    }
+    ctx.fillStyle = "#000";
+    ctx.textBaseline = "top";
+    const pad = PADDING + (balloon.balloon === "thought" ? THINK_INSET : 0);
+    for (const [i, line] of lines.entries()) {
+        // Centred, so the ragged wrap edge reads as shared between both sides.
+        const width = ctx.measureText(line).width;
+        ctx.fillText(line, box.x + (box.width - width) / 2, box.y + pad + i * LINE_HEIGHT);
+    }
+    ctx.restore();
+}
+/** A scalloped outline, drawn as one continuous closed path of outward-bulging arcs. */
+function cloud(ctx, box) {
+    const cols = Math.max(4, Math.round(box.width / 26));
+    const rows = Math.max(2, Math.round(box.height / 24));
+    const rx = box.width / (cols * 2);
+    const ry = box.height / (rows * 2);
+    const { x, y, width: w, height: h } = box;
+    ctx.beginPath();
+    ctx.moveTo(x, y);
+    // Top edge, left -> right, each scallop bulging up.
+    for (let i = 0; i < cols; i++) {
+        ctx.arc(x + (w * (i + 0.5)) / cols, y, rx, Math.PI, 2 * Math.PI, false);
+    }
+    // Right edge, top -> bottom, bulging right.
+    for (let i = 0; i < rows; i++) {
+        ctx.arc(x + w, y + (h * (i + 0.5)) / rows, ry, -Math.PI / 2, Math.PI / 2, false);
+    }
+    // Bottom edge, right -> left, bulging down.
+    for (let i = cols - 1; i >= 0; i--) {
+        ctx.arc(x + (w * (i + 0.5)) / cols, y + h, rx, 0, Math.PI, false);
+    }
+    // Left edge, bottom -> top, bulging left.
+    for (let i = rows - 1; i >= 0; i--) {
+        ctx.arc(x, y + (h * (i + 0.5)) / rows, ry, Math.PI / 2, (3 * Math.PI) / 2, false);
+    }
+    ctx.closePath();
+}
+/**
+ * A thought balloon's tail: a line of bubbles rather than an arrow — the
+ * mark that says *interior* at a glance. Three bubbles at even spacing,
+ * smallest nearest the speaker.
+ */
+function bubbleTrail(ctx, box, target) {
+    const from = { x: box.x + box.width / 2, y: box.y + box.height };
+    for (let i = 1; i <= 3; i++) {
+        const t = i / 4;
+        ctx.beginPath();
+        ctx.arc(from.x + (target.x - from.x) * t, from.y + (target.y - from.y) * t, 6 - i * 1.4, 0, Math.PI * 2);
+        ctx.fill();
+        ctx.stroke();
+    }
+}
+/**
+ * Walk edge `a->b` and append its outward bumps to `pts`: alternating
+ * waypoints, a bump pushed out by `WAVE_AMP` along the edge normal `(nx,ny)`
+ * then a point left on the edge, so the outline only ever bulges outward,
+ * never pinches in. The corner points that bracket each edge are pushed by
+ * the caller; this adds only the between-corner bumps.
+ *
+ * Below two intervals there are no bumps — the edge stays a straight
+ * spline chord.
+ */
+function pushWaves(pts, ax, ay, bx, by, nx, ny) {
+    const dist = Math.hypot(bx - ax, by - ay);
+    const n = Math.floor(dist / WAVE_INTERVAL);
+    if (n < 2)
+        return;
+    const ux = (bx - ax) / dist, uy = (by - ay) / dist;
+    const seg = dist / n;
+    for (let i = 1; i < n; i++) {
+        const px = ax + ux * seg * i, py = ay + uy * seg * i;
+        // Odd steps bulge out, even steps stay on the edge.
+        if (i % 2 === 1)
+            pts.push({ x: px + nx * WAVE_AMP, y: py + ny * WAVE_AMP });
+        else
+            pts.push({ x: px, y: py });
+    }
+}
+/**
+ * Render a ring of waypoints as one smooth closed (or open) loop: a
+ * Catmull-Rom curve through every point, each segment converted to a cubic
+ * Bezier with control points `p +/- (next-prev)*t/3`; `t = SPLINE_TENSION`.
+ * `open` leaves a gap between the last and first point (the bottom stretch a
+ * tail bridges); otherwise the loop closes on itself. Assumes the path is
+ * already open and positions the current point itself.
+ */
+function strokeCardinal(ctx, pts, open) {
+    const n = pts.length;
+    if (n < 2)
+        return;
+    const f = SPLINE_TENSION / 3;
+    const at = (i) => open ? pts[Math.min(Math.max(i, 0), n - 1)] : pts[(i + n) % n];
+    ctx.moveTo(pts[0].x, pts[0].y);
+    const last = open ? n - 1 : n;
+    for (let i = 0; i < last; i++) {
+        const p0 = at(i - 1), p1 = at(i), p2 = at(i + 1), p3 = at(i + 2);
+        ctx.bezierCurveTo(p1.x + (p2.x - p0.x) * f, p1.y + (p2.y - p0.y) * f, p2.x - (p3.x - p1.x) * f, p2.y - (p3.y - p1.y) * f, p2.x, p2.y);
+    }
+}
+/**
+ * A speech balloon: a hand-drawn outline with a bowed tail rooted on the
+ * bottom edge. The tail always leaves the bottom edge, never a side, its
+ * root sliding along that edge to sit under the speaker, bowed as two curves
+ * with a sharp tip (kept off the body spline so the point stays crisp). A
+ * 45-degree-from-vertical clamp keeps a head off to the side from dragging
+ * the tip out past a readable angle.
+ */
+function roundedSpeech(ctx, box, target) {
+    const { x, y, width: w, height: h } = box;
+    const right = x + w, bottom = y + h;
+    if (!target) {
+        // No speaker: one closed ring — top, right, bottom, left — all corners
+        // and bumps splined together into a plain blob.
+        const ring = [];
+        ring.push({ x, y });
+        pushWaves(ring, x, y, right, y, 0, -1); // top, bulging up
+        ring.push({ x: right, y });
+        pushWaves(ring, right, y, right, bottom, 1, 0); // right, bulging right
+        ring.push({ x: right, y: bottom });
+        pushWaves(ring, right, bottom, x, bottom, 0, 1); // bottom, bulging down
+        ring.push({ x, y: bottom });
+        pushWaves(ring, x, bottom, x, y, -1, 0); // left, bulging left
+        ctx.beginPath();
+        strokeCardinal(ctx, ring, false);
+        ctx.closePath();
+        return;
+    }
+    // Tail roots ride the bottom edge under the head, far enough from a corner
+    // that both roots stay on the flat run.
+    const root = Math.min(Math.max(target.x, x + 16), right - 16);
+    const rootR = root + 9, rootL = root - 9;
+    const tipY = Math.max(target.y, bottom + TAIL_MIN_EXIT);
+    // 45-degree clamp: the tip's horizontal run may not exceed its vertical
+    // drop, so a side speaker cannot flatten the tail.
+    const dy = tipY - bottom;
+    const tipX = Math.min(Math.max(target.x, root - dy), root + dy);
+    const alt = 0.05 * Math.hypot(tipX - root, dy); // bow depth
+    // Body ring, open along the bottom between the two roots: start at rootR,
+    // run the bottom out to the right corner, up and over and down, back along
+    // the bottom to rootL. The tail then bridges rootL->tip->rootR as sharp quads.
+    const ring = [];
+    ring.push({ x: rootR, y: bottom });
+    pushWaves(ring, rootR, bottom, right, bottom, 0, 1); // bottom, right of the tail
+    ring.push({ x: right, y: bottom });
+    pushWaves(ring, right, bottom, right, y, 1, 0); // right, bulging right
+    ring.push({ x: right, y });
+    pushWaves(ring, right, y, x, y, 0, -1); // top, bulging up
+    ring.push({ x, y });
+    pushWaves(ring, x, y, x, bottom, -1, 0); // left, bulging left
+    ring.push({ x, y: bottom });
+    pushWaves(ring, x, bottom, rootL, bottom, 0, 1); // bottom, left of the tail
+    ring.push({ x: rootL, y: bottom });
+    ctx.beginPath();
+    strokeCardinal(ctx, ring, true); // ends at rootL (current point)
+    ctx.quadraticCurveTo((rootL + tipX) / 2 - alt, (bottom + tipY) / 2, tipX, tipY);
+    ctx.quadraticCurveTo((tipX + rootR) / 2 + alt, (tipY + bottom) / 2, rootR, bottom);
+    ctx.closePath();
+}

package/dist/cast-manifest.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The pack contract: what an asset pack ships and what the renderer reads.
+ *
+ * Types only. A complex character composites faces onto torsos at draw time
+ * (one face x one torso = one figure), so a pack ships parts, not baked
+ * figures — the join is the few lines of arithmetic in {@link figureFor}, and
+ * keeping parts separate is what lets {@link PoseCycle} round-robin distinct
+ * pairings instead of freezing one drawing per emotion.
+ */
+/** A rectangle within a sprite sheet. */
+export interface SheetRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** One drawing in a sheet, plus everything the face/torso join needs. */
+export interface PackedPart {
+    kind: "face" | "torso" | "body";
+    index: number;
+    emotion: string;
+    angle: number;
+    intensity: number;
+    /** Neck socket (torso), or its counterpart inside the face image. */
+    cx: number;
+    cy: number;
+    /** Per-face nudge on the socket — a tilted head, a thrown-back laugh. */
+    cxDelta: number;
+    cyDelta: number;
+    /** Where a balloon tail attaches. */
+    x: number;
+    figure: SheetRect;
+    /** The halo, when the pose has one. Drawn before any figure. */
+    aura: SheetRect | null;
+}
+export interface PackedAvatar {
+    name: string;
+    type: string;
+    /** Whether the torso is drawn over the face's collar, or under it. */
+    torsoFirst: boolean;
+    sheet: string;
+    sheetWidth: number;
+    sheetHeight: number;
+    faces: PackedPart[];
+    torsos: PackedPart[];
+    /** Simple avatars only; complex avatars leave this empty. */
+    bodies: PackedPart[];
+}
+export interface PackedBackdrop {
+    id: string;
+    file: string;
+    width: number;
+    height: number;
+}
+export interface CastManifest {
+    version: 1;
+    /** Character id (a {@link "@toonstrip/schema".Body.character}) → avatar. */
+    cast: Record<string, PackedAvatar>;
+    backdrops: PackedBackdrop[];
+}

package/dist/cast-manifest.js

@@ -0,0 +1,10 @@
+/**
+ * The pack contract: what an asset pack ships and what the renderer reads.
+ *
+ * Types only. A complex character composites faces onto torsos at draw time
+ * (one face x one torso = one figure), so a pack ships parts, not baked
+ * figures — the join is the few lines of arithmetic in {@link figureFor}, and
+ * keeping parts separate is what lets {@link PoseCycle} round-robin distinct
+ * pairings instead of freezing one drawing per emotion.
+ */
+export {};

package/dist/emotion.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The emotion wheel's fixed points: an angle (which emotion), an intensity
+ * 0.0-1.0 (how much), and eight gesture sentinels placed outside the wheel's
+ * metric so a gesture never nearest-neighbour-matches a facial expression.
+ */
+export interface Emotion {
+    /** Radians on the wheel, or a gesture sentinel above 2*PI. */
+    angle: number;
+    /** 0.0-1.0. */
+    intensity: number;
+}
+/** One weighted candidate emotion. Higher priority is tried first. */
+export interface EmotionOption extends Emotion {
+    priority: number;
+}
+export declare const EMOTION_NAMES: readonly [null, "HAPPY", "COY", "BORED", "SCARED", "SAD", "ANGRY", "SHOUT", "LAUGH", "NEUTRAL", "WAVE", "POINTOTHER", "POINTSELF", "DOUBLEPOINT", "SHRUG", "3QRWALK", "SIDEWALK", "3QFWALK"];
+export type EmotionName = Exclude<(typeof EMOTION_NAMES)[number], null>;
+/** Points on the emotion wheel that have an angle. */
+export declare const NEMOTIONS = 8;
+/**
+ * Named-emotion index to runtime angle. Indices 1-8 are angles around the
+ * wheel; 9 (NEUTRAL) is 0.0, the same angle as HAPPY, distinguished only by
+ * intensity 0. The eight gestures (10-17) are sentinels above 2*PI,
+ * deliberately outside the angular metric.
+ */
+export declare const EMOTION_ANGLES: readonly number[];
+export declare function emotionAngle(index: number): number;
+/** True for the gesture sentinels, which no angular metric can reach. */
+export declare function isGesture(angle: number): boolean;

package/dist/emotion.js

@@ -0,0 +1,38 @@
+/**
+ * The emotion wheel's fixed points: an angle (which emotion), an intensity
+ * 0.0-1.0 (how much), and eight gesture sentinels placed outside the wheel's
+ * metric so a gesture never nearest-neighbour-matches a facial expression.
+ */
+export const EMOTION_NAMES = [
+    null, "HAPPY", "COY", "BORED", "SCARED", "SAD", "ANGRY", "SHOUT", "LAUGH",
+    "NEUTRAL", "WAVE", "POINTOTHER", "POINTSELF", "DOUBLEPOINT", "SHRUG",
+    "3QRWALK", "SIDEWALK", "3QFWALK",
+];
+/** Points on the emotion wheel that have an angle. */
+export const NEMOTIONS = 8;
+/**
+ * Named-emotion index to runtime angle. Indices 1-8 are angles around the
+ * wheel; 9 (NEUTRAL) is 0.0, the same angle as HAPPY, distinguished only by
+ * intensity 0. The eight gestures (10-17) are sentinels above 2*PI,
+ * deliberately outside the angular metric.
+ */
+export const EMOTION_ANGLES = [
+    0, // index 0 unused
+    (0 * 2 * Math.PI) / 8, // HAPPY
+    (1 * 2 * Math.PI) / 8, // COY
+    (2 * 2 * Math.PI) / 8, // BORED
+    (3 * 2 * Math.PI) / 8, // SCARED
+    (4 * 2 * Math.PI) / 8, // SAD
+    (5 * 2 * Math.PI) / 8, // ANGRY
+    (6 * 2 * Math.PI) / 8, // SHOUT
+    (7 * 2 * Math.PI) / 8, // LAUGH
+    0.0, // NEUTRAL — same angle as HAPPY by design
+    1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, // gesture sentinels
+];
+export function emotionAngle(index) {
+    return EMOTION_ANGLES[index] ?? 0;
+}
+/** True for the gesture sentinels, which no angular metric can reach. */
+export function isGesture(angle) {
+    return angle > 2 * Math.PI;
+}

package/dist/figure.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Figures: pose selection and the face-onto-torso join.
+ *
+ * A complex character's poses are not baked figures — a face and a torso are
+ * separate drawings, composited at draw time — so what is left at render
+ * time is the emotion wheel (pure arithmetic, `./pose.js`) plus the join
+ * geometry below, re-expressed as `drawImage` calls against a sprite sheet.
+ */
+import type { EmotionOption } from "./emotion.js";
+import type { CastManifest, PackedAvatar, PackedPart } from "./cast-manifest.js";
+/** A drawable sheet image — an `HTMLImageElement`/`ImageBitmap` in a browser,
+ *  an `@napi-rs/canvas` `Image` in Node. Anything `drawImage` accepts. */
+export type SheetImage = CanvasImageSource;
+export interface Cast {
+    manifest: CastManifest;
+    /** Character id -> decoded sheet, ready for `drawImage`. */
+    sheets: Map<string, SheetImage>;
+    backdrops: Map<string, SheetImage>;
+}
+/** A chosen figure: which parts, and the box they occupy in figure space. */
+export interface Figure {
+    avatar: PackedAvatar;
+    face: PackedPart;
+    torso: PackedPart;
+    width: number;
+    height: number;
+    /** Where the head ends, from the top — the balloon tail's vertical target. */
+    headHeight: number;
+    /** Horizontal anchor for a balloon tail. */
+    faceX: number;
+    facePos: {
+        x: number;
+        y: number;
+    };
+    torsoPos: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Per-character memory for the round-robin: begin the scan after the pose
+ * used last, so a repeated emotion cycles through whatever variants exist
+ * instead of returning the same drawing forever.
+ */
+export interface PoseCycle {
+    face: number;
+    torso: number;
+}
+export declare function newCycle(): PoseCycle;
+/**
+ * Choose a figure for an emotion set and assemble its geometry. The face
+ * lands at `torso.cx + face.cxDelta - face.cx`, and the union box may extend
+ * above and left of the torso, so everything is rebased onto it.
+ */
+export declare function figureFor(avatar: PackedAvatar, options: readonly EmotionOption[], cycle: PoseCycle): Figure | null;
+/**
+ * Draw a figure at `(x, y)`, scaled uniformly — a face never scales
+ * differently from the torso it is composited onto. Compositing happens in
+ * figure space; the viewport scale is applied afterwards, here, to the
+ * assembled result.
+ *
+ * Draw order: both halos before either figure, then `torsoFirst` decides
+ * whether the collar sits over the jaw.
+ */
+export declare function drawFigure(ctx: CanvasRenderingContext2D, sheet: CanvasImageSource, figure: Figure, x: number, y: number, scale: number, mirror?: boolean): void;

package/dist/figure.js

@@ -0,0 +1,93 @@
+/**
+ * Figures: pose selection and the face-onto-torso join.
+ *
+ * A complex character's poses are not baked figures — a face and a torso are
+ * separate drawings, composited at draw time — so what is left at render
+ * time is the emotion wheel (pure arithmetic, `./pose.js`) plus the join
+ * geometry below, re-expressed as `drawImage` calls against a sprite sheet.
+ */
+import { selectComplexPose } from "./pose.js";
+export function newCycle() {
+    return { face: -1, torso: -1 };
+}
+function rotate(items, start) {
+    if (items.length === 0)
+        return [];
+    const from = ((start % items.length) + items.length) % items.length;
+    return [...items.slice(from), ...items.slice(0, from)];
+}
+/**
+ * Choose a figure for an emotion set and assemble its geometry. The face
+ * lands at `torso.cx + face.cxDelta - face.cx`, and the union box may extend
+ * above and left of the torso, so everything is rebased onto it.
+ */
+export function figureFor(avatar, options, cycle) {
+    const faces = rotate(avatar.faces, cycle.face + 1);
+    const torsos = rotate(avatar.torsos, cycle.torso + 1);
+    const chosen = selectComplexPose(faces, torsos, options);
+    const face = chosen.face;
+    const torso = chosen.torso;
+    if (!face || !torso)
+        return null;
+    cycle.face = avatar.faces.indexOf(face);
+    cycle.torso = avatar.torsos.indexOf(torso);
+    const xOffset = torso.cx + face.cxDelta - face.cx;
+    const yOffset = torso.cy + face.cyDelta - face.cy;
+    const left = Math.min(0, xOffset);
+    const top = Math.min(0, yOffset);
+    const right = Math.max(torso.figure.width, xOffset + face.figure.width);
+    const bottom = Math.max(torso.figure.height, yOffset + face.figure.height);
+    const facePos = { x: xOffset - left, y: yOffset - top };
+    const torsoPos = { x: -left, y: -top };
+    return {
+        avatar, face, torso,
+        width: right - left,
+        height: bottom - top,
+        headHeight: yOffset + face.figure.height - top,
+        faceX: face.x + xOffset - left,
+        facePos, torsoPos,
+    };
+}
+/**
+ * Draw a figure at `(x, y)`, scaled uniformly — a face never scales
+ * differently from the torso it is composited onto. Compositing happens in
+ * figure space; the viewport scale is applied afterwards, here, to the
+ * assembled result.
+ *
+ * Draw order: both halos before either figure, then `torsoFirst` decides
+ * whether the collar sits over the jaw.
+ */
+export function drawFigure(ctx, sheet, figure, x, y, scale, mirror = false) {
+    const { face, torso, facePos, torsoPos } = figure;
+    // `mirror` flips the figure horizontally about its own box so it faces the
+    // other way — in a two-shot the right-hand figure is mirrored so the two
+    // look at each other instead of both facing out. Done with a transform
+    // rather than per-part x maths so the face/torso join flips as one unit.
+    ctx.save();
+    if (mirror) {
+        ctx.translate(x + figure.width * scale, y);
+        ctx.scale(-1, 1);
+    }
+    else {
+        ctx.translate(x, y);
+    }
+    const part = (p, rect, pos) => {
+        if (!rect)
+            return;
+        ctx.drawImage(sheet, rect.x, rect.y, rect.width, rect.height, 
+        // The aura rect and the figure rect share dimensions (packed as a pair),
+        // so one placement serves both.
+        pos.x * scale, pos.y * scale, rect.width * scale, rect.height * scale);
+    };
+    part(torso, torso.aura, torsoPos);
+    part(face, face.aura, facePos);
+    if (figure.avatar.torsoFirst) {
+        part(torso, torso.figure, torsoPos);
+        part(face, face.figure, facePos);
+    }
+    else {
+        part(face, face.figure, facePos);
+        part(torso, torso.figure, torsoPos);
+    }
+    ctx.restore();
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./cast-manifest.js";
+export * from "./emotion.js";
+export * from "./pose.js";
+export * from "./layout.js";
+export { BALLOON_FONT, LINE_HEIGHT, ONE_LINE_THRESHOLD, AREA_FUDGE, CONTINUATION, widestWord, goalWidth, measureBalloon, chromeFor, measureAtWidth, splitHeight, drawBalloon, type BalloonBox, type TailTarget, } from "./balloon.js";
+export * from "./balloon-layout.js";
+export * from "./figure.js";
+export * from "./render.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./cast-manifest.js";
+export * from "./emotion.js";
+export * from "./pose.js";
+export * from "./layout.js";
+export { BALLOON_FONT, LINE_HEIGHT, ONE_LINE_THRESHOLD, AREA_FUDGE, CONTINUATION, widestWord, goalWidth, measureBalloon, chromeFor, measureAtWidth, splitHeight, drawBalloon, } from "./balloon.js";
+export * from "./balloon-layout.js";
+export * from "./figure.js";
+export * from "./render.js";