@markii/ansi 0.15.0 → 0.17.0-next.0

package/dist/render.js

@@ -1,40 +1,71 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment, isValidElement } 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 { columnsBlock, frameBlock, frameTopLine, inkBorderStyle, isTextAlign, measureWidth, padText, ruleLine, wrapText, } from './text-grid.js';
+import { drawTableGrid } from './components/table-grid.js';
+import { ROW_GUTTER, resolveRowLayout, } from './components/row.js';
+import { CARD_FRAME_OVERHEAD, resolveCardBoxWidth, resolveCardInnerWidth, } from './components/card.js';
+import { Callout, CALLOUT_TOKENS, headerTextFor, resolveCalloutBoxWidth, resolveCalloutInnerWidth, resolveCalloutType, } 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';
 import { resolveScopedPath } from './resolve.js';
-import { dataStateSuffix, emptyInlineTitle, failureToken, invalidAttributeValueLabel, invalidAttributeValueTitle, } from './failure-presentation.js';
-import { formatValue, getContract, reportDiagnostic, } from '@markii/stdlib';
+import { dataStateSuffix, emptyInlineTitle, failureToken, formMismatchTitle, NO_ENGINE_VIEW_LABEL, noEngineViewTitle, invalidAttributeValueLabel, invalidAttributeValueTitle, unsafeImageSrcLabel, unsafeImageSrcTitle, } from './failure-presentation.js';
+import { createUnavailableComponentLookup, 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, renderInkToStringSync } from './ink-string.js';
+import { InteractiveRoot } from './interactive.js';
+import { glyphsFor } from './glyphs.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 a self-drawing component's body uses when it sits
+ *   inside a string-drawn ancestor (a standalone `cell`, a GFM table cell),
+ *   and what a non-left `text=` body uses in the render-once path, because
+ *   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 block directives that genuinely need Ink's real layout or
+ *   real component state: `row` (a flex `Box` row), `tabs` and `details`
+ *   (real React state, for `ctx.interactive`'s keyboard-driven switching/
+ *   toggling), and the containers `card`, `callout` and `figure`, whose
+ *   bodies are Ink subtrees so those can sit inside them. A `row`/`tabs`/
+ *   `details` reached through a STRING-mode ancestor (a standalone `cell`,
+ *   or a GFM table cell) falls back to a flattened STRING rendering of
+ *   itself with no interactivity, an accepted boundary: a body drawn as a
+ *   string cannot hold live state. See `renderRowString` and
+ *   `renderDirectiveString` 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 +77,27 @@ 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 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';
+/**
+ * `card` and `figure` join this list (batch 11's Ink-frames phase): both are
+ * containers whose body previously only ever reached STRING mode, so a
+ * `tabs`/`details` nested inside one could never become focusable. `card`
+ * draws its frame with an Ink `Box` border (`renderCardElement`); `figure`
+ * never drew a frame at all (it is a caption + optional image line), so it
+ * gains no border, only ELEMENT-mode children.
+ *
+ * `callout` joins them too. Its colored bar is a one-column left border
+ * on an Ink `Box` whose border glyph is the already-styled bar string: Ink
+ * repeats that glyph down the body's whole height, whatever the height turns
+ * out to be, and the color still comes from this engine's own SGR helpers,
+ * never an Ink color prop.
+ */
+const CARD_NAME = 'card';
+const CALLOUT_NAME = 'callout';
+const FIGURE_NAME = 'figure';
 /** 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 +126,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];
@@ -134,6 +210,8 @@ function isRegisteredInline(entry) {
 /** The fallback label line, worded for the reason and the form the directive was written in. Plain text (no escapes). */
 function fallbackLabel(name, inline, reason) {
     const code = `\`${stripControlCharacters(name)}\``;
+    if (reason === 'no-engine-view')
+        return `${NO_ENGINE_VIEW_LABEL} ${code}`;
     if (reason === 'form-mismatch') {
         return inline
             ? `block component ${code} written inline`
@@ -141,30 +219,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) {
+function unknownDirective(name, inline, childrenText, reason, width, color, glyphs) {
     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 +231,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, glyphs }), 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) {
+function componentError(name, inline, childrenText, width, color, glyphs) {
     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, glyphs }), 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 +263,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 +287,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 +305,21 @@ 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,
+        glyphs: wctx.glyphs,
+        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,52 +333,86 @@ 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;
         ctx.dataError = binding.dataError;
         ctx.dataFailureKind = binding.dataFailureKind;
+        ctx.dataSuffix = dataStateSuffix(binding.dataStatus, binding.dataFailureKind);
     }
     if (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);
+        const missingView = wctx.unavailable?.(name);
+        if (missingView !== undefined) {
+            reportDiagnostic(wctx.onDiagnostic, {
+                kind: 'no-engine-view',
+                directive: name,
+                message: noEngineViewTitle(name, missingView.pack, missingView.engines),
+            });
+            return unknownDirective(name, inline, safeChildrenText(childrenText), 'no-engine-view', width, wctx.color, wctx.glyphs);
+        }
+        return unknownDirective(name || '(unnamed)', inline, safeChildrenText(childrenText), 'unregistered', width, wctx.color, wctx.glyphs);
     }
     if (isFormMismatch(entry, kind)) {
-        return unknownDirective(name || '(unnamed)', inline, safeChildrenText(children), 'form-mismatch', width, wctx.color);
+        reportDiagnostic(wctx.onDiagnostic, {
+            kind: 'form-mismatch',
+            directive: name,
+            message: formMismatchTitle(name),
+        });
+        return unknownDirective(name || '(unnamed)', inline, safeChildrenText(childrenText), 'form-mismatch', width, wctx.color, wctx.glyphs);
     }
     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
+                : isValidElement(result)
+                    ? renderInkToStringSync(result, width)
+                    : 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, wctx.glyphs);
+    }
     const markerSeparator = inline ? ' ' : '\n';
     const invalidEnum = invalidEnumAttribute(name, binding.attributes);
     if (invalidEnum) {
@@ -345,221 +425,121 @@ 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;
-}
-/**
- * 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;
+    return renderInlineChildrenString(children, width, indent, wctx);
 }
-/** 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);
+        gridRows.push(columnsBlock(rowCells, rowCells.map(() => layout.colWidth), ROW_GUTTER));
     }
-    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;
+    return panels;
 }
-/**
- * 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})`;
-}
-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.glyphs.quoteBar}`, wctx);
+        const prefix = dim(wctx.glyphs.quoteBar, 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.glyphs.rule), wctx.color);
+    }
+    if (node.tagName === 'table')
+        return renderGfmTableString(node, width, wctx);
+    if (node.tagName === 'pre') {
+        const marker = renderScriptMarker(node, wctx.color, wctx.glyphs);
+        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 +547,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 +566,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 +578,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 +586,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 +594,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,15 +625,7 @@ 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) {
+function renderScriptMarker(node, color, glyphs) {
     try {
         const codeNode = findChildElement(node, 'code');
         const meta = codeNode
@@ -669,7 +639,9 @@ function renderScriptMarker(node, color) {
             return undefined;
         const src = attrs.src || undefined;
         const detail = src ?? getLanguage(codeNode);
-        const summary = detail ? `⚙ ${name} · ${detail}` : `⚙ ${name}`;
+        const summary = detail
+            ? `${glyphs.script} ${name} ${glyphs.scriptSeparator} ${detail}`
+            : `${glyphs.script} ${name}`;
         return dim(summary, color);
     }
     catch {
@@ -687,18 +659,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 +669,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) {
@@ -731,53 +692,658 @@ function renderTable(tableEl, width, wctx) {
             }
         }
     }
-    return drawTableGrid(headerCells.length > 0 ? headerCells : undefined, bodyRows, width, (text) => bold(text, wctx.color));
+    return drawTableGrid(headerCells.length > 0 ? headerCells : undefined, bodyRows, width, wctx.glyphs, (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, wctx.glyphs);
+    }
+    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) {
+    if (!Object.hasOwn(registry, name))
+        return false;
+    const component = readRegistryComponent(registry[name]);
+    if (component == null)
+        return false;
+    // The element form of a callout replaces the standard component's string
+    // drawing. A host that registered its own `callout` keeps its own output,
+    // so only the standard one takes the element path.
+    if (name === CALLOUT_NAME)
+        return component === Callout;
+    return true;
+}
+// ---------------------------------------------------------------------------
+// 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));
+}
+/**
+ * Whether `node` is a block directive whose element form can hold real
+ * state or focus (`row`, `tabs`, `details`, `card`, `callout`, `figure`).
+ * Used only to decide which children of a justified body stay Ink subtrees.
+ */
+function isInteractiveCapableBlock(node, wctx) {
+    if (node.type !== 'element' || node.tagName !== DIRECTIVE_TAG)
+        return false;
+    if (stringProperty(node, 'data-mk-kind') === TEXT_DIRECTIVE_KIND) {
+        return false;
+    }
+    const { name } = resolveDirectiveAlias(wctx.registry, stringProperty(node, 'data-mk-name') ?? '', parseAttributes(stringProperty(node, 'data-mk-attrs')));
+    return ((name === ROW_NAME ||
+        name === TABS_NAME ||
+        name === DETAILS_NAME ||
+        name === CARD_NAME ||
+        name === CALLOUT_NAME ||
+        name === FIGURE_NAME) &&
+        hasRealComponent(wctx.registry, name));
+}
+/**
+ * The body of a self-drawing container (`card`, `callout`, a `row` cell)
+ * as one Ink element, honoring its `text=` alignment.
+ *
+ * `left` keeps the whole body a real Ink subtree. `center`/`right` justify
+ * each block with `text-grid.ts`'s `padText`, the one justification
+ * implementation, which needs a string. In the render-once path that means
+ * the whole body is one flattened, justified string, exactly as the
+ * pre-Ink engine drew it (the committed fixtures depend on it). In the
+ * live viewer a block that can hold focus (a `tabs`, a `details`, a nested
+ * container) stays an Ink subtree and is placed at the left of the body,
+ * because a subtree cannot be justified line by line; every other block is
+ * still justified. So the live view trades alignment of those blocks'
+ * headings for being usable.
+ */
+function renderAlignedBodyElement(nodes, width, indent, wctx, align) {
+    if (align === 'left')
+        return renderBlocksElement(nodes, width, indent, wctx);
+    const justify = (text) => text
+        .split('\n')
+        .map((line) => padText(line, width, align))
+        .join('\n');
+    if (!wctx.interactive) {
+        const text = renderDirectiveChildrenString(nodes, width, indent, wctx);
+        return text === '' ? null : styledText(justify(text));
+    }
+    const elements = [];
+    for (const node of nodes) {
+        let el;
+        if (isInteractiveCapableBlock(node, wctx)) {
+            el = renderBlockElement(node, width, indent, wctx);
+        }
+        else {
+            const text = renderBlockString(node, width, indent, wctx);
+            el = text.trim() === '' ? null : styledText(justify(text));
+        }
+        if (el === null)
+            continue;
+        elements.push(_jsx(Box, { marginTop: elements.length > 0 ? 1 : 0, flexDirection: "column", children: el }, elements.length));
+    }
+    return elements.length === 0 ? null : _jsx(_Fragment, { children: elements });
+}
+/**
+ * Renders one `row` cell at `cellWidth`. `text=left` (the default) keeps
+ * the cell a real Ink element tree (`renderBlockElement`), so anything
+ * focusable inside it stays focusable. `text=center`/`text=right` instead
+ * falls back to a flattened, pre-justified STRING — batch 11's justification
+ * rule: exactly ONE implementation, `text-grid.ts`'s `padText`, never a
+ * second Ink-`alignItems`-based mechanism. Before this batch, `row`'s
+ * ELEMENT-mode grid silently ignored `text=` altogether (only the STRING-
+ * mode fallback, reached when a `row` is nested inside a self-drawing
+ * container, honored it); this closes that gap using the SAME helper the
+ * STRING mode already uses, rather than inventing a second mechanism.
+ */
+function renderRowCellElement(node, cellWidth, indent, wctx, align) {
+    if (align === 'left')
+        return renderBlockElement(node, cellWidth, indent, wctx);
+    if (wctx.interactive) {
+        return renderAlignedBodyElement([node], cellWidth, indent, wctx, align);
+    }
+    const text = renderBlockString(node, cellWidth, indent, wctx);
+    if (text.trim() === '')
+        return null;
+    const justified = text
+        .split('\n')
+        .map((line) => padText(line, cellWidth, align))
+        .join('\n');
+    return styledText(justified);
+}
+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: renderRowCellElement(node, width, indent, wctx, layout.align) }, index)))
+            .filter(Boolean);
+        return _jsx(Box, { flexDirection: "column", children: items });
+    }
+    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 ? ROW_GUTTER : 0, flexDirection: "column", children: renderRowCellElement(node, layout.colWidth, indent, wctx, layout.align) }, 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, glyphs: wctx.glyphs, 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, glyphs: wctx.glyphs, interactive: wctx.interactive, focusId: focusId }));
+}
+/**
+ * Places a self-sized element (a `card`'s own bordered `Box`, already drawn
+ * at `boxWidth`) within the full `width` per the resolved `align` preset —
+ * the ELEMENT-mode twin of `layout.ts`'s string-based `selfLayoutAlign`,
+ * kept separate from `applyLayoutElement` below because a self-drawing
+ * component (unlike `row`/`tabs`/`details`) has ALREADY resolved its own
+ * width (including `fit`, which `applyLayoutElement` does not implement)
+ * and must never be narrowed a second time.
+ */
+function selfLayoutAlignElement(element, boxWidth, layout, width) {
+    if (!layout?.align)
+        return element;
+    const alignItems = layout.align === 'center'
+        ? 'center'
+        : layout.align === 'right'
+            ? 'flex-end'
+            : 'flex-start';
+    return (_jsx(Box, { width: width, flexDirection: "column", alignItems: alignItems, children: _jsx(Box, { width: boxWidth, flexDirection: "column", children: element }) }));
+}
+/**
+ * `:::card{title="..." text=left|center|right} ... :::` as a real Ink
+ * element (batch 11: card moves off `frameBlock`'s hand-drawn string frame
+ * onto Ink's own `Box` border, so a `tabs`/`details` nested in its body can
+ * become a real focusable — this function's `body` is built through
+ * `renderBlocksElement`, ELEMENT mode, whenever that is possible).
+ *
+ * Ink's border has no primitive for weaving text into an edge, so a titled
+ * card still draws its OWN top line by hand (`frameTopLine`, the exact same
+ * string `frameBlock` would have produced) and tells Ink not to draw a top
+ * border at all; an untitled card lets Ink draw all four sides, which
+ * `frameGlyphs`'s character set makes byte-identical to `frameBlock`'s own
+ * untitled output (proven against the committed fixtures).
+ *
+ * `text=center`/`text=right` (batch 11's justification rule: exactly ONE
+ * implementation, `text-grid.ts`'s `padText`, pre-justifying a STRING before
+ * Ink ever sees it, never a second Ink-`alignItems`-based mechanism) falls
+ * back to building the body as one flattened, pre-justified string, exactly
+ * like the pre-Ink engine did — an accepted, documented trade: a `tabs`/
+ * `details` nested inside a CENTERED or RIGHT-aligned card body is not
+ * focusable, the same "self-drawing container's own body is a fixed string"
+ * boundary this engine already draws elsewhere (this file's top comment).
+ * `text=left` (the default, and by far the common case) keeps full nested
+ * interactivity.
+ */
+function renderCardElement(element, attributes, width, indent, wctx, layout) {
+    const title = attributes.title ?? null;
+    const titleText = title ? stripControlCharacters(title) : undefined;
+    const rawTextAlign = attributes.text;
+    const align = rawTextAlign && isTextAlign(rawTextAlign) ? rawTextAlign : 'left';
+    const boxWidth = resolveCardBoxWidth({ ...attributes, title: titleText ?? null }, layout, width);
+    const innerWidth = Math.max(1, boxWidth - CARD_FRAME_OVERHEAD);
+    const bodyElement = renderAlignedBodyElement(element.children, innerWidth, indent, wctx, align);
+    const bordered = (_jsx(Box, { width: boxWidth, flexDirection: "column", borderStyle: inkBorderStyle('solid', wctx.glyphs), borderTop: !titleText, children: bodyElement ?? _jsx(Text, { children: " " }) }));
+    const framed = titleText ? (_jsxs(Box, { flexDirection: "column", width: boxWidth, children: [styledText(frameTopLine({
+                style: 'solid',
+                title: titleText,
+                width: boxWidth,
+                glyphs: wctx.glyphs,
+            })), bordered] })) : (bordered);
+    const positioned = selfLayoutAlignElement(framed, boxWidth, layout, width);
+    // The invalid-`text=`-value marker is appended AFTER alignment, on its
+    // own unindented line, exactly like the STRING engine's own
+    // `renderDirectiveContentString` (the marker is never itself aligned or
+    // framed) — see `invalidEnumMarkerElement`'s call sites elsewhere in this
+    // file for the same shape.
+    const marker = invalidEnumMarkerElement(CARD_NAME, attributes, wctx);
+    if (!marker)
+        return positioned;
+    return (_jsxs(Box, { flexDirection: "column", children: [positioned, marker] }));
+}
+/**
+ * `:::callout{type=info|warning|danger title="..." text=left|center|right}`
+ * as a real Ink element, so a `tabs`/`details` in its body can be focused.
+ *
+ * The colored bar is the left border of an Ink `Box`, one column wide, whose
+ * border glyph is the bar already styled by this engine's own SGR helpers
+ * (never an Ink color prop). Ink repeats that glyph down the full height of
+ * the body, so the bar needs no knowledge of the body's line count. The
+ * bar glyph's trailing space becomes the box's left padding, so the layout
+ * matches the string form column for column.
+ *
+ * The icon/label line and the title line are justified per `text=` with
+ * `padText`; the body goes through `renderAlignedBodyElement`.
+ */
+function renderCalloutElement(element, attributes, width, indent, wctx, layout) {
+    const type = resolveCalloutType(attributes);
+    const token = CALLOUT_TOKENS[type];
+    const titleText = attributes.title
+        ? stripControlCharacters(attributes.title)
+        : undefined;
+    const rawTextAlign = attributes.text;
+    const align = rawTextAlign && isTextAlign(rawTextAlign) ? rawTextAlign : 'left';
+    const { glyphs, color, theme } = wctx;
+    const barWidth = measureWidth(glyphs.calloutBar);
+    const boxWidth = resolveCalloutBoxWidth(type, titleText ?? null, layout, width, glyphs);
+    const innerWidth = Math.max(1, boxWidth - barWidth);
+    const placeLine = (line) => align === 'left' ? line : padText(line, innerWidth, align);
+    const barGlyph = glyphs.calloutBar.trimEnd();
+    const border = {
+        topLeft: '',
+        top: '',
+        topRight: '',
+        right: '',
+        bottomRight: '',
+        bottom: '',
+        bottomLeft: '',
+        left: style(barGlyph, token, theme, color),
+    };
+    const body = renderAlignedBodyElement(element.children, innerWidth, indent, wctx, align);
+    const box = (_jsxs(Box, { width: boxWidth, flexDirection: "column", borderStyle: border, borderTop: false, borderRight: false, borderBottom: false, paddingLeft: barWidth - measureWidth(barGlyph), children: [styledText(placeLine(style(headerTextFor(type, glyphs), token, theme, color))), titleText ? styledText(placeLine(bold(titleText, color))) : null, body] }));
+    const positioned = selfLayoutAlignElement(box, boxWidth, layout, width);
+    const marker = invalidEnumMarkerElement(CALLOUT_NAME, attributes, wctx);
+    if (!marker)
+        return positioned;
+    return (_jsxs(Box, { flexDirection: "column", children: [positioned, marker] }));
+}
+/**
+ * `:::figure{src="..." alt="..."} caption markdown :::` as a real Ink
+ * element (batch 11: `figure` never drew a hand-drawn frame — it is a plain
+ * dim alt/src line followed by its caption body — but its body still only
+ * ever reached STRING mode before this change, so a `tabs`/`details` in its
+ * caption could never become focusable. `body` here is built through
+ * `renderBlocksElement`, ELEMENT mode, exactly mirroring `figure.ts`'s own
+ * STRING-mode component line for line: the header lines (alt/src/refused)
+ * stack directly above the caption with NO blank row between them, matching
+ * `Figure`'s own `lines.join('\n')` (a single line break, not a blank
+ * paragraph gap) — `Box`'s default zero margin between column children
+ * reproduces that exactly.
+ */
+const FIGURE_DIRECTIVE_NAME = 'figure';
+function renderFigureElement(element, attributes, width, indent, wctx) {
+    const rawSrc = attributes.src ?? null;
+    const alt = attributes.alt ?? '';
+    const refused = Boolean(rawSrc) && !isSafeUrl(rawSrc);
+    const safeSrc = rawSrc && !refused ? rawSrc : null;
+    const src = safeSrc
+        ? stripControlCharacters(resolveImageAttribute(safeSrc, wctx.resolveImageSrc))
+        : null;
+    const headerLines = [];
+    if (rawSrc) {
+        if (alt) {
+            headerLines.push(dim(`alt: ${stripControlCharacters(alt)}`, wctx.color));
+        }
+        if (refused) {
+            reportDiagnostic(wctx.onDiagnostic, {
+                kind: 'unsafe-image-src',
+                directive: FIGURE_DIRECTIVE_NAME,
+                message: unsafeImageSrcTitle(FIGURE_DIRECTIVE_NAME),
+            });
+            headerLines.push(dim(`[${unsafeImageSrcLabel(FIGURE_DIRECTIVE_NAME)}]`, wctx.color));
+        }
+        else if (src) {
+            headerLines.push(dim(src, wctx.color));
+        }
+    }
+    const headerElement = headerLines.length > 0 ? styledText(headerLines.join('\n')) : null;
+    const body = renderBlocksElement(element.children, width, indent, wctx);
+    if (!headerElement && !body)
+        return null;
+    return (_jsxs(Box, { flexDirection: "column", children: [headerElement, body] }));
+}
+/** Renders one directive as a real Ink element (block position only). Dispatches `row`/`tabs`/`details`/`card`/`figure` 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 ||
+            name === CARD_NAME ||
+            name === CALLOUT_NAME ||
+            name === FIGURE_NAME) &&
+        hasRealComponent(wctx.registry, name)) {
+        // None of these six own a layout axis (`registryLayoutAxis` is
+        // undefined for all of them in the standard registry), so, unlike a
+        // layout-wrapper scope, a `width=`/`align=` the author wrote still needs
+        // resolving here rather than being handled by the directive's own name.
+        const { attributes, resolved: layoutResolved } = resolveLayoutAttributes(aliased, undefined);
+        try {
+            if (name === CARD_NAME) {
+                // `card` resolves its OWN width (including `fit`, which the generic
+                // `applyLayoutElement` below does not implement) and aligns itself
+                // with `selfLayoutAlignElement` — see `renderCardElement`'s doc
+                // comment. It never goes through the generic post-render wrap.
+                return renderCardElement(element, attributes, width, indent, wctx, layoutResolved);
+            }
+            if (name === CALLOUT_NAME && !wctx.interactive && layoutResolved?.align) {
+                // The string form places each line of a callout on its own, so
+                // `align=` leaves the bars ragged; the element form places the block
+                // as a unit. The render-once output stays the string form's, byte for
+                // byte, and only the live viewer places the callout as a unit.
+                return styledText(renderDirectiveString(element, width, indent, wctx));
+            }
+            if (name === CALLOUT_NAME) {
+                // Self-sized and self-aligned like `card`: see `renderCalloutElement`.
+                return renderCalloutElement(element, attributes, width, indent, wctx, layoutResolved);
+            }
+            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 if (name === DETAILS_NAME) {
+                el = renderDetailsElement(element, attributes, width, indent, wctx);
+            }
+            else {
+                el = renderFigureElement(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, wctx.glyphs));
+        }
+    }
+    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.glyphs.quoteBar}`, wctx);
+        if (!inner)
+            return null;
+        return (_jsxs(Box, { width: width, children: [styledText(dim(wctx.glyphs.quoteBar, 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 +1355,45 @@ 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, glyphs, interactive, resolveImageSrc, resolveHref, onDiagnostic, unavailable) {
+    return {
         registry,
         scope,
         color,
         theme,
+        glyphs,
+        interactive,
         resolveImageSrc,
         resolveHref,
         onDiagnostic,
+        unavailable,
+        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, glyphs, interactive, resolveImageSrc, resolveHref, onDiagnostic, unavailable, width) {
+    const wctx = buildWalkContext(registry, scope, color, theme, glyphs, interactive, resolveImageSrc, resolveHref, onDiagnostic, unavailable);
+    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, glyphs, interactive, resolveImageSrc, resolveHref, onDiagnostic, unavailable, width) {
+    const element = buildRootElement(root, registry, scope, color, theme, glyphs, interactive, resolveImageSrc, resolveHref, onDiagnostic, unavailable, 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 +1401,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, glyphsFor(options?.box), options?.interactive ?? false, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic, createUnavailableComponentLookup(options?.unavailableComponents), options?.width ?? DEFAULT_WIDTH);
     }
     catch (error) {
         return renderFailureFallback(error, color);
@@ -839,21 +1413,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, glyphsFor(options?.box), options?.interactive ?? false, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic, createUnavailableComponentLookup(options?.unavailableComponents), 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 +1442,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 +1458,53 @@ 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 glyphs = glyphsFor(options?.box);
+    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 unavailable = createUnavailableComponentLookup(options?.unavailableComponents);
+    const content = buildRootElement(root, registry, scope, color, theme, glyphs, interactive, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic, unavailable, 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, glyphs, 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, unavailable);
+    countingWctx.focusCounter = counter;
+    countingWctx.focusables = focusables;
+    renderBlocksElement(root.children, width, '', countingWctx);
+    return (_jsx(InteractiveRoot, { focusables: focusables, onExit: options?.onExit, color: color, theme: theme, keyLegend: glyphs.keyLegend, viewportRows: options?.viewportRows, width: width, children: content }));
+}