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

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/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

@@ -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

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, 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';
@@ -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'));
@@ -1241,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'));
@@ -1312,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') {
@@ -1409,6 +1479,23 @@ 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. */
@@ -1443,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, 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 +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, 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);
@@ -1522,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, 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/package.json

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