@markii/ansi 0.15.0 → 0.17.0-next.0

package/dist/components/tabs-string.js

@@ -0,0 +1,30 @@
+import { childrenText } from '../registry.js';
+/** The visible marker appended to whichever tab is treated as "active". */
+const ACTIVE_MARKER = ' (active)';
+/**
+ * The STRING-mode `tabs` registration — the fallback rendering used only
+ * when a `tabs` directive is reached through `render.tsx`'s STRING mode
+ * (nested inside a self-drawing container) AND, unlike `row`, not
+ * reachable through the panel-extraction path there either (both of
+ * `render.tsx`'s STRING and ELEMENT dispatchers for `tabs` build panels
+ * directly from the hast tree via `extractTabPanels`/`extractTabPanelsElement`
+ * rather than calling this component, since only the hast tree — not an
+ * already-flattened string — can tell each `tab` child's own `label` apart
+ * from its neighbor without a fragile heuristic). This registration exists
+ * so the registry always has a real `tabs` component (alias resolution,
+ * the contract-drift coverage test, and a caller invoking it directly all
+ * see one), using the same blank-line-boundary heuristic the pre-Ink engine
+ * used when it has nothing but a flattened string to work with.
+ */
+export const Tabs = ({ children }) => {
+    const text = childrenText(children);
+    if (!text.trim())
+        return '';
+    const blocks = text.split('\n\n');
+    const [first, ...rest] = blocks;
+    if (first === undefined)
+        return text;
+    const lines = first.split('\n');
+    lines[0] = `${lines[0] ?? ''}${ACTIVE_MARKER}`;
+    return [lines.join('\n'), ...rest].join('\n\n');
+};

package/dist/components/tabs.d.ts

@@ -1,18 +1,35 @@
-import type { AnsiComponent } from '../registry.js';
+import type { GlyphSet } from '../glyphs.js';
+import type { ReactNode } from 'react';
+import type { ColorLevel } from '../ansi.js';
+import type { ElementTabPanel } from '../render.js';
 /**
  * `::::tabs :::tab{label="..."} ... ::: :::tab{label="..."} ... ::: ::::` —
- * a tabbed panel switcher. A terminal has no click-driven tab switching (see
- * `render.ts`'s top comment on interactive components), so every panel is
- * shown, stacked, in document order — matching `@markii/html`'s `Tabs`
- * faithfulness limitation of showing every panel rather than picking one.
+ * a tabbed panel switcher, built as a real Ink element (`render.tsx`'s
+ * `renderTabsElement` calls this directly rather than going through the
+ * ordinary registry-component invocation, so it can hand it real per-panel
+ * subtrees — see `registry.ts`'s and `render.tsx`'s doc comments).
  *
- * "The active tab marked": since every panel is always visible here, this
- * engine treats the FIRST tab (document order) as the one a live host would
- * show before any interaction, and marks only its heading line — every
- * `tab` child's block is joined into `childrenText` with a blank line
- * between them (`render.ts`'s `renderBlocks`), the same separator this
- * engine uses between any two sibling blocks, so splitting on the first
- * blank line reliably finds the boundary between the first tab's block and
- * the rest without needing any information `tabs` does not have.
+ * Non-interactive (the default, and the render-once path): every panel is
+ * shown, stacked, in document order, the first one's heading marked
+ * `(active)` — matching the pre-Ink engine's faithfulness limitation of
+ * showing every panel rather than picking one, since a static render has no
+ * way to ask which panel a reader wants.
+ *
+ * Interactive: only the active panel's body is shown; the header row lists
+ * every label, the active one bracketed; left/right or Tab switches it when
+ * this `tabs` instance is focused (`useIsFocused`). When this `tabs`
+ * instance itself is the FOCUSED component (as opposed to merely being
+ * interactive), the whole header strip is drawn in the accent color and
+ * prefixed with a `› ` glyph (`useFocusMarker`), so focus is visible even
+ * on a theme with no perceptible accent color; an unfocused header strip
+ * gets two leading spaces instead, so nothing shifts horizontally when
+ * focus moves onto or off of this block.
  */
-export declare const Tabs: AnsiComponent;
+export interface InteractiveTabsProps {
+    panels: readonly ElementTabPanel[];
+    color: ColorLevel;
+    glyphs: GlyphSet;
+    interactive: boolean;
+    focusId: number | undefined;
+}
+export declare function InteractiveTabs({ panels, color, glyphs, interactive, focusId, }: InteractiveTabsProps): ReactNode;

package/dist/components/tabs.js

@@ -1,30 +1,55 @@
-/** The visible marker appended to whichever tab is treated as "active" (see this module's doc comment for how that is decided). */
-const ACTIVE_MARKER = ' (active)';
-/**
- * `::::tabs :::tab{label="..."} ... ::: :::tab{label="..."} ... ::: ::::` —
- * a tabbed panel switcher. A terminal has no click-driven tab switching (see
- * `render.ts`'s top comment on interactive components), so every panel is
- * shown, stacked, in document order — matching `@markii/html`'s `Tabs`
- * faithfulness limitation of showing every panel rather than picking one.
- *
- * "The active tab marked": since every panel is always visible here, this
- * engine treats the FIRST tab (document order) as the one a live host would
- * show before any interaction, and marks only its heading line — every
- * `tab` child's block is joined into `childrenText` with a blank line
- * between them (`render.ts`'s `renderBlocks`), the same separator this
- * engine uses between any two sibling blocks, so splitting on the first
- * blank line reliably finds the boundary between the first tab's block and
- * the rest without needing any information `tabs` does not have.
- */
-export const Tabs = (_attributes, children) => {
-    const childrenText = children();
-    if (!childrenText.trim())
-        return '';
-    const blocks = childrenText.split('\n\n');
-    const [first, ...rest] = blocks;
-    if (first === undefined)
-        return childrenText;
-    const lines = first.split('\n');
-    lines[0] = `${lines[0] ?? ''}${ACTIVE_MARKER}`;
-    return [lines.join('\n'), ...rest].join('\n\n');
-};
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { bold, dim } from '../ansi.js';
+import { useFocusAnchor, useFocusMarker, useIsFocused, useReportActiveLabel, } from '../interactive.js';
+export function InteractiveTabs({ panels, color, glyphs, interactive, focusId, }) {
+    const [active, setActive] = useState(0);
+    const focused = useIsFocused(focusId);
+    const reportActiveLabel = useReportActiveLabel();
+    const anchor = useFocusAnchor(focusId);
+    useInput((_input, key) => {
+        if (panels.length === 0)
+            return;
+        let nextIndex;
+        if (key.leftArrow) {
+            nextIndex = (active - 1 + panels.length) % panels.length;
+        }
+        else if (key.rightArrow || key.tab) {
+            nextIndex = (active + 1) % panels.length;
+        }
+        if (nextIndex === undefined)
+            return;
+        setActive(nextIndex);
+    }, { isActive: interactive && focused });
+    // Every hook this component calls runs BEFORE the non-interactive early
+    // return below, so the hook order is identical in both modes. The header
+    // strip is cheap to build and unused in the non-interactive branch; that
+    // waste is the price of never making a hook call conditional.
+    const activeIndex = Math.min(active, Math.max(0, panels.length - 1));
+    const activePanel = panels[activeIndex];
+    const activeLabel = activePanel?.label ?? '';
+    // Tells the status line which panel is showing. Reported from an effect
+    // on the active label itself, so it also follows a re-parse (`--watch`)
+    // that changes the panels under a mounted block. The root ignores a
+    // report that repeats what it already has, so this cannot loop.
+    useEffect(() => {
+        if (interactive && focusId !== undefined) {
+            reportActiveLabel(focusId, activeLabel);
+        }
+    }, [interactive, focusId, activeLabel, reportActiveLabel]);
+    const strip = panels
+        .map((panel, index) => {
+        const rendered = index === activeIndex
+            ? bold(`[${panel.label}]`, color)
+            : dim(panel.label, color);
+        return index > 0 ? `  ${rendered}` : rendered;
+    })
+        .join('');
+    const focusGlyph = focused ? glyphs.focus : '  ';
+    const headingLine = useFocusMarker(`${focusGlyph}${strip}`, focusId);
+    if (!interactive) {
+        return (_jsx(Box, { flexDirection: "column", children: panels.map((panel, index) => (_jsxs(Box, { marginTop: index > 0 ? 1 : 0, flexDirection: "column", children: [_jsx(Text, { children: bold(`${panel.label}${index === 0 ? ' (active)' : ''}`, color) }), panel.body] }, index))) }));
+    }
+    return (_jsxs(Box, { ref: anchor, flexDirection: "column", children: [_jsx(Text, { children: headingLine }), activePanel?.body] }));
+}

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,15 +1,17 @@
-export { renderMarkToAnsi, renderMarkNodeToAnsi, renderMarkInlineToAnsi, type RenderMarkOptions, } from './render.js';
+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, REGISTRY_ALIASES, type DirectiveAttributes, type AnsiRegistry, type AnsiRegistryEntry, type AnsiComponent, type AnsiChildren, type AnsiChildPart, type AnsiChildrenOptions, type AnsiRenderContext, type RegistryAlias, type RegistryAliases, type ResolvedDirective, type ValueResolution, } from './registry.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';
 export { failurePhrase, failureTitle, failureToken, dataStateSuffix, emptyInlineTitle, invalidAttributeValueLabel, invalidAttributeValueTitle, unsafeImageSrcLabel, unsafeImageSrcTitle, } from './failure-presentation.js';
 export { stringifyStoredValue } from './value-format.js';
-export { measure, stripAnsi } from './measure.js';
 export { stripControlCharacters, sanitizeBlockText, sanitizeUrlText, BLOCK_TAB_WIDTH, } from './sanitize.js';
-export { wrap, pad, indentBlock, columns, frame, rule, type FrameOptions, } from './box.js';
 export { resolveLayoutAttributes, applyLayout, LAYOUT_ATTRIBUTE_KEYS, type ResolvedLayoutAttributes, type ResolvedLayoutPresets, type WidthPreset, type AlignPreset, } from './layout.js';
 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

@@ -1,17 +1,20 @@
-// @markii/ansi: a framework-free terminal renderer for Markii documents. It
+// @markii/ansi: a terminal renderer for Markii documents, built on Ink. It
 // consumes @markii/core's sanitized hast and emits a plain string (optionally
 // carrying ANSI SGR/OSC 8 escapes) for a terminal, a pipe, or any host that
-// wants text with no HTML and no React runtime. It is a third platform
-// renderer alongside @markii/html and @markii/react.
-export { renderMarkToAnsi, renderMarkNodeToAnsi, renderMarkInlineToAnsi, } from './render.js';
+// wants text with no HTML runtime — plus, for a live viewer, the Ink element
+// tree itself (`buildMarkElement`). It is a third platform renderer alongside
+// @markii/html and @markii/react.
+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, REGISTRY_ALIASES, } from './registry.js';
+export { createAnsiRegistry, mergeAnsiRegistries, registryAliases, readRegistryComponent, resolveDirectiveAlias, childrenText, REGISTRY_ALIASES, } from './registry.js';
 export { resolveStorePath, resolveScopedPath, VAULT_NAME_PREFIX, } from './resolve.js';
 export { failurePhrase, failureTitle, failureToken, dataStateSuffix, emptyInlineTitle, invalidAttributeValueLabel, invalidAttributeValueTitle, unsafeImageSrcLabel, unsafeImageSrcTitle, } from './failure-presentation.js';
 export { stringifyStoredValue } from './value-format.js';
-export { measure, stripAnsi } from './measure.js';
 export { stripControlCharacters, sanitizeBlockText, sanitizeUrlText, BLOCK_TAB_WIDTH, } from './sanitize.js';
-export { wrap, pad, indentBlock, columns, frame, rule, } from './box.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

@@ -0,0 +1,23 @@
+import type { ReactElement } from 'react';
+/**
+ * Mounts `element` with Ink at `columns` wide, captures the first (and only)
+ * frame as a plain string, and unmounts. `ink` is imported dynamically
+ * because `yoga-layout` (Ink's layout engine) resolves its WASM module via a
+ * top-level `await` at ES-module-evaluation time (`SPIKE-10-findings.md`'s
+ * "Item 3"): the first call to this function pays that one-time cost, and
+ * every exported entry point that reaches here is therefore `async`. A
+ * later call in the same process reuses the already-evaluated module graph,
+ * 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

@@ -0,0 +1,65 @@
+import { Writable } from 'node:stream';
+import { render as inkRender } from 'ink';
+function makeCollectingStream(columns) {
+    const chunks = [];
+    const stream = new Writable({
+        write(chunk, _encoding, callback) {
+            chunks.push(chunk.toString('utf8'));
+            callback();
+        },
+    });
+    stream.columns = columns;
+    stream.rows = 40;
+    // Ink's static/measured layout paths expect a TTY-shaped stream.
+    stream.isTTY = true;
+    stream.getColorDepth = () => 8;
+    stream.hasColors = () => true;
+    return { stream, getOutput: () => chunks.join('') };
+}
+/**
+ * Mounts `element` with Ink at `columns` wide, captures the first (and only)
+ * frame as a plain string, and unmounts. `ink` is imported dynamically
+ * because `yoga-layout` (Ink's layout engine) resolves its WASM module via a
+ * top-level `await` at ES-module-evaluation time (`SPIKE-10-findings.md`'s
+ * "Item 3"): the first call to this function pays that one-time cost, and
+ * every exported entry point that reaches here is therefore `async`. A
+ * later call in the same process reuses the already-evaluated module graph,
+ * the ordinary ESM module-cache guarantee.
+ */
+export async function renderInkToString(element, columns) {
+    const { render } = await import('ink');
+    const { stream, getOutput } = makeCollectingStream(columns);
+    const instance = render(element, {
+        stdout: stream,
+        stdin: process.stdin,
+        exitOnCtrlC: false,
+        patchConsole: false,
+        debug: false,
+        interactive: false,
+    });
+    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

@@ -0,0 +1,66 @@
+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 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';
+    label: string;
+}
+export interface InteractiveRootProps {
+    /** Every focusable component the walk assigned a `focusId` to, in `focusId` order (empty for none). */
+    focusables: readonly FocusableDescriptor[];
+    /** Called when the reader presses `q`. The engine owns no process state: it never calls `process.exit` itself (AGENTS.md, batch-10 brief). */
+    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;
+}
+/**
+ * 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
+ * bar (batch 10.1) naming the focused block and the key legend. Rendered
+ * only when the caller actually wants a live, keyboard-driven view:
+ * `buildMarkElement` mounts this when `interactive` is true, but the
+ * render-ONCE string path (`ink-string.ts`, `renderRootToString`) never
+ * reaches it at all — `tabs`/`details` still fall back to `FocusContext`'s
+ * 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, keyLegend, viewportRows, width, children, }: InteractiveRootProps): ReactNode;