@markii/ansi 0.16.0 → 0.17.0-next.1

package/dist/pack-loader.d.ts

@@ -0,0 +1,64 @@
+import type { PackManifest } from '@markii/pack';
+import type { AnsiRegistry, AnsiRegistryEntry } from './registry.js';
+/**
+ * This engine's id in a pack manifest's per-component `sources` map
+ * (docs/packs.md). A component with an `ansi` source has a terminal view.
+ */
+export declare const ANSI_ENGINE_ID = "ansi";
+/**
+ * The component modules a host hands to `loadAnsiPack`, keyed by the
+ * manifest's LOCAL component name. Each is the `{ component, inline? }`
+ * pair a pack's `terminal.js` registered (`./pack-script.ts`).
+ */
+export type AnsiPackComponentModules = Record<string, AnsiRegistryEntry>;
+/**
+ * Returns `value` with every string in it run through
+ * `stripControlCharacters`, so a pack that prints a stored value cannot
+ * print a control character a script smuggled in. Arrays and plain objects
+ * are copied (null-prototype for objects, hasOwn-guarded), never mutated.
+ * Anything past `MAX_SANITIZE_DEPTH`, and every non-JSON value, becomes
+ * `undefined`. Never throws: a throwing getter reads as `undefined`.
+ */
+export declare function sanitizeValueForPack(value: unknown, depth?: number): unknown;
+/** What `loadAnsiPack` reports about a pack it could not run. */
+export interface LoadAnsiPackResult {
+    registry: AnsiRegistry;
+    /** Present when the pack has components but none has an `ansi` source: the pack contributes nothing. `engine` names the engines it does declare. */
+    dropped?: {
+        name: string;
+        engine: string;
+    };
+}
+/**
+ * Loads one pack's terminal components into a namespaced `AnsiRegistry`,
+ * mirroring `@markii/react`'s `loadPack`: gating is per component (only
+ * components with an `ansi` source register; the rest fall back to the
+ * unknown-component box), a manifest component with no module is skipped,
+ * a stray module is ignored, and a declared `kind` decides the `inline`
+ * flag. Reads are `Object.hasOwn`-guarded. Never throws.
+ */
+export declare function loadAnsiPack(manifest: PackManifest, componentModules: AnsiPackComponentModules): LoadAnsiPackResult;
+/** One pack ready to install: its manifest plus its registered component modules. */
+export interface AnsiPackToInstall {
+    manifest: PackManifest;
+    componentModules: AnsiPackComponentModules;
+}
+export type InstallAnsiPacksResult = {
+    ok: true;
+    registry: AnsiRegistry;
+    dropped: {
+        name: string;
+        engine: string;
+    }[];
+} | {
+    ok: false;
+    collisions: readonly string[];
+};
+/**
+ * Installs several packs into one registry on top of `base`, rejecting the
+ * whole install when two share a namespace (the install-time rule in
+ * docs/packs.md), exactly like `@markii/react`'s `installPacks`. A host
+ * that wants keep-first behavior (a bundled pack wins over a user pack of
+ * the same namespace) filters the list before calling.
+ */
+export declare function installAnsiPacks(packs: readonly AnsiPackToInstall[], base?: AnsiRegistry): InstallAnsiPacksResult;

package/dist/pack-loader.js

@@ -0,0 +1,172 @@
+import { composeDirectiveName, detectNamespaceCollisions, packComponentsForEngine, packDeclaredEngines, packSupportsEngine, } from '@markii/pack';
+import { createAnsiRegistry, mergeAnsiRegistries } from './registry.js';
+import { stripControlCharacters } from './sanitize.js';
+/**
+ * This engine's id in a pack manifest's per-component `sources` map
+ * (docs/packs.md). A component with an `ansi` source has a terminal view.
+ */
+export const ANSI_ENGINE_ID = 'ansi';
+/** The deepest a stored value is walked when sanitizing it for a pack. */
+const MAX_SANITIZE_DEPTH = 16;
+/**
+ * Returns `value` with every string in it run through
+ * `stripControlCharacters`, so a pack that prints a stored value cannot
+ * print a control character a script smuggled in. Arrays and plain objects
+ * are copied (null-prototype for objects, hasOwn-guarded), never mutated.
+ * Anything past `MAX_SANITIZE_DEPTH`, and every non-JSON value, becomes
+ * `undefined`. Never throws: a throwing getter reads as `undefined`.
+ */
+export function sanitizeValueForPack(value, depth = 0) {
+    if (depth > MAX_SANITIZE_DEPTH)
+        return undefined;
+    if (typeof value === 'string')
+        return stripControlCharacters(value);
+    if (value === null ||
+        typeof value === 'number' ||
+        typeof value === 'boolean') {
+        return value;
+    }
+    try {
+        if (Array.isArray(value)) {
+            return value.map((item) => sanitizeValueForPack(item, depth + 1));
+        }
+        if (typeof value === 'object') {
+            const out = Object.create(null);
+            for (const key of Object.keys(value)) {
+                if (!Object.hasOwn(value, key))
+                    continue;
+                out[stripControlCharacters(key)] = sanitizeValueForPack(value[key], depth + 1);
+            }
+            return out;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+/** A copy of `attributes` with every string value (and key) stripped of control characters. A bare attribute stays `null`. */
+function sanitizeAttributes(attributes) {
+    const out = Object.create(null);
+    try {
+        for (const key of Object.keys(attributes)) {
+            if (!Object.hasOwn(attributes, key))
+                continue;
+            const raw = attributes[key];
+            out[stripControlCharacters(key)] =
+                typeof raw === 'string' ? stripControlCharacters(raw) : raw;
+        }
+    }
+    catch {
+        // A hostile attribute object yields whatever copied so far.
+    }
+    return out;
+}
+/**
+ * The ctx a pack component receives: the engine's ctx with `resolve` and
+ * `data` replaced by sanitized-copy versions. `ctx.text` stays the engine's
+ * sanitizer, the way a pack prints any other string it composes.
+ */
+function packContext(ctx) {
+    const packCtx = {
+        ...ctx,
+        resolve: (name) => {
+            const resolution = ctx.resolve(name);
+            return {
+                ...resolution,
+                value: sanitizeValueForPack(resolution.value),
+                ...(resolution.error !== undefined
+                    ? { error: stripControlCharacters(resolution.error) }
+                    : {}),
+            };
+        },
+    };
+    if ('data' in ctx)
+        packCtx.data = sanitizeValueForPack(ctx.data);
+    if (ctx.dataError !== undefined) {
+        packCtx.dataError = stripControlCharacters(ctx.dataError);
+    }
+    return packCtx;
+}
+/**
+ * Wraps a pack's component so the engine, not the pack, decides what text
+ * reaches it. The wrapper sanitizes the attributes and the stored-value
+ * view of the ctx before calling the pack, and a throw inside the pack's
+ * render is contained by the walk's existing per-component boundary.
+ *
+ * This bounds what AUTHOR text can do through a pack. It cannot bound the
+ * pack's own code: a terminal pack runs in the host's process with the
+ * host's privileges and can write to stdout itself (docs/security.md).
+ */
+function wrapPackComponent(component) {
+    // Called as a plain function, like every registry component: it returns
+    // a string or an Ink element (the engine lays the element out at the
+    // directive's width). Components the pack's view renders INSIDE that
+    // element are ordinary React components and may use hooks.
+    return function PackComponent(props) {
+        return component({
+            attributes: sanitizeAttributes(props.attributes),
+            children: props.children,
+            ctx: packContext(props.ctx),
+        });
+    };
+}
+/**
+ * Loads one pack's terminal components into a namespaced `AnsiRegistry`,
+ * mirroring `@markii/react`'s `loadPack`: gating is per component (only
+ * components with an `ansi` source register; the rest fall back to the
+ * unknown-component box), a manifest component with no module is skipped,
+ * a stray module is ignored, and a declared `kind` decides the `inline`
+ * flag. Reads are `Object.hasOwn`-guarded. Never throws.
+ */
+export function loadAnsiPack(manifest, componentModules) {
+    if (!packSupportsEngine(manifest, ANSI_ENGINE_ID)) {
+        return {
+            registry: createAnsiRegistry(),
+            dropped: { name: manifest.name, engine: packDeclaredEngines(manifest) },
+        };
+    }
+    const entries = {};
+    for (const { localName, kind } of packComponentsForEngine(manifest, ANSI_ENGINE_ID)) {
+        if (!Object.hasOwn(componentModules, localName))
+            continue;
+        const module = componentModules[localName];
+        if (module == null || typeof module.component !== 'function')
+            continue;
+        const composed = composeDirectiveName(manifest.name, localName);
+        if (!composed.ok)
+            continue;
+        const entry = {
+            component: wrapPackComponent(module.component),
+        };
+        const inline = kind === undefined ? module.inline : kind === 'inline';
+        if (inline !== undefined)
+            entry.inline = inline;
+        entries[composed.name] = entry;
+    }
+    return { registry: createAnsiRegistry(entries) };
+}
+/**
+ * Installs several packs into one registry on top of `base`, rejecting the
+ * whole install when two share a namespace (the install-time rule in
+ * docs/packs.md), exactly like `@markii/react`'s `installPacks`. A host
+ * that wants keep-first behavior (a bundled pack wins over a user pack of
+ * the same namespace) filters the list before calling.
+ */
+export function installAnsiPacks(packs, base = createAnsiRegistry()) {
+    const collisions = detectNamespaceCollisions(packs.map((pack) => pack.manifest.name));
+    if (collisions.length > 0) {
+        return {
+            ok: false,
+            collisions: collisions.map((collision) => collision.namespace),
+        };
+    }
+    const dropped = [];
+    const loaded = packs.map((pack) => {
+        const result = loadAnsiPack(pack.manifest, pack.componentModules);
+        if (result.dropped)
+            dropped.push(result.dropped);
+        return result.registry;
+    });
+    return { ok: true, registry: mergeAnsiRegistries(base, ...loaded), dropped };
+}

package/dist/pack-script.d.ts

@@ -0,0 +1,44 @@
+import type { AnsiPackToInstall } from './pack-loader.js';
+/**
+ * The terminal pack registration contract (docs/packs.md). A pack's
+ * prebuilt `terminal.js` is an ESM module. On evaluation it calls
+ *
+ *   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
+ * `__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
+ * exports) and a pack reads them only inside render-time functions, so
+ * evaluating the script with both undefined must not throw.
+ *
+ * SECURITY: evaluating this script runs the pack's code in the calling
+ * process with that process's full privileges. Only a host's own device-
+ * local install store and bundled packs may reach `loadTerminalPackScript`:
+ * never a note, a bundle, the working directory, or an environment
+ * variable (docs/security.md).
+ */
+export declare const TERMINAL_REGISTER_GLOBAL = "__markiiRegisterTerminalPack";
+export declare const TERMINAL_REACT_GLOBAL = "__markiiReactInk";
+export declare const TERMINAL_INK_GLOBAL = "__markiiInk";
+/**
+ * Publishes this package's own React and Ink instances for pack scripts to
+ * read at render time. Idempotent. Left in place for the life of the
+ * process, since a pack reads them each time its component renders.
+ */
+export declare function installTerminalPackGlobals(): void;
+export type LoadTerminalPackScriptResult = {
+    ok: true;
+    pack: AnsiPackToInstall;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Evaluates one pack's `terminal.js` text and returns the validated pack
+ * ready for `installAnsiPacks`, or the reason it could not be used. Never
+ * rejects. SECURITY: runs the script's code in this process; see the
+ * module comment for who may call it.
+ */
+export declare function loadTerminalPackScript(scriptText: string): Promise<LoadTerminalPackScriptResult>;

package/dist/pack-script.js

@@ -0,0 +1,135 @@
+import * as React from 'react';
+import * as Ink from 'ink';
+import { parsePackManifest } from '@markii/pack';
+/**
+ * The terminal pack registration contract (docs/packs.md). A pack's
+ * prebuilt `terminal.js` is an ESM module. On evaluation it calls
+ *
+ *   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
+ * `__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
+ * exports) and a pack reads them only inside render-time functions, so
+ * evaluating the script with both undefined must not throw.
+ *
+ * SECURITY: evaluating this script runs the pack's code in the calling
+ * process with that process's full privileges. Only a host's own device-
+ * local install store and bundled packs may reach `loadTerminalPackScript`:
+ * never a note, a bundle, the working directory, or an environment
+ * variable (docs/security.md).
+ */
+export const TERMINAL_REGISTER_GLOBAL = '__markiiRegisterTerminalPack';
+export const TERMINAL_REACT_GLOBAL = '__markiiReactInk';
+export const TERMINAL_INK_GLOBAL = '__markiiInk';
+/**
+ * Publishes this package's own React and Ink instances for pack scripts to
+ * read at render time. Idempotent. Left in place for the life of the
+ * process, since a pack reads them each time its component renders.
+ */
+export function installTerminalPackGlobals() {
+    const g = globalThis;
+    g[TERMINAL_REACT_GLOBAL] = React;
+    g[TERMINAL_INK_GLOBAL] = Ink;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Own-property validation of the registered map, same rule as the webview convention. */
+function toComponentModules(value) {
+    if (!isPlainObject(value))
+        return undefined;
+    const out = Object.create(null);
+    for (const key of Object.keys(value)) {
+        if (!Object.hasOwn(value, key))
+            continue;
+        const entry = value[key];
+        if (!isPlainObject(entry) || typeof entry.component !== 'function') {
+            return undefined;
+        }
+        if (Object.hasOwn(entry, 'inline') && typeof entry.inline !== 'boolean') {
+            return undefined;
+        }
+        out[key] = {
+            component: entry.component,
+            ...(typeof entry.inline === 'boolean' ? { inline: entry.inline } : {}),
+        };
+    }
+    return out;
+}
+// Evaluations are serialized: the register hook is one process global.
+let queue = Promise.resolve();
+let nonce = 0;
+async function evaluate(scriptText) {
+    installTerminalPackGlobals();
+    const g = globalThis;
+    const previous = g[TERMINAL_REGISTER_GLOBAL];
+    const registrations = [];
+    g[TERMINAL_REGISTER_GLOBAL] = (manifestJson, modules) => {
+        registrations.push({ manifestJson, modules });
+    };
+    try {
+        nonce += 1;
+        const source = `${scriptText}\n//# markiiTerminalPack=${String(nonce)}`;
+        const url = `data:text/javascript;base64,${Buffer.from(source, 'utf8').toString('base64')}`;
+        try {
+            await import(/* @vite-ignore */ url);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            return {
+                ok: false,
+                reason: `terminal.js threw while loading: ${detail}`,
+            };
+        }
+    }
+    finally {
+        if (previous === undefined)
+            delete g[TERMINAL_REGISTER_GLOBAL];
+        else
+            g[TERMINAL_REGISTER_GLOBAL] = previous;
+    }
+    if (registrations.length !== 1) {
+        return {
+            ok: false,
+            reason: registrations.length === 0
+                ? `terminal.js did not call ${TERMINAL_REGISTER_GLOBAL}`
+                : `terminal.js called ${TERMINAL_REGISTER_GLOBAL} ${String(registrations.length)} times; exactly one registration is allowed`,
+        };
+    }
+    const { manifestJson, modules } = registrations[0];
+    if (typeof manifestJson !== 'string') {
+        return {
+            ok: false,
+            reason: 'terminal.js did not provide a manifest JSON string',
+        };
+    }
+    const parsed = parsePackManifest(manifestJson);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            reason: `terminal.js manifest is invalid (${parsed.errors.join('; ')})`,
+        };
+    }
+    const componentModules = toComponentModules(modules);
+    if (componentModules === undefined) {
+        return { ok: false, reason: 'terminal.js registered malformed components' };
+    }
+    return { ok: true, pack: { manifest: parsed.manifest, componentModules } };
+}
+/**
+ * Evaluates one pack's `terminal.js` text and returns the validated pack
+ * ready for `installAnsiPacks`, or the reason it could not be used. Never
+ * rejects. SECURITY: runs the script's code in this process; see the
+ * module comment for who may call it.
+ */
+export function loadTerminalPackScript(scriptText) {
+    const run = queue.then(() => evaluate(scriptText));
+    queue = run.catch(() => undefined);
+    return run.catch((error) => ({
+        ok: false,
+        reason: `terminal.js could not be evaluated: ${error instanceof Error ? error.message : String(error)}`,
+    }));
+}

package/dist/registry.d.ts

@@ -3,6 +3,7 @@ import type { FailureKind, ValueStatus } from './value-types.js';
 import type { LayoutAxis, OnDiagnostic } from '@markii/stdlib';
 import type { ColorLevel } from './ansi.js';
 import type { AnsiTheme, Tier1Token } from './theme.js';
+import type { GlyphSet } from './glyphs.js';
 import type { ResolvedLayoutAttributes } from './layout.js';
 import type { ResolveImageSrc } from './image-resolve.js';
 import type { ResolveHref } from './href-resolve.js';
@@ -63,6 +64,12 @@ export interface AnsiRenderContext {
     color: ColorLevel;
     /** The resolved theme for this render. */
     theme: AnsiTheme;
+    /**
+     * The glyphs for this render's box style (`./glyphs.ts`). A component that
+     * draws a frame, rule, bar, or symbol takes it from here, never from a
+     * literal, so `box: 'ascii'` reaches it.
+     */
+    glyphs: GlyphSet;
     /**
      * Whether this render is in INTERACTIVE mode (a live viewer), as opposed
      * to the default render-once mode. NAME COLLISION, documented at both
@@ -109,6 +116,14 @@ export interface AnsiRenderContext {
     dataStatus?: ValueStatus;
     dataError?: string;
     dataFailureKind?: FailureKind;
+    /**
+     * The engine's quiet trailing marker for this binding's state, e.g.
+     * ` (script error)` or ` (stale)`, and `''` for a fresh or missing one.
+     * Present with `data`. A component that cannot import the engine's
+     * failure-presentation module (a terminal pack, which only sees this
+     * context) appends it so the wording stays in one place.
+     */
+    dataSuffix?: string;
     /**
      * The resolved width/align presets for the axis a layout-scope entry does
      * not already own — this engine's counterpart to `@markii/html`'s

package/dist/render.d.ts

@@ -4,27 +4,67 @@ import type { MarkNode } from '@markii/core';
 import { type ColorOption } from './ansi.js';
 import { type AnsiTheme } from './theme.js';
 import type { AnsiRegistry } from './registry.js';
-import { type OnDiagnostic } from '@markii/stdlib';
+import { type OnDiagnostic, type UnavailableComponent } from '@markii/stdlib';
 import { type ResolveImageSrc } from './image-resolve.js';
 import { type ResolveHref } from './href-resolve.js';
 import type { AnsiValueStore, AnsiVaultStore } from './value-types.js';
+import { type BoxStyle } from './glyphs.js';
 type MarkRoot = ReturnType<typeof parse>;
 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;
+    /**
+     * `'unicode'` (the default) draws frames, rules, bars, and markers with
+     * box-drawing and symbol characters; `'ascii'` draws every one of them
+     * with 7-bit characters, for a terminal that cannot show the others. The
+     * engine never chooses this from the environment: the host does.
+     */
+    readonly box?: BoxStyle;
     readonly resolveImageSrc?: ResolveImageSrc;
     readonly resolveHref?: ResolveHref;
     readonly onDiagnostic?: OnDiagnostic;
+    /**
+     * Components of installed packs that this render cannot draw, as plain
+     * data from the host. A directive named here renders the usual fallback
+     * with the label "no terminal view for" instead of "unknown component",
+     * and `onDiagnostic` gets a `'no-engine-view'` event. Omitted, the render
+     * is unchanged.
+     */
+    readonly unavailableComponents?: readonly UnavailableComponent[];
     readonly store?: AnsiValueStore;
     readonly vault?: AnsiVaultStore;
     /**
@@ -37,6 +77,13 @@ export interface RenderMarkOptions {
      * every panel/always-open exactly as the pre-Ink engine did.
      */
     readonly interactive?: boolean;
+    /**
+     * `buildMarkElement` only: the terminal's row count. Gives the live view
+     * a viewport of this many rows minus its one-row status line, scrolled
+     * with the keys in the legend. Omitted, the live view is laid out at its
+     * full height. The render-once string path never reads it.
+     */
+    readonly viewportRows?: number;
 }
 /**
  * Renders Markii text to a plain string (optionally carrying ANSI SGR/OSC 8