@markii/ansi 0.17.0-next.0 → 0.17.0-next.2

package/dist/failure-presentation.d.ts

@@ -37,6 +37,10 @@ export declare function emptyInlineTitle(name: string): string;
 export declare function invalidAttributeValueTitle(directive: string, attribute: string, value: string): string;
 /** The marker text for a component-built image whose `src` was refused as unsafe. Wording identical to `@markii/html`'s `unsafeImageSrcTitle`. */
 export declare function unsafeImageSrcTitle(directive: string): string;
+/** The diagnostic text for a host `renderCode` callback that threw; the code block rendered as usual. Wording identical to `@markii/html`'s `codeRendererFailedTitle`. */
+export declare function codeRendererFailedTitle(): string;
+/** The diagnostic text for a directive that names no registered component; the unknown-component box was shown. */
+export declare function unknownDirectiveTitle(directive: string): string;
 /** The diagnostic text for a registered block component written as an inline directive. Wording identical to `@markii/html`'s `formMismatchTitle`. */
 export declare function formMismatchTitle(directive: string): string;
 /**
@@ -71,3 +75,14 @@ export declare const NO_ENGINE_VIEW_LABEL = "no terminal view for";
  * and is never printed in the note.
  */
 export declare function noEngineViewTitle(directive: string, pack: string, engines: readonly string[]): string;
+/**
+ * The fallback label for a directive of a pack whose terminal view script
+ * could not be loaded. Followed by the directive name in backticks, like the
+ * other fallback labels. `pack` is stripped by the caller's sanitizer.
+ */
+export declare function packLoadFailedLabel(pack: string): string;
+/**
+ * The diagnostic text for the same case. The loader's own line (what threw)
+ * is on the diagnostics surface already; this one names the directive.
+ */
+export declare function packLoadFailedTitle(directive: string, pack: string): string;

package/dist/failure-presentation.js

@@ -99,6 +99,14 @@ export function invalidAttributeValueTitle(directive, attribute, value) {
 export function unsafeImageSrcTitle(directive) {
     return `${directive}: image source was refused as unsafe and was not shown`;
 }
+/** The diagnostic text for a host `renderCode` callback that threw; the code block rendered as usual. Wording identical to `@markii/html`'s `codeRendererFailedTitle`. */
+export function codeRendererFailedTitle() {
+    return 'code block: the host code renderer failed, so the plain block was shown';
+}
+/** The diagnostic text for a directive that names no registered component; the unknown-component box was shown. */
+export function unknownDirectiveTitle(directive) {
+    return `${directive}: unknown component, shown as a placeholder`;
+}
 /** The diagnostic text for a registered block component written as an inline directive. Wording identical to `@markii/html`'s `formMismatchTitle`. */
 export function formMismatchTitle(directive) {
     return `${directive}: block component was written inline and was not rendered`;
@@ -144,3 +152,18 @@ export function noEngineViewTitle(directive, pack, engines) {
         : 'it has no views for any engine';
     return `The ${pack} pack has no terminal view for this component; ${has}`;
 }
+/**
+ * The fallback label for a directive of a pack whose terminal view script
+ * could not be loaded. Followed by the directive name in backticks, like the
+ * other fallback labels. `pack` is stripped by the caller's sanitizer.
+ */
+export function packLoadFailedLabel(pack) {
+    return `the \`${pack}\` pack failed to load, no terminal view for`;
+}
+/**
+ * The diagnostic text for the same case. The loader's own line (what threw)
+ * is on the diagnostics surface already; this one names the directive.
+ */
+export function packLoadFailedTitle(directive, pack) {
+    return `The ${pack} pack failed to load in the terminal, so ${directive} has no view`;
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { renderMarkToAnsi, renderMarkNodeToAnsi, renderMarkInlineToAnsi, buildMarkElement, type RenderMarkOptions, } from './render.js';
+export { renderMarkToAnsi, renderMarkNodeToAnsi, renderMarkInlineToAnsi, buildMarkElement, type RenderCode, type RenderCodeBlock, type RenderMarkOptions, } from './render.js';
 export { fg, colorize, bold, dim, italic, underline, inverse, hyperlink, detectColorLevel, resolveColorOption, type ColorLevel, type ColorOption, type AnsiColor, } from './ansi.js';
 export { defaultAnsiTheme, type AnsiTheme, type Tier1Token } from './theme.js';
 export { BOX_STYLES, isBoxStyle, glyphsFor, type BoxStyle, type FrameEdges, type GlyphSet, } from './glyphs.js';

package/dist/interactive.d.ts

@@ -1,7 +1,25 @@
 import type { ReactNode } from 'react';
+import { useInput } from 'ink';
 import type { DOMElement } from 'ink';
 import type { AnsiTheme } from './theme.js';
 import type { ColorLevel } from './ansi.js';
+/**
+ * Wraps a focusable pack component's live element. It draws a two-column
+ * gutter (the accent marker while the component has focus, blanks
+ * otherwise) and names the component's focus id for `usePackInput`. The
+ * pack draws inside the width that is left.
+ */
+export declare function PackFocusScope({ focusId, children, }: {
+    focusId: number;
+    children: ReactNode;
+}): ReactNode;
+/**
+ * Ink's `useInput`, for a terminal pack: the same handler and options, but
+ * keys reach the handler only while the pack component whose subtree calls
+ * it has focus. Outside a focusable pack component it never fires. A pack
+ * reads this as `__markiiInk.useInput`, so it never sees raw stdin.
+ */
+export declare function usePackInput(handler: Parameters<typeof useInput>[0], options?: Parameters<typeof useInput>[1]): void;
 /** Whether the component identified by `focusId` is the currently focused one. `undefined` (a non-interactive render, or a component that never got a `focusId`) is never focused. */
 export declare function useIsFocused(focusId: number | undefined): boolean;
 /** Wraps `text` in the accent-colored focus marker when interactive AND `focusId` is the focused one; otherwise returns `text` unchanged. */
@@ -29,7 +47,7 @@ export declare function useFocusAnchor(focusId: number | undefined): (node: DOME
  * yet (mount, or a reader who has not switched panels).
  */
 export interface FocusableDescriptor {
-    kind: 'tabs' | 'details';
+    kind: 'tabs' | 'details' | 'pack';
     label: string;
 }
 export interface InteractiveRootProps {

package/dist/interactive.js

@@ -11,6 +11,36 @@ const FocusContext = createContext({
     reportActiveLabel: () => { },
     registerAnchor: () => { },
 });
+/**
+ * The `focusId` of the pack component a subtree belongs to, or `undefined`
+ * outside one. Provided by `PackFocusScope`; read only by `usePackInput`.
+ */
+const PackFocusContext = createContext(undefined);
+/**
+ * Wraps a focusable pack component's live element. It draws a two-column
+ * gutter (the accent marker while the component has focus, blanks
+ * otherwise) and names the component's focus id for `usePackInput`. The
+ * pack draws inside the width that is left.
+ */
+export function PackFocusScope({ focusId, children, }) {
+    const gutter = useFocusMarker('▌ ', focusId);
+    const focused = useIsFocused(focusId);
+    return (_jsx(PackFocusContext.Provider, { value: focusId, children: _jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { children: focused ? gutter : '  ' }), _jsx(Box, { flexDirection: "column", flexGrow: 1, children: children })] }) }));
+}
+/**
+ * Ink's `useInput`, for a terminal pack: the same handler and options, but
+ * keys reach the handler only while the pack component whose subtree calls
+ * it has focus. Outside a focusable pack component it never fires. A pack
+ * reads this as `__markiiInk.useInput`, so it never sees raw stdin.
+ */
+export function usePackInput(handler, options = {}) {
+    const focusId = useContext(PackFocusContext);
+    const focused = useIsFocused(focusId);
+    useInput(handler, {
+        ...options,
+        isActive: focused && options.isActive !== false,
+    });
+}
 /** Whether the component identified by `focusId` is the currently focused one. `undefined` (a non-interactive render, or a component that never got a `focusId`) is never focused. */
 export function useIsFocused(focusId) {
     const api = useContext(FocusContext);

package/dist/pack-loader.js

@@ -142,6 +142,9 @@ export function loadAnsiPack(manifest, componentModules) {
         const inline = kind === undefined ? module.inline : kind === 'inline';
         if (inline !== undefined)
             entry.inline = inline;
+        // Focus only makes sense for a block view.
+        if (module.focusable === true && inline !== true)
+            entry.focusable = true;
         entries[composed.name] = entry;
     }
     return { registry: createAnsiRegistry(entries) };

package/dist/pack-script.d.ts

@@ -6,7 +6,7 @@ import type { AnsiPackToInstall } from './pack-loader.js';
  *   globalThis.__markiiRegisterTerminalPack(manifestJson, componentModules)
  *
  * with the raw `pack.json` text and an own-property map of
- * `{ component, inline? }` keyed by local component name, the same shape
+ * `{ component, inline?, focusable? }` keyed by local component name, the same shape
  * `__markiiRegisterPack` takes for the webview. React and Ink are NOT
  * bundled into the script. The host sets `globalThis.__markiiReactInk`
  * (the React instance Ink uses) and `globalThis.__markiiInk` (Ink's

package/dist/pack-script.js

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import * as Ink from 'ink';
+import { usePackInput } from './interactive.js';
 import { parsePackManifest } from '@markii/pack';
 /**
  * The terminal pack registration contract (docs/packs.md). A pack's
@@ -8,7 +9,7 @@ import { parsePackManifest } from '@markii/pack';
  *   globalThis.__markiiRegisterTerminalPack(manifestJson, componentModules)
  *
  * with the raw `pack.json` text and an own-property map of
- * `{ component, inline? }` keyed by local component name, the same shape
+ * `{ component, inline?, focusable? }` keyed by local component name, the same shape
  * `__markiiRegisterPack` takes for the webview. React and Ink are NOT
  * bundled into the script. The host sets `globalThis.__markiiReactInk`
  * (the React instance Ink uses) and `globalThis.__markiiInk` (Ink's
@@ -32,7 +33,9 @@ export const TERMINAL_INK_GLOBAL = '__markiiInk';
 export function installTerminalPackGlobals() {
     const g = globalThis;
     g[TERMINAL_REACT_GLOBAL] = React;
-    g[TERMINAL_INK_GLOBAL] = Ink;
+    // Ink's exports with `useInput` replaced by the focus-gated one: a pack
+    // gets keys while its component has focus and never raw stdin.
+    g[TERMINAL_INK_GLOBAL] = { ...Ink, useInput: usePackInput };
 }
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -52,9 +55,16 @@ function toComponentModules(value) {
         if (Object.hasOwn(entry, 'inline') && typeof entry.inline !== 'boolean') {
             return undefined;
         }
+        if (Object.hasOwn(entry, 'focusable') &&
+            typeof entry.focusable !== 'boolean') {
+            return undefined;
+        }
         out[key] = {
             component: entry.component,
             ...(typeof entry.inline === 'boolean' ? { inline: entry.inline } : {}),
+            ...(typeof entry.focusable === 'boolean'
+                ? { focusable: entry.focusable }
+                : {}),
         };
     }
     return out;

package/dist/registry.d.ts

@@ -171,6 +171,16 @@ export interface AnsiRegistryEntry {
      * Ink primitives Yoga can reflow.
      */
     selfLayout?: boolean;
+    /**
+     * Marks a BLOCK component whose returned Ink element the live viewer
+     * mounts and lets take focus, instead of drawing it as a static
+     * snapshot. It joins the focus order (up/down/j/k) and, while focused,
+     * its element's `useInput` calls receive keys (a pack reads
+     * `__markiiInk.useInput`, which is gated this way). In a render-once
+     * pass, or inside a framed body (a callout, a card) it renders as
+     * before: a snapshot with no focus.
+     */
+    focusable?: boolean;
 }
 /** One alias: a second name for an existing component, optionally carrying preset attributes. */
 export interface RegistryAlias {

package/dist/render.d.ts

@@ -14,12 +14,36 @@ export interface ElementTabPanel {
     label: string;
     body: ReactNode;
 }
+/** A fenced code block as offered to `RenderMarkOptions.renderCode`. */
+export interface RenderCodeBlock {
+    /** The info-string language, or `undefined` when the fence names none. */
+    readonly lang: string | undefined;
+    /** The code text, control characters removed and tabs expanded. */
+    readonly code: string;
+}
+/** The `renderCode` callback: a string for a code block, or `undefined` to draw it as usual. */
+export type RenderCode = (code: RenderCodeBlock) => string | undefined;
 /**
  * Options for `renderMarkToAnsi`/`renderMarkNodeToAnsi`/`renderMarkInlineToAnsi`.
  * `store`/`vault` are offered both here and as positional parameters; when
  * both are given, the option wins.
  */
 export interface RenderMarkOptions {
+    /**
+     * Replaces the output for an ordinary fenced code block. Called with the
+     * info-string language (`undefined` when the fence names none) and the
+     * code text, already stripped of control characters and with tabs
+     * expanded (the engine's own sanitizer, so author escapes cannot reach
+     * the terminal through a host that echoes it). Return a string to use it,
+     * or `undefined` to draw the block as usual. The returned string is
+     * HOST-TRUSTED and inserted as-is, so the host may add its own SGR
+     * styling and owns keeping control characters out of anything it adds.
+     * Never called for script fences or inline code. A callback that throws
+     * draws the block as usual and reports a `'code-renderer-failed'` event
+     * through `onDiagnostic`. Element results are not supported: fenced blocks
+     * are drawn as strings in this engine.
+     */
+    readonly renderCode?: RenderCode;
     readonly width?: number;
     readonly color?: ColorOption;
     readonly theme?: AnsiTheme;
@@ -33,6 +57,13 @@ export interface RenderMarkOptions {
     readonly resolveImageSrc?: ResolveImageSrc;
     readonly resolveHref?: ResolveHref;
     readonly onDiagnostic?: OnDiagnostic;
+    /**
+     * Also report a directive that names no registered component as an
+     * `'unknown-directive'` event. Off by default: the fallback box already
+     * marks it in the output. A host that places findings in the note's
+     * source (a language server) turns it on.
+     */
+    readonly reportUnknownDirectives?: boolean;
     /**
      * Components of installed packs that this render cannot draw, as plain
      * data from the host. A directive named here renders the usual fallback

package/dist/render.js

@@ -15,13 +15,13 @@ import { sanitizeBlockText, sanitizeUrlText, stripControlCharacters, } from './s
 import { readRegistryComponent, registryLayoutAxis, registrySelfLayout, resolveDirectiveAlias, } from './registry.js';
 import { applyLayout, resolveLayoutAttributes, } from './layout.js';
 import { resolveScopedPath } from './resolve.js';
-import { dataStateSuffix, emptyInlineTitle, failureToken, formMismatchTitle, NO_ENGINE_VIEW_LABEL, noEngineViewTitle, invalidAttributeValueLabel, invalidAttributeValueTitle, unsafeImageSrcLabel, unsafeImageSrcTitle, } from './failure-presentation.js';
+import { dataStateSuffix, emptyInlineTitle, failureToken, codeRendererFailedTitle, formMismatchTitle, NO_ENGINE_VIEW_LABEL, noEngineViewTitle, packLoadFailedLabel, packLoadFailedTitle, invalidAttributeValueLabel, invalidAttributeValueTitle, unsafeImageSrcLabel, unknownDirectiveTitle, 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, renderInkToStringSync } from './ink-string.js';
-import { InteractiveRoot } from './interactive.js';
+import { InteractiveRoot, PackFocusScope } from './interactive.js';
 import { glyphsFor } from './glyphs.js';
 import { InteractiveTabs } from './components/tabs.js';
 import { InteractiveDetails } from './components/details.js';
@@ -126,6 +126,29 @@ function nodeOrRootToHast(node) {
     }
     return { type: 'root', children };
 }
+/**
+ * A walk context whose `onDiagnostic` stamps each event with the source
+ * range of `element`, unless an inner directive already did. This is how a
+ * host (the language server) places a finding in the note without any
+ * component knowing about positions. A node with no position, or a render
+ * with no `onDiagnostic`, returns `wctx` itself.
+ */
+function withNodePosition(wctx, element) {
+    const downstream = wctx.onDiagnostic;
+    const range = element.position;
+    if (downstream === undefined || range === undefined)
+        return wctx;
+    const position = {
+        startLine: range.start.line,
+        startColumn: range.start.column,
+        endLine: range.end.line,
+        endColumn: range.end.column,
+    };
+    return {
+        ...wctx,
+        onDiagnostic: (event) => downstream(event.position === undefined ? { ...event, position } : event),
+    };
+}
 function nextFocusId(wctx) {
     const id = wctx.focusCounter.current;
     wctx.focusCounter.current += 1;
@@ -208,8 +231,11 @@ 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) {
+function fallbackLabel(name, inline, reason, pack) {
     const code = `\`${stripControlCharacters(name)}\``;
+    if (reason === 'pack-load-failed') {
+        return `${packLoadFailedLabel(stripControlCharacters(pack ?? ''))} ${code}`;
+    }
     if (reason === 'no-engine-view')
         return `${NO_ENGINE_VIEW_LABEL} ${code}`;
     if (reason === 'form-mismatch') {
@@ -220,8 +246,8 @@ 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, glyphs) {
-    const label = fallbackLabel(name, inline, reason);
+function unknownDirective(name, inline, childrenText, reason, width, color, glyphs, pack) {
+    const label = fallbackLabel(name, inline, reason, pack);
     if (inline) {
         return childrenText === ''
             ? dim(label, color)
@@ -380,10 +406,17 @@ function renderDirectiveContentString(name, kind, isBlock, attributes, childrenT
             reportDiagnostic(wctx.onDiagnostic, {
                 kind: 'no-engine-view',
                 directive: name,
-                message: noEngineViewTitle(name, missingView.pack, missingView.engines),
+                message: missingView.loadFailed
+                    ? packLoadFailedTitle(name, missingView.pack)
+                    : noEngineViewTitle(name, missingView.pack, missingView.engines),
             });
-            return unknownDirective(name, inline, safeChildrenText(childrenText), 'no-engine-view', width, wctx.color, wctx.glyphs);
+            return unknownDirective(name, inline, safeChildrenText(childrenText), missingView.loadFailed ? 'pack-load-failed' : 'no-engine-view', width, wctx.color, wctx.glyphs, missingView.pack);
         }
+        reportDiagnostic(wctx.onDiagnostic, {
+            kind: 'unknown-directive',
+            directive: name || '(unnamed)',
+            message: unknownDirectiveTitle(name || '(unnamed)'),
+        });
         return unknownDirective(name || '(unnamed)', inline, safeChildrenText(childrenText), 'unregistered', width, wctx.color, wctx.glyphs);
     }
     if (isFormMismatch(entry, kind)) {
@@ -536,6 +569,9 @@ function renderBlockString(node, width, indent, wctx) {
         const marker = renderScriptMarker(node, wctx.color, wctx.glyphs);
         if (marker !== undefined)
             return marker;
+        const custom = applyRenderCode(node, wctx);
+        if (custom !== undefined)
+            return custom;
         return renderCodeBlock(node, wctx.color);
     }
     return wrapText(renderInlineChildrenString(node.children ?? [], width, indent, wctx), width).join('\n');
@@ -648,6 +684,35 @@ function renderScriptMarker(node, color, glyphs) {
         return undefined;
     }
 }
+/**
+ * Offers one ordinary fenced code block to the host's `renderCode`. The
+ * text handed over is already run through `sanitizeBlockText` (control
+ * characters dropped, tabs expanded), so a host that echoes it cannot
+ * smuggle author escapes into the terminal. Returns the host's string, or
+ * `undefined` to draw the block as usual: no callback, a decline, a
+ * non-string result, or a throw (reported through `onDiagnostic`).
+ */
+function applyRenderCode(node, wctx) {
+    if (!wctx.renderCode)
+        return undefined;
+    const codeNode = findChildElement(node, 'code');
+    if (!codeNode)
+        return undefined;
+    try {
+        const result = wctx.renderCode({
+            lang: getLanguage(codeNode) || undefined,
+            code: sanitizeBlockText(getCodeText(codeNode)),
+        });
+        return typeof result === 'string' ? result : undefined;
+    }
+    catch {
+        reportDiagnostic(wctx.onDiagnostic, {
+            kind: 'code-renderer-failed',
+            message: codeRendererFailedTitle(),
+        });
+        return undefined;
+    }
+}
 function renderCodeBlock(node, color) {
     const codeNode = findChildElement(node, 'code');
     const language = getLanguage(codeNode);
@@ -775,7 +840,8 @@ function renderBlocksString(nodes, width, indent, wctx) {
     }
     return blocks.join('\n\n');
 }
-function renderDirectiveString(element, width, indent, wctx) {
+function renderDirectiveString(element, width, indent, walk) {
+    const wctx = withNodePosition(walk, element);
     const written = stringProperty(element, 'data-mk-name') ?? '';
     const kind = stringProperty(element, 'data-mk-kind');
     const rawAttributes = parseAttributes(stringProperty(element, 'data-mk-attrs'));
@@ -1204,7 +1270,8 @@ function renderFigureElement(element, attributes, width, indent, wctx) {
     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) {
+function renderDirectiveElement(element, width, indent, walk) {
+    const wctx = withNodePosition(walk, element);
     const written = stringProperty(element, 'data-mk-name') ?? '';
     const kind = stringProperty(element, 'data-mk-kind');
     const rawAttributes = parseAttributes(stringProperty(element, 'data-mk-attrs'));
@@ -1275,8 +1342,48 @@ function renderDirectiveElement(element, width, indent, wctx) {
             return styledText(componentError(name || '(unnamed)', false, '', width, wctx.color, wctx.glyphs));
         }
     }
+    if (entry?.focusable === true && !formMismatch && wctx.interactive) {
+        const focusable = renderFocusablePackElement(element, name, aliased, width, indent, wctx);
+        if (focusable !== undefined)
+            return focusable;
+    }
     return styledText(renderDirectiveString(element, width, indent, wctx));
 }
+/**
+ * A `focusable` registry component in the live viewer: the component runs
+ * as usual, but an Ink element it returns is mounted (not drawn once) in a
+ * `PackFocusScope`, so it joins the focus order and receives keys while
+ * focused. Returns `undefined` when the component returns a string or
+ * throws, so the caller falls back to the string path (which reports the
+ * failure the usual way). The component draws two columns narrower: the
+ * scope's gutter carries the focus marker.
+ */
+function renderFocusablePackElement(element, name, attributes, width, indent, wctx) {
+    const component = readRegistryComponent(wctx.registry[name]);
+    if (component == null)
+        return undefined;
+    const innerWidth = Math.max(1, width - 2);
+    const binding = resolveDataAttribute(attributes, wctx.scope);
+    const focusId = nextFocusId(wctx);
+    recordFocusable(wctx, { kind: 'pack', label: stripControlCharacters(name) });
+    const ctx = buildComponentContext(innerWidth, indent, wctx, binding, undefined, focusId);
+    let result;
+    try {
+        result = component({
+            attributes: binding.attributes,
+            children: renderDirectiveChildrenString(element.children, innerWidth, indent, wctx),
+            ctx,
+        });
+    }
+    catch {
+        // Same as the string path: the failure is contained to a neutral box.
+        return styledText(componentError(name || '(unnamed)', false, '', width, wctx.color, wctx.glyphs));
+    }
+    if (!isValidElement(result)) {
+        return styledText(typeof result === 'string' ? result : '');
+    }
+    return _jsx(PackFocusScope, { focusId: focusId, children: result });
+}
 /** 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') {
@@ -1355,7 +1462,7 @@ 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, glyphs, interactive, resolveImageSrc, resolveHref, onDiagnostic, unavailable) {
+function buildWalkContext(registry, scope, color, theme, glyphs, interactive, resolveImageSrc, resolveHref, onDiagnostic, unavailable, renderCode) {
     return {
         registry,
         scope,
@@ -1367,20 +1474,38 @@ function buildWalkContext(registry, scope, color, theme, glyphs, interactive, re
         resolveHref,
         onDiagnostic,
         unavailable,
+        renderCode,
         focusCounter: { current: 0 },
         focusables: undefined,
     };
 }
+/**
+ * The `onDiagnostic` a render hands its walk: the caller's own, minus
+ * `'unknown-directive'` events unless `reportUnknownDirectives` asked for
+ * them. The fallback box already marks an unknown directive in the output,
+ * so a host that does not place findings in a source (the viewer, an
+ * export) keeps the quiet diagnostics surface it always had.
+ */
+function diagnosticsFor(options) {
+    const downstream = options?.onDiagnostic;
+    if (downstream === undefined || options?.reportUnknownDirectives === true) {
+        return downstream;
+    }
+    return (event) => {
+        if (event.kind !== 'unknown-directive')
+            downstream(event);
+    };
+}
 /** 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);
+function buildRootElement(root, registry, scope, color, theme, glyphs, interactive, resolveImageSrc, resolveHref, onDiagnostic, unavailable, width, renderCode) {
+    const wctx = buildWalkContext(registry, scope, color, theme, glyphs, interactive, resolveImageSrc, resolveHref, onDiagnostic, unavailable, renderCode);
     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);
+async function renderRootToString(root, registry, scope, color, theme, glyphs, interactive, resolveImageSrc, resolveHref, onDiagnostic, unavailable, width, renderCode) {
+    const element = buildRootElement(root, registry, scope, color, theme, glyphs, interactive, resolveImageSrc, resolveHref, onDiagnostic, unavailable, width, renderCode);
     const raw = await renderInkToString(element, width);
     return finalizeOutput(raw);
 }
@@ -1405,7 +1530,7 @@ async function renderRootToString(root, registry, scope, color, theme, glyphs, i
 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, glyphsFor(options?.box), options?.interactive ?? false, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic, createUnavailableComponentLookup(options?.unavailableComponents), 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, diagnosticsFor(options), createUnavailableComponentLookup(options?.unavailableComponents), options?.width ?? DEFAULT_WIDTH, options?.renderCode);
     }
     catch (error) {
         return renderFailureFallback(error, color);
@@ -1420,7 +1545,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, glyphsFor(options?.box), options?.interactive ?? false, options?.resolveImageSrc, options?.resolveHref, options?.onDiagnostic, createUnavailableComponentLookup(options?.unavailableComponents), 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, diagnosticsFor(options), createUnavailableComponentLookup(options?.unavailableComponents), options?.width ?? DEFAULT_WIDTH, options?.renderCode);
     }
     catch (error) {
         return renderFailureFallback(error, color);
@@ -1484,7 +1609,7 @@ export function buildMarkElement(document, registry = defaultAnsiRegistry, optio
         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);
+    const content = buildRootElement(root, registry, scope, color, theme, glyphs, interactive, options?.resolveImageSrc, options?.resolveHref, diagnosticsFor(options), unavailable, width, options?.renderCode);
     if (!interactive)
         return content;
     // The walk above already assigned every focusable component's `focusId`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/ansi",
-  "version": "0.17.0-next.0",
+  "version": "0.17.0-next.2",
   "description": "The terminal renderer for Markii (.mk.md): a registry-driven hast-to-terminal engine built on Ink. Renders a note once as a string with optional color, for a pipe or a log, or as a live Ink tree a host can mount.",
   "keywords": [
     "markdown",
@@ -51,15 +51,15 @@
     "regenerate:fixtures": "npm run build:dist && node scripts/regenerate-ansi-fixtures.ts"
   },
   "dependencies": {
-    "@markii/core": "^0.17.0-next.0",
-    "@markii/pack": "^0.17.0-next.0",
-    "@markii/stdlib": "^0.17.0-next.0",
+    "@markii/core": "^0.17.0-next.2",
+    "@markii/pack": "^0.17.0-next.2",
+    "@markii/stdlib": "^0.17.0-next.2",
     "ink": "^7.1.1",
     "react": "^19.2.0"
   },
   "devDependencies": {
     "@types/hast": "^3.0.4",
-    "@markii/runtime": "^0.17.0-next.0",
+    "@markii/runtime": "^0.17.0-next.2",
     "@types/react": "^19.2.0"
   }
 }