# paratext/term-img

> Every export of paratext/term-img, with its signature and doc comment: supportsInlineImage, terminalImageFor, UnsupportedTerminalError, terminalImage, plus 2 types.

Source: https://paratext.interlace.tools/docs/api/term-img

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`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.

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

## Functions

### supportsInlineImage

`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.

```ts
function supportsInlineImage(runtime: Runtime): boolean;
```

| Parameter | Type |
| :-- | :-- |
| `runtime` | `Runtime` |

**Returns** `boolean`

### terminalImageFor

`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.

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

| Parameter | Type |
| :-- | :-- |
| `runtime` | `Runtime` |

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

## Classes

### UnsupportedTerminalError

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.

```ts
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);
}
```

## Constants

### default

The default export, declared as `terminalImage`.

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

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

## Interfaces

### TerminalImageOptions

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

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

## Types

### TerminalImageInput

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

```ts
type TerminalImageInput = Uint8Array | string | null | undefined;
```