@elaraai/east-codex-plugin 0.0.0-stage → 1.0.90

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,332 @@
1
+ ---
2
+ name: e3-ui-cli
3
+ description: "Browse an e3 repository in the terminal, and render east-ui / e3-ui components to PNG. Use when: (1) Opening an e3 repository interactively — `e3-ui [repo] [workspace]` (a local path, `https://host/repos/(repo)`, or a bare origin) shows a workspace dashboard (task / dataset status, the last or live dataflow run with the budget it runs under, units waiting for room and requeued, each task's peak memory — and, while a deploy runs, each file source and record at the step it has reached), task views (a lazily paged value tree of the output with /find and /goto, stdout and stderr with tail-follow, the run history, a ui() task's manifest), editable inputs with a commit bar, records (their rows, through any of their indexes, and their commits, read-only), and `/run` / `/stop`, all driven by a command box with completion, vim-style keys and the mouse, (2) Signing in to a remote e3 server for the terminal UI (`e3-ui auth… See the detailed scope below."
4
+ ---
5
+
6
+ ## Detailed skill scope
7
+
8
+ Browse an e3 repository in the terminal, and render east-ui / e3-ui components to PNG. Use when: (1) Opening an e3 repository interactively — `e3-ui [repo] [workspace]` (a local path, `https://host/repos/<repo>`, or a bare origin) shows a workspace dashboard (task / dataset status, the last or live dataflow run with the budget it runs under, units waiting for room and requeued, each task's peak memory — and, while a deploy runs, each file source and record at the step it has reached), task views (a lazily paged value tree of the output with /find and /goto, stdout and stderr with tail-follow, the run history, a ui() task's manifest), editable inputs with a commit bar, records (their rows, through any of their indexes, and their commits, read-only), and `/run` / `/stop`, all driven by a command box with completion, vim-style keys and the mouse, (2) Signing in to a remote e3 server for the terminal UI (`e3-ui auth login|logout|status|token|whoami` — the same device flow and store as `e3 auth`), (3) Screenshotting an east-ui component or e3-ui decision surface with `e3-ui shot` — from a .ts/.tsx source file, serialized .beast2/.json IR, or a live e3 task's computed output, (4) Rendering ONE example from a `*.examples.ts(x)` file (`--from-source <file> -e <exampleName>`) or EVERY renderable UI export in a project (`e3-ui shots`), (5) Setting up or troubleshooting the headless browser on a server or CI (`e3-ui install-browser`, `e3-ui doctor`), (6) Rendering PNGs from Node with renderToPng / renderTaskToPng / capture.
9
+
10
+ # e3-ui CLI (@elaraai/e3-ui-cli)
11
+
12
+ Two things in one command. With no subcommand, `e3-ui` is a full-screen
13
+ **terminal UI** over an e3 repository — local (an embedded
14
+ `@elaraai/e3-api-server`, exactly as `e3-ui shot --from-task` and the VS Code
15
+ extension already do) or remote (`https://host/repos/<repo>` with the token
16
+ `e3-ui auth login` saved). With `shot` / `shots` it is the **renderer** that
17
+ turns east-ui / e3-ui components — East functions returning a
18
+ `UIComponentType`, or e3 `ui()` tasks — into PNG images (and optionally
19
+ self-contained HTML) with headless Chromium. The East→React renderer is
20
+ pre-bundled; the only external runtime dependency is the browser binary,
21
+ which the CLI manages, and the terminal UI never needs it.
22
+
23
+ ## Before writing code — search the example index
24
+
25
+ Every East API has a tested example in the plugin's index — the index IS the
26
+ API reference, printed from each example's IR in TypeScript or python. Before
27
+ writing or changing East code:
28
+
29
+ 1. Call `search_east_examples` for each capability you
30
+ are about to use — `language: "python"` for east-py, `"typescript"`
31
+ otherwise. Summaries come back first: id, signature, the inputs and the
32
+ expected result, a few hundred bytes each.
33
+ 2. Fetch the one or two that match with `get_east_example`
34
+ and pattern your code on them.
35
+ 3. Do not read `node_modules/@elaraai/**` or `*.examples.ts` files wholesale,
36
+ and do not reason from `.d.ts` signatures: the index holds the same
37
+ programs, exact and far cheaper, and the signatures omit the runtime rules
38
+ that make East code correct.
39
+
40
+ Nothing is injected for you; the search is the step.
41
+
42
+ ## Quick Start
43
+
44
+ ```bash
45
+ npm install -g @elaraai/e3-ui-cli # small — downloads no browser
46
+
47
+ # The terminal UI (the default command) over a local repository:
48
+ e3-ui ./my-repo # → the workspace dashboard, or the workspaces list
49
+ e3-ui ./my-repo main --task forecast # straight to a task; --input <name> opens an input
50
+ e3-ui https://e3.example.com/repos/demo # remote — needs a saved token:
51
+ e3-ui auth login https://e3.example.com # the same device flow + store (~/.e3/credentials.json) as `e3 auth`
52
+ e3-ui https://e3.example.com # a bare origin → the repositories list
53
+
54
+ # Screenshots need the browser once per machine (add --with-deps on fresh Linux servers):
55
+ e3-ui install-browser
56
+ e3-ui shot --from-source ./dashboard.tsx -o dashboard.png
57
+ e3-ui shot --from-source test/collections/schematic.examples.tsx -e schematicNets -o nets.png
58
+ e3-ui shot --from-task main.dashboard --repo ./.repos -o dashboard.png
59
+ e3-ui shots src --out .shots --json # EVERYTHING renderable under src/
60
+ ```
61
+
62
+ ```ts
63
+ import { renderToPng } from "@elaraai/e3-ui-cli";
64
+
65
+ await renderToPng({ input: { path: "./dashboard.tsx" }, output: "dashboard.png" });
66
+ ```
67
+
68
+ ## The terminal UI
69
+
70
+ `e3-ui [repo] [workspace]` — `repo` defaults to `$E3_REPO`, then `.`, and is
71
+ resolved with e3's own grammar: a local path, `https://host/repos/<repo>`,
72
+ or a bare `https://host` (the repositories list). The first view is the
73
+ workspace given, else the one remembered for that repository, else the only
74
+ one, else the workspaces list; `--task <name>` / `--input <name>` open a task
75
+ or an input straight away. Without a TTY on both ends (`e3-ui | cat`, CI) it
76
+ refuses on stderr with exit 1 and points at the scriptable commands — the UI
77
+ is never started and Ink is never loaded.
78
+
79
+ | Screen | What it shows · what `⏎` does |
80
+ |---|---|
81
+ | **Repositories** (bare origin) | NAME · WORKSPACES · PACKAGES · OBJECTS · LAST DEPLOY; `⏎` binds one |
82
+ | **Workspaces** | NAME · STATE · PACKAGE · TASKS (`● 4 ◐ 1 ✗ 1`) · LAST RUN; `⏎` opens the dashboard |
83
+ | **Dashboard** | TASKS / DATASETS counts + the accounted bar, the last execution (its failures) or the live event feed, the tasks table (with each task's PEAK memory), the inputs table and, when the workspace holds records, the RECORDS table (rows · size · indexes · newest commit); `⏎` opens the task / input / record / a failed task's logs. While a run is live the panel shows the scheduler: the cores and memory the server's budget holds, a split task's progress (`forecast · 3 of 8 pieces`), each unit waiting for room (what it needs, what is free) and each unit the guard stopped and requeued. While a deploy holds the workspace (a first deploy included) the title reads `◔ DEPLOYING · demand@1.5.0 · pid 4242 · started 9s ago`, and the column is the deploy. A DEPLOY header gives its phase: `TAKING IN · 2 of 6 files · 17 of 32 MB · 1.7 MB/s · ~8.8s left`, then `MIGRATING`, `BUILDING INDEXES` and `FINISHING`. The INPUTS table follows, with each file source's step: `waiting`, then `hashing` and `taking in` with a bar (a collection's moves a piece at a time), then `unchanged`, `carried` or `taken in by east-c` (the runners that took it in). Then the RECORDS table: `migrating · add_owner · 1 of 2`, `building by_owner · 1 of 1`, then what the deploy did with the record. When the deploy ends, the dashboard reads the workspace again |
84
+ | **Task** `1 Output · 2 Stdout · 3 Stderr · 4 Runs (· 5 Reads)` | the output as a value tree (a collection paged in pages of 128 KiB of stored bytes or 16 rows, whichever is more, at most 500 rows; anything else whole up to 200 KB; with the *no output* / *too large* / *not indexed* states; a row of more than 12 fields, or a row that is a collection, starts collapsed), each log stream with tail-follow (the Stderr tab shows its line count), every run with its peak memory, a `ui()` task's manifest |
85
+ | **Input** | the same tree, editable: `e` edit a leaf, `a` add, `x` remove, `t` tag / set; the commit bar sums the pending ops, `⏎ APPLY` writes them, `esc DISCARD`; a value changed on the server while editing raises a banner (`⏎` reloads and re-applies) |
86
+ | **Record** `1 State · 2 History` | the rows as a read-only paged value tree — or, after `/index <name>`, one of its indexes: an entry per index key, opening to the row (joined when the index projects nothing) — and the commits newest first, 100 a page, e3's own (`$deploy`, `$compact`, …) muted. Written only through its mutations (`e3 mutate`), never here |
87
+ | **Help** `?` | a tab per page — only the commands and keys that work where you are |
88
+
89
+ ### The command box
90
+
91
+ `/` opens it; `Tab` completes; `⏎` runs; `esc` cancels. Plain text without
92
+ `/` fuzzy-jumps to any workspace, task, input, record or dataset. Every command shows
93
+ its consequence before `⏎` (`run 6 tasks in main, ignoring the cache`); a
94
+ confirmation is the same command re-run with `--force`.
95
+
96
+ | Command | Effect |
97
+ |---|---|
98
+ | `/task <name>` · `/input <name>` · `/record <name>` · `/dataset <path>` | open a task / input / record / dataset (`.inputs.x`, `.tasks.x.output`, `.records.x`) |
99
+ | `/workspace <name>` · `/workspaces` · `/repos` · `/repo <path\|url>` | switch workspace · the lists · open another repository |
100
+ | `/run [--force \| --force-task <task>…] [--filter <task>]` · `/stop` | start / cancel the dataflow (`r` / `x` prefill them): `--force` re-runs every task (under `--filter`, its task), `--force-task`, repeated, the tasks it names; `--filter` runs one task, by its exact name, and the tasks it depends on. It runs under the server's budget — for a local repository, the embedded server's `-j` / `--memory` |
101
+ | `/logs <task> [stderr]` · `/runs <task>` | a task's stdout (or stderr) / run history |
102
+ | `/find <key>` · `/goto <row\|N%>` · `/save [file] [--force]` | in a value tree: exact `"key"`, prefix, or struct-key fields `a\|b`; jump by row or percent; write the `.beast2` bytes (`.log` for logs) |
103
+ | `/index <name>` · `/index primary` | in a record: page through one of its indexes, where `/find` searches the index's key and `/goto` counts its entries; or its rows again |
104
+ | `/tag <name>` · `/add [key]` · `/remove [--force]` · `/apply` · `/discard [--then "<cmd>"]` · `/reload` | editing an input |
105
+ | `/login <url>` · `/refresh` · `/help` · `/about` · `/quit [--force]` | the device-flow login · poll every feed now · … |
106
+
107
+ ### Keys
108
+
109
+ | Where | Keys |
110
+ |---|---|
111
+ | everywhere | `?` help · `q` `^c` quit · `esc` `⌫` back · `/` a command · `1 2 3 …` tabs · `tab` `⇧tab` next / prev tab · `R` refresh |
112
+ | lists | `↑↓ j k` move · `pgup pgdn ^u ^d` page · `gg G` top / bottom · `⏎ →` open · `r` `/run` · `x` `/stop` · `w` workspaces |
113
+ | value tree | `→ l` expand or next · `← h` collapse or parent · `⏎ space` toggle · `⇧←` collapse deep · `n N` next / prev match · `s` save |
114
+ | stdout / stderr | `↑↓` scroll (pauses follow) · `G` end · `F` follow · `← →` `tab` the other tabs · `s` save · `c` copy (OSC 52) · `n N` matches |
115
+ | inputs | `e` edit · `a` add · `x` remove · `t` tag / set · `⏎` apply all · `esc` discard · in an editor: `⏎` commit · `esc` cancel · `space` toggles a boolean |
116
+ | mouse | wheel scrolls the pane under the cursor · click selects (on `▸` toggles) · drag the scrollbar thumb · click tabs, crumbs, pills, completion rows · `--no-mouse` |
117
+
118
+ ### Environment and files
119
+
120
+ | Variable / file | Effect |
121
+ |---|---|
122
+ | `E3_REPO` | the default repository argument |
123
+ | `~/.e3/credentials.json` (`E3_CREDENTIALS_PATH`) | the token store, shared with `e3 auth` |
124
+ | `$XDG_STATE_HOME/e3-ui/state.json` (`E3_UI_STATE`) | the last repository, each repository's last workspace and view, every value tree's expand-set and top row (0600, atomic) |
125
+ | `E3_UI_DEBUG=1` | appends a `debug.log` beside the state file (never to the screen) |
126
+ | `E3_UI_ASCII=1` / `--ascii` · `TERM=linux` · a non-UTF-8 locale | the ASCII glyph set |
127
+ | `NO_COLOR` / `FORCE_COLOR` | colour off / on (else the terminal's depth) |
128
+ | `--no-mouse` · `TERM=dumb` · a non-TTY | mouse reporting off (keyboard only) |
129
+
130
+ Terminals: works over SSH and in tmux (`set -g mouse on` for the wheel and
131
+ drag there); in Kitty, iTerm2, WezTerm, Ghostty, GNOME Terminal, Windows
132
+ Terminal and the VS Code terminal the mouse just works; elsewhere the wheel
133
+ still scrolls because terminals turn it into arrow keys on the alternate
134
+ screen. Below 60×16 the app refuses; 80–99 columns tightens the tables,
135
+ 60–79 drops their secondary columns.
136
+
137
+ ## Decision Tree
138
+
139
+ ```
140
+ Look at / operate a repository
141
+ ├─ Interactively (status, runs, outputs, logs, inputs, records, a deploy as it runs) → e3-ui [repo] [workspace] (the terminal UI)
142
+ │ ├─ a remote server → e3-ui auth login <url>, then e3-ui https://host/repos/<repo>
143
+ │ ├─ a specific task or input → --task <name> / --input <name>
144
+ │ ├─ a record, through an index → /record <name>, then /index <name> (read-only; mutate with e3 mutate)
145
+ │ └─ no TTY (a script, CI) → e3 workspace status · e3 dataset get (the UI refuses)
146
+ └─ As an image of a UI component → e3-ui shot / shots (below)
147
+
148
+ Render a component to an image
149
+ ├─ EVERYTHING in a project (audit the renderable surface)
150
+ │ → e3-ui shots [paths…] --out .shots [--html] [--json]
151
+ │ every export is classified at the IR level (output type
152
+ │ vs UIComponentType, zero inputs, platform calls) — skips
153
+ │ are listed with reasons, never silently dropped
154
+ ├─ From TypeScript source (.ts/.tsx) → e3-ui shot --from-source <file> [-e <export>]
155
+ │ ├─ exports an East fn → UIComponentType → rendered directly
156
+ │ ├─ exports example() defs (*.examples.*) → -e <exampleName> per shot (the def's fn is unwrapped;
157
+ │ │ without -e the file must have a SOLE renderable export)
158
+ │ ├─ exports an e3 ui() task (zero inputs) → unwrapped and rendered (create-e3 --ui scaffold: npm run shot)
159
+ │ └─ ui() task WITH compute-time inputs → not standalone-renderable → use --from-task
160
+ ├─ From serialized IR (.beast2/.json, stdin) → e3-ui shot --from-ir <file|->
161
+ ├─ From a deployed e3 workspace task → e3-ui shot --from-task <ws.task> --repo <path>
162
+ └─ From Node code → renderToPng / renderTaskToPng
163
+
164
+ What KIND of component is it?
165
+ ├─ Self-sized (cards, stacks, forms, charts…) → shot renders true to layout
166
+ ├─ Width-flexible (Schematic, Plan, Table…) → pass --frame-width full (the `shots` sweep DEFAULT) to
167
+ │ mount the frame at viewport width; the default single-shot
168
+ │ frame is shrink-to-fit and collapses these
169
+ ├─ Reads e3 data (Data.bind / Decision.bind) → a standalone shot has NO workspace: use --from-task
170
+ │ against a deployed repo, or (monorepo) the seeded
171
+ │ harness: make e3-ui-examples-html-<key>
172
+ └─ Browser-local State.bind only → renders standalone (initial state)
173
+
174
+ Browser setup / problems
175
+ ├─ Fresh machine or CI → e3-ui install-browser [--with-deps]
176
+ ├─ "Could not launch" / anything unclear → e3-ui doctor
177
+ ├─ Fleet-shared cache → PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers (install + shot)
178
+ ├─ Force a specific binary → E3_UI_CHROMIUM_PATH=/path/to/chrome
179
+ └─ Ubuntu snap chromium → never used (auto-skipped); install-browser or Chrome .deb
180
+ ```
181
+
182
+ ## CLI Reference
183
+
184
+ ### `e3-ui [repo] [workspace]`
185
+
186
+ The terminal UI (the default command).
187
+
188
+ | Argument / flag | Description |
189
+ |---|---|
190
+ | `[repo]` | A local path · `https://host/repos/<repo>` · `https://host` (the repositories list). Default: `$E3_REPO`, then `.`. |
191
+ | `[workspace]` | The workspace to open (else the one remembered for the repository, the only one, or the list). |
192
+ | `-t, --task <name>` | Open a task on start. |
193
+ | `-i, --input <name>` | Open an input on start (exclusive with `--task`). |
194
+ | `-j, --jobs <n>` | A local repository's embedded server: its cores, the runner processes it keeps in flight (default: `$E3_JOBS`, else the CPUs available). Refused for a remote repository, which runs under its server's budget. |
195
+ | `--memory <size>` | Its memory, as `8G` or `512M` (default: `$E3_MEMORY`, else the memory available, less a reserve). |
196
+ | `--no-mouse` | Disable mouse reporting. |
197
+ | `--ascii` | Box-drawing off (also `E3_UI_ASCII=1`). |
198
+
199
+ ### `e3-ui auth login|logout|status|token|whoami [url]`
200
+
201
+ The same commands, device flow and credential store (`~/.e3/credentials.json`)
202
+ as `e3 auth`, so a token saved by either is used by both.
203
+
204
+ ### `e3-ui shot`
205
+
206
+ Exactly one `--from-*` source per run.
207
+
208
+ | Flag | Description |
209
+ |---|---|
210
+ | `--from-source <file>` | Render a `.ts`/`.tsx` source. **Runs the file and its imports as Node code** — only point it at code you trust. |
211
+ | `--from-ir <file>` | Render serialized component IR (`.beast2`/`.json`); `-` reads stdin. |
212
+ | `--from-task <ws.task>` | Render a live e3 task's computed output (requires `--repo`). |
213
+ | `--repo <path>` | Local e3 repository path for `--from-task`. |
214
+ | `-e, --export <name>` | Which export to render (default: the `default` export, then the SOLE renderable export). Required in practice for `*.examples.*` files — they export many; an `example()` def is unwrapped to its `fn`. |
215
+ | `-o, --output <path>` | Output PNG path (default: derived from the source / task name). |
216
+ | `--html` | Also write a self-contained HTML (fonts inlined, no scripts) next to the PNG. |
217
+ | `--viewport <WxH>` | Chromium viewport (default 1280x900). |
218
+ | `--dpr <n>` | Device scale factor (default 2). |
219
+ | `--full-page` | Capture the whole page instead of the component frame. |
220
+ | `--element <selector>` | Capture a specific CSS selector. |
221
+ | `--wait <ms>` | Extra settle time after fonts/skeletons clear (default 300). |
222
+ | `--timeout <ms>` | Max wait for the render (default 30000); raise for slow live tasks. |
223
+ | `--frame-width <w>` | Mount the component frame at a definite width — `full` (viewport) or a CSS width (`900px`). Width-flexible components (Schematic/Plan/Table) collapse in the default shrink-to-fit frame. |
224
+
225
+ ### `e3-ui shots [paths…]`
226
+
227
+ Sweep files/directories (default `src`; directories recurse, `*.spec.*` and `*.d.ts` excluded) for EVERY renderable UI export — bare East fns, `example()` defs, zero-input `ui()` tasks — and render each to `<out>/<relative-path>/<export>.png` through ONE shared browser. Renderability is decided from the IR (east's own `isSubtypeValue` against the project's `UIComponentType`; `walkIR` for platform calls), so every skip carries its typed reason: wrong output type, takes inputs, parameterized ui() task, workspace-bound (`data_*`/`func_*`/`record_*` reads → use `--from-task`), or failed to load. Render failures exit non-zero.
228
+
229
+ | Flag | Description |
230
+ |---|---|
231
+ | `--out <dir>` | Output directory (default `.shots` — git-ignore it). |
232
+ | `--html` | Also write a standalone HTML beside each PNG. |
233
+ | `--json` | Also write `<out>/manifest.json` (rendered / skipped / failed, with reasons). |
234
+ | `--frame-width <w>` | `full` (default — faithful width), a CSS width, or `none` for the shrink-to-fit crop. |
235
+ | `--viewport`, `--dpr`, `--wait`, `--timeout` | As for `shot`. |
236
+
237
+ ### `e3-ui install-browser [--with-deps]`
238
+
239
+ Downloads the version-matched `chromium-headless-shell` into the
240
+ playwright-managed cache (honors `PLAYWRIGHT_BROWSERS_PATH`). ~100 MB lighter
241
+ than full Chromium. `--with-deps` also installs OS libraries (Linux only —
242
+ skipped with a note on Windows/macOS). Re-run after upgrading the CLI if
243
+ `shot` reports a missing executable. The terminal UI never needs a browser.
244
+
245
+ ### `e3-ui doctor`
246
+
247
+ Prints the env-override state, runs the real launch cascade against
248
+ `about:blank`, and reports what worked — or the exact remediation.
249
+
250
+ ### Browser launch order (all platforms)
251
+
252
+ 1. `E3_UI_CHROMIUM_PATH` / `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` env override.
253
+ 2. The playwright-managed cache (what `install-browser` fills).
254
+ 3. A system Chrome / Chromium / Edge at standard per-OS locations — Ubuntu
255
+ snap shims are detected and skipped (snap confinement breaks automation).
256
+
257
+ Chromium runs sandbox-off (playwright's default) — appropriate for rendering
258
+ trusted local components; running as root on a server just works.
259
+
260
+ ## Programmatic API
261
+
262
+ | Signature | Description |
263
+ |---|---|
264
+ | `renderToPng(opts)` | Full pipeline for source/IR inputs: load → encode payload → capture PNG (+ optional HTML). |
265
+ | `renderTaskToPng(opts)` | Start a local e3 API server over `repo`, render the task's computed output. |
266
+ | `capture(opts)` | Low-level: serve the prebuilt app, launch the browser, inject a `ShotPayload`, screenshot. |
267
+ | `buildPayload(input)` | Turn a source/IR input into the base64 payload `capture` consumes. |
268
+ | `loadComponentFromSource(file, exportName?)` | esbuild-load a `.ts`/`.tsx` in memory; returns the East function (unwraps `example()` defs to their `fn`, and zero-input `ui()` tasks). ❗ throws for parameterized ui() tasks |
269
+ | `sweep(opts)` | The `shots` sweep: discover → classify (IR-level) → render through one `CaptureSession`; returns `{ rendered, skipped, failed }`. |
270
+ | `classifyExports(exports, ctx)` / `detectContextFor(file)` | IR-level renderability detection — output type vs the PROJECT's `UIComponentType`, zero-input check, `walkIR` platform classification. |
271
+ | `openCaptureSession(appDir)` | One served app + one browser for many `captureOne(...)` calls (what `sweep` uses). |
272
+ | `launchBrowser(env?)` | The acquisition cascade; returns `{ browser, source }`. ❗ throws with remediation when no browser |
273
+ | `installBrowser({ withDeps? })` | Programmatic `install-browser`. |
274
+ | `doctor(env?)` | Programmatic `doctor`; returns a process exit code. |
275
+ | `startRepoServer(opts)` | Spin up the local e3 API server used by `--from-task` and by the terminal UI over a local repository. |
276
+
277
+ The terminal UI itself has no programmatic entry point: it is a process that
278
+ owns the terminal. Scripts use `e3 workspace status`, `e3 dataset get` and
279
+ `@elaraai/e3-api-client` instead.
280
+
281
+ ## Key Patterns
282
+
283
+ ```bash
284
+ # Watch a workspace while its dataflow runs — the pill counts events, the panel streams them:
285
+ e3-ui ./repo main # then r ⏎ (or /run --force ⏎); x ⏎ cancels
286
+ # Watch a deploy as it runs, a first deploy included (from another shell, `e3 workspace deploy ./repo main …`):
287
+ e3-ui ./repo main # the dashboard is the deploy — its INPUTS and RECORDS at their steps — until it ends
288
+ # Look at a task's output, then its logs, then its runs:
289
+ e3-ui ./repo main --task forecast # 1 Output · 2 Stdout · 3 Stderr · 4 Runs; /find k015 · /goto 50% · s save
290
+ # A record: its rows, an index, its commits:
291
+ e3-ui ./repo main # then /record plans ⏎ · /index by_owner ⏎ · /find alice ⏎ · 2 (History)
292
+ # Fix an input value in place:
293
+ e3-ui ./repo main --input params # e → type → ⏎ → ⏎ APPLY (the commit bar) ; esc discards
294
+ # A remote repository:
295
+ e3-ui auth login https://e3.example.com && e3-ui https://e3.example.com/repos/demo
296
+ # Keyboard only, box-drawing off, no state file (a locked-down host):
297
+ E3_UI_STATE=/dev/null e3-ui --no-mouse --ascii ./repo
298
+
299
+ # create-e3 --ui scaffold: the generated shot script renders the surface
300
+ npm run shot # = e3-ui shot --from-source src/ui/index.tsx --export surface -o surface.png
301
+
302
+ # One example() from an examples file (self-sized component) — name the export
303
+ e3-ui shot --from-source test/display/combine.examples.tsx -e combineDensities -o combine.png
304
+
305
+ # Width-flexible component (Schematic/Plan/Table) — mount the frame at viewport width
306
+ e3-ui shot --from-source test/collections/schematic.examples.tsx -e schematicStress --frame-width full -o stress.png
307
+
308
+ # Sweep a whole project (the --ui scaffold wires this as `npm run shots`):
309
+ e3-ui shots src --out .shots # PNGs, faithful width, typed skip reasons
310
+ e3-ui shots src --out .shots --html # + standalone HTML pairs
311
+
312
+ # Data-bound e3-ui example (Data.bind / Decision.bind) — the sweep SKIPS these as
313
+ # workspace-bound; render from a deployed repo (or, in the east monorepo, the
314
+ # seeded harness: make e3-ui-examples-html-decision/queue):
315
+ e3-ui shot --from-task main.queue --repo ./.repos -o queue.png
316
+
317
+ # CI / server bootstrap (one-time, cache shared across runs)
318
+ export PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers
319
+ sudo -E e3-ui install-browser --with-deps
320
+ e3-ui doctor
321
+
322
+ # Pipe IR produced elsewhere
323
+ some-tool --emit-ir | e3-ui shot --from-ir - -o out.png
324
+ ```
325
+
326
+ ## Related skills
327
+
328
+ - **e3** — repositories, workspaces, dataflow, `e3 auth`; the scriptable counterpart of the terminal UI, and what produces the task outputs `--from-task` consumes.
329
+ - **east-ui** — authoring the components this CLI renders (JSX tags, `UIComponentType`); the value tree the terminal shows is its row model.
330
+ - **e3-ui** — `ui()` tasks, `Data.bind`, decision surfaces; `--from-task` renders their computed output, the terminal UI shows their manifest.
331
+ - **east-project** — scaffolding a project whose `--ui` option wires `npm run shot`.
332
+ - **e3-create** — the `npm create @elaraai/e3 -- --ui` flag (and every other scaffold option) that generates the `src/ui/index.tsx` surface this screenshots.