@markii/ansi 0.16.0 → 0.17.0-next.0

package/dist/render.js

@@ -1,27 +1,28 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Fragment } from 'react';
+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, carrySgrAcrossLines, dim, hyperlink, inverse, italic, resolveColorOption, underline, } from './ansi.js';
 import { style } from './style.js';
 import { defaultAnsiTheme } from './theme.js';
-import { frameBlock, measureWidth, padText, ruleLine, wrapText, } from './text-grid.js';
+import { columnsBlock, frameBlock, frameTopLine, inkBorderStyle, isTextAlign, 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 { 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 { renderInkToString } from './ink-string.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';
 /**
@@ -40,30 +41,26 @@ import { InteractiveDetails } from './components/details.js';
  *
  * - 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
+ *   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 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.
+ *   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 for a NON-interactive render at
  * all: `@markii/stdlib`'s `INTERACTIVE_ATTRIBUTE` marks an element a HOST
@@ -80,10 +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 three block directive names given real Ink layout/state (see this file's top comment). */
+/** 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',
@@ -196,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`
@@ -204,7 +220,7 @@ function fallbackLabel(name, inline, reason) {
     return `unknown component ${code}`;
 }
 /** 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);
     if (inline) {
         return childrenText === ''
@@ -219,17 +235,17 @@ function unknownDirective(name, inline, childrenText, reason, width, color) {
             .join('\n')
         : '';
     const body = wrappedChildren ? `${label}\n\n${wrappedChildren}` : label;
-    return dim(frameBlock(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`;
     if (inline) {
         return childrenText === ''
             ? dim(label, color)
             : `${dim(`${label}:`, color)} ${childrenText}`;
     }
-    return dim(frameBlock(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. */
 function resolveDataAttribute(attributes, scope) {
@@ -296,6 +312,7 @@ function buildComponentContext(width, indent, wctx, binding, layout, focusId) {
         indent,
         color,
         theme,
+        glyphs: wctx.glyphs,
         interactive: wctx.interactive,
         style: (text, token) => style(text, token, theme, color),
         bold: (text) => bold(text, color),
@@ -323,6 +340,7 @@ function buildComponentContext(width, indent, wctx, binding, layout, focusId) {
         ctx.dataStatus = binding.dataStatus;
         ctx.dataError = binding.dataError;
         ctx.dataFailureKind = binding.dataFailureKind;
+        ctx.dataSuffix = dataStateSuffix(binding.dataStatus, binding.dataFailureKind);
     }
     if (layout)
         ctx.layout = layout;
@@ -357,10 +375,24 @@ function renderDirectiveContentString(name, kind, isBlock, attributes, childrenT
         : undefined;
     const component = readRegistryComponent(entry);
     if (!entry || component == null) {
-        return unknownDirective(name || '(unnamed)', inline, safeChildrenText(childrenText), '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(childrenText), '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, undefined);
@@ -371,10 +403,15 @@ function renderDirectiveContentString(name, kind, isBlock, attributes, childrenT
             children: childrenText,
             ctx,
         });
-        rendered = typeof result === 'string' ? result : String(result ?? '');
+        rendered =
+            typeof result === 'string'
+                ? result
+                : isValidElement(result)
+                    ? renderInkToStringSync(result, width)
+                    : String(result ?? '');
     }
     catch {
-        return componentError(name || '(unnamed)', inline, safeChildrenText(childrenText), width, wctx.color);
+        return componentError(name || '(unnamed)', inline, safeChildrenText(childrenText), width, wctx.color, wctx.glyphs);
     }
     const markerSeparator = inline ? ' ' : '\n';
     const invalidEnum = invalidEnumAttribute(name, binding.attributes);
@@ -420,16 +457,7 @@ function renderRowString(element, attributes, width, indent, wctx) {
     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'));
+        gridRows.push(columnsBlock(rowCells, rowCells.map(() => layout.colWidth), ROW_GUTTER));
     }
     return gridRows.join('\n\n');
 }
@@ -489,8 +517,8 @@ function renderBlockString(node, width, indent, wctx) {
     }
     if (node.tagName === 'blockquote') {
         const innerWidth = Math.max(1, width - 2);
-        const inner = renderBlocksString(node.children, innerWidth, `${indent}│ `, wctx);
-        const prefix = dim('│ ', wctx.color);
+        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}`)
@@ -499,12 +527,13 @@ function renderBlockString(node, width, indent, wctx) {
     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 === '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);
+        const marker = renderScriptMarker(node, wctx.color, wctx.glyphs);
         if (marker !== undefined)
             return marker;
         return renderCodeBlock(node, wctx.color);
@@ -596,7 +625,7 @@ function getCodeText(codeNode) {
     }
     return text.endsWith('\n') ? text.slice(0, -1) : text;
 }
-function renderScriptMarker(node, color) {
+function renderScriptMarker(node, color, glyphs) {
     try {
         const codeNode = findChildElement(node, 'code');
         const meta = codeNode
@@ -610,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 {
@@ -661,7 +692,7 @@ function renderGfmTableString(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 getPlainText(node) {
     let text = '';
@@ -790,7 +821,7 @@ function renderDirectiveString(element, width, indent, wctx) {
         childrenWidth = resolveCardInnerWidth(attributes, layoutForWidth, width);
     }
     else if (isBlock && name === 'callout') {
-        childrenWidth = resolveCalloutInnerWidth(attributes, layoutForWidth, width);
+        childrenWidth = resolveCalloutInnerWidth(attributes, layoutForWidth, width, wctx.glyphs);
     }
     else if (isBlock && name === DETAILS_NAME) {
         childrenWidth = resolveDetailsInnerWidth(width);
@@ -803,8 +834,17 @@ function renderDirectiveString(element, width, indent, wctx) {
     return content;
 }
 function hasRealComponent(registry, name) {
-    return (Object.hasOwn(registry, name) &&
-        readRegistryComponent(registry[name]) != null);
+    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
@@ -840,6 +880,95 @@ function invalidEnumMarkerElement(name, attributes, wctx) {
     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)
@@ -847,15 +976,14 @@ function renderRowElement(element, attributes, width, indent, wctx) {
     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)))
+            .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 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));
+        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 });
 }
@@ -870,7 +998,7 @@ function renderTabsElement(element, width, indent, wctx) {
             label: panels[0]?.label ?? DEFAULT_TAB_LABEL,
         });
     }
-    return (_jsx(InteractiveTabs, { panels: panels, color: wctx.color, interactive: wctx.interactive, focusId: focusId }));
+    return (_jsx(InteractiveTabs, { panels: panels, color: wctx.color, glyphs: wctx.glyphs, interactive: wctx.interactive, focusId: focusId }));
 }
 function extractTabPanelsElement(element, width, indent, wctx) {
     const panels = [];
@@ -912,9 +1040,170 @@ function renderDetailsElement(element, attributes, width, indent, wctx) {
             label: stripControlCharacters(title),
         });
     }
-    return (_jsx(InteractiveDetails, { title: stripControlCharacters(title), body: body, defaultOpen: open, color: wctx.color, interactive: wctx.interactive, focusId: focusId }));
+    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` to their real builders; every other directive falls back to the string engine, wrapped in one `<Text>`. */
+/** 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');
@@ -932,15 +1221,37 @@ function renderDirectiveElement(element, width, indent, wctx) {
         : undefined;
     const formMismatch = entry ? isFormMismatch(entry, kind) : false;
     if (!formMismatch &&
-        (name === ROW_NAME || name === TABS_NAME || name === DETAILS_NAME) &&
+        (name === ROW_NAME ||
+            name === TABS_NAME ||
+            name === DETAILS_NAME ||
+            name === CARD_NAME ||
+            name === CALLOUT_NAME ||
+            name === FIGURE_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
+        // 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
-        // the GENERIC post-render treatment — `applyLayoutElement` below, the
-        // JSX-based twin of `layout.ts`'s string `applyLayout`.
+        // 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);
@@ -948,9 +1259,12 @@ function renderDirectiveElement(element, width, indent, wctx) {
             else if (name === TABS_NAME) {
                 el = renderTabsElement(element, width, indent, wctx);
             }
-            else {
+            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);
@@ -958,7 +1272,7 @@ function renderDirectiveElement(element, width, indent, wctx) {
             return applyLayoutElement(withMarker, layoutResolved, width);
         }
         catch {
-            return styledText(componentError(name || '(unnamed)', false, '', width, wctx.color));
+            return styledText(componentError(name || '(unnamed)', false, '', width, wctx.color, wctx.glyphs));
         }
     }
     return styledText(renderDirectiveString(element, width, indent, wctx));
@@ -977,10 +1291,10 @@ function renderBlockElement(node, width, indent, wctx) {
     }
     if (node.tagName === 'blockquote') {
         const innerWidth = Math.max(1, width - 2);
-        const inner = renderBlocksElement(node.children, innerWidth, `${indent}│ `, wctx);
+        const inner = renderBlocksElement(node.children, innerWidth, `${indent}${wctx.glyphs.quoteBar}`, wctx);
         if (!inner)
             return null;
-        return (_jsxs(Box, { width: width, children: [styledText(dim('│ ', wctx.color)), _jsx(Box, { flexDirection: "column", width: innerWidth, children: inner })] }));
+        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);
@@ -1041,16 +1355,18 @@ 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 buildWalkContext(registry, scope, color, theme, interactive, resolveImageSrc, resolveHref, onDiagnostic) {
+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,
     };
@@ -1058,13 +1374,13 @@ function buildWalkContext(registry, scope, color, theme, interactive, resolveIma
 /** 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);
+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, interactive, resolveImageSrc, resolveHref, onDiagnostic, width) {
-    const element = buildRootElement(root, registry, scope, color, theme, interactive, resolveImageSrc, resolveHref, onDiagnostic, width);
+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);
 }
@@ -1089,7 +1405,7 @@ async function renderRootToString(root, registry, scope, color, theme, interacti
 export async function renderMarkToAnsi(text, registry = defaultAnsiRegistry, store, vault, options) {
     const color = resolveColorOption(options?.color);
     try {
-        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);
+        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);
@@ -1104,7 +1420,7 @@ export async function renderMarkToAnsi(text, registry = defaultAnsiRegistry, sto
 export async function renderMarkNodeToAnsi(node, registry = defaultAnsiRegistry, store, vault, options) {
     const color = resolveColorOption(options?.color);
     try {
-        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);
+        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);
@@ -1153,6 +1469,7 @@ export async function renderMarkInlineToAnsi(text, registry = defaultAnsiRegistr
 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;
@@ -1166,7 +1483,8 @@ export function buildMarkElement(document, registry = defaultAnsiRegistry, optio
     catch {
         root = { type: 'root', children: [] };
     }
-    const content = buildRootElement(root, registry, scope, color, theme, interactive, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic, width);
+    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`
@@ -1179,14 +1497,14 @@ export function buildMarkElement(document, registry = defaultAnsiRegistry, optio
     // mount/resize, not per keystroke.
     const counter = { current: 0 };
     const focusables = [];
-    const countingWctx = buildWalkContext(registry, scope, color, theme, true, options?.resolveImageSrc, options?.resolveHref, 
+    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);
+    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, children: content }));
+    return (_jsx(InteractiveRoot, { focusables: focusables, onExit: options?.onExit, color: color, theme: theme, keyLegend: glyphs.keyLegend, viewportRows: options?.viewportRows, width: width, children: content }));
 }