@getorrery/cells 0.0.0-stage → 0.2.1

package/dist/open.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The open UI (plan 41, decisions 0086, 0087, 0090): `chart`, `raster` and
+ * `image` drawn in cells, the text form every client shares, and placed
+ * surfaces as pane columns and band rows. Drawn from the boards
+ * (`design/harness/tui-sheet-next.js`: H1-Chrome-31/32, H1-Content-28…30).
+ *
+ * Colour never carries meaning alone (decision 0090 §5): bars and glyphs do,
+ * mono swaps colours for the patterns `░▒▓█`, and every value is printed,
+ * right-aligned in its own column.
+ *
+ * A raster's pixels are classes `fg#rrggbb` and `bg#rrggbb`: the painter
+ * reads them as truecolour, and mono never gets them.
+ */
+import type { Placed, Surface, SurfaceKind } from "@getorrery/protocol";
+import { type Line } from "./cells";
+type Chart = Extract<SurfaceKind, {
+    t: "chart";
+}>;
+type Raster = Extract<SurfaceKind, {
+    t: "raster";
+}>;
+type Image = Extract<SurfaceKind, {
+    t: "image";
+}>;
+/** A pane's share of the width (W0.2). */
+export declare const PANE_SHARE = 0.25;
+/** Under this many columns a pane folds into a band row (W0.2). */
+export declare const PANE_MIN = 18;
+/** A pane folds when it would leave the thread fewer columns than this (W0.2). */
+export declare const THREAD_MIN = 40;
+/** Band rows shown; the rest say `+N more` (W0.2). */
+export declare const BAND_MAX = 3;
+/** A raster's cap, in pixels (W0.2; the host refuses larger). */
+export declare const RASTER_MAX_W = 64;
+export declare const RASTER_MAX_H = 32;
+/** A number as a value column prints it: whole, or to two places. */
+export declare function num(v: number): string;
+/** A payload's props as `[key, value]` pairs, keys sorted, strings unquoted: as `orrery_proto::surface::props_text`. */
+export declare function propsEntries(payload: unknown): [string, string][];
+/** {@link propsEntries} as text, one `key value` line each. */
+export declare function propsText(payload: unknown): string;
+/**
+ * The text form of a surface: line for line `orrery_proto::surface::text_form`,
+ * what every client shows where nothing else draws.
+ * shortcut: a non-string prop is `JSON.stringify`'d, so a float like `1.0` reads `1` where serde writes `1.0`; fine until a fixture carries one.
+ */
+export declare function textForm(s: Surface): string;
+interface ChartOpts {
+    /** Dim: rewound, or its owner stopped. */
+    dim?: boolean;
+    /** No title row: a band row draws the body alone. */
+    bare?: boolean;
+}
+/** A chart, in `w` cells. */
+export declare function chart(k: Chart, w: number, m: boolean, o?: ChartOpts): Line[];
+/**
+ * A raster: half-blocks, two pixels a cell (`▀`, top in front, bottom behind).
+ * With row labels, two rows share a cell row: the top one labelled left, the
+ * bottom one right. Mono: one pixel a cell, its legend step (or brightness)
+ * as `·░▒▓█`. Larger than 64 × 32 (refused by the host) is cut, never scaled.
+ */
+export declare function raster(k: Raster, w: number, m: boolean, o?: {
+    dim?: boolean;
+}): Line[];
+/**
+ * An image, as its `alt`: what this client shows on every terminal.
+ * shortcut: no picture, even where Kitty, iTerm2 or Sixel would show one — `@getorrery/anim` encodes RGBA but decodes no PNG or JPEG; draw it once a decoder is in.
+ */
+export declare function image(k: Image, w: number, m: boolean, o?: {
+    dim?: boolean;
+}): Line[];
+/** A placed surface as a client holds it: its node, what the host knows of it, and the surface (absent while it loads). */
+export interface PlacedView {
+    node: string;
+    placed: Placed;
+    surface: Surface | null;
+}
+/** How a placed surface's body is drawn: `from.surfaceLines`, by the caller. */
+export type Draw = (s: Surface, w: number) => Line[];
+/** Who placed it, as drawn: an extension by its id. */
+export declare function ownerName(owner: string): string;
+/** Its title: the owner's, else the surface's own heading, else its id. */
+export declare function titleOf(v: PlacedView): string;
+/**
+ * The fallback order (decision 0086): a `custom` this client has no renderer
+ * for takes the fallback its sender stored with the placement when it carries
+ * none itself; with neither, `from` draws its text form. Every core kind is
+ * drawn natively.
+ */
+export declare function resolved(v: PlacedView): Surface | null;
+/** The pane's width at `w` columns. */
+export declare function paneWidth(w: number): number;
+/** Whether panes fold into band rows at `w` columns, with `sides` of them open. */
+export declare function panesFold(w: number, sides: number): boolean;
+/**
+ * A pane's rows, `iw` cells wide: each placed surface stacked in arrival
+ * order under its head (title and `✕`, then its owner), a stopped one dimmed
+ * with the fix.
+ */
+export declare function paneLines(vs: PlacedView[], iw: number, m: boolean, draw: Draw): Line[];
+/** One row of the band: whose it is, and a one-row body `iw` cells wide. */
+export interface BandRow {
+    owner: string;
+    body: (iw: number) => Line;
+}
+/** A placed surface as a band row: the first row of its body, or loading, or stopped with the fix. */
+export declare function bandRow(v: PlacedView, m: boolean, draw: Draw): BandRow;
+/** A pane folded into one band row (narrow): its first surface's owner, `▸`, its title, and how many more it holds. */
+export declare function foldedRow(vs: PlacedView[], m?: boolean): BandRow;
+/** The band: owner in a fixed column, one row each, at most {@link BAND_MAX}, then `+N more`. Empty draws nothing. */
+export declare function bandLines(rows: BandRow[], w: number): Line[];
+export {};

package/dist/pixel_frames.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The design's pixel mark, agent states and wordmark, as frames. **Generated**
+ * by `scripts/pixel-frames.mjs` from the ratatui client's `widgets/pixel_frames.rs`;
+ * do not edit by hand.
+ */
+/** One animation: its speed, its palette and its frames. */
+export interface Anim {
+    name: string;
+    fps: number;
+    palette: readonly number[];
+    frames: readonly (readonly string[])[];
+}
+/** A still image: the wordmark. */
+export interface Still {
+    palette: readonly number[];
+    rows: readonly string[];
+}
+export declare const SIZE = 13;
+export declare const SMALL = 7;
+export declare const IDLE: Anim;
+export declare const LOADING: Anim;
+export declare const THINKING: Anim;
+export declare const EXECUTING: Anim;
+export declare const WAITING: Anim;
+export declare const DONE: Anim;
+export declare const ERROR: Anim;
+export declare const SMALL_IDLE: Anim;
+export declare const SMALL_LOADING: Anim;
+export declare const SMALL_THINKING: Anim;
+export declare const SMALL_EXECUTING: Anim;
+export declare const SMALL_WAITING: Anim;
+export declare const SMALL_DONE: Anim;
+export declare const SMALL_ERROR: Anim;
+export declare const WORDMARK_SM: Still;
+export declare const WORDMARK_LG: Still;
+export declare const LIGHT_IDLE: Anim;
+export declare const LIGHT_LOADING: Anim;
+export declare const LIGHT_THINKING: Anim;
+export declare const LIGHT_EXECUTING: Anim;
+export declare const LIGHT_WAITING: Anim;
+export declare const LIGHT_DONE: Anim;
+export declare const LIGHT_ERROR: Anim;
+export declare const LIGHT_SMALL_IDLE: Anim;
+export declare const LIGHT_SMALL_LOADING: Anim;
+export declare const LIGHT_SMALL_THINKING: Anim;
+export declare const LIGHT_SMALL_EXECUTING: Anim;
+export declare const LIGHT_SMALL_WAITING: Anim;
+export declare const LIGHT_SMALL_DONE: Anim;
+export declare const LIGHT_SMALL_ERROR: Anim;
+export declare const LIGHT_WORDMARK_SM: Still;
+export declare const LIGHT_WORDMARK_LG: Still;
+export declare const STATES: readonly Anim[];
+export declare const SMALL_STATES: readonly Anim[];
+export declare const LIGHT_STATES: readonly Anim[];
+export declare const LIGHT_SMALL_STATES: readonly Anim[];

package/dist/screen.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The fullscreen layout: `banner (as the thread's first item) → thread → dock
+ * → consent → input → footer` — port of `harness/clients/cells/src/screen.rs`.
+ *
+ * Everything under the thread keeps its rows; the thread gets the rest. The
+ * last column is the scroll track, reserved whether or not it shows. A block
+ * that starts above the view (the banner's logo) is cut to blank rows rather
+ * than drawn half.
+ */
+import { type Item } from "./cells";
+import { type FooterView } from "./el/chrome";
+/** One element in a region: its id and its props. */
+export interface Part {
+    el: string;
+    props?: unknown;
+}
+/** A whole screen. */
+export interface ScreenView {
+    thread?: Part[];
+    dock?: Part[];
+    consent?: Part[];
+    input?: Part[];
+    footer?: FooterView | null;
+    /** Scrolled up: the first row in view and how many items arrived below. */
+    scroll?: [number, number] | null;
+}
+/** Where the scroll thumb sits: first row and length, for a view of `th` rows starting at `top` over `total` rows. */
+export declare function thumb(top: number, th: number, total: number): [number, number];
+/** The thread's rows at `cw` columns, blocks expanded into the rows they cover. */
+export declare function threadRows(ps: Part[], cw: number, m: boolean): Item[];
+/** Fill `w × h` with the screen's regions. */
+export declare function compose(s: ScreenView, w: number, h: number, m: boolean): Item[];

package/dist/session.d.ts

@@ -0,0 +1,85 @@
+/**
+ * A cloud session's live changes and its setup, as cells (platform plan 07,
+ * decision 0046) — port of `harness/clients/cells/src/session.rs`.
+ *
+ * Neither is a UI node the host declares: both come off the session's own
+ * events. `orrery.session.changes` is kept by the store (`changes`);
+ * `orrery.session.setup` is not, so a client folds each body into a
+ * {@link SetupView} as it arrives. Whether the work was pushed, and the PR it
+ * opened, is read off the git tool calls in the transcript ({@link gitOutcome}).
+ */
+import type { TurnView } from "@getorrery/client";
+import type { FileChange, SessionChanges } from "@getorrery/protocol";
+import { type Line, type ToolState } from "./cells";
+/** The `Custom` name setup progress rides under (decision 0046 §3). */
+export declare const SETUP_EVENT = "orrery.session.setup";
+/** How many install lines the setup block keeps under its head. */
+export declare const SETUP_TAIL = 3;
+/** How many files the changes block lists before `… n more`. */
+export declare const CHANGES_ROWS = 8;
+/** One setup step the runner ran. */
+export interface SetupStep {
+    cmd: string;
+    exitCode: number;
+}
+/** A container session's setup, folded from its `orrery.session.setup` events. */
+export interface SetupView {
+    /** `resolving`, `starting`, `started`, `install`, `setup`, `self-heal`, `ready`, `hibernated`, `resumed`, `failed`; empty before the first event. */
+    phase: string;
+    image: string | null;
+    /** Started from the cache layer. */
+    fromCache: boolean;
+    /** The last install lines, oldest first, at most {@link SETUP_TAIL}. */
+    lines: string[];
+    /** The steps the setup ran, once it reported. */
+    steps: SetupStep[];
+    /** The setup's verdict, once it reported. */
+    ok: boolean | null;
+    /** The self-heal brief, when setup failed and the agent repairs it. */
+    brief: string | null;
+    /** Why it failed, in words; for `diagnosis`, the node's line (what it noticed, the limit, the key). */
+    error: string | null;
+    /** For `diagnosis`: the cause (`oom`, `disk`, `stall`, …) and whether it is an error (platform decision 0009 §5). */
+    diagnosis: {
+        cause: string;
+        error: boolean;
+    } | null;
+    /** Drawn: from the first event until the first turn starts after it (a failure stays). */
+    visible: boolean;
+}
+export declare function emptySetup(): SetupView;
+/** Fold one event body in; a new view, or the same one when nothing changed. */
+export declare function applySetup(v: SetupView, body: unknown): SetupView;
+/** The first turn started: the block hides, unless setup failed. */
+export declare function setupTurnStarted(v: SetupView): SetupView;
+/** Still coming up: no turn can run yet. */
+export declare function setupBusy(v: SetupView): boolean;
+/** The head row's words and state. */
+export declare function setupHead(v: SetupView): [string, ToolState];
+/** The setup block: a tool row named `setup`, then what it ran under `⎿`. */
+export declare function setupLines(v: SetupView, w: number, m: boolean): Line[];
+/** What the git tools reported: pushed, and the PR it opened. */
+export interface GitOutcome {
+    pushed: boolean;
+    pr: number | null;
+    url: string | null;
+}
+/** The PR number and URL in `gh pr create`'s output. */
+export declare function prNumber(text: string): [number, string] | null;
+/** Read the git tool calls of a transcript: the last finished `git.push` and `git.pr`. `null` when neither ran. */
+export declare function gitOutcome(turns: readonly TurnView[]): GitOutcome | null;
+/** What the changes block draws. */
+export interface ChangesView {
+    /** The store's `changes` (absent before the first event). */
+    changes?: SessionChanges | null;
+    /** The machine the session runs on, for `streaming from …`. */
+    machine?: string | null;
+    /** What the git tools reported. */
+    git?: GitOutcome | null;
+}
+/** The files still differing from the index. */
+export declare function changedFiles(c: SessionChanges | null | undefined): FileChange[];
+/** The right side of the head: `pushed · PR #n`, `pushed`, or `streaming from <machine>`. */
+export declare function changesNote(v: ChangesView): [string, string] | null;
+/** The changes block: a head with the totals, then a row a file (at most {@link CHANGES_ROWS}). */
+export declare function changesLines(v: ChangesView, w: number, m: boolean): Line[];

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@getorrery/cells",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "description": "The terminal design as cells: every harness element drawn as rows of styled cells, checked against the design's own goldens. A port of the orrery-cells crate.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kouji-dev/orrery",
+    "directory": "harness/clients/cells-ts"
+  },
+  "dependencies": {
+    "@getorrery/client": "0.2.1",
+    "@getorrery/protocol": "0.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8",
+    "@types/node": "^22.10.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "node ../../../scripts/release/build-lib.mjs src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.