@elaraai/east-codex-plugin 0.0.0-stage → 1.0.89
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.
- package/.build/daemon/east-py-lsp.js +568 -0
- package/.build/daemon/lsp.js +3737 -0
- package/.build/daemon/server.js +3535 -0
- package/.build/hooks/codex-tools.js +584 -0
- package/.build/hooks/diagnose-bash.js +399 -0
- package/.build/hooks/diagnose.js +347 -0
- package/.build/hooks/pre-read.js +100 -0
- package/.build/hooks/pre-write.js +247 -0
- package/.build/hooks/session-start.js +263 -0
- package/.build/hooks/subagent-start.js +212 -0
- package/.build/mcp/server.js +23577 -0
- package/.build/status/report.js +2163 -0
- package/.codex-plugin/plugin.json +36 -0
- package/.lsp.json +21 -0
- package/.mcp.json +11 -0
- package/LICENSE.md +682 -0
- package/README.md +192 -2
- package/hooks/hooks.json +51 -0
- package/index.json +44926 -0
- package/package.json +36 -4
- package/skills/e3/SKILL.md +841 -0
- package/skills/e3-create/SKILL.md +265 -0
- package/skills/e3-ui/SKILL.md +2260 -0
- package/skills/e3-ui-cli/SKILL.md +332 -0
- package/skills/east/SKILL.md +690 -0
- package/skills/east-contribute/SKILL.md +348 -0
- package/skills/east-design/SKILL.md +233 -0
- package/skills/east-node-io/SKILL.md +143 -0
- package/skills/east-node-std/SKILL.md +289 -0
- package/skills/east-ontology/SKILL.md +181 -0
- package/skills/east-project/SKILL.md +189 -0
- package/skills/east-py/SKILL.md +2023 -0
- package/skills/east-py-datascience/SKILL.md +280 -0
- package/skills/east-py-io/SKILL.md +186 -0
- package/skills/east-py-std/SKILL.md +301 -0
- package/skills/east-ui/SKILL.md +1529 -0
|
@@ -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.
|