@getorrery/cells 0.0.0-stage → 0.2.1

package/dist/el/input.d.ts

@@ -0,0 +1,136 @@
+/**
+ * List 2 · Input & navigation: @-mentions, attachments, the palette, search,
+ * help, message actions, rewind — port of `el/input.rs`.
+ */
+import { type Item } from "../cells";
+import { type Runs } from "./content";
+/** A match. */
+export interface MentionItem {
+    path: string;
+    meta: string;
+}
+/** The `@` picker above the input. */
+export interface MentionView {
+    query: string;
+    typed?: string;
+    items?: MentionItem[];
+    selected?: number;
+    /** `ready`, `indexing`, `error`, `outside`, `chip`; `ready` when absent. */
+    state?: string;
+    note?: string | null;
+    error?: string | null;
+    chip?: string | null;
+}
+/** Fuzzy file and symbol search over the workspace; a pick becomes a chip. */
+export declare function mention(p: MentionView, w: number, m: boolean): Item[];
+/** An attachment. */
+export interface AttachChip {
+    text: string;
+    /** `ready`, `uploading`, `rejected`, `unsupported`; `ready` when absent. */
+    state?: string;
+}
+/** The input with its attachments on the first row. */
+export interface AttachView {
+    chips: AttachChip[];
+    selected?: number | null;
+    typed?: string;
+    /** `[kind, text]`: `error` or `warn`. */
+    message?: [string, string] | null;
+    hint?: string;
+}
+/** Chips on their own row inside the input. */
+export declare function attach(p: AttachView, w: number, m: boolean): Item[];
+/** A palette entry. */
+export interface PaletteItem {
+    label: string;
+    detail?: string;
+    disabled?: boolean;
+}
+/** A group of entries. */
+export interface PaletteGroup {
+    label: string;
+    items?: PaletteItem[];
+    loading?: string | null;
+    error?: string | null;
+}
+/** ctrl+k. */
+export interface PaletteView {
+    query?: string;
+    groups?: PaletteGroup[];
+    /** The entry under the cursor, by label. */
+    selected?: string | null;
+}
+/** Every command, setting and recent session in one fuzzy list. */
+export declare function palette(p: PaletteView, w: number, m: boolean): Item[];
+/** ctrl+r in the input, or `/` in the thread. */
+export interface SearchView {
+    /** `history` or `transcript`. */
+    scope: string;
+    query: string;
+    count?: string;
+    /** `ready`, `searching`, `empty`, `error`; `ready` when absent. */
+    state?: string;
+    entry?: string;
+    rows?: Runs[];
+    note?: string | null;
+    error?: string | null;
+}
+/** The search row, or the history label in the input. */
+export declare function search(p: SearchView, w: number, m: boolean): Item[];
+/** A key. */
+export interface KeyV {
+    key: string;
+    action: string;
+    disabled?: boolean;
+}
+/** `?` on an empty input. */
+export interface HelpView {
+    keys: KeyV[];
+    filter?: string | null;
+    note?: string | null;
+    visible?: number | null;
+}
+/** Every key in two columns at ≥64 columns, one below; typing filters. */
+export declare function help(p: HelpView, w: number, m: boolean): Item[];
+/** An action on a message. */
+export interface ActionV {
+    key: string;
+    label: string;
+    disabled?: boolean;
+}
+/** The row under a selected message. */
+export interface ActionsView {
+    message: string;
+    actions: ActionV[];
+    /** The action with focus, by key. */
+    focused?: string | null;
+    busy?: string | null;
+    error?: string | null;
+    note?: string | null;
+}
+/** Copy, retry, edit & resend, fork — one row, single-letter keys. */
+export declare function actions(p: ActionsView, w: number, m: boolean): Item[];
+/** A file a turn changed. */
+export interface FileStat {
+    path: string;
+    stat: string;
+}
+/** A turn to rewind to. */
+export interface RewindTurn {
+    n: string;
+    prompt: string;
+    at: string;
+    files?: FileStat[];
+    /** `true` when absent. */
+    checkpoint?: boolean;
+}
+/** esc esc on an empty input. */
+export interface RewindView {
+    turns?: RewindTurn[];
+    selected?: number;
+    busy?: string | null;
+    error?: string | null;
+    hint?: string | null;
+}
+/** Turns with the files each changed; enter restores code and chat. */
+export declare function rewind(p: RewindView, w: number, m: boolean): Item[];

package/dist/el/markdown.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Streaming markdown as rows — port of `el/markdown.rs`.
+ *
+ * A line is final once its newline arrives: nothing drawn above the last line
+ * ever changes. A half-open fence is code at once. The markup is formatted,
+ * not shown: headings lose their `#`, emphasis is styled, lists nest.
+ */
+import { type Line } from "../cells";
+/** Markdown source as rows at `w` columns. */
+export declare function render(src: string, w: number, m: boolean, streaming: boolean, link: number | null): Line[];

package/dist/el/mod.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Every element of the design, as a view model and a function drawing it —
+ * port of `el/mod.rs`.
+ *
+ * A view model is plain JSON (snake_case, the same fields and defaults as the
+ * crate's serde structs), so the same props drive the Rust crate, this port
+ * and the fixtures under `harness/clients/conformance/design/props/`.
+ */
+import { type Item } from "../cells";
+import * as agent from "./agent";
+import * as chrome from "./chrome";
+import * as content from "./content";
+import * as extensions from "./extensions";
+import * as context from "./context";
+import * as feedback from "./feedback";
+import * as input from "./input";
+import * as sessions from "./sessions";
+/** Every element id, in the design's order. */
+export declare const ELEMENTS: readonly string[];
+/** An element's props did not match its view model, or the id is unknown. */
+export declare class BadProps extends Error {
+    readonly id: string;
+    readonly reason: string;
+    constructor(id: string, reason: string);
+}
+/**
+ * Draw element `id` from its props at `w` columns, in mono when `m`.
+ *
+ * @throws {BadProps} when the id is unknown or the props are not an object.
+ */
+export declare function render(id: string, props: unknown, w: number, m: boolean): Item[];
+export { agent, chrome, content, context, extensions, feedback, input, sessions };
+export { type Block, blocks } from "./block";
+export * as markdown from "./markdown";
+export { arrow, errLines, flag, hl, ov, panelHead, warnLines } from "./helpers";

package/dist/el/sessions.d.ts

@@ -0,0 +1,131 @@
+/**
+ * List 2 · Sessions & setup: resume, the session tree, OAuth, MCP, skills,
+ * workspace trust, the first run, the theme picker — port of `el/sessions.rs`.
+ */
+import { type Item, type Line } from "../cells";
+import { type Runs } from "./content";
+/** A past session. */
+export interface SessionRow {
+    title: string;
+    branch: string;
+    at: string;
+    cost: string;
+    turns: string;
+    locked?: string | null;
+}
+/** `orrery --resume`, `/resume`. */
+export interface ResumeView {
+    items?: SessionRow[];
+    selected?: number;
+    preview?: Runs[];
+    last?: string;
+    loading?: string | null;
+    error?: string | null;
+}
+/** Title, branch, cost; a preview pane on the right at ≥64 columns. */
+export declare function resume(p: ResumeView, w: number, m: boolean): Item[];
+/** A turn in the tree. */
+export interface TreeTurn {
+    lane?: string;
+    n: string;
+    prompt: string;
+    branch?: string | null;
+    current?: boolean;
+}
+/** Forks, with box-drawing lanes. */
+export interface SessionTreeView {
+    turns?: TreeTurn[];
+    selected?: number;
+    busy?: string | null;
+    error?: string | null;
+}
+/** `●` a turn, `◉` where you are. */
+export declare function sessionTree(p: SessionTreeView, w: number, m: boolean): Item[];
+/** Device-code sign-in. */
+export interface OAuthView {
+    title: string;
+    step?: string | null;
+    url: string;
+    code: string;
+    /** `waiting`, `approved`, `error`, `expired`; `waiting` when absent. */
+    state?: string;
+    note?: string;
+}
+/** The URL, the code large in a heavy box, a spinner with the expiry. */
+export declare function oauth(p: OAuthView, w: number, m: boolean): Item[];
+/** A server. */
+export interface Server {
+    name: string;
+    transport: string;
+    /** `ok`, `auth`, `failed`, `off`, `connecting`. */
+    state: string;
+    detail: string;
+}
+/** `/mcp`. */
+export interface McpView {
+    servers?: Server[];
+    selected?: number;
+    tools?: string[] | null;
+    note?: string | null;
+}
+/** One row per server; its error and fix on the row. */
+export declare function mcp(p: McpView, w: number, m: boolean): Item[];
+/** A skill. */
+export interface SkillRow {
+    name: string;
+    version: string;
+    /** `on`, `off`, `update`, `installing`. */
+    state: string;
+    latest?: string | null;
+    progress?: number | null;
+}
+/** `/skills`. */
+export interface SkillsView {
+    /** `installed` or `available`; `installed` when absent. */
+    tab?: string;
+    items?: SkillRow[];
+    selected?: number;
+    error?: string | null;
+}
+/** Tabs, then name, version and state per row; install progress inline. */
+export declare function skills(p: SkillsView, w: number, m: boolean): Item[];
+/** The first run in a folder. */
+export interface TrustView {
+    path: string;
+    hooks?: string[];
+    mcp?: string[];
+    /** Other files found that trust would load (configuration, extensions). */
+    files?: string[];
+    /** The answers, in order; the design's three when empty. */
+    options?: string[];
+    selected?: number;
+    error?: string | null;
+}
+/** What trust enables, the hooks and servers by name, three choices. */
+export declare function trust(p: TrustView, w: number, m: boolean): Item[];
+/** Under the banner on an empty thread. */
+export interface WelcomeView {
+    suggestions?: string[];
+    tips?: string[];
+    /** `ready`, `scanning`, `empty`; `ready` when absent. */
+    state?: string;
+    selected?: number | null;
+    warn?: string | null;
+}
+/** Three suggestions, tips, and what is missing. */
+export declare function welcome(p: WelcomeView, w: number, m: boolean): Item[];
+/** A theme. */
+export interface ThemeRow {
+    id: string;
+    label: string;
+}
+/** `/theme`. */
+export interface ThemeView {
+    themes: ThemeRow[];
+    selected?: number;
+    error?: string | null;
+}
+/** The fixed sample every theme is previewed with. */
+export declare function themeSample(w: number, m: boolean): Line[];
+/** The list; under it, a fixed sample redrawn in the highlighted theme. */
+export declare function theme(p: ThemeView, w: number, m: boolean): Item[];

package/dist/from.d.ts

@@ -0,0 +1,131 @@
+/**
+ * From what the host sent to what the design draws — port of
+ * `harness/clients/cells/src/from.rs`.
+ *
+ * The protocol carries surfaces, turns and UI nodes; the design draws
+ * elements. This is the one place a TypeScript client turns the first into
+ * the second, so two clients cannot map a diff or a tool call differently.
+ * Only types are imported from `@getorrery/client` and `@getorrery/protocol`: this
+ * package stays pure drawing.
+ */
+import type { TurnView } from "@getorrery/client";
+import type { Field, Status, Surface, TurnMeta, UiDoc } from "@getorrery/protocol";
+import { type Line } from "./cells";
+import * as content from "./el/content";
+/**
+ * What the client knows about a surface that the host does not: the cursor
+ * in a question, the focused field, whether a tool call is expanded.
+ */
+export interface Local {
+    /** The choice under the cursor in a question. */
+    choice?: number | null;
+    /** The field with focus in a form, and what is typed in it. */
+    field?: [number, string] | null;
+    /** A tool call's whole result, not its preview. */
+    expanded?: boolean;
+    /** The row under the cursor in a list or table. */
+    row?: number | null;
+    /** How long a tool call took, or has run: `0.4s`. */
+    dur?: string | null;
+}
+/** Model prose, markdown, under a `●` gutter; the caret after it while it streams. */
+export declare function proseMd(src: string, streaming: boolean, w: number, m: boolean): Line[];
+/**
+ * A tool call's argument summary: the first string argument (a path, a
+ * command), else the arguments compacted.
+ */
+export declare function argsSummary(raw0: string): string;
+/** How many result rows a folded tool call previews. Decision 0024 folds a call to its head row alone. */
+export declare const PREVIEW_ROWS = 3;
+/** The class of the zero-width mark a foldable surface's first row carries: `fold:<surface id>`. */
+export declare const FOLD_MARK = "fold:";
+/** The surface id a row's fold mark names, when it has one. */
+export declare function foldMark(l: Line): string | null;
+/** A tool's short name for its line: `builtin.bash` is `bash`. */
+export declare function toolName(name: string): string;
+/**
+ * A call's main argument, for its one line (decision 0024): `bash` → the
+ * command, `read` / `write` / `edit` → the path, `glob` / `grep` → the
+ * pattern, anything else → its first string argument. First line only.
+ */
+export declare function mainArg(name: string, raw: string): string;
+/** A tool call: its head row, then its result under `⎿`. */
+export declare function toolCall(name: string, status: Status | null | undefined, children: Surface[], local: Local, w: number, m: boolean): Line[];
+/** The custom surface kind the host uses for input that joined a run. */
+export declare const STEER_KIND = "orrery.steer";
+/**
+ * The custom surface kind an attached agent's result is (decision 0021):
+ * `{ name, state, ms, text }`, drawn folded — `▸ code-reviewer · done · 12s` —
+ * over the first line of what it said; unfolded, all of it.
+ */
+export declare const AGENT_RESULT_KIND = "orrery.agent-result";
+/** A surface as the element that draws its kind. */
+export { propsEntries, propsText, textForm } from "./open";
+export declare function surfaceLines(s: Surface, local: Local, w: number, m: boolean): Line[];
+/**
+ * How a client draws its own `custom` kinds (decision 0093): the rows for a
+ * kind's props at a width, null for a kind it does not know. The port of the
+ * crate's `catalog::CustomDraw`.
+ */
+export type CustomDraw = (kind: string, props: Record<string, unknown>, w: number) => Line[] | null | undefined;
+/**
+ * Install the client's own components: every `custom` surface of a kind it
+ * draws is drawn by it, at the width it is given (a stack's child at the
+ * child's), with its own classes. One per process; null removes it.
+ */
+export declare function setCustomDraw(f: CustomDraw | null): void;
+/** The installed hook's rows for `kind`, each cut to `w`; null when it does not draw `kind`. */
+export declare function customLines(kind: string, props: unknown, w: number): Line[] | null;
+/** A form surface's view model, with the client's focus and typing. */
+export declare function formView(fields: Field[], submit: string, local: Local): content.FormView;
+/** A turn's rows: the prompt, the reasoning fold, what came back, the outcome. */
+export interface TurnOpts {
+    /** The line that started it. */
+    echo?: string | null;
+    /** Its reasoning is open. */
+    foldOpen?: boolean;
+    /** The clock now, for a fold still thinking. */
+    nowMs?: number;
+    /** The host's facts about it. */
+    meta?: TurnMeta | null;
+    /** A surface not drawn here (the dock has it). */
+    hidden?: string | null;
+    /** Per-surface client state, by surface id. */
+    local?: ((id: string) => Local) | null;
+    /** The prompt is selected: banded, the actions under it. */
+    selected?: boolean;
+    /**
+     * Close a turn that ended well with its outcome line. A prompt's turn
+     * does; a command's says how it ended itself.
+     */
+    outcome?: boolean;
+}
+/** Micro-USD as a person reads it (decision 0019): two decimals, or four under a cent, so a real cost never reads `$0.00`. */
+export declare function usd(micro: number): string;
+/** `1.2k`, `41.2k`, `340`. */
+export declare function kilo(n: number): string;
+/** A tool call's duration: `0.4s`, `12s`, `1m 5s`. */
+export declare function dur(ms: number): string;
+/** `4s`, `1m 52s`, `1h 12m`. */
+export declare function took(ms: number): string;
+/** The outcome line's detail: time, tools, tokens, cost. */
+export declare function outcomeDetail(meta: TurnMeta | null | undefined, tools: number): string;
+/** Whether a stack is a tool call: its first child is the arguments, as code. */
+export declare function isToolCall(children: Surface[] | undefined): boolean;
+/** A turn as rows at `w` columns. */
+export declare function turn(tv: TurnView, o: TurnOpts, w: number, m: boolean): Line[];
+/**
+ * How many options an element offers to choose from, when it is one a person
+ * chooses in (decision 0007): the trust answers, the models, the sessions to
+ * resume, the servers, the skills, the turns to rewind to, the themes, the
+ * forks, the suggestions.
+ */
+export declare function options(el: string, props: unknown): number | null;
+/** An element's props with this client's cursor put in them. */
+export declare function withCursor(el: string, props: unknown, cursor: string | null | undefined): unknown;
+/** An overlay's child as rows: as {@link node}, and an element that windows its rows (`/extensions`) is told the `rows` the overlay has. */
+export declare function overlayNode(doc: UiDoc, id: string, cursor: string | null | undefined, rows: number, w: number, m: boolean): Line[];
+/** A UI node (Tier 2, or an element) as rows. `cursor` is where this client moved a list's cursor. */
+export declare function node(doc: UiDoc, id: string, cursor: string | null | undefined, w: number, m: boolean): Line[];
+/** Whether a node's children are drawn by the node itself. */
+export declare function childrenDrawnInline(type: string): boolean;

package/dist/golden.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Rows as the design's goldens write them, and a comparison that says where
+ * two renderings part — a port of `harness/clients/cells/src/golden.rs`.
+ *
+ * A row is `{ t: text, c: [[cells, classes], …] }`. The 2-cell pixel mark is
+ * `` with class `px:<state>`, the spinner `` with
+ * `spin <cls>`. A block beside rows is `{ blk: {…}, lines: [row, …] }`.
+ */
+import { type Item, type Line } from "./cells";
+/** A golden row, as JSON. */
+export type Row = {
+    t: string;
+    c: [number, string][];
+} | {
+    blk: unknown;
+    lines: Row[];
+};
+/** One line as a golden row, cut to `w` the way the design's page does. */
+export declare function row(l: Line, w: number): Row;
+/** An element's rows as golden rows. */
+export declare function rows(items: Item[], w: number): Row[];
+/** Normalise a golden row: classes sorted and runs merged, so order is not a difference. */
+export declare function normalise(v: any): any;
+/** What a set of classes paints in mono, where hue is gone. */
+export declare function monoPaint(c: string): string;
+/** Deep JSON equality, as `serde_json::Value` compares: key order ignored, a missing key is not `null`. */
+export declare function jsonEq(a: unknown, b: unknown): boolean;
+/** {@link diff}, comparing what mono paints rather than class names. */
+export declare function diffMono(want: unknown[], got: unknown[]): string | null;
+/** Where two renderings first differ, as a sentence and both renderings in plain text; `null` when the same. */
+export declare function diff(want0: unknown[], got0: unknown[]): string | null;

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@getorrery/cells` — the terminal design as cells, a TypeScript port of the
+ * `orrery-cells` crate (`harness/clients/cells`). Same view models, same
+ * rows, checked against the same goldens.
+ */
+export * from "./cells";
+export * as golden from "./golden";
+export { compose, thumb, threadRows, type Part, type ScreenView } from "./screen";
+export { BadProps, ELEMENTS, render } from "./el/mod";
+export * as el from "./el/mod";
+export * as from from "./from";
+export * as open from "./open";
+export * as pixelFrames from "./pixel_frames";
+export * as session from "./session";