@markii/ansi 0.16.0 → 0.17.0-next.0

package/dist/failure-presentation.d.ts

@@ -37,6 +37,8 @@ export declare function emptyInlineTitle(name: string): string;
 export declare function invalidAttributeValueTitle(directive: string, attribute: string, value: string): string;
 /** The marker text for a component-built image whose `src` was refused as unsafe. Wording identical to `@markii/html`'s `unsafeImageSrcTitle`. */
 export declare function unsafeImageSrcTitle(directive: string): string;
+/** The diagnostic text for a registered block component written as an inline directive. Wording identical to `@markii/html`'s `formMismatchTitle`. */
+export declare function formMismatchTitle(directive: string): string;
 /**
  * The INLINE marker text for a known attribute's value outside its closed
  * enum, this engine's own departure from `@markii/html`'s identical wording:
@@ -56,3 +58,16 @@ export declare function invalidAttributeValueLabel(directive: string, attribute:
  * only.
  */
 export declare function unsafeImageSrcLabel(directive: string): string;
+/**
+ * The words of a fallback label for a directive that names a component of
+ * an installed pack with no view in this engine. Followed by the directive
+ * name in backticks, like the other fallback labels.
+ */
+export declare const NO_ENGINE_VIEW_LABEL = "no terminal view for";
+/**
+ * The diagnostic text for the same case: the pack, and the engines the
+ * component does ship a view for. A terminal has no tooltip, so this
+ * sentence reaches the host's diagnostics surface through `onDiagnostic`
+ * and is never printed in the note.
+ */
+export declare function noEngineViewTitle(directive: string, pack: string, engines: readonly string[]): string;

package/dist/failure-presentation.js

@@ -99,6 +99,10 @@ export function invalidAttributeValueTitle(directive, attribute, value) {
 export function unsafeImageSrcTitle(directive) {
     return `${directive}: image source was refused as unsafe and was not shown`;
 }
+/** The diagnostic text for a registered block component written as an inline directive. Wording identical to `@markii/html`'s `formMismatchTitle`. */
+export function formMismatchTitle(directive) {
+    return `${directive}: block component was written inline and was not rendered`;
+}
 /**
  * The INLINE marker text for a known attribute's value outside its closed
  * enum, this engine's own departure from `@markii/html`'s identical wording:
@@ -122,3 +126,21 @@ export function invalidAttributeValueLabel(directive, attribute) {
 export function unsafeImageSrcLabel(directive) {
     return `${directive}: image not shown`;
 }
+/**
+ * The words of a fallback label for a directive that names a component of
+ * an installed pack with no view in this engine. Followed by the directive
+ * name in backticks, like the other fallback labels.
+ */
+export const NO_ENGINE_VIEW_LABEL = 'no terminal view for';
+/**
+ * The diagnostic text for the same case: the pack, and the engines the
+ * component does ship a view for. A terminal has no tooltip, so this
+ * sentence reaches the host's diagnostics surface through `onDiagnostic`
+ * and is never printed in the note.
+ */
+export function noEngineViewTitle(directive, pack, engines) {
+    const has = engines.length > 0
+        ? `it has views for: ${engines.join(', ')}`
+        : 'it has no views for any engine';
+    return `The ${pack} pack has no terminal view for this component; ${has}`;
+}

package/dist/glyphs.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Every glyph this engine draws on its own, as one table per box style.
+ * `unicode` is the default; `ascii` is a 7-bit form for a terminal that
+ * cannot show box drawing or symbols. Every component, frame, rule, and
+ * status-line string reads its glyphs from the set the render was given,
+ * so the two styles cannot drift apart: `glyphs.test.ts` renders the whole
+ * render corpus in `ascii` and fails on any byte above 0x7f that did not
+ * come from the note itself.
+ *
+ * Each entry occupies the same number of terminal columns in both sets
+ * where layout depends on it (frames, rules, bars, focus and fold markers),
+ * so switching style never changes how a note wraps. The engine never
+ * picks a style from the environment; the host decides.
+ */
+export declare const BOX_STYLES: readonly ["unicode", "ascii"];
+export type BoxStyle = (typeof BOX_STYLES)[number];
+export declare function isBoxStyle(value: string): value is BoxStyle;
+/** One frame edge set: the solid frame of a card, or the dashed one of a fallback box. */
+export interface FrameEdges {
+    readonly horizontal: string;
+    readonly vertical: string;
+}
+export interface GlyphSet {
+    /** Corners shared by every frame and by a table's outer edge. */
+    readonly topLeft: string;
+    readonly topRight: string;
+    readonly bottomLeft: string;
+    readonly bottomRight: string;
+    readonly solid: FrameEdges;
+    readonly dashed: FrameEdges;
+    /** A table's inner junctions. */
+    readonly teeDown: string;
+    readonly teeUp: string;
+    readonly teeRight: string;
+    readonly teeLeft: string;
+    readonly cross: string;
+    /** A thematic break and a `divider` drawn as a line. */
+    readonly rule: string;
+    /** A `divider` drawn as dots. */
+    readonly ruleDots: string;
+    /** A `divider{style=ornament}` centerpiece. */
+    readonly ornament: string;
+    /** The bar a blockquote's lines start with, including its trailing space. */
+    readonly quoteBar: string;
+    /** The bar a callout's lines start with, including its trailing space. */
+    readonly calloutBar: string;
+    readonly calloutIcons: {
+        readonly info: string;
+        readonly warning: string;
+        readonly danger: string;
+    };
+    /** The marker before a focused block's heading, including its trailing space. */
+    readonly focus: string;
+    /** A details block's fold marker. */
+    readonly foldOpen: string;
+    readonly foldClosed: string;
+    /** The collapsed script marker: its leading symbol and the separator before its detail. */
+    readonly script: string;
+    readonly scriptSeparator: string;
+    /** Eight steps, lowest first, that a line chart's sparkline is built from. */
+    readonly sparkline: string;
+    /** A filled bar cell (chart bars, a progress bar's done part) and an empty one. */
+    readonly barFilled: string;
+    readonly barEmpty: string;
+    readonly starFilled: string;
+    readonly starEmpty: string;
+    /** What a `stat` shows when its value is empty. */
+    readonly emptyValue: string;
+    /** The key legend on the live viewer's status line. */
+    readonly keyLegend: string;
+}
+/** The glyph set for `style`; anything other than `'ascii'` gets the unicode set. */
+export declare function glyphsFor(style: BoxStyle | undefined): GlyphSet;

package/dist/glyphs.js

@@ -0,0 +1,88 @@
+/**
+ * Every glyph this engine draws on its own, as one table per box style.
+ * `unicode` is the default; `ascii` is a 7-bit form for a terminal that
+ * cannot show box drawing or symbols. Every component, frame, rule, and
+ * status-line string reads its glyphs from the set the render was given,
+ * so the two styles cannot drift apart: `glyphs.test.ts` renders the whole
+ * render corpus in `ascii` and fails on any byte above 0x7f that did not
+ * come from the note itself.
+ *
+ * Each entry occupies the same number of terminal columns in both sets
+ * where layout depends on it (frames, rules, bars, focus and fold markers),
+ * so switching style never changes how a note wraps. The engine never
+ * picks a style from the environment; the host decides.
+ */
+export const BOX_STYLES = ['unicode', 'ascii'];
+export function isBoxStyle(value) {
+    return BOX_STYLES.includes(value);
+}
+const UNICODE = {
+    topLeft: '┌',
+    topRight: '┐',
+    bottomLeft: '└',
+    bottomRight: '┘',
+    solid: { horizontal: '─', vertical: '│' },
+    dashed: { horizontal: '╌', vertical: '┆' },
+    teeDown: '┬',
+    teeUp: '┴',
+    teeRight: '├',
+    teeLeft: '┤',
+    cross: '┼',
+    rule: '─',
+    ruleDots: '·',
+    ornament: '❖',
+    quoteBar: '│ ',
+    calloutBar: '▌ ',
+    calloutIcons: { info: 'ℹ', warning: '▲', danger: '✕' },
+    focus: '› ',
+    foldOpen: '▾',
+    foldClosed: '▸',
+    script: '⚙',
+    scriptSeparator: '·',
+    sparkline: '▁▂▃▄▅▆▇█',
+    barFilled: '█',
+    barEmpty: '░',
+    starFilled: '★',
+    starEmpty: '☆',
+    emptyValue: '—',
+    keyLegend: 'q quit  ↑↓/jk focus  ←→/tab switch  enter open/close  space/pgdn scroll  g/G top/end',
+};
+const ASCII = {
+    topLeft: '+',
+    topRight: '+',
+    bottomLeft: '+',
+    bottomRight: '+',
+    solid: { horizontal: '-', vertical: '|' },
+    dashed: { horizontal: '.', vertical: ':' },
+    teeDown: '+',
+    teeUp: '+',
+    teeRight: '+',
+    teeLeft: '+',
+    cross: '+',
+    rule: '-',
+    ruleDots: '.',
+    ornament: '*',
+    quoteBar: '| ',
+    calloutBar: '| ',
+    calloutIcons: { info: 'i', warning: '!', danger: 'x' },
+    focus: '> ',
+    foldOpen: '-',
+    foldClosed: '+',
+    script: '#',
+    scriptSeparator: '-',
+    sparkline: '_.-:=+*#',
+    barFilled: '#',
+    barEmpty: '.',
+    starFilled: '*',
+    starEmpty: '.',
+    emptyValue: '-',
+    keyLegend: 'q quit  up/down/jk focus  left/right/tab switch  enter open/close  space/pgdn scroll  g/G top/end',
+};
+const GLYPHS = {
+    unicode: UNICODE,
+    ascii: ASCII,
+};
+/** The glyph set for `style`; anything other than `'ascii'` gets the unicode set. */
+export function glyphsFor(style) {
+    return style === 'ascii' ? GLYPHS.ascii : GLYPHS.unicode;
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { renderMarkToAnsi, renderMarkNodeToAnsi, renderMarkInlineToAnsi, buildMarkElement, type RenderMarkOptions, } from './render.js';
 export { fg, colorize, bold, dim, italic, underline, inverse, hyperlink, detectColorLevel, resolveColorOption, type ColorLevel, type ColorOption, type AnsiColor, } from './ansi.js';
 export { defaultAnsiTheme, type AnsiTheme, type Tier1Token } from './theme.js';
+export { BOX_STYLES, isBoxStyle, glyphsFor, type BoxStyle, type FrameEdges, type GlyphSet, } from './glyphs.js';
 export { style } from './style.js';
 export { createAnsiRegistry, mergeAnsiRegistries, registryAliases, readRegistryComponent, resolveDirectiveAlias, childrenText, REGISTRY_ALIASES, type DirectiveAttributes, type AnsiRegistry, type AnsiRegistryEntry, type AnsiComponent, type AnsiComponentProps, type AnsiRenderContext, type RegistryAlias, type RegistryAliases, type ResolvedDirective, type ValueResolution, } from './registry.js';
 export { resolveStorePath, resolveScopedPath, VAULT_NAME_PREFIX, type StorePathResolution, type ValueScope, } from './resolve.js';
@@ -11,3 +12,6 @@ export { resolveLayoutAttributes, applyLayout, LAYOUT_ATTRIBUTE_KEYS, type Resol
 export { type ResolveImageSrc } from './image-resolve.js';
 export { type ResolveHref } from './href-resolve.js';
 export type { AnsiValueStore, AnsiVaultStore, FailureKind, StoredValue, ValueStatus, } from './value-types.js';
+export { defaultAnsiRegistry } from './components/index.js';
+export { ANSI_ENGINE_ID, loadAnsiPack, installAnsiPacks, sanitizeValueForPack, type AnsiPackComponentModules, type AnsiPackToInstall, type LoadAnsiPackResult, type InstallAnsiPacksResult, } from './pack-loader.js';
+export { loadTerminalPackScript, installTerminalPackGlobals, TERMINAL_REGISTER_GLOBAL, TERMINAL_REACT_GLOBAL, TERMINAL_INK_GLOBAL, type LoadTerminalPackScriptResult, } from './pack-script.js';

package/dist/index.js

@@ -7,6 +7,7 @@
 export { renderMarkToAnsi, renderMarkNodeToAnsi, renderMarkInlineToAnsi, buildMarkElement, } from './render.js';
 export { fg, colorize, bold, dim, italic, underline, inverse, hyperlink, detectColorLevel, resolveColorOption, } from './ansi.js';
 export { defaultAnsiTheme } from './theme.js';
+export { BOX_STYLES, isBoxStyle, glyphsFor, } from './glyphs.js';
 export { style } from './style.js';
 export { createAnsiRegistry, mergeAnsiRegistries, registryAliases, readRegistryComponent, resolveDirectiveAlias, childrenText, REGISTRY_ALIASES, } from './registry.js';
 export { resolveStorePath, resolveScopedPath, VAULT_NAME_PREFIX, } from './resolve.js';
@@ -14,3 +15,6 @@ export { failurePhrase, failureTitle, failureToken, dataStateSuffix, emptyInline
 export { stringifyStoredValue } from './value-format.js';
 export { stripControlCharacters, sanitizeBlockText, sanitizeUrlText, BLOCK_TAB_WIDTH, } from './sanitize.js';
 export { resolveLayoutAttributes, applyLayout, LAYOUT_ATTRIBUTE_KEYS, } from './layout.js';
+export { defaultAnsiRegistry } from './components/index.js';
+export { ANSI_ENGINE_ID, loadAnsiPack, installAnsiPacks, sanitizeValueForPack, } from './pack-loader.js';
+export { loadTerminalPackScript, installTerminalPackGlobals, TERMINAL_REGISTER_GLOBAL, TERMINAL_REACT_GLOBAL, TERMINAL_INK_GLOBAL, } from './pack-script.js';

package/dist/ink-string.d.ts

@@ -10,3 +10,14 @@ import type { ReactElement } from 'react';
  * the ordinary ESM module-cache guarantee.
  */
 export declare function renderInkToString(element: ReactElement, columns: number): Promise<string>;
+/**
+ * The same capture as `renderInkToString`, synchronously. Valid only once
+ * Ink's module has finished evaluating, which is always true inside a walk
+ * (`render.tsx` imports Ink statically). Used for a registry component that
+ * returns an Ink element instead of a string (a terminal pack's view): the
+ * element is laid out at the width the directive was given and captured as
+ * text, so it composes with the string-built blocks around it. The result
+ * is a snapshot, so a component rendered this way has no live state.
+ * Trailing newlines Ink adds are removed.
+ */
+export declare function renderInkToStringSync(element: ReactElement, columns: number): string;

package/dist/ink-string.js

@@ -1,4 +1,5 @@
 import { Writable } from 'node:stream';
+import { render as inkRender } from 'ink';
 function makeCollectingStream(columns) {
     const chunks = [];
     const stream = new Writable({
@@ -39,3 +40,26 @@ export async function renderInkToString(element, columns) {
     instance.unmount();
     return getOutput();
 }
+/**
+ * The same capture as `renderInkToString`, synchronously. Valid only once
+ * Ink's module has finished evaluating, which is always true inside a walk
+ * (`render.tsx` imports Ink statically). Used for a registry component that
+ * returns an Ink element instead of a string (a terminal pack's view): the
+ * element is laid out at the width the directive was given and captured as
+ * text, so it composes with the string-built blocks around it. The result
+ * is a snapshot, so a component rendered this way has no live state.
+ * Trailing newlines Ink adds are removed.
+ */
+export function renderInkToStringSync(element, columns) {
+    const { stream, getOutput } = makeCollectingStream(columns);
+    const instance = inkRender(element, {
+        stdout: stream,
+        stdin: process.stdin,
+        exitOnCtrlC: false,
+        patchConsole: false,
+        debug: false,
+        interactive: false,
+    });
+    instance.unmount();
+    return getOutput().replace(/\n+$/, '');
+}

package/dist/interactive.d.ts

@@ -1,18 +1,32 @@
 import type { ReactNode } from 'react';
+import type { DOMElement } from 'ink';
 import type { AnsiTheme } from './theme.js';
 import type { ColorLevel } from './ansi.js';
 /** Whether the component identified by `focusId` is the currently focused one. `undefined` (a non-interactive render, or a component that never got a `focusId`) is never focused. */
 export declare function useIsFocused(focusId: number | undefined): boolean;
 /** Wraps `text` in the accent-colored focus marker when interactive AND `focusId` is the focused one; otherwise returns `text` unchanged. */
 export declare function useFocusMarker(text: string, focusId: number | undefined): string;
+/**
+ * Lets a `tabs` instance report its currently active panel's label to
+ * `InteractiveRoot`, so the status line names the panel showing rather than
+ * the block's first one. Call it from an effect, never during render (see
+ * `FocusApi.reportActiveLabel`).
+ */
+export declare function useReportActiveLabel(): (focusId: number, label: string) => void;
+/**
+ * The ref callback a focusable component puts on its outermost `Box`, so
+ * the live viewer can scroll the focused block into view. A no-op without a
+ * `focusId` or outside an interactive render.
+ */
+export declare function useFocusAnchor(focusId: number | undefined): (node: DOMElement | null) => void;
 /**
  * One focusable component, in the same document order `render.tsx`'s
  * counting walk assigns `focusId`s in — `focusables[focusId]` is always
- * that component's descriptor. `label` is a stable identity: for `tabs`,
- * the FIRST panel's label, never the currently active one. A `tabs` block's
- * active panel is its own component state, so naming it on the status line
- * would need a report channel back up to this root on every switch; the
- * first label identifies the block just as well and cannot loop.
+ * that component's descriptor. `label` is the descriptor's STABLE identity
+ * (for `tabs`, the FIRST panel's label): it is used on the status line only
+ * until a `tabs` instance reports its actual active panel via
+ * `reportActiveLabel`, and as the fallback before any report has happened
+ * yet (mount, or a reader who has not switched panels).
  */
 export interface FocusableDescriptor {
     kind: 'tabs' | 'details';
@@ -25,6 +39,17 @@ export interface InteractiveRootProps {
     onExit?: () => void;
     color: ColorLevel;
     theme: AnsiTheme;
+    /** The key legend on the status line, identical regardless of what is focused: the render's `GlyphSet.keyLegend`, so it follows the box style. */
+    keyLegend: string;
+    /**
+     * The terminal's row count. When given, the document gets a viewport of
+     * this many rows minus the one-row status line, scrolled with the keys in
+     * the legend, and the status line stays pinned at the bottom. Absent, the
+     * document is laid out at its full height with the status line after it.
+     */
+    viewportRows?: number;
+    /** The columns the status line is cut to, so it stays one row. */
+    width: number;
     children: ReactNode;
 }
 /**
@@ -38,4 +63,4 @@ export interface InteractiveRootProps {
  * default (uninteractive) value there, so a string render never sees a
  * focus marker, a glyph, or a status line.
  */
-export declare function InteractiveRoot({ focusables, onExit, color, theme, children, }: InteractiveRootProps): ReactNode;
+export declare function InteractiveRoot({ focusables, onExit, color, theme, keyLegend, viewportRows, width, children, }: InteractiveRootProps): ReactNode;

package/dist/interactive.js

@@ -1,12 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useContext, useMemo, useState } from 'react';
-import { Box, Text, useInput } from 'ink';
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { Box, Text, measureElement, useInput } from 'ink';
 import { dim } from './ansi.js';
 import { style } from './style.js';
+import { cutToWidth } from './text-grid.js';
 const FocusContext = createContext({
     interactive: false,
     focusedId: undefined,
     focusMarker: (text) => text,
+    reportActiveLabel: () => { },
+    registerAnchor: () => { },
 });
 /** Whether the component identified by `focusId` is the currently focused one. `undefined` (a non-interactive render, or a component that never got a `focusId`) is never focused. */
 export function useIsFocused(focusId) {
@@ -19,8 +22,29 @@ export function useFocusMarker(text, focusId) {
     const focused = focusId !== undefined && api.interactive && api.focusedId === focusId;
     return focused ? api.focusMarker(text) : text;
 }
-/** The key legend shown on the status line, identical regardless of what is focused. */
-const KEY_LEGEND = '↑↓/jk focus  ←→/tab switch  enter open/close  q quit';
+/**
+ * Lets a `tabs` instance report its currently active panel's label to
+ * `InteractiveRoot`, so the status line names the panel showing rather than
+ * the block's first one. Call it from an effect, never during render (see
+ * `FocusApi.reportActiveLabel`).
+ */
+export function useReportActiveLabel() {
+    const api = useContext(FocusContext);
+    return api.reportActiveLabel;
+}
+/**
+ * The ref callback a focusable component puts on its outermost `Box`, so
+ * the live viewer can scroll the focused block into view. A no-op without a
+ * `focusId` or outside an interactive render.
+ */
+export function useFocusAnchor(focusId) {
+    const { registerAnchor } = useContext(FocusContext);
+    return useCallback((node) => {
+        if (focusId === undefined)
+            return;
+        registerAnchor(focusId, node ?? undefined);
+    }, [focusId, registerAnchor]);
+}
 /**
  * The root of an interactive render: owns which `focusId` is focused, moves
  * it on up/down/j/k, calls `onExit` on `q`, and renders the one-line status
@@ -32,33 +56,152 @@ const KEY_LEGEND = '↑↓/jk focus  ←→/tab switch  enter open/close  q quit
  * default (uninteractive) value there, so a string render never sees a
  * focus marker, a glyph, or a status line.
  */
-export function InteractiveRoot({ focusables, onExit, color, theme, children, }) {
+export function InteractiveRoot({ focusables, onExit, color, theme, keyLegend, viewportRows, width, children, }) {
     const focusableCount = focusables.length;
     const [focusIndex, setFocusIndex] = useState(0);
+    // `focusId -> the label its last active-panel report carried`. Only a
+    // `tabs` descriptor is ever reported against; `details` never calls
+    // `reportActiveLabel`, so its entry here simply never appears. Absent
+    // keys are expected (mount, or a `tabs` the reader has not switched yet)
+    // and fall back to the descriptor's own stable `label` below.
+    const [activeLabels, setActiveLabels] = useState({});
+    const viewport = viewportRows !== undefined ? Math.max(1, viewportRows - 1) : undefined;
+    const [offset, setOffset] = useState(0);
+    const contentRef = useRef(null);
+    const anchors = useRef(new Map());
+    // What the last reveal pass saw, so a reveal runs when focus MOVES or the
+    // focused block changes height (a details opening), and not on every
+    // render: a reader who scrolled away on purpose is left where they are.
+    const lastRevealed = useRef({
+        id: undefined,
+        height: -1,
+    });
+    const contentHeight = () => contentRef.current ? measureElement(contentRef.current).height : 0;
+    const maxOffset = () => viewport === undefined ? 0 : Math.max(0, contentHeight() - viewport);
+    const scrollBy = (delta) => {
+        if (viewport === undefined)
+            return;
+        const limit = maxOffset();
+        setOffset((current) => Math.min(limit, Math.max(0, current + delta)));
+    };
+    const scrollTo = (target) => {
+        if (viewport === undefined)
+            return;
+        setOffset(target === 'top' ? 0 : maxOffset());
+    };
     useInput((input, key) => {
         if (input === 'q') {
             onExit?.();
             return;
         }
-        if (focusableCount === 0)
+        if (viewport !== undefined) {
+            const page = Math.max(1, viewport - 1);
+            if (key.pageDown || input === ' ' || (key.ctrl && input === 'f')) {
+                scrollBy(page);
+                return;
+            }
+            if (key.pageUp || input === 'b' || (key.ctrl && input === 'b')) {
+                scrollBy(-page);
+                return;
+            }
+            if (key.home || input === 'g') {
+                scrollTo('top');
+                return;
+            }
+            if (key.end || input === 'G') {
+                scrollTo('end');
+                return;
+            }
+            if (key.ctrl && input === 'e') {
+                scrollBy(1);
+                return;
+            }
+            if (key.ctrl && input === 'y') {
+                scrollBy(-1);
+                return;
+            }
+        }
+        const down = key.downArrow || input === 'j';
+        const up = key.upArrow || input === 'k';
+        if (focusableCount === 0) {
+            // Nothing to focus: the same keys scroll a line at a time.
+            if (down)
+                scrollBy(1);
+            else if (up)
+                scrollBy(-1);
             return;
-        if (key.downArrow || input === 'j') {
+        }
+        if (down) {
             setFocusIndex((current) => (current + 1) % focusableCount);
         }
-        else if (key.upArrow || input === 'k') {
+        else if (up) {
             setFocusIndex((current) => (current - 1 + focusableCount) % focusableCount);
         }
     }, { isActive: true });
     const focusedId = focusableCount > 0 ? focusIndex % focusableCount : undefined;
+    // Invoked from `tabs.tsx`'s KEY HANDLER, never during render — see
+    // `FocusApi.reportActiveLabel`'s doc comment. The equality guard avoids an
+    // unnecessary re-render when a switch reports the label it already had
+    // (e.g. wrapping from the last panel back past the first is still a real
+    // change, but re-reporting the same active panel is not).
+    const reportActiveLabel = useCallback((focusId, label) => {
+        setActiveLabels((current) => current[focusId] === label ? current : { ...current, [focusId]: label });
+    }, []);
+    const registerAnchor = useCallback((focusId, node) => {
+        if (node)
+            anchors.current.set(focusId, node);
+        else
+            anchors.current.delete(focusId);
+    }, []);
     const api = useMemo(() => ({
         interactive: true,
         focusedId,
         focusMarker: (text) => style(text, '--mk-accent', theme, color),
-    }), [focusedId, color, theme]);
+        reportActiveLabel,
+        registerAnchor,
+    }), [focusedId, color, theme, reportActiveLabel, registerAnchor]);
+    // After every commit Ink has laid the tree out, so this is where the
+    // viewport is kept honest: the offset never exceeds the document (a
+    // resize or a closing details can shrink it), and a focus move, or a
+    // focused block growing, scrolls that block into view.
+    useEffect(() => {
+        if (viewport === undefined || !contentRef.current)
+            return;
+        const content = measureElement(contentRef.current);
+        const limit = Math.max(0, content.height - viewport);
+        let next = Math.min(offset, limit);
+        const anchor = focusedId !== undefined ? anchors.current.get(focusedId) : undefined;
+        if (anchor) {
+            const box = measureElement(anchor);
+            const seen = lastRevealed.current;
+            if (seen.id !== focusedId || seen.height !== box.height) {
+                lastRevealed.current = { id: focusedId, height: box.height };
+                const top = box.y - content.y;
+                const bottom = top + box.height;
+                if (top < next)
+                    next = top;
+                else if (bottom > next + viewport)
+                    next = Math.min(top, bottom - viewport);
+                next = Math.min(limit, Math.max(0, next));
+            }
+        }
+        if (next !== offset)
+            setOffset(next);
+    });
     const focused = focusedId !== undefined ? focusables[focusedId] : undefined;
+    const focusedLabel = focused && focusedId !== undefined
+        ? (activeLabels[focusedId] ?? focused.label)
+        : undefined;
     const statusLabel = focused
-        ? `${focused.kind} "${focused.label}"`
+        ? `${focused.kind} "${focusedLabel}"`
         : 'nothing focusable';
-    const statusLine = dim(`${statusLabel}  ${KEY_LEGEND}`, color);
-    return (_jsx(FocusContext.Provider, { value: api, children: _jsxs(Box, { flexDirection: "column", children: [children, _jsx(Text, { children: statusLine })] }) }));
+    // Cut to the width on plain text: the status line must stay one row (the
+    // viewport math counts it as one), and a label or legend that wrapped
+    // would push the document up.
+    const statusLine = dim(cutToWidth(`${statusLabel}  ${keyLegend}`, width), color);
+    const status = _jsx(Text, { children: statusLine });
+    if (viewport === undefined) {
+        return (_jsx(FocusContext.Provider, { value: api, children: _jsxs(Box, { flexDirection: "column", children: [children, status] }) }));
+    }
+    return (_jsx(FocusContext.Provider, { value: api, children: _jsxs(Box, { flexDirection: "column", height: viewport + 1, children: [_jsx(Box, { flexDirection: "column", height: viewport, flexShrink: 0, overflow: "hidden", children: _jsx(Box, { ref: contentRef, flexDirection: "column", flexShrink: 0, marginTop: -offset, children: children }) }), status] }) }));
 }

package/dist/pack-loader.d.ts

@@ -0,0 +1,64 @@
+import type { PackManifest } from '@markii/pack';
+import type { AnsiRegistry, AnsiRegistryEntry } from './registry.js';
+/**
+ * This engine's id in a pack manifest's per-component `sources` map
+ * (docs/packs.md). A component with an `ansi` source has a terminal view.
+ */
+export declare const ANSI_ENGINE_ID = "ansi";
+/**
+ * The component modules a host hands to `loadAnsiPack`, keyed by the
+ * manifest's LOCAL component name. Each is the `{ component, inline? }`
+ * pair a pack's `terminal.js` registered (`./pack-script.ts`).
+ */
+export type AnsiPackComponentModules = Record<string, AnsiRegistryEntry>;
+/**
+ * Returns `value` with every string in it run through
+ * `stripControlCharacters`, so a pack that prints a stored value cannot
+ * print a control character a script smuggled in. Arrays and plain objects
+ * are copied (null-prototype for objects, hasOwn-guarded), never mutated.
+ * Anything past `MAX_SANITIZE_DEPTH`, and every non-JSON value, becomes
+ * `undefined`. Never throws: a throwing getter reads as `undefined`.
+ */
+export declare function sanitizeValueForPack(value: unknown, depth?: number): unknown;
+/** What `loadAnsiPack` reports about a pack it could not run. */
+export interface LoadAnsiPackResult {
+    registry: AnsiRegistry;
+    /** Present when the pack has components but none has an `ansi` source: the pack contributes nothing. `engine` names the engines it does declare. */
+    dropped?: {
+        name: string;
+        engine: string;
+    };
+}
+/**
+ * Loads one pack's terminal components into a namespaced `AnsiRegistry`,
+ * mirroring `@markii/react`'s `loadPack`: gating is per component (only
+ * components with an `ansi` source register; the rest fall back to the
+ * unknown-component box), a manifest component with no module is skipped,
+ * a stray module is ignored, and a declared `kind` decides the `inline`
+ * flag. Reads are `Object.hasOwn`-guarded. Never throws.
+ */
+export declare function loadAnsiPack(manifest: PackManifest, componentModules: AnsiPackComponentModules): LoadAnsiPackResult;
+/** One pack ready to install: its manifest plus its registered component modules. */
+export interface AnsiPackToInstall {
+    manifest: PackManifest;
+    componentModules: AnsiPackComponentModules;
+}
+export type InstallAnsiPacksResult = {
+    ok: true;
+    registry: AnsiRegistry;
+    dropped: {
+        name: string;
+        engine: string;
+    }[];
+} | {
+    ok: false;
+    collisions: readonly string[];
+};
+/**
+ * Installs several packs into one registry on top of `base`, rejecting the
+ * whole install when two share a namespace (the install-time rule in
+ * docs/packs.md), exactly like `@markii/react`'s `installPacks`. A host
+ * that wants keep-first behavior (a bundled pack wins over a user pack of
+ * the same namespace) filters the list before calling.
+ */
+export declare function installAnsiPacks(packs: readonly AnsiPackToInstall[], base?: AnsiRegistry): InstallAnsiPacksResult;