better-ink-ui 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +64 -2
- package/dist/index.d.mts +288 -0
- package/dist/index.mjs +800 -0
- package/dist/index.mjs.map +1 -0
- package/dist/lock-CgGrUVeY.mjs +413 -0
- package/dist/lock-CgGrUVeY.mjs.map +1 -0
- package/dist/worker.d.mts +1 -0
- package/dist/worker.mjs +736 -0
- package/dist/worker.mjs.map +1 -0
- package/package.json +71 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ryan Garber
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,65 @@
|
|
|
1
|
-
#
|
|
1
|
+
# better-ink-picture
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Images for [Ink](https://github.com/vadimdemedes/ink) that never block the render loop.
|
|
4
|
+
|
|
5
|
+
- **Off the main thread.** Reading, probing, decoding and sending images all happen in a worker, which writes
|
|
6
|
+
straight to the terminal's file descriptor. The main thread only lays out a grid of placeholder characters.
|
|
7
|
+
- **Fast paths only.** Kitty graphics with Unicode placeholders (Kitty ≥ 0.28, Ghostty): the terminal draws the image
|
|
8
|
+
at full resolution, and it scrolls, clips and re-renders like text. Every other terminal gets a link to a file.
|
|
9
|
+
- **Detection that asks.** The terminal is queried for graphics support, whether it can read our files, its cell size
|
|
10
|
+
and its name, with no fixed sleeps.
|
|
11
|
+
- **Little work.** PNGs are never decoded. A local PNG is sent as its path, and base64 is sent as it came. Other formats
|
|
12
|
+
are decoded once, never larger than the window. Probes read headers only.
|
|
13
|
+
- **Smart scaling.** Give a width, a height, or both: the image keeps its aspect ratio and takes only the cells it
|
|
14
|
+
fills, never more than its own size or the terminal's.
|
|
15
|
+
|
|
16
|
+
## Usage
|
|
17
|
+
|
|
18
|
+
```tsx
|
|
19
|
+
import { render } from "ink";
|
|
20
|
+
import { detectTerminal, Image, ImageProvider } from "better-ink-picture";
|
|
21
|
+
|
|
22
|
+
// before render(): detection reads stdin, which Ink takes over
|
|
23
|
+
const capabilities = await detectTerminal();
|
|
24
|
+
|
|
25
|
+
render(
|
|
26
|
+
<ImageProvider capabilities={capabilities}>
|
|
27
|
+
<Image src="./photo.jpg" width={40} alt="a photo" />
|
|
28
|
+
</ImageProvider>
|
|
29
|
+
);
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`src` takes a file path, `http(s):`/`file:` URL, data URL, base64 string, `Uint8Array`, or an explicit
|
|
33
|
+
`{ path } | { url } | { base64 } | { bytes }`.
|
|
34
|
+
|
|
35
|
+
| Prop | Meaning |
|
|
36
|
+
| ---------- | ------------------------------------------------------------------------------ |
|
|
37
|
+
| `width` | Most columns; alone, the image scales to it and its rows follow |
|
|
38
|
+
| `height` | Most rows; alone, the image scales to it and its columns follow |
|
|
39
|
+
| `upscale` | Allow scaling past the image's own pixel size (default `false`) |
|
|
40
|
+
| `alt` | Description; the fallback link's text |
|
|
41
|
+
| `loading` | Shown while the header is read |
|
|
42
|
+
| `fallback` | `({ path, url, hyperlinks, alt }) => ReactNode` for terminals without graphics |
|
|
43
|
+
| `onLoad` | Called with the image's size in pixels and cells |
|
|
44
|
+
| `onError` | Called when the image can't be read |
|
|
45
|
+
|
|
46
|
+
Without graphics, an image is written to `$TMPDIR/better-ink-picture` (a local file links to itself). The link is OSC 8
|
|
47
|
+
where the terminal supports it, and the plain path otherwise.
|
|
48
|
+
|
|
49
|
+
`BETTER_INK_PICTURE_PROTOCOL=kitty|none` forces the protocol. Install `sharp` to decode WebP, AVIF and TIFF, and to
|
|
50
|
+
decode JPEG and GIF faster. Without it, JPEG and GIF use pure-JS decoders, and other formats fall back to a link.
|
|
51
|
+
|
|
52
|
+
## Bundlers
|
|
53
|
+
|
|
54
|
+
By default the worker loads from `worker.mjs` beside the main module. A bundled app, such as
|
|
55
|
+
`bun build --compile`, should build `better-ink-picture/worker` as its own entrypoint and start it:
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
<ImageProvider capabilities={capabilities} worker={() => new Worker(new URL("./image-worker.js", import.meta.url))}>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Limits
|
|
62
|
+
|
|
63
|
+
- Inside tmux or screen, images fall back to links.
|
|
64
|
+
- GIFs show their first frame.
|
|
65
|
+
- An image is at most 297×297 cells, the size of the protocol's placeholder table.
|
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
import { ReactNode } from "react";
|
|
2
|
+
/**
|
|
3
|
+
* An image to show:
|
|
4
|
+
* - a file path (absolute, relative to the working directory, or `~/`-prefixed)
|
|
5
|
+
* - an `http(s):` or `file:` URL
|
|
6
|
+
* - a `data:` URL, or a bare base64 string
|
|
7
|
+
* - the encoded bytes themselves
|
|
8
|
+
* - any of the above stated explicitly, when a string could be read more than one way
|
|
9
|
+
*/
|
|
10
|
+
type ImageSource = string | Uint8Array | {
|
|
11
|
+
path: string;
|
|
12
|
+
} | {
|
|
13
|
+
url: string;
|
|
14
|
+
} | {
|
|
15
|
+
base64: string;
|
|
16
|
+
} | {
|
|
17
|
+
bytes: Uint8Array;
|
|
18
|
+
};
|
|
19
|
+
type ImageFormat = "png" | "jpeg" | "gif" | "webp" | "bmp" | "avif" | "tiff" | "unknown";
|
|
20
|
+
/** What a probe learns about an image, from as few of its bytes as it can. */
|
|
21
|
+
type ImageMeta = {
|
|
22
|
+
/** Identifies the image's contents across sources and renders. */
|
|
23
|
+
key: string;
|
|
24
|
+
/** Pixel width, as displayed (after EXIF orientation). */
|
|
25
|
+
width: number;
|
|
26
|
+
/** Pixel height, as displayed (after EXIF orientation). */
|
|
27
|
+
height: number;
|
|
28
|
+
format: ImageFormat;
|
|
29
|
+
};
|
|
30
|
+
type Size = {
|
|
31
|
+
width: number;
|
|
32
|
+
height: number;
|
|
33
|
+
};
|
|
34
|
+
type TerminalCapabilities = {
|
|
35
|
+
/**
|
|
36
|
+
* How images are drawn: `kitty` is the Kitty graphics protocol with Unicode
|
|
37
|
+
* placeholders (Kitty ≥ 0.28, Ghostty); `none` stands an image as a link to
|
|
38
|
+
* a file instead.
|
|
39
|
+
*/
|
|
40
|
+
protocol: "kitty" | "none";
|
|
41
|
+
/**
|
|
42
|
+
* Whether the terminal can read files this process writes, so an image is
|
|
43
|
+
* sent as its path rather than its bytes (false over SSH, for one).
|
|
44
|
+
*/
|
|
45
|
+
fileTransfer: boolean;
|
|
46
|
+
/** Whether the terminal opens OSC 8 hyperlinks. */
|
|
47
|
+
hyperlinks: boolean;
|
|
48
|
+
/** One cell's size in pixels. */
|
|
49
|
+
cell: Size;
|
|
50
|
+
/** The window's size in pixels, when the terminal reported it. */
|
|
51
|
+
window?: Size;
|
|
52
|
+
/** The terminal's own name and version, from XTVERSION. */
|
|
53
|
+
terminal?: {
|
|
54
|
+
name: string;
|
|
55
|
+
version?: string;
|
|
56
|
+
};
|
|
57
|
+
/** How the capabilities were found. */
|
|
58
|
+
detectedBy: "query" | "environment" | "override";
|
|
59
|
+
};
|
|
60
|
+
/** A worker as either Node's `worker_threads` or the web's `Worker` makes it. */
|
|
61
|
+
type WorkerLike = {
|
|
62
|
+
postMessage(message: unknown): void;
|
|
63
|
+
terminate?(): unknown;
|
|
64
|
+
unref?(): void;
|
|
65
|
+
on?(event: "message", listener: (message: unknown) => void): unknown;
|
|
66
|
+
addEventListener?(type: "message", listener: (event: {
|
|
67
|
+
data: unknown;
|
|
68
|
+
}) => void): unknown;
|
|
69
|
+
};
|
|
70
|
+
/** The stream Ink renders to: a terminal, with its descriptor and size. */
|
|
71
|
+
type Output = NodeJS.WritableStream & {
|
|
72
|
+
fd?: number;
|
|
73
|
+
columns?: number;
|
|
74
|
+
rows?: number;
|
|
75
|
+
};
|
|
76
|
+
type ImageClientOptions = {
|
|
77
|
+
/** What the terminal can do; detect it with `detectTerminal()` before rendering. */
|
|
78
|
+
capabilities?: TerminalCapabilities;
|
|
79
|
+
/** The stream Ink renders to. Images are written to its file descriptor. */
|
|
80
|
+
stdout?: Output;
|
|
81
|
+
/**
|
|
82
|
+
* Starts the image worker. The default loads `worker.mjs` beside this
|
|
83
|
+
* module; a bundled app (`bun build --compile`, say) builds
|
|
84
|
+
* `better-ink-picture/worker` as its own entrypoint and starts that here.
|
|
85
|
+
*/
|
|
86
|
+
worker?: () => WorkerLike;
|
|
87
|
+
/** Where images without a file of their own are written. */
|
|
88
|
+
tmpdir?: string;
|
|
89
|
+
/** How long an image stays in the terminal after it leaves the screen, in ms. */
|
|
90
|
+
releaseDelay?: number;
|
|
91
|
+
};
|
|
92
|
+
type Settled<T> = {
|
|
93
|
+
promise: Promise<T>;
|
|
94
|
+
value?: T;
|
|
95
|
+
error?: unknown;
|
|
96
|
+
};
|
|
97
|
+
/**
|
|
98
|
+
* The main thread's side of the image worker. It does no image work itself:
|
|
99
|
+
* it hands sources to the worker, remembers what came back so a component
|
|
100
|
+
* that mounts again renders at once, and counts who shows each image so it
|
|
101
|
+
* leaves the terminal only once nothing does.
|
|
102
|
+
*/
|
|
103
|
+
export declare class ImageClient {
|
|
104
|
+
readonly capabilities: TerminalCapabilities;
|
|
105
|
+
private readonly stdout;
|
|
106
|
+
private readonly startWorker;
|
|
107
|
+
private readonly directory;
|
|
108
|
+
private readonly releaseDelay;
|
|
109
|
+
private worker?;
|
|
110
|
+
private lock?;
|
|
111
|
+
private restoreWrite?;
|
|
112
|
+
private nextRequest;
|
|
113
|
+
private readonly requests;
|
|
114
|
+
private readonly probes;
|
|
115
|
+
private readonly files;
|
|
116
|
+
private readonly views;
|
|
117
|
+
private readonly viewIds;
|
|
118
|
+
private readonly failures;
|
|
119
|
+
private readonly listeners;
|
|
120
|
+
private nextId;
|
|
121
|
+
private disposed;
|
|
122
|
+
constructor({ capabilities, stdout, worker, tmpdir: directory, releaseDelay }?: ImageClientOptions);
|
|
123
|
+
/** The worker, started on first use: an app that shows no images starts none. */
|
|
124
|
+
private ensureWorker;
|
|
125
|
+
/** The most pixels worth decoding: the window's size, as near as it's known. */
|
|
126
|
+
private maxPixels;
|
|
127
|
+
/** Takes the terminal lock around each of the main thread's own writes. */
|
|
128
|
+
private guardWrites;
|
|
129
|
+
private post;
|
|
130
|
+
private onMessage;
|
|
131
|
+
private request;
|
|
132
|
+
private settle;
|
|
133
|
+
/**
|
|
134
|
+
* An image's size and key, from the worker — once per source, however many
|
|
135
|
+
* components show it. `peekProbe` has it at once when it's already known.
|
|
136
|
+
*/
|
|
137
|
+
probe(src: ImageSource): Settled<ImageMeta>;
|
|
138
|
+
/** A file to open an image from: its own path, or a copy in the temp directory. */
|
|
139
|
+
file(src: ImageSource): Settled<string>;
|
|
140
|
+
/**
|
|
141
|
+
* The id an image is drawn under at a size. Each size is its own image in
|
|
142
|
+
* the terminal: its placeholders are scaled to the grid it was placed on.
|
|
143
|
+
*/
|
|
144
|
+
viewId(key: string, columns: number, rows: number): number;
|
|
145
|
+
/** Puts an image on screen (sending it, the first time) for as long as it's retained. */
|
|
146
|
+
retain(id: number): void;
|
|
147
|
+
/**
|
|
148
|
+
* Lets an image go. It stays a moment in case it's shown again — a
|
|
149
|
+
* re-render, a resize back — and then leaves the terminal.
|
|
150
|
+
*/
|
|
151
|
+
release(id: number): void;
|
|
152
|
+
/** Why an image couldn't be sent, if it couldn't. */
|
|
153
|
+
failure(id: number): string | undefined;
|
|
154
|
+
subscribe(listener: () => void): () => boolean;
|
|
155
|
+
private emit;
|
|
156
|
+
/** Removes every image this client sent from the terminal, and stops the worker. */
|
|
157
|
+
dispose(): void;
|
|
158
|
+
private stop;
|
|
159
|
+
}
|
|
160
|
+
type Env = Record<string, string | undefined>;
|
|
161
|
+
/** The environment variable that forces a protocol: `kitty` or `none`. */
|
|
162
|
+
export declare const PROTOCOL_ENV = "BETTER_INK_PICTURE_PROTOCOL";
|
|
163
|
+
/**
|
|
164
|
+
* Whether a terminal opens OSC 8 hyperlinks. No terminal can be asked, so
|
|
165
|
+
* this goes by its name and environment; `FORCE_HYPERLINK` overrides.
|
|
166
|
+
*/
|
|
167
|
+
export declare const supportsHyperlinks: (env: Env, terminal?: {
|
|
168
|
+
name: string;
|
|
169
|
+
version?: string;
|
|
170
|
+
}) => boolean;
|
|
171
|
+
/**
|
|
172
|
+
* Capabilities from the environment alone, for when the terminal can't be
|
|
173
|
+
* asked. Less sure than {@link detectTerminal}: an environment variable
|
|
174
|
+
* survives into places its terminal doesn't (tmux, SSH), so this guesses
|
|
175
|
+
* `kitty` only for a local, unmultiplexed Kitty or Ghostty.
|
|
176
|
+
*/
|
|
177
|
+
export declare const capabilitiesFromEnvironment: (env?: Env) => TerminalCapabilities;
|
|
178
|
+
type DetectOptions = {
|
|
179
|
+
stdin?: NodeJS.ReadStream;
|
|
180
|
+
stdout?: NodeJS.WriteStream;
|
|
181
|
+
env?: Env;
|
|
182
|
+
/** How long to wait for the terminal's answers, in ms. */
|
|
183
|
+
timeout?: number;
|
|
184
|
+
};
|
|
185
|
+
/**
|
|
186
|
+
* Asks the terminal what it can do: whether it speaks Kitty graphics, both
|
|
187
|
+
* sent directly and read from a file; its cell and window sizes in pixels;
|
|
188
|
+
* and its name. Primary device attributes, which every terminal answers, are
|
|
189
|
+
* asked last, so their answer means the rest are in — this waits as long as
|
|
190
|
+
* the terminal takes to answer and no longer, and the timeout covers only a
|
|
191
|
+
* terminal that answers nothing.
|
|
192
|
+
*
|
|
193
|
+
* Call it before Ink's `render()`: it reads stdin in raw mode, and once Ink
|
|
194
|
+
* owns stdin the answers would arrive as keystrokes.
|
|
195
|
+
*/
|
|
196
|
+
export declare const detectTerminal: ({ stdin, stdout, env, timeout }?: DetectOptions) => Promise<TerminalCapabilities>;
|
|
197
|
+
type FitOptions = {
|
|
198
|
+
/** The image's size in pixels. */
|
|
199
|
+
image: Size;
|
|
200
|
+
/** One cell's size in pixels. */
|
|
201
|
+
cell: Size;
|
|
202
|
+
/** The most columns to take; unset leaves width to the height (or the bounds). */
|
|
203
|
+
width?: number;
|
|
204
|
+
/** The most rows to take; unset leaves height to the width (or the bounds). */
|
|
205
|
+
height?: number;
|
|
206
|
+
/** Space the image may never exceed, such as the terminal's size. */
|
|
207
|
+
bounds?: Size;
|
|
208
|
+
/** Whether to scale past the image's own size. */
|
|
209
|
+
upscale?: boolean;
|
|
210
|
+
};
|
|
211
|
+
/**
|
|
212
|
+
* The fewest whole cells that show an image at the largest size its limits
|
|
213
|
+
* allow, keeping its aspect ratio:
|
|
214
|
+
*
|
|
215
|
+
* - with `width`, the image scales to that many columns, and its rows follow;
|
|
216
|
+
* - with `height`, to that many rows, and its columns follow;
|
|
217
|
+
* - with both, to the largest size that fits inside both;
|
|
218
|
+
* - with neither, its own size.
|
|
219
|
+
*
|
|
220
|
+
* It never grows past its own pixel size (unless `upscale`), nor past
|
|
221
|
+
* `bounds`, and never takes a cell more than it fills.
|
|
222
|
+
*/
|
|
223
|
+
export declare const fitCells: ({ image, cell, width, height, bounds, upscale }: FitOptions) => {
|
|
224
|
+
columns: number;
|
|
225
|
+
rows: number;
|
|
226
|
+
};
|
|
227
|
+
/** What a fallback link points to. */
|
|
228
|
+
type ImageLink = {
|
|
229
|
+
/** The file the image can be opened from. */
|
|
230
|
+
path: string;
|
|
231
|
+
/** Its `file:` URL. */
|
|
232
|
+
url: string;
|
|
233
|
+
/** Whether the terminal opens OSC 8 links. */
|
|
234
|
+
hyperlinks: boolean;
|
|
235
|
+
alt?: string;
|
|
236
|
+
};
|
|
237
|
+
type ImageLoad = ImageMeta & {
|
|
238
|
+
columns: number;
|
|
239
|
+
rows: number;
|
|
240
|
+
};
|
|
241
|
+
type ImageProps = {
|
|
242
|
+
/** A file path, URL, data URL, base64 string, or the image's bytes. */
|
|
243
|
+
src: ImageSource;
|
|
244
|
+
/**
|
|
245
|
+
* The most columns to take. With only `width`, the image scales to it and
|
|
246
|
+
* its rows follow; with `height` too, it fits inside both.
|
|
247
|
+
*/
|
|
248
|
+
width?: number;
|
|
249
|
+
/** The most rows to take. With only `height`, the image scales to it and its columns follow. */
|
|
250
|
+
height?: number;
|
|
251
|
+
/** Whether to scale an image past its own pixel size. */
|
|
252
|
+
upscale?: boolean;
|
|
253
|
+
/** Describes the image; the fallback link's text. */
|
|
254
|
+
alt?: string;
|
|
255
|
+
/** Shown while the image's size is read — usually a few milliseconds, once. */
|
|
256
|
+
loading?: ReactNode;
|
|
257
|
+
/** Renders the link to an image the terminal can't draw. */
|
|
258
|
+
fallback?: (link: ImageLink) => ReactNode;
|
|
259
|
+
onLoad?: (image: ImageLoad) => void;
|
|
260
|
+
onError?: (error: Error) => void;
|
|
261
|
+
};
|
|
262
|
+
/**
|
|
263
|
+
* An image, drawn at full resolution by a terminal that speaks the Kitty
|
|
264
|
+
* graphics protocol (Kitty, Ghostty), and otherwise a link to a file of it.
|
|
265
|
+
*
|
|
266
|
+
* Every byte of image work happens in a worker; the component itself only
|
|
267
|
+
* lays out a grid of placeholder characters, which costs no more to render
|
|
268
|
+
* than a line of text.
|
|
269
|
+
*/
|
|
270
|
+
export declare function Image(props: ImageProps): import("react").JSX.Element;
|
|
271
|
+
/**
|
|
272
|
+
* The image client for this tree: the provider's, or — with no provider — a
|
|
273
|
+
* shared one that guesses the terminal from its environment.
|
|
274
|
+
*/
|
|
275
|
+
export declare const useImageClient: () => ImageClient;
|
|
276
|
+
type ImageProviderProps = Omit<ImageClientOptions, "stdout"> & {
|
|
277
|
+
children?: ReactNode;
|
|
278
|
+
};
|
|
279
|
+
/**
|
|
280
|
+
* Gives the images inside it one worker and what the terminal can do. Pass
|
|
281
|
+
* `capabilities` from `await detectTerminal()`, run before Ink's `render()`;
|
|
282
|
+
* without them, the terminal is guessed from its environment.
|
|
283
|
+
*
|
|
284
|
+
* On unmount, every image it put in the terminal is deleted.
|
|
285
|
+
*/
|
|
286
|
+
export declare function ImageProvider({ children, ...options }: ImageProviderProps): import("react").JSX.Element;
|
|
287
|
+
export type { DetectOptions, FitOptions, ImageClientOptions, ImageFormat, ImageLink, ImageLoad, ImageMeta, ImageProps, ImageProviderProps, ImageSource, TerminalCapabilities, WorkerLike };
|
|
288
|
+
//# sourceMappingURL=index.d.mts.map
|