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

package/dist/failure-presentation.d.ts

@@ -37,6 +37,8 @@ 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 registered block component written as an inline directive. Wording identical to `@markii/html`'s `formMismatchTitle`. */
 export declare function formMismatchTitle(directive: string): string;
 /**
@@ -71,3 +73,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,10 @@ 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 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 +148,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/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;

package/dist/render.js

@@ -15,7 +15,7 @@ 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, 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';
@@ -208,8 +208,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 +223,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,9 +383,11 @@ 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);
         }
         return unknownDirective(name || '(unnamed)', inline, safeChildrenText(childrenText), 'unregistered', width, wctx.color, wctx.glyphs);
     }
@@ -536,6 +541,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 +656,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);
@@ -1355,7 +1392,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,6 +1404,7 @@ function buildWalkContext(registry, scope, color, theme, glyphs, interactive, re
         resolveHref,
         onDiagnostic,
         unavailable,
+        renderCode,
         focusCounter: { current: 0 },
         focusables: undefined,
     };
@@ -1374,13 +1412,13 @@ function buildWalkContext(registry, scope, color, theme, glyphs, interactive, re
 /** 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 +1443,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, options?.onDiagnostic, createUnavailableComponentLookup(options?.unavailableComponents), options?.width ?? DEFAULT_WIDTH, options?.renderCode);
     }
     catch (error) {
         return renderFailureFallback(error, color);
@@ -1420,7 +1458,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, options?.onDiagnostic, createUnavailableComponentLookup(options?.unavailableComponents), options?.width ?? DEFAULT_WIDTH, options?.renderCode);
     }
     catch (error) {
         return renderFailureFallback(error, color);
@@ -1484,7 +1522,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, options?.onDiagnostic, 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.1",
   "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.1",
+    "@markii/pack": "^0.17.0-next.1",
+    "@markii/stdlib": "^0.17.0-next.1",
     "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.1",
     "@types/react": "^19.2.0"
   }
 }