@markii/ansi 0.15.0 → 0.16.0

package/dist/render.js

@@ -1,9 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Fragment } from 'react';
+import { Box, Text } from 'ink';
 import { parse, toHast, nodeToHast, isSafeUrl, parseMetaAttributes, isValidScriptName, } from '@markii/core';
-import { bold, dim, hyperlink, inverse, italic, resolveColorOption, underline, } from './ansi.js';
+import { bold, carrySgrAcrossLines, dim, hyperlink, inverse, italic, resolveColorOption, underline, } from './ansi.js';
 import { style } from './style.js';
 import { defaultAnsiTheme } from './theme.js';
-import { columns, frame, pad, rule, wrap } from './box.js';
-import { measure } from './measure.js';
+import { frameBlock, measureWidth, padText, ruleLine, wrapText, } from './text-grid.js';
+import { drawTableGrid } from './components/table-grid.js';
+import { resolveRowLayout } from './components/row.js';
+import { resolveCardInnerWidth } from './components/card.js';
+import { resolveCalloutInnerWidth } from './components/callout.js';
+import { resolveDetailsInnerWidth } from './components/details-string.js';
 import { sanitizeBlockText, sanitizeUrlText, stripControlCharacters, } from './sanitize.js';
 import { readRegistryComponent, registryLayoutAxis, registrySelfLayout, resolveDirectiveAlias, } from './registry.js';
 import { applyLayout, resolveLayoutAttributes, } from './layout.js';
@@ -13,28 +20,55 @@ import { formatValue, getContract, reportDiagnostic, } from '@markii/stdlib';
 import { resolveImageAttribute, } from './image-resolve.js';
 import { resolveHrefAttribute } from './href-resolve.js';
 import { defaultAnsiRegistry } from './components/index.js';
-import { drawTableGrid } from './components/table-grid.js';
+import { renderInkToString } from './ink-string.js';
+import { InteractiveRoot } from './interactive.js';
+import { InteractiveTabs } from './components/tabs.js';
+import { InteractiveDetails } from './components/details.js';
 /**
- * The hast walk for the terminal engine, mirroring `@markii/html`'s
- * `render.ts` structure closely enough that a reader of one can read the
- * other: the same directive-resolution pipeline (alias, layout, data
- * binding, form mismatch, invalid-enum notice, empty-inline notice,
- * never-throw component containment), applied to a WIDTH-AWARE plain-text
- * output instead of an HTML string.
+ * The hast walk for the terminal engine (batch 10: the Ink rewrite). Every
+ * DECISION this walk makes is unchanged from the pre-Ink engine (alias
+ * resolution, layout resolution, data binding, form mismatch, invalid-enum
+ * notice, empty-inline notice, never-throw component containment, script-
+ * fence markers, link and image handling) — see AGENTS.md's architecture
+ * rules and the batch-10 brief. What changed is the OUTPUT shape: instead of
+ * building one big plain string, the walk builds a tree of Ink elements
+ * (`Box`/`Text`) and hands it to `ink-string.ts` (the render-once path) or
+ * returns it directly (the new live-viewer export, `buildMarkElement`).
+ *
+ * Two rendering "modes" coexist deliberately, and BOTH still exist in the
+ * pre-Ink engine's shape:
  *
- * The one structural difference `@markii/html` does not have: wrapping is
- * not free here. A browser reflows HTML at whatever width the viewport
- * gives it; a terminal line is fixed the moment this engine emits it. Every
- * block-rendering function below therefore takes an explicit `width`
- * (columns available) and, for a directive, an `indent` (the prefix an
- * enclosing block has already applied), and produces its OWN wrapped lines
- * rather than leaving wrapping to something downstream.
+ * - STRING mode (`render*String` functions below): the pre-Ink algorithm,
+ *   almost verbatim, still building one flattened, pre-wrapped, pre-aligned
+ *   string. This is what every standard component's OWN body still uses —
+ *   `card` frames a string, `callout` bars a string, `details` indents a
+ *   string — because these components draw FIXED-WIDTH GLYPHS that must be
+ *   correct the moment the string is built; Ink lays a tree out AFTER it is
+ *   built, so it cannot reflow a box-drawing frame or re-justify per-line
+ *   text alignment the way `text=center` needs (Ink has no per-line
+ *   paragraph-justify primitive). String mode is also the ONLY mode inline
+ *   content ever uses, at any nesting depth: an inline directive's body is
+ *   phrasing content by definition (docs/spec.md), never a layout the reader
+ *   would want Ink to lay out as boxes.
+ * - ELEMENT mode (`render*Element` functions below): real Ink elements,
+ *   used for the document's own block sequencing (so ordinary prose wraps
+ *   through Ink's own layout instead of this engine's manual `wrap()`) and
+ *   for the three block directives that genuinely need Ink's real layout or
+ *   real component state: `row` (a flex `Box` row instead of the deleted
+ *   `columns()` string helper), `tabs` and `details` (real React state, for
+ *   `ctx.interactive`'s keyboard-driven switching/toggling). A `row`/`tabs`/
+ *   `details` reached through a STRING-mode ancestor (nested inside `card`,
+ *   `callout`, `figure`, a standalone `cell`, or a GFM table cell) falls
+ *   back to a flattened STRING rendering of itself with no interactivity —
+ *   an accepted, documented boundary: a self-drawing container's body is, by
+ *   its own nature, a fixed string, so nothing nested inside one can be
+ *   live. See this file's `renderRowString`/`renderTabsString` for that
+ *   fallback.
  *
- * Interactive components have no meaning in a terminal: `@markii/stdlib`'s
- * `INTERACTIVE_ATTRIBUTE` marks an element a host should treat as a live
- * control (a script-marker `<summary>`, say); this engine has no notion of
- * a live control at all, so it never reads that attribute and never emits
- * a marker for it — there is nothing to degrade, unlike a genuine failure.
+ * Interactive components have no meaning for a NON-interactive render at
+ * all: `@markii/stdlib`'s `INTERACTIVE_ATTRIBUTE` marks an element a HOST
+ * should treat as a live control (a script-marker `<summary>`, say); this
+ * engine never reads that attribute and never emits a marker for it.
  */
 /** The hast tag name `@markii/core` marks every directive with. */
 const DIRECTIVE_TAG = 'mk-directive';
@@ -46,6 +80,10 @@ const VALUE_DIRECTIVE_NAME = 'value';
 const DATA_ATTRIBUTE_KEY = 'data';
 /** The attribute `@markii/core` preserves a code fence's raw `meta` string onto. */
 const CODE_META_ATTR = 'data-mk-meta';
+/** The three block directive names given real Ink layout/state (see this file's top comment). */
+const ROW_NAME = 'row';
+const TABS_NAME = 'tabs';
+const DETAILS_NAME = 'details';
 /** Block-level hast tags this engine recognizes; anything else inside a directive's children is treated as inline content. */
 const BLOCK_TAGS = new Set([
     'p',
@@ -74,6 +112,30 @@ function nodeOrRootToHast(node) {
     }
     return { type: 'root', children };
 }
+function nextFocusId(wctx) {
+    const id = wctx.focusCounter.current;
+    wctx.focusCounter.current += 1;
+    return id;
+}
+/** Records `descriptor` for `focusId` when `wctx` is collecting them (a no-op otherwise). Call sites push in the same order they call `nextFocusId`, so `focusId` always equals the descriptor's index. */
+function recordFocusable(wctx, descriptor) {
+    wctx.focusables?.push(descriptor);
+}
+/**
+ * The ONE place a STRING built by this file's string engine becomes an Ink
+ * `<Text>` leaf. Every such string passes through `ansi.js`'s
+ * `carrySgrAcrossLines` first — see that function's doc comment for why:
+ * Ink resets SGR state at every embedded line boundary within one `<Text>`
+ * value, so a multi-line styled string (a dim-wrapped frame, a wrapped
+ * bold heading, a paragraph whose bold span straddled a wrap point) must
+ * have every physical line already self-contained before Ink ever sees it.
+ * This is the SYSTEMATIC fix (a single choke point) rather than a per-
+ * call-site one: every `<Text>` in this file that renders a plain string
+ * uses this, never a bare `<Text>{str}</Text>`.
+ */
+function styledText(text) {
+    return _jsx(Text, { children: carrySgrAcrossLines(text) });
+}
 /** A directive property read back as a string, or `undefined` if absent or non-string. */
 function stringProperty(element, name) {
     const value = element.properties?.[name];
@@ -141,30 +203,9 @@ function fallbackLabel(name, inline, reason) {
     }
     return `unknown component ${code}`;
 }
-/**
- * Renders `children`'s default (whole-body) text, never throwing. Used only
- * on already-exceptional paths (an unregistered directive, a form mismatch,
- * a component that itself threw): the render walk underneath `children` is
- * documented never-throw, but these three call sites are exactly the ones
- * built to contain a failure, so they must not become a new way to produce
- * one themselves.
- */
-function safeChildrenText(children) {
-    try {
-        return children();
-    }
-    catch {
-        return '';
-    }
-}
 /** The unknown-directive fallback: dim inline text for a text directive, a dashed dim frame for a block directive. Wording matches `@markii/html`'s `fallbackLabel` exactly. */
 function unknownDirective(name, inline, childrenText, reason, width, color) {
     const label = fallbackLabel(name, inline, reason);
-    // The label and the passed-through content need a visible boundary. The
-    // HTML and React engines get one from the fallback's own styling, which a
-    // terminal cannot rely on: with color off there is nothing at all between
-    // the two, so the label runs straight into the author's words. A colon is
-    // the separator, and only when there is content to separate.
     if (inline) {
         return childrenText === ''
             ? dim(label, color)
@@ -174,24 +215,23 @@ function unknownDirective(name, inline, childrenText, reason, width, color) {
     const wrappedChildren = childrenText
         ? childrenText
             .split('\n')
-            .flatMap((line) => wrap(line, innerWidth))
+            .flatMap((line) => wrapText(line, innerWidth))
             .join('\n')
         : '';
     const body = wrappedChildren ? `${label}\n\n${wrappedChildren}` : label;
-    return dim(frame(body, { style: 'dashed', width }), color);
+    return dim(frameBlock(body, { style: 'dashed', width }), color);
 }
 /** A registered component that threw while rendering, contained to a neutral box rather than failing the whole document. Never dumps the error text. */
 function componentError(name, inline, childrenText, width, color) {
     const label = `component \`${stripControlCharacters(name)}\` failed to render`;
-    // Same boundary rule as `unknownDirective`'s inline branch above.
     if (inline) {
         return childrenText === ''
             ? dim(label, color)
             : `${dim(`${label}:`, color)} ${childrenText}`;
     }
-    return dim(frame(label, { style: 'dashed', width }), color);
+    return dim(frameBlock(label, { style: 'dashed', width }), color);
 }
-/** Splits a `data=<name>` attribute off `attributes` and resolves it against `scope`. Never throws. Mirrors `@markii/html`'s `resolveDataAttribute`. */
+/** Splits a `data=<name>` attribute off `attributes` and resolves it against `scope`. Never throws. */
 function resolveDataAttribute(attributes, scope) {
     if (!Object.hasOwn(attributes, DATA_ATTRIBUTE_KEY))
         return { attributes };
@@ -207,7 +247,7 @@ function resolveDataAttribute(attributes, scope) {
         dataFailureKind: resolved.status === 'error' ? resolved.failureKind : undefined,
     };
 }
-/** Whether one of `name`'s `@markii/stdlib` contract attributes with a closed `enum` is present with a value outside it. Mirrors `@markii/html`'s identical check. */
+/** Whether one of `name`'s `@markii/stdlib` contract attributes with a closed `enum` is present with a value outside it. */
 function invalidEnumAttribute(name, attributes) {
     const contract = getContract(name);
     if (!contract)
@@ -231,14 +271,7 @@ function resolveValue(scope, name) {
         return { value: undefined, status: 'missing' };
     return resolveScopedPath(scope, trimmed);
 }
-/**
- * Builds the missing/stale/resolved marker text for a resolved value name.
- * A plain miss (no error attached) shows only the `{name}` placeholder —
- * there is nothing more to say. An `'error'` status, or a stale value, gets
- * `failure-presentation.ts`'s `dataStateSuffix` appended as visible trailing
- * text: a terminal has no tooltip channel, so the reason has to reach the
- * text itself (AGENTS.md's "clean is not silent").
- */
+/** Builds the missing/stale/resolved marker text for a resolved value name. */
 function renderValueMarker(name, resolved, format, decimals, color, theme) {
     if (resolved.status === 'missing' || resolved.status === 'error') {
         const failureKind = resolved.status === 'error' ? resolved.failureKind : undefined;
@@ -256,24 +289,20 @@ function renderValueMarker(name, resolved, format, decimals, color, theme) {
     return suffix ? `${styled}${dim(suffix, color)}` : styled;
 }
 /** Builds the `AnsiRenderContext` handed to one component invocation. */
-function buildComponentContext(width, indent, wctx, binding, layout) {
+function buildComponentContext(width, indent, wctx, binding, layout, focusId) {
     const { color, theme, scope } = wctx;
     const ctx = {
         width,
         indent,
         color,
         theme,
+        interactive: wctx.interactive,
         style: (text, token) => style(text, token, theme, color),
         bold: (text) => bold(text, color),
         dim: (text) => dim(text, color),
         italic: (text) => italic(text, color),
         underline: (text) => underline(text, color),
         inverse: (text) => inverse(text, color),
-        wrap: (text, w) => wrap(text, w),
-        pad: (text, w, align) => pad(text, w, align),
-        columns: (blocks, widths, gutter) => columns(blocks, widths, gutter),
-        frame: (block, options) => frame(block, options),
-        rule: (w, char) => rule(w, char),
         text: (value) => stripControlCharacters(value),
         resolve: (name) => resolveValue(scope, name),
         valueMarker: (name, format, decimals) => {
@@ -287,6 +316,8 @@ function buildComponentContext(width, indent, wctx, binding, layout) {
         resolveHref: wctx.resolveHref,
         onDiagnostic: wctx.onDiagnostic,
     };
+    if (focusId !== undefined)
+        ctx.focusId = focusId;
     if ('data' in binding) {
         ctx.data = binding.data;
         ctx.dataStatus = binding.dataStatus;
@@ -297,42 +328,54 @@ function buildComponentContext(width, indent, wctx, binding, layout) {
         ctx.layout = layout;
     return ctx;
 }
-/** Resolves one directive (registry component, `:value[...]`, or a fallback), given its layout-stripped attributes. Never throws. */
-function renderDirectiveContent(name, kind, isBlock, attributes, children, width, indent, wctx, layoutForComponent) {
+// ---------------------------------------------------------------------------
+// STRING MODE — the pre-Ink algorithm. Used for every inline position (at
+// any depth) and for a directive's own body once it is not one of the three
+// Ink-element-aware directives (`row`/`tabs`/`details`).
+// ---------------------------------------------------------------------------
+function safeChildrenText(text) {
+    return text ?? '';
+}
+function isBlockLevelChildren(children) {
+    for (const child of children) {
+        if (child.type !== 'element')
+            continue;
+        if (BLOCK_TAGS.has(child.tagName))
+            return true;
+        if (child.tagName === DIRECTIVE_TAG) {
+            const kind = stringProperty(child, 'data-mk-kind');
+            if (kind !== TEXT_DIRECTIVE_KIND)
+                return true;
+        }
+    }
+    return false;
+}
+function renderDirectiveContentString(name, kind, isBlock, attributes, childrenText, width, indent, wctx, layoutForComponent) {
     const inline = !isBlock;
     const entry = Object.hasOwn(wctx.registry, name)
         ? wctx.registry[name]
         : undefined;
     const component = readRegistryComponent(entry);
     if (!entry || component == null) {
-        return unknownDirective(name || '(unnamed)', inline, safeChildrenText(children), 'unregistered', width, wctx.color);
+        return unknownDirective(name || '(unnamed)', inline, safeChildrenText(childrenText), 'unregistered', width, wctx.color);
     }
     if (isFormMismatch(entry, kind)) {
-        return unknownDirective(name || '(unnamed)', inline, safeChildrenText(children), 'form-mismatch', width, wctx.color);
+        return unknownDirective(name || '(unnamed)', inline, safeChildrenText(childrenText), 'form-mismatch', width, wctx.color);
     }
     const binding = resolveDataAttribute(attributes, wctx.scope);
-    const ctx = buildComponentContext(width, indent, wctx, binding, layoutForComponent);
+    const ctx = buildComponentContext(width, indent, wctx, binding, layoutForComponent, undefined);
     let rendered;
     try {
-        rendered = component(binding.attributes, children, ctx);
+        const result = component({
+            attributes: binding.attributes,
+            children: childrenText,
+            ctx,
+        });
+        rendered = typeof result === 'string' ? result : String(result ?? '');
     }
     catch {
-        return componentError(name || '(unnamed)', inline, safeChildrenText(children), width, wctx.color);
-    }
-    // The silent-value-drop mechanism (AGENTS.md "clean is not silent"): a
-    // known attribute's value outside its closed enum still renders the
-    // component exactly as registered, with a short labeled marker appended
-    // (there is no tooltip channel in a terminal, so the full reason cannot
-    // live inline without becoming body text again). The full sentence is
-    // reported to `onDiagnostic` for a host's own diagnostics surface; a
-    // caller that passes no `onDiagnostic` simply gets the marker with no
-    // reason anywhere, exactly like the browser engines with no tooltip read.
-    //
-    // A block component's marker goes on its OWN line. Appended to the same
-    // line it would land against the bottom edge of whatever the component
-    // drew, turning a clean box into a box with a label stuck to its corner.
-    // Only an inline component, which is already part of a line of text,
-    // takes the marker inline.
+        return componentError(name || '(unnamed)', inline, safeChildrenText(childrenText), width, wctx.color);
+    }
     const markerSeparator = inline ? ' ' : '\n';
     const invalidEnum = invalidEnumAttribute(name, binding.attributes);
     if (invalidEnum) {
@@ -345,221 +388,129 @@ function renderDirectiveContent(name, kind, isBlock, attributes, children, width
         const label = invalidAttributeValueLabel(name, invalidEnum.attribute);
         rendered = `${rendered}${markerSeparator}${dim(`[${label}]`, wctx.color)}`;
     }
-    // An `inline: true` component with no content still renders exactly as
-    // registered, with the same quiet trailing marker.
-    if (isRegisteredInline(entry) && safeChildrenText(children).trim() === '') {
+    if (isRegisteredInline(entry) &&
+        safeChildrenText(childrenText).trim() === '') {
         rendered = `${rendered}${dim(` (${emptyInlineTitle(name)})`, wctx.color)}`;
     }
     return rendered;
 }
-/** Whether `children` reads as block-level content (a container directive's body) rather than inline/phrasing content (a leaf directive's body). */
-function isBlockLevelChildren(children) {
-    for (const child of children) {
-        if (child.type !== 'element')
-            continue;
-        if (BLOCK_TAGS.has(child.tagName))
-            return true;
-        if (child.tagName === DIRECTIVE_TAG) {
-            const kind = stringProperty(child, 'data-mk-kind');
-            if (kind !== TEXT_DIRECTIVE_KIND)
-                return true;
-        }
-    }
-    return false;
-}
-function renderDirectiveChildren(children, width, indent, wctx) {
+function renderDirectiveChildrenString(children, width, indent, wctx) {
     if (isBlockLevelChildren(children)) {
-        return renderBlocks(children, width, indent, wctx);
-    }
-    return renderInlineChildren(children, width, indent, wctx);
-}
-/** The resolved directive name for a `<mk-directive>` element, after alias resolution — the name `AnsiChildPart.name` reports. Attributes play no part in identifying a child this way, so an empty attribute map is enough. */
-function resolvedChildDirectiveName(element, registry) {
-    const written = stringProperty(element, 'data-mk-name') ?? '';
-    return resolveDirectiveAlias(registry, written, {}).name;
-}
-/**
- * Builds one `AnsiChildPart` per top-level child of a directive's BLOCK
- * body (a pure whitespace-only text node between blocks, the same kind
- * `renderBlocks` already treats as carrying no content, contributes no
- * part). Each part renders lazily via the same per-node `renderBlock` the
- * ordinary block walk uses, so a container that calls `part.render` at its
- * own chosen width gets exactly what a document-level render at that width
- * would have produced — no separate rendering path to drift from the
- * ordinary one.
- */
-function buildBlockChildParts(nodes, width, indent, wctx) {
-    const parts = [];
-    for (const node of nodes) {
-        if (node.type === 'text' && node.value.trim() === '')
-            continue;
-        const name = node.type === 'element' && node.tagName === DIRECTIVE_TAG
-            ? resolvedChildDirectiveName(node, wctx.registry)
-            : undefined;
-        parts.push({
-            name,
-            render: (options) => renderBlock(node, options?.width ?? width, options?.indent ?? indent, wctx),
-        });
+        return renderBlocksString(children, width, indent, wctx);
     }
-    return parts;
+    return renderInlineChildrenString(children, width, indent, wctx);
 }
-/**
- * Builds the `AnsiChildren` handle a component receives (`registry.ts`'s
- * doc comment on the type): calling it renders the WHOLE body, lazily, at
- * an optionally narrower width/indent; `.parts` exposes each top-level
- * child separately for a container (`row`) that must size each one before
- * it is drawn. Nothing under `element` is rendered until a caller actually
- * invokes one of these functions.
- */
-function buildChildren(element, width, indent, wctx) {
-    const isBlock = isBlockLevelChildren(element.children);
-    const fn = ((options) => renderDirectiveChildren(element.children, options?.width ?? width, options?.indent ?? indent, wctx));
-    Object.defineProperty(fn, 'parts', {
-        enumerable: true,
-        get: () => isBlock
-            ? buildBlockChildParts(element.children, width, indent, wctx)
-            : [
-                {
-                    render: (options) => renderInlineChildren(element.children, options?.width ?? width, options?.indent ?? indent, wctx),
-                },
-            ],
-    });
-    return fn;
-}
-/** Turns one `<mk-directive>` element into its rendered text, including the layout adjustment for a block directive whose layout it does not own. */
-function renderDirective(element, width, indent, wctx) {
-    const written = stringProperty(element, 'data-mk-name') ?? '';
-    const kind = stringProperty(element, 'data-mk-kind');
-    const rawAttributes = parseAttributes(stringProperty(element, 'data-mk-attrs'));
-    const isBlock = kind !== TEXT_DIRECTIVE_KIND;
-    if (written === VALUE_DIRECTIVE_NAME) {
-        const plainLabel = extractPlainText(element.children);
-        const resolved = resolveValue(wctx.scope, plainLabel);
-        return renderValueMarker(plainLabel.trim(), resolved, rawAttributes.format ?? undefined, rawAttributes.decimals ?? undefined, wctx.color, wctx.theme);
+function renderRowString(element, attributes, width, indent, wctx) {
+    const cellNodes = element.children.filter((node) => !(node.type === 'text' && node.value.trim() === ''));
+    const layout = resolveRowLayout(attributes, cellNodes.length, width);
+    if (cellNodes.length === 0)
+        return '';
+    const place = (text, w) => layout.align === 'left'
+        ? text
+        : text
+            .split('\n')
+            .map((line) => padText(line, w, layout.align))
+            .join('\n');
+    if (layout.stacked) {
+        return cellNodes
+            .map((node) => place(renderBlockString(node, width, indent, wctx), width))
+            .join('\n\n');
     }
-    const { name, attributes: aliased } = resolveDirectiveAlias(wctx.registry, written, rawAttributes);
-    const ownedAxis = registryLayoutAxis(wctx.registry, name);
-    const { attributes, resolved: layoutResolved } = resolveLayoutAttributes(aliased, isBlock ? ownedAxis : undefined);
-    const isLayoutScope = ownedAxis !== undefined && isBlock;
-    // A `selfLayout` component (a box-drawing standard component: card,
-    // callout, table, chart) also owns applying its own width/align — see
-    // `registry.ts`'s `AnsiRegistryEntry.selfLayout` doc comment for why the
-    // generic post-render `applyLayout` below would corrupt its frame.
-    const isSelfLayout = isBlock && registrySelfLayout(wctx.registry, name);
-    const children = buildChildren(element, width, indent, wctx);
-    const content = renderDirectiveContent(name, kind, isBlock, attributes, children, width, indent, wctx, isLayoutScope || isSelfLayout ? layoutResolved : undefined);
-    if (isBlock && layoutResolved && !isLayoutScope && !isSelfLayout) {
-        return applyLayout(content, layoutResolved, width);
+    const placedCells = cellNodes.map((node) => place(renderBlockString(node, layout.colWidth, indent, wctx), layout.colWidth));
+    const gridRows = [];
+    for (let index = 0; index < placedCells.length; index += layout.columnCount) {
+        const rowCells = placedCells.slice(index, index + layout.columnCount);
+        const lineArrays = rowCells.map((cell) => cell.split('\n'));
+        const rowHeight = Math.max(0, ...lineArrays.map((lines) => lines.length));
+        const lines = [];
+        for (let line = 0; line < rowHeight; line += 1) {
+            lines.push(lineArrays
+                .map((cellLines) => padText(cellLines[line] ?? '', layout.colWidth, 'left'))
+                .join(' ')
+                .replace(/[ ]+$/, ''));
+        }
+        gridRows.push(lines.join('\n'));
     }
-    return content;
+    return gridRows.join('\n\n');
 }
-/** The plain text content of an element's descendants, sanitized (used for inline `<code>`, which never carries nested styling). */
-function getPlainText(node) {
-    let text = '';
-    for (const child of node.children) {
-        if (child.type === 'text')
-            text += stripControlCharacters(child.value);
-        else if (child.type === 'element')
-            text += getPlainText(child);
+const DEFAULT_TAB_LABEL = 'Tab';
+/** Extracts each top-level `tab` child's own label attribute and rendered body, used by BOTH the string fallback and the real interactive builder — a structural replacement for the pre-Ink engine's fragile "split the flattened string on a blank line" heuristic. */
+function extractTabPanels(element, width, indent, wctx) {
+    const panels = [];
+    for (const node of element.children) {
+        if (node.type === 'text' && node.value.trim() === '')
+            continue;
+        if (node.type !== 'element')
+            continue;
+        let label = DEFAULT_TAB_LABEL;
+        let isTab = false;
+        if (node.tagName === DIRECTIVE_TAG) {
+            const written = stringProperty(node, 'data-mk-name') ?? '';
+            const attrs = parseAttributes(stringProperty(node, 'data-mk-attrs'));
+            const { name } = resolveDirectiveAlias(wctx.registry, written, attrs);
+            if (name === 'tab') {
+                label = attrs.label ?? DEFAULT_TAB_LABEL;
+                isTab = true;
+            }
+        }
+        // A `tab` child's own label is drawn ONCE, by the heading `tabs`
+        // itself builds below — rendering the whole `tab` directive here (as
+        // for any other block) would ALSO invoke `tab.ts`'s own component,
+        // which draws its OWN bold heading from the same attribute, printing
+        // the label twice. Render only the tab's INNER children instead. A
+        // non-`tab` block (an unlabeled panel) still renders as a whole block,
+        // unchanged.
+        const body = isTab
+            ? renderDirectiveChildrenString(node.children, width, indent, wctx)
+            : renderBlockString(node, width, indent, wctx);
+        panels.push({ label, body });
     }
-    return text;
-}
-/**
- * A link renders as an OSC 8 hyperlink ONLY when: the color level allows
- * escapes at all, `@markii/core`'s `isSafeUrl` accepts the (resolved)
- * href, AND `./sanitize.js`'s `sanitizeUrlText` leaves the href UNCHANGED —
- * that last check is the one that refuses a href carrying a BEL, ESC, or
- * space rather than silently embedding a sanitized-down version of it,
- * matching this module's `hyperlink.probe.test.ts`. Anything else falls
- * back to plain text: the URL once, if the link's own text already IS the
- * URL, otherwise the text followed by `(url)`.
- */
-function renderLink(node, width, indent, wctx) {
-    const hrefRaw = typeof node.properties?.href === 'string' ? node.properties.href : '';
-    const resolvedHref = resolveHrefAttribute(hrefRaw, wctx.resolveHref);
-    const text = renderInlineChildren(node.children, width, indent, wctx);
-    const sanitizedHref = stripControlCharacters(resolvedHref);
-    const canHyperlink = wctx.color !== 'none' &&
-        resolvedHref.trim() !== '' &&
-        isSafeUrl(resolvedHref) &&
-        sanitizeUrlText(resolvedHref) === resolvedHref;
-    if (canHyperlink)
-        return hyperlink(text, resolvedHref, wctx.color);
-    const plainText = text.replace(/\x1b\[[0-9;]*m|\x1b\]8;;[^\x07\x1b]*\x07/g, '');
-    if (plainText === sanitizedHref)
-        return sanitizedHref;
-    return `${text} (${sanitizedHref})`;
+    return panels;
 }
-function renderImage(node, wctx) {
-    const altRaw = typeof node.properties?.alt === 'string' ? node.properties.alt : '';
-    const alt = stripControlCharacters(altRaw);
-    const srcRaw = typeof node.properties?.src === 'string' ? node.properties.src : '';
-    const resolvedSrc = resolveImageAttribute(srcRaw, wctx.resolveImageSrc);
-    const src = stripControlCharacters(resolvedSrc);
-    return `[${alt}] (${src})`;
-}
-function renderInlineNode(node, width, indent, wctx) {
+const ACTIVE_MARKER = ' (active)';
+function renderBlockString(node, width, indent, wctx) {
     if (node.type === 'text')
         return stripControlCharacters(node.value);
     if (node.type !== 'element')
         return '';
-    switch (node.tagName) {
-        case DIRECTIVE_TAG:
-            return renderDirective(node, width, indent, wctx);
-        case 'strong':
-            return bold(renderInlineChildren(node.children, width, indent, wctx), wctx.color);
-        case 'em':
-            return italic(renderInlineChildren(node.children, width, indent, wctx), wctx.color);
-        case 'del':
-            return dim(`~${renderInlineChildren(node.children, width, indent, wctx)}~`, wctx.color);
-        case 'code': {
-            const inner = getPlainText(node);
-            return wctx.color === 'none'
-                ? dim(inner, wctx.color)
-                : inverse(inner, wctx.color);
-        }
-        case 'a':
-            return renderLink(node, width, indent, wctx);
-        case 'img':
-            return renderImage(node, wctx);
-        case 'br':
-            return '\n';
-        case 'input':
-            // Task-list checkboxes are consumed by `renderListItem`; a stray one
-            // (outside a list item) produces nothing rather than leaking markup.
-            return '';
-        default:
-            return renderInlineChildren(node.children ?? [], width, indent, wctx);
+    if (node.tagName === DIRECTIVE_TAG) {
+        return renderDirectiveString(node, width, indent, wctx);
     }
+    if (/^h[1-6]$/.test(node.tagName)) {
+        const level = Number(node.tagName.slice(1));
+        const text = renderInlineChildrenString(node.children, width, indent, wctx);
+        const styled = level === 1
+            ? underline(bold(text, wctx.color), wctx.color)
+            : bold(text, wctx.color);
+        return wrapText(styled, width).join('\n');
+    }
+    if (node.tagName === 'p') {
+        return wrapText(renderInlineChildrenString(node.children, width, indent, wctx), width).join('\n');
+    }
+    if (node.tagName === 'blockquote') {
+        const innerWidth = Math.max(1, width - 2);
+        const inner = renderBlocksString(node.children, innerWidth, `${indent}│ `, wctx);
+        const prefix = dim('│ ', wctx.color);
+        return inner
+            .split('\n')
+            .map((line) => `${prefix}${line}`)
+            .join('\n');
+    }
+    if (node.tagName === 'ul' || node.tagName === 'ol') {
+        return renderListString(node, width, indent, wctx);
+    }
+    if (node.tagName === 'hr')
+        return dim(ruleLine(width), wctx.color);
+    if (node.tagName === 'table')
+        return renderGfmTableString(node, width, wctx);
+    if (node.tagName === 'pre') {
+        const marker = renderScriptMarker(node, wctx.color);
+        if (marker !== undefined)
+            return marker;
+        return renderCodeBlock(node, wctx.color);
+    }
+    return wrapText(renderInlineChildrenString(node.children ?? [], width, indent, wctx), width).join('\n');
 }
-function renderInlineChildren(children, width, indent, wctx) {
-    let result = '';
-    for (const child of children)
-        result += renderInlineNode(child, width, indent, wctx);
-    return result;
-}
-function renderHeading(el, width, indent, wctx) {
-    const level = Number(el.tagName.slice(1));
-    const text = renderInlineChildren(el.children, width, indent, wctx);
-    const styled = level === 1
-        ? underline(bold(text, wctx.color), wctx.color)
-        : bold(text, wctx.color);
-    return wrap(styled, width).join('\n');
-}
-function renderParagraph(el, width, indent, wctx) {
-    const text = renderInlineChildren(el.children, width, indent, wctx);
-    return wrap(text, width).join('\n');
-}
-function renderBlockquote(el, width, indent, wctx) {
-    const innerWidth = Math.max(1, width - 2);
-    const inner = renderBlocks(el.children, innerWidth, `${indent}│ `, wctx);
-    const prefix = dim('│ ', wctx.color);
-    return inner
-        .split('\n')
-        .map((line) => `${prefix}${line}`)
-        .join('\n');
-}
-/** The task-checkbox state of a list item, or `undefined` for an ordinary item. */
 function taskState(li) {
     for (const child of li.children) {
         if (child.type !== 'element')
@@ -567,13 +518,11 @@ function taskState(li) {
         if (child.tagName === 'input') {
             return { checked: Boolean(child.properties?.checked) };
         }
-        // A task checkbox is always the first element in `remark-gfm`'s output;
-        // any other element first means this is not a task item.
         return undefined;
     }
     return undefined;
 }
-function renderListItem(li, marker, width, indent, wctx) {
+function renderListItemString(li, marker, width, indent, wctx) {
     const task = taskState(li);
     const contentChildren = li.children.filter((child) => !(task && child.type === 'element' && child.tagName === 'input'));
     const nestedLists = [];
@@ -588,11 +537,11 @@ function renderListItem(li, marker, width, indent, wctx) {
         }
     }
     const prefix = `${marker}${task ? (task.checked ? '[x] ' : '[ ] ') : ''}`;
-    const prefixWidth = measure(prefix);
+    const prefixWidth = measureWidth(prefix);
     const bodyWidth = Math.max(1, width - prefixWidth);
     const bodyText = isBlockLevelChildren(restChildren)
-        ? renderBlocks(restChildren, bodyWidth, `${indent}${' '.repeat(prefixWidth)}`, wctx)
-        : wrap(renderInlineChildren(restChildren, bodyWidth, indent, wctx), bodyWidth).join('\n');
+        ? renderBlocksString(restChildren, bodyWidth, `${indent}${' '.repeat(prefixWidth)}`, wctx)
+        : wrapText(renderInlineChildrenString(restChildren, bodyWidth, indent, wctx), bodyWidth).join('\n');
     const bodyLines = bodyText === '' ? [''] : bodyText.split('\n');
     const firstLine = `${prefix}${bodyLines[0] ?? ''}`;
     const restLines = bodyLines
@@ -600,7 +549,7 @@ function renderListItem(li, marker, width, indent, wctx) {
         .map((line) => `${' '.repeat(prefixWidth)}${line}`);
     let result = [firstLine, ...restLines].join('\n');
     for (const nested of nestedLists) {
-        const nestedText = renderBlock(nested, Math.max(1, width - 2), `${indent}  `, wctx);
+        const nestedText = renderBlockString(nested, Math.max(1, width - 2), `${indent}  `, wctx);
         result += `\n${nestedText
             .split('\n')
             .map((line) => `  ${line}`)
@@ -608,7 +557,7 @@ function renderListItem(li, marker, width, indent, wctx) {
     }
     return result;
 }
-function renderList(el, width, indent, wctx) {
+function renderListString(el, width, indent, wctx) {
     const ordered = el.tagName === 'ol';
     const startRaw = el.properties?.start;
     const start = ordered && typeof startRaw === 'number' ? startRaw : 1;
@@ -616,7 +565,7 @@ function renderList(el, width, indent, wctx) {
     return items
         .map((li, index) => {
         const marker = ordered ? `${start + index}. ` : '- ';
-        return renderListItem(li, marker, width, indent, wctx);
+        return renderListItemString(li, marker, width, indent, wctx);
     })
         .join('\n');
 }
@@ -647,14 +596,6 @@ function getCodeText(codeNode) {
     }
     return text.endsWith('\n') ? text.slice(0, -1) : text;
 }
-/**
- * Folds a script code block into a one-line collapsed marker, matching
- * `@markii/html`'s `renderScriptMarker` summary wording exactly (a
- * terminal has no expand/collapse affordance, so the body is never shown —
- * see this module's top comment on interactive components). Returns
- * `undefined` for any other `<pre>` so the caller renders it as an
- * ordinary code block.
- */
 function renderScriptMarker(node, color) {
     try {
         const codeNode = findChildElement(node, 'code');
@@ -687,18 +628,7 @@ function renderCodeBlock(node, color) {
         lines.push(dim(`    ${line}`, color));
     return lines.join('\n');
 }
-/**
- * An ordinary GFM markdown table, box-drawn with a bold header row through
- * `./components/table-grid.js`'s `drawTableGrid` — the SAME box-drawing and
- * width-negotiation routine the data-bound `::table` component
- * (`./components/table.ts`) draws with, so this engine has exactly one
- * table-drawing implementation rather than two. Rendered at the directive's
- * real available `width`, not a hardcoded budget: each cell's inline
- * markdown is rendered once at that width so its own links/emphasis/code
- * are preserved, and `drawTableGrid` then negotiates how much of `width`
- * each column actually gets.
- */
-function renderTable(tableEl, width, wctx) {
+function renderGfmTableString(tableEl, width, wctx) {
     const headerCells = [];
     const bodyRows = [];
     let sawHeader = false;
@@ -708,7 +638,7 @@ function renderTable(tableEl, width, wctx) {
                 continue;
             if (cell.tagName !== 'td' && cell.tagName !== 'th')
                 continue;
-            into.push(renderInlineChildren(cell.children, width, '', wctx));
+            into.push(renderInlineChildrenString(cell.children, width, '', wctx));
         }
     };
     for (const section of tableEl.children) {
@@ -733,51 +663,373 @@ function renderTable(tableEl, width, wctx) {
     }
     return drawTableGrid(headerCells.length > 0 ? headerCells : undefined, bodyRows, width, (text) => bold(text, wctx.color));
 }
-function renderBlock(node, width, indent, wctx) {
+function getPlainText(node) {
+    let text = '';
+    for (const child of node.children) {
+        if (child.type === 'text')
+            text += stripControlCharacters(child.value);
+        else if (child.type === 'element')
+            text += getPlainText(child);
+    }
+    return text;
+}
+function renderLink(node, width, indent, wctx) {
+    const hrefRaw = typeof node.properties?.href === 'string' ? node.properties.href : '';
+    const resolvedHref = resolveHrefAttribute(hrefRaw, wctx.resolveHref);
+    const text = renderInlineChildrenString(node.children, width, indent, wctx);
+    const sanitizedHref = stripControlCharacters(resolvedHref);
+    const canHyperlink = wctx.color !== 'none' &&
+        resolvedHref.trim() !== '' &&
+        isSafeUrl(resolvedHref) &&
+        sanitizeUrlText(resolvedHref) === resolvedHref;
+    if (canHyperlink)
+        return hyperlink(text, resolvedHref, wctx.color);
+    const plainText = text.replace(/\x1b\[[0-9;]*m|\x1b\]8;;[^\x07\x1b]*\x07/g, '');
+    if (plainText === sanitizedHref)
+        return sanitizedHref;
+    return `${text} (${sanitizedHref})`;
+}
+function renderImage(node, wctx) {
+    const altRaw = typeof node.properties?.alt === 'string' ? node.properties.alt : '';
+    const alt = stripControlCharacters(altRaw);
+    const srcRaw = typeof node.properties?.src === 'string' ? node.properties.src : '';
+    const resolvedSrc = resolveImageAttribute(srcRaw, wctx.resolveImageSrc);
+    const src = stripControlCharacters(resolvedSrc);
+    return `[${alt}] (${src})`;
+}
+function renderInlineNodeString(node, width, indent, wctx) {
     if (node.type === 'text')
         return stripControlCharacters(node.value);
     if (node.type !== 'element')
         return '';
-    if (node.tagName === DIRECTIVE_TAG)
-        return renderDirective(node, width, indent, wctx);
-    if (/^h[1-6]$/.test(node.tagName))
-        return renderHeading(node, width, indent, wctx);
-    if (node.tagName === 'p')
-        return renderParagraph(node, width, indent, wctx);
-    if (node.tagName === 'blockquote')
-        return renderBlockquote(node, width, indent, wctx);
-    if (node.tagName === 'ul' || node.tagName === 'ol')
-        return renderList(node, width, indent, wctx);
-    if (node.tagName === 'hr')
-        return dim(rule(width), wctx.color);
-    if (node.tagName === 'table')
-        return renderTable(node, width, wctx);
-    if (node.tagName === 'pre') {
-        const marker = renderScriptMarker(node, wctx.color);
-        if (marker !== undefined)
-            return marker;
-        return renderCodeBlock(node, wctx.color);
+    switch (node.tagName) {
+        case DIRECTIVE_TAG:
+            return renderDirectiveString(node, width, indent, wctx);
+        case 'strong':
+            return bold(renderInlineChildrenString(node.children, width, indent, wctx), wctx.color);
+        case 'em':
+            return italic(renderInlineChildrenString(node.children, width, indent, wctx), wctx.color);
+        case 'del':
+            return dim(`~${renderInlineChildrenString(node.children, width, indent, wctx)}~`, wctx.color);
+        case 'code': {
+            const inner = getPlainText(node);
+            return wctx.color === 'none'
+                ? dim(inner, wctx.color)
+                : inverse(inner, wctx.color);
+        }
+        case 'a':
+            return renderLink(node, width, indent, wctx);
+        case 'img':
+            return renderImage(node, wctx);
+        case 'br':
+            return '\n';
+        case 'input':
+            return '';
+        default:
+            return renderInlineChildrenString(node.children ?? [], width, indent, wctx);
     }
-    return wrap(renderInlineChildren(node.children ?? [], width, indent, wctx), width).join('\n');
 }
-function renderBlocks(nodes, width, indent, wctx) {
+function renderInlineChildrenString(children, width, indent, wctx) {
+    let result = '';
+    for (const child of children)
+        result += renderInlineNodeString(child, width, indent, wctx);
+    return result;
+}
+function renderBlocksString(nodes, width, indent, wctx) {
     const blocks = [];
     for (const node of nodes) {
-        const rendered = renderBlock(node, width, indent, wctx);
-        // Whitespace-only output is dropped, not just the empty string.
-        // remark-rehype puts a formatting `\n` TEXT node between every pair of
-        // block elements, and `stripControlCharacters` turns a line feed into a
-        // space rather than deleting it (see its doc comment: inline text reads
-        // better that way). Kept, each of those would become a block of its own
-        // holding one space, so every pair of real blocks would be separated by
-        // a blank line, a space line, and another blank line instead of a single
-        // blank line. Nothing a reader can see is ever lost by this test: a
-        // block whose entire rendered form is whitespace carries no content.
+        const rendered = renderBlockString(node, width, indent, wctx);
         if (rendered.trim() !== '')
             blocks.push(rendered);
     }
     return blocks.join('\n\n');
 }
+function renderDirectiveString(element, width, indent, wctx) {
+    const written = stringProperty(element, 'data-mk-name') ?? '';
+    const kind = stringProperty(element, 'data-mk-kind');
+    const rawAttributes = parseAttributes(stringProperty(element, 'data-mk-attrs'));
+    const isBlock = kind !== TEXT_DIRECTIVE_KIND;
+    if (written === VALUE_DIRECTIVE_NAME) {
+        const plainLabel = extractPlainText(element.children);
+        const resolved = resolveValue(wctx.scope, plainLabel);
+        return renderValueMarker(plainLabel.trim(), resolved, rawAttributes.format ?? undefined, rawAttributes.decimals ?? undefined, wctx.color, wctx.theme);
+    }
+    const { name, attributes: aliased } = resolveDirectiveAlias(wctx.registry, written, rawAttributes);
+    // A `row`/`tabs` reached through STRING mode (nested inside a self-drawing
+    // container's own body) falls back to a flattened rendering with no real
+    // flex layout / interactivity — see this file's top comment.
+    if (isBlock && name === ROW_NAME && hasRealComponent(wctx.registry, name)) {
+        return renderRowString(element, aliased, width, indent, wctx);
+    }
+    if (isBlock && name === TABS_NAME && hasRealComponent(wctx.registry, name)) {
+        const panels = extractTabPanels(element, width, indent, wctx);
+        return panels
+            .map((panel, index) => {
+            const heading = bold(`${panel.label}${index === 0 ? ACTIVE_MARKER : ''}`, wctx.color);
+            return panel.body ? `${heading}\n${panel.body}` : heading;
+        })
+            .join('\n\n');
+    }
+    const ownedAxis = registryLayoutAxis(wctx.registry, name);
+    const { attributes, resolved: layoutResolved } = resolveLayoutAttributes(aliased, isBlock ? ownedAxis : undefined);
+    const isLayoutScope = ownedAxis !== undefined && isBlock;
+    const isSelfLayout = isBlock && registrySelfLayout(wctx.registry, name);
+    const layoutForWidth = isLayoutScope || isSelfLayout ? layoutResolved : undefined;
+    // `card`/`callout`/`details` narrow their own body before drawing a frame
+    // or an indent around it. Each computes that inner width from ONLY its
+    // own attributes (never from the body), so the walk resolves it here,
+    // BEFORE building children, and builds children exactly ONCE at that
+    // final width — never at the outer width followed by a re-wrap. A
+    // re-wrap-afterward shipped as a real regression (post-phase-2 review):
+    // it corrupts anything self-drawing nested inside (a card's frame, a
+    // row's columns), since a word-based re-wrapper has no notion that a run
+    // of box-drawing characters is not prose. See `resolveCardInnerWidth`'s
+    // doc comment.
+    let childrenWidth = width;
+    if (isBlock && name === 'card') {
+        childrenWidth = resolveCardInnerWidth(attributes, layoutForWidth, width);
+    }
+    else if (isBlock && name === 'callout') {
+        childrenWidth = resolveCalloutInnerWidth(attributes, layoutForWidth, width);
+    }
+    else if (isBlock && name === DETAILS_NAME) {
+        childrenWidth = resolveDetailsInnerWidth(width);
+    }
+    const childrenText = renderDirectiveChildrenString(element.children, childrenWidth, indent, wctx);
+    const content = renderDirectiveContentString(name, kind, isBlock, attributes, childrenText, width, indent, wctx, layoutForWidth);
+    if (isBlock && layoutResolved && !isLayoutScope && !isSelfLayout) {
+        return applyLayout(content, layoutResolved, width);
+    }
+    return content;
+}
+function hasRealComponent(registry, name) {
+    return (Object.hasOwn(registry, name) &&
+        readRegistryComponent(registry[name]) != null);
+}
+// ---------------------------------------------------------------------------
+// ELEMENT MODE — real Ink elements, used for block sequencing and for
+// `row`/`tabs`/`details`. See this file's top comment.
+// ---------------------------------------------------------------------------
+/** Wraps `element` per `layout`'s resolved width/align, the JSX-based twin of `layout.ts`'s string-based `applyLayout`, for the three directives whose own output is a real Ink element rather than a string. */
+function applyLayoutElement(element, layout, width) {
+    if (!layout)
+        return element;
+    let target = width;
+    if (layout.width === 'narrow')
+        target = Math.max(20, Math.round(width / 2));
+    const align = layout.align;
+    const alignItems = align === 'center'
+        ? 'center'
+        : align === 'right'
+            ? 'flex-end'
+            : 'flex-start';
+    if (target === width && !align)
+        return element;
+    return (_jsx(Box, { width: width, flexDirection: "column", alignItems: alignItems, children: _jsx(Box, { width: target, flexDirection: "column", children: element }) }));
+}
+function invalidEnumMarkerElement(name, attributes, wctx) {
+    const invalidEnum = invalidEnumAttribute(name, attributes);
+    if (!invalidEnum)
+        return null;
+    reportDiagnostic(wctx.onDiagnostic, {
+        kind: 'invalid-attribute-value',
+        directive: name,
+        attribute: invalidEnum.attribute,
+        message: invalidAttributeValueTitle(name, invalidEnum.attribute, invalidEnum.value),
+    });
+    const label = invalidAttributeValueLabel(name, invalidEnum.attribute);
+    return styledText(dim(`[${label}]`, wctx.color));
+}
+function renderRowElement(element, attributes, width, indent, wctx) {
+    const cellNodes = element.children.filter((node) => !(node.type === 'text' && node.value.trim() === ''));
+    if (cellNodes.length === 0)
+        return null;
+    const layout = resolveRowLayout(attributes, cellNodes.length, width);
+    if (layout.stacked) {
+        const items = cellNodes
+            .map((node, index) => (_jsx(Box, { marginTop: index > 0 ? 1 : 0, flexDirection: "column", children: renderBlockElement(node, width, indent, wctx) }, index)))
+            .filter(Boolean);
+        return _jsx(Box, { flexDirection: "column", children: items });
+    }
+    const gutter = 1;
+    const rows = [];
+    for (let index = 0; index < cellNodes.length; index += layout.columnCount) {
+        const rowCells = cellNodes.slice(index, index + layout.columnCount);
+        rows.push(_jsx(Box, { flexDirection: "row", marginTop: index > 0 ? 1 : 0, children: rowCells.map((node, cellIndex) => (_jsx(Box, { width: layout.colWidth, marginRight: cellIndex < rowCells.length - 1 ? gutter : 0, flexDirection: "column", children: renderBlockElement(node, layout.colWidth, indent, wctx) }, cellIndex))) }, index));
+    }
+    return _jsx(Box, { flexDirection: "column", children: rows });
+}
+function renderTabsElement(element, width, indent, wctx) {
+    const panels = extractTabPanelsElement(element, width, indent, wctx);
+    if (panels.length === 0)
+        return null;
+    const focusId = wctx.interactive ? nextFocusId(wctx) : undefined;
+    if (focusId !== undefined) {
+        recordFocusable(wctx, {
+            kind: 'tabs',
+            label: panels[0]?.label ?? DEFAULT_TAB_LABEL,
+        });
+    }
+    return (_jsx(InteractiveTabs, { panels: panels, color: wctx.color, interactive: wctx.interactive, focusId: focusId }));
+}
+function extractTabPanelsElement(element, width, indent, wctx) {
+    const panels = [];
+    for (const node of element.children) {
+        if (node.type === 'text' && node.value.trim() === '')
+            continue;
+        if (node.type !== 'element')
+            continue;
+        let label = DEFAULT_TAB_LABEL;
+        let isTab = false;
+        if (node.tagName === DIRECTIVE_TAG) {
+            const written = stringProperty(node, 'data-mk-name') ?? '';
+            const attrs = parseAttributes(stringProperty(node, 'data-mk-attrs'));
+            const { name } = resolveDirectiveAlias(wctx.registry, written, attrs);
+            if (name === 'tab') {
+                label = attrs.label ?? DEFAULT_TAB_LABEL;
+                isTab = true;
+            }
+        }
+        // See `extractTabPanels`'s (string-mode) identical comment: rendering
+        // the whole `tab` directive here would ALSO invoke `tab.ts`'s own
+        // component, printing the label a second time.
+        const body = isTab
+            ? renderBlocksElement(node.children, width, indent, wctx)
+            : renderBlockElement(node, width, indent, wctx);
+        panels.push({ label, body });
+    }
+    return panels;
+}
+function renderDetailsElement(element, attributes, width, indent, wctx) {
+    const title = attributes.title ?? 'Details';
+    const open = Object.hasOwn(attributes, 'open');
+    const innerWidth = resolveDetailsInnerWidth(width);
+    const body = renderBlocksElement(element.children, innerWidth, indent, wctx);
+    const focusId = wctx.interactive ? nextFocusId(wctx) : undefined;
+    if (focusId !== undefined) {
+        recordFocusable(wctx, {
+            kind: 'details',
+            label: stripControlCharacters(title),
+        });
+    }
+    return (_jsx(InteractiveDetails, { title: stripControlCharacters(title), body: body, defaultOpen: open, color: wctx.color, interactive: wctx.interactive, focusId: focusId }));
+}
+/** Renders one directive as a real Ink element (block position only). Dispatches `row`/`tabs`/`details` to their real builders; every other directive falls back to the string engine, wrapped in one `<Text>`. */
+function renderDirectiveElement(element, width, indent, wctx) {
+    const written = stringProperty(element, 'data-mk-name') ?? '';
+    const kind = stringProperty(element, 'data-mk-kind');
+    const rawAttributes = parseAttributes(stringProperty(element, 'data-mk-attrs'));
+    const isBlock = kind !== TEXT_DIRECTIVE_KIND;
+    if (!isBlock) {
+        // A stray inline (text) directive at a block position (rare; hast
+        // structure keeps these inside a paragraph in practice) still renders,
+        // via the string engine.
+        return styledText(renderDirectiveString(element, width, indent, wctx));
+    }
+    const { name, attributes: aliased } = resolveDirectiveAlias(wctx.registry, written, rawAttributes);
+    const entry = Object.hasOwn(wctx.registry, name)
+        ? wctx.registry[name]
+        : undefined;
+    const formMismatch = entry ? isFormMismatch(entry, kind) : false;
+    if (!formMismatch &&
+        (name === ROW_NAME || name === TABS_NAME || name === DETAILS_NAME) &&
+        hasRealComponent(wctx.registry, name)) {
+        // None of `row`/`tabs`/`details` own a layout axis (`registryLayoutAxis`
+        // is undefined for all three in the standard registry), so, unlike a
+        // layout-wrapper scope, a `width=`/`align=` the author wrote still needs
+        // the GENERIC post-render treatment — `applyLayoutElement` below, the
+        // JSX-based twin of `layout.ts`'s string `applyLayout`.
+        const { attributes, resolved: layoutResolved } = resolveLayoutAttributes(aliased, undefined);
+        try {
+            let el = null;
+            if (name === ROW_NAME) {
+                el = renderRowElement(element, attributes, width, indent, wctx);
+            }
+            else if (name === TABS_NAME) {
+                el = renderTabsElement(element, width, indent, wctx);
+            }
+            else {
+                el = renderDetailsElement(element, attributes, width, indent, wctx);
+            }
+            if (!el)
+                return null;
+            const marker = invalidEnumMarkerElement(name, attributes, wctx);
+            const withMarker = marker ? (_jsxs(Box, { flexDirection: "column", children: [el, marker] })) : (el);
+            return applyLayoutElement(withMarker, layoutResolved, width);
+        }
+        catch {
+            return styledText(componentError(name || '(unnamed)', false, '', width, wctx.color));
+        }
+    }
+    return styledText(renderDirectiveString(element, width, indent, wctx));
+}
+/** Renders one block-level hast node as a real Ink element, or `null` for a node that carries no content (whitespace-only text). */
+function renderBlockElement(node, width, indent, wctx) {
+    if (node.type === 'text') {
+        return node.value.trim() === ''
+            ? null
+            : styledText(stripControlCharacters(node.value));
+    }
+    if (node.type !== 'element')
+        return null;
+    if (node.tagName === DIRECTIVE_TAG) {
+        return renderDirectiveElement(node, width, indent, wctx);
+    }
+    if (node.tagName === 'blockquote') {
+        const innerWidth = Math.max(1, width - 2);
+        const inner = renderBlocksElement(node.children, innerWidth, `${indent}│ `, wctx);
+        if (!inner)
+            return null;
+        return (_jsxs(Box, { width: width, children: [styledText(dim('│ ', wctx.color)), _jsx(Box, { flexDirection: "column", width: innerWidth, children: inner })] }));
+    }
+    if (node.tagName === 'ul' || node.tagName === 'ol') {
+        return renderListElement(node, width, indent, wctx);
+    }
+    const text = renderBlockString(node, width, indent, wctx);
+    if (text.trim() === '')
+        return null;
+    return styledText(text);
+}
+function renderListElement(el, width, indent, wctx) {
+    const ordered = el.tagName === 'ol';
+    const startRaw = el.properties?.start;
+    const start = ordered && typeof startRaw === 'number' ? startRaw : 1;
+    const items = el.children.filter((child) => child.type === 'element' && child.tagName === 'li');
+    if (items.length === 0)
+        return null;
+    const items$ = items.map((li, index) => {
+        const marker = ordered ? `${start + index}. ` : '- ';
+        const task = taskState(li);
+        const contentChildren = li.children.filter((child) => !(task && child.type === 'element' && child.tagName === 'input'));
+        const prefix = `${marker}${task ? (task.checked ? '[x] ' : '[ ] ') : ''}`;
+        const prefixWidth = measureWidth(prefix);
+        const bodyWidth = Math.max(1, width - prefixWidth);
+        const nestedLists = contentChildren.filter((child) => child.type === 'element' &&
+            (child.tagName === 'ul' || child.tagName === 'ol'));
+        const restChildren = contentChildren.filter((child) => !nestedLists.includes(child));
+        const bodyIsBlock = isBlockLevelChildren(restChildren);
+        const bodyText = bodyIsBlock
+            ? undefined
+            : wrapText(renderInlineChildrenString(restChildren, bodyWidth, indent, wctx), bodyWidth).join('\n');
+        return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [styledText(prefix), _jsx(Box, { width: bodyWidth, flexDirection: "column", children: bodyIsBlock
+                                ? renderBlocksElement(restChildren, bodyWidth, indent, wctx)
+                                : styledText(bodyText ?? '') })] }), nestedLists.length > 0 && (_jsx(Box, { marginLeft: 2, flexDirection: "column", children: nestedLists.map((nested, nestedIndex) => (_jsx(Fragment, { children: renderBlockElement(nested, Math.max(1, width - 2), `${indent}  `, wctx) }, nestedIndex))) }))] }, index));
+    });
+    return _jsx(Box, { flexDirection: "column", children: items$ });
+}
+/** Renders a sequence of block-level hast nodes as a real Ink element (a column `Box`), one blank row (`marginTop`) between consecutive non-empty blocks — the Ink-element twin of `renderBlocksString`'s `'\n\n'.join`. */
+function renderBlocksElement(nodes, width, indent, wctx) {
+    const elements = [];
+    for (const node of nodes) {
+        const el = renderBlockElement(node, width, indent, wctx);
+        if (el === null)
+            continue;
+        elements.push(_jsx(Box, { marginTop: elements.length > 0 ? 1 : 0, flexDirection: "column", children: el }, elements.length));
+    }
+    if (elements.length === 0)
+        return null;
+    return _jsx(_Fragment, { children: elements });
+}
 /** Collapses trailing blank lines to exactly one terminating `\n`, and leaves an empty document as `''`. */
 function finalizeOutput(text) {
     if (text === '')
@@ -789,34 +1041,43 @@ function renderFailureFallback(error, color) {
     const message = error instanceof Error ? error.message : String(error);
     return `${dim('failed to render document', color)}\n${stripControlCharacters(message)}\n`;
 }
-function renderRoot(root, registry, scope, color, theme, resolveImageSrc, resolveHref, onDiagnostic, width) {
-    const wctx = {
+function buildWalkContext(registry, scope, color, theme, interactive, resolveImageSrc, resolveHref, onDiagnostic) {
+    return {
         registry,
         scope,
         color,
         theme,
+        interactive,
         resolveImageSrc,
         resolveHref,
         onDiagnostic,
+        focusCounter: { current: 0 },
+        focusables: undefined,
     };
-    return finalizeOutput(renderBlocks(root.children, width, '', wctx));
 }
 /** The columns assumed when a caller supplies no `width` option. */
 const DEFAULT_WIDTH = 80;
+/** Builds the root Ink element for `root`, given every resolved render input. Exported for `buildMarkElement` (the live-viewer entry point, phase 3) as well as this module's own three string-producing entry points. */
+function buildRootElement(root, registry, scope, color, theme, interactive, resolveImageSrc, resolveHref, onDiagnostic, width) {
+    const wctx = buildWalkContext(registry, scope, color, theme, interactive, resolveImageSrc, resolveHref, onDiagnostic);
+    const body = renderBlocksElement(root.children, width, '', wctx);
+    return (_jsx(Box, { width: width, flexDirection: "column", children: body ?? _jsx(Text, { children: " " }) }));
+}
+async function renderRootToString(root, registry, scope, color, theme, interactive, resolveImageSrc, resolveHref, onDiagnostic, width) {
+    const element = buildRootElement(root, registry, scope, color, theme, interactive, resolveImageSrc, resolveHref, onDiagnostic, width);
+    const raw = await renderInkToString(element, width);
+    return finalizeOutput(raw);
+}
 /**
  * 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'`
@@ -824,14 +1085,11 @@ const DEFAULT_WIDTH = 80;
  * 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 function renderMarkToAnsi(text, registry = defaultAnsiRegistry, store, vault, options) {
+export async function renderMarkToAnsi(text, registry = defaultAnsiRegistry, store, vault, options) {
     const color = resolveColorOption(options?.color);
     try {
-        return renderRoot(toHast(text), registry, { store: options?.store ?? store, vault: options?.vault ?? vault }, color, options?.theme ?? defaultAnsiTheme, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic, options?.width ?? DEFAULT_WIDTH);
+        return await renderRootToString(toHast(text), registry, { store: options?.store ?? store, vault: options?.vault ?? vault }, color, options?.theme ?? defaultAnsiTheme, options?.interactive ?? false, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic, options?.width ?? DEFAULT_WIDTH);
     }
     catch (error) {
         return renderFailureFallback(error, color);
@@ -839,21 +1097,20 @@ export function renderMarkToAnsi(text, registry = defaultAnsiRegistry, store, va
 }
 /**
  * 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 function renderMarkNodeToAnsi(node, registry = defaultAnsiRegistry, store, vault, options) {
+export async function renderMarkNodeToAnsi(node, registry = defaultAnsiRegistry, store, vault, options) {
     const color = resolveColorOption(options?.color);
     try {
-        return renderRoot(nodeOrRootToHast(node), registry, { store: options?.store ?? store, vault: options?.vault ?? vault }, color, options?.theme ?? defaultAnsiTheme, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic, options?.width ?? DEFAULT_WIDTH);
+        return await renderRootToString(nodeOrRootToHast(node), registry, { store: options?.store ?? store, vault: options?.vault ?? vault }, color, options?.theme ?? defaultAnsiTheme, options?.interactive ?? false, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic, options?.width ?? DEFAULT_WIDTH);
     }
     catch (error) {
         return renderFailureFallback(error, color);
     }
 }
-/** Whether `root` is exactly one paragraph holding exactly one text directive (`:name[...]`) and nothing else. Mirrors `@markii/html`'s identical `loneInlineDirective`. */
+/** Whether `root` is exactly one paragraph holding exactly one text directive (`:name[...]`) and nothing else. */
 function loneInlineDirective(root) {
     if (root.children.length !== 1)
         return undefined;
@@ -869,17 +1126,15 @@ function loneInlineDirective(root) {
 }
 /**
  * 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 function renderMarkInlineToAnsi(text, registry = defaultAnsiRegistry, store, vault, options) {
+export async function renderMarkInlineToAnsi(text, registry = defaultAnsiRegistry, store, vault, options) {
     try {
         const root = parse(text);
         const lone = loneInlineDirective(root);
         if (lone) {
-            return renderMarkNodeToAnsi(lone, registry, store, vault, options);
+            return await renderMarkNodeToAnsi(lone, registry, store, vault, options);
         }
     }
     catch {
@@ -887,3 +1142,51 @@ export function renderMarkInlineToAnsi(text, registry = defaultAnsiRegistry, sto
     }
     return renderMarkToAnsi(text, registry, store, vault, options);
 }
+/**
+ * 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 function buildMarkElement(document, registry = defaultAnsiRegistry, options) {
+    const color = resolveColorOption(options?.color);
+    const theme = options?.theme ?? defaultAnsiTheme;
+    const scope = { store: options?.store, vault: options?.vault };
+    const width = options?.width ?? DEFAULT_WIDTH;
+    const interactive = options?.interactive ?? true;
+    let root;
+    try {
+        root =
+            typeof document === 'string'
+                ? toHast(document)
+                : nodeOrRootToHast(document);
+    }
+    catch {
+        root = { type: 'root', children: [] };
+    }
+    const content = buildRootElement(root, registry, scope, color, theme, interactive, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic, width);
+    if (!interactive)
+        return content;
+    // The walk above already assigned every focusable component's `focusId`
+    // (`WalkContext.focusCounter`) and, incidentally, discarded each one's
+    // descriptor (`WalkContext.focusables` is left `undefined` on the real
+    // render, since nothing there needs it). Rebuilding once more, this time
+    // collecting descriptors, is wasteful only in the sense that the tree is
+    // constructed twice; simpler and safer than threading mutable state out
+    // of a pure element-builder, and this entry point is called once per
+    // mount/resize, not per keystroke.
+    const counter = { current: 0 };
+    const focusables = [];
+    const countingWctx = buildWalkContext(registry, scope, color, theme, true, options?.resolveImageSrc, options?.resolveHref, 
+    // No `onDiagnostic`: the real walk above already reported every notice
+    // this document produces, and this second walk exists only to collect
+    // focus descriptors. Passing the callback here would report each notice
+    // twice on every mount and again on every resize.
+    undefined);
+    countingWctx.focusCounter = counter;
+    countingWctx.focusables = focusables;
+    renderBlocksElement(root.children, width, '', countingWctx);
+    return (_jsx(InteractiveRoot, { focusables: focusables, onExit: options?.onExit, color: color, theme: theme, children: content }));
+}