paratext/term-img

paratext/term-img — the term-img surface, drop-in for the bytes it can produce.

A subpath rather than the package root, because the root default export is already ansi-escapes' object (R8) and term-img's is a function (D-006). Graded 12 / 18 against term-img's own suite, and 12 is the ceiling: the six red cases all hand a path to a supported terminal, and D-030 says image takes bytes, so that node:fs stays out of a package that otherwise touches nothing but strings. The refusal below sits at exactly the line upstream calls readFileSync, which is what keeps the four path-to-an-unsupported- terminal cases passing. The six are named in compat-oracle/src/hosts.ts and the whole argument is in .sdlc/intents/paratext/design.md.

This file carries term-img's own terminal table rather than IMAGE.when, which also requires a tty. Not to buy a case: term-img's unsupported branch is fallback(), whose default throws, so a tty clause here would turn every piped run into an UnsupportedTerminalError — a drop-in taking down programs the incumbent left standing. The root's image() keeps the clause, where the projection really is a string. term-img.test.ts pins the divergence so a later consistency edit has to argue with it.

import terminalImage from 'paratext/term-img';
import { supportsInlineImage, terminalImageFor, UnsupportedTerminalError } from 'paratext/term-img';

FunctionsCopy Anchor Link

supportsInlineImageCopy Anchor Link

term-img's own support question, from the environment alone.

One deliberate correction. Upstream reads the iTerm2 major version as Number(version[0]) — the first character — so it would read 10.2.1 as 1 and refuse a terminal five majors past its minimum. Number.parseInt is what it meant. Nothing in the vendored suite distinguishes the two (its case is 3.3.7), so this is a fix that costs no compatibility and is written down rather than left to be re-discovered.

Upstream reaches for iterm2-version, which falls back to reading the installed bundle's Info.plist through app-path. It never gets there when TERM_PROGRAM is iTerm.app, because that package returns TERM_PROGRAM_VERSION first — so an environment read is the whole of the reachable behaviour, and two dependencies buy nothing.

function supportsInlineImage(runtime: Runtime): boolean;

Returns boolean

terminalImageForCopy Anchor Link

terminalImage bound to a runtime you supply — the pure form, and what the export wraps.

The order of the three checks is upstream's, exactly, because every one of its cases depends on it: the argument is validated before the terminal is consulted, and the terminal is consulted before the bytes are wanted. That is why a path handed to an unsupported terminal still raises UnsupportedTerminalError here rather than the path refusal — upstream would not have opened the file either.

function terminalImageFor(runtime: Runtime): (image?: TerminalImageInput, options?: TerminalImageOptions) => string;

Returns (image?: TerminalImageInput, options?: TerminalImageOptions) => string

ClassesCopy Anchor Link

UnsupportedTerminalErrorCopy Anchor Link

Thrown when the terminal is not believed to draw an inline image and the caller supplied no fallback. Upstream's class, upstream's message, upstream's name — a caller that matched on error.name or on instanceof keeps working, which is most of what drop-in means for an error type.

class UnsupportedTerminalError extends Error {
    /**
     * The parameter is ours; upstream's constructor takes none. It is a superset — `new
     * UnsupportedTerminalError()` still produces upstream's exact message — and it exists so a
     * caller that knows more about *why* the terminal refused can say so.
     */
    constructor(message?: string);
}

ConstantsCopy Anchor Link

defaultCopy Anchor Link

The default export, declared as terminalImage.

terminalImage(image, options?) against the real process — term-img's default export.

const terminalImage: (image?: TerminalImageInput, options?: TerminalImageOptions) => string;

InterfacesCopy Anchor Link

TerminalImageOptionsCopy Anchor Link

term-img's options: ansi-escapes' four, plus the escape hatch from the throw.

interface TerminalImageOptions extends ImageOptions {
    /** Called instead of throwing when the terminal cannot draw it. Its return value is ours. */
    fallback?: () => string;
}

TypesCopy Anchor Link

TerminalImageInputCopy Anchor Link

What upstream's argument accepts, including the path form this package refuses.

type TerminalImageInput = Uint8Array | string | null | undefined;