postext 1.20.0 → 1.20.2

package/dist/comics/lettering/placement.js

@@ -61,18 +61,40 @@ function sceneOf(panel) {
         visBox: boundsOf(visible),
         faces: panel.anchors.filter((a) => a.face).map((a) => a.face),
         avoid: [...(panel.avoid ?? [])],
-        soft: [...(panel.softAvoid ?? [])],
+        soft: figureContacts(panel.softAvoid ?? [], panel.anchors),
         mouths: panel.anchors.filter((a) => a.visible && a.id !== 'sfx').map((a) => a.mouth),
         fwd: panel.direction === 'rtl' ? -1 : 1,
         buttPoly: buttPolygon(panel),
         neighbours: [...(panel.neighbours ?? [])],
         ...(panel.limit ? { limit: panel.limit } : {}),
         ...(trim ? { edge: insetRect(trim, panel.insetPx), edgeSfx: panel.sheet ?? trim } : {}),
+        bleeds: panel.limit !== undefined && panel.polygon.some((p) => !pointInRect(p, panel.limit, 0.5)),
         foreign: [...(panel.foreign ?? [])],
         keepOut: [...(panel.keepOut ?? [])],
         live,
     };
 }
+/** How many times a balloon costs more over another character's figure
+ *  than over its own speaker's (a letterer covers the speaker's shoulder
+ *  before the one being spoken to). */
+const OTHER_FIGURE = 4;
+/** Soft zones with `contact` marked on the figures of characters whose
+ *  faces all but touch (a hug, cheek to cheek): there the arms of one lie
+ *  over the other, and no speaker's own figure is free to cover. Two
+ *  figures merely standing side by side are not in contact. */
+function figureContacts(zones, anchors) {
+    const faceOf = (id) => anchors.find((a) => a.id === id)?.face;
+    const touching = (a, b) => {
+        const gx = Math.max(a.x, b.x) - Math.min(a.x + a.width, b.x + b.width);
+        const gy = Math.max(a.y, b.y) - Math.min(a.y + a.height, b.y + b.height);
+        return gx <= 0.25 * Math.min(a.width, b.width) && gy <= 0.25 * Math.min(a.height, b.height);
+    };
+    return zones.map((z) => {
+        const f = z.owner !== undefined ? faceOf(z.owner) : undefined;
+        const contact = f !== undefined && anchors.some((a) => a.id !== z.owner && a.face !== undefined && touching(f, a.face));
+        return contact ? { ...z, contact: true } : { ...z };
+    });
+}
 function buttPolygon(panel) {
     const half = (panel.borderPx ?? 0) / 2;
     const live = livePolygon(panel);
@@ -91,6 +113,29 @@ function coveredArea(samples, rect, area) {
             n++;
     return (n / Math.max(1, samples.length)) * area;
 }
+/** Whether a face fills a good part of its panel (a close shot): its box
+ *  then has corners of hair a balloon may cover (in a long shot they are a
+ *  few pixels beside the face). */
+function closeShot(face, vis) {
+    return face.width >= 0.35 * vis.width || face.height >= 0.35 * vis.height;
+}
+/** Area of a face's box the samples fall in, less its top corners: above
+ *  its middle a face is the oval its box holds (the corners are hair or
+ *  background); below it, the whole box (cheeks, jaw and chin). */
+function coveredOval(samples, rect, area) {
+    const cx = rect.x + rect.width / 2;
+    const cy = rect.y + rect.height / 2;
+    const rx = rect.width / 2;
+    const ry = rect.height / 2;
+    let n = 0;
+    for (const s of samples) {
+        if (!pointInRect(s, rect))
+            continue;
+        if (s.y >= cy || ((s.x - cx) / rx) ** 2 + ((s.y - cy) / ry) ** 2 <= 1)
+            n++;
+    }
+    return (n / Math.max(1, samples.length)) * area;
+}
 function areaOf(v) {
     // The bodies' boxes, as an ellipse fills them.
     return v.bodies.reduce((s, b) => s + b.bbox.width * b.bbox.height * 0.8, 0);
@@ -139,8 +184,17 @@ function evaluate(scene, unit, vi, at, others, level, firstOrder, terms) {
     const reasons = new Set();
     let hard = 0;
     let soft = 0;
+    let order = 0;
+    let cover = 0;
+    let coverArt = 0;
     const S = (k, x) => {
         soft += x;
+        if (k === 'order')
+            order += x;
+        else if (k === 'coverAvoid' || k === 'coverArt')
+            cover += x;
+        if (k === 'coverArt')
+            coverArt += x;
         if (terms)
             terms[k] = (terms[k] ?? 0) + x;
     };
@@ -151,11 +205,12 @@ function evaluate(scene, unit, vi, at, others, level, firstOrder, terms) {
         if (terms)
             terms[`!${k}`] = (terms[`!${k}`] ?? 0) + x;
     };
-    // Faces, avoid zones, mouths.
+    // Faces (in a close shot less the top corners of their boxes, hair or
+    // background), avoid zones, mouths.
     for (const f of scene.faces) {
         if (!rectsOverlap(box, f))
             continue;
-        const a = coveredArea(samples, f, area);
+        const a = closeShot(f, scene.visBox) ? coveredOval(samples, f, area) : coveredArea(samples, f, area);
         if (a > 0) {
             H('face', (W.face * a) / em2 + W.face);
             reasons.add('face');
@@ -166,8 +221,11 @@ function evaluate(scene, unit, vi, at, others, level, firstOrder, terms) {
             continue;
         const a = coveredArea(samples, r, area);
         if (a > 0) {
+            // (What the art marks costs three times what a guard over a head
+            // does: a balloon touches the top of the hair before it covers a
+            // hand the artist asked to keep clear.)
             if (level.coverAvoid)
-                S('coverAvoid', (2 * a) / em2);
+                S(r.guard ? 'coverAvoid' : 'coverArt', ((r.guard ? 2 : 6) * a) / em2);
             else {
                 H('avoid', (W.avoid * a) / em2 + W.avoid);
                 reasons.add('avoid');
@@ -177,7 +235,8 @@ function evaluate(scene, unit, vi, at, others, level, firstOrder, terms) {
     for (const r of scene.soft) {
         if (!rectsOverlap(box, r))
             continue;
-        S('softAvoid', ((r.weight ?? 1) * W.soft * coveredArea(samples, r, area)) / em2);
+        const other = r.owner !== undefined && (r.contact === true || r.owner !== unit.speaker);
+        S(other ? 'otherFigure' : 'softAvoid', ((r.weight ?? 1) * (other ? OTHER_FIGURE : 1) * W.soft * coveredArea(samples, r, area)) / em2);
     }
     const bodiesHere = v.bodies.map((b) => moved(b.core, at));
     for (const m of scene.mouths) {
@@ -190,13 +249,19 @@ function evaluate(scene, unit, vi, at, others, level, firstOrder, terms) {
     }
     // Outside the panel. A unit that breaks its border on purpose (`break`,
     // at the level that allows it; a pin, where its author put it) may run
-    // past the border, the gutter and the live area: a little cost, never a
-    // fault — but never off the sheet, and never into another panel's art
-    // unless it is a sound effect or a `break` (drawn sound and a balloon
-    // breaking into the next panel are both the letterer's call).
+    // past the border and the gutter: a little cost, never a fault — but
+    // never off the sheet, and never into another panel's art unless it is
+    // a sound effect or a `break` (drawn sound and a balloon breaking into
+    // the next panel are both the letterer's call). Only a pin, drawn sound
+    // or the `break` of a panel that bleeds leaves the live area: a balloon
+    // left to the engine breaks into the gutter and the next panel, never
+    // into the margin.
     const rim = moved(v.rim, at);
     const intended = unit.pin !== undefined || (level.breakBorder && unit.breakBorder === true);
-    const edge = intended ? (unit.kind === 'sfx' ? scene.edgeSfx : scene.edge) ?? scene.limit : scene.limit;
+    const edge = !intended ? scene.limit
+        : unit.kind === 'sfx' ? scene.edgeSfx ?? scene.limit
+            : unit.pin !== undefined || scene.bleeds ? scene.edge ?? scene.limit
+                : scene.limit ?? scene.edge;
     let out = 0;
     let intrude = 0;
     let offPage = 0;
@@ -369,8 +434,10 @@ function evaluate(scene, unit, vi, at, others, level, firstOrder, terms) {
     }
     if (unit.kind === 'sfx' && unit.near)
         S('sfxNear', (0.5 * dist(centre, unit.near)) / em);
-    // High in the panel; the first one in the top start corner.
-    if (unit.kind !== 'sfx') {
+    // High in the panel; the first one in the top start corner. (A unit set
+    // at a corner or an edge has its place: a caption at the foot of a panel
+    // is not drawn to the top of it.)
+    if (unit.kind !== 'sfx' && !unit.position) {
         const top = box.y - scene.visBox.y;
         S('height', ((scene.heightBias ?? 1) * (unit.kind === 'note' ? W.height * Math.max(0, scene.visBox.y + scene.visBox.height - (box.y + box.height)) : W.height * top)) / em);
         if (unit.order === firstOrder && unit.kind !== 'note') {
@@ -378,7 +445,7 @@ function evaluate(scene, unit, vi, at, others, level, firstOrder, terms) {
             S('start', (W.start * fromStart) / em);
         }
     }
-    return { hard, soft, reasons };
+    return { hard, soft, reasons, order, cover, coverArt };
 }
 /** A rectangle grown by `d` px on every side. */
 function grow(r, d) {
@@ -486,11 +553,12 @@ function candidates(scene, unit, vi) {
 }
 /** The anchor a corner or edge keyword puts a unit at: its box flush
  *  with the panel (`butt`) or with the inset area, at that corner. */
-export function positionAnchor(scene, v, position, butt) {
+export function positionAnchor(scene, v, position, butt, along) {
     const poly = butt ? scene.buttPoly : scene.visible;
     const box = boundsOf(poly);
     const startLeft = scene.fwd === 1;
-    const hx = position === 'top' || position === 'bottom' ? 0.5
+    // `along`: where on its edge (0 left, 1 right) instead of the keyword's.
+    const hx = along !== undefined ? along : position === 'top' || position === 'bottom' ? 0.5
         : position.endsWith('start') ? (startLeft ? 0 : 1) : (startLeft ? 1 : 0);
     const vy = position.startsWith('top') ? 0 : 1;
     const bx = box.x + hx * (box.width - v.bbox.width);
@@ -509,8 +577,10 @@ export function positionAnchor(scene, v, position, butt) {
 }
 /** A corner or edge unit's anchors: its own corner first, then — a cost
  *  each, so taken only when its own covers a face, an avoid zone or a
- *  balloon — the other corner of that edge, the middle of it, and the
- *  corners of the opposite edge. */
+ *  balloon — the other corner of that edge, the middle of it, the spots
+ *  along it just clear of what it would cover (between two heads), and
+ *  only then the corners of the opposite edge: a caption at the head of a
+ *  panel (a strip's title) stays at its head when there is room there. */
 function positionAnchors(scene, v, position, butt) {
     const top = position.startsWith('top');
     const across = position.endsWith('start') ? (top ? 'top-end' : 'bottom-end') : position.endsWith('end') ? (top ? 'top-start' : 'bottom-start') : (top ? 'top-start' : 'bottom-start');
@@ -518,7 +588,27 @@ function positionAnchors(scene, v, position, butt) {
     const flip = (q) => (q.startsWith('top') ? q.replace('top', 'bottom') : q.replace('bottom', 'top'));
     const list = [[position, 0], [across, 2], [middle, 3], [flip(position), 5], [flip(across), 6]];
     const seen = new Set();
-    return list.filter(([q]) => (seen.has(q) ? false : (seen.add(q), true))).map(([q, extra]) => ({ at: positionAnchor(scene, v, q, butt), extra }));
+    const out = list.filter(([q]) => (seen.has(q) ? false : (seen.add(q), true))).map(([q, extra]) => ({ at: positionAnchor(scene, v, q, butt), extra }));
+    // Along the edge: the box butted against each side of every face or
+    // avoid zone in the edge's band, nearer its own corner first.
+    const own = positionAnchor(scene, v, position, butt);
+    const band = movedRect(v.bbox, own);
+    const span = boundsOf(butt ? scene.buttPoly : scene.visible);
+    const free = span.width - v.bbox.width;
+    if (free > 0) {
+        const ownX = band.x;
+        for (const r of [...scene.faces, ...scene.avoid]) {
+            if (r.y > band.y + band.height || r.y + r.height < band.y)
+                continue;
+            for (const x of [r.x + r.width + 1, r.x - v.bbox.width - 1]) {
+                const f = (x - span.x) / free;
+                if (f <= 0 || f >= 1)
+                    continue;
+                out.push({ at: positionAnchor(scene, v, position, butt, f), extra: 3.5 + Math.abs(x - ownX) / span.width });
+            }
+        }
+    }
+    return out;
 }
 const LEVELS = [
     { breakBorder: false, coverAvoid: false },
@@ -562,12 +652,53 @@ function bestFor(scene, unit, others, firstOrder, fixed) {
             continue;
         const choice = { variant: best.variant, level: best.level, at: best.at, ev: best.ev };
         if (choice.ev.hard === 0)
-            return choice;
+            return fixed || li !== 0 ? choice : orderBeforeAvoid(scene, unit, others, firstOrder, best, penalty);
         if (!fallback || better(choice.ev, fallback.ev))
             fallback = choice;
     }
     return fallback;
 }
+/** What taking the last fallback (covering an avoid zone a little) to keep
+ *  the reading order costs on top of the cover itself. */
+const ORDER_OVER_AVOID = 4;
+/** The most a balloon may cover of avoid zones (as their cost: 2 per em²
+ *  of a guard over a head, 6 of a zone the art marks) to keep the reading
+ *  order: the top of the hair over a face, the edge of a hat; of what the
+ *  art marks, hardly a corner. */
+const ORDER_COVER_MAX = 16;
+const ORDER_COVER_ART_MAX = 6;
+/** Whether a spot (its evaluation and cost terms) may stand in for one
+ *  that reads out of order: clean, in order, covering no more of avoid
+ *  zones than the caps, and its tail off the other faces (a tail across
+ *  another character's face reads as theirs, worse than a line read
+ *  late). */
+function keepsOrder(ev, terms) {
+    return ev.hard === 0 && ev.order < W.orderBase && ev.cover <= ORDER_COVER_MAX && ev.coverArt <= ORDER_COVER_ART_MAX
+        && (terms.otherFace ?? 0) < W.otherFace;
+}
+/** A clean choice that reads out of order (the balloon above the one it
+ *  answers, or beside it on the wrong side) against the same unit covering
+ *  a little of an avoid zone in reading order: a letterer lets a balloon
+ *  touch the top of a head before setting a reply ahead of its line. */
+function orderBeforeAvoid(scene, unit, others, firstOrder, best, penalty) {
+    const plain = { variant: best.variant, level: best.level, at: best.at, ev: best.ev };
+    if (best.ev.order < W.orderBase || unit.pin || unit.position)
+        return plain;
+    const level = LEVELS[2];
+    let alt;
+    for (let vi = 0; vi < unit.variants.length; vi++) {
+        for (const at of candidates(scene, unit, vi)) {
+            const terms = {};
+            const ev = evaluate(scene, unit, vi, at, others, level, firstOrder, terms);
+            if (!keepsOrder(ev, terms))
+                continue;
+            const score = ev.soft + penalty(vi) + ORDER_OVER_AVOID;
+            if (!alt || score < alt.score - 1e-9)
+                alt = { variant: vi, level: 2, at, ev, score };
+        }
+    }
+    return alt && alt.score < best.score - 1e-9 ? { variant: alt.variant, level: alt.level, at: alt.at, ev: alt.ev } : plain;
+}
 /** What choosing a reshaped text block costs (its poorer shape). */
 const RESHAPE_COST = 1.5;
 /** A pinned unit's anchors: on its pin, and moved the least that keeps
@@ -731,6 +862,59 @@ function swapCrossing(scene, placed, firstOrder) {
     }
     return undefined;
 }
+/** The cheapest spot for `unit` that reads in order with the others, over
+ *  all its shapes and fallback levels (see {@link keepsOrder}; covering an
+ *  avoid zone pays as much more as in {@link orderBeforeAvoid}); undefined
+ *  when there is none. */
+function inOrder(scene, unit, others, firstOrder) {
+    const levels = LEVELS.map((_, i) => i).filter((i) => i === 0 || unit.breakBorder || i === 2);
+    let best;
+    for (const li of levels) {
+        for (let vi = 0; vi < unit.variants.length; vi++) {
+            const penalty = unit.variants[vi].reshaped ? RESHAPE_COST : 0;
+            for (const at of candidates(scene, unit, vi)) {
+                const terms = {};
+                const ev = evaluate(scene, unit, vi, at, others, LEVELS[li], firstOrder, terms);
+                if (!keepsOrder(ev, terms))
+                    continue;
+                const score = ev.soft + penalty + (ev.cover > 0 ? ORDER_OVER_AVOID : 0);
+                if (!best || score < best.score - 1e-9)
+                    best = { variant: vi, level: li, at, ev, score };
+            }
+        }
+    }
+    return best && { variant: best.variant, level: best.level, at: best.at, ev: best.ev };
+}
+/** The layout with one balloon that reads out of order placed again over
+ *  all its shapes and fallbacks, the others where they stand, when that
+ *  lowers the whole layout's cost; else undefined. The improvement passes
+ *  keep a balloon's shape and level, and a pair placed again has the later
+ *  balloon alone first, in the room the earlier one needs: neither moves
+ *  the first line of a pair above the hair of its speaker, in a shape a
+ *  line deeper, ahead of the reply that already stands below it. */
+function reorder(scene, placed, firstOrder) {
+    const base = totalCost(scene, placed, firstOrder);
+    let best;
+    let cost = base;
+    for (let i = 0; i < placed.length; i++) {
+        const p = placed[i];
+        if (p.unit.pin || p.unit.position || p.unit.kind === 'sfx' || p.ev.order < W.orderBase)
+            continue;
+        const others = placed.filter((_, j) => j !== i);
+        const c = inOrder(scene, p.unit, others, firstOrder);
+        if (!c)
+            continue;
+        const out = placed.map((q, j) => (j === i ? { ...q, variant: c.variant, level: c.level, at: c.at, ev: c.ev } : q));
+        // (Covering an avoid zone to read in order pays what `bestFor` asks;
+        // the whole layout's cost counts the order on both balloons of a pair.)
+        const t = totalCost(scene, out, firstOrder) + (c.ev.cover > 0 ? ORDER_OVER_AVOID : 0);
+        if (t < cost - 1e-6) {
+            cost = t;
+            best = out;
+        }
+    }
+    return best;
+}
 /** The layout with one pair of free units taken out and placed again
  * (each order in turn, the second seeing the first) when that lowers the
  * whole layout's cost; else undefined. A single move cannot undo a pair
@@ -816,16 +1000,9 @@ function totalCost(scene, placed, firstOrder) {
     }
     return hard * 1000 + soft;
 }
-/** Height biases the solver is run with: a greedy pass that lifts every
- *  balloon higher first can leave room below for the later ones (the
- *  Kurlander order often wants the earlier balloons high); the layout with
- *  the lowest plain cost wins. */
-const HEIGHT_BIASES = [1, 3, 7];
-/** Place every unit of a panel (see the module comment). */
-export function placeUnits(panel, units, passes = 3) {
-    const scene = sceneOf(panel);
-    const ordered = [...units].sort((a, b) => a.order - b.order || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-    const firstOrder = ordered.find((u) => u.kind !== 'sfx' && u.kind !== 'note')?.order ?? Number.NaN;
+/** The search of {@link placeUnits}: greedy runs in a few orders and
+ *  height biases, then pairs placed again; the cheapest layout. */
+function search(scene, ordered, firstOrder, passes) {
     let placed;
     let bestCost = Number.POSITIVE_INFINITY;
     const tries = (mode) => {
@@ -859,6 +1036,35 @@ export function placeUnits(panel, units, passes = 3) {
             break;
         placed = solveFrom(scene, next, firstOrder, passes);
     }
+    // Balloons still read out of order placed again with every shape and
+    // fallback open, the others where they stand.
+    for (let round = 0; round < 2 && ordered.length > 1; round++) {
+        const next = reorder(scene, placed, firstOrder);
+        if (!next)
+            break;
+        placed = solveFrom(scene, next, firstOrder, passes);
+    }
+    return { placed: placed, cost: totalCost(scene, placed, firstOrder) };
+}
+/** Height biases the solver is run with: a greedy pass that lifts every
+ *  balloon higher first can leave room below for the later ones (the
+ *  Kurlander order often wants the earlier balloons high); the layout with
+ *  the lowest plain cost wins. */
+const HEIGHT_BIASES = [1, 3, 7];
+/** Place every unit of a panel (see the module comment). `extend`, when
+ * given, adds spare variants to the units (see `letterPanelDetailed`):
+ * a panel the first search leaves with a fault is searched again with
+ * them, and the cheaper layout is kept. */
+export function placeUnits(panel, units, passes = 3, extend) {
+    const scene = sceneOf(panel);
+    const ordered = [...units].sort((a, b) => a.order - b.order || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const firstOrder = ordered.find((u) => u.kind !== 'sfx' && u.kind !== 'note')?.order ?? Number.NaN;
+    let { placed, cost } = search(scene, ordered, firstOrder, passes);
+    if (cost >= 1000 && extend?.()) {
+        const again = search(scene, ordered, firstOrder, passes);
+        if (again.cost < cost - 1e-9)
+            ({ placed, cost } = again);
+    }
     const final = placed;
     const diagnostics = [];
     for (let i = 0; i < final.length; i++) {