Programmatic API

Everything the CLI does is exported from @noctcore/showcase-kit:

import { capture, exportPortfolio, frame, generateIcons, hero, loadConfig, readmeSnippet } from '@noctcore/showcase-kit';

const config = await loadConfig(); // or loadConfig('path/to/showcase.config.mjs')
await capture(config, { only: ['library'], langs: ['en'] });
await frame(config);
await exportPortfolio(config);
console.log(readmeSnippet(config, { lang: 'en', cols: 2 }));
await hero(config);
await generateIcons('mascot.png', 'web', 'public');

resolveConfig(object, rootDir) validates a config object without a file, with the same checks as the CLI (see Config). defineConfig only exists for types and editor completion: it reads target.mode, so tty setup and nav functions get the terminal session instead of a page. A resolved config is a web or a tty config; isTtyConfig(config) tells them apart.

The terminal engine is exported too, for scripts of your own: openTtySession({ command, cwd, env, cols, rows }) returns a session with press, type, waitForText, screen and close, and renderTtyScreen(page, session.screen(), resolveTerminalOptions(undefined, cwd), 2) renders a screen to a PNG in a Playwright page whose context has the same device scale factor. parseKeys, DARK_THEME, LIGHT_THEME and TERMINAL_DEFAULTS come with them.

record(config, { only, langs }) records clips, and encodeAnimation(frames, { format, loop, quality, fps }) is the encoder behind it: frames of one size as { png, delayMs } in, an animated WebP (lossless, or lossy with quality), a GIF, or an MP4 through ffmpeg out. A delay longer than one WebP or GIF frame can hold (65535 ms in sharp) is split into repeats of the same image, and input it cannot encode is refused with a ShowcaseError.

Errors meant for the person running a command are ShowcaseErrors; an invalid config throws a ConfigError, a ShowcaseError whose issues lists every problem.

The rest of this page is generated from src/index.ts on each build: every export, whether it exists at runtime or only as a type, its summary from the source and its signature.

Config

CONFIG_NAMES

const, runtime export, from src/config/load.ts

const CONFIG_NAMES: readonly ["showcase.config.ts", "showcase.config.mts", "showcase.config.mjs", "showcase.config.js"]

defineConfig

function, runtime export, from src/config/define.ts

Identity helper that gives a config file full type checking and editor completion. The mode comes from target.mode, so in tty mode setup and function navs get the terminal session instead of a page.

function defineConfig<M extends Mode = "url" | "cdp">(config: ShowcaseConfig<M> & { target: { mode: M; }; }): ShowcaseConfig<M>

findConfigFile

function, runtime export, from src/config/load.ts

Find a config file in from or a parent directory, stopping at the first directory that holds a package.json or .git (the project root): a config above it belongs to some other project.

function findConfigFile(from?: string): string | undefined

init

function, runtime export, from src/init.ts

Write a starter config into dir. Refuses to overwrite an existing config unless force.

function init(dir: string, { typescript, force, tty }?: { typescript?: boolean | undefined; force?: boolean | undefined; tty?: boolean | undefined; }): string

isTtyConfig

function, runtime export, from src/config/resolve.ts

Narrows a resolved config to tty mode.

function isTtyConfig(config: ResolvedConfig): config is ResolvedTtyConfig

loadConfig

function, runtime export, from src/config/load.ts

Load, validate and resolve a config file. Without file, search from cwd upward.

function loadConfig(file?: string | undefined, cwd?: string): Promise<ResolvedConfig>

resolveConfig

function, runtime export, from src/config/resolve.ts

Validate a user config and fill in every default.

function resolveConfig(input: unknown, root: string, source?: string | undefined): ResolvedConfig

starterConfig

function, runtime export, from src/init.ts

The starter config text, filled in from the package.json in dir where possible.

function starterConfig(dir: string, typescript: boolean, { tty }?: { tty?: boolean | undefined; }): string

Pipeline

capture

function, runtime export, from src/capture.ts

Capture raw screenshots of every selected shot in every selected language.

function capture(config: ResolvedConfig, options?: CaptureOptions): Promise<CaptureResult>

frame

function, runtime export, from src/frame/index.ts

Turn raw captures into framed README images at outputs.readme.

function frame(config: ResolvedConfig, options?: FrameRunOptions): Promise<FramedFile[]>

record

function, runtime export, from src/record.ts

Record every selected clip in every selected language: a fresh app per clip, the steps on the clip's frame clock, each unique screen rendered once, framed like the README images, and written as each of the clip's formats.

function record(config: ResolvedConfig, options?: RecordOptions): Promise<RecordedClip[]>

CapturedFile

interface, type-only export, from src/capture.ts

interface CapturedFile {
    lang: string;
    id: string;
    path: string;
    width: number;
    height: number;
}

CaptureOptions

interface, type-only export, from src/capture.ts

interface CaptureOptions {
    only?: string[];
    langs?: string[];
}

CaptureResult

interface, type-only export, from src/capture.ts

interface CaptureResult {
    files: CapturedFile[];
    startedPid?: number;
}

FramedFile

interface, type-only export, from src/frame/index.ts

interface FramedFile {
    lang: string;
    id: string;
    path: string;
    width: number;
    height: number;
}

FrameRunOptions

interface, type-only export, from src/frame/index.ts

interface FrameRunOptions {
    only?: string[];
    langs?: string[];
}

RecordedClip

interface, type-only export, from src/record.ts

interface RecordedClip {
    lang: string;
    id: string;
    width: number;
    height: number;
    frames: number;
    durationMs: number;
    files: RecordedFile[];
}

RecordedFile

interface, type-only export, from src/record.ts

interface RecordedFile {
    format: ClipFormat;
    path: string;
    bytes: number;
}

RecordOptions

interface, type-only export, from src/record.ts

interface RecordOptions {
    only?: string[];
    langs?: string[];
}

Outputs

encodeIcns

function, runtime export, from src/icons.ts

A macOS .icns holding PNG images.

function encodeIcns(images: { type: string; data: Buffer<ArrayBufferLike>; }[]): Buffer<ArrayBufferLike>

encodeIco

function, runtime export, from src/icons.ts

A Windows .ico holding PNG images, one per size (the format Vista and later read).

function encodeIco(images: { size: number; data: Buffer<ArrayBufferLike>; }[]): Buffer<ArrayBufferLike>

exportPortfolio

function, runtime export, from src/portfolio.ts

Export 16:9 (or any size) portfolio images: the framed window contained on the background at exactly size pixels, a thumbnail copy, and a gallery JSON the portfolio can import.

function exportPortfolio(config: ResolvedConfig, options?: { only?: string[] | undefined; }): Promise<PortfolioResult>

GALLERY_FILE

const, runtime export, from src/config/resolve.ts

const GALLERY_FILE: "showcase.gallery.json"

generateIcons

function, runtime export, from src/icons.ts

Write an app icon set for preset from one square source image.

function generateIcons(source: string, preset: IconPreset, outDir: string): Promise<{ file: string; path: string; }[]>

hero

function, runtime export, from src/hero.ts

Render the README hero banner to hero.output at exactly hero.size pixels.

function hero(config: ResolvedConfig): Promise<{ path: string; width: number; height: number; }>

heroHtml

function, runtime export, from src/hero.ts

The hero page: text and framed shots, arranged by hero.layout.

function heroHtml(config: ResolvedConfig, { windows, logo }: { windows: HeroWindow[]; logo: string | undefined; }): string

ICON_PRESETS

const, runtime export, from src/icons.ts

const ICON_PRESETS: Record<IconPreset, IconFile[]>

readmeSnippet

function, runtime export, from src/readme.ts

An HTML table of the framed images, images in one row and <sub> captions in the next, ready to paste into a README. Clips follow the shots: an <img> of the WebP (or GIF), with a link to the MP4 when there is one, or only a link for an MP4-only clip.

function readmeSnippet(config: ResolvedConfig, options?: ReadmeOptions): string

GalleryItem

interface, type-only export, from src/portfolio.ts

Matches the portfolio's GalleryItem type.

interface GalleryItem {
    src: string;
    alt: string;
    caption: string;
}

IconPreset

type, type-only export, from src/icons.ts

type IconPreset = 'web' | 'electron' | 'tauri';

PortfolioResult

interface, type-only export, from src/portfolio.ts

interface PortfolioResult {
    dir: string;
    files: string[];
    thumbnail: string | undefined;
    gallery: GalleryItem[];
    galleryFile: string | undefined;
}

ReadmeLayout

type, type-only export, from src/readme.ts

How showcase readme lays out the images. Every layout uses only HTML that GitHub keeps in a README.

type ReadmeLayout = 'table' | 'rows' | 'featured' | 'details' | 'list';

ReadmeOptions

interface, type-only export, from src/readme.ts

interface ReadmeOptions {
    lang?: string;
    layout?: ReadmeLayout;
    cols?: number;
    base?: string;
    only?: string[];
}

Terminal engine

DARK_THEME

const, runtime export, from src/tty/theme.ts

Tokyo Night.

const DARK_THEME: TerminalTheme

LIGHT_THEME

const, runtime export, from src/tty/theme.ts

Tokyo Night Day.

const LIGHT_THEME: TerminalTheme

openTtySession

const, runtime export, from src/tty/session.ts

Starts a session. Implemented by the engine; lazily loads the PTY package with a friendly install error.

const openTtySession: OpenTtySession

parseKeys

function, runtime export, from src/tty/keys.ts

Turn Keys into keystrokes: one string of bytes per key, to be written one at a time. Plain text is typed a character at a time; {Name} is a key (see KNOWN); {{ is a literal {. Unknown names are errors.

function parseKeys(keys: Keys, opts?: KeyOptions): string[]

renderTtyScreen

const, runtime export, from src/tty/render.ts

Render a screen to a PNG of the terminal area (grid plus padding) at deviceScaleFactor.

const renderTtyScreen: RenderTtyScreen

resolveTerminalOptions

function, runtime export, from src/tty/theme.ts

Fill in every default and make font paths absolute (relative to baseDir, the config's folder). It checks what the renderer relies on (16 ansi colors, #rrggbb colors, positive sizes, font files that exist) and throws a ShowcaseError otherwise; the config layer still owns shape checks such as unknown keys.

function resolveTerminalOptions(opts: TerminalOptions | undefined, baseDir: string): ResolvedTerminalOptions

TERMINAL_DEFAULTS

const, runtime export, from src/tty/theme.ts

const TERMINAL_DEFAULTS: { readonly size: 15; readonly lineHeight: 1.32; readonly padding: 12; readonly cursor: "hide"; }

Encoding

encodeAnimation

function, runtime export, from src/encode.ts

Encode frames as an animated WebP or GIF (with sharp) or an MP4 (with ffmpeg from PATH).

function encodeAnimation(frames: AnimationFrame[], opts: EncodeOptions): Promise<Buffer<ArrayBufferLike>>

AnimationFormat

type, type-only export, from src/encode.ts

type AnimationFormat = 'webp' | 'gif' | 'mp4';

AnimationFrame

interface, type-only export, from src/encode.ts

One frame of an animation: a PNG and how long it stays on screen.

interface AnimationFrame {
    png: Buffer;
    delayMs: number;
}

EncodeOptions

interface, type-only export, from src/encode.ts

interface EncodeOptions {
    format: AnimationFormat;
    loop?: number;
    quality?: number;
    fps?: number;
}

Errors

ConfigError

class, runtime export, from src/errors.ts

class ConfigError extends ShowcaseError {
  constructor(issues: string[], source?: string | undefined);
  name: string;
  readonly issues: string[];
}

ShowcaseError

class, runtime export, from src/errors.ts

An error with a message meant for the person running the CLI: printed without a stack trace.

class ShowcaseError extends Error {
  constructor(message?: string | undefined);
  constructor(message?: string | undefined, options?: ErrorOptions | undefined);
  name: string;
}

Types

The config types behind Config, their resolved forms, and the terminal engine’s contract.

Background

type, type-only export, from src/config/types.ts

What a frame or the hero sits on.

type Background = string | {
    type: 'solid';
    color: string;
} | {
    type: 'gradient';
    from: string;
    to: string;
    angle?: number;
} | {
    type: 'transparent';
} | {
    type: 'mesh';
    colors: string[];
} | {
    type: 'dots';
    color: string;
    dot?: string;
    spacing?: number;
} | {
    type: 'noise';
    from: string;
    to: string;
    angle?: number;
    amount?: number;
};

BrowserOptions

interface, type-only export, from src/config/types.ts

Which Chromium the kit launches, and how.

interface BrowserOptions {
    channel?: string;
    executablePath?: string;
    headless?: boolean;
    args?: string[];
}

CdpTarget

interface, type-only export, from src/config/types.ts

A running Chromium based app the kit attaches to over the DevTools Protocol.

interface CdpTarget {
    mode: 'cdp';
    cdpUrl?: string;
    pageMatch?: string | RegExp;
    start?: string;
    cwd?: string;
    env?: Record<string, string>;
    readyTimeoutMs?: number;
}

Clip

interface, type-only export, from src/config/types.ts

A short animated recording of a terminal app, written by showcase record. Each clip starts a fresh app.

interface Clip {
    id: string;
    title?: string;
    caption?: string;
    alt?: string;
    steps: ClipStep[];
    fps?: number;
    durationMs?: number;
    maxFrames?: number;
    tailMs?: number;
    formats?: ClipFormat[];
}

ClipFormat

type, type-only export, from src/config/types.ts

A clip file format.

type ClipFormat = 'webp' | 'gif' | 'mp4';

ClipStep

type, type-only export, from src/config/types.ts

One step of a clip's timeline. Steps run on the clip's frame clock, so a key's effect shows from the next frame.

type ClipStep = {
    keys: Keys;
} | {
    type: string;
    delayMs?: number;
} | {
    waitFor: string | RegExp;
} | {
    sleep: number;
};

CommonConfig

interface, type-only export, from src/config/types.ts

Settings shared by every mode.

interface CommonConfig {
    name: string;
    slug?: string;
    root?: string;
    deviceScaleFactor?: number;
    langs?: string[];
    frame?: FrameOptions;
    outputs?: Outputs;
    hero?: HeroOptions;
    browser?: BrowserOptions;
    timeouts?: Timeouts;
}

FrameOptions

interface, type-only export, from src/config/types.ts

How a capture is framed for the README, the portfolio, the hero and clips.

interface FrameOptions {
    style?: FrameStyle;
    theme?: 'light' | 'dark';
    title?: string | false;
    address?: string;
    background?: Background;
    padding?: number;
    radius?: number;
    shadow?: boolean;
    quality?: number;
    maxWidth?: number;
}

FrameStyle

type, type-only export, from src/config/types.ts

The window chrome around a capture. window reads as macOS, windows as Windows 11, browser as a browser with an address bar, and terminal as a terminal emulator.

type FrameStyle = 'window' | 'minimal' | 'none' | 'browser' | 'windows' | 'terminal';

HeroLayout

type, type-only export, from src/config/types.ts

How the hero banner is composed.

type HeroLayout = 'stack' | 'spotlight' | 'split' | 'row' | 'mosaic' | 'centered';

HeroOptions

interface, type-only export, from src/config/types.ts

The README banner that showcase hero renders.

interface HeroOptions {
    layout?: HeroLayout;
    tagline?: string;
    logo?: string;
    shots?: string[];
    lang?: string;
    output?: string;
    size?: [
        number,
        number
    ];
    background?: Background;
    theme?: 'light' | 'dark';
    quality?: number;
}

Keys

type, type-only export, from src/tty/types.ts

Keys to send. Plain text is typed as is; names in braces are keys: {Enter}, {Down}, {Tab}, {Esc}, {C-c}.

type Keys = string | string[];

Mode

type, type-only export, from src/config/types.ts

The target modes: 'url', 'cdp' or 'tty'.

type Mode = Target['mode'];

Nav

type, type-only export, from src/config/types.ts

How to reach a shot.

type Nav = string | {
    click: string;
} | {
    goto: string;
} | NavFn;

NavFn

type, type-only export, from src/config/types.ts

Navigate to a shot: click a selector, visit a path or URL, or run your own steps.

type NavFn = (page: Page) => Promise<void> | void;

OpenTtySession

type, type-only export, from src/tty/types.ts

Starts a session. Implemented by the engine; lazily loads the PTY package with a friendly install error.

type OpenTtySession = (opts: TtySessionOptions) => Promise<TtySession>;

Outputs

interface, type-only export, from src/config/types.ts

Where each kind of file is written, relative to the config root.

interface Outputs {
    raw?: string;
    readme?: string | false;
    portfolio?: PortfolioOutput;
    clips?: string;
}

PortfolioOutput

interface, type-only export, from src/config/types.ts

Fixed-size images for a portfolio site, a thumbnail and a gallery JSON.

interface PortfolioOutput {
    dir: string;
    size?: [
        number,
        number
    ];
    format?: 'webp' | 'png';
    quality?: number;
    thumbnail?: string;
    lang?: string;
    publicPath?: string;
    padding?: number;
    gallery?: string | false;
}

RenderTtyScreen

type, type-only export, from src/tty/types.ts

Renders a screen to a PNG in an existing Chromium page (the kit's browser), at deviceScaleFactor. The PNG is the terminal area: grid plus padding on the theme background, ready for frame, portfolio and hero.

type RenderTtyScreen = (page: Page, screen: TtyScreen, look: ResolvedTerminalOptions, deviceScaleFactor: number) => Promise<Buffer>;

ResolvedBackground

type, type-only export, from src/config/types.ts

A background in its object form, with angle filled in.

type ResolvedBackground = {
    type: 'solid';
    color: string;
} | {
    type: 'gradient';
    from: string;
    to: string;
    angle: number;
} | {
    type: 'transparent';
} | {
    type: 'mesh';
    colors: string[];
} | {
    type: 'dots';
    color: string;
    dot: string;
    spacing: number;
} | {
    type: 'noise';
    from: string;
    to: string;
    angle: number;
    amount: number;
};

ResolvedClip

interface, type-only export, from src/config/types.ts

A clip with its defaults filled in.

interface ResolvedClip {
    id: string;
    title: string;
    caption: string | undefined;
    alt: string;
    steps: ClipStep[];
    fps: number;
    durationMs: number | undefined;
    maxFrames?: number;
    tailMs: number;
    formats: ClipFormat[];
}

ResolvedConfig

type, type-only export, from src/config/types.ts

A validated config with every default filled in: the web or the tty kind, told apart by target.mode.

type ResolvedConfig = ResolvedWebConfig | ResolvedTtyConfig;

ResolvedFrame

interface, type-only export, from src/config/types.ts

frame with every default filled in.

interface ResolvedFrame {
    style: FrameStyle;
    theme: 'light' | 'dark';
    title: string | false;
    address: string;
    background: ResolvedBackground;
    padding: number;
    radius: number;
    shadow: boolean;
    quality: number;
    maxWidth: number | undefined;
}

ResolvedHero

interface, type-only export, from src/config/types.ts

hero with every default filled in.

interface ResolvedHero {
    layout: HeroLayout;
    tagline: string | undefined;
    logo: string | undefined;
    shots: string[];
    lang: string;
    output: string;
    size: [
        number,
        number
    ];
    background: ResolvedBackground;
    theme: 'light' | 'dark';
    quality: number;
}

ResolvedPortfolio

interface, type-only export, from src/config/types.ts

outputs.portfolio with every default filled in.

interface ResolvedPortfolio {
    dir: string;
    size: [
        number,
        number
    ];
    format: 'webp' | 'png';
    quality: number;
    thumbnail: string;
    lang: string;
    publicPath: string;
    padding: number;
    gallery: string | false;
}

ResolvedShot

type, type-only export, from src/config/types.ts

A shot of either kind. Frames, the portfolio, the hero and the README only read id, title, alt, caption.

type ResolvedShot = ResolvedWebShot | ResolvedTtyShot;

ResolvedTerminalOptions

interface, type-only export, from src/tty/types.ts

TerminalOptions with every default filled in and every file path absolute.

interface ResolvedTerminalOptions {
    theme: TerminalTheme;
    font: {
        file?: string;
        boldFile?: string;
        italicFile?: string;
        boldItalicFile?: string;
        fallbackFile?: string;
        size: number;
    };
    lineHeight: number;
    padding: number;
    cursor: 'hide' | 'show';
}

ResolvedTtyConfig

interface, type-only export, from src/config/types.ts

A tty mode config with every default filled in.

interface ResolvedTtyConfig extends ResolvedCommon {
    target: ResolvedTtyTarget;
    ready: string | RegExp | undefined;
    terminal: ResolvedTerminalOptions;
    setup: TtyConfig['setup'];
    shots: ResolvedTtyShot[];
    clips: ResolvedClip[];
}

ResolvedTtyShot

interface, type-only export, from src/config/types.ts

A tty shot with its defaults filled in.

interface ResolvedTtyShot extends TtyShot {
    title: string;
    alt: string;
    delayMs: number;
    restart: boolean;
}

ResolvedTtyTarget

interface, type-only export, from src/config/types.ts

A tty target with every default filled in and cwd absolute.

interface ResolvedTtyTarget {
    mode: 'tty';
    command: string | [
        file: string,
        ...args: string[]
    ];
    cwd: string;
    env: TtyTarget['env'];
    inheritEnv: boolean | string[];
    cols: number;
    rows: number;
    quitKey: string | false;
    inputDelayMs: number;
    readyTimeoutMs: number;
}

ResolvedWebConfig

interface, type-only export, from src/config/types.ts

A url or cdp mode config with every default filled in.

interface ResolvedWebConfig extends ResolvedCommon {
    target: WebTarget & {
        readyTimeoutMs: number;
    };
    ready: string | undefined;
    viewport: {
        width: number;
        height: number;
    };
    colorScheme: 'light' | 'dark' | 'no-preference';
    css: string | undefined;
    setup: WebConfig['setup'];
    shots: ResolvedWebShot[];
}

ResolvedWebShot

interface, type-only export, from src/config/types.ts

A web shot with its defaults filled in.

interface ResolvedWebShot extends Shot {
    title: string;
    alt: string;
    delayMs: number;
}

SetupContext

interface, type-only export, from src/config/types.ts

What setup receives in url and cdp mode.

interface SetupContext {
    page: Page;
    context: BrowserContext;
    lang: string;
    mode: WebTarget['mode'];
    config: ResolvedWebConfig;
}

Shot

interface, type-only export, from src/config/types.ts

A view to capture in url or cdp mode.

interface Shot {
    id: string;
    title?: string;
    caption?: string;
    alt?: string;
    nav?: Nav;
    waitFor?: string;
    delayMs?: number;
}

ShowcaseConfig

type, type-only export, from src/config/types.ts

The config a showcase.config.* file exports. Without a type argument it is the web config, as before tty mode; defineConfig picks the right one from target.mode.

type ShowcaseConfig<M extends Mode = WebTarget['mode']> = M extends 'tty' ? TtyConfig : WebConfig;

Target

type, type-only export, from src/config/types.ts

How to reach the app, told apart by mode.

type Target = UrlTarget | CdpTarget | TtyTarget;

TerminalOptions

interface, type-only export, from src/tty/types.ts

How the terminal looks when rendered. Every field is optional in config.

interface TerminalOptions {
    theme?: 'dark' | 'light' | TerminalTheme;
    font?: {
        file?: string;
        boldFile?: string;
        italicFile?: string;
        boldItalicFile?: string;
        fallbackFile?: string;
        size?: number;
    };
    lineHeight?: number;
    padding?: number;
    cursor?: 'hide' | 'show';
}

TerminalTheme

interface, type-only export, from src/tty/types.ts

A 16 color ANSI palette plus the default colors.

interface TerminalTheme {
    background: string;
    foreground: string;
    cursor?: string;
    ansi: string[];
}

Timeouts

interface, type-only export, from src/config/types.ts

How long to wait, in milliseconds.

interface Timeouts {
    readyMs?: number;
    shotMs?: number;
    networkIdleMs?: number;
}

TtyConfig

interface, type-only export, from src/config/types.ts

A terminal app captured from a pseudo terminal: mode: 'tty'.

interface TtyConfig extends CommonConfig {
    target: TtyTarget;
    ready?: string | RegExp;
    terminal?: TerminalOptions;
    setup?: (ctx: TtySetupContext) => Promise<void> | void;
    shots: TtyShot[];
    clips?: Clip[];
}

TtyNavFn

type, type-only export, from src/config/types.ts

Your own steps in tty mode: press keys, type, wait for text.

type TtyNavFn = (tty: TtySession) => Promise<void> | void;

TtyScreen

interface, type-only export, from src/tty/types.ts

An immutable copy of the visible screen, cheap to take and to compare.

interface TtyScreen {
    cols: number;
    rows: number;
    text: string;
    key: string;
    readonly grid: unknown;
}

TtySession

interface, type-only export, from src/tty/types.ts

A running app in a pseudo terminal.

interface TtySession {
    readonly pid: number;
    press(keys: Keys): Promise<void>;
    type(text: string, opts?: {
        delayMs?: number;
    }): Promise<void>;
    waitForText(pattern: string | RegExp, opts?: {
        timeoutMs?: number;
    }): Promise<void>;
    screenText(): string;
    screen(): TtyScreen;
    resize(cols: number, rows: number): Promise<void>;
    sleep(ms: number): Promise<void>;
    close(opts?: {
        quitKey?: string | false;
    }): Promise<void>;
    readonly exited: Promise<number | null>;
}

TtySessionOptions

interface, type-only export, from src/tty/types.ts

How to start the app under a pseudo terminal.

interface TtySessionOptions {
    command: string | [
        file: string,
        ...args: string[]
    ];
    cwd: string;
    env: Record<string, string>;
    inheritEnv?: boolean | string[];
    cols: number;
    rows: number;
}

TtySetupContext

interface, type-only export, from src/config/types.ts

What setup receives in tty mode.

interface TtySetupContext {
    tty: TtySession;
    lang: string;
    mode: 'tty';
    config: ResolvedTtyConfig;
}

TtyShot

interface, type-only export, from src/config/types.ts

A shot in tty mode. Shots run in order in one app process per language, so each starts where the last ended.

interface TtyShot {
    id: string;
    title?: string;
    caption?: string;
    alt?: string;
    keys?: Keys;
    nav?: TtyNavFn;
    waitFor?: string | RegExp;
    delayMs?: number;
    restart?: boolean;
}

TtyTarget

interface, type-only export, from src/config/types.ts

Runs a terminal app in a pseudo terminal and captures its screen. Needs @lydell/node-pty (or node-pty).

interface TtyTarget {
    mode: 'tty';
    command: string | [
        file: string,
        ...args: string[]
    ];
    cwd?: string;
    env?: Record<string, string> | ((ctx: {
        lang: string;
    }) => Record<string, string>);
    inheritEnv?: boolean | string[];
    cols?: number;
    rows?: number;
    quitKey?: string | false;
    inputDelayMs?: number;
    readyTimeoutMs?: number;
}

UrlTarget

interface, type-only export, from src/config/types.ts

A web app the kit opens in its own headless Chromium, starting it first if needed.

interface UrlTarget {
    mode: 'url';
    url: string;
    start?: string;
    cwd?: string;
    env?: Record<string, string>;
    readyTimeoutMs?: number;
    reuseExisting?: boolean;
}

WebConfig

interface, type-only export, from src/config/types.ts

A web app captured in a browser page: mode: 'url' or mode: 'cdp'.

interface WebConfig extends CommonConfig {
    target: WebTarget;
    ready?: string;
    viewport?: {
        width: number;
        height: number;
    };
    colorScheme?: 'light' | 'dark' | 'no-preference';
    css?: string;
    setup?: (ctx: SetupContext) => Promise<void> | void;
    shots: Shot[];
}

WebTarget

type, type-only export, from src/config/types.ts

The targets captured in a browser page.

type WebTarget = UrlTarget | CdpTarget;