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

package/dist/screens/PageRender.js

@@ -0,0 +1,273 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Box, Text } from "ink";
+import { decodeImage, fetchImage, halfBlockRows, quadrantRows, sextantRows } from "../render/image.js";
+import { blockMode } from "../render/capabilities.js";
+import { fitToBox } from "../render/graphics.js";
+import { useTerminalImages } from "./useTerminalImages.js";
+import { paintFooter, paintPage } from "../render/paint.js";
+import { DEFAULT_VIEWPORT, frameRows } from "../render/layout.js";
+import { Surface } from "../render/surface.js";
+import { palette } from "../theme.js";
+export { DEFAULT_VIEWPORT };
+/**
+ * A launched page, drawn as the paywall rather than outlined as a tree.
+ *
+ * **This screen does not lay anything out.** `src/render/layout.ts` asks Yoga
+ * for coordinates, `src/render/paint.ts` paints them into a character grid where
+ * every cell owns its own colours, and this file prints that grid one row at a
+ * time. Ink is the printer, not the layout engine.
+ *
+ * That is the whole point of the compositor: a terminal has no z-order and an
+ * Ink `Box` carries one background colour, so the earlier flexbox version drew
+ * a background layer *above* the page, flattened a gradient to one colour and
+ * could never put an image under text. Painting cells fixes all three at once.
+ *
+ * The frame is drawn in two pieces, because the footer does not scroll. The
+ * page surface gives the scrolled window; the footer is painted on its own and
+ * its rows replace the window's last rows, so it stays against the bottom of
+ * the frame with the content running under it — the terminal's version of
+ * `sdk/web`'s `position: absolute; bottom: 0` footer over a scrolling content
+ * container. The layout has already inset the content by the footer's height,
+ * so nothing is left hiding behind it.
+ */
+/**
+ * The widest a portrait device's frame may get, however much room there is.
+ *
+ * 44 is where a 393×852 phone comes out about 48 rows: a phone-sized inset
+ * beside the events, which is what this pane is for. It was briefly 88, to buy
+ * an image more cells to be drawn in — at 44 a logo laid out into a box one row
+ * tall, and one row cannot show a shape however finely a glyph subdivides it.
+ * That is no longer the trade: a terminal that speaks a graphics protocol draws
+ * the image at its own resolution, so how many cells the box spans stops
+ * deciding how much of the image survives, and the frame can be the size that
+ * reads best again.
+ *
+ * It still decides on a terminal that draws glyphs, where cells *are* the
+ * resolution. If images there want more room, this is the number to raise —
+ * `frameCols` keeps the device's shape at any value.
+ */
+export const PORTRAIT_FRAME_COLS = 44;
+/**
+ * The narrowest the frame will shrink to fit a short terminal. Below this the
+ * page's own text stops wrapping into anything readable, so the frame keeps
+ * this width and the window scrolls instead.
+ */
+export const MIN_FRAME_COLS = 32;
+/** The one line under the frame saying what the render is not. */
+export const APPROXIMATION_NOTE = "Approximation · no per-character font sizes or custom fonts · grids and carousels render once, not per row or slide";
+/**
+ * Why a product card can read `${sku.displayText}` instead of a price.
+ *
+ * A paywall's own SKUs carry `displayText` as smart text of their own — the real
+ * staging value is `**${sku.price} per ${sku.period}**` — so resolving it needs
+ * store product data. The CLI registers no store, and a live configure against
+ * staging Test Nami reports 0 products, so the price tokens have nothing to
+ * resolve from. Leaving the token visible is deliberate; without this line it
+ * reads as a rendering bug rather than a missing catalogue.
+ */
+export const NO_PRODUCTS_NOTE = "No store products, so ${sku.price} and the display text built on it stay unresolved — the CLI has no store to price against";
+/** True when the page shows product cards, which is when the note above is worth saying. */
+export function hasProductCards(node) {
+    if (node.kind === "product")
+        return true;
+    return node.kind === "box" ? node.children.some(hasProductCards) : false;
+}
+/**
+ * How many columns the frame takes for a device viewport in a pane this size.
+ *
+ * Width alone is the wrong question, and getting that wrong is what made an
+ * 88-column phone look nothing like a phone. The frame's height comes from its
+ * width (`frameRows`), so widening a 393×852 phone to 88 columns makes it 95
+ * rows tall — and a terminal showing 50 of them displays the top half of a
+ * phone, which reads as a squat, wrong-shaped box no matter how exactly the
+ * model preserved the aspect. The aspect is only right where it is *seen*.
+ *
+ * So when a row budget is given the frame is the largest one that fits it
+ * whole: the device's own shape, as large as the window allows, growing by
+ * itself when the window grows or the font shrinks. `MIN_FRAME_COLS` is the
+ * floor — below it the frame stops shrinking and the window scrolls, which is
+ * the old behaviour and better than an unreadable page.
+ *
+ * Without a row budget it is width alone, which is what a caller measuring
+ * columns before it knows its height wants.
+ */
+export function frameCols(viewport, width, rows) {
+    const available = Math.max(1, Math.floor(width));
+    const widest = viewport.height > viewport.width ? Math.min(available, PORTRAIT_FRAME_COLS) : available;
+    if (rows === undefined)
+        return widest;
+    const budget = Math.max(1, Math.floor(rows));
+    // `frameRows` rises with `cols`, so the first width that fits walking down is
+    // the widest that fits. It is at most a few dozen steps of arithmetic.
+    let cols = widest;
+    while (cols > MIN_FRAME_COLS && frameRows(viewport, cols) > budget)
+        cols -= 1;
+    return Math.min(cols, available);
+}
+/**
+ * What the arrows move between: the nodes the model marked focusable, in source
+ * order. A product card is one stop, not one per line, and a container the
+ * template made pressable is one stop too.
+ */
+export function focusablePageNodes(page) {
+    const out = [];
+    walk(page.root, (node) => {
+        if ("focusable" in node && node.focusable)
+            out.push(node);
+    });
+    return out;
+}
+function walk(node, visit) {
+    visit(node);
+    if (node.kind === "box")
+        for (const child of node.children)
+            walk(child, visit);
+}
+export function PageRender({ page, caps, width, height, viewport = DEFAULT_VIEWPORT, focused, scrollTop = 0, loadImage, }) {
+    // Two columns go to the frame's own border, and four rows to the page name,
+    // the border and the scroll hint — the same budget `visible` spends below.
+    const cols = frameCols(viewport, Math.max(width - 2, 1), Math.max(height - 4, 1));
+    const images = useImages(page, caps, loadImage);
+    // Decoding is the expensive half of drawing an image and the page is repainted
+    // on every keystroke, so each url is decoded once and kept.
+    const decoded = useRef(new Map());
+    const decode = (url, bytes) => {
+        if (!decoded.current.has(url))
+            decoded.current.set(url, decodeImage(bytes));
+        return decoded.current.get(url) ?? null;
+    };
+    // A terminal that draws pixels takes the image boxes away from the painter.
+    // The painter reports where they are as it goes, and the hook draws them
+    // there; the surface keeps the holes, so nothing shows through a picture.
+    const pixels = caps.imageTier === "kitty" && caps.trueColor;
+    const reserved = useRef([]);
+    // Where the page's reservations stop and the footer's begin. The two are
+    // painted into different surfaces and composited at different rows, so their
+    // boxes cannot be read in the same coordinates.
+    const footerFrom = useRef(0);
+    const frameRef = useRef(null);
+    const deps = useMemo(() => ({
+        focused,
+        reserveImage: pixels
+            ? (area) => {
+                // The fit is done here, not in the hook, because the painter needs
+                // the answer: it clears exactly what the picture will cover, and an
+                // image keeps its own shape rather than filling the box it was
+                // given. A url that will not decode is left to the painter.
+                const raw = images.get(area.url);
+                const source = raw ? decode(area.url, raw) : null;
+                if (!source)
+                    return null;
+                const fitted = fitToBox(source, area, area.cropping, area.align);
+                // `paintPage` and `paintFooter` both walk with these deps, so the
+                // list is reset by the render that is about to use it, not by a
+                // caller who would have to remember to.
+                reserved.current.push({
+                    url: area.url,
+                    x: fitted.x,
+                    y: fitted.y,
+                    cols: fitted.cols,
+                    rows: fitted.rows,
+                    crop: fitted.crop,
+                    section: area.section,
+                    backdrop: area.backdrop,
+                });
+                return { x: fitted.x, y: fitted.y, w: fitted.cols, h: fitted.rows };
+            }
+            : undefined,
+        image: (url, w, h, backdrop, cropping) => {
+            const bytes = images.get(url);
+            if (!bytes || !caps.trueColor)
+                return null;
+            const pixels = decodeImage(bytes);
+            if (!pixels)
+                return null;
+            const draw = { sextant: sextantRows, quadrant: quadrantRows, half: halfBlockRows }[blockMode()];
+            return draw(pixels, w, h, backdrop, cropping);
+        },
+    }), [focused, images, caps.trueColor, pixels]);
+    const surface = useMemo(() => {
+        reserved.current = [];
+        return paintPage(page, cols, frameRows(viewport, cols), viewport, deps);
+    }, [page, cols, viewport, deps]);
+    // The footer is not in that surface: it does not scroll with the page.
+    const footer = useMemo(() => {
+        footerFrom.current = reserved.current.length;
+        return paintFooter(page, cols, viewport, deps);
+    }, [page, cols, viewport, deps]);
+    // One row for the page name, two for the border, one for the scroll hint.
+    const visible = Math.max(1, Math.min(surface.rows, Math.max(height - 4, 1)));
+    const hidden = Math.max(0, surface.rows - visible);
+    const offset = Math.max(0, Math.min(Math.floor(scrollTop), hidden));
+    // Compose the visible window as cells, not as rows of spans: the footer must
+    // cover the page where it has a fill and let the page through where it does
+    // not, the way an absolutely positioned footer does on the web. Replacing
+    // whole rows punched a hole wherever the footer was transparent.
+    const window = useMemo(() => {
+        const frame = new Surface(cols, visible);
+        frame.blit(surface, 0, -offset);
+        if (footer)
+            frame.blit(footer, 0, visible - footer.rows);
+        return frame.toRows();
+    }, [surface, footer, cols, visible, offset]);
+    // Both sets of boxes, in the window's own rows: the page's scroll under the
+    // window, the footer's are pinned to the bottom of it.
+    const imageAreas = useMemo(() => reserved.current.map((area, index) => index < footerFrom.current
+        ? { ...area, y: area.y - offset }
+        : { ...area, y: visible - (footer?.rows ?? 0) + area.y }), [surface, footer, offset, visible]);
+    useTerminalImages({ enabled: pixels, frameRef, areas: imageAreas, bytes: images, windowRows: visible });
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { bold: true, children: "Page" }), " ", _jsx(Text, { children: page.pageName || "—" })] }), _jsx(Box, { ref: frameRef, width: cols + 2, borderStyle: "round", borderColor: caps.trueColor ? palette.aqua : undefined, flexDirection: "column", children: window.map((spans, index) => (_jsx(Text, { children: spans.map((span, i) => _jsx(Text, { ...inkProps(span, caps), children: span.text }, i)) }, index))) }), hidden > 0 && (_jsxs(Text, { dimColor: true, children: ["\u25BE ", hidden - offset, " more rows below \u00B7 ", offset, " above \u00B7 PgUp/PgDn"] }))] }));
+}
+/** A painted span's styling, dropped entirely when the terminal has no true colour. */
+function inkProps(span, caps) {
+    return {
+        color: caps.trueColor ? span.fg : undefined,
+        backgroundColor: caps.trueColor ? span.bg : undefined,
+        bold: span.bold,
+        italic: span.italic,
+        underline: span.underline,
+        dimColor: span.dim,
+    };
+}
+/**
+ * Every image on the page, fetched once and kept by url.
+ *
+ * Nothing is fetched at the `placeholder` tier, which is what a non-TTY (and so
+ * every test render) reports — a screen test never touches the network by
+ * accident. A url that will not load stays out of the map and draws as its own
+ * name, because one unreachable asset must never take the page down.
+ */
+function useImages(page, caps, loadImage) {
+    const urls = useMemo(() => imageUrls(page), [page]);
+    const [loaded, setLoaded] = useState(() => new Map());
+    const key = urls.join("\u0000");
+    useEffect(() => {
+        if (caps.imageTier === "placeholder" || urls.length === 0)
+            return;
+        const load = loadImage ?? ((url) => fetchImage(url));
+        let live = true;
+        void Promise.all(urls.map(async (url) => [url, await load(url)])).then((pairs) => {
+            if (!live)
+                return;
+            const next = new Map();
+            for (const [url, bytes] of pairs)
+                if (bytes)
+                    next.set(url, bytes);
+            setLoaded(next);
+        });
+        return () => {
+            live = false;
+        };
+        // `key` stands in for `urls`, which is rebuilt whenever the page changes.
+    }, [key, caps.imageTier]);
+    return loaded;
+}
+function imageUrls(page) {
+    const urls = [];
+    walk(page.root, (node) => {
+        if (node.kind === "image" && node.url && !urls.includes(node.url))
+            urls.push(node.url);
+    });
+    return urls;
+}

package/dist/screens/Shell.js

@@ -12,10 +12,13 @@ import { NewToNami } from "./NewToNami.js";
 import { SuccessScreen } from "./SuccessScreen.js";
 import { PickPlacement } from "./PickPlacement.js";
 import { LaunchScreen, focusableNodes } from "./LaunchScreen.js";
+import { focusablePageNodes } from "./PageRender.js";
 import { corePlacements } from "../placements/list.js";
 import { compositeForPlacement, pressNode, startLaunch as startLaunchFn } from "../placements/launch.js";
+import { renderPageForPlacement } from "../placements/page.js";
+import { detectCaps } from "../render/capabilities.js";
 import { EventBus } from "../events/bus.js";
-import { terminalColumns } from "../utils/terminal.js";
+import { terminalColumns, terminalRows } from "../utils/terminal.js";
 import { deviceById, presetsFor, resolveDevice, toSelection } from "../devices/presets.js";
 import { SelectionHeader } from "./SelectionHeader.js";
 import { Thinking } from "../components/Thinking.js";
@@ -37,7 +40,7 @@ import TextInput from "ink-text-input";
  * pasted App Platform ID. Every path funnels back through `configure`, so the
  * SDK is re-configured in place and each platform keeps its own storage file.
  */
-export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitWhenDone = true, phase, hostWasExplicit = false, verify, configure, placementsSource, compositeSource, startLaunch }) {
+export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitWhenDone = true, phase, hostWasExplicit = false, verify, configure, placementsSource, compositeSource, pageSource, startLaunch }) {
     const { exit } = useApp();
     const { stdout } = useStdout();
     const [state, setState] = useState({ kind: "boot" });
@@ -55,6 +58,9 @@ export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitW
     const [paused, setPaused] = useState(false);
     const [expanded, setExpanded] = useState(false);
     const [focusIndex, setFocusIndex] = useState(0);
+    // The launch pane opens on the render; `t` swaps it for NAM-4542's outline.
+    const [view, setView] = useState("render");
+    const [scrollTop, setScrollTop] = useState(0);
     const [notice, setNotice] = useState(undefined);
     // The bus subscriber runs outside React's render, so pause is read from a ref.
     const pausedRef = useRef(false);
@@ -179,9 +185,17 @@ export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitW
         setFocusIndex(0);
         setExpanded(false);
         setNotice(undefined);
+        setView("render");
+        setScrollTop(0);
         pausedRef.current = false;
         setPaused(false);
-        setState({ kind: "launch", home, placement, composite: (compositeSource ?? compositeForPlacement)(placement.label) });
+        setState({
+            kind: "launch",
+            home,
+            placement,
+            composite: (compositeSource ?? compositeForPlacement)(placement.label),
+            page: (pageSource ?? renderPageForPlacement)(placement.label),
+        });
     };
     // Subscriptions live and die with the launch state, so leaving the screen
     // unregisters every handler it added.
@@ -350,8 +364,13 @@ export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitW
                                 .then(() => ctx.config.markOnboardingDone())
                                 .catch(() => { });
                             setState({ kind: "home", app: state.app, platform: state.platform, device: state.device, result });
-                        }, onBack: () => chooseDevice(state.app, state.platform, state.device ?? undefined) })), state.kind === "home" && (_jsx(SuccessScreen, { app: state.app, platform: state.platform, device: state.device, result: state.result, host: ctx.host, canSwitchDevice: presetsFor(state.platform.type).length > 1 })), state.kind === "pick-placement" && (_jsx(PickPlacement, { placements: state.placements, onSelect: (placement) => openLaunch(state.home, placement), onCancel: () => setState(state.home) })), state.kind === "launch" && (_jsx(LaunchScreen, { placement: state.placement, composite: state.composite, deviceName: state.home.device?.displayName, events: events, width: Math.max(terminalColumns(stdout) - 2, 40), paused: paused, expanded: expanded, selectedSeq: events.at(-1)?.seq, focusIndex: focusIndex, onPress: press, onMove: (delta) => {
-                            const count = focusableNodes(state.composite).length;
+                        }, onBack: () => chooseDevice(state.app, state.platform, state.device ?? undefined) })), state.kind === "home" && (_jsx(SuccessScreen, { app: state.app, platform: state.platform, device: state.device, result: state.result, host: ctx.host, canSwitchDevice: presetsFor(state.platform.type).length > 1 })), state.kind === "pick-placement" && (_jsx(PickPlacement, { placements: state.placements, onSelect: (placement) => openLaunch(state.home, placement), onCancel: () => setState(state.home) })), state.kind === "launch" && (_jsx(LaunchScreen, { placement: state.placement, composite: state.composite, page: state.page, caps: detectCaps(ctx.env, Boolean(stdout?.isTTY)), deviceName: state.home.device?.displayName, viewport: state.home.device ?? undefined, events: events, width: Math.max(terminalColumns(stdout) - 2, 40), height: Math.max(terminalRows(stdout) - 6, 8), view: view, paused: paused, expanded: expanded, selectedSeq: events.at(-1)?.seq, focusIndex: focusIndex, scrollTop: scrollTop, onPress: press, onMove: (delta) => {
+                            // Each view has its own focusable list, so the count follows the view.
+                            const count = view === "render" ? focusablePageNodes(state.page).length : focusableNodes(state.composite).length;
                             setFocusIndex((index) => (count === 0 ? 0 : (index + delta + count) % count));
+                        }, onScroll: (delta) => setScrollTop((top) => Math.max(0, top + delta)), onToggleView: () => {
+                            // The two views focus different node lists, so the index cannot carry over.
+                            setFocusIndex(0);
+                            setView((current) => (current === "render" ? "outline" : "render"));
                         }, onTogglePause: togglePause, onClear: clearEvents, onToggleExpand: () => setExpanded((on) => !on), onBack: () => setState(state.home), notice: notice })), state.kind === "welcome" && (_jsx(WelcomeScreen, { host: ctx.host, onChoose: onWelcomeChoice, onCancel: () => finish(0) })), state.kind === "new-to-nami" && (_jsx(NewToNami, { host: ctx.host, onContinue: () => { step("configure"); setState({ kind: "paste-id", home: null }); }, onBack: () => setState({ kind: "welcome" }) })), state.kind === "switch" && (_jsx(SwitchScreen, { recent: state.recent, current: state.current, orgName: orgName, canSwitchDevice: presetsFor(state.home.platform.type).length > 1, canSwitchOrg: true, onChoose: (action) => onSwitchChoice(state.home, action), onCancel: () => setState(state.home) })), state.kind === "pick-org" && (_jsx(PickOrg, { orgs: state.orgs, currentOrgId: orgId, onSelect: (org) => void switchOrg(org), onCancel: () => setState(state.home) })), state.kind === "paste-id" && (_jsxs(Box, { flexDirection: "column", children: [state.notice && _jsx(Text, { color: palette.coral, children: state.notice }), _jsxs(Box, { children: [_jsx(Text, { children: "App Platform ID: " }), _jsx(TextInput, { value: pasted, onChange: setPasted, onSubmit: (v) => { setPasted(""); void usePastedId(state.home, v); } })] }), _jsxs(Text, { dimColor: true, children: ["Checking ", pasteHost.name, ". nami platforms --app <app> lists them. Esc to go back."] })] })), state.kind === "fatal" && _jsx(Text, { color: palette.coral, children: state.message })] })] }));
 }

package/dist/screens/useTerminalImages.js

@@ -0,0 +1,129 @@
+/**
+ * Drawing the page's images as pixels, past Ink.
+ *
+ * `src/render/graphics.ts` builds the escapes; this is the part that has to
+ * deal with Ink, and there are three things to know about that.
+ *
+ * 1. **Ink deletes an image put in its tree.** Its `sanitizeAnsi` strips the
+ *    protocol's envelope out of any `<Text>`, so the pixels must be written
+ *    straight to the stream. That is what makes this a hook with a side effect
+ *    rather than a component.
+ * 2. **The position has to come from Ink's own layout**, since the escape is
+ *    placed by moving the cursor. Every Ink element carries the Yoga node it
+ *    was laid out with, so walking up from the frame's box and adding the
+ *    offsets gives its cell on screen — the same route `ink-picture` takes.
+ * 3. **Ink writes its frame asynchronously.** An escape emitted from an effect
+ *    can reach the terminal *before* the frame it was positioned against, and
+ *    Ink's next redraw erases what is under it. So the placement repeats on a
+ *    timer: it is a handful of bytes, it always lands after the newest frame,
+ *    and a redraw that clears an image restores it within one tick. Placement
+ *    is deliberately separate from transmission for exactly this reason —
+ *    re-sending the pixels this often would be visible.
+ */
+import { useEffect, useRef } from "react";
+import { useStdout } from "ink";
+import { decodeImage } from "../render/image.js";
+import { BACKGROUND_Z, UNDER_FILLS, at, clipToWindow, forget, place, rgbaFor, transmit } from "../render/graphics.js";
+/** Ids are ours to choose; this keeps them clear of whatever else is on screen. */
+const FIRST_ID = 7100;
+/** How often a placement is re-asserted. Fast enough not to be seen, cheap enough not to matter. */
+const REDRAW_MS = 120;
+/** Everything about a placement that changes the pixels the terminal must hold. */
+const identity = (a) => `${a.url}:${a.cols}x${a.rows}:${a.crop ? `${a.crop.x},${a.crop.y},${a.crop.w},${a.crop.h}` : ""}`;
+export function useTerminalImages({ enabled, frameRef, areas, bytes, windowRows, redrawMs = REDRAW_MS, }) {
+    const { stdout } = useStdout();
+    const sent = useRef(new Map());
+    const nextId = useRef(FIRST_ID);
+    // What to draw, rebuilt whenever the page, the window or the scroll changes.
+    const key = `${areas.map(identity).join("|")}#${windowRows}#${bytes.size}`;
+    useEffect(() => {
+        if (!enabled || areas.length === 0)
+            return;
+        const drawing = areas.flatMap((area) => {
+            const raw = bytes.get(area.url);
+            if (!raw)
+                return [];
+            // Keyed by everything that changes the pixels, not by url: the same asset
+            // can appear twice on a page at different sizes, and one entry keyed by
+            // url alone would hand the second box the first one's image.
+            const id = identity(area);
+            let image = sent.current.get(id);
+            if (!image) {
+                const pixels = decodeImage(raw);
+                if (!pixels)
+                    return [];
+                // The crop happens here rather than in the placement, so the pixels the
+                // terminal holds are exactly what should appear in those cells.
+                const scaled = rgbaFor(pixels, area.cols, area.rows, area.backdrop, area.crop);
+                image = { id: nextId.current++, width: scaled.width, height: scaled.height };
+                sent.current.set(id, image);
+                for (const chunk of transmit(image.id, scaled.data, scaled.width, scaled.height))
+                    stdout.write(chunk);
+            }
+            const clip = clipToWindow({ y: area.y, rows: area.rows }, 0, windowRows, image.height, image.width);
+            return clip ? [{ area, image, clip }] : [];
+        });
+        if (drawing.length === 0)
+            return;
+        const paint = () => {
+            const frame = absolutePosition(frameRef.current);
+            if (!frame)
+                return;
+            const terminalHeight = stdout.rows ?? frame.appHeight;
+            for (const { area, image, clip } of drawing) {
+                // One row and one column in from the frame's border.
+                const row = frame.row + 1 + clip.row;
+                const col = frame.col + 1 + area.x;
+                // Ink prints a newline after its output unless the app fills the screen,
+                // so the cursor is one row below the app in the usual case.
+                const up = frame.appHeight - row - (frame.appHeight >= terminalHeight ? 1 : 0);
+                stdout.write(at(col, up, place(image.id, {
+                    cols: area.cols,
+                    rows: clip.rows,
+                    source: clip.source,
+                    z: area.section === "background" ? BACKGROUND_Z : UNDER_FILLS,
+                })));
+            }
+        };
+        paint();
+        const timer = setInterval(paint, redrawMs);
+        // `unref` so a placement timer can never be the reason the process stays up.
+        timer.unref?.();
+        return () => clearInterval(timer);
+        // `key` stands for `areas`, which is rebuilt on every render.
+    }, [enabled, key, stdout, frameRef, redrawMs]);
+    // Everything this page put on screen goes when the screen does, or the
+    // pictures outlive the page that asked for them.
+    useEffect(() => {
+        const live = sent.current;
+        return () => {
+            for (const { id } of live.values())
+                stdout.write(forget(id));
+            live.clear();
+        };
+    }, [stdout]);
+}
+/**
+ * An element's cell position in the app's output, and the app's own height.
+ *
+ * Yoga reports each node relative to its parent, so the absolute position is
+ * the sum up the tree — the same accumulation `src/render/layout.ts` does for
+ * the page's own boxes, on Ink's tree instead of ours.
+ */
+function absolutePosition(node) {
+    if (!node?.yogaNode)
+        return null;
+    let col = 0;
+    let row = 0;
+    let appHeight = 0;
+    let at = node;
+    while (at) {
+        if (at.yogaNode) {
+            col += at.yogaNode.getComputedLeft();
+            row += at.yogaNode.getComputedTop();
+            appHeight = at.yogaNode.getComputedHeight();
+        }
+        at = at.parentNode ?? undefined;
+    }
+    return { col, row, appHeight };
+}

package/dist/utils/terminal.js

@@ -1,3 +1,11 @@
+/**
+ * The one NO_COLOR rule for the whole CLI: any non-empty value means the user
+ * asked for a quiet terminal. `shouldAnimate` and `detectCaps`
+ * (`src/render/capabilities.ts`) both defer to it so the two cannot drift.
+ */
+export function colorDisabled(env = process.env) {
+    return Boolean(env.NO_COLOR);
+}
 /**
  * Whether it is appropriate to animate: an interactive TTY, not CI, and the
  * user has not asked for a quiet terminal via NO_COLOR (any non-empty value).
@@ -8,10 +16,18 @@ export function shouldAnimate(env = process.env, stdout = process.stdout) {
         return false;
     if (env.CI)
         return false;
-    if (env.NO_COLOR)
+    if (colorDisabled(env))
         return false;
     return true;
 }
 export function terminalColumns(stdout = process.stdout, fallback = 80) {
     return stdout.columns && stdout.columns > 0 ? stdout.columns : fallback;
 }
+/**
+ * Rows the terminal has. The page render caps its frame to this and scrolls
+ * rather than squashing the page, so a terminal that never reports a height
+ * gets the conventional 24 rather than an unbounded frame.
+ */
+export function terminalRows(stdout = process.stdout, fallback = 24) {
+    return stdout.rows && stdout.rows > 0 ? stdout.rows : fallback;
+}

package/dist/version.js

@@ -1,2 +1,2 @@
 /** CLI package version. Stamped by scripts/version.sh from the repo VERSION file — do not hand-edit. */
-export const NAMI_CLI_VERSION = "3.4.12-dev.202609302217";
+export const NAMI_CLI_VERSION = "3.4.12-dev.202610051802";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namiml/cli",
-  "version": "3.4.12-dev.202609302217",
+  "version": "3.4.12-dev.202610051802",
   "description": "Nami SDK developer CLI — terminal test app, implementation and flow checks",
   "keywords": [
     "nami",
@@ -35,12 +35,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@namiml/sdk-core": "3.4.12-dev.202609302217",
+    "@namiml/sdk-core": "3.4.12-dev.202610051802",
     "commander": "^15",
     "env-paths": "^4",
     "ink": "^6.0.0",
     "ink-select-input": "^6",
     "ink-text-input": "^6",
+    "jpeg-js": "^0.4.4",
+    "pngjs": "^7.0.0",
     "react": "^19.0.0"
   }
 }