@toonstrip/core 0.1.0

package/dist/balloon-layout.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The multi-balloon layout driver.
+ *
+ * Balloons in a panel are not stacked; each is placed over its own speaker
+ * and then squeezed out of the way of the balloons already placed, so every
+ * tail can still reach its head without crossing another balloon. That
+ * "without crossing" is the route region: a horizontal corridor each balloon
+ * reserves between itself and its speaker. A later balloon may not be placed
+ * inside a corridor an earlier one owns, and once placed it carves its own
+ * span out of theirs. When a balloon cannot be placed at all the *panel* is
+ * refused — the caller's signal to split the panel's lines across more than
+ * one panel.
+ *
+ * Coordinates are CSS px with y pointing down; `top` is the smaller y.
+ *
+ * **Determinism.** Two rolls (the width goal, the horizontal straddle) are
+ * drawn from a small deterministic PRNG seeded by the panel's own content
+ * ({@link panelSeed}), so a panel with the same speakers and text always
+ * lays out the same way and a caller can replay a strip exactly.
+ */
+import type { BalloonBox } from "./balloon.js";
+import type { Line } from "@toonstrip/schema";
+/** A rectangle in panel space, y down: `top` is the smaller y. */
+export interface Rect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/** The corridor a balloon reserves between itself and its speaker. */
+export interface RouteRgn {
+    left: number;
+    right: number;
+    bottom: number;
+}
+/** Measurement, injected so the driver itself never touches a canvas. */
+export interface BalloonMetrics {
+    /** The whole text on one line. */
+    oneLineWidth(text: string): number;
+    /** The floor a wrap may not go below. */
+    widestWord(text: string): number;
+    /** Reflow `text` into a box of exactly `boxWidth`. */
+    measure(text: string, boxWidth: number): {
+        lines: string[];
+        width: number;
+        height: number;
+    };
+    /** What fits in `boxHeight`, and the remainder. */
+    split(text: string, boxWidth: number, boxHeight: number): {
+        text: string;
+        rest: string | null;
+    };
+    /** Chrome each side, so the driver can tell when a span is too narrow to build. */
+    chrome: number;
+}
+/** One balloon offered to the driver, in the panel's draw order. */
+export interface BalloonInput {
+    /** Speaker id, so the caller can match a laid-out box back to its line. */
+    speaker: string;
+    /** A caption: pinned left, and it reserves no corridor. */
+    isBox: boolean;
+    /**
+     * The x a tail must reach, or `null` for a speaker with no body on stage
+     * (or a caption); such a balloon is placed like a caption and blocks
+     * nobody's route.
+     */
+    arrowX: number | null;
+    text: string;
+    metrics: BalloonMetrics;
+}
+/**
+ * The production {@link BalloonMetrics}: a real canvas, measuring in the
+ * balloon's own chrome. `ctx.font` must already be {@link "./balloon.js".BALLOON_FONT}
+ * — the caller sets it once for the whole panel.
+ */
+export declare function canvasMetrics(ctx: CanvasRenderingContext2D, balloon: Pick<Line, "balloon" | "text">): BalloonMetrics;
+/** A placed balloon: where it goes, how its text broke, what corridor it owns. */
+export interface LaidBalloon {
+    input: BalloonInput;
+    box: BalloonBox;
+    lines: readonly string[];
+    routeRgn: RouteRgn;
+}
+export type LayoutResult = {
+    fits: true;
+    balloons: LaidBalloon[];
+    leftover: string | null;
+} | {
+    fits: false;
+};
+/**
+ * A deterministic stand-in for `rand`: mulberry32, chosen because it is four
+ * lines and has no state to carry between panels. Every roll the driver
+ * makes comes from here, so a panel with the same content always lays out
+ * the same way.
+ */
+export declare function makeRandom(seed: number): () => number;
+/**
+ * The panel's seed, derived from its own content (FNV-1a over each speaker
+ * and line). Two panels that say the same thing lay out the same way, and a
+ * replayed panel lays out as it did the first time.
+ */
+export declare function panelSeed(inputs: readonly BalloonInput[]): number;
+/**
+ * Place every balloon in draw order, and give up on the whole panel the
+ * moment one will not go — except a panel holding exactly one balloon that
+ * will not fit, which is force-fitted into the free rect and split, since
+ * refusing it would refuse a panel a fresh, empty panel could not hold
+ * either.
+ */
+export declare function layoutBalloons(inputs: readonly BalloonInput[], freeRect: Rect, seed?: number): LayoutResult;

package/dist/balloon-layout.js

@@ -0,0 +1,286 @@
+/**
+ * The multi-balloon layout driver.
+ *
+ * Balloons in a panel are not stacked; each is placed over its own speaker
+ * and then squeezed out of the way of the balloons already placed, so every
+ * tail can still reach its head without crossing another balloon. That
+ * "without crossing" is the route region: a horizontal corridor each balloon
+ * reserves between itself and its speaker. A later balloon may not be placed
+ * inside a corridor an earlier one owns, and once placed it carves its own
+ * span out of theirs. When a balloon cannot be placed at all the *panel* is
+ * refused — the caller's signal to split the panel's lines across more than
+ * one panel.
+ *
+ * Coordinates are CSS px with y pointing down; `top` is the smaller y.
+ *
+ * **Determinism.** Two rolls (the width goal, the horizontal straddle) are
+ * drawn from a small deterministic PRNG seeded by the panel's own content
+ * ({@link panelSeed}), so a panel with the same speakers and text always
+ * lays out the same way and a caller can replay a strip exactly.
+ */
+import { AREA_FUDGE, LINE_HEIGHT, ONE_LINE_THRESHOLD, chromeFor, measureAtWidth, splitHeight, widestWord, } from "./balloon.js";
+/**
+ * The production {@link BalloonMetrics}: a real canvas, measuring in the
+ * balloon's own chrome. `ctx.font` must already be {@link "./balloon.js".BALLOON_FONT}
+ * — the caller sets it once for the whole panel.
+ */
+export function canvasMetrics(ctx, balloon) {
+    const as = (text) => text === balloon.text ? balloon : { ...balloon, text };
+    return {
+        chrome: chromeFor(balloon),
+        oneLineWidth: (text) => ctx.measureText(text).width,
+        widestWord: (text) => widestWord(ctx, text),
+        measure: (text, boxWidth) => measureAtWidth(ctx, as(text), boxWidth),
+        split: (text, boxWidth, boxHeight) => splitHeight(ctx, as(text), boxWidth, boxHeight),
+    };
+}
+/** The drop a tail needs below the balloon. */
+const MIN_HOOK_HEIGHT = 20;
+/** The width a corridor may not shrink past. */
+const MIN_ROUTE_WIDTH = 60;
+/**
+ * The lift taken off a previous balloon's box bottom before it becomes the
+ * next balloon's ceiling. Zero here: `box` is already the text box alone
+ * (a tail is drawn from it, not measured into it), so no separate overhang
+ * correction is needed.
+ */
+const DOCK_DELTA = 0;
+/** How far below the free rect's top a balloon nothing pushed down docks. */
+const TOP_BORDER = 4;
+/** The fudge a balloon's width goal is padded by, twice over, before being capped. */
+const WIDTH_FUDGE = 40;
+const LARGE = Infinity;
+/**
+ * A deterministic stand-in for `rand`: mulberry32, chosen because it is four
+ * lines and has no state to carry between panels. Every roll the driver
+ * makes comes from here, so a panel with the same content always lays out
+ * the same way.
+ */
+export function makeRandom(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * The panel's seed, derived from its own content (FNV-1a over each speaker
+ * and line). Two panels that say the same thing lay out the same way, and a
+ * replayed panel lays out as it did the first time.
+ */
+export function panelSeed(inputs) {
+    let hash = 0x811c9dc5;
+    for (const input of inputs) {
+        for (const ch of `${input.speaker} ${input.text}`) {
+            hash ^= ch.codePointAt(0) ?? 0;
+            hash = Math.imul(hash, 0x01000193) >>> 0;
+        }
+    }
+    return hash >>> 0;
+}
+/**
+ * Place every balloon in draw order, and give up on the whole panel the
+ * moment one will not go — except a panel holding exactly one balloon that
+ * will not fit, which is force-fitted into the free rect and split, since
+ * refusing it would refuse a panel a fresh, empty panel could not hold
+ * either.
+ */
+export function layoutBalloons(inputs, freeRect, seed = panelSeed(inputs)) {
+    const random = makeRandom(seed); // always lay out the same way for this seed
+    const laid = [];
+    for (let i = 0; i < inputs.length; i++) {
+        const balloon = layoutBalloon(inputs[i], laid, freeRect, random);
+        if (!balloon) {
+            if (i === 0 && inputs.length === 1)
+                return forceFitBalloon(inputs[0], freeRect);
+            return { fits: false };
+        }
+        laid.push(balloon);
+    }
+    return { fits: true, balloons: laid, leftover: null };
+}
+/** One balloon's placement: estimate a span, squeeze it into the free corridor, measure, validate. */
+function layoutBalloon(input, laid, freeRect, random) {
+    const brect = getCloudEstimate(input, laid, freeRect, random); // best guess
+    // squeezed between the corridors, and pushed below anything in the way
+    const pushed = getInterveningBBox(input, laid, freeRect, brect);
+    const span = brect.right - brect.left;
+    // A span that cannot hold the widest single word is not a balloon.
+    if (span - input.metrics.chrome * 2 < input.metrics.widestWord(input.text))
+        return null;
+    const measured = input.metrics.measure(input.text, span);
+    const box = {
+        x: brect.left, y: brect.top, width: measured.width, height: measured.height,
+    };
+    // A balloon nothing pushed down docks flush to the free rect's top.
+    if (!pushed)
+        box.y = freeRect.top + TOP_BORDER;
+    // The estimate placed the *span* so it covers the arrow. The wrap is
+    // word-granular, so the true box can come back narrower than the span it
+    // was granted and that guarantee can slip; when it does, slide the
+    // shrunken box back over the arrow (inside the free rect), rather than
+    // leave a tail reaching out of the balloon it belongs to.
+    if (input.arrowX !== null && !input.isBox
+        && (input.arrowX < box.x || input.arrowX > box.x + box.width)) {
+        box.x = Math.max(freeRect.left, Math.min(input.arrowX - box.width / 2, freeRect.right - box.width));
+    }
+    const routeRgn = {
+        left: box.x, right: box.x + box.width, bottom: box.y + box.height,
+    };
+    // A balloon hanging that low leaves its own tail no room.
+    if (routeRgn.bottom > freeRect.bottom - MIN_HOOK_HEIGHT)
+        return null;
+    adjustRouteRgns(input, laid, routeRgn);
+    return { input, box, lines: measured.lines, routeRgn };
+}
+/** How wide this balloon wants to be, and where along x it wants to sit. */
+function getCloudEstimate(input, laid, freeRect, random) {
+    const len = input.metrics.oneLineWidth(input.text);
+    const area = AREA_FUDGE * len * 2 * LINE_HEIGHT;
+    const maxWidth = freeRect.right - freeRect.left;
+    let goalWidth;
+    if (len <= ONE_LINE_THRESHOLD) {
+        goalWidth = len; // short enough to stay on one line
+    }
+    else {
+        // The height this balloon could use if it grew down to the hook line.
+        const potentialHeight = freeRect.bottom - lowestPreviousBottom(laid, freeRect.top)
+            + MIN_HOOK_HEIGHT;
+        const minWidth = Math.max(area / potentialHeight, input.metrics.widestWord(input.text));
+        goalWidth = minWidth + random() * (maxWidth - minWidth);
+    }
+    goalWidth = Math.min(goalWidth + WIDTH_FUDGE, maxWidth);
+    goalWidth = Math.min(goalWidth, len + WIDTH_FUDGE); // never wider than the text
+    let left;
+    if (input.isBox || input.arrowX === null) {
+        left = freeRect.left;
+    }
+    else {
+        // Straddle the speaker: the balloon's left is rolled inside
+        // [arrowX - goalWidth, arrowX], which guarantees the span covers arrowX
+        // so the tail drops straight.
+        const leftLimit = input.arrowX - goalWidth;
+        let startX = leftLimit + random() * (input.arrowX - leftLimit);
+        if (startX < freeRect.left)
+            startX = freeRect.left;
+        if (startX + goalWidth > freeRect.right)
+            startX = freeRect.right - goalWidth;
+        left = startX;
+    }
+    return { left, right: left + goalWidth, top: freeRect.top, bottom: freeRect.bottom };
+}
+/**
+ * Shrink or shift `brect` into the gap left by the corridors already
+ * claimed, then drop its top below whatever is already in the way. Mutates
+ * `brect`. Returns whether anything actually pushed the top down, which
+ * decides whether the balloon docks flush to the free rect's top.
+ */
+function getInterveningBBox(input, laid, freeRect, brect) {
+    const toPtX = input.arrowX ?? freeRect.left;
+    let mostLeft = freeRect.left;
+    let mostRight = freeRect.right;
+    for (const prev of laid) {
+        const { leftAllowance, rightAllowance } = queryRouteRgn(prev, toPtX);
+        mostLeft = Math.max(leftAllowance, mostLeft);
+        mostRight = Math.min(rightAllowance, mostRight);
+    }
+    if (mostLeft > brect.left || mostRight < brect.right) { // can't be placed as is
+        const clearance = mostRight - mostLeft;
+        if (clearance >= brect.right - brect.left) { // shift it
+            const delta = mostLeft > brect.left ? mostLeft - brect.left : mostRight - brect.right;
+            brect.left += delta;
+            brect.right += delta;
+        }
+        else { // grab maximal clearance
+            brect.left = mostLeft;
+            brect.right = mostRight;
+        }
+    }
+    // Then the top: below the bottom of anything overlapping in x, and below
+    // the top of anything clear of it.
+    brect.top = freeRect.top;
+    for (const prev of laid) {
+        const cloud = prev.box;
+        if (cloud.x + cloud.width < brect.left) { // clear to one side — tuck alongside
+            brect.top = Math.max(brect.top, cloud.y);
+        }
+        else {
+            // overlapping balloons nest a little instead of stacking flush.
+            brect.top = Math.max(brect.top, cloud.y + cloud.height - DOCK_DELTA);
+        }
+    }
+    return brect.top > freeRect.top;
+}
+/** The balloon whose ink reaches furthest down the panel. */
+function lowestPreviousBottom(laid, lowY) {
+    let lowest = lowY;
+    for (const prev of laid)
+        lowest = Math.max(lowest, prev.box.y + prev.box.height);
+    return lowest;
+}
+/**
+ * How far a *new* balloon aiming at `otherToX` may extend before it would
+ * block this one's tail. A balloon only defends the side its own speaker is
+ * on, and never lets its corridor be squeezed below {@link MIN_ROUTE_WIDTH}.
+ * A caption defends nothing, and so does a balloon whose speaker has no body
+ * on stage: neither drops a tail.
+ */
+function queryRouteRgn(prev, otherToX) {
+    if (prev.input.isBox || prev.input.arrowX === null) {
+        return { leftAllowance: -LARGE, rightAllowance: LARGE };
+    }
+    const toX = prev.input.arrowX;
+    if (otherToX > toX) {
+        return {
+            leftAllowance: Math.max(toX, prev.routeRgn.left + MIN_ROUTE_WIDTH),
+            rightAllowance: LARGE,
+        };
+    }
+    return {
+        leftAllowance: -LARGE,
+        rightAllowance: Math.min(toX, prev.routeRgn.right - MIN_ROUTE_WIDTH),
+    };
+}
+/**
+ * The balloon just placed carves its own span out of every corridor claimed
+ * before it, so the balloons that follow are squeezed by the accumulated
+ * result rather than by the original rects.
+ */
+function adjustRouteRgns(input, laid, routeRgn) {
+    const toX = input.arrowX;
+    if (toX === null)
+        return; // no tail, nothing to route around
+    for (const prev of laid) {
+        if (prev.input.arrowX === null)
+            continue;
+        if (toX > prev.input.arrowX)
+            prev.routeRgn.right = Math.min(prev.routeRgn.right, routeRgn.left);
+        else
+            prev.routeRgn.left = Math.max(prev.routeRgn.left, routeRgn.right);
+    }
+}
+/**
+ * Give the balloon the whole free rect, split off whatever hangs past the
+ * bottom, and dock it at the top. Only ever reached for a lone balloon in an
+ * otherwise empty panel — the case where refusing would achieve nothing.
+ */
+function forceFitBalloon(input, freeRect) {
+    const width = freeRect.right - freeRect.left;
+    const split = input.metrics.split(input.text, width, freeRect.bottom - freeRect.top);
+    const measured = input.metrics.measure(split.text, width);
+    const box = {
+        x: freeRect.left, y: freeRect.top + TOP_BORDER, width: measured.width, height: measured.height,
+    };
+    return {
+        fits: true,
+        balloons: [{
+                input: { ...input, text: split.text },
+                box,
+                lines: measured.lines,
+                routeRgn: { left: box.x, right: box.x + box.width, bottom: box.y + box.height },
+            }],
+        leftover: split.rest,
+    };
+}

package/dist/balloon.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Balloons: speech, thought, and caption, drawn as a hand-drawn (wavy-edged)
+ * outline rather than a plain rounded rect.
+ *
+ * - `speech` — a balloon with a tail rooted on its speaker's head.
+ * - `thought` — a scalloped cloud with a bubble-trail tail.
+ * - `caption` — a plain box, spoken by nobody, no tail.
+ */
+import type { Line } from "@toonstrip/schema";
+export interface BalloonBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Where the tail should point: the figure's face anchor, in panel space. */
+export interface TailTarget {
+    x: number;
+    y: number;
+}
+/**
+ * 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 declare const BALLOON_FONT = "13px \"Comic Sans MS\", \"Comic Neue\", ui-rounded, cursive";
+export declare const LINE_HEIGHT = 15;
+/** Below this one-line width, a balloon stays a single line rather than being wrapped for shape. */
+export declare const ONE_LINE_THRESHOLD = 100;
+/** Ink-area fudge factor used when estimating a compact wrap width. */
+export declare const AREA_FUDGE = 1.3;
+/** Widest single word, the floor a balloon may not wrap below. */
+export declare function widestWord(ctx: CanvasRenderingContext2D, text: string): number;
+/**
+ * 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 declare function goalWidth(ctx: CanvasRenderingContext2D, text: string, maxWidth: number): number;
+export declare function measureBalloon(ctx: CanvasRenderingContext2D, balloon: Pick<Line, "balloon" | "text">, maxWidth: number): {
+    lines: string[];
+    width: number;
+    height: number;
+};
+/** The chrome a balloon kind puts between its outline and its text, each side. */
+export declare function chromeFor(balloon: Pick<Line, "balloon">): number;
+/**
+ * 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 declare function measureAtWidth(ctx: CanvasRenderingContext2D, balloon: Pick<Line, "balloon" | "text">, boxWidth: number): {
+    lines: string[];
+    width: number;
+    height: number;
+};
+/** Appended to the part of a too-tall balloon that fit, prepended to the rest. */
+export declare 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 declare function splitHeight(ctx: CanvasRenderingContext2D, balloon: Pick<Line, "balloon" | "text">, boxWidth: number, boxHeight: number): {
+    text: string;
+    rest: string | null;
+};
+/**
+ * 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 declare function drawBalloon(ctx: CanvasRenderingContext2D, balloon: Pick<Line, "balloon">, box: BalloonBox, lines: readonly string[], target: TailTarget | null): void;