@toonstrip/core 0.1.0

package/dist/layout.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Panel sequencing: the responsive column-count-from-available-width policy.
+ *
+ * Every panel renders at a fixed native size and never stretches above it —
+ * a figure that composed differently at every viewport width would be an
+ * authoring instability. Column count reflows instead: a width that cannot
+ * hold another native panel earns one anyway if the row can shrink to within
+ * {@link MIN_PANEL_SCALE} of native, and a viewport narrower than one native
+ * panel fits the single column down to whatever width is available.
+ */
+/** Native panel size — the art is ~400x400, so this is the 1:1 point. */
+export declare const UNIT: {
+    width: number;
+    height: number;
+};
+/** The column ceiling on a wide viewport — a decision, not a fit result. */
+export declare const MAX_COLUMNS = 3;
+/**
+ * Shrink tolerance: the floor a panel may shrink to *in order to earn
+ * another column*. Not a floor on a lone panel — a viewport too narrow for
+ * even one native panel gets a straight fit-down (see {@link layoutStrip}),
+ * which can go below this.
+ */
+export declare const MIN_PANEL_SCALE = 0.85;
+export interface StripLayout {
+    /** Panels per row. Always at least 1. */
+    columns: number;
+    /** CSS-pixel width of one panel. */
+    panelWidth: number;
+    /** CSS-pixel height of one panel, at the native aspect. */
+    panelHeight: number;
+}
+export interface LayoutOptions {
+    /** Space between panels, both axes. */
+    gutter?: number;
+    /** Ceiling on columns; defaults to {@link MAX_COLUMNS}. */
+    maxColumns?: number;
+}
+/**
+ * How many panels fit across `available` pixels, fit against
+ * {@link MIN_PANEL_SCALE} of the native unit width rather than the unit
+ * itself — so a width that cannot hold two *native* panels but can hold two
+ * shrunk to >= 0.85 native still earns the two-up layout. {@link layoutStrip}
+ * fills in the actual share width afterward.
+ */
+export declare function columnsFor(available: number, gutter: number, maxColumns?: number): number;
+/**
+ * The strip's geometry at a given container width. The panel width resolves
+ * to one of three cases:
+ *
+ * - **Native.** `share >= UNIT.width`: the panel sits at native and the row
+ *   is centred in its leftover. The common case above one column's worth of
+ *   space.
+ * - **Shrink-to-earn-a-column.** `0.85*UNIT.width <= share < UNIT.width`:
+ *   arises because {@link columnsFor} fit the extra column against
+ *   {@link MIN_PANEL_SCALE}; panels shrink to the share so both fit.
+ * - **Fit-down.** One column narrower than a native panel: the lone panel
+ *   scales down to fit rather than overflow. The only case that may drop
+ *   below 0.85.
+ */
+export declare function layoutStrip(available: number, options?: LayoutOptions): StripLayout;
+/**
+ * Which cell a panel occupies. Kept as its own function because it is the
+ * half of the policy that says *reading order is row-major* — the strip's
+ * DOM order and the grid's flow have to agree with it or a resize would
+ * renumber the comic.
+ */
+export declare function cellFor(index: number, columns: number): {
+    row: number;
+    column: number;
+};

package/dist/layout.js

@@ -0,0 +1,71 @@
+/**
+ * Panel sequencing: the responsive column-count-from-available-width policy.
+ *
+ * Every panel renders at a fixed native size and never stretches above it —
+ * a figure that composed differently at every viewport width would be an
+ * authoring instability. Column count reflows instead: a width that cannot
+ * hold another native panel earns one anyway if the row can shrink to within
+ * {@link MIN_PANEL_SCALE} of native, and a viewport narrower than one native
+ * panel fits the single column down to whatever width is available.
+ */
+/** Native panel size — the art is ~400x400, so this is the 1:1 point. */
+export const UNIT = { width: 400, height: 340 };
+/** The column ceiling on a wide viewport — a decision, not a fit result. */
+export const MAX_COLUMNS = 3;
+/**
+ * Shrink tolerance: the floor a panel may shrink to *in order to earn
+ * another column*. Not a floor on a lone panel — a viewport too narrow for
+ * even one native panel gets a straight fit-down (see {@link layoutStrip}),
+ * which can go below this.
+ */
+export const MIN_PANEL_SCALE = 0.85;
+/**
+ * How many panels fit across `available` pixels, fit against
+ * {@link MIN_PANEL_SCALE} of the native unit width rather than the unit
+ * itself — so a width that cannot hold two *native* panels but can hold two
+ * shrunk to >= 0.85 native still earns the two-up layout. {@link layoutStrip}
+ * fills in the actual share width afterward.
+ */
+export function columnsFor(available, gutter, maxColumns = MAX_COLUMNS) {
+    const minWidth = UNIT.width * MIN_PANEL_SCALE;
+    const fit = Math.floor((available + gutter) / (minWidth + gutter));
+    return Math.max(1, Math.min(fit, maxColumns));
+}
+/**
+ * The strip's geometry at a given container width. The panel width resolves
+ * to one of three cases:
+ *
+ * - **Native.** `share >= UNIT.width`: the panel sits at native and the row
+ *   is centred in its leftover. The common case above one column's worth of
+ *   space.
+ * - **Shrink-to-earn-a-column.** `0.85*UNIT.width <= share < UNIT.width`:
+ *   arises because {@link columnsFor} fit the extra column against
+ *   {@link MIN_PANEL_SCALE}; panels shrink to the share so both fit.
+ * - **Fit-down.** One column narrower than a native panel: the lone panel
+ *   scales down to fit rather than overflow. The only case that may drop
+ *   below 0.85.
+ */
+export function layoutStrip(available, options = {}) {
+    const gutter = options.gutter ?? 10;
+    // A container that has not been measured yet reports 0; fall back to the
+    // unit rather than dividing a row into a zero-width panel.
+    const width = available > 0 ? available : UNIT.width;
+    const columns = columnsFor(width, gutter, options.maxColumns);
+    const share = (width - (columns - 1) * gutter) / columns;
+    // Native is the ceiling — never a free stretch.
+    const panelWidth = Math.max(1, Math.min(share, UNIT.width));
+    return {
+        columns,
+        panelWidth,
+        panelHeight: Math.round((panelWidth / UNIT.width) * UNIT.height),
+    };
+}
+/**
+ * Which cell a panel occupies. Kept as its own function because it is the
+ * half of the policy that says *reading order is row-major* — the strip's
+ * DOM order and the grid's flow have to agree with it or a resize would
+ * renumber the comic.
+ */
+export function cellFor(index, columns) {
+    return { row: Math.floor(index / columns), column: index % columns };
+}

package/dist/pose.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pose selection: mapping a requested emotion onto the poses a character
+ * owns. Selection is nearest-neighbour on the emotion wheel, which is why a
+ * character never needs a pose for every emotion — a request resolves to
+ * whatever the pack actually shipped.
+ *
+ * Generic over `T extends Emotion` rather than fixed to a pack-format record:
+ * selection only ever reads an angle and an intensity, never a byte offset or
+ * a palette, so any manifest entry that carries `{ angle, intensity }` can be
+ * passed straight through.
+ */
+import { type Emotion, type EmotionOption } from "./emotion.js";
+/** Normalize into (-PI, PI]. */
+export declare function normalizeAngle(value: number): number;
+export declare function subtractAngles(a: number, b: number): number;
+/**
+ * Nearest pose by angle, then by intensity. Used for faces, which always
+ * resolve to something: a character with one face still has to render.
+ */
+export declare function nearestByAngle<T extends Emotion>(records: readonly T[], want: Emotion): T | undefined;
+/**
+ * Nearest torso or body: a gated search — a candidate must fall inside the
+ * wheel segment, or be a resting neutral, to be considered at all. A torso
+ * can therefore fail to match, and the caller falls back to neutral.
+ *
+ * `start` implements a round-robin: the scan begins after the pose used
+ * last, so a repeated identical emotion cycles through whatever variants
+ * exist instead of freezing on one drawing.
+ */
+export declare function nearestGated<T extends Emotion>(records: readonly T[], want: Emotion, start?: number): T | undefined;
+export declare function firstNeutral<T extends Emotion>(records: readonly T[]): T | undefined;
+/**
+ * Resolve one emotion to a face *or* a torso. An emotion on the wheel is a
+ * facial expression and resolves against faces; a gesture (wave, shrug, ...)
+ * is a body posture and resolves against torsos by exact match, since no
+ * angular metric applies to a sentinel. One request therefore constrains one
+ * half of the figure and leaves the other free — a character can wave while
+ * looking sad.
+ */
+export declare function headAndTorsoFor<T extends Emotion>(faces: readonly T[], torsos: readonly T[], want: Emotion): {
+    face?: T;
+    torso?: T;
+};
+/**
+ * Resolve a *set* of weighted candidate emotions to a face and a torso.
+ *
+ * Options are consumed highest-priority first; the first that yields a face
+ * fixes the face, the first that yields a torso fixes the torso, and the
+ * scan stops once both are filled. Anything still unfilled falls back to
+ * neutral. This is how a gesture (which only ever fills a torso) and a
+ * facial emotion (which only ever fills a face) combine into one figure from
+ * one caller-supplied option set.
+ */
+export declare function selectComplexPose<T extends Emotion>(faces: readonly T[], torsos: readonly T[], options: readonly EmotionOption[]): {
+    face?: T;
+    torso?: T;
+};
+/** Resolve a single emotion to a face and a torso — the common path. */
+export declare function selectPose<T extends Emotion>(faces: readonly T[], torsos: readonly T[], want: Emotion, lastTorso?: number): {
+    face?: T;
+    torso?: T;
+};
+/** Simple characters have one image per pose; the same gated search applies. */
+export declare function selectBody<T extends Emotion>(bodies: readonly T[], want: Emotion, lastBody?: number): T | undefined;

package/dist/pose.js

@@ -0,0 +1,165 @@
+/**
+ * Pose selection: mapping a requested emotion onto the poses a character
+ * owns. Selection is nearest-neighbour on the emotion wheel, which is why a
+ * character never needs a pose for every emotion — a request resolves to
+ * whatever the pack actually shipped.
+ *
+ * Generic over `T extends Emotion` rather than fixed to a pack-format record:
+ * selection only ever reads an angle and an intensity, never a byte offset or
+ * a palette, so any manifest entry that carries `{ angle, intensity }` can be
+ * passed straight through.
+ */
+import { NEMOTIONS, isGesture } from "./emotion.js";
+/** Normalize into (-PI, PI]. */
+export function normalizeAngle(value) {
+    if (value > -Math.PI && value <= Math.PI)
+        return value;
+    let t = value / (2 * Math.PI);
+    t = (t - Math.trunc(t)) * 2 * Math.PI;
+    if (t > Math.PI)
+        return t - 2 * Math.PI;
+    if (t <= -Math.PI)
+        return t + 2 * Math.PI;
+    return t;
+}
+export function subtractAngles(a, b) {
+    return normalizeAngle(a - b);
+}
+/**
+ * How far a pose may sit from the request and still be considered: half a
+ * wheel segment in each direction, so the eight segments tile the circle.
+ */
+const ANGLE_TOLERANCE = Math.PI / NEMOTIONS;
+const isNeutral = (rec) => rec.angle === 0 && rec.intensity === 0;
+/**
+ * Nearest pose by angle, then by intensity. Used for faces, which always
+ * resolve to something: a character with one face still has to render.
+ */
+export function nearestByAngle(records, want) {
+    let best;
+    let bestAngle = 3 * Math.PI;
+    let bestIntensity = 2.0;
+    for (const rec of records) {
+        const angle = Math.abs(subtractAngles(rec.angle, want.angle));
+        if (angle > bestAngle)
+            continue;
+        const intensity = Math.abs(want.intensity - rec.intensity);
+        if (angle === bestAngle && intensity >= bestIntensity)
+            continue;
+        bestAngle = angle;
+        bestIntensity = intensity;
+        best = rec;
+    }
+    return best;
+}
+/**
+ * Nearest torso or body: a gated search — a candidate must fall inside the
+ * wheel segment, or be a resting neutral, to be considered at all. A torso
+ * can therefore fail to match, and the caller falls back to neutral.
+ *
+ * `start` implements a round-robin: the scan begins after the pose used
+ * last, so a repeated identical emotion cycles through whatever variants
+ * exist instead of freezing on one drawing.
+ */
+export function nearestGated(records, want, start = 0) {
+    let best;
+    let bestIntensity = 2.0;
+    const n = records.length;
+    for (let i = 0; i < n; i++) {
+        const rec = records[(start + i) % n];
+        // Gestures are sentinels above 2*PI; the angular metric cannot reach them.
+        if (isGesture(rec.angle))
+            continue;
+        const angle = Math.abs(subtractAngles(rec.angle, want.angle));
+        const firstNeutralMatch = isNeutral(rec) && best === undefined;
+        if (angle >= ANGLE_TOLERANCE && !firstNeutralMatch)
+            continue;
+        // A resting neutral standing in for a felt emotion is a weak match, but a
+        // legal one — rank it behind anything that actually matched.
+        const intensity = firstNeutralMatch && want.intensity > 0
+            ? 1.5
+            : Math.abs(want.intensity - rec.intensity);
+        if (intensity >= bestIntensity)
+            continue;
+        bestIntensity = intensity;
+        best = rec;
+    }
+    return best;
+}
+export function firstNeutral(records) {
+    return records.find(isNeutral) ?? records[0];
+}
+/**
+ * Resolve one emotion to a face *or* a torso. An emotion on the wheel is a
+ * facial expression and resolves against faces; a gesture (wave, shrug, ...)
+ * is a body posture and resolves against torsos by exact match, since no
+ * angular metric applies to a sentinel. One request therefore constrains one
+ * half of the figure and leaves the other free — a character can wave while
+ * looking sad.
+ */
+export function headAndTorsoFor(faces, torsos, want) {
+    if (!isGesture(want.angle)) {
+        const face = nearestByAngle(faces, want);
+        return face ? { face } : {};
+    }
+    const torso = torsos.find((rec) => rec.angle === want.angle);
+    return torso ? { torso } : {};
+}
+/**
+ * Resolve a *set* of weighted candidate emotions to a face and a torso.
+ *
+ * Options are consumed highest-priority first; the first that yields a face
+ * fixes the face, the first that yields a torso fixes the torso, and the
+ * scan stops once both are filled. Anything still unfilled falls back to
+ * neutral. This is how a gesture (which only ever fills a torso) and a
+ * facial emotion (which only ever fills a face) combine into one figure from
+ * one caller-supplied option set.
+ */
+export function selectComplexPose(faces, torsos, options) {
+    const remaining = options.map((o) => ({ ...o }));
+    let face;
+    let torso;
+    for (;;) {
+        let best;
+        for (const option of remaining) {
+            if (option.priority > (best?.priority ?? 0))
+                best = option;
+        }
+        if (!best)
+            break;
+        best.priority = 0;
+        const found = headAndTorsoFor(faces, torsos, best);
+        face ??= found.face;
+        torso ??= found.torso;
+        if (face && torso)
+            break;
+    }
+    face ??= firstNeutral(faces);
+    torso ??= firstNeutral(torsos);
+    const out = {};
+    if (face)
+        out.face = face;
+    if (torso)
+        out.torso = torso;
+    return out;
+}
+/** Resolve a single emotion to a face and a torso — the common path. */
+export function selectPose(faces, torsos, want, lastTorso = -1) {
+    const face = nearestByAngle(faces, want);
+    const torso = nearestGated(torsos, want, (lastTorso + 1) % Math.max(1, torsos.length))
+        ?? firstNeutral(torsos);
+    const out = {};
+    if (face)
+        out.face = face;
+    if (torso)
+        out.torso = torso;
+    return out;
+}
+/** Simple characters have one image per pose; the same gated search applies. */
+export function selectBody(bodies, want, lastBody = -1) {
+    if (isGesture(want.angle)) {
+        return bodies.find((rec) => rec.angle === want.angle) ?? firstNeutral(bodies);
+    }
+    return nearestGated(bodies, want, (lastBody + 1) % Math.max(1, bodies.length))
+        ?? firstNeutral(bodies);
+}

package/dist/render.d.ts

@@ -0,0 +1,190 @@
+/**
+ * A panel, drawn. The renderer is a pure function of a {@link Panel} plus the
+ * cast: it reads no external state, which is what makes it testable in Node
+ * without a caller-side game loop or session — a shot arrives as a name
+ * (`establishing`, `close-up`) chosen by the caller, and this file decides
+ * what that shot looks like at the current panel size.
+ */
+import type { Body, Line, Panel } from "@toonstrip/schema";
+import { type Cast, type Figure, type PoseCycle } from "./figure.js";
+import { type BalloonBox } from "./balloon.js";
+import { type Rect } from "./balloon-layout.js";
+/** The bodiless caption channel — a line with no speaking body. */
+export declare const CAPTION = "caption";
+/** A camera preset, as the numbers a render needs. */
+type Shot = {
+    /** How much of the backdrop is visible behind the figures. */
+    backdrop: number;
+} & (
+/** Figure height as a fraction of panel height — the ordinary case. */
+{
+    fill: number;
+    /** Vertical framing: 1 shows the whole figure, lower crops toward the head. */
+    reveal: number;
+    headFill?: never;
+    headTop?: never;
+}
+/**
+ * *Head* height as a fraction of panel height, for a rung tight enough
+ * that the head is the shot. Not interchangeable with `fill`, which scales
+ * by body height — a family of characters with different head-to-body
+ * ratios would get a different shot per character from `fill` alone.
+ */
+ | {
+    headFill: number;
+    /** Where the head-top sits, as a fraction of panel height. */
+    headTop: number;
+    fill?: never;
+    reveal?: never;
+});
+/**
+ * When a panel carries a speech or thought balloon, no figure may grow wider
+ * than this fraction of the panel — a speech balloon straddles the head from
+ * above, so it needs to be wider than the head to sit over it and still
+ * read. Left uncapped on a panel with no such balloon (a `reaction` beat,
+ * whose whole point is a face that fills the frame).
+ */
+export declare const MAX_FIGURE_WIDTH = 0.55;
+/**
+ * When a panel carries a speech or thought balloon, no head may grow taller
+ * than this fraction of the panel — `fill` scales a figure by its *body*
+ * height, but what a reader reads as "how close is this" is head size, and
+ * heads vary as a fraction of figure height across a cast. This is a
+ * per-figure clamp on top of `fill`, binding hardest at `close-up`.
+ */
+export declare const MAX_HEAD_HEIGHT = 0.38;
+/**
+ * Reserved band at the top of the panel for a straddling speech balloon and
+ * its tail. A speech balloon sits above its speaker and drops a near-
+ * vertical tail, which only works if the head is far enough down to leave
+ * room — so when such a balloon is present, a figure is pushed down until
+ * its head-top clears this fraction of the panel height.
+ */
+export declare const BALLOON_HEADROOM = 0.44;
+/** A laid-out body: its speaker id, figure, and placement in panel space. */
+export interface PlacedBody {
+    speaker: string;
+    figure: Figure;
+    x: number;
+    y: number;
+    scale: number;
+    mirror: boolean;
+}
+export interface RenderOptions {
+    /**
+     * Per-character pose cycles. Owned by the caller so that re-rendering the
+     * same panel (a resize, a re-paint) is idempotent, while a *new* panel
+     * advances the cycle. Without this split, a resize would silently redraw
+     * every panel with different bodies.
+     */
+    cycles?: Map<string, PoseCycle>;
+    /**
+     * Somewhere to record what this render placed. Purely an output: the
+     * renderer reads nothing from it and draws the same pixels whether or not
+     * it is passed. Useful for a visual-diff gate: the geometry that produced
+     * a change says *what* moved, which a pixel hash alone cannot.
+     */
+    trace?: PanelTrace;
+}
+/** What a render placed, in panel space. Filled in by {@link RenderOptions.trace}. */
+export interface PanelTrace {
+    bodies: Array<{
+        speaker: string;
+        x: number;
+        y: number;
+        scale: number;
+        mirror: boolean;
+    }>;
+    balloons: Array<{
+        speaker: string;
+        box: BalloonBox;
+        /** How the text broke — the count is enough to spot a re-wrap. */
+        lines: number;
+        /** Where the tail points, or `null` for a balloon that grows none. */
+        tail: {
+            x: number;
+            y: number;
+        } | null;
+    }>;
+    /** True when the balloon driver refused the panel and the stack fallback drew it. */
+    stacked: boolean;
+}
+export declare function renderPanel(ctx: CanvasRenderingContext2D, panel: Panel, cast: Cast, width: number, height: number, options?: RenderOptions): void;
+/** A body earns the stage if requested, or if it speaks this panel. */
+export declare function isSpeaker(body: Body, speakers: readonly Line[]): boolean;
+/**
+ * Stage order and facing. Order is stable by insertion (no talk-to graph
+ * exists to score a better one). Facing is scored: a body is charged for
+ * each neighbour it does not face and each neighbour that does not face it;
+ * reduced over a fixed row this means each body faces its **larger side** —
+ * the leftmost faces right, the rightmost faces left, and the row turns
+ * inward. An exact tie (the middle of an odd row) keeps the rightward default.
+ */
+export declare function orderBodies<T>(bodies: readonly T[]): Array<{
+    body: T;
+    flip: boolean;
+}>;
+/**
+ * Reserve the top band for a straddling speech balloon, and keep the head
+ * that sits under it small enough to leave a body in frame.
+ *
+ * 1. Push down to the band: a figure whose head-top is above
+ *    {@link BALLOON_HEADROOM} is moved down until it clears. A figure
+ *    already below the band is left alone.
+ * 2. Cap the head: with the head-top pinned, head size is the whole of "how
+ *    close are we", and `shot.fill` scales by *body* height — a poor proxy
+ *    across a cast whose head-to-body ratio varies. See {@link MAX_HEAD_HEIGHT}.
+ *
+ * Only figures the band actually pinned are capped, and they shrink about
+ * their own centre so the balloon column stays over them.
+ */
+export declare function applyHeadroom(placed: PlacedBody[], height: number): void;
+/**
+ * Place N bodies across the panel floor. Each body is scaled to the
+ * camera's fill height, normalized to a common target height across the
+ * cast. Widths are summed; if the row overruns the panel the whole set is
+ * reduced by one factor. Bodies are then spread with equal margins,
+ * including the two edges.
+ */
+export declare function layoutAvatars(bodies: ReadonlyArray<{
+    body: Body;
+    figure: Figure;
+}>, width: number, height: number, shot: Shot, widthCap?: number): PlacedBody[];
+/**
+ * Who is on stage in this panel, and posed how. Each figure's pose comes
+ * from its **own** body's emotion, so N participants pose independently,
+ * never sharing one panel emotion. Unknown character ids (no sheet, no
+ * manifest entry) are skipped.
+ *
+ * Exported because it is the step that advances `cycles`, and it takes no
+ * width — a caller that needs a panel's round-robin advanced without
+ * drawing it (a virtualized strip that stages every panel but paints only
+ * the ones on screen) can call this and get exactly what {@link renderPanel}
+ * would have consumed. Calling it mutates `cycles`; pass a copy to avoid that.
+ */
+export declare function selectFigures(panel: Panel, cast: Cast, cycles: Map<string, PoseCycle>): Array<{
+    body: Body;
+    figure: Figure;
+}>;
+export declare function fit(figure: Figure, height: number, fill: number, widthCap?: number, headFill?: number): number;
+/** The band balloons may occupy, from the panel's top down to {@link BALLOON_HEADROOM}. */
+export declare function balloonRect(width: number, height: number, titled?: boolean): Rect;
+/** The inset from the panel border. */
+export declare const BALLOON_MARGIN = 10;
+/** The location title's height, and the type it is set in. Not a balloon: no tail, no draw order. */
+export declare const TITLE_HEIGHT = 22;
+/** Draw the location title, clipped to the panel's width. */
+export declare function drawLocationTitle(ctx: CanvasRenderingContext2D, title: string, width: number): void;
+/**
+ * Slide a box horizontally until it no longer overlaps any face box, moving
+ * it toward whichever side needs less travel and still fits the panel. When
+ * the box is too wide to clear at all, it is left where it was and only
+ * nudged back inside the panel edges.
+ */
+export declare function clearOfFaces(x: number, y: number, w: number, h: number, bulge: number, faces: ReadonlyArray<{
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}>, width: number): number;
+export {};