@markii/ansi 0.0.1 → 0.16.0

package/dist/interactive.d.ts

@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react';
+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;
+/**
+ * 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.
+ */
+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;
+    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, children, }: InteractiveRootProps): ReactNode;

package/dist/interactive.js

@@ -0,0 +1,64 @@
+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 { dim } from './ansi.js';
+import { style } from './style.js';
+const FocusContext = createContext({
+    interactive: false,
+    focusedId: undefined,
+    focusMarker: (text) => text,
+});
+/** 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) {
+    const api = useContext(FocusContext);
+    return focusId !== undefined && api.interactive && api.focusedId === focusId;
+}
+/** Wraps `text` in the accent-colored focus marker when interactive AND `focusId` is the focused one; otherwise returns `text` unchanged. */
+export function useFocusMarker(text, focusId) {
+    const api = useContext(FocusContext);
+    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';
+/**
+ * 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 function InteractiveRoot({ focusables, onExit, color, theme, children, }) {
+    const focusableCount = focusables.length;
+    const [focusIndex, setFocusIndex] = useState(0);
+    useInput((input, key) => {
+        if (input === 'q') {
+            onExit?.();
+            return;
+        }
+        if (focusableCount === 0)
+            return;
+        if (key.downArrow || input === 'j') {
+            setFocusIndex((current) => (current + 1) % focusableCount);
+        }
+        else if (key.upArrow || input === 'k') {
+            setFocusIndex((current) => (current - 1 + focusableCount) % focusableCount);
+        }
+    }, { isActive: true });
+    const focusedId = focusableCount > 0 ? focusIndex % focusableCount : undefined;
+    const api = useMemo(() => ({
+        interactive: true,
+        focusedId,
+        focusMarker: (text) => style(text, '--mk-accent', theme, color),
+    }), [focusedId, color, theme]);
+    const focused = focusedId !== undefined ? focusables[focusedId] : undefined;
+    const statusLabel = focused
+        ? `${focused.kind} "${focused.label}"`
+        : '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 })] }) }));
+}

package/dist/layout.js

@@ -1,6 +1,5 @@
 import { ALIGN_PRESETS, LAYOUT_ATTRIBUTE_KEYS, WIDTH_PRESETS, } from '@markii/stdlib';
-import { pad, wrap } from './box.js';
-import { measure } from './measure.js';
+import { padText as pad, wrapText as wrap, measureWidth as measure, } from './text-grid.js';
 /**
  * The terminal counterpart of `@markii/html`'s `layout.ts`: the same closed
  * `width`/`align` vocabulary from `@markii/stdlib`, but resolved to COLUMN

package/dist/registry.d.ts

@@ -1,12 +1,4 @@
-/**
- * The registry contract for the terminal engine: the string-emitting twin of
- * `@markii/html`'s `registry.ts`, itself the string-emitting twin of
- * `@markii/react`'s `registry.ts`. A component here is a plain function from
- * attributes and already-rendered children TEXT to an output string — no
- * hast, no React, no HTML. The alias, merge, and hostile-configuration rules
- * are kept identical to both existing renderers, so a note resolves the same
- * way in all three.
- */
+import type { FC, ReactNode } from 'react';
 import type { FailureKind, ValueStatus } from './value-types.js';
 import type { LayoutAxis, OnDiagnostic } from '@markii/stdlib';
 import type { ColorLevel } from './ansi.js';
@@ -14,6 +6,23 @@ import type { AnsiTheme, Tier1Token } from './theme.js';
 import type { ResolvedLayoutAttributes } from './layout.js';
 import type { ResolveImageSrc } from './image-resolve.js';
 import type { ResolveHref } from './href-resolve.js';
+/**
+ * The registry contract for the terminal engine, batch-10 (the Ink
+ * rewrite): a component is a React function component receiving
+ * `{ attributes, children, ctx }`, where `children` is ALREADY a built Ink
+ * element tree (a `ReactNode`) rather than the lazy string-producing
+ * `AnsiChildren` handle the pre-Ink engine used. Building children eagerly
+ * is the batch-10 brief's own instruction (`AGENTS.md`'s architecture
+ * section is silent on this; the brief is explicit: "Delete... the lazy-
+ * children machinery"): Ink/Yoga lays a tree out AFTER it is built, exactly
+ * like a browser reflows HTML, so a component no longer needs to ask for a
+ * narrower re-render of its own body the way the old string engine did —
+ * the one standard component that still needs a per-cell WIDTH NUMBER before
+ * it draws (`row`, whose cells may hold a self-drawing box like `card`) gets
+ * that from `render.tsx`'s own walk, which still threads `width` top-down
+ * exactly as before; see `render.tsx`'s `renderRow` for why that one case is
+ * handled at the walk level rather than through a registry-facing API.
+ */
 /**
  * Attributes parsed off a directive, e.g. `{type=warning title="Careful"}`. A
  * bare attribute (present but valueless, e.g. `{collapsed}`) arrives as
@@ -32,28 +41,47 @@ export interface ValueResolution {
     failureKind?: FailureKind;
 }
 /**
- * The render context handed to every component. Mirrors
- * `@markii/html`'s `HtmlRenderContext` field for field, with the HTML-only
- * `esc` swapped for `text` (this engine's control-character sanitizer, see
- * `./sanitize.js`'s `stripControlCharacters`) and a set of terminal-only
- * fields added: `width`/`indent` (the layout budget this directive's own
- * output has to work with), `color`/`theme` (what this render resolved),
- * and the box/style helpers pre-bound to both.
+ * The render context handed to every component. Mirrors the pre-Ink
+ * engine's `AnsiRenderContext` for every field EXCEPT the string-layout
+ * helpers (`wrap`/`pad`/`columns`/`frame`/`rule`), which are dropped:
+ * ordinary prose now wraps through Ink's own layout, and the handful of
+ * self-drawing standard components (`card`, `callout`, `divider`, `chart`,
+ * `table`) that still need exact box-drawing glyphs use `./text-grid.js`'s
+ * private helpers directly rather than through the context.
  */
 export interface AnsiRenderContext {
-    /** The columns available to this directive's own output. A component wraps its own text to this width. */
+    /** The columns available to this directive's own output. A self-drawing component sizes its own frame to this width (or to `layout`'s resolved preset of it). */
     width: number;
     /**
      * The prefix an enclosing block (a blockquote, a nested list) has already
-     * applied to every line above this directive. Informational only: a
-     * component emits its own block UNINDENTED, and the walk applies the
-     * prefix afterward, exactly as `width` is already the post-indent budget.
+     * applied to every line above this directive, informational only: a
+     * component draws its own content at `width` and the walk applies the
+     * enclosing indent as an Ink `Box` wrapper, not as a string prefix.
      */
     indent: string;
     /** The resolved color depth for this render. */
     color: ColorLevel;
     /** The resolved theme for this render. */
     theme: AnsiTheme;
+    /**
+     * Whether this render is in INTERACTIVE mode (a live viewer), as opposed
+     * to the default render-once mode. NAME COLLISION, documented at both
+     * declarations: this is UNRELATED to Ink's own `render()` option also
+     * spelled `interactive` (`ink-string.ts`'s doc comment) — that one
+     * controls which escape sequences Ink emits around a frame; this one
+     * controls which CONTENT a component renders (`tabs` shows only the
+     * active panel, `details` starts closed unless `open` is present) and
+     * whether it registers a keyboard handler at all.
+     */
+    interactive: boolean;
+    /**
+     * A stable, document-order identity for a FOCUSABLE component (currently
+     * `tabs` and `details`) when `interactive` is true; `undefined` when not
+     * interactive, or for any other component. Assigned once by `render.tsx`
+     * as it walks the tree (see `render.tsx`'s `WalkContext.nextFocusId`), so
+     * a component never has to compute its own position in document order.
+     */
+    focusId?: number;
     /** Applies `theme`'s color for `token` at this render's `color` level. Unchanged at `'none'` or for a `null` theme entry. */
     style(text: string, token: Tier1Token): string;
     /** SGR bold, pre-bound to this render's color level. */
@@ -66,26 +94,11 @@ export interface AnsiRenderContext {
     underline(text: string): string;
     /** SGR inverse/reverse video, pre-bound to this render's color level. */
     inverse(text: string): string;
-    /** Greedy word wrap, pre-bound to nothing (width is explicit here since a component may wrap narrower than its own `ctx.width`, e.g. inside its own frame). */
-    wrap(text: string, width: number): string[];
-    /** Pads `text` to `width` columns, aligned `left`/`center`/`right`. */
-    pad(text: string, width: number, align: 'left' | 'center' | 'right'): string;
-    /** Places blocks side by side; see `./box.js`'s `columns`. */
-    columns(blocks: readonly string[], widths: readonly number[], gutter: number): string;
-    /** Draws a box around `block`; see `./box.js`'s `frame`. */
-    frame(block: string, options: {
-        style: 'solid' | 'dashed';
-        title?: string;
-        width: number;
-    }): string;
-    /** A full-width horizontal rule; see `./box.js`'s `rule`. */
-    rule(width: number, char?: string): string;
     /**
      * The sanitizer a component MUST run any author-supplied string through
-     * before printing it (this engine's counterpart to the HTML context's
-     * `esc`): strips every control character an untrusted note could use to
-     * move the cursor or smuggle an escape sequence (`./sanitize.js`'s
-     * `stripControlCharacters`).
+     * before printing it: strips every control character an untrusted note
+     * could use to move the cursor or smuggle an escape sequence
+     * (`./sanitize.js`'s `stripControlCharacters`).
      */
     text(value: string): string;
     /** Resolves a `data=`/`:value[...]` name against the current render's store/vault. Never throws. */
@@ -108,76 +121,39 @@ export interface AnsiRenderContext {
     onDiagnostic?: OnDiagnostic;
 }
 /**
- * How a component wants ONE render of its children to happen: at a
- * narrower `width` than the directive itself was rendered at (a self-layout
- * box sizing its own inner budget), and/or a different `indent`. Omitting a
- * field inherits the value the enclosing directive was rendered with.
- */
-export interface AnsiChildrenOptions {
-    width?: number;
-    indent?: string;
-}
-/**
- * One top-level child of a directive's own body, independently renderable
- * at its own width — the piece `row` needs and no other standard component
- * does: it must decide each cell's column width BEFORE that cell's content
- * (including a self-drawing box like `card`) is rendered, not re-wrap an
- * already-drawn frame afterward. `name` is the child's own resolved
- * directive name (e.g. `'cell'`) when the child is itself a directive, and
- * `undefined` for a plain block (a paragraph, a list) or a directive with a
- * different name — enough for a container to recognize a semantically
- * tagged child without ever seeing a hast node.
+ * One registry component: a React function component. `attributes` are the
+ * directive's raw string attributes (bare attributes as `null`); `children`
+ * is the directive's already-rendered inner markdown, an Ink element tree;
+ * `ctx` is `AnsiRenderContext` above. Attribute parsing, validation, and
+ * defaulting are the component's own job, exactly as in the other two
+ * engines' contracts. A component MAY use React hooks (`useState`,
+ * `useInput`, ...) since `render.tsx` always invokes it as a JSX element,
+ * never as a plain function call — `tabs` and `details` need this for
+ * interactive mode.
  */
-export interface AnsiChildPart {
-    readonly name?: string;
-    render(options?: AnsiChildrenOptions): string;
+export interface AnsiComponentProps {
+    attributes: DirectiveAttributes;
+    children: ReactNode;
+    ctx: AnsiRenderContext;
 }
-/**
- * The children a component receives. Calling it directly renders the
- * directive's WHOLE body as one flattened string — what every component
- * except `row` wants, and what used to be eagerly computed as a plain
- * string before the component ever ran. `options` narrows the width/indent
- * for that one call (a self-layout box's inner budget); omitted, it renders
- * at the width/indent the directive itself was given.
- *
- * `.parts` exposes each of the directive's own top-level children
- * separately, in document order, each independently renderable at its own
- * width via its own `render(options)` — see `AnsiChildPart`.
- *
- * Laziness is the point: nothing under this directive is rendered until a
- * component actually calls `children()` or one of `.parts`' `render()`
- * functions, so a container can decide sizes top-down before anything below
- * it draws a single character.
- */
-export type AnsiChildren = ((options?: AnsiChildrenOptions) => string) & {
-    readonly parts: readonly AnsiChildPart[];
-};
-/**
- * One registry component: receives the directive's raw string attributes
- * (bare attributes as `null`), a lazy handle onto its inner markdown
- * (`AnsiChildren`, see above), and the render context, and returns the text
- * to emit. Attribute parsing, validation, and defaulting are the
- * component's own job, exactly as in the other two engines' contracts.
- */
-export type AnsiComponent = (attributes: DirectiveAttributes, children: AnsiChildren, ctx: AnsiRenderContext) => string;
+export type AnsiComponent = FC<AnsiComponentProps>;
 /** One registry entry: the component plus whether it is meant to be used inline vs as a block, and whether it is a layout scope. Mirrors `@markii/html`'s `HtmlRegistryEntry`. */
 export interface AnsiRegistryEntry {
     component: AnsiComponent;
     inline?: boolean;
     layout?: LayoutAxis;
     /**
-     * Marks a component that draws its OWN box (a frame, a table grid) rather
-     * than plain wrapped text — `card`, `callout`, `table`, `chart` in the
-     * standard set. `applyLayout`'s generic re-wrap/pad would corrupt a
-     * pre-drawn frame's box-drawing characters if `render.ts` narrowed it
-     * AFTER the component already drew it at the full width. A `selfLayout`
-     * component instead receives the resolved `width`/`align` presets as
-     * `ctx.layout` (the same field a layout-WRAPPER scope receives) and is
-     * trusted to size its own frame correctly; `render.ts` then skips its
-     * usual post-render `applyLayout` call for it, exactly as it already does
-     * for a layout-wrapper scope. Unlike `layout: LayoutAxis`, this is not
-     * "this directive's name sets an axis" — it is "this directive draws pixels
-     * that a generic wrap/pad would break."
+     * Marks a component that draws its OWN fixed-width block (box-drawing
+     * glyphs, a rule, a sparkline) rather than plain wrapped prose — `card`,
+     * `callout`, `divider`, `table`, `chart` in the standard set. A generic
+     * post-render narrow/align pass would corrupt a pre-drawn frame's
+     * box-drawing characters, so a `selfLayout` component instead receives the
+     * resolved `width`/`align` presets as `ctx.layout` and is trusted to size
+     * its own frame correctly; `render.tsx` skips its usual post-render
+     * `applyLayout` wrapping for it. Kept from the pre-Ink engine: Ink's own
+     * layout does not solve this, because the content in question is a
+     * pre-built STRING (see `text-grid.ts`'s module doc comment), not
+     * Ink primitives Yoga can reflow.
      */
     selfLayout?: boolean;
 }
@@ -225,3 +201,18 @@ export interface ResolvedDirective {
  * throws.
  */
 export declare function resolveDirectiveAlias(registry: AnsiRegistry, name: string, attributes: DirectiveAttributes): ResolvedDirective;
+/**
+ * Reads a component's `children` prop back as plain text. `render.tsx`
+ * always hands most standard components (every one except `row`, `tabs`,
+ * `details`) an already-flattened STRING as `children` — see `render.tsx`'s
+ * top comment on why those three are the only ones that get a real Ink
+ * element tree instead. `children` is still typed `ReactNode` on
+ * `AnsiComponentProps` (the honest public contract: "an Ink element tree",
+ * per the batch-10 brief, and a string IS a valid `ReactNode`), so a
+ * component that needs its body AS TEXT (to measure it, frame it, indent
+ * it, or check whether it is empty) reads it through this helper rather
+ * than assuming the type; a non-string `children` degrades to `''` rather
+ * than throwing, matching this package's never-throw posture everywhere
+ * else.
+ */
+export declare function childrenText(children: ReactNode): string;

package/dist/registry.js

@@ -1,12 +1,3 @@
-/**
- * The registry contract for the terminal engine: the string-emitting twin of
- * `@markii/html`'s `registry.ts`, itself the string-emitting twin of
- * `@markii/react`'s `registry.ts`. A component here is a plain function from
- * attributes and already-rendered children TEXT to an output string — no
- * hast, no React, no HTML. The alias, merge, and hostile-configuration rules
- * are kept identical to both existing renderers, so a note resolves the same
- * way in all three.
- */
 /** The symbol an alias table hangs off a registry under. Mirrors `@markii/html`'s `REGISTRY_ALIASES`. */
 export const REGISTRY_ALIASES = Symbol('markii.ansi.registry.aliases');
 /** Reads a registry's alias table, or `undefined` if it has none. Returned as-is; treat as read-only. */
@@ -119,3 +110,20 @@ export function resolveDirectiveAlias(registry, name, attributes) {
         attributes: mergeAliasAttributes(alias.attributes, attributes),
     };
 }
+/**
+ * Reads a component's `children` prop back as plain text. `render.tsx`
+ * always hands most standard components (every one except `row`, `tabs`,
+ * `details`) an already-flattened STRING as `children` — see `render.tsx`'s
+ * top comment on why those three are the only ones that get a real Ink
+ * element tree instead. `children` is still typed `ReactNode` on
+ * `AnsiComponentProps` (the honest public contract: "an Ink element tree",
+ * per the batch-10 brief, and a string IS a valid `ReactNode`), so a
+ * component that needs its body AS TEXT (to measure it, frame it, indent
+ * it, or check whether it is empty) reads it through this helper rather
+ * than assuming the type; a non-string `children` degrades to `''` rather
+ * than throwing, matching this package's never-throw posture everywhere
+ * else.
+ */
+export function childrenText(children) {
+    return typeof children === 'string' ? children : '';
+}

package/dist/render.d.ts

@@ -1,3 +1,4 @@
+import type { ReactElement, ReactNode } from 'react';
 import { parse } from '@markii/core';
 import type { MarkNode } from '@markii/core';
 import { type ColorOption } from './ansi.js';
@@ -8,11 +9,14 @@ import { type ResolveImageSrc } from './image-resolve.js';
 import { type ResolveHref } from './href-resolve.js';
 import type { AnsiValueStore, AnsiVaultStore } from './value-types.js';
 type MarkRoot = ReturnType<typeof parse>;
+export interface ElementTabPanel {
+    label: string;
+    body: ReactNode;
+}
 /**
  * Options for `renderMarkToAnsi`/`renderMarkNodeToAnsi`/`renderMarkInlineToAnsi`.
  * `store`/`vault` are offered both here and as positional parameters; when
- * both are given, the option wins (matching `@markii/html`'s
- * `RenderMarkOptions`).
+ * both are given, the option wins.
  */
 export interface RenderMarkOptions {
     readonly width?: number;
@@ -23,21 +27,27 @@ export interface RenderMarkOptions {
     readonly onDiagnostic?: OnDiagnostic;
     readonly store?: AnsiValueStore;
     readonly vault?: AnsiVaultStore;
+    /**
+     * Renders the document's CONTENT in interactive shape (tabs show only
+     * their active panel, details start closed unless `open`) without
+     * actually mounting a live keyboard loop — this render-once path always
+     * captures exactly one frame (`ink-string.ts`'s own `interactive: false`
+     * Ink render option is a SEPARATE thing; see its doc comment for the
+     * name collision). Defaults to `false`: unset, `tabs`/`details` render
+     * every panel/always-open exactly as the pre-Ink engine did.
+     */
+    readonly interactive?: boolean;
 }
 /**
  * Renders Markii text to a plain string (optionally carrying ANSI SGR/OSC 8
  * escapes) using `registry` to resolve directive names. `registry` is
  * OPTIONAL here, unlike the other two engines' required parameter, and
- * defaults to `defaultAnsiRegistry` (empty in this phase; every directive
- * therefore renders the unknown-component fallback).
+ * defaults to `defaultAnsiRegistry`.
  *
- * Pipeline: `@markii/core`'s `toHast` (parse -> tag directive nodes ->
- * remark-rehype -> sanitize URLs) -> a width-aware hast walk that swaps
- * directive elements for registry components (or the unknown-directive
- * fallback), folds script fences into a one-line marker, and wraps every
- * paragraph, heading, and list item to `options.width` (default 80). Pure
- * and never-throwing: parsing is tolerant, unknown names always render a
- * fallback, and any unexpected internal error degrades to the "failed to
+ * `async` since the first call in a process pays Ink/Yoga's one-time module-
+ * evaluation cost (`ink-string.ts`'s doc comment; `SPIKE-10-findings.md`'s
+ * "Item 3"). Never throws: parsing is tolerant, unknown names always render
+ * a fallback, and any unexpected internal error degrades to the "failed to
  * render document" line.
  *
  * `options.color` resolves via `./ansi.js`'s `resolveColorOption`: `'auto'`
@@ -45,25 +55,30 @@ export interface RenderMarkOptions {
  * environment knowledge of its own — a caller that wants automatic
  * detection calls `detectColorLevel` itself and passes the result as
  * `'16'`/`'256'`/`'truecolor'`.
- *
- * `store`/`vault` and `resolveImageSrc`/`resolveHref`/`onDiagnostic` carry
- * the same meaning as `@markii/html`'s identical options.
  */
-export declare function renderMarkToAnsi(text: string, registry?: AnsiRegistry, store?: AnsiValueStore, vault?: AnsiVaultStore, options?: RenderMarkOptions): string;
+export declare function renderMarkToAnsi(text: string, registry?: AnsiRegistry, store?: AnsiValueStore, vault?: AnsiVaultStore, options?: RenderMarkOptions): Promise<string>;
 /**
  * The block-level twin of `renderMarkToAnsi`: renders one already-parsed
- * mdast node OR a whole already-parsed mdast document (`@markii/core`'s
- * `MarkNode`, or the `Root` `parse` itself returns) instead of raw document
- * text. Same registry resolution, same fallbacks, same purity and
+ * mdast node OR a whole already-parsed mdast document instead of raw
+ * document text. Same registry resolution, same fallbacks, same purity and
  * never-throw guarantees, same options.
  */
-export declare function renderMarkNodeToAnsi(node: MarkNode | MarkRoot, registry?: AnsiRegistry, store?: AnsiValueStore, vault?: AnsiVaultStore, options?: RenderMarkOptions): string;
+export declare function renderMarkNodeToAnsi(node: MarkNode | MarkRoot, registry?: AnsiRegistry, store?: AnsiValueStore, vault?: AnsiVaultStore, options?: RenderMarkOptions): Promise<string>;
 /**
  * Renders `text` as a single, standalone inline directive when that is all
- * it is, mirroring `@markii/html`'s identical `renderMarkInlineToHtml`: a
- * source whose only parsed block is a paragraph holding exactly one text
- * directive renders that directive alone. Any other source falls back to
- * the exact same rendering `renderMarkToAnsi` would produce.
+ * it is. Any other source falls back to the exact same rendering
+ * `renderMarkToAnsi` would produce.
+ */
+export declare function renderMarkInlineToAnsi(text: string, registry?: AnsiRegistry, store?: AnsiValueStore, vault?: AnsiVaultStore, options?: RenderMarkOptions): Promise<string>;
+/**
+ * The live-viewer entry point (phase 3 consumes this): builds the same Ink
+ * element tree `renderMarkToAnsi` would render to a string, but returns the
+ * element itself so a host (the CLI's `markii view`) can mount it directly
+ * with Ink's own `render()` instead of re-rendering a string on every
+ * keystroke/resize. `document` accepts raw text OR an already-parsed mdast
+ * node/root, mirroring the three string entry points' flexibility.
  */
-export declare function renderMarkInlineToAnsi(text: string, registry?: AnsiRegistry, store?: AnsiValueStore, vault?: AnsiVaultStore, options?: RenderMarkOptions): string;
+export declare function buildMarkElement(document: string | MarkNode | MarkRoot, registry?: AnsiRegistry, options?: RenderMarkOptions & {
+    readonly onExit?: () => void;
+}): ReactElement;
 export {};