@softov/ahpc 0.1.0

package/dist/src/tui.d.ts

@@ -0,0 +1,92 @@
+import type { UnicodeLevel } from '@textui/core';
+/**
+ * The entry point.
+ *
+ * Split from `app.tsx` so the example can be *mounted* without being *run*.
+ * What is here and not there: the terminal, the quit key, and the clock - the
+ * scripted host is driven by a timer here and by a test's own loop there,
+ * which is what makes streaming testable at all.
+ */
+interface Options {
+    static_: boolean;
+    width: number;
+    height: number;
+    unicode?: UnicodeLevel;
+    colors?: number;
+    /** Milliseconds a scripted word takes to arrive. */
+    tick: number;
+    /** Run the script to the end before the first frame, for a still. */
+    settled: boolean;
+    /** Or exactly this many scripted words, for a still of a turn mid-flight. */
+    pump?: number;
+    /**
+     * Write the still as an SVG here instead of ANSI on stdout.
+     *
+     * The form a still can be *looked at* in - a README, the docs, a pull
+     * request. An `.ans` file is only a screenshot on a terminal, so the places
+     * that most want to show what this looks like are the ones that cannot
+     * replay one.
+     */
+    svg?: string;
+    /** Which screen a still opens on. Absent is the one the application boots to. */
+    screen?: string;
+    session?: string;
+    theme: string;
+    shell: string;
+    /** The header trades its name for a creature, on an open session. */
+    boodInline: boolean;
+    /** The creature roams the whole application. */
+    boodFloat: boolean;
+    /** Say something on the open session before the frame is taken. */
+    say?: string;
+    /** Answer the confirmation the script stops at, to reach the question. */
+    approve: boolean;
+    /** ...and then answer the question, to reach the end of the turn. */
+    answer: boolean;
+    /**
+     * A real host: `ws://127.0.0.1:9187`, or wherever the editor advertises one.
+     *
+     * Left off, the scripted host runs - which is the point of the seam. The
+     * fake is for driving a shape on purpose (a blocked confirmation, a failing
+     * turn, a question) and the real one is for finding out what a host actually
+     * sends. Nothing above `HostConnection` knows which is which.
+     */
+    host?: string;
+    token?: string;
+    /** Read this config instead of the one XDG names. */
+    configFile?: string;
+    /** Keys from the config file, over the ones this client ships with. */
+    keys?: Record<string, string | null>;
+    /**
+     * Where the agent works.
+     *
+     * **A path on the host, not on this machine** - the same thing the
+     * `compose.workspace` command says, and the reason there is one flag rather
+     * than two. It defaults to nothing at all: the host is somewhere else, its
+     * filesystem is not this one, and a client that sent its own cwd would be
+     * naming a directory that does not exist there.
+     */
+    path?: string;
+    /**
+     * A directory on *this* machine to serve back to the host.
+     *
+     * The screen rather than the CLI, because a published directory is only
+     * reachable while a connection is open: `ahpc session list` answers and
+     * exits, so a host has nothing left to ask. Absent means nothing is served.
+     */
+    publish?: string;
+    /** Whether the host may write into it. Read-only otherwise. */
+    publishWritable?: boolean;
+    help: boolean;
+}
+export declare const USAGE = "ahpc - a terminal client for the Agent Host Protocol\n\n  ahpc [options]\n\nThe host\n  --host <url>          A live agent host, ws://host:port\n  --token <tkn>         A bearer token for it\n  --config-file <f>     Read this instead of ~/.config/ahpc/config.json\n  (none of these)       The scripted host, which needs nothing installed\n\nWhere the agent works\n  --path <dir>          A path on the host, not on this machine. The host\n                        has to serve it, and says so if it does not.\n                        Left out, the host decides.\n\nWhat this client serves back\n  --publish <dir>       Serve this directory to the host under\n                        virtual://<clientId>/. Nothing is served without\n                        it, and every such request is refused.\n  --publish-writable    Let the host write into it. Read-only otherwise.\n                        Serving lasts as long as the screen does: with no\n                        terminal attached this prints one frame and exits,\n                        so a background shell publishes nothing.\n\nAppearance\n  --theme <name>        workbench, paper-light, ...\n  --shell <name>        The shell layout\n  --screen <name>       Which screen to open on\n  --bood                Let the creature loose on the whole screen. It\n                        keeps off the composer and off anything asking\n                        a question, and alt+g turns it off again.\n  --session <uri>       Open this session\n\nStills, for a README or a test\n  --static, -s          One frame to stdout instead of running\n  --width, -w <n>       Columns\n  --height <n>          Rows\n  --unicode <level>     ascii, bmp, full\n  --colors <n>          0, 4, 8 or 24\n  --svg <file>          Write the still as SVG here\n  --tick <ms>           Milliseconds per scripted word\n  --settled             Run the script out before the frame\n  --pump <n>            Or exactly this many scripted words\n  --say <text>          Say this on the open session first\n  --approve             Answer the confirmation the script stops at\n  --answer              ...and then the question\n\n  --help, -h            This\n\nCommands\n  ahpc <command> ...    Drive a host without the screen. 'ahpc help' lists\n                        them: sessions, prompts, approvals, terminals.\n";
+export declare function parse(argv: string[]): Options;
+/**
+ * The screen.
+ *
+ * Exported rather than run, so `main.tsx` can decide between this and the CLI
+ * without either being loaded to make the choice - this file pulls in a whole
+ * renderer, and `ahpc session list` should not pay for one.
+ */
+export declare function tui(argv: string[]): Promise<void>;
+export {};

package/dist/src/tui.js

@@ -0,0 +1,372 @@
+import { WRITER_KEY, createApp } from '@textui/core';
+import { writeFile } from 'node:fs/promises';
+import { bufferToSvg, createNodeTerminal, createWriter, renderStill, } from '@textui/terminal';
+import { registerChat } from './app.js';
+import { CONTROLLER } from './control.js';
+import { connect, sink } from './connect.js';
+import { loadConfig } from './config.js';
+import { reportHostError } from './state.js';
+export const USAGE = `ahpc - a terminal client for the Agent Host Protocol
+
+  ahpc [options]
+
+The host
+  --host <url>          A live agent host, ws://host:port
+  --token <tkn>         A bearer token for it
+  --config-file <f>     Read this instead of ~/.config/ahpc/config.json
+  (none of these)       The scripted host, which needs nothing installed
+
+Where the agent works
+  --path <dir>          A path on the host, not on this machine. The host
+                        has to serve it, and says so if it does not.
+                        Left out, the host decides.
+
+What this client serves back
+  --publish <dir>       Serve this directory to the host under
+                        virtual://<clientId>/. Nothing is served without
+                        it, and every such request is refused.
+  --publish-writable    Let the host write into it. Read-only otherwise.
+                        Serving lasts as long as the screen does: with no
+                        terminal attached this prints one frame and exits,
+                        so a background shell publishes nothing.
+
+Appearance
+  --theme <name>        workbench, paper-light, ...
+  --shell <name>        The shell layout
+  --screen <name>       Which screen to open on
+  --bood                Let the creature loose on the whole screen. It
+                        keeps off the composer and off anything asking
+                        a question, and alt+g turns it off again.
+  --session <uri>       Open this session
+
+Stills, for a README or a test
+  --static, -s          One frame to stdout instead of running
+  --width, -w <n>       Columns
+  --height <n>          Rows
+  --unicode <level>     ascii, bmp, full
+  --colors <n>          0, 4, 8 or 24
+  --svg <file>          Write the still as SVG here
+  --tick <ms>           Milliseconds per scripted word
+  --settled             Run the script out before the frame
+  --pump <n>            Or exactly this many scripted words
+  --say <text>          Say this on the open session first
+  --approve             Answer the confirmation the script stops at
+  --answer              ...and then the question
+
+  --help, -h            This
+
+Commands
+  ahpc <command> ...    Drive a host without the screen. 'ahpc help' lists
+                        them: sessions, prompts, approvals, terminals.
+`;
+export function parse(argv) {
+    const options = {
+        static_: false,
+        width: process.stdout.columns ?? 100,
+        height: process.stdout.rows ?? 30,
+        tick: 40,
+        settled: false,
+        theme: 'paper',
+        shell: 'workbench',
+        boodInline: false,
+        boodFloat: false,
+        approve: false,
+        answer: false,
+        help: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        switch (argv[i]) {
+            case '--static':
+            case '-s':
+                options.static_ = true;
+                break;
+            case '--width':
+            case '-w':
+                options.width = Number(argv[++i]);
+                break;
+            case '--height':
+                options.height = Number(argv[++i]);
+                break;
+            case '--unicode':
+                options.unicode = argv[++i];
+                break;
+            case '--colors':
+                options.colors = Number(argv[++i]);
+                break;
+            case '--tick':
+                options.tick = Number(argv[++i]);
+                break;
+            case '--settled':
+                options.settled = true;
+                break;
+            case '--pump':
+                options.pump = Number(argv[++i]);
+                break;
+            case '--svg':
+                options.svg = String(argv[++i]);
+                break;
+            case '--say':
+                options.say = String(argv[++i]);
+                break;
+            case '--approve':
+                options.approve = true;
+                break;
+            case '--answer':
+                options.answer = true;
+                break;
+            case '--screen':
+                options.screen = String(argv[++i]);
+                break;
+            case '--theme':
+                options.theme = String(argv[++i]);
+                break;
+            case '--shell':
+                options.shell = String(argv[++i]);
+                break;
+            case '--bood':
+                options.boodFloat = true;
+                break;
+            case '--session':
+                options.session = String(argv[++i]);
+                break;
+            case '--host':
+                options.host = String(argv[++i]);
+                break;
+            case '--token':
+                options.token = String(argv[++i]);
+                break;
+            case '--config-file':
+                options.configFile = String(argv[++i]);
+                break;
+            case '--path':
+                options.path = String(argv[++i]);
+                break;
+            case '--publish':
+                options.publish = String(argv[++i]);
+                break;
+            case '--publish-writable':
+                options.publishWritable = true;
+                break;
+            case '--help':
+            case '-h':
+                options.help = true;
+                break;
+            // A flag nobody reads is a flag nobody can rely on: an unknown one is
+            // said so rather than silently doing what the defaults would have done.
+            default:
+                if (argv[i]?.startsWith('-')) {
+                    process.stderr.write(`Unknown option ${argv[i]}. Try --help.\n`);
+                    process.exit(2);
+                }
+                break;
+        }
+    }
+    return options;
+}
+function overrides(options) {
+    return {
+        ...(options.unicode ? { unicode: options.unicode, wideChars: options.unicode !== 'ascii' } : {}),
+        ...(options.colors !== undefined ? { colorDepth: options.colors } : {}),
+    };
+}
+/**
+ * Where a new session works, as this client can honestly answer it.
+ *
+ * `--path` when it was given, and it is a path on the **host**. Otherwise
+ * nothing: the host's filesystem is not this one, so a path from here is one
+ * it has never heard of, and the honest answer is to let the host decide.
+ */
+const workspaceFor = (options) => options.path ?? '';
+/** One frame, to stdout. The same application, against a terminal that is a size. */
+async function still(options) {
+    const host = await connect(options);
+    const { text } = await renderStill({
+        width: options.width,
+        height: options.height,
+        capabilities: overrides(options),
+        theme: options.theme,
+        shell: options.shell,
+        onBoot: (booted) => {
+            registerChat(booted, {
+                host, workspace: workspaceFor(options),
+                boodInline: options.boodInline, boodFloat: options.boodFloat,
+                ...(options.keys ? { keys: options.keys } : {}),
+            });
+        },
+        // A still of a turn mid-flight is what `--pump` is for: run a fixed number
+        // of scripted words rather than all of them, and the caret is wherever the
+        // agent had got to. `--settled` runs until the script has nothing left it
+        // can do without being answered, which is how the confirmation is reached.
+        before: (app) => {
+            const controller = app.services.require(CONTROLLER);
+            if (options.session)
+                controller.open(options.session);
+            /*
+             * Pushed when asked for, and not otherwise.
+             *
+             * `screen` used to default to `sessions` and the push was skipped for
+             * that value, so `--screen sessions` was the one screen a still could
+             * not take - the session list, which is the first thing a reader of the
+             * README wants to see. Absent means the screen the application boots
+             * to, which is what a still with no flags has always shown.
+             */
+            if (options.screen)
+                app.screens.push(options.screen);
+            if (options.say)
+                controller.send(options.say);
+            const steps = options.pump ?? (options.settled ? 100_000 : 0);
+            for (let i = 0; i < steps; i++)
+                if (host.pump?.() !== true)
+                    break;
+            if (options.approve) {
+                controller.approve();
+                for (let i = 0; i < 100_000; i++)
+                    if (host.pump?.() !== true)
+                        break;
+            }
+            if (options.answer) {
+                controller.answer({ q1: { kind: 'selected', value: 'transcript-scope' } }, true);
+                for (let i = 0; i < 100_000; i++)
+                    if (host.pump?.() !== true)
+                        break;
+            }
+        },
+        after: async (app) => {
+            if (options.svg === undefined)
+                return;
+            // The theme's own two colours, not the exporter's defaults: a cell left
+            // at the terminal default means "whatever the emulator is set to", and
+            // the honest answer for a picture of *this* application is the
+            // background it was drawn against.
+            await writeFile(options.svg, `${bufferToSvg(app.buffer(), {
+                background: app.theme.colors.canvas,
+                foreground: app.theme.colors.text,
+                title: `chat - ${options.screen ?? 'new'}`,
+            })}\n`, 'utf8');
+        },
+    });
+    // The frame is drawn, so let the host go. A live one is a socket and a
+    // local one is a subprocess, and either keeps the event loop alive after
+    // `main` has returned - a still that renders correctly and then hangs for
+    // ever, which is what every `--host` still did.
+    await host.close?.();
+    if (options.svg !== undefined) {
+        process.stderr.write(`${options.svg}\n`);
+        return;
+    }
+    process.stdout.write(`${text}\n`);
+}
+/**
+ * The screen.
+ *
+ * Exported rather than run, so `main.tsx` can decide between this and the CLI
+ * without either being loaded to make the choice - this file pulls in a whole
+ * renderer, and `ahpc session list` should not pay for one.
+ */
+export async function tui(argv) {
+    const options = parse(argv);
+    /*
+     * The file, under whatever was typed.
+     *
+     * Same order as the CLI uses, because the two front ends answering
+     * differently about which host to talk to is the one difference nobody
+     * would think to look for.
+     */
+    const file = loadConfig('ahpc', options.configFile);
+    options.host = options.host ?? process.env.AHPC_HOST ?? file.host;
+    options.token = options.token ?? process.env.AHPC_TOKEN ?? file.token;
+    if (file.theme && !argv.includes('--theme'))
+        options.theme = file.theme;
+    if (file.shell && !argv.includes('--shell'))
+        options.shell = file.shell;
+    if (file.boodInline !== undefined)
+        options.boodInline = file.boodInline;
+    if (file.boodFloat !== undefined && !argv.includes('--bood'))
+        options.boodFloat = file.boodFloat;
+    if (file.keys)
+        options.keys = file.keys;
+    if (options.help) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (options.static_ || !process.stdout.isTTY) {
+        await still(options);
+        return;
+    }
+    const terminal = createNodeTerminal();
+    const host = await connect(options);
+    const app = createApp({
+        terminal,
+        // A starting point, not a fixture. `alt+t` and the palette change both
+        // while it runs, and the screens are the same graph under either.
+        theme: options.theme,
+        shell: options.shell,
+        session: { managed: true, altScreen: true, mouse: true, title: 'assistant' },
+        onBoot: (booted) => {
+            registerChat(booted, {
+                host, workspace: workspaceFor(options),
+                boodInline: options.boodInline, boodFloat: options.boodFloat,
+                ...(options.keys ? { keys: options.keys } : {}),
+            });
+            booted.commands.register({
+                id: 'app.quit',
+                title: 'Quit',
+                slots: ['palette'],
+                run: () => void app.stop().then(() => process.exit(0)),
+            });
+            // `q` is *not* bound. The focused composer would take it first anyway,
+            // but a quit key that exists only where it happens to be unread is a
+            // quit key nobody can rely on - so it is ctrl+c and the palette.
+            //
+            // `ctrl+c` is registered for the turn *and* for this, in that order:
+            // while something is running it stops it, and when nothing is, the
+            // first binding does not apply and this one does. Cancel what is
+            // happening, or leave if nothing is - which is what the key means
+            // everywhere else.
+            booted.keybindings.register({ keys: 'ctrl+c', commandId: 'app.quit' });
+            booted.keybindings.register({ keys: 'ctrl+q', commandId: 'app.quit' });
+            /*
+             * A rebinding that names nothing is said out loud.
+             *
+             * Checked here rather than where the bindings are registered, because
+             * this is the first point at which every command exists - `app.quit`
+             * above is registered by the shell rather than by the controller, and a
+             * check that ran earlier would report it as unknown. A chord bound to a
+             * name no command answers to does nothing at all, which from the
+             * keyboard is indistinguishable from a config file that never loaded.
+             */
+            for (const [chord, id] of Object.entries(options.keys ?? {})) {
+                if (id !== null && !booted.commands.get(id)) {
+                    sink.report(`Config: ${chord} is bound to "${id}", which is not a command. Run 'ahpc config --json' for the ones there are.`);
+                }
+            }
+        },
+    });
+    app.services.provide(WRITER_KEY, createWriter(terminal.capabilities()));
+    sink.report = (message) => reportHostError(app.store, message);
+    await app.start();
+    /**
+     * The last resort, and the reason it exists at all.
+     *
+     * A promise nobody caught ends the Node process, and this process is holding
+     * a terminal in its alternate screen with the cursor hidden and raw mode on.
+     * Exiting from there leaves a shell nobody can type into. So whatever it is,
+     * the application is stopped first - which puts the terminal back - and then
+     * the error is printed where it can be read.
+     */
+    const bail = (label) => (error) => {
+        void app.stop().finally(() => {
+            process.stderr.write(`${label}: ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+            process.exit(1);
+        });
+    };
+    process.on('unhandledRejection', bail('Unhandled rejection'));
+    process.on('uncaughtException', bail('Uncaught exception'));
+    // The clock, for the scripted host only. A real connection has a socket
+    // pushing actions, and everything above it cannot tell the difference -
+    // which is why this is the only line that has to know.
+    if (host.pump) {
+        const timer = setInterval(() => { host.pump?.(); }, Math.max(1, options.tick));
+        timer.unref?.();
+    }
+}

package/dist/src/view/automations.d.ts

@@ -0,0 +1,31 @@
+import type { BoxProps, RenderOutput } from '@textui/core';
+import type { Automation } from '../ahp/types.js';
+/**
+ * What the host will do without being asked.
+ *
+ * The catalogue is sessions somebody started; this is the other half - the
+ * ones that start themselves. Both halves are the host's, and a client that
+ * drew only the first makes a session appearing at nine in the morning look
+ * like something nobody can account for.
+ *
+ * Two facts per row and they are not the same fact. The **schedule** is what
+ * was written down and is true whatever the host does with it; **next run** is
+ * what the host will actually do. A host with no clock, an automation switched
+ * off and an expression the host could not read all say the same thing here -
+ * a schedule with nothing coming - and that is worth showing rather than
+ * hiding behind the expression.
+ */
+/** "in 4h 12m". A next run is only ever ahead, so there is no past tense. */
+export declare function until(iso: string, from?: number): string;
+/** The schedule as written, with the zone only when it is not the obvious one. */
+export declare function scheduleOf(automation: Automation): string;
+export interface AutomationListProps extends BoxProps {
+    automations: Automation[];
+    /** The cursor moved. What a key acting on "this one" needs. */
+    onSelect?(uri: string): void;
+    /** Enter on a row. */
+    onOpen?(uri: string): void;
+    focusId?: string;
+    autoFocus?: boolean;
+}
+export declare const AutomationList: (props: AutomationListProps) => RenderOutput;

package/dist/src/view/automations.js

@@ -0,0 +1,76 @@
+import { jsx as _jsx, jsxs as _jsxs } from "@textui/core/jsx-runtime";
+import { defineComponent, useTheme } from '@textui/core';
+import { Column, EmptyState, List, Marquee, Row } from '@textui/widgets';
+/**
+ * What the host will do without being asked.
+ *
+ * The catalogue is sessions somebody started; this is the other half - the
+ * ones that start themselves. Both halves are the host's, and a client that
+ * drew only the first makes a session appearing at nine in the morning look
+ * like something nobody can account for.
+ *
+ * Two facts per row and they are not the same fact. The **schedule** is what
+ * was written down and is true whatever the host does with it; **next run** is
+ * what the host will actually do. A host with no clock, an automation switched
+ * off and an expression the host could not read all say the same thing here -
+ * a schedule with nothing coming - and that is worth showing rather than
+ * hiding behind the expression.
+ */
+/** "in 4h 12m". A next run is only ever ahead, so there is no past tense. */
+export function until(iso, from = Date.now()) {
+    const ms = new Date(iso).getTime() - from;
+    if (!Number.isFinite(ms))
+        return '';
+    if (ms <= 0)
+        return 'due';
+    const minutes = Math.floor(ms / 60_000);
+    const days = Math.floor(minutes / 1440);
+    const hours = Math.floor((minutes % 1440) / 60);
+    const rest = minutes % 60;
+    if (days > 0)
+        return `in ${days}d ${hours}h`;
+    if (hours > 0)
+        return `in ${hours}h ${rest}m`;
+    return `in ${rest}m`;
+}
+/** The schedule as written, with the zone only when it is not the obvious one. */
+export function scheduleOf(automation) {
+    if (!automation.schedule)
+        return 'manual only';
+    const { expression, timeZone } = automation.schedule;
+    return timeZone && timeZone !== 'UTC' ? `${expression}  ${timeZone}` : expression;
+}
+const RUN_TONE = {
+    completed: 'success',
+    failed: 'danger',
+    cancelled: 'warning',
+    running: 'accent',
+    pending: 'muted',
+};
+export const AutomationList = defineComponent('AutomationList', (props) => {
+    const { automations, onSelect, onOpen, focusId, autoFocus, ...rest } = props;
+    const theme = useTheme();
+    if (automations.length === 0) {
+        return (_jsx(EmptyState, { title: "No automations", message: "This host holds none. One that fires on a schedule starts a session with nobody at the keyboard.", ...rest }));
+    }
+    const byUri = new Map(automations.map((one) => [one.resource, one]));
+    const items = automations.map((one) => ({
+        id: one.resource,
+        // Filled for one that will fire, hollow for one that will not. The
+        // switch and the clock are different questions and this answers the
+        // first; the meta answers the second.
+        icon: one.enabled ? theme.glyphs.bulletFilled : theme.glyphs.bulletHollow,
+        label: one.title,
+        meta: scheduleOf(one),
+        tone: (one.enabled ? 'default' : 'muted'),
+    }));
+    return (_jsx(List, { items: items, flex: 1, ...(focusId ? { focusId } : {}), ...(autoFocus ? { autoFocus } : {}), ...(onSelect ? { onSelect: (id) => onSelect(id) } : {}), ...(onOpen ? { onActivate: (id) => onOpen(id) } : {}), renderItem: (item, state) => {
+            const one = byUri.get(item.id);
+            const runs = one?.runs.slice(0, 3) ?? [];
+            return (_jsxs(Column, { children: [_jsxs(Row, { gap: 1, children: [_jsx("text", { content: item.icon ?? '', ...(state.selected ? {} : { fg: one?.enabled ? 'accent' : 'muted' }), shrink: 0 }), _jsx(Marquee, { content: item.label, active: state.selected && state.focused, flex: 1, ...(one?.enabled ? {} : { fg: 'muted' }) }), one?.enabled === false ? _jsx("text", { content: "off", fg: "muted", shrink: 0 }) : null] }), _jsxs(Row, { gap: 1, children: [_jsx("text", { content: " ", shrink: 0 }), _jsx("text", { content: item.meta ?? '', fg: "subtle", shrink: 0 }), _jsx("text", { content: one?.nextRunAt ? `${theme.glyphs.separator} ${until(one.nextRunAt)}` : `${theme.glyphs.separator} nothing scheduled`, ...(one?.nextRunAt ? { fg: 'info' } : { fg: 'subtle' }), shrink: 0 }), runs.map((run) => (_jsx("text", { content: run.status === 'completed'
+                                    ? theme.glyphs.check
+                                    : run.status === 'failed'
+                                        ? theme.glyphs.cross
+                                        : theme.glyphs.bulletFilled, fg: RUN_TONE[run.status] ?? 'muted', shrink: 0 }, run.resource)))] })] }));
+        }, ...rest }));
+});

package/dist/src/view/bood/art.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The drawing tag.
+ *
+ * A tagged template reading `strings.raw`, because this is drawing. A figure
+ * whose every backslash has to be doubled to survive the parser is one
+ * somebody will eventually get wrong, and the mistake does not look like a
+ * mistake - it looks like a slightly worse cat.
+ *
+ *     art`
+ *  /\_/\
+ * ( ^.^ )
+ * `
+ *
+ * The leading and trailing blank lines are the ones the backticks sit on, and
+ * they are dropped. Nothing else is: art starts at column zero in the file,
+ * because leading spaces are part of the animal and a dedent would eat them.
+ */
+export declare function art(strings: TemplateStringsArray): string[];
+/** One cell's frames, however the file wrote them. One frame, or several. */
+export declare function framesOf(cell: string[] | string[][]): string[][];
+/**
+ * Square a form off: one width, one height, across every mood and every frame.
+ *
+ * Padded once, here, rather than by the compositor - because the compositor
+ * pads to the widest row *it* was given, and a centred figure with one short
+ * row leans. And because a frame one row taller than the next does not read as
+ * animation, it reads as the line underneath it jumping.
+ */
+export declare function square(cells: string[][][]): {
+    width: number;
+    height: number;
+};
+/**
+ * A long open and a short shut.
+ *
+ * Two frames alternating at the ticker's rate is not a blink, it is a strobe.
+ * The hold lives in the data rather than in the component, because how long a
+ * cat's eyes stay open is a fact about the cat.
+ */
+export declare const blink: (open: string[], shut: string[]) => string[][];
+/** Two frames, each held for two - a slow alternation inside a fast ticker. */
+export declare const alternate: (a: string[], b: string[]) => string[][];
+/**
+ * Fill a pose's slots: a run of `%` takes the face, a run of `#` the tell.
+ *
+ * The run is written exactly as wide as the token that fills it, so a filled
+ * row is the same length as the row it came from and nothing downstream has to
+ * re-measure. `registerCreature` checks that at registration; the padding here
+ * is what happens when somebody registers their own creature at runtime and
+ * got it wrong, and a short token is better than a row that shifts.
+ */
+export declare function fill(rows: string[], face: string, tell: string): string[];
+/**
+ * What one frame is, and where the animal is inside it.
+ *
+ * The anchor is the middle of the face slot - the creature's identity point -
+ * and a figure is placed by it rather than by its left edge. That is what lets
+ * a cat turn side-on: the walking drawing is twice as wide as the front one
+ * with the head at the far end, and anchored on the face the body swings round
+ * a head that stays where it was. Anchored on the corner it would jump ten
+ * cells every time the cat turned round.
+ *
+ * A pose that pins its own face has no slot to read, so it falls back to the
+ * middle, which is where a symmetrical drawing's identity is anyway.
+ */
+export declare function metric(rows: string[]): {
+    width: number;
+    height: number;
+    anchor: number;
+};
+/**
+ * The anchor a whole pose is placed by: frame zero's, shared by every frame.
+ *
+ * Per-frame anchors would hold the face still and slide everything else, which
+ * is the wrong half of the motion to believe. The cat at the keyboard bobs its
+ * head one cell between frames; taking the anchor from frame zero keeps the
+ * desk still and moves the head, which is what the drawing means.
+ */
+export declare function anchorOf(frames: string[][]): number;
+/**
+ * Write a figure into a field of rows, bottom-aligned and anchored.
+ *
+ * Bottom-aligned because the feet own the y: the landing squash is a row
+ * shorter than the stand, and padding underneath would sink the creature
+ * through the floor at exactly the moment it hits it.
+ *
+ * Anything off the field is dropped rather than wrapped, so a creature halfway
+ * out of a narrow box is half a creature instead of a smear down the far side.
+ */
+export declare function blit(field: string[], rows: string[], x: number, y: number, anchor: number): string[];