@namiml/cli 3.4.12-dev.202610051759 → 3.4.12-dev.202610060208

package/dist/render/paint.js

@@ -0,0 +1,625 @@
+/**
+ * Laid-out boxes → a painted character grid.
+ *
+ * This is the composing third of the cell compositor (NAM-4548 reopened).
+ * `src/render/page-model.ts` decides *what* is on the page, `src/render/style.ts`
+ * parses the authored values, `src/render/layout.ts` turns the two into absolute
+ * rectangles **in paint order**, and `src/render/surface.ts` is the grid. This
+ * module does one thing: walk the rectangles in the order the layout returned
+ * them and paint each one.
+ *
+ * That order is the whole ticket. The layout emits the background slot first,
+ * then header, content and footer, and a parent before its children — so
+ * everything painted later lands on top of what came before. A cell keeps the
+ * background it was given unless something explicitly repaints it, which is how
+ * copy ends up **over** a background image rather than instead of it.
+ *
+ * The footer is the one slot that is **not** painted into the page surface.
+ * `sdk/web` gives it `position: absolute; bottom: 0; width: 100%` over the
+ * content container, so it stays put while the content scrolls under it; here
+ * the page surface scrolls, so the footer is painted on its own by
+ * `paintFooter` and the screen drops it against the bottom of the frame. It is
+ * still painted *over* the content, never under it.
+ *
+ * Six things worth knowing before changing it:
+ *
+ *  1. **Wrapping comes from `layout.ts`.** `wrapText` is the function the layout
+ *     measured the boxes with, so wrapping with anything else would paint rows
+ *     the boxes were never sized for — and `wrapText` measures with the same
+ *     `textColumns` used here, so the two cannot disagree about how wide a
+ *     string is. That is the point of there being one of it: the surface
+ *     decides how many columns a glyph really takes, and the layout asks it.
+ *  2. **Nothing passes a background to `drawText`** for ordinary copy. The
+ *     surface keeps whatever is already in the cell, and a background handed in
+ *     here would punch a hole through the page's backdrop.
+ *  3. **Horizontal overflow is real.** The Penguin page reaches column 81 in a
+ *     44-column frame, because that is what the authored widths say. The frame
+ *     clips it — the surface does that silently — rather than this module
+ *     squashing or re-wrapping it.
+ *  4. **A translucent fill is composited, not stamped.** A scrim authored
+ *     `rgba(1 25 50 / 0.08)` is blended with the cell beneath it, so the image
+ *     under it still shows through; a fill that parses to nothing (both NFL
+ *     gradients take their stops from deferred `${block.*}` data) paints
+ *     nothing at all rather than inventing a colour.
+ *  5. **The footer paints last, somewhere else.** `paintPage` skips every box
+ *     the layout tagged `section: "footer"` and `paintFooter` paints exactly
+ *     those, translated to their own surface. Nothing else knows the
+ *     difference: both walk the same boxes with the same `paint`.
+ *  6. **An image has no dimensions at layout time**, so its box is whatever was
+ *     authored, or a flat few rows. `halfBlockRows` never upscales, so a grid
+ *     smaller than its box is placed at the box's top left and never stretched.
+ *
+ * The surface is as tall as the **page**, which is regularly taller than the
+ * frame: the screen scrolls a window over it rather than this module deciding
+ * what is visible.
+ */
+import { DEFAULT_VIEWPORT, frameRows, layoutPage, wrapText } from "./layout.js";
+import { Surface, cellWidth, graphemes, textColumns } from "./surface.js";
+import { alignmentFraction, alignmentProps, blend, cellScale, parseColor, parseFill, sampleGradient, toCells, toHex, } from "./style.js";
+const NO_INSETS = { top: 0, right: 0, bottom: 0, left: 0 };
+/**
+ * `› ` — the two cells `layout.ts` reserves in a button's width for the focus
+ * marker. The marker itself belongs to the screen, which knows what is focused;
+ * the slot is left blank here so the label never moves when it appears.
+ */
+const BUTTON_MARKER = 2;
+/** A product card is drawn inside a one-cell border, which its geometry reserves. */
+const CARD_BORDER = 1;
+/** `fontSize` at or above which copy reads as a heading. The real pages run 32 / 20 / 15 / 12. */
+const HEADING_FONT_SIZE = 24;
+/** `fontSize` at or below which copy is fine print. */
+const FINE_PRINT_FONT_SIZE = 13;
+/** Text types that are headings or fine print whatever size they were given. */
+const HEADING_TYPES = new Set(["title", "heading", "headline"]);
+const FINE_PRINT_TYPES = new Set(["legal", "caption", "footnote"]);
+/** Box-drawing glyphs: square corners, and the round set an authored radius picks. */
+const SQUARE = { tl: "┌", tr: "┐", bl: "└", br: "┘", h: "─", v: "│" };
+const ROUND = { ...SQUARE, tl: "╭", tr: "╮", bl: "╰", br: "╯" };
+/** Enough of an image's name to recognise; the real urls are 64-character hashes. */
+const NAME_LIMIT = 28;
+const EDGE_AXIS = { top: "height", right: "width", bottom: "height", left: "width" };
+/**
+ * Paint a page into a fresh surface — **everything but the footer**.
+ *
+ * `cols` × `rows` is the frame in cells and `viewport` is the device those
+ * cells stand for — authored padding and heights are device pixels, so without
+ * it nothing scales. The surface comes back `cols` wide and as tall as the page
+ * the layout measured, which is never less than `rows`.
+ *
+ * The footer is left out because it does not scroll with the page: it is drawn
+ * over the bottom of the frame by `paintFooter`, the way `sdk/web` pins its
+ * `position: absolute; bottom: 0` footer over a scrolling content container.
+ * The content the layout inset for it is already out of its way.
+ */
+export function paintPage(page, cols, rows, viewport = DEFAULT_VIEWPORT, deps = {}) {
+    const width = Math.max(1, Math.floor(cols));
+    const { boxes, height } = layoutPage(page, width, rows, viewport);
+    const surface = new Surface(width, height);
+    const scale = cellScale(viewport, width);
+    // In the order the layout returned them: background first, a parent before
+    // its children, so everything painted later sits on top.
+    for (const laid of boxes)
+        if (laid.section !== "footer")
+            paint(surface, laid, scale, deps);
+    return surface;
+}
+/**
+ * Paint the footer alone, into a surface exactly its own height.
+ *
+ * `null` when the page has no footer slot, which is a real case — the committed
+ * Penguin fixture authors an empty `footer: []` — and is what tells a screen
+ * there is nothing to pin. The rows come back with their own origin at row 0,
+ * so a screen can drop them against the bottom of whatever it is showing
+ * without knowing where in the page the layout put them.
+ *
+ * There is no `rows` argument because the footer is measured against the device
+ * frame (`frameRows`), not against the pane: the same frame `paintPage` is
+ * given by the screen, so the two agree on the footer's height.
+ */
+export function paintFooter(page, cols, viewport = DEFAULT_VIEWPORT, deps = {}) {
+    const width = Math.max(1, Math.floor(cols));
+    const { boxes, footerHeight } = layoutPage(page, width, frameRows(viewport, width), viewport);
+    const footer = boxes.filter((laid) => laid.section === "footer");
+    if (footer.length === 0 || footerHeight <= 0)
+        return null;
+    const surface = new Surface(width, footerHeight);
+    const scale = cellScale(viewport, width);
+    // The footer's own top row becomes row 0 of its surface. A footer taller than
+    // the frame starts above it — a negative `y`, exactly as it overflows the top
+    // of its container on the web — and this is the shift that brings it back.
+    const top = footer[0].y;
+    for (const laid of footer)
+        paint(surface, { ...laid, y: laid.y - top }, scale, deps);
+    return surface;
+}
+function paint(surface, laid, scale, deps) {
+    const { node } = laid;
+    switch (node.kind) {
+        case "spacer":
+            return;
+        case "box":
+            paintFill(surface, laid, node.style.fill);
+            paintBorder(surface, laid, node.style.border);
+            return;
+        case "text":
+            paintFill(surface, laid, node.style.fill);
+            paintBorder(surface, laid, node.style.border);
+            paintText(surface, laid, node, scale);
+            return;
+        case "button":
+            paintFill(surface, laid, node.style.fill);
+            paintBorder(surface, laid, node.style.border);
+            paintButton(surface, laid, node, scale, deps.focused);
+            return;
+        case "product":
+            paintFill(surface, laid, node.style?.fill);
+            paintCard(surface, laid, node, scale, deps.focused);
+            return;
+        case "image":
+            paintFill(surface, laid, node.style?.fill);
+            paintImage(surface, laid, node, scale, deps);
+            return;
+    }
+}
+// ---------------------------------------------------------------------------
+// Fills and borders
+// ---------------------------------------------------------------------------
+/**
+ * A box's background.
+ *
+ * An opaque fill — solid or gradient — is one `fillRectRows` sweep, with
+ * `sampleGradient` giving each row its own colour. A fill carrying alpha is
+ * composited cell by cell against what is already painted, which is what keeps
+ * an authored scrim a scrim instead of a lid; a fully transparent one paints
+ * nothing, and so does a fill that parses to nothing.
+ */
+function paintFill(surface, laid, value) {
+    const fill = parseFill(value);
+    if (!fill)
+        return;
+    const { x, y, w, h } = laid;
+    if (w <= 0 || h <= 0)
+        return;
+    if (isOpaque(fill)) {
+        surface.fillRectRows(x, y, w, h, (t) => sampleGradient(fill, t));
+        return;
+    }
+    for (let row = 0; row < h; row += 1) {
+        const color = sampleGradient(fill, h === 1 ? 0 : row / (h - 1));
+        if (!color || color.a <= 0)
+            continue;
+        if (color.a >= 1) {
+            surface.fillRect(x, y + row, w, 1, color);
+            continue;
+        }
+        for (let col = 0; col < w; col += 1) {
+            const under = surface.cellAt(x + col, y + row);
+            if (!under)
+                continue;
+            // With nothing beneath, the terminal's own background is what shows, and
+            // we do not know it — so the authored colour is drawn as authored.
+            surface.fillRect(x + col, y + row, 1, 1, under.bg ? blend(color, under.bg) : color);
+        }
+    }
+}
+/** True when nothing about this fill needs compositing with what is beneath it. */
+function isOpaque(fill) {
+    if (!fill)
+        return false;
+    if (fill.kind === "solid")
+        return fill.color.a >= 1;
+    return fill.stops.length > 0 && fill.stops.every((stop) => stop.color.a >= 1);
+}
+/**
+ * An authored border, drawn **inside** the box's own area.
+ *
+ * Only a product card's geometry reserves its border, so a border drawn here
+ * would otherwise push into its neighbour. It is painted with the box rather
+ * than after its children, so a child that reaches the edge draws over it — a
+ * border must never hide content.
+ */
+function paintBorder(surface, laid, border) {
+    if (!border || !(typeof border.width === "number") || border.width <= 0)
+        return;
+    const color = parseColor(border.color);
+    drawFrame(surface, laid, (border.radius ?? 0) > 0, color ? { fg: color } : {});
+}
+function drawFrame(surface, rect, round, style) {
+    const { x, y, w, h } = rect;
+    if (w < 2 || h < 2)
+        return;
+    const glyphs = round ? ROUND : SQUARE;
+    const span = glyphs.h.repeat(w - 2);
+    surface.drawText(x, y, `${glyphs.tl}${span}${glyphs.tr}`, style, w);
+    surface.drawText(x, y + h - 1, `${glyphs.bl}${span}${glyphs.br}`, style, w);
+    for (let row = 1; row < h - 1; row += 1) {
+        surface.drawText(x, y + row, glyphs.v, style, 1);
+        surface.drawText(x + w - 1, y + row, glyphs.v, style, 1);
+    }
+}
+// ---------------------------------------------------------------------------
+// Copy
+// ---------------------------------------------------------------------------
+function paintText(surface, laid, node, scale) {
+    const area = inner(laid, insets(node.style, scale));
+    if (area.w <= 0 || area.h <= 0)
+        return;
+    const segments = node.style.capitalize
+        ? node.segments.map((segment) => ({ ...segment, text: segment.text.toUpperCase() }))
+        : node.segments;
+    const styles = styleRuns(segments, node.style);
+    const full = segments.map((segment) => segment.text).join("");
+    // `alignItems` is the horizontal axis for a column, which is how `style.ts`
+    // folds a bare `alignment` in — the same call the layout makes.
+    const align = alignmentProps(node.style.horizontalAlignment ?? node.style.alignment, node.style.verticalAlignment, "column").alignItems;
+    // Wrap at what is actually visible. The layout caps a measure at the frame
+    // width, but a box that starts at x still runs past the right edge by its own
+    // offset, and the surface would clip the tail of every line. Wrapping to the
+    // visible width loses no words; the reserved-height guard below still stops a
+    // box painting into the next one.
+    const visible = Math.max(1, Math.min(area.w, surface.cols - area.x));
+    let cursor = 0;
+    wrapText(full, visible).forEach((line, row) => {
+        // The layout measured the same string with the same wrap, so a line past
+        // the rows it reserved would be painting over the next box.
+        if (row >= area.h)
+            return;
+        const found = full.indexOf(line, cursor);
+        const start = found < 0 ? cursor : found;
+        cursor = start + line.length;
+        drawRuns(surface, area.x + indent(align, area.w, line), area.y + row, line, start, styles);
+    });
+}
+/** One style object per character of the joined text, so a run is an identity comparison. */
+function styleRuns(segments, style) {
+    const linkColor = parseColor(style.linkColor);
+    const fontColor = parseColor(style.fontColor);
+    const heading = isHeading(style);
+    const finePrint = isFinePrint(style);
+    const out = [];
+    for (const segment of segments) {
+        const cell = {};
+        const color = segment.link !== undefined && linkColor ? linkColor : fontColor;
+        // A colour with no alpha at all is nothing to draw, not black.
+        if (color && color.a > 0)
+            cell.fg = color;
+        if (heading || segment.bold)
+            cell.bold = true;
+        if (segment.italic)
+            cell.italic = true;
+        if (segment.link !== undefined)
+            cell.underline = true;
+        if (finePrint)
+            cell.dim = true;
+        for (let i = 0; i < segment.text.length; i += 1)
+            out.push(cell);
+    }
+    return out;
+}
+/**
+ * Draw one wrapped line as runs of like-styled characters.
+ *
+ * No background is passed: the cells keep whatever is already beneath them,
+ * which is what puts copy over a fill or an image instead of through it.
+ */
+function drawRuns(surface, x, y, line, start, styles, 
+/** Stop here, exclusive. A run past it is dropped rather than drawn over whatever is there. */
+until = Infinity) {
+    let col = x;
+    let at = 0;
+    while (at < line.length && col < until) {
+        const style = styles[start + at] ?? {};
+        let end = at + 1;
+        while (end < line.length && styles[start + end] === style)
+            end += 1;
+        const run = line.slice(at, end);
+        surface.drawText(col, y, run, style, Math.max(0, until - col));
+        col += textColumns(run);
+        at = end;
+    }
+}
+/** Where a line starts inside a box the template asked to be centred or right-aligned. */
+function indent(align, width, line) {
+    const slack = width - textColumns(line);
+    if (slack <= 0)
+        return 0;
+    if (align === "center")
+        return Math.floor(slack / 2);
+    if (align === "flex-end")
+        return slack;
+    return 0;
+}
+function isHeading(style) {
+    if (style.textType && HEADING_TYPES.has(style.textType))
+        return true;
+    return style.fontSize !== undefined && style.fontSize >= HEADING_FONT_SIZE;
+}
+function isFinePrint(style) {
+    if (style.textType && FINE_PRINT_TYPES.has(style.textType))
+        return true;
+    return style.fontSize !== undefined && style.fontSize <= FINE_PRINT_FONT_SIZE;
+}
+// ---------------------------------------------------------------------------
+// Controls and cards
+// ---------------------------------------------------------------------------
+/**
+ * One pressable control on one line: `[ Close ]`, never the word `button` with
+ * its label on the line below. The two cells the layout reserved for the focus
+ * marker stay blank — the screen owns focus, and the label must not shift when
+ * the marker arrives.
+ */
+function paintButton(surface, laid, node, scale, focused) {
+    const area = inner(laid, insets(node.style, scale));
+    if (area.w <= 0 || area.h <= 0)
+        return;
+    // The label's row: the middle of the button, not its first.
+    //
+    // A control the template gave height to is a box, and writing the label at the
+    // top of it put the words *on* the box's own top edge — through the border of
+    // a bordered button, and against the ceiling of a filled one, with the rest of
+    // the button empty underneath. Centring is what makes it read as a button
+    // with its label inside rather than a label with a box hanging off it.
+    const row = area.y + Math.floor(Math.max(0, area.h - 1) / 2);
+    if (focused === node)
+        surface.drawText(area.x, row, "› ", { bold: true }, BUTTON_MARKER);
+    const x = area.x + BUTTON_MARKER;
+    const width = area.w - BUTTON_MARKER;
+    if (width <= 0)
+        return;
+    const label = node.label;
+    const text = label.map((segment) => segment.text).join("");
+    // A control the template actually styled — the real buy CTA is
+    // `fillColor #ffffff, borderColor #ffffff, borderWidth 2, borderRadius 8` —
+    // is drawn as that button: its own fill and border are already painted, so
+    // the label is centred in it. The `[ … ]` chrome is our own affordance for a
+    // control that would otherwise be indistinguishable from a line of text, and
+    // on a button that already looks like one it is clutter — a bordered button
+    // came out reading `—[ RESTORE PURCHASE ]—`, its own frame and our brackets
+    // both.
+    const filled = sampleGradient(parseFill(node.style.fill), 0.5);
+    const boxed = drewBorder(laid, node.style.border);
+    /**
+     * Centre the label in the button itself, not in its padded content area.
+     *
+     * The two differ by the padding and by the two cells reserved for the focus
+     * marker, and centring in the smaller one pushed the label right until it
+     * overwrote the border it was supposed to sit inside — `RESTORE PURCHASE`
+     * came out with no closing edge. A bordered button keeps a cell clear at each
+     * edge; a filled one has the whole box.
+     */
+    const centred = (colour) => {
+        const from = boxed ? laid.x + 1 : laid.x;
+        const span = Math.max(0, boxed ? laid.w - 2 : laid.w);
+        const shown = ellipsize(text, span);
+        const room = Math.max(0, span - textColumns(shown));
+        // Never under the focus marker, which is drawn at the left of the same row.
+        const start = Math.max(from + Math.floor(room / 2), focused === node ? area.x + BUTTON_MARKER : from);
+        // And never past the far edge, whatever the arithmetic above worked out.
+        drawRuns(surface, start, row, shown, 0, styleRuns(label, colour), from + span);
+    };
+    if (filled && filled.a > 0) {
+        // A cell has no alpha, so a label in the fill's own colour would vanish.
+        centred({ fontColor: toHex(readable(filled)) });
+        return;
+    }
+    if (boxed) {
+        centred({});
+        return;
+    }
+    const styles = styleRuns(label, {});
+    // A control is one line: an authored icon button is a few cells wide and its
+    // label does not fit, and wrapping it would push the rows below it down.
+    const inside = ellipsize(text, width - BRACKETS);
+    surface.drawText(x, row, "[ ", {}, width);
+    drawRuns(surface, x + 2, row, inside, 0, styles, x + width);
+    const tail = 2 + textColumns(inside);
+    if (tail + 2 <= width)
+        surface.drawText(x + tail, row, " ]", {}, width - tail);
+}
+/** `[ ` and ` ]` around a label the template did not style. */
+const BRACKETS = 4;
+/**
+ * `text`, or as much of it as fits in `width` with an ellipsis for the rest.
+ *
+ * A control is one line — wrapping it would push everything below it down — so
+ * a label longer than its button has to lose something. Losing it silently
+ * reads as a shorter label than the template has: `SIGN IN WITH TV` looks
+ * authored, `SIGN IN WITH T…` says the button is too narrow for its words,
+ * which is the truth and is what the SDKs' own paywalls do.
+ *
+ * Grapheme by grapheme, because the ellipsis has to land on a whole character
+ * and an emoji or a CJK glyph is two columns wide.
+ */
+function ellipsize(text, width) {
+    if (width <= 0)
+        return "";
+    if (textColumns(text) <= width)
+        return text;
+    if (width === 1)
+        return "…";
+    let out = "";
+    let used = 0;
+    for (const glyph of graphemes(text)) {
+        const w = cellWidth(glyph);
+        if (used + w > width - 1)
+            break;
+        out += glyph;
+        used += w;
+    }
+    return `${out.trimEnd()}…`;
+}
+/**
+ * Whether `paintBorder` actually drew a frame around this box.
+ *
+ * Not merely whether one was authored: `drawFrame` needs two cells in each
+ * direction, so a one-row button's border is asked for and never appears — and
+ * that button does still want the `[ … ]` chrome, being otherwise a bare line
+ * of text.
+ */
+function drewBorder(laid, border) {
+    return (!!border && typeof border.width === "number" && border.width > 0 && laid.w >= 2 && laid.h >= 2);
+}
+/**
+ * Near-black or near-white, whichever reads against this fill. A terminal cell
+ * has no alpha, so a label painted in the fill's own colour would vanish — the
+ * real buy CTA is white on white without this.
+ */
+function readable(bg) {
+    // Rec. 601 luma, which is what every contrast rule of thumb is built on.
+    const luma = (bg.r * 299 + bg.g * 587 + bg.b * 114) / 1000;
+    return luma > 140 ? { r: 17, g: 17, b: 17, a: 1 } : { r: 255, g: 255, b: 255, a: 1 };
+}
+/**
+ * A sku card: its own lines inside a one-cell border, which is the border the
+ * layout reserved two cells of geometry for.
+ */
+function paintCard(surface, laid, node, scale, focused) {
+    const area = inner(laid, insets(node.style, scale));
+    if (area.w < 2 || area.h < 2)
+        return;
+    if (focused === node)
+        surface.drawText(area.x, area.y, "›", { bold: true }, 1);
+    const border = node.style?.border;
+    const color = parseColor(border?.color);
+    drawFrame(surface, area, (border?.radius ?? 0) > 0, color ? { fg: color } : {});
+    const width = area.w - CARD_BORDER * 2;
+    // Wrap with the same function the layout measured the card's height with
+    // (`layout.ts`'s `measureLines` -> `wrapText`). Clipping here instead would
+    // truncate a line the layout had already reserved a second row for, which is
+    // how `${sku.displayText}` lost its closing brace.
+    // A card wearing its CTA's fill needs a label that reads against it — the real
+    // buy control is white, and white-on-white is invisible.
+    const filled = sampleGradient(parseFill(node.style?.fill), 0.5);
+    const cardText = filled && filled.a > 0 ? { fontColor: toHex(readable(filled)) } : {};
+    let row = 0;
+    for (const line of node.lines) {
+        const text = line.map((segment) => segment.text).join("");
+        const styles = styleRuns(line, cardText);
+        let cursor = 0;
+        for (const part of wrapText(text, width)) {
+            if (row >= area.h - CARD_BORDER * 2)
+                return;
+            // Where this wrapped row starts in the unwrapped line, so its styling
+            // stays aligned: `wrapText` breaks on spaces, so the rows are in order.
+            const at = text.indexOf(part, cursor);
+            const start = at === -1 ? cursor : at;
+            drawRuns(surface, area.x + CARD_BORDER, area.y + CARD_BORDER + row, part, start, styles);
+            cursor = start + part.length;
+            row += 1;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Images
+// ---------------------------------------------------------------------------
+/**
+ * An image's cells, placed at its box's top left.
+ *
+ * The cells carry their own colours, and an empty `fg` or `bg` means "leave
+ * what is underneath" — `drawCells` already honours that, so nothing is
+ * pre-filled behind an image. There are no pixels at layout time, so the box is
+ * whatever was authored; a grid smaller than its box is never stretched to fill
+ * it. Anything that cannot be drawn is named rather than left as a hole.
+ */
+function paintImage(surface, laid, node, scale, deps) {
+    const area = inner(laid, insets(node.style, scale));
+    if (area.w <= 0 || area.h <= 0)
+        return;
+    // A terminal that draws real pixels takes the whole box. Nothing is painted
+    // there — a placeholder or a glyph image would show through wherever the
+    // picture is transparent — and whatever was painted there already is cleared,
+    // because such an image is drawn below any cell that carries a background
+    // colour and a fill left behind would hide it outright.
+    // What is already under this box — the page fill, a section's fill, whatever
+    // was painted before it. Both renderers composite the image against it, so it
+    // has to be read before the cells are cleared for one of them.
+    const beneath = surface.cellAt(area.x, area.y)?.bg;
+    const covered = deps.reserveImage?.({
+        url: node.url,
+        x: area.x,
+        y: area.y,
+        w: area.w,
+        h: area.h,
+        cropping: node.cropping,
+        section: laid.section,
+        backdrop: beneath,
+        align: imageAlignment(node.style),
+    });
+    if (covered) {
+        // Only what the picture actually covers. An image keeps its own shape, so
+        // it rarely fills the box it was given, and clearing the whole box left the
+        // terminal's own background showing in bands either side of every logo.
+        surface.clearRect(covered.x, covered.y, covered.w, covered.h);
+        return;
+    }
+    const cells = deps.image?.(node.url, area.w, area.h, beneath, node.cropping) ?? null;
+    if (cells && cells.length > 0) {
+        // Keeping the image's shape means it rarely fills its box exactly, so where
+        // it sits in the space left over is the authored alignment's business. Both
+        // renderers centred regardless, which put the NFL+ logo — `alignment: left`
+        // — in the middle of its box.
+        const align = imageAlignment(node.style);
+        const wide = Math.max(...cells.map((row) => row.length));
+        const x = area.x + Math.max(0, Math.floor((area.w - wide) * align.x));
+        const y = area.y + Math.max(0, Math.floor((area.h - cells.length) * align.y));
+        surface.drawCells(x, y, cells);
+        return;
+    }
+    // A background image that cannot be drawn paints nothing. It is decoration
+    // sized to the whole page, so its name would land at the top-left and sit
+    // over the header — on the real NFL location page that put `[image: …]`
+    // through the centred logo. A header or content image keeps its placeholder,
+    // because there it occupies layout a developer needs to see.
+    if (laid.section === "background")
+        return;
+    surface.drawText(area.x, area.y, `[image: ${shortName(node.alt ?? fileName(node.url))}]`, { dim: true }, area.w);
+}
+/**
+ * The authored alignment of an image inside its own box, as fractions.
+ *
+ * `horizontalAlignment` wins over the bare `alignment` the templates also use,
+ * which is the same precedence `paintText` and the layout apply.
+ */
+function imageAlignment(style) {
+    return {
+        x: alignmentFraction(style?.horizontalAlignment ?? style?.alignment),
+        y: alignmentFraction(style?.verticalAlignment),
+    };
+}
+function shortName(name) {
+    return name.length <= NAME_LIMIT ? name : `…${name.slice(-(NAME_LIMIT - 1))}`;
+}
+function fileName(url) {
+    const path = url.split(/[?#]/)[0];
+    return path.split("/").filter(Boolean).pop() ?? url;
+}
+// ---------------------------------------------------------------------------
+// Geometry
+// ---------------------------------------------------------------------------
+/**
+ * A box's padding in whole cells, through `style.ts`'s own `toCells` — the same
+ * call the layout made, so the content lands where the layout measured it.
+ * Yoga's computed width includes the padding, which is why it comes back off.
+ */
+function insets(style, scale) {
+    const edges = style?.padding;
+    if (!edges)
+        return NO_INSETS;
+    const out = { ...NO_INSETS };
+    for (const side of ["top", "right", "bottom", "left"]) {
+        const authored = edges[side];
+        // A value still carrying `${state.safeAreaTop}` is not a number of pixels.
+        if (typeof authored !== "number")
+            continue;
+        out[side] = toCells(authored, EDGE_AXIS[side], scale);
+    }
+    return out;
+}
+function inner(laid, pad) {
+    return {
+        x: laid.x + pad.left,
+        y: laid.y + pad.top,
+        w: laid.w - pad.left - pad.right,
+        h: laid.h - pad.top - pad.bottom,
+    };
+}