@markii/ansi 0.0.1

package/dist/layout.js

@@ -0,0 +1,144 @@
+import { ALIGN_PRESETS, LAYOUT_ATTRIBUTE_KEYS, WIDTH_PRESETS, } from '@markii/stdlib';
+import { pad, wrap } from './box.js';
+import { measure } from './measure.js';
+/**
+ * The terminal counterpart of `@markii/html`'s `layout.ts`: the same closed
+ * `width`/`align` vocabulary from `@markii/stdlib`, but resolved to COLUMN
+ * ARITHMETIC instead of a CSS class, since there is no stylesheet here. The
+ * two reserved keys are still always stripped off a directive's attributes
+ * before a component sees them, whether or not their value turns out to be
+ * valid, exactly like the other two engines.
+ */
+export { LAYOUT_ATTRIBUTE_KEYS };
+const NORMAL_WIDTH = 'normal';
+function widthPresetFor(value) {
+    if (value === null || value === undefined || value === '')
+        return undefined;
+    if (value === NORMAL_WIDTH)
+        return undefined;
+    return WIDTH_PRESETS.includes(value)
+        ? value
+        : undefined;
+}
+function alignPresetFor(value) {
+    if (value === null || value === undefined || value === '')
+        return undefined;
+    return ALIGN_PRESETS.includes(value)
+        ? value
+        : undefined;
+}
+/**
+ * Splits `width`/`align` off `attributes`, returning the remaining
+ * attributes untouched plus the presets those two attributes resolved to,
+ * if any. Same rules as `@markii/html`'s `resolveLayoutAttributes`: both
+ * keys are stripped whenever present regardless of validity; an invalid or
+ * hostile value never produces a preset; `ownedAxis` (a layout wrapper's own
+ * axis) strips its attribute but produces no preset for it, since the
+ * directive's NAME already decided that axis. Never throws.
+ */
+export function resolveLayoutAttributes(attributes, ownedAxis) {
+    let rest = attributes;
+    const resolved = {};
+    if (Object.hasOwn(rest, 'width')) {
+        const { width, ...remainder } = rest;
+        rest = remainder;
+        const preset = ownedAxis === 'width' ? undefined : widthPresetFor(width);
+        if (preset)
+            resolved.width = preset;
+    }
+    if (Object.hasOwn(rest, 'align')) {
+        const { align, ...remainder } = rest;
+        rest = remainder;
+        const preset = ownedAxis === 'align' ? undefined : alignPresetFor(align);
+        if (preset)
+            resolved.align = preset;
+    }
+    return Object.keys(resolved).length > 0
+        ? { attributes: rest, resolved }
+        : { attributes: rest };
+}
+/** The minimum column count `narrow` ever shrinks to, regardless of how small `width` is. */
+export const NARROW_MINIMUM = 20;
+/** The widest line already present in `block`, or `1` for an empty block (never a zero-width target). */
+function maxLineWidth(block) {
+    let max = 0;
+    for (const line of block.split('\n'))
+        max = Math.max(max, measure(line));
+    return max || 1;
+}
+/**
+ * Turns `layout`'s resolved presets into an actual re-wrapped, aligned
+ * block, given `width` columns of budget. Mapping (all documented here,
+ * the one place it is decided): `narrow` halves `width` (rounded, never
+ * below `NARROW_MINIMUM`); `wide` and `full` both use the entire `width`
+ * (a terminal has no notion of "wider than the column" to distinguish
+ * them); `fit` shrinks to `block`'s own widest existing line, never wider
+ * than `width`. `align` then places the (possibly narrowed) block within
+ * the full `width` using `./box.js`'s `pad`, which is where `align`'s
+ * `left`/`center`/`right` meaning comes from — this function invents none
+ * of its own.
+ */
+export function applyLayout(block, layout, width) {
+    if (!layout)
+        return block;
+    let target = width;
+    if (layout.width === 'narrow') {
+        target = Math.max(NARROW_MINIMUM, Math.round(width / 2));
+    }
+    else if (layout.width === 'fit') {
+        target = Math.min(width, maxLineWidth(block));
+    }
+    const narrowed = target < width
+        ? block
+            .split('\n')
+            .flatMap((line) => wrap(line, Math.max(1, target)))
+            .join('\n')
+        : block;
+    if (!layout.align)
+        return narrowed;
+    return narrowed
+        .split('\n')
+        .map((line) => pad(line, width, layout.align))
+        .join('\n');
+}
+/**
+ * The target width a SELF-DRAWING box component (`card`, `callout`, `table`,
+ * `chart`; see `registry.ts`'s `AnsiRegistryEntry.selfLayout`) should draw
+ * its own frame at, given the resolved `width` preset. Mirrors the width
+ * half of `applyLayout`'s mapping exactly (`narrow` halves `width`, floored
+ * at `NARROW_MINIMUM`; `wide`/`full`/absent use the whole budget; `fit`
+ * shrinks to the box's own natural content width, capped at `width`), so a
+ * component that draws at this width up front needs no further narrowing:
+ * `applyLayout`'s `wrap` step becomes a no-op on an already-correctly-sized
+ * line. `naturalWidth` is the box's own widest line at its full content size
+ * (only consulted for `fit`); a caller that draws lazily may pass a function
+ * to defer that measurement until it is known to matter.
+ */
+export function selfLayoutWidth(layout, width, naturalWidth) {
+    if (!layout?.width)
+        return width;
+    if (layout.width === 'narrow') {
+        return Math.max(NARROW_MINIMUM, Math.round(width / 2));
+    }
+    if (layout.width === 'fit') {
+        const natural = typeof naturalWidth === 'function' ? naturalWidth() : naturalWidth;
+        return Math.min(width, Math.max(1, natural));
+    }
+    return width;
+}
+/**
+ * Pads a SELF-DRAWING box's already-drawn frame (every line already
+ * `boxWidth` columns wide) within the full `width` per the resolved `align`
+ * preset — the align half of `applyLayout`, factored out so a `selfLayout`
+ * component can align its own frame without going through the generic
+ * narrow/wrap path that would otherwise re-wrap (and corrupt) its
+ * box-drawing characters. A no-op when `layout.align` is absent.
+ */
+export function selfLayoutAlign(block, layout, width) {
+    if (!layout?.align)
+        return block;
+    return block
+        .split('\n')
+        .map((line) => pad(line, width, layout.align))
+        .join('\n');
+}

package/dist/measure.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Hand-written display-width measurement (no dependency is permitted here;
+ * see AGENTS.md's Stack section and the batch brief). This is a DELIBERATE
+ * APPROXIMATION of Unicode's East Asian Width property (UAX #11), not a
+ * full Unicode width table: it covers the ranges most terminal content
+ * actually uses (Latin text, CJK, common emoji, combining marks) and gets
+ * one class of case knowingly wrong, documented below.
+ *
+ * KNOWN LIMITATION: a grapheme cluster joined by a zero-width joiner
+ * (U+200D), such as a multi-person or multi-skin-tone emoji sequence,
+ * measures as the sum of its parts rather than as the single glyph a
+ * terminal actually draws. Getting this exactly right needs a real
+ * grapheme-segmentation table, which this package deliberately does not
+ * carry.
+ */
+/** Removes every SGR and OSC 8 escape sequence this engine can itself produce, so `measure` counts only what a terminal actually draws. */
+export declare function stripAnsi(text: string): string;
+/**
+ * The display width of `text`: ANSI escapes are stripped first, then every
+ * remaining code point (iterated as a code point, not a UTF-16 code unit,
+ * so a surrogate pair counts once) contributes its width per
+ * `codePointWidth`'s rules. This is what every wrapping/padding/column
+ * helper in `./box.ts` measures against.
+ */
+export declare function measure(text: string): number;

package/dist/measure.js

@@ -0,0 +1,108 @@
+/**
+ * Hand-written display-width measurement (no dependency is permitted here;
+ * see AGENTS.md's Stack section and the batch brief). This is a DELIBERATE
+ * APPROXIMATION of Unicode's East Asian Width property (UAX #11), not a
+ * full Unicode width table: it covers the ranges most terminal content
+ * actually uses (Latin text, CJK, common emoji, combining marks) and gets
+ * one class of case knowingly wrong, documented below.
+ *
+ * KNOWN LIMITATION: a grapheme cluster joined by a zero-width joiner
+ * (U+200D), such as a multi-person or multi-skin-tone emoji sequence,
+ * measures as the sum of its parts rather than as the single glyph a
+ * terminal actually draws. Getting this exactly right needs a real
+ * grapheme-segmentation table, which this package deliberately does not
+ * carry.
+ */
+/** SGR: `ESC [ ... m`. */
+const SGR_PATTERN = /\x1b\[[0-9;]*m/g;
+/** OSC 8 hyperlink open/close: `ESC ] 8 ; ; ... BEL`. */
+const OSC8_PATTERN = /\x1b\]8;;[^\x07\x1b]*\x07/g;
+/** Removes every SGR and OSC 8 escape sequence this engine can itself produce, so `measure` counts only what a terminal actually draws. */
+export function stripAnsi(text) {
+    return text.replace(OSC8_PATTERN, '').replace(SGR_PATTERN, '');
+}
+/** Combining marks: measure 0, since a terminal draws them layered onto the preceding column rather than advancing the cursor. */
+const COMBINING_RANGES = [
+    [0x0300, 0x036f],
+    [0x1ab0, 0x1aff],
+    [0x1dc0, 0x1dff],
+    [0x20d0, 0x20f0],
+    [0xfe00, 0xfe0f],
+    [0xfe20, 0xfe2f],
+];
+/** Zero-width characters: measure 0 (zero-width space/joiner/non-joiner, word joiner, byte-order mark used as a zero-width no-break space). */
+const ZERO_WIDTH_RANGES = [
+    [0x200b, 0x200d],
+    [0x2060, 0x2060],
+    [0xfeff, 0xfeff],
+];
+/** East Asian Wide and Fullwidth: measure 2. */
+const WIDE_RANGES = [
+    [0x1100, 0x115f],
+    [0x2e80, 0x303e],
+    [0x3041, 0x33ff],
+    [0x3400, 0x4dbf],
+    [0x4e00, 0x9fff],
+    [0xa000, 0xa4cf],
+    [0xac00, 0xd7a3],
+    [0xf900, 0xfaff],
+    [0xfe30, 0xfe6f],
+    [0xff00, 0xff60],
+    [0xffe0, 0xffe6],
+    [0x20000, 0x2fffd],
+    [0x30000, 0x3fffd],
+];
+/** Common emoji ranges: measure 2. U+2600-U+27BF is included only when followed by the U+FE0F variation selector (see `measureText`). */
+const EMOJI_RANGES = [
+    [0x1f300, 0x1f64f],
+    [0x1f680, 0x1f6ff],
+    [0x1f900, 0x1f9ff],
+    [0x1fa70, 0x1faff],
+];
+const EMOJI_PRESENTATION_LOW = 0x2600;
+const EMOJI_PRESENTATION_HIGH = 0x27bf;
+const VARIATION_SELECTOR_16 = 0xfe0f;
+function inRanges(code, ranges) {
+    for (const [low, high] of ranges) {
+        if (code >= low && code <= high)
+            return true;
+    }
+    return false;
+}
+/**
+ * The display width of one code point, given the NEXT code point in the
+ * stream (needed only to check the emoji-variation-selector rule for the
+ * dingbat range U+2600-U+27BF).
+ */
+function codePointWidth(code, next) {
+    if (inRanges(code, COMBINING_RANGES))
+        return 0;
+    if (inRanges(code, ZERO_WIDTH_RANGES))
+        return 0;
+    if (inRanges(code, WIDE_RANGES))
+        return 2;
+    if (inRanges(code, EMOJI_RANGES))
+        return 2;
+    if (code >= EMOJI_PRESENTATION_LOW &&
+        code <= EMOJI_PRESENTATION_HIGH &&
+        next === VARIATION_SELECTOR_16) {
+        return 2;
+    }
+    return 1;
+}
+/**
+ * The display width of `text`: ANSI escapes are stripped first, then every
+ * remaining code point (iterated as a code point, not a UTF-16 code unit,
+ * so a surrogate pair counts once) contributes its width per
+ * `codePointWidth`'s rules. This is what every wrapping/padding/column
+ * helper in `./box.ts` measures against.
+ */
+export function measure(text) {
+    const stripped = stripAnsi(text);
+    const codePoints = Array.from(stripped, (char) => char.codePointAt(0) ?? 0);
+    let width = 0;
+    for (let index = 0; index < codePoints.length; index += 1) {
+        width += codePointWidth(codePoints[index], codePoints[index + 1]);
+    }
+    return width;
+}

package/dist/registry.d.ts

@@ -0,0 +1,227 @@
+/**
+ * The registry contract for the terminal engine: the string-emitting twin of
+ * `@markii/html`'s `registry.ts`, itself the string-emitting twin of
+ * `@markii/react`'s `registry.ts`. A component here is a plain function from
+ * attributes and already-rendered children TEXT to an output string — no
+ * hast, no React, no HTML. The alias, merge, and hostile-configuration rules
+ * are kept identical to both existing renderers, so a note resolves the same
+ * way in all three.
+ */
+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 { ResolvedLayoutAttributes } from './layout.js';
+import type { ResolveImageSrc } from './image-resolve.js';
+import type { ResolveHref } from './href-resolve.js';
+/**
+ * Attributes parsed off a directive, e.g. `{type=warning title="Careful"}`. A
+ * bare attribute (present but valueless, e.g. `{collapsed}`) arrives as
+ * `null`. A key that was never written is simply absent.
+ */
+export type DirectiveAttributes = Record<string, string | null | undefined>;
+/**
+ * A `data=`/`:value[...]` name resolved against the render's value store
+ * (and, for an `@`-prefixed name, its vault) — this engine's read-only view
+ * of `./resolve.js`'s `StorePathResolution`.
+ */
+export interface ValueResolution {
+    value: unknown;
+    status: ValueStatus;
+    error?: string;
+    failureKind?: FailureKind;
+}
+/**
+ * The render context handed to every component. Mirrors
+ * `@markii/html`'s `HtmlRenderContext` field for field, with the HTML-only
+ * `esc` swapped for `text` (this engine's control-character sanitizer, see
+ * `./sanitize.js`'s `stripControlCharacters`) and a set of terminal-only
+ * fields added: `width`/`indent` (the layout budget this directive's own
+ * output has to work with), `color`/`theme` (what this render resolved),
+ * and the box/style helpers pre-bound to both.
+ */
+export interface AnsiRenderContext {
+    /** The columns available to this directive's own output. A component wraps its own text to this width. */
+    width: number;
+    /**
+     * The prefix an enclosing block (a blockquote, a nested list) has already
+     * applied to every line above this directive. Informational only: a
+     * component emits its own block UNINDENTED, and the walk applies the
+     * prefix afterward, exactly as `width` is already the post-indent budget.
+     */
+    indent: string;
+    /** The resolved color depth for this render. */
+    color: ColorLevel;
+    /** The resolved theme for this render. */
+    theme: AnsiTheme;
+    /** Applies `theme`'s color for `token` at this render's `color` level. Unchanged at `'none'` or for a `null` theme entry. */
+    style(text: string, token: Tier1Token): string;
+    /** SGR bold, pre-bound to this render's color level. */
+    bold(text: string): string;
+    /** SGR dim/faint, pre-bound to this render's color level. */
+    dim(text: string): string;
+    /** SGR italic, pre-bound to this render's color level. */
+    italic(text: string): string;
+    /** SGR underline, pre-bound to this render's color level. */
+    underline(text: string): string;
+    /** SGR inverse/reverse video, pre-bound to this render's color level. */
+    inverse(text: string): string;
+    /** Greedy word wrap, pre-bound to nothing (width is explicit here since a component may wrap narrower than its own `ctx.width`, e.g. inside its own frame). */
+    wrap(text: string, width: number): string[];
+    /** Pads `text` to `width` columns, aligned `left`/`center`/`right`. */
+    pad(text: string, width: number, align: 'left' | 'center' | 'right'): string;
+    /** Places blocks side by side; see `./box.js`'s `columns`. */
+    columns(blocks: readonly string[], widths: readonly number[], gutter: number): string;
+    /** Draws a box around `block`; see `./box.js`'s `frame`. */
+    frame(block: string, options: {
+        style: 'solid' | 'dashed';
+        title?: string;
+        width: number;
+    }): string;
+    /** A full-width horizontal rule; see `./box.js`'s `rule`. */
+    rule(width: number, char?: string): string;
+    /**
+     * The sanitizer a component MUST run any author-supplied string through
+     * before printing it (this engine's counterpart to the HTML context's
+     * `esc`): strips every control character an untrusted note could use to
+     * move the cursor or smuggle an escape sequence (`./sanitize.js`'s
+     * `stripControlCharacters`).
+     */
+    text(value: string): string;
+    /** Resolves a `data=`/`:value[...]` name against the current render's store/vault. Never throws. */
+    resolve(name: string): ValueResolution;
+    /** The quiet missing/stale/failure-tinted marker for `name`. Never throws. */
+    valueMarker(name: string, format?: string, decimals?: string): string;
+    data?: unknown;
+    dataStatus?: ValueStatus;
+    dataError?: string;
+    dataFailureKind?: FailureKind;
+    /**
+     * The resolved width/align presets for the axis a layout-scope entry does
+     * not already own — this engine's counterpart to `@markii/html`'s
+     * `layoutClassName`, carried as data instead of a class name since there
+     * is no stylesheet here.
+     */
+    layout?: ResolvedLayoutAttributes['resolved'];
+    resolveImageSrc?: ResolveImageSrc;
+    resolveHref?: ResolveHref;
+    onDiagnostic?: OnDiagnostic;
+}
+/**
+ * How a component wants ONE render of its children to happen: at a
+ * narrower `width` than the directive itself was rendered at (a self-layout
+ * box sizing its own inner budget), and/or a different `indent`. Omitting a
+ * field inherits the value the enclosing directive was rendered with.
+ */
+export interface AnsiChildrenOptions {
+    width?: number;
+    indent?: string;
+}
+/**
+ * One top-level child of a directive's own body, independently renderable
+ * at its own width — the piece `row` needs and no other standard component
+ * does: it must decide each cell's column width BEFORE that cell's content
+ * (including a self-drawing box like `card`) is rendered, not re-wrap an
+ * already-drawn frame afterward. `name` is the child's own resolved
+ * directive name (e.g. `'cell'`) when the child is itself a directive, and
+ * `undefined` for a plain block (a paragraph, a list) or a directive with a
+ * different name — enough for a container to recognize a semantically
+ * tagged child without ever seeing a hast node.
+ */
+export interface AnsiChildPart {
+    readonly name?: string;
+    render(options?: AnsiChildrenOptions): string;
+}
+/**
+ * The children a component receives. Calling it directly renders the
+ * directive's WHOLE body as one flattened string — what every component
+ * except `row` wants, and what used to be eagerly computed as a plain
+ * string before the component ever ran. `options` narrows the width/indent
+ * for that one call (a self-layout box's inner budget); omitted, it renders
+ * at the width/indent the directive itself was given.
+ *
+ * `.parts` exposes each of the directive's own top-level children
+ * separately, in document order, each independently renderable at its own
+ * width via its own `render(options)` — see `AnsiChildPart`.
+ *
+ * Laziness is the point: nothing under this directive is rendered until a
+ * component actually calls `children()` or one of `.parts`' `render()`
+ * functions, so a container can decide sizes top-down before anything below
+ * it draws a single character.
+ */
+export type AnsiChildren = ((options?: AnsiChildrenOptions) => string) & {
+    readonly parts: readonly AnsiChildPart[];
+};
+/**
+ * One registry component: receives the directive's raw string attributes
+ * (bare attributes as `null`), a lazy handle onto its inner markdown
+ * (`AnsiChildren`, see above), and the render context, and returns the text
+ * to emit. Attribute parsing, validation, and defaulting are the
+ * component's own job, exactly as in the other two engines' contracts.
+ */
+export type AnsiComponent = (attributes: DirectiveAttributes, children: AnsiChildren, ctx: AnsiRenderContext) => string;
+/** One registry entry: the component plus whether it is meant to be used inline vs as a block, and whether it is a layout scope. Mirrors `@markii/html`'s `HtmlRegistryEntry`. */
+export interface AnsiRegistryEntry {
+    component: AnsiComponent;
+    inline?: boolean;
+    layout?: LayoutAxis;
+    /**
+     * Marks a component that draws its OWN box (a frame, a table grid) rather
+     * than plain wrapped text — `card`, `callout`, `table`, `chart` in the
+     * standard set. `applyLayout`'s generic re-wrap/pad would corrupt a
+     * pre-drawn frame's box-drawing characters if `render.ts` narrowed it
+     * AFTER the component already drew it at the full width. A `selfLayout`
+     * component instead receives the resolved `width`/`align` presets as
+     * `ctx.layout` (the same field a layout-WRAPPER scope receives) and is
+     * trusted to size its own frame correctly; `render.ts` then skips its
+     * usual post-render `applyLayout` call for it, exactly as it already does
+     * for a layout-wrapper scope. Unlike `layout: LayoutAxis`, this is not
+     * "this directive's name sets an axis" — it is "this directive draws pixels
+     * that a generic wrap/pad would break."
+     */
+    selfLayout?: boolean;
+}
+/** One alias: a second name for an existing component, optionally carrying preset attributes. */
+export interface RegistryAlias {
+    name: string;
+    attributes?: DirectiveAttributes;
+}
+/** Alias name -> what it stands for. */
+export type RegistryAliases = Record<string, RegistryAlias>;
+/** The symbol an alias table hangs off a registry under. Mirrors `@markii/html`'s `REGISTRY_ALIASES`. */
+export declare const REGISTRY_ALIASES: unique symbol;
+/** Directive name -> component registration, plus an optional alias table under `REGISTRY_ALIASES`. */
+export interface AnsiRegistry {
+    [name: string]: AnsiRegistryEntry;
+    [REGISTRY_ALIASES]?: RegistryAliases;
+}
+/** Reads a registry's alias table, or `undefined` if it has none. Returned as-is; treat as read-only. */
+export declare function registryAliases(registry: AnsiRegistry): RegistryAliases | undefined;
+/**
+ * Creates a registry from a plain object of entries plus an optional alias
+ * table. The returned map has a `null` prototype so a directive named
+ * `constructor`, `toString`, `hasOwnProperty`, etc. cannot resolve to an
+ * inherited member.
+ */
+export declare function createAnsiRegistry(entries?: AnsiRegistry, aliases?: RegistryAliases): AnsiRegistry;
+/** Merges any number of registries, later ones taking precedence, into a null-prototype map. Alias tables merge per name. */
+export declare function mergeAnsiRegistries(...registries: AnsiRegistry[]): AnsiRegistry;
+/** Reads `entry.component`, or `undefined` if `entry` is nullish or the read itself throws. */
+export declare function readRegistryComponent(entry: AnsiRegistryEntry | undefined): AnsiComponent | undefined;
+/** The layout axis the component registered under `name` owns, or `undefined`. Mirrors `@markii/html`'s `registryLayoutAxis`. */
+export declare function registryLayoutAxis(registry: AnsiRegistry, name: string): LayoutAxis | undefined;
+/** Whether the component registered under `name` is marked `selfLayout` (see `AnsiRegistryEntry`'s doc comment). Fails permissive (`false`) on a throwing `.selfLayout` getter, matching `registryLayoutAxis`'s defensiveness. */
+export declare function registrySelfLayout(registry: AnsiRegistry, name: string): boolean;
+/** A directive name and attributes after alias resolution. */
+export interface ResolvedDirective {
+    name: string;
+    attributes: DirectiveAttributes;
+}
+/**
+ * Resolves one directive name through the registry's alias table. Same four
+ * rules as `@markii/html`'s `resolveDirectiveAlias`: a real component wins
+ * over any alias; an unaliased name passes through; an alias is followed
+ * exactly one hop; author attributes win over the alias's presets. Never
+ * throws.
+ */
+export declare function resolveDirectiveAlias(registry: AnsiRegistry, name: string, attributes: DirectiveAttributes): ResolvedDirective;

package/dist/registry.js

@@ -0,0 +1,121 @@
+/**
+ * The registry contract for the terminal engine: the string-emitting twin of
+ * `@markii/html`'s `registry.ts`, itself the string-emitting twin of
+ * `@markii/react`'s `registry.ts`. A component here is a plain function from
+ * attributes and already-rendered children TEXT to an output string — no
+ * hast, no React, no HTML. The alias, merge, and hostile-configuration rules
+ * are kept identical to both existing renderers, so a note resolves the same
+ * way in all three.
+ */
+/** The symbol an alias table hangs off a registry under. Mirrors `@markii/html`'s `REGISTRY_ALIASES`. */
+export const REGISTRY_ALIASES = Symbol('markii.ansi.registry.aliases');
+/** Reads a registry's alias table, or `undefined` if it has none. Returned as-is; treat as read-only. */
+export function registryAliases(registry) {
+    return registry[REGISTRY_ALIASES];
+}
+function mergeAliasTables(tables) {
+    const present = tables.filter((table) => table !== undefined);
+    if (present.length === 0)
+        return undefined;
+    const merged = Object.create(null);
+    for (const table of present) {
+        for (const name of Object.keys(table))
+            merged[name] = table[name];
+    }
+    return merged;
+}
+/**
+ * Creates a registry from a plain object of entries plus an optional alias
+ * table. The returned map has a `null` prototype so a directive named
+ * `constructor`, `toString`, `hasOwnProperty`, etc. cannot resolve to an
+ * inherited member.
+ */
+export function createAnsiRegistry(entries = {}, aliases) {
+    const registry = Object.assign(Object.create(null), entries);
+    const merged = mergeAliasTables([registryAliases(entries), aliases]);
+    if (merged)
+        registry[REGISTRY_ALIASES] = merged;
+    return registry;
+}
+/** Merges any number of registries, later ones taking precedence, into a null-prototype map. Alias tables merge per name. */
+export function mergeAnsiRegistries(...registries) {
+    const merged = Object.assign(Object.create(null), ...registries);
+    const aliases = mergeAliasTables(registries.map(registryAliases));
+    if (aliases)
+        merged[REGISTRY_ALIASES] = aliases;
+    else
+        delete merged[REGISTRY_ALIASES];
+    return merged;
+}
+/** Reads `entry.component`, or `undefined` if `entry` is nullish or the read itself throws. */
+export function readRegistryComponent(entry) {
+    if (!entry)
+        return undefined;
+    try {
+        return entry.component ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The layout axis the component registered under `name` owns, or `undefined`. Mirrors `@markii/html`'s `registryLayoutAxis`. */
+export function registryLayoutAxis(registry, name) {
+    const entry = Object.hasOwn(registry, name) ? registry[name] : undefined;
+    if (readRegistryComponent(entry) == null)
+        return undefined;
+    try {
+        const axis = entry?.layout;
+        return axis === 'width' || axis === 'align' ? axis : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether the component registered under `name` is marked `selfLayout` (see `AnsiRegistryEntry`'s doc comment). Fails permissive (`false`) on a throwing `.selfLayout` getter, matching `registryLayoutAxis`'s defensiveness. */
+export function registrySelfLayout(registry, name) {
+    const entry = Object.hasOwn(registry, name) ? registry[name] : undefined;
+    if (readRegistryComponent(entry) == null)
+        return false;
+    try {
+        return entry?.selfLayout === true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasComponent(registry, name) {
+    return (Object.hasOwn(registry, name) &&
+        readRegistryComponent(registry[name]) != null);
+}
+function mergeAliasAttributes(preset, author) {
+    if (!preset)
+        return author;
+    const result = {};
+    for (const [key, value] of Object.entries(preset))
+        result[key] = value;
+    for (const [key, value] of Object.entries(author))
+        result[key] = value;
+    return result;
+}
+/**
+ * Resolves one directive name through the registry's alias table. Same four
+ * rules as `@markii/html`'s `resolveDirectiveAlias`: a real component wins
+ * over any alias; an unaliased name passes through; an alias is followed
+ * exactly one hop; author attributes win over the alias's presets. Never
+ * throws.
+ */
+export function resolveDirectiveAlias(registry, name, attributes) {
+    if (hasComponent(registry, name))
+        return { name, attributes };
+    const aliases = registryAliases(registry);
+    if (!aliases || !Object.hasOwn(aliases, name))
+        return { name, attributes };
+    const alias = aliases[name];
+    if (typeof alias?.name !== 'string' || alias.name === '') {
+        return { name, attributes };
+    }
+    return {
+        name: alias.name,
+        attributes: mergeAliasAttributes(alias.attributes, attributes),
+    };
+}