@markii/ansi 0.0.1

package/dist/ansi.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The escape-sequence primitives and color model this engine is built on.
+ * Every helper here returns a string with no escape state left open: a
+ * sequence a helper opens, it closes within the same returned string, so
+ * concatenating helper outputs can never leak color or style into text a
+ * later helper did not intend to touch.
+ *
+ * The engine never decides for itself whether color is appropriate: it has
+ * no access to `process`, `stdout`, or the environment (`detectColorLevel`
+ * takes both as explicit parameters), so a caller that wants automatic
+ * detection has to ask for it and hand back the answer.
+ */
+/** What this engine will actually emit: no escapes at all, or one of three color depths. */
+export type ColorLevel = 'none' | '16' | '256' | 'truecolor';
+/** What a caller asks for. `'auto'` defers to `detectColorLevel`; see `resolveColorOption` for why an unresolved `'auto'` never reaches the renderer as a level on its own. */
+export type ColorOption = 'auto' | 'never' | '16' | '256' | 'truecolor';
+/**
+ * One theme color, carrying all three depths a terminal might support so
+ * `fg` can pick the right one without recomputing anything at render time.
+ * `ansi16` is an SGR foreground code: 30-37 for the eight standard colors,
+ * 90-97 for their bright counterparts.
+ */
+export interface AnsiColor {
+    ansi16: number;
+    ansi256: number;
+    truecolor: readonly [number, number, number];
+}
+/** The SGR sequence that sets `color` as the foreground at `level`, or `''` at `'none'`. */
+export declare function fg(color: AnsiColor, level: ColorLevel): string;
+/** Wraps `text` in `color`'s foreground SGR at `level`, resetting after and restoring the color after any reset `text` carried. Unchanged at `'none'`. */
+export declare function colorize(text: string, color: AnsiColor, level: ColorLevel): string;
+/** SGR bold (1). Returns `text` unchanged at `'none'`. */
+export declare const bold: (text: string, level: ColorLevel) => string;
+/** SGR dim/faint (2). Returns `text` unchanged at `'none'`. */
+export declare const dim: (text: string, level: ColorLevel) => string;
+/** SGR italic (3). Returns `text` unchanged at `'none'`. */
+export declare const italic: (text: string, level: ColorLevel) => string;
+/** SGR underline (4). Returns `text` unchanged at `'none'`. */
+export declare const underline: (text: string, level: ColorLevel) => string;
+/** SGR inverse/reverse video (7). Returns `text` unchanged at `'none'`. */
+export declare const inverse: (text: string, level: ColorLevel) => string;
+/**
+ * OSC 8: `ESC ] 8 ; ; url BEL text ESC ] 8 ; ; BEL`. Emitted only when
+ * `level` is not `'none'`; at `'none'` this returns `text` UNCHANGED, and
+ * the CALLER is responsible for appending the `(url)` form itself (this
+ * function has no opinion on that wording; `render.ts` and the
+ * failure-presentation module own it). The split exists because a
+ * plain-text render (`'none'`) still wants the URL visible somewhere, while
+ * a color-capable terminal gets the real clickable link instead.
+ */
+export declare function hyperlink(text: string, url: string, level: ColorLevel): string;
+/**
+ * Reads color intent from an environment map and TTY flag, following (in
+ * order): `NO_COLOR` (any non-empty value forces `'none'`, per the
+ * no-color.org convention) beats everything else; `FORCE_COLOR` (`0` forces
+ * `'none'`, `1`/`true` forces `'16'`, `2` forces `'256'`, `3` forces
+ * `'truecolor'`) beats the TTY check; a non-TTY output forces `'none'`
+ * (piping to a file or another program should never carry escape codes
+ * unless the caller explicitly forced one above); `TERM=dumb` forces
+ * `'none'`; `COLORTERM` of `truecolor`/`24bit` forces `'truecolor'`; a
+ * `TERM` containing `256color` gives `'256'`; anything else that got this
+ * far gets the conservative `'16'`.
+ *
+ * Reads NOTHING itself: no `process`, no `globalThis`. A caller (a CLI's
+ * entry point, typically) supplies `env` and `isTTY` explicitly.
+ */
+export declare function detectColorLevel(env: Record<string, string | undefined>, isTTY: boolean): ColorLevel;
+/**
+ * Resolves a caller-supplied `ColorOption` to the `ColorLevel` this engine
+ * will actually use. `'never'` and `'auto'` BOTH resolve to `'none'` here:
+ * the engine has no environment knowledge of its own (see this module's top
+ * comment) and must never emit an escape it cannot justify, so `'auto'`
+ * detection is entirely the caller's job via `detectColorLevel` — a caller
+ * that wants automatic detection calls that function itself and passes the
+ * resulting level in directly, rather than passing `'auto'` through to this
+ * engine and hoping it guesses right. `undefined` behaves exactly like
+ * `'auto'`.
+ */
+export declare function resolveColorOption(option: ColorOption | undefined): ColorLevel;

package/dist/ansi.js

@@ -0,0 +1,136 @@
+/**
+ * The escape-sequence primitives and color model this engine is built on.
+ * Every helper here returns a string with no escape state left open: a
+ * sequence a helper opens, it closes within the same returned string, so
+ * concatenating helper outputs can never leak color or style into text a
+ * later helper did not intend to touch.
+ *
+ * The engine never decides for itself whether color is appropriate: it has
+ * no access to `process`, `stdout`, or the environment (`detectColorLevel`
+ * takes both as explicit parameters), so a caller that wants automatic
+ * detection has to ask for it and hand back the answer.
+ */
+const ESC = '\x1b';
+const RESET = `${ESC}[0m`;
+/** The SGR sequence that sets `color` as the foreground at `level`, or `''` at `'none'`. */
+export function fg(color, level) {
+    if (level === 'none')
+        return '';
+    if (level === '16')
+        return `${ESC}[${color.ansi16}m`;
+    if (level === '256')
+        return `${ESC}[38;5;${color.ansi256}m`;
+    const [r, g, b] = color.truecolor;
+    return `${ESC}[38;2;${r};${g};${b}m`;
+}
+/**
+ * Wraps `text` in `open`, closes with a full reset, and re-opens `open`
+ * after every reset `text` already contained.
+ *
+ * Every helper in this module closes with SGR 0, which resets ALL
+ * attributes rather than only the one it set, because SGR has no "undo just
+ * this" code a renderer can rely on across terminals. That makes the
+ * helpers safe to concatenate but not, on its own, safe to NEST: a dim
+ * frame holding one colored word would lose its dim from that word onward,
+ * since the word's own reset clears the frame's attribute too. Re-opening
+ * after each inner reset restores the outer attribute for the remainder, so
+ * a component can style text that other components already styled without
+ * having to know what they did. The cost is one extra sequence per nesting
+ * point, which is invisible in the terminal and stable in a fixture.
+ */
+function wrapSgr(text, open) {
+    const restored = text.includes(RESET)
+        ? text.split(RESET).join(`${RESET}${open}`)
+        : text;
+    return `${open}${restored}${RESET}`;
+}
+/** Wraps `text` in `color`'s foreground SGR at `level`, resetting after and restoring the color after any reset `text` carried. Unchanged at `'none'`. */
+export function colorize(text, color, level) {
+    if (level === 'none')
+        return text;
+    return wrapSgr(text, fg(color, level));
+}
+function sgrWrap(code) {
+    return (text, level) => level === 'none' ? text : wrapSgr(text, `${ESC}[${code}m`);
+}
+/** SGR bold (1). Returns `text` unchanged at `'none'`. */
+export const bold = sgrWrap(1);
+/** SGR dim/faint (2). Returns `text` unchanged at `'none'`. */
+export const dim = sgrWrap(2);
+/** SGR italic (3). Returns `text` unchanged at `'none'`. */
+export const italic = sgrWrap(3);
+/** SGR underline (4). Returns `text` unchanged at `'none'`. */
+export const underline = sgrWrap(4);
+/** SGR inverse/reverse video (7). Returns `text` unchanged at `'none'`. */
+export const inverse = sgrWrap(7);
+/**
+ * OSC 8: `ESC ] 8 ; ; url BEL text ESC ] 8 ; ; BEL`. Emitted only when
+ * `level` is not `'none'`; at `'none'` this returns `text` UNCHANGED, and
+ * the CALLER is responsible for appending the `(url)` form itself (this
+ * function has no opinion on that wording; `render.ts` and the
+ * failure-presentation module own it). The split exists because a
+ * plain-text render (`'none'`) still wants the URL visible somewhere, while
+ * a color-capable terminal gets the real clickable link instead.
+ */
+export function hyperlink(text, url, level) {
+    if (level === 'none')
+        return text;
+    return `${ESC}]8;;${url}\x07${text}${ESC}]8;;\x07`;
+}
+/**
+ * Reads color intent from an environment map and TTY flag, following (in
+ * order): `NO_COLOR` (any non-empty value forces `'none'`, per the
+ * no-color.org convention) beats everything else; `FORCE_COLOR` (`0` forces
+ * `'none'`, `1`/`true` forces `'16'`, `2` forces `'256'`, `3` forces
+ * `'truecolor'`) beats the TTY check; a non-TTY output forces `'none'`
+ * (piping to a file or another program should never carry escape codes
+ * unless the caller explicitly forced one above); `TERM=dumb` forces
+ * `'none'`; `COLORTERM` of `truecolor`/`24bit` forces `'truecolor'`; a
+ * `TERM` containing `256color` gives `'256'`; anything else that got this
+ * far gets the conservative `'16'`.
+ *
+ * Reads NOTHING itself: no `process`, no `globalThis`. A caller (a CLI's
+ * entry point, typically) supplies `env` and `isTTY` explicitly.
+ */
+export function detectColorLevel(env, isTTY) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== '')
+        return 'none';
+    const forceColor = env.FORCE_COLOR;
+    if (forceColor !== undefined) {
+        if (forceColor === '0')
+            return 'none';
+        if (forceColor === '1' || forceColor === 'true')
+            return '16';
+        if (forceColor === '2')
+            return '256';
+        if (forceColor === '3')
+            return 'truecolor';
+    }
+    if (!isTTY)
+        return 'none';
+    if (env.TERM === 'dumb')
+        return 'none';
+    const colorterm = env.COLORTERM;
+    if (colorterm === 'truecolor' || colorterm === '24bit')
+        return 'truecolor';
+    if (env.TERM?.includes('256color'))
+        return '256';
+    return '16';
+}
+/**
+ * Resolves a caller-supplied `ColorOption` to the `ColorLevel` this engine
+ * will actually use. `'never'` and `'auto'` BOTH resolve to `'none'` here:
+ * the engine has no environment knowledge of its own (see this module's top
+ * comment) and must never emit an escape it cannot justify, so `'auto'`
+ * detection is entirely the caller's job via `detectColorLevel` — a caller
+ * that wants automatic detection calls that function itself and passes the
+ * resulting level in directly, rather than passing `'auto'` through to this
+ * engine and hoping it guesses right. `undefined` behaves exactly like
+ * `'auto'`.
+ */
+export function resolveColorOption(option) {
+    if (option === '16' || option === '256' || option === 'truecolor') {
+        return option;
+    }
+    return 'none';
+}

package/dist/box.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Greedy word wrap to `width` columns. An existing `\n` is a hard break
+ * (each hard-broken segment is wrapped independently); a word wider than
+ * `width` on its own is broken at the width boundary via `breakLongWord`
+ * rather than overflowing the line.
+ */
+export declare function wrap(text: string, width: number): string[];
+/** Pads `text` to `width` columns with spaces, aligned `left`/`center`/`right`. A `text` already at or over `width` is returned unchanged. */
+export declare function pad(text: string, width: number, align: 'left' | 'center' | 'right'): string;
+/**
+ * Re-wraps a block of text that was already wrapped to a WIDER budget than
+ * `width` (the shape a component's pre-rendered `childrenText` always
+ * arrives in: `render.ts` wraps a directive's body to the full directive
+ * width before the component ever runs, since a container component that
+ * draws its own frame or indent — `card`, `callout`, `details`, `figure` —
+ * only learns it needs a NARROWER inner budget once it starts drawing).
+ * Every existing `\n` is a hard break, each hard-broken line re-wrapped
+ * independently if it still overflows `width`; a line already inside the
+ * budget passes through unchanged. Mirrors the same pattern `render.ts`'s
+ * `unknownDirective` fallback already uses for its dashed frame.
+ */
+export declare function rewrapBlock(text: string, width: number): string;
+/** Prefixes every line of `block` (split on `\n`) with `prefix`, e.g. a blockquote's `│ `. */
+export declare function indentBlock(block: string, prefix: string): string;
+/**
+ * Places `blocks` side by side, each padded (left-aligned) to its entry in
+ * `widths`, joined by `gutter` spaces, top-aligned: a block with fewer
+ * lines than its neighbors gets its missing rows filled with blank,
+ * full-width padding rather than leaving a ragged gap.
+ */
+export declare function columns(blocks: readonly string[], widths: readonly number[], gutter: number): string;
+/** `frame`'s options: which glyph set to draw with, an optional title woven into the top edge, and the frame's total outer width (borders included). */
+export interface FrameOptions {
+    style: 'solid' | 'dashed';
+    title?: string;
+    width: number;
+}
+/**
+ * Draws a box around `block`: `┌ ─ ┐ │ └ ┘` for `'solid'`, `┌ ╌ ┐ ┆ └ ┘` for
+ * `'dashed'` (the corners are shared; only the edge glyphs change). A
+ * `title` is woven into the top edge as `┌─ title ────┐`. Every content
+ * line is padded to the frame's inner width, so every drawn line is exactly
+ * `options.width` columns wide.
+ */
+export declare function frame(block: string, options: FrameOptions): string;
+/** A full-width horizontal rule, `char` (default `─`) repeated to `width` columns. */
+export declare function rule(width: number, char?: string): string;

package/dist/box.js

@@ -0,0 +1,209 @@
+import { measure } from './measure.js';
+/**
+ * Hand-written, width-aware layout helpers: wrapping, padding, side-by-side
+ * columns, and box drawing. Every measurement goes through `./measure.ts`,
+ * so these helpers wrap and pad correctly around colored text, wide CJK
+ * characters, and emoji, not just plain ASCII. None of these read the
+ * theme; they take and return plain strings, leaving color entirely to
+ * `./style.ts` and the caller.
+ *
+ * `wrap`'s word-splitting collapses runs of spaces to one, the ordinary
+ * behavior of a text wrapper: exact inter-word spacing is not something a
+ * terminal reflow is expected to preserve.
+ */
+const ESCAPE_PATTERN = /\x1b\[[0-9;]*m|\x1b\]8;;[^\x07\x1b]*\x07/g;
+/**
+ * Splits `text` into atoms an escape sequence never gets split across: each
+ * escape sequence is its own zero-width atom, and every other code point is
+ * its own atom carrying `measure`'s width for that single code point. A
+ * combining mark or variation selector that only reads as zero-width in
+ * context with its BASE character (see `./measure.ts`'s module comment)
+ * still measures correctly here, because it is itself in the zero-width/
+ * combining ranges regardless of what precedes it; the one case this
+ * under- or over-counts by a column is the dingbat-plus-variation-selector
+ * pair (`☀️`), which needs to see both code points at once to know it
+ * should measure 2 — an accepted instance of `./measure.ts`'s documented
+ * approximation.
+ */
+function tokenize(text) {
+    const atoms = [];
+    let lastIndex = 0;
+    let match;
+    ESCAPE_PATTERN.lastIndex = 0;
+    while ((match = ESCAPE_PATTERN.exec(text)) !== null) {
+        if (match.index > lastIndex) {
+            pushChars(atoms, text.slice(lastIndex, match.index));
+        }
+        atoms.push({ text: match[0], width: 0 });
+        lastIndex = match.index + match[0].length;
+    }
+    if (lastIndex < text.length)
+        pushChars(atoms, text.slice(lastIndex));
+    return atoms;
+}
+function pushChars(atoms, plain) {
+    for (const char of plain) {
+        atoms.push({ text: char, width: measure(char) });
+    }
+}
+/** Breaks one over-long word into chunks of at most `width` columns, never splitting an escape sequence. */
+function breakLongWord(word, width) {
+    const atoms = tokenize(word);
+    const chunks = [];
+    let current = '';
+    let currentWidth = 0;
+    for (const atom of atoms) {
+        if (currentWidth + atom.width > width && current !== '') {
+            chunks.push(current);
+            current = '';
+            currentWidth = 0;
+        }
+        current += atom.text;
+        currentWidth += atom.width;
+    }
+    if (current !== '')
+        chunks.push(current);
+    return chunks.length > 0 ? chunks : [''];
+}
+/**
+ * Greedy word wrap to `width` columns. An existing `\n` is a hard break
+ * (each hard-broken segment is wrapped independently); a word wider than
+ * `width` on its own is broken at the width boundary via `breakLongWord`
+ * rather than overflowing the line.
+ */
+export function wrap(text, width) {
+    const w = Math.max(1, width);
+    const lines = [];
+    for (const hardLine of text.split('\n')) {
+        const words = hardLine.split(/ +/).filter((word) => word !== '');
+        if (words.length === 0) {
+            lines.push('');
+            continue;
+        }
+        let current = '';
+        let currentWidth = 0;
+        for (const word of words) {
+            const wordWidth = measure(word);
+            if (wordWidth > w) {
+                if (current !== '') {
+                    lines.push(current);
+                    current = '';
+                    currentWidth = 0;
+                }
+                lines.push(...breakLongWord(word, w));
+                continue;
+            }
+            if (current === '') {
+                current = word;
+                currentWidth = wordWidth;
+                continue;
+            }
+            if (currentWidth + 1 + wordWidth <= w) {
+                current += ` ${word}`;
+                currentWidth += 1 + wordWidth;
+            }
+            else {
+                lines.push(current);
+                current = word;
+                currentWidth = wordWidth;
+            }
+        }
+        if (current !== '')
+            lines.push(current);
+    }
+    return lines;
+}
+/** Pads `text` to `width` columns with spaces, aligned `left`/`center`/`right`. A `text` already at or over `width` is returned unchanged. */
+export function pad(text, width, align) {
+    const total = Math.max(0, width - measure(text));
+    if (total === 0)
+        return text;
+    if (align === 'right')
+        return ' '.repeat(total) + text;
+    if (align === 'center') {
+        const left = Math.floor(total / 2);
+        const right = total - left;
+        return ' '.repeat(left) + text + ' '.repeat(right);
+    }
+    return text + ' '.repeat(total);
+}
+/**
+ * Re-wraps a block of text that was already wrapped to a WIDER budget than
+ * `width` (the shape a component's pre-rendered `childrenText` always
+ * arrives in: `render.ts` wraps a directive's body to the full directive
+ * width before the component ever runs, since a container component that
+ * draws its own frame or indent — `card`, `callout`, `details`, `figure` —
+ * only learns it needs a NARROWER inner budget once it starts drawing).
+ * Every existing `\n` is a hard break, each hard-broken line re-wrapped
+ * independently if it still overflows `width`; a line already inside the
+ * budget passes through unchanged. Mirrors the same pattern `render.ts`'s
+ * `unknownDirective` fallback already uses for its dashed frame.
+ */
+export function rewrapBlock(text, width) {
+    if (!text)
+        return text;
+    return text
+        .split('\n')
+        .flatMap((line) => wrap(line, width))
+        .join('\n');
+}
+/** Prefixes every line of `block` (split on `\n`) with `prefix`, e.g. a blockquote's `│ `. */
+export function indentBlock(block, prefix) {
+    return block
+        .split('\n')
+        .map((line) => `${prefix}${line}`)
+        .join('\n');
+}
+/**
+ * Places `blocks` side by side, each padded (left-aligned) to its entry in
+ * `widths`, joined by `gutter` spaces, top-aligned: a block with fewer
+ * lines than its neighbors gets its missing rows filled with blank,
+ * full-width padding rather than leaving a ragged gap.
+ */
+export function columns(blocks, widths, gutter) {
+    const gap = ' '.repeat(Math.max(0, gutter));
+    const lineArrays = blocks.map((block) => block.split('\n'));
+    const rowCount = Math.max(0, ...lineArrays.map((lines) => lines.length));
+    const rows = [];
+    for (let row = 0; row < rowCount; row += 1) {
+        const cells = lineArrays.map((lines, index) => pad(lines[row] ?? '', widths[index] ?? 0, 'left'));
+        // The padding on the LAST column is dropped again. It buys nothing: no
+        // column follows it to be aligned against, and left in place it would
+        // end every row with a run of spaces, which shows up as trailing
+        // whitespace in a committed fixture and in anything that pipes this
+        // output to a file. Padding between columns is what does the work.
+        rows.push(cells.join(gap).replace(/[ ]+$/, ''));
+    }
+    return rows.join('\n');
+}
+/**
+ * Draws a box around `block`: `┌ ─ ┐ │ └ ┘` for `'solid'`, `┌ ╌ ┐ ┆ └ ┘` for
+ * `'dashed'` (the corners are shared; only the edge glyphs change). A
+ * `title` is woven into the top edge as `┌─ title ────┐`. Every content
+ * line is padded to the frame's inner width, so every drawn line is exactly
+ * `options.width` columns wide.
+ */
+export function frame(block, options) {
+    const { style: kind, title, width } = options;
+    const horizontal = kind === 'dashed' ? '╌' : '─';
+    const vertical = kind === 'dashed' ? '┆' : '│';
+    const innerWidth = Math.max(1, width - 2);
+    let top;
+    if (title) {
+        const label = ` ${title} `;
+        const remaining = Math.max(0, innerWidth - measure(label) - 1);
+        top = `┌${horizontal}${label}${horizontal.repeat(remaining)}┐`;
+    }
+    else {
+        top = `┌${horizontal.repeat(innerWidth)}┐`;
+    }
+    const bottom = `└${horizontal.repeat(innerWidth)}┘`;
+    const lines = block
+        .split('\n')
+        .map((line) => `${vertical}${pad(line, innerWidth, 'left')}${vertical}`);
+    return [top, ...lines, bottom].join('\n');
+}
+/** A full-width horizontal rule, `char` (default `─`) repeated to `width` columns. */
+export function rule(width, char = '─') {
+    return char.repeat(Math.max(0, width));
+}

package/dist/components/badge.d.ts

@@ -0,0 +1,10 @@
+import type { AnsiComponent } from '../registry.js';
+export type BadgeVariant = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+/**
+ * `:badge[New]{variant=success}` — a status pill for an inline text
+ * directive. Unknown/missing `variant` falls back to `neutral` rather than
+ * throwing. Terminal form: an inverse-video chip, ` label ` colored for the
+ * variant. At color level `'none'` there is no inverse video to distinguish
+ * a badge from surrounding text, so it degrades to `[label]` instead.
+ */
+export declare const Badge: AnsiComponent;

package/dist/components/badge.js

@@ -0,0 +1,44 @@
+const BADGE_VARIANTS = [
+    'neutral',
+    'info',
+    'success',
+    'warning',
+    'danger',
+];
+const DEFAULT_VARIANT = 'neutral';
+function isBadgeVariant(value) {
+    return BADGE_VARIANTS.includes(value);
+}
+/** Variant -> the theme token its chip's background reads (mirroring `@markii/html`'s color choice for the same variant). */
+const VARIANT_TOKEN = {
+    neutral: 'muted',
+    info: 'info',
+    success: 'success',
+    warning: 'warning',
+    danger: 'danger',
+};
+const TOKEN_NAME = {
+    muted: '--mk-muted',
+    info: '--mk-info',
+    success: '--mk-success',
+    warning: '--mk-warning',
+    danger: '--mk-danger',
+};
+/**
+ * `:badge[New]{variant=success}` — a status pill for an inline text
+ * directive. Unknown/missing `variant` falls back to `neutral` rather than
+ * throwing. Terminal form: an inverse-video chip, ` label ` colored for the
+ * variant. At color level `'none'` there is no inverse video to distinguish
+ * a badge from surrounding text, so it degrades to `[label]` instead.
+ */
+export const Badge = (attributes, children, ctx) => {
+    const rawVariant = attributes.variant ?? DEFAULT_VARIANT;
+    const variant = isBadgeVariant(rawVariant)
+        ? rawVariant
+        : DEFAULT_VARIANT;
+    const childrenText = children();
+    if (ctx.color === 'none')
+        return `[${childrenText}]`;
+    const token = TOKEN_NAME[VARIANT_TOKEN[variant]];
+    return ctx.inverse(ctx.style(` ${childrenText} `, token));
+};

package/dist/components/callout.d.ts

@@ -0,0 +1,20 @@
+import type { AnsiComponent } from '../registry.js';
+export type CalloutType = 'info' | 'warning' | 'danger';
+/**
+ * `:::callout{type=info|warning|danger title="..." text=left|center|right}` —
+ * a colored aside/warning/danger box. Unknown/missing `type` falls back to
+ * `info` (`render.ts`'s generic invalid-enum notice covers reporting that,
+ * same as every other enum attribute). Terminal form: every line carries a
+ * colored left bar; the first line is the icon plus the type label, an
+ * optional bold title line follows, then the body wrapped to the remaining
+ * width. `text` aligns the icon/title/body lines within that remaining
+ * width; absent/invalid `text` behaves as `left` (no padding needed).
+ *
+ * Registered `selfLayout` (`registry.ts`'s `AnsiRegistryEntry.selfLayout`):
+ * every line carries the colored bar prefix, which a generic post-render
+ * `applyLayout` narrowing would re-wrap right through, losing the bar on any
+ * continuation line. This component instead reads the resolved
+ * `width`/`align` off `ctx.layout` itself and sizes/places its own bar
+ * block, exactly like `card`/`table`/`chart`.
+ */
+export declare const Callout: AnsiComponent;

package/dist/components/callout.js

@@ -0,0 +1,71 @@
+import { measure } from '../measure.js';
+import { selfLayoutAlign, selfLayoutWidth } from '../layout.js';
+const CALLOUT_TYPES = ['info', 'warning', 'danger'];
+const CALLOUT_ICONS = {
+    info: 'ℹ',
+    warning: '▲',
+    danger: '✕',
+};
+const CALLOUT_LABELS = {
+    info: 'Info',
+    warning: 'Warning',
+    danger: 'Danger',
+};
+const CALLOUT_TOKENS = {
+    info: '--mk-info',
+    warning: '--mk-warning',
+    danger: '--mk-danger',
+};
+function isCalloutType(value) {
+    return CALLOUT_TYPES.includes(value);
+}
+const TEXT_ALIGNS = ['left', 'center', 'right'];
+function isTextAlign(value) {
+    return TEXT_ALIGNS.includes(value);
+}
+/** The left bar every line of a callout carries, marking it as one colored block at a glance (`box.ts` reserves `│`/`┆` for frames, so this uses the half-block glyph instead). */
+const BAR = '▌ ';
+/**
+ * `:::callout{type=info|warning|danger title="..." text=left|center|right}` —
+ * a colored aside/warning/danger box. Unknown/missing `type` falls back to
+ * `info` (`render.ts`'s generic invalid-enum notice covers reporting that,
+ * same as every other enum attribute). Terminal form: every line carries a
+ * colored left bar; the first line is the icon plus the type label, an
+ * optional bold title line follows, then the body wrapped to the remaining
+ * width. `text` aligns the icon/title/body lines within that remaining
+ * width; absent/invalid `text` behaves as `left` (no padding needed).
+ *
+ * Registered `selfLayout` (`registry.ts`'s `AnsiRegistryEntry.selfLayout`):
+ * every line carries the colored bar prefix, which a generic post-render
+ * `applyLayout` narrowing would re-wrap right through, losing the bar on any
+ * continuation line. This component instead reads the resolved
+ * `width`/`align` off `ctx.layout` itself and sizes/places its own bar
+ * block, exactly like `card`/`table`/`chart`.
+ */
+export const Callout = (attributes, children, ctx) => {
+    const rawType = attributes.type ?? 'info';
+    const type = isCalloutType(rawType) ? rawType : 'info';
+    const token = CALLOUT_TOKENS[type];
+    const title = attributes.title ?? null;
+    const rawTextAlign = attributes.text;
+    const align = rawTextAlign && isTextAlign(rawTextAlign) ? rawTextAlign : 'left';
+    const headerText = `${CALLOUT_ICONS[type]} ${CALLOUT_LABELS[type]}`;
+    const titleText = title ? ctx.text(title) : undefined;
+    const naturalWidth = BAR.length + Math.max(measure(headerText), measure(titleText ?? ''));
+    const boxWidth = selfLayoutWidth(ctx.layout, ctx.width, naturalWidth);
+    const bar = ctx.style(BAR, token);
+    const innerWidth = Math.max(1, boxWidth - BAR.length);
+    const placeLine = (line) => align === 'left' ? line : ctx.pad(line, innerWidth, align);
+    const headerLine = `${bar}${placeLine(ctx.style(headerText, token))}`;
+    const lines = [headerLine];
+    if (titleText) {
+        lines.push(`${bar}${placeLine(ctx.bold(titleText))}`);
+    }
+    const childrenText = children({ width: innerWidth });
+    if (childrenText) {
+        for (const line of childrenText.split('\n')) {
+            lines.push(`${bar}${placeLine(line)}`);
+        }
+    }
+    return selfLayoutAlign(lines.join('\n'), ctx.layout, ctx.width);
+};

package/dist/components/card.d.ts

@@ -0,0 +1,12 @@
+import type { AnsiComponent } from '../registry.js';
+/**
+ * `:::card{title="..." text=left|center|right} ... :::` — a titled panel.
+ * `title` is optional; the title is woven into the frame's top edge, not a
+ * separate line, when given. `text` aligns the body inside the frame;
+ * absent/invalid behaves as `left`.
+ *
+ * Registered `selfLayout` (see `callout.ts`'s doc comment for why): this
+ * component draws a real box-drawn frame, which a generic post-render
+ * narrow/pad would corrupt, so it reads `ctx.layout` and sizes its own frame.
+ */
+export declare const Card: AnsiComponent;