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

package/dist/ansi.d.ts

@@ -46,8 +46,7 @@ export declare const inverse: (text: string, level: ColorLevel) => string;
  * at a line boundary are closed with a reset before the `\n` and reopened
  * at the start of the next line.
  *
- * This is the SYSTEMATIC fix for a real Ink behavior discovered during
- * batch 10's post-phase-2 review: Ink's `<Text>` does not treat an embedded
+ * This is the systematic fix for an Ink behavior: Ink's `<Text>` does not treat an embedded
  * raw ANSI escape as transparent across an embedded newline the way a
  * terminal receiving the same bytes directly would — it resets SGR state
  * at every line boundary within one `<Text>` value and does not reopen it.

package/dist/ansi.js

@@ -72,8 +72,7 @@ const SGR_TOKEN = /\x1b\[([0-9;]*)m/g;
  * at a line boundary are closed with a reset before the `\n` and reopened
  * at the start of the next line.
  *
- * This is the SYSTEMATIC fix for a real Ink behavior discovered during
- * batch 10's post-phase-2 review: Ink's `<Text>` does not treat an embedded
+ * This is the systematic fix for an Ink behavior: Ink's `<Text>` does not treat an embedded
  * raw ANSI escape as transparent across an embedded newline the way a
  * terminal receiving the same bytes directly would — it resets SGR state
  * at every line boundary within one `<Text>` value and does not reopen it.

package/dist/components/card.d.ts

@@ -18,8 +18,7 @@ export declare function resolveCardBoxWidth(attributes: DirectiveAttributes, lay
  * children are built ONCE, directly at the correct inner width, and never
  * built wide and re-wrapped narrower afterward.
  *
- * That re-wrap-afterward shape was a real, shipped regression (caught
- * post-phase-2 review): re-wrapping an ALREADY-RENDERED child block with a
+ * That re-wrap-afterward shape was a real, shipped regression: re-wrapping an ALREADY-RENDERED child block with a
  * word-based wrapper corrupts anything in it that draws its own fixed-width
  * glyphs (a nested `card`/`callout`'s frame, a nested `row`'s columns) — the
  * word-wrapper has no notion that a run of box-drawing characters is not

package/dist/components/card.js

@@ -31,8 +31,7 @@ export function resolveCardBoxWidth(attributes, layout, outerWidth) {
  * children are built ONCE, directly at the correct inner width, and never
  * built wide and re-wrapped narrower afterward.
  *
- * That re-wrap-afterward shape was a real, shipped regression (caught
- * post-phase-2 review): re-wrapping an ALREADY-RENDERED child block with a
+ * That re-wrap-afterward shape was a real, shipped regression: re-wrapping an ALREADY-RENDERED child block with a
  * word-based wrapper corrupts anything in it that draws its own fixed-width
  * glyphs (a nested `card`/`callout`'s frame, a nested `row`'s columns) — the
  * word-wrapper has no notion that a run of box-drawing characters is not

package/dist/components/row.d.ts

@@ -1,7 +1,7 @@
 import type { AnsiComponent, DirectiveAttributes } from '../registry.js';
 declare const TEXT_ALIGNS: readonly ["left", "center", "right"];
 export type RowTextAlign = (typeof TEXT_ALIGNS)[number];
-/** Below this width, cells stack vertically instead of sitting side by side — a named constant per the batch brief, not a magic number. */
+/** Below this width, cells stack vertically instead of sitting side by side — a named constant, not a magic number. */
 export declare const ROW_COLUMN_THRESHOLD = 60;
 /** The blank columns between two cells of a grid row. Shared by both emitters (the Ink flex `Box` and the flattened string). */
 export declare const ROW_GUTTER = 1;

package/dist/components/row.js

@@ -6,7 +6,7 @@ const TEXT_ALIGNS = ['left', 'center', 'right'];
 function isTextAlign(value) {
     return TEXT_ALIGNS.includes(value);
 }
-/** Below this width, cells stack vertically instead of sitting side by side — a named constant per the batch brief, not a magic number. */
+/** Below this width, cells stack vertically instead of sitting side by side — a named constant, not a magic number. */
 export const ROW_COLUMN_THRESHOLD = 60;
 /** The blank columns between two cells of a grid row. Shared by both emitters (the Ink flex `Box` and the flattened string). */
 export const ROW_GUTTER = 1;

package/dist/failure-presentation.d.ts

@@ -39,6 +39,8 @@ export declare function invalidAttributeValueTitle(directive: string, attribute:
 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;
 /**

package/dist/failure-presentation.js

@@ -103,6 +103,10 @@ export function unsafeImageSrcTitle(directive) {
 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`;

package/dist/ink-string.d.ts

@@ -3,8 +3,7 @@ import type { ReactElement } from 'react';
  * Mounts `element` with Ink at `columns` wide, captures the first (and only)
  * frame as a plain string, and unmounts. `ink` is imported dynamically
  * because `yoga-layout` (Ink's layout engine) resolves its WASM module via a
- * top-level `await` at ES-module-evaluation time (`SPIKE-10-findings.md`'s
- * "Item 3"): the first call to this function pays that one-time cost, and
+ * top-level `await` at ES-module-evaluation time: the first call to this function pays that one-time cost, and
  * every exported entry point that reaches here is therefore `async`. A
  * later call in the same process reuses the already-evaluated module graph,
  * the ordinary ESM module-cache guarantee.

package/dist/ink-string.js

@@ -20,8 +20,7 @@ function makeCollectingStream(columns) {
  * Mounts `element` with Ink at `columns` wide, captures the first (and only)
  * frame as a plain string, and unmounts. `ink` is imported dynamically
  * because `yoga-layout` (Ink's layout engine) resolves its WASM module via a
- * top-level `await` at ES-module-evaluation time (`SPIKE-10-findings.md`'s
- * "Item 3"): the first call to this function pays that one-time cost, and
+ * top-level `await` at ES-module-evaluation time: the first call to this function pays that one-time cost, and
  * every exported entry point that reaches here is therefore `async`. A
  * later call in the same process reuses the already-evaluated module graph,
  * the ordinary ESM module-cache guarantee.

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,13 +47,13 @@ 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 {
     /** Every focusable component the walk assigned a `focusId` to, in `focusId` order (empty for none). */
     focusables: readonly FocusableDescriptor[];
-    /** Called when the reader presses `q`. The engine owns no process state: it never calls `process.exit` itself (AGENTS.md, batch-10 brief). */
+    /** Called when the reader presses `q`. The engine owns no process state: it never calls `process.exit` itself. */
     onExit?: () => void;
     color: ColorLevel;
     theme: AnsiTheme;
@@ -55,7 +73,7 @@ export interface InteractiveRootProps {
 /**
  * The root of an interactive render: owns which `focusId` is focused, moves
  * it on up/down/j/k, calls `onExit` on `q`, and renders the one-line status
- * bar (batch 10.1) naming the focused block and the key legend. Rendered
+ * bar naming the focused block and the key legend. Rendered
  * only when the caller actually wants a live, keyboard-driven view:
  * `buildMarkElement` mounts this when `interactive` is true, but the
  * render-ONCE string path (`ink-string.ts`, `renderRootToString`) never

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);
@@ -48,7 +78,7 @@ export function useFocusAnchor(focusId) {
 /**
  * The root of an interactive render: owns which `focusId` is focused, moves
  * it on up/down/j/k, calls `onExit` on `q`, and renders the one-line status
- * bar (batch 10.1) naming the focused block and the key legend. Rendered
+ * bar naming the focused block and the key legend. Rendered
  * only when the caller actually wants a live, keyboard-driven view:
  * `buildMarkElement` mounts this when `interactive` is true, but the
  * render-ONCE string path (`ink-string.ts`, `renderRootToString`) never

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

@@ -8,14 +8,11 @@ import type { ResolvedLayoutAttributes } from './layout.js';
 import type { ResolveImageSrc } from './image-resolve.js';
 import type { ResolveHref } from './href-resolve.js';
 /**
- * The registry contract for the terminal engine, batch-10 (the Ink
- * rewrite): a component is a React function component receiving
+ * The registry contract for the terminal engine: a component is a React function component receiving
  * `{ attributes, children, ctx }`, where `children` is ALREADY a built Ink
  * element tree (a `ReactNode`) rather than the lazy string-producing
  * `AnsiChildren` handle the pre-Ink engine used. Building children eagerly
- * is the batch-10 brief's own instruction (`AGENTS.md`'s architecture
- * section is silent on this; the brief is explicit: "Delete... the lazy-
- * children machinery"): Ink/Yoga lays a tree out AFTER it is built, exactly
+ * is how this engine works: Ink/Yoga lays a tree out AFTER it is built, exactly
  * like a browser reflows HTML, so a component no longer needs to ask for a
  * narrower re-render of its own body the way the old string engine did —
  * the one standard component that still needs a per-cell WIDTH NUMBER before
@@ -171,6 +168,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 {
@@ -223,7 +230,7 @@ export declare function resolveDirectiveAlias(registry: AnsiRegistry, name: stri
  * top comment on why those three are the only ones that get a real Ink
  * element tree instead. `children` is still typed `ReactNode` on
  * `AnsiComponentProps` (the honest public contract: "an Ink element tree",
- * per the batch-10 brief, and a string IS a valid `ReactNode`), so a
+ * and a string IS a valid `ReactNode`), so a
  * component that needs its body AS TEXT (to measure it, frame it, indent
  * it, or check whether it is empty) reads it through this helper rather
  * than assuming the type; a non-string `children` degrades to `''` rather

package/dist/registry.js

@@ -117,7 +117,7 @@ export function resolveDirectiveAlias(registry, name, attributes) {
  * top comment on why those three are the only ones that get a real Ink
  * element tree instead. `children` is still typed `ReactNode` on
  * `AnsiComponentProps` (the honest public contract: "an Ink element tree",
- * per the batch-10 brief, and a string IS a valid `ReactNode`), so a
+ * and a string IS a valid `ReactNode`), so a
  * component that needs its body AS TEXT (to measure it, frame it, indent
  * it, or check whether it is empty) reads it through this helper rather
  * than assuming the type; a non-string `children` degrades to `''` rather

package/dist/render.d.ts

@@ -57,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
@@ -92,8 +99,7 @@ export interface RenderMarkOptions {
  * defaults to `defaultAnsiRegistry`.
  *
  * `async` since the first call in a process pays Ink/Yoga's one-time module-
- * evaluation cost (`ink-string.ts`'s doc comment; `SPIKE-10-findings.md`'s
- * "Item 3"). Never throws: parsing is tolerant, unknown names always render
+ * evaluation cost (`ink-string.ts`'s doc comment). Never throws: parsing is tolerant, unknown names always render
  * a fallback, and any unexpected internal error degrades to the "failed to
  * render document" line.
  *
@@ -118,7 +124,7 @@ export declare function renderMarkNodeToAnsi(node: MarkNode | MarkRoot, registry
  */
 export declare function renderMarkInlineToAnsi(text: string, registry?: AnsiRegistry, store?: AnsiValueStore, vault?: AnsiVaultStore, options?: RenderMarkOptions): Promise<string>;
 /**
- * The live-viewer entry point (phase 3 consumes this): builds the same Ink
+ * The live-viewer entry point: builds the same Ink
  * element tree `renderMarkToAnsi` would render to a string, but returns the
  * element itself so a host (the CLI's `markii view`) can mount it directly
  * with Ink's own `render()` instead of re-rendering a string on every

package/dist/render.js

@@ -15,23 +15,23 @@ 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, codeRendererFailedTitle, formMismatchTitle, NO_ENGINE_VIEW_LABEL, noEngineViewTitle, packLoadFailedLabel, packLoadFailedTitle, 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';
 /**
- * The hast walk for the terminal engine (batch 10: the Ink rewrite). Every
+ * The hast walk for the terminal engine (the Ink rewrite). Every
  * DECISION this walk makes is unchanged from the pre-Ink engine (alias
  * resolution, layout resolution, data binding, form mismatch, invalid-enum
  * notice, empty-inline notice, never-throw component containment, script-
  * fence markers, link and image handling) — see AGENTS.md's architecture
- * rules and the batch-10 brief. What changed is the OUTPUT shape: instead of
+ * rules. The OUTPUT is a tree of Ink elements: instead of
  * building one big plain string, the walk builds a tree of Ink elements
  * (`Box`/`Text`) and hands it to `ink-string.ts` (the render-once path) or
  * returns it directly (the new live-viewer export, `buildMarkElement`).
@@ -82,7 +82,7 @@ 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
+ * `card` and `figure` join this list: 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`
@@ -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;
@@ -389,6 +412,11 @@ function renderDirectiveContentString(name, kind, isBlock, attributes, childrenT
             });
             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)) {
@@ -812,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'));
@@ -848,7 +877,7 @@ function renderDirectiveString(element, width, indent, wctx) {
     // own attributes (never from the body), so the walk resolves it here,
     // BEFORE building children, and builds children exactly ONCE at that
     // final width — never at the outer width followed by a re-wrap. A
-    // re-wrap-afterward shipped as a real regression (post-phase-2 review):
+    // re-wrap-afterward shipped as a regression:
     // it corrupts anything self-drawing nested inside (a card's frame, a
     // row's columns), since a word-based re-wrapper has no notion that a run
     // of box-drawing characters is not prose. See `resolveCardInnerWidth`'s
@@ -983,13 +1012,11 @@ function renderAlignedBodyElement(nodes, width, indent, wctx, align) {
  * 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
+ * falls back to a flattened, pre-justified STRING — the 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.
+ * second Ink-`alignItems`-based mechanism. The ELEMENT-mode grid and the STRING-mode fallback (reached when a `row`
+ * is nested inside a self-drawing container) both honor `text=` through
+ * that one helper.
  */
 function renderRowCellElement(node, cellWidth, indent, wctx, align) {
     if (align === 'left')
@@ -1100,7 +1127,7 @@ function selfLayoutAlignElement(element, boxWidth, layout, width) {
 }
 /**
  * `:::card{title="..." text=left|center|right} ... :::` as a real Ink
- * element (batch 11: card moves off `frameBlock`'s hand-drawn string frame
+ * element (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).
@@ -1112,9 +1139,7 @@ function selfLayoutAlignElement(element, boxWidth, layout, width) {
  * `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
+ * `text=center`/`text=right` 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
@@ -1197,7 +1222,7 @@ function renderCalloutElement(element, attributes, width, indent, wctx, layout)
 }
 /**
  * `:::figure{src="..." alt="..."} caption markdown :::` as a real Ink
- * element (batch 11: `figure` never drew a hand-drawn frame — it is a plain
+ * element (`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
@@ -1241,7 +1266,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'));
@@ -1312,8 +1338,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') {
@@ -1409,9 +1475,26 @@ function buildWalkContext(registry, scope, color, theme, glyphs, interactive, re
         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. */
+/** Builds the root Ink element for `root`, given every resolved render input. Exported for `buildMarkElement` (the live-viewer entry point) 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, renderCode) {
     const wctx = buildWalkContext(registry, scope, color, theme, glyphs, interactive, resolveImageSrc, resolveHref, onDiagnostic, unavailable, renderCode);
     const body = renderBlocksElement(root.children, width, '', wctx);
@@ -1429,8 +1512,7 @@ async function renderRootToString(root, registry, scope, color, theme, glyphs, i
  * defaults to `defaultAnsiRegistry`.
  *
  * `async` since the first call in a process pays Ink/Yoga's one-time module-
- * evaluation cost (`ink-string.ts`'s doc comment; `SPIKE-10-findings.md`'s
- * "Item 3"). Never throws: parsing is tolerant, unknown names always render
+ * evaluation cost (`ink-string.ts`'s doc comment). Never throws: parsing is tolerant, unknown names always render
  * a fallback, and any unexpected internal error degrades to the "failed to
  * render document" line.
  *
@@ -1443,7 +1525,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, options?.renderCode);
+        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);
@@ -1458,7 +1540,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, options?.renderCode);
+        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);
@@ -1497,7 +1579,7 @@ export async function renderMarkInlineToAnsi(text, registry = defaultAnsiRegistr
     return renderMarkToAnsi(text, registry, store, vault, options);
 }
 /**
- * The live-viewer entry point (phase 3 consumes this): builds the same Ink
+ * The live-viewer entry point: builds the same Ink
  * element tree `renderMarkToAnsi` would render to a string, but returns the
  * element itself so a host (the CLI's `markii view`) can mount it directly
  * with Ink's own `render()` instead of re-rendering a string on every
@@ -1522,7 +1604,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, options?.renderCode);
+    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/dist/text-grid.d.ts

@@ -3,9 +3,8 @@
  * handful of STANDARD COMPONENTS that draw their own fixed-width glyphs
  * (`card`, `callout`, `divider`, `chart`, `table`, and the plain-markdown
  * table grid in `render.tsx`). Everything else in this engine wraps prose
- * through Ink's own layout (`ink-string.ts`'s doc comment and AGENTS.md's
- * batch-10 brief: "Drop wrap/pad/columns/frame/rule: Ink's layout replaces
- * them").
+ * through Ink's own layout (`ink-string.ts`'s doc comment): Ink's layout replaces
+ * wrap, pad, columns, frame and rule.
  *
  * A self-drawing component cannot lean on Ink for this: the string it builds
  * (a box-drawing frame, a sparkline, a table grid) is a fixed block of
@@ -13,9 +12,8 @@
  * `<Text>` renders it verbatim rather than reflowing pre-drawn glyphs. This
  * module is therefore kept as a small, PRIVATE (not exported from
  * `src/index.ts`) implementation detail of those few components, replacing
- * the old public `measure.ts`/`box.ts` modules the batch-10 brief has this
- * engine delete. The width-measurement approximation is unchanged from the
- * old `measure.ts`: Latin/CJK/emoji/combining-mark ranges, not a full
+ * the old public `measure.ts`/`box.ts` modules. The width-measurement
+ * approximation covers Latin/CJK/emoji/combining-mark ranges, not a full
  * Unicode grapheme-segmentation table (see the doc comment below for the one
  * documented limitation).
  */

package/dist/text-grid.js

@@ -3,9 +3,8 @@
  * handful of STANDARD COMPONENTS that draw their own fixed-width glyphs
  * (`card`, `callout`, `divider`, `chart`, `table`, and the plain-markdown
  * table grid in `render.tsx`). Everything else in this engine wraps prose
- * through Ink's own layout (`ink-string.ts`'s doc comment and AGENTS.md's
- * batch-10 brief: "Drop wrap/pad/columns/frame/rule: Ink's layout replaces
- * them").
+ * through Ink's own layout (`ink-string.ts`'s doc comment): Ink's layout replaces
+ * wrap, pad, columns, frame and rule.
  *
  * A self-drawing component cannot lean on Ink for this: the string it builds
  * (a box-drawing frame, a sparkline, a table grid) is a fixed block of
@@ -13,9 +12,8 @@
  * `<Text>` renders it verbatim rather than reflowing pre-drawn glyphs. This
  * module is therefore kept as a small, PRIVATE (not exported from
  * `src/index.ts`) implementation detail of those few components, replacing
- * the old public `measure.ts`/`box.ts` modules the batch-10 brief has this
- * engine delete. The width-measurement approximation is unchanged from the
- * old `measure.ts`: Latin/CJK/emoji/combining-mark ranges, not a full
+ * the old public `measure.ts`/`box.ts` modules. The width-measurement
+ * approximation covers Latin/CJK/emoji/combining-mark ranges, not a full
  * Unicode grapheme-segmentation table (see the doc comment below for the one
  * documented limitation).
  */

package/dist/value-types.d.ts

@@ -1,7 +1,7 @@
 /**
  * `@markii/ansi`'s own structural view of `@markii/runtime`'s value-store
  * contract. This package's dependency list is deliberately minimal (exactly
- * `@markii/core` and `@markii/stdlib`; see AGENTS.md and the batch brief),
+ * `@markii/core` and `@markii/stdlib`; see AGENTS.md),
  * so it never imports `@markii/runtime` at runtime: declaring the shapes it
  * needs here, rather than importing them, keeps a terminal render usable in
  * a context that never pulled in the runtime package at all (a CLI that

package/dist/value-types.js

@@ -1,7 +1,7 @@
 /**
  * `@markii/ansi`'s own structural view of `@markii/runtime`'s value-store
  * contract. This package's dependency list is deliberately minimal (exactly
- * `@markii/core` and `@markii/stdlib`; see AGENTS.md and the batch brief),
+ * `@markii/core` and `@markii/stdlib`; see AGENTS.md),
  * so it never imports `@markii/runtime` at runtime: declaring the shapes it
  * needs here, rather than importing them, keeps a terminal render usable in
  * a context that never pulled in the runtime package at all (a CLI that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/ansi",
-  "version": "0.17.0-next.1",
+  "version": "0.17.0-next.3",
   "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.1",
-    "@markii/pack": "^0.17.0-next.1",
-    "@markii/stdlib": "^0.17.0-next.1",
+    "@markii/core": "^0.17.0-next.3",
+    "@markii/pack": "^0.17.0-next.3",
+    "@markii/stdlib": "^0.17.0-next.3",
     "ink": "^7.1.1",
     "react": "^19.2.0"
   },
   "devDependencies": {
     "@types/hast": "^3.0.4",
-    "@markii/runtime": "^0.17.0-next.1",
+    "@markii/runtime": "^0.17.0-next.3",
     "@types/react": "^19.2.0"
   }
 }