@namiml/cli 3.4.12-dev.202609302217 → 3.4.12-dev.202610051802

package/dist/render/layout.js

@@ -0,0 +1,544 @@
+/**
+ * The render model → absolute cell boxes, laid out by Yoga.
+ *
+ * This is the layout half 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, and this module turns the two into one flat array
+ * of rectangles in the order a painter should draw them. Nothing here reads a
+ * template, resolves a condition or parses a colour — a second parser for an
+ * authored value is exactly how two views of the same page drift apart, so
+ * every `width`, `height`, `padding`, `spacing` and alignment goes through
+ * `style.ts`.
+ *
+ * Four things are worth knowing before changing it:
+ *
+ *  1. **Yoga reports parent-relative coordinates.** `getComputedLayout()` on a
+ *     child is measured from its parent's box, so a button that reads `y = 2`
+ *     inside a content section starting at row 3 really sits on row 5.
+ *     `collect()` accumulates the offsets on the way down; every number in a
+ *     `LaidOut` is absolute within the page.
+ *  2. **The background slot is absolutely positioned.** It is laid out at the
+ *     top left at `100%` × `100%`, out of flow, so it fills the frame *behind*
+ *     the other three sections instead of pushing them down — and it is emitted
+ *     first, so a painter walking the array straight through paints it beneath
+ *     everything else. That is the bug this ticket was reopened for.
+ *  3. **So is the footer slot.** Only two of the four sections are in flow.
+ *     The footer is pinned to the bottom of the *frame* at `100%` wide, over
+ *     the content rather than after it, and the content section is given a
+ *     bottom inset equal to the footer's measured height — `sdk/web`'s absolute
+ *     `Footer.ts` plus the `--nami-footer-height` its `Content.ts` folds into
+ *     its `padding-bottom`, which is Apple's measured-footer content inset in
+ *     turn. Measuring it needs a layout, so `layoutPage` runs two passes.
+ *  4. **The Yoga nodes are freed.** They are WASM-backed, so the tree and its
+ *     config are released as soon as the numbers have been read. `layoutPage`
+ *     is pure in both directions: it neither keeps native memory nor touches
+ *     the model it was handed, which is what lets a screen re-lay-out a page on
+ *     every keystroke.
+ *
+ * `height` is the page's own height, not the frame's: a page taller than `rows`
+ * reports its full height and the frame scrolls it rather than squashing it. A
+ * page shorter than `rows` is padded out to the frame, so a background always
+ * has the whole frame to fill.
+ */
+import { alignmentProps, cellScale, parseSize, toCells } from "./style.js";
+import { textColumns } from "./surface.js";
+// Static, the way Ink itself imports it (`node_modules/ink/build/dom.js`). A
+// top-level `await import` here makes this module async, and an async module in
+// a screen's import graph breaks Ink's reconciler under Jest with "import a
+// file after the Jest environment has been torn down".
+import Yoga, { Align, Direction, Edge, FlexDirection, Gutter, Justify, PositionType } from "yoga-layout";
+/**
+ * The device a frame assumes when the caller does not name one: the phone the
+ * ticket measured against. `cols` and `rows` cannot supply it — they say how
+ * big the frame is in cells, not how many device pixels a cell is worth, and an
+ * authored `36` is a number of device pixels.
+ */
+export const DEFAULT_VIEWPORT = { width: 393, height: 852 };
+/** Rows an image gets when nothing authored says otherwise. */
+const DEFAULT_IMAGE_ROWS = 4;
+/** `› ` + `[ ` + label + ` ]` — the cells a button spends on chrome. */
+const BUTTON_CHROME = 6;
+/** A product card is drawn inside a one-cell border. */
+const CARD_BORDER = 2;
+/** Two edges and a row between them: the least a drawn box can hold a label in. */
+const BUTTON_BOX_ROWS = 3;
+/**
+ * Whether a button will be drawn as a box rather than as a line of text — which
+ * is what `paint.ts` decides from the same two properties.
+ */
+function drawsAsBox(style) {
+    const border = style.border;
+    const bordered = !!border && typeof border.width === "number" && border.width > 0;
+    const filled = !!style.fill && style.fill !== "transparent";
+    return bordered || filled;
+}
+/** `style.ts` has already turned the authored words into flex words. */
+const JUSTIFY = {
+    "flex-start": Justify.FlexStart,
+    "flex-end": Justify.FlexEnd,
+    center: Justify.Center,
+    "space-between": Justify.SpaceBetween,
+    "space-around": Justify.SpaceAround,
+    "space-evenly": Justify.SpaceEvenly,
+};
+const ALIGN = {
+    "flex-start": Align.FlexStart,
+    "flex-end": Align.FlexEnd,
+    center: Align.Center,
+    stretch: Align.Stretch,
+};
+const EDGE_SIDES = [
+    ["top", Edge.Top, "height"],
+    ["right", Edge.Right, "width"],
+    ["bottom", Edge.Bottom, "height"],
+    ["left", Edge.Left, "width"],
+];
+/**
+ * Rows a device viewport occupies in a frame this many columns wide.
+ *
+ * The frame's height is not the terminal's: a phone is 852 device pixels tall
+ * and a cell stands for a fixed number of them, so the frame a page is laid out
+ * against comes from the device. A screen showing fewer rows than this scrolls
+ * a window over the result.
+ */
+export function frameRows(viewport, cols) {
+    const width = Math.max(1, Math.floor(cols));
+    return Math.max(1, toCells(viewport.height, "height", cellScale(viewport, width)));
+}
+/**
+ * Lay a page out into absolute boxes, in paint order.
+ *
+ * `cols` × `rows` is the frame in cells; `viewport` is the device those cells
+ * stand for, and matters only because authored sizes are in device pixels.
+ *
+ * **Two passes, because the footer is measured.** `sdk/web`'s `PaywallScreen`
+ * puts the footer `position: absolute; bottom: 0` over the content container
+ * and publishes its rendered height as `--nami-footer-height`, which
+ * `Content.ts` folds into its own `padding-bottom` calc — the same
+ * measured-footer content inset Apple applies. Nothing can know that height
+ * before the footer has been laid out, so the first pass measures it and the
+ * second gives the content section the inset. Yoga is cheap enough for that
+ * (500 layouts of the real PPO page take 142 ms), and a page with no footer
+ * never runs the second pass at all.
+ */
+/**
+ * Known limitation: **horizontal overflow is not clamped.** Authored widths are
+ * device pixels scaled to cells, and on the real Penguin page a section comes
+ * out 79 columns wide inside a 44-column frame, so its copy wraps at 79 and the
+ * painter clips what falls outside — a sentence can lose its tail off the right
+ * edge. Clamping every node with `setMaxWidthPercent(100)` does remove the
+ * overflow, but it also moved a centred child one cell left of its parent and
+ * broke the containment invariant this module's tests pin, so it was reverted
+ * rather than shipped. Fixing it properly means agreeing the width *before*
+ * measurement, so layout and paint wrap at the same number.
+ */
+export function layoutPage(page, cols, rows, viewport = DEFAULT_VIEWPORT) {
+    const width = Math.max(1, Math.floor(cols));
+    const frame = Math.max(1, Math.floor(rows));
+    const scale = cellScale(viewport, width);
+    const measured = layoutOnce(page, width, frame, scale, 0);
+    if (measured.footerHeight === 0)
+        return measured;
+    return layoutOnce(page, width, frame, scale, measured.footerHeight);
+}
+/**
+ * One Yoga pass. `contentInset` is the bottom inset the content section carries
+ * for the footer drawn over it — zero on the measuring pass.
+ */
+function layoutOnce(page, width, frame, scale, contentInset) {
+    const config = Yoga.Config.create();
+    // Whole cells: a terminal has no sub-cell positions, and rounding once here
+    // is what stops two adjacent boxes overlapping or leaving a seam.
+    config.setPointScaleFactor(1);
+    const root = Yoga.Node.createWithConfig(config);
+    root.setFlexDirection(FlexDirection.Column);
+    root.setWidth(width);
+    root.setMinHeight(frame);
+    // Nothing may measure wider than the frame — see `fit`.
+    const cap = width;
+    const built = { node: page.root, ynode: root, children: [] };
+    for (const child of paintOrder(page.root)) {
+        const sub = build(child, "column", scale, config, cap);
+        if (isFooter(child)) {
+            // Out of flow, pinned to the bottom of the *frame* — not of the page,
+            // which is regularly taller and would drop the footer below the fold.
+            root.insertChild(frameLayer(config, frame, sub.ynode), root.getChildCount());
+        }
+        else {
+            if (contentInset > 0 && isContent(child))
+                insetForFooter(sub.ynode, child, contentInset, scale);
+            root.insertChild(sub.ynode, root.getChildCount());
+            if (isBackground(child))
+                asBackdrop(sub.ynode);
+        }
+        built.children.push(sub);
+    }
+    root.calculateLayout(width, undefined, Direction.LTR);
+    const boxes = [];
+    collect(built, 0, 0, 0, boxes);
+    const height = pageHeight(boxes, Math.round(root.getComputedLayout().height));
+    const footer = boxes.find((laid) => laid.section === "footer");
+    root.freeRecursive();
+    config.free();
+    return { boxes, height, footerHeight: footer ? footer.h : 0 };
+}
+/**
+ * The page's real height, and the backdrop stretched to match it.
+ *
+ * A section can overflow its own box — a child sized `50%` of a parent that is
+ * itself auto-height does not add to that parent's content height, which is
+ * ordinary flexbox behaviour and happens on the committed Pimsleur fixture,
+ * where the sections measure 105 rows and the content reaches row 196. The page
+ * is as tall as the lowest row anything reaches, or the frame, whichever is
+ * more; anything less and the scroll window would clip content that exists.
+ *
+ * The root and the background slot are then stretched to that height so the
+ * backdrop really is behind the whole page rather than behind the first screen
+ * of it. Re-running the layout against the taller root is deliberately **not**
+ * done: percentage-sized children would grow with it and the page would chase
+ * its own tail.
+ */
+function pageHeight(boxes, rootHeight) {
+    const bottom = boxes.reduce((lowest, laid) => Math.max(lowest, laid.y + laid.h), 0);
+    const height = Math.max(rootHeight, bottom);
+    for (const laid of boxes) {
+        if (laid.depth === 0 || isBackground(laid.node))
+            laid.h = Math.max(laid.h, height);
+    }
+    return height;
+}
+/**
+ * The page root's children in the order they are painted: the background slot
+ * first, then the rest in the order the model emitted them — header, content,
+ * footer. A page with no background slot is left alone.
+ */
+function paintOrder(root) {
+    if (root.kind !== "box")
+        return [];
+    const background = root.children.filter(isBackground);
+    if (background.length === 0)
+        return root.children;
+    return [...background, ...root.children.filter((child) => !isBackground(child))];
+}
+function isBackground(node) {
+    return sectionOf(node) === "background";
+}
+function isFooter(node) {
+    return sectionOf(node) === "footer";
+}
+function isContent(node) {
+    return sectionOf(node) === "content";
+}
+function sectionOf(node) {
+    return node.kind === "box" ? node.section : undefined;
+}
+/**
+ * Take the background out of flow and give it the whole frame. Its own authored
+ * size is deliberately overridden: a background container authored `100%` tall
+ * would otherwise stack above the header and push the page off the bottom of
+ * the very frame it is meant to sit behind.
+ */
+function asBackdrop(ynode) {
+    ynode.setPositionType(PositionType.Absolute);
+    ynode.setPosition(Edge.Left, 0);
+    ynode.setPosition(Edge.Top, 0);
+    ynode.setWidthPercent(100);
+    ynode.setHeightPercent(100);
+}
+/**
+ * The footer, pinned to the bottom of the frame and full width, the way
+ * `sdk/web`'s `containers/Footer.ts` is `position: absolute; bottom: 0;
+ * width: 100%` over the content container.
+ *
+ * "The bottom" has to mean the bottom of the **frame**: the page is usually
+ * taller than the terminal and scrolls, and a footer pinned to the bottom of
+ * the page would only appear once the developer had scrolled all the way down —
+ * which is the opposite of what a viewport-anchored footer does. So the footer
+ * is hung inside a layer the size of the frame, itself out of flow at the top
+ * left, and the numbers come back absolute like every other box: the footer
+ * lands at `frame - its height` whatever the page does below it.
+ *
+ * A footer taller than the frame gets a negative top, exactly as an over-tall
+ * absolute element overflows its container's top edge on the web. Nothing in
+ * flow moves for it, so the content still starts at the top of the page.
+ */
+function frameLayer(config, frame, footer) {
+    const layer = Yoga.Node.createWithConfig(config);
+    layer.setPositionType(PositionType.Absolute);
+    layer.setPosition(Edge.Left, 0);
+    layer.setPosition(Edge.Top, 0);
+    layer.setWidthPercent(100);
+    layer.setHeight(frame);
+    footer.setPositionType(PositionType.Absolute);
+    footer.setPosition(Edge.Bottom, 0);
+    footer.setWidthPercent(100);
+    layer.insertChild(footer, 0);
+    return layer;
+}
+/**
+ * The content section's bottom inset: its own authored bottom padding **plus**
+ * the footer's measured height, which is `Content.ts`'s
+ * `padding-bottom: calc(<authored>px + var(--nami-footer-height, 0px))` in
+ * cells. Without it the last line of content sits under a footer drawn over it.
+ */
+function insetForFooter(ynode, node, footerHeight, scale) {
+    const authored = node.kind === "box" ? node.style.padding?.bottom : undefined;
+    const own = typeof authored === "number" ? toCells(authored, "height", scale) : 0;
+    ynode.setPadding(Edge.Bottom, own + footerHeight);
+}
+// ---------------------------------------------------------------------------
+// Model → Yoga
+// ---------------------------------------------------------------------------
+function build(node, parent, scale, config, cap) {
+    const ynode = Yoga.Node.createWithConfig(config);
+    const children = [];
+    // Only a row's children share a width. Vertically the frame scrolls rather
+    // than squashing, so nothing shrinks on that axis; `minWidth: 0` is the
+    // flexbox rule that lets a flex item shrink below its own content, without
+    // which two cards in one row paint over each other.
+    if (parent === "row") {
+        ynode.setFlexShrink(1);
+        ynode.setMinWidth(0);
+    }
+    else {
+        ynode.setFlexShrink(0);
+    }
+    switch (node.kind) {
+        case "box": {
+            const flow = node.style.direction === "horizontal" ? "row" : "column";
+            ynode.setFlexDirection(flow === "row" ? FlexDirection.Row : FlexDirection.Column);
+            applyStyle(ynode, node.style, flow, parent, scale, node.children.length > 0);
+            // A row container the template did not size fills the width it was given,
+            // the way a block-level flex container does on the web. Without it two
+            // `100%` cards side by side spill out of a row sized to its content.
+            if (flow === "row" && node.style.width === undefined)
+                ynode.setWidthPercent(100);
+            for (const child of node.children) {
+                const sub = build(child, flow, scale, config, cap);
+                ynode.insertChild(sub.ynode, ynode.getChildCount());
+                children.push(sub);
+            }
+            break;
+        }
+        case "spacer": {
+            // A spacer pushes along whichever axis its parent runs.
+            const cells = Math.max(1, toCells(node.size, parent === "row" ? "width" : "height", scale));
+            if (parent === "row")
+                ynode.setWidth(cells);
+            else
+                ynode.setHeight(cells);
+            break;
+        }
+        case "text": {
+            applyStyle(ynode, node.style, "column", parent, scale, false);
+            const body = plain(node.segments, node.style.capitalize);
+            ynode.setMeasureFunc((available) => measureLines([body], available, cap));
+            break;
+        }
+        case "button": {
+            applyStyle(ynode, node.style, "column", parent, scale, false);
+            const label = plain(node.label);
+            // A drawn box needs three rows to hold anything: one for each edge and one
+            // for what is inside. An authored TV button is about 60 device pixels tall,
+            // which rounds to two cells, and at two the frame took both rows and the
+            // label ended up written along the top edge — `╭──MORE PLANS──╮` over an
+            // empty box. Rounding such a button up by one row is the same kind of
+            // approximation as the cell grid itself, and it is the difference between
+            // a button and a caption with a box under it.
+            if (drawsAsBox(node.style))
+                ynode.setMinHeight(BUTTON_BOX_ROWS);
+            // A control is one line. An authored icon button is a few cells wide and
+            // its label does not fit; wrapping it would push everything below it down
+            // and paint over whatever shares its row, so it clips instead.
+            ynode.setMeasureFunc((available) => ({
+                width: Math.min(fit(available, cap), textColumns(label) + BUTTON_CHROME),
+                height: 1,
+            }));
+            break;
+        }
+        case "product": {
+            applyStyle(ynode, node.style ?? {}, "column", parent, scale, false);
+            const lines = node.lines.map((line) => plain(line));
+            ynode.setMeasureFunc((available) => {
+                const inner = measureLines(lines, fit(available, cap) - CARD_BORDER, cap);
+                return { width: inner.width + CARD_BORDER, height: inner.height + CARD_BORDER };
+            });
+            break;
+        }
+        case "image": {
+            applyStyle(ynode, node.style ?? {}, "column", parent, scale, false);
+            // With no bytes in hand there is no aspect to honour, so an unsized image
+            // takes a fixed few rows and whatever width it was given.
+            if (parseSize(node.style?.height, "height", scale).kind === "content")
+                ynode.setHeight(DEFAULT_IMAGE_ROWS);
+            break;
+        }
+    }
+    return { node, ynode, children };
+}
+/**
+ * One node's authored box style onto its Yoga node. `flow` is the direction
+ * this node lays its own children out in (gap and alignment); `parent` is the
+ * direction it sits in (whether it may shrink to its content).
+ */
+function applyStyle(ynode, style, flow, parent, scale, hasChildren) {
+    applySize(ynode, parseSize(style.width, "width", scale), "width");
+    const height = parseSize(style.height, "height", scale);
+    // An authored height is a shape, not a cap: terminal copy wraps to more rows
+    // than a device's type does, and a hard height would let the overflow paint
+    // over the next section. A container takes its height as a floor and grows;
+    // the frame is the one thing that really clips.
+    applySize(ynode, height, hasChildren && height.kind !== "content" ? "minHeight" : "height");
+    // `fitContent` is an explicit request to shrink to the content. An absent
+    // size is not — it means "stretch", which is what flexbox does by default —
+    // and `parseSize` reports the two the same way, so the authored value decides.
+    if (shrinksToContent(style, parent, scale))
+        ynode.setAlignSelf(Align.FlexStart);
+    applyEdges(style.padding, scale, (edge, value) => ynode.setPadding(edge, value));
+    applyEdges(style.margin, scale, (edge, value) => ynode.setMargin(edge, value));
+    if (style.spacing !== undefined) {
+        const gap = toCells(style.spacing, flow === "row" ? "width" : "height", scale);
+        if (gap > 0)
+            ynode.setGap(flow === "row" ? Gutter.Column : Gutter.Row, gap);
+    }
+    // `sdk/web`'s `alignAndJustifyItems`: a bare `alignment` is the fallback for
+    // the horizontal axis in both directions, which is why it folds in here
+    // rather than being treated as a third axis.
+    const aligned = alignmentProps(style.horizontalAlignment ?? style.alignment, style.verticalAlignment, flow);
+    const justify = aligned.justifyContent === undefined ? undefined : JUSTIFY[aligned.justifyContent];
+    if (justify !== undefined)
+        ynode.setJustifyContent(justify);
+    const align = aligned.alignItems === undefined ? undefined : ALIGN[aligned.alignItems];
+    if (align !== undefined)
+        ynode.setAlignItems(align);
+}
+/** True when the node authored a cross-axis size that resolves to "as big as my content". */
+function shrinksToContent(style, parent, scale) {
+    const axis = parent === "row" ? "height" : "width";
+    const authored = parent === "row" ? style.height : style.width;
+    if (authored === undefined)
+        return false;
+    return parseSize(authored, axis, scale).kind === "content";
+}
+function applySize(ynode, size, prop) {
+    switch (size.kind) {
+        case "percent":
+            if (prop === "width")
+                ynode.setWidthPercent(size.value);
+            else if (prop === "height")
+                ynode.setHeightPercent(size.value);
+            else
+                ynode.setMinHeightPercent(size.value);
+            break;
+        case "cells":
+            if (prop === "width")
+                ynode.setWidth(size.value);
+            else if (prop === "height")
+                ynode.setHeight(size.value);
+            else
+                ynode.setMinHeight(size.value);
+            break;
+        default:
+            break;
+    }
+}
+function applyEdges(edges, scale, set) {
+    if (!edges)
+        return;
+    for (const [side, edge, axis] of EDGE_SIDES) {
+        const authored = edges[side];
+        // A value still carrying `${state.safeAreaTop}` is not a number of pixels.
+        if (typeof authored !== "number")
+            continue;
+        const cells = toCells(authored, axis, scale);
+        if (cells > 0)
+            set(edge, cells);
+    }
+}
+// ---------------------------------------------------------------------------
+// Reading the layout back
+// ---------------------------------------------------------------------------
+/**
+ * Depth first, a parent before its children, accumulating the parent offsets.
+ *
+ * The slot a box belongs to is inherited on the way down, so every box in the
+ * footer's subtree carries `section: "footer"` and a painter can lift the lot
+ * out of the scrolling page in one filter.
+ */
+function collect(built, originX, originY, depth, out, section) {
+    const slot = sectionOf(built.node) ?? section;
+    const layout = built.ynode.getComputedLayout();
+    const x = originX + Math.round(layout.left);
+    const y = originY + Math.round(layout.top);
+    const laid = { node: built.node, x, y, w: Math.round(layout.width), h: Math.round(layout.height), depth };
+    if (slot)
+        laid.section = slot;
+    out.push(laid);
+    for (const child of built.children)
+        collect(child, x, y, depth + 1, out, slot);
+}
+// ---------------------------------------------------------------------------
+// Measuring
+// ---------------------------------------------------------------------------
+/**
+ * Wrap one string into terminal rows.
+ *
+ * Greedy word wrap on spaces, with a word longer than the line broken where it
+ * runs out — a 64-character asset name must not push everything beside it off
+ * the row. Authored newlines are kept, and an empty string is one empty row
+ * rather than none, because a blank line still occupies the page.
+ */
+export function wrapText(value, width) {
+    const limit = Number.isFinite(width) && width >= 1 ? Math.floor(width) : 1;
+    const rows = [];
+    for (const paragraph of value.split("\n")) {
+        let line = "";
+        for (const word of paragraph.split(" ")) {
+            if (line !== "" && textColumns(line) + 1 + textColumns(word) <= limit) {
+                line = `${line} ${word}`;
+                continue;
+            }
+            if (line !== "")
+                rows.push(line);
+            let pending = word;
+            while (textColumns(pending) > limit) {
+                rows.push(pending.slice(0, limit));
+                pending = pending.slice(limit);
+            }
+            line = pending;
+        }
+        rows.push(line);
+    }
+    return rows;
+}
+/** The box a list of lines needs at a given available width. */
+function measureLines(lines, available, cap) {
+    const limit = Math.max(1, fit(available, cap));
+    let width = 0;
+    let height = 0;
+    for (const line of lines) {
+        const wrapped = wrapText(line, limit);
+        height += wrapped.length;
+        for (const row of wrapped)
+            width = Math.max(width, textColumns(row));
+    }
+    return { width: Math.min(width, limit), height: Math.max(height, 1) };
+}
+/** Yoga passes `NaN` for "as much as you like"; a measure function has to cope. */
+/**
+ * Yoga passes `NaN` for "as much as you like", which happens whenever a parent
+ * lets a child size to content — an authored `horizontalAlignment: center` does
+ * exactly that. Measuring unconstrained then reports max-content: on the real
+ * Penguin page one sentence measured 79 columns inside a 44-column frame, its
+ * `width: 100%` children inherited that, and the painter clipped the tail off
+ * the right edge. Capping an unconstrained measure at the frame keeps
+ * measurement and paint agreeing on where copy wraps.
+ */
+function fit(available, cap) {
+    const limit = Number.isFinite(available) && available > 0 ? Math.floor(available) : cap;
+    return Math.max(1, Math.min(limit, cap));
+}
+function plain(segments, capitalize) {
+    const value = segments.map((segment) => segment.text).join("");
+    return capitalize ? value.toUpperCase() : value;
+}