lavish-axi 0.1.44 → 0.1.46
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/README.md +60 -25
- package/dist/chrome-client.js +629 -58
- package/dist/chrome.css +304 -0
- package/dist/cli.mjs +1787 -302
- package/package.json +5 -2
- package/plugin.json +21 -0
- package/skills/lavish/SKILL.md +10 -9
package/README.md
CHANGED
|
@@ -95,6 +95,32 @@ This installs a `SessionStart` hook for **Claude Code**, **Codex**, **OpenCode**
|
|
|
95
95
|
Unlike the skill, the hook also shows your live open sessions, so a fresh agent session can resume an in-flight review.
|
|
96
96
|
**Restart your agent session after running this** so the new hook takes effect.
|
|
97
97
|
|
|
98
|
+
### Agent Plugin
|
|
99
|
+
|
|
100
|
+
Lavish also ships as an [Agent Plugin](https://agent-plugins.org) - the vendor-neutral packaging standard for skills and MCP servers - so clients that speak that format can load it directly.
|
|
101
|
+
|
|
102
|
+
**No marketplace is involved.** The installed npm package _is_ the plugin: `plugin.json` sits at the package root next to the `skills/` directory, so whatever `npm install` already put on disk is a complete, conformant plugin. Install the CLI, then register it:
|
|
103
|
+
|
|
104
|
+
```sh
|
|
105
|
+
npm install -g lavish-axi
|
|
106
|
+
lavish-axi setup plugin
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
That registers the installed package with every supported client it finds - **VS Code**, **Cursor**, and **GitHub Copilot CLI** - and reports which ones were absent. It is opt-in and idempotent, and it repairs the registered path after a reinstall or relocation. Reload each client afterward.
|
|
110
|
+
|
|
111
|
+
Each client is registered independently: one that cannot be registered is reported with what to do about it, and never blocks the others or fails the command.
|
|
112
|
+
|
|
113
|
+
To register by hand instead, point any client at the package directory (`npm root -g`/`lavish-axi`):
|
|
114
|
+
|
|
115
|
+
| Client | Register with |
|
|
116
|
+
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
|
|
117
|
+
| VS Code | `"chat.pluginLocations": { "<package-dir>": true }` in user settings |
|
|
118
|
+
| Cursor | link the package dir at `~/.cursor/plugins/local/lavish-axi` (`setup plugin` handles Windows link compatibility) |
|
|
119
|
+
| GitHub Copilot CLI | `copilot plugin install <package-dir>` (or `copilot plugin install kunchenguid/lavish-axi` straight from the repo) |
|
|
120
|
+
|
|
121
|
+
Codex and ChatGPT install plugins only from marketplace sources, so Codex users should use the session hook above instead.
|
|
122
|
+
Lavish declares no MCP server - the CLI itself is the agent interface - so a plugin install brings the same `lavish` skill, and the skill and plugin are alternatives rather than a stack.
|
|
123
|
+
|
|
98
124
|
### From source
|
|
99
125
|
|
|
100
126
|
```sh
|
|
@@ -121,14 +147,14 @@ pnpm link
|
|
|
121
147
|
┌────────────────────────┐
|
|
122
148
|
│ Human annotates text │
|
|
123
149
|
│ or elements, sends │
|
|
124
|
-
│ chat, or
|
|
125
|
-
│
|
|
150
|
+
│ chat, or queues layout │
|
|
151
|
+
│ issues from the inbox │
|
|
126
152
|
└───────┬────────────────┘
|
|
127
153
|
▼
|
|
128
154
|
┌────────────────────────┐
|
|
129
155
|
│ lavish-axi poll waits │
|
|
130
156
|
│ and returns prompts │
|
|
131
|
-
│
|
|
157
|
+
│ the user queued │
|
|
132
158
|
└────────────────────────┘
|
|
133
159
|
```
|
|
134
160
|
|
|
@@ -136,13 +162,20 @@ pnpm link
|
|
|
136
162
|
- **Portable artifacts** - The artifact runs in an iframe while Lavish injects a small SDK for annotations, snapshots, feedback controls, and render-time layout checks.
|
|
137
163
|
Lavish does not inject any design system, so the saved HTML file renders identically whether you open it through `lavish-axi` or directly in a browser.
|
|
138
164
|
Run `lavish-axi design` for the single source of agent-facing design guidance and optional CDN or Mermaid snippets.
|
|
139
|
-
- **Open-time layout gate** - The browser chrome masks an artifact only while the real in-iframe audit
|
|
140
|
-
|
|
141
|
-
The user can click **Show anyway**, and a bounded safety timeout fails open
|
|
142
|
-
- **Layout
|
|
165
|
+
- **Open-time layout gate** - The browser chrome masks an artifact only while the real in-iframe audit waits for fonts and final geometry.
|
|
166
|
+
The first completed check always reveals the artifact, whatever it found; the gate never holds the review hostage waiting for a repair.
|
|
167
|
+
The user can click **Show anyway**, and a bounded safety timeout fails open when no check has completed.
|
|
168
|
+
- **Layout issues inbox** - Detection is passive. After fonts and finite animations settle, the injected SDK confirms severe failures from direct rendered evidence such as materially escaped meaningful content or required controls, clipped text fragments, viewport reachability, or near-total semantic occlusion.
|
|
143
169
|
Explicit ellipsis and line clamp, standard visually hidden accessibility text, intentional scrollers or masks, parent overhang, generic element scroll geometry, decorative overlap, and uncertain motion do not produce findings by themselves.
|
|
144
|
-
Proven failures are
|
|
145
|
-
|
|
170
|
+
Proven failures are filed in a **Layout issues** button in the top bar, which is hidden while nothing is unresolved and otherwise shows the unresolved count.
|
|
171
|
+
Its drawer lists each issue with severity, a plain-language explanation, the affected viewport, the target/component identity, when it was last seen, and its lifecycle state, plus per-issue **Reveal** (highlight it in the artifact) and **Dismiss** actions.
|
|
172
|
+
Nothing is selected by default. The user picks issues (or **Select all**) and **Queue selected fixes** turns that whole group into one ordinary queued prompt, tagged `layout-warnings`, that reaches the agent through the normal feedback path when they send.
|
|
173
|
+
Detection never returns `lavish-axi poll` and never wakes an agent; only the user queueing a fix does. The one exception is a fatal `artifact_failures` response, for failures that make the review itself unusable, such as the artifact document or one of its own local assets failing to load.
|
|
174
|
+
- **Layout issue lifecycle** - Each issue is identified by a stable fingerprint of the diagnostic rule, the normalized target identity, and the viewport class, so repeat detections update one record instead of inflating the count.
|
|
175
|
+
`Open` means the latest completed check for its viewport still detects it. `Queued for fix` means the user asked for a repair - it stays unresolved and counted, and cannot be queued again while that request is outstanding.
|
|
176
|
+
`Resolved` requires a newer successful artifact load plus a complete check at the same viewport that no longer detects it; it then leaves the count but keeps a bounded history.
|
|
177
|
+
`Still present` (recurring) means a queued issue survived a newer revision, so it is selectable again with its earlier attempt retained. `Unverified` means a reload or check failed or was incomplete, so the prior issue was preserved rather than cleared. `Returned` means a resolved issue came back on a later revision.
|
|
178
|
+
Dismissal applies only to the current artifact revision; a later revision surfaces the issue again if it is still detected. A check at one viewport never clears an issue found at another, and a viewport removed from the configured diagnostic set (`LAVISH_AXI_DIAGNOSTIC_VIEWPORTS`, default all) is marked obsolete with an explicit reason rather than reading as fixed.
|
|
146
179
|
- **Local assets** - Copy local images, CSS, fonts, and scripts next to the HTML artifact and reference them with relative paths from that directory; root-prefixed paths such as `/assets/logo.png` will not resolve through Lavish's artifact route.
|
|
147
180
|
- **Export and sharing** - `lavish-axi export` writes `<name>.export.html` by inlining local assets only, stripping the annotation SDK, and leaving remote CDN/font references as links that still need network access.
|
|
148
181
|
`lavish-axi share` publishes the same local-inlined HTML to [ht-ml.app](https://ht-ml.app), a third-party hosting service not part of Lavish.
|
|
@@ -151,7 +184,7 @@ pnpm link
|
|
|
151
184
|
Per-asset and per-bundle inline caps default to 10 MB and 25 MB, overridable with `LAVISH_AXI_EXPORT_MAX_ASSET_BYTES` and `LAVISH_AXI_EXPORT_MAX_BUNDLE_BYTES`.
|
|
152
185
|
Unresolved local assets or export notices such as author-set CSP meta tags and redacted file URLs are surfaced in command or browser output.
|
|
153
186
|
Use `--token` or `LAVISH_AXI_HTML_APP_TOKEN` for an optional bearer token; set `LAVISH_AXI_HTML_APP_API_URL` only when overriding the ht-ml.app API base.
|
|
154
|
-
- **Live reload** - Lavish watches the HTML artifact file by default and preserves the artifact iframe scroll position
|
|
187
|
+
- **Live reload** - Lavish watches the HTML artifact file by default and preserves review context across reloads: the artifact iframe scroll position, an open annotation card's unsent text, and answers to `data-lavish-question` controls (application-owned form state is left alone). While a queued layout-issue batch is outstanding, closely spaced saves coalesce so one batch of fixes costs one refresh. To also reload on sibling asset changes, add `data-lavish-live-reload-root` to the root element or `<meta name="lavish-live-reload" content="root">`.
|
|
155
188
|
- **Feedback controls** - Native controls (radios, checkboxes, inputs, selects, buttons, labels, disclosure summaries, contenteditable) are interactive automatically, so they do not need `data-lavish-action`.
|
|
156
189
|
For reversible choices, let option clicks update local state, then queue exactly one final answer from a per-question submit or Queue answer button with `window.lavish.queuePrompt()`.
|
|
157
190
|
Mark only custom (non-native) clickable elements with `data-lavish-action` so Lavish does not annotate them, and use `data-lavish-question` or `queueKey` when pre-send updates for the same question should replace each other.
|
|
@@ -160,7 +193,7 @@ pnpm link
|
|
|
160
193
|
- **Keyboard shortcuts** - In the chrome composer, Enter sends queued prompts and Shift+Enter inserts a newline.
|
|
161
194
|
In the annotation card, Enter queues the annotation, Shift+Enter inserts a newline, and Ctrl+Enter (Cmd+Enter on macOS) queues it and sends all queued prompts immediately.
|
|
162
195
|
Cmd+I or Ctrl+I toggles between annotate and explore mode from either the browser chrome or the artifact iframe, including while focus is in a textarea or control.
|
|
163
|
-
- **Agent presence** - The browser shows when no agent is listening, keeps queued feedback
|
|
196
|
+
- **Agent presence** - The browser shows when no agent is listening, keeps queued feedback for the next successful `lavish-axi poll` send even across reloads, and only blocks human sends while the agent is working on delivered feedback; the agent's reply (`--agent-reply`) concludes that work and re-enables sends.
|
|
164
197
|
The no-timeout poll always writes an immediate stderr banner so it is visibly not hung; it adds the periodic stderr wait ticks only in an interactive terminal, so when stderr is piped (as under agent harnesses) the captured output carries no tick noise. Stdout always stays reserved for the final response; if the poll is interrupted or times out, re-run it because queued feedback is never lost.
|
|
165
198
|
Codex-specific guidance keeps that poll attached to the active turn instead of hiding it in a background task, because completed background tasks may not resume the agent.
|
|
166
199
|
- **Session end etiquette** - Lavish tracks who ended a session: a human clicking **End session** (or **Send & end session**) in the browser is a user-initiated end, while `lavish-axi end <html-file>` is agent-initiated.
|
|
@@ -179,6 +212,7 @@ pnpm link
|
|
|
179
212
|
- **Server cleanup** - The detached server stops after the last session ends when nothing is connected, or after `LAVISH_AXI_IDLE_TIMEOUT_MS` (default 30 minutes) with no browser or poll connections.
|
|
180
213
|
Set `LAVISH_AXI_IDLE_TIMEOUT_MS=0` or `off` to disable idle self-shutdown.
|
|
181
214
|
- **Local-first state** - Session state stays under `~/.lavish-axi/` by default, or `LAVISH_AXI_STATE_DIR` when set.
|
|
215
|
+
- **Diagnostic viewports** - `LAVISH_AXI_DIAGNOSTIC_VIEWPORTS` sets which viewport classes the layout-issue inbox tracks (`mobile`, `compact`, `desktop`; comma-separated, default all). Warnings whose class leaves the set are marked obsolete with an explicit reason instead of silently reading as fixed.
|
|
182
216
|
- **Server port** - Set `LAVISH_AXI_PORT` to choose the server port; it defaults to `4387`.
|
|
183
217
|
- **Network binding** - The server binds to loopback (`127.0.0.1`) by default. Set `LAVISH_AXI_HOST` to bind elsewhere; a wildcard (`0.0.0.0` or `::`) binds every interface. Binding beyond loopback exposes an unauthenticated server that can read and serve arbitrary local files to anything that can reach it, so only do so on a trusted network. Set `LAVISH_AXI_LINK_HOST` to control the hostname written into generated session links (defaults to the bind address, or loopback when bound to a wildcard).
|
|
184
218
|
- **Allowed hosts** - To defend against DNS rebinding, the server rejects (`403`) any request whose `Host` header is missing or not one it answers to: the loopback names (`127.0.0.1`, `::1`, `localhost`) plus the configured bind and link host. If you reach the server under another name - a wildcard bind accessed by LAN IP, a reverse-proxy hostname, or an extra interface - list those names in `LAVISH_AXI_ALLOWED_HOSTS` (whitespace-separated) to allow them. Behind a reverse proxy, the forwarded `X-Forwarded-Host` is validated against the same list, so add your public hostname there and have the proxy send it. Set `LAVISH_AXI_ALLOWED_HOSTS` to `*` to disable the check entirely (only when the server sits behind your own authentication or proxy).
|
|
@@ -186,20 +220,21 @@ pnpm link
|
|
|
186
220
|
|
|
187
221
|
## CLI Reference
|
|
188
222
|
|
|
189
|
-
| Command | Description
|
|
190
|
-
| ------------------------------- |
|
|
191
|
-
| `lavish-axi` | Show current sessions and usage guidance.
|
|
192
|
-
| `lavish-axi update` | Check for or apply the latest npm release through the AXI SDK self-updater.
|
|
193
|
-
| `lavish-axi <html-file>` | Open or resume a Lavish Editor session, with the open-time layout gate enabled by default. Refuses to reopen a session the user explicitly ended from the browser unless `--reopen` is passed.
|
|
194
|
-
| `lavish-axi poll <html-file>` | Long-poll until the user sends feedback
|
|
195
|
-
| `lavish-axi end <html-file>` | End a session as the agent; unlike a user-initiated end from the browser, this still allows a plain reopen later.
|
|
196
|
-
| `lavish-axi export <html-file>` | Write a portable copy of the artifact: one HTML file with its local assets inlined, so it opens with no server and no sibling files. Remote CDN/font references are left as links.
|
|
197
|
-
| `lavish-axi share <html-file>` | Publish the artifact (local assets inlined) to [ht-ml.app](https://ht-ml.app), a third-party host not part of Lavish, and print a visitable URL plus a secret update key; shares are public by default, and `--password` makes viewers enter the password before viewing.
|
|
198
|
-
| `lavish-axi stop` | Shut down the background server.
|
|
199
|
-
| `lavish-axi playbook [id]` | List focused artifact guidance or show one playbook; agents must open each matching playbook before writing HTML.
|
|
200
|
-
| `lavish-axi design` | Show agent-facing design guidance, including optional CDN and Mermaid snippets.
|
|
201
|
-
| `lavish-axi setup hooks` | Install or repair optional SessionStart hooks for Claude Code, Codex, OpenCode, and GitHub Copilot CLI; restart the agent session afterward.
|
|
202
|
-
| `lavish-axi
|
|
223
|
+
| Command | Description |
|
|
224
|
+
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
225
|
+
| `lavish-axi` | Show current sessions and usage guidance. |
|
|
226
|
+
| `lavish-axi update` | Check for or apply the latest npm release through the AXI SDK self-updater. |
|
|
227
|
+
| `lavish-axi <html-file>` | Open or resume a Lavish Editor session, with the open-time layout gate enabled by default. Unresolved layout issues from earlier in the session are preserved. Refuses to reopen a session the user explicitly ended from the browser unless `--reopen` is passed. |
|
|
228
|
+
| `lavish-axi poll <html-file>` | Long-poll until the user sends feedback or ends the session; detected layout issues wait in the user's Layout issues inbox and arrive only when queued. Leave no-timeout polls running, or re-run them if interrupted. Codex guidance keeps polls attached to the active turn. On `status: ended`, stop polling and do not reopen uninvited. |
|
|
229
|
+
| `lavish-axi end <html-file>` | End a session as the agent; unlike a user-initiated end from the browser, this still allows a plain reopen later. |
|
|
230
|
+
| `lavish-axi export <html-file>` | Write a portable copy of the artifact: one HTML file with its local assets inlined, so it opens with no server and no sibling files. Remote CDN/font references are left as links. |
|
|
231
|
+
| `lavish-axi share <html-file>` | Publish the artifact (local assets inlined) to [ht-ml.app](https://ht-ml.app), a third-party host not part of Lavish, and print a visitable URL plus a secret update key; shares are public by default, and `--password` makes viewers enter the password before viewing. |
|
|
232
|
+
| `lavish-axi stop` | Shut down the background server. |
|
|
233
|
+
| `lavish-axi playbook [id]` | List focused artifact guidance or show one playbook; agents must open each matching playbook before writing HTML. |
|
|
234
|
+
| `lavish-axi design` | Show agent-facing design guidance, including optional CDN and Mermaid snippets. |
|
|
235
|
+
| `lavish-axi setup hooks` | Install or repair optional SessionStart hooks for Claude Code, Codex, OpenCode, and GitHub Copilot CLI; restart the agent session afterward. |
|
|
236
|
+
| `lavish-axi setup plugin` | Register the installed package as an [Agent Plugin](https://agent-plugins.org) in VS Code, Cursor, and GitHub Copilot CLI; opt-in, idempotent, no marketplace involved. Reload each client afterward. |
|
|
237
|
+
| `lavish-axi server` | Run the local Lavish Editor server. |
|
|
203
238
|
|
|
204
239
|
Known playbook IDs: `diagram`, `table`, `comparison`, `plan`, `code`, `input`, `slides`.
|
|
205
240
|
One artifact often combines several playbooks, such as a plan that includes a comparison and a diagram, so agents must match against each `use_when` trigger and open every matching playbook before writing HTML.
|