lavish-axi

When Mermaid diagrams (flowchart, sequence, class, ER, and state diagrams) are rendered in .mermaid containers, they become editable Excalidraw whiteboards in the browser.

Workflow for Agents:

1. User Feedback: When a user queues feedback, the poll command returns a whiteboard prompt containing a bounded edit summary, a scenePath (.excalidraw JSON), and a previewPath (PNG).
2. Applying Edits: To apply changes, update the Mermaid source in the artifact. Do not attempt to write the Excalidraw scene file back to the filesystem.
3. Other types: Mermaid diagrams that are not one of the supported types embed as images that can be drawn on, but are not converted to editable shapes.

In the Lavish browser, any Mermaid diagram inside a .mermaid container is automatically converted into an editable Excalidraw whiteboard.

• Editing: Click a diagram to unlock it. Use the Fullscreen action for easier editing. Whiteboard scenes autosave locally.
• Stale Edits: If a live reload changes the Mermaid source, the whiteboard will indicate that edits are stale. You can then choose to re-convert/discard edits or continue editing the saved scene.
• Feedback: Use Queue feedback to include a bounded edit summary, the local .excalidraw scene, and PNG preview paths in the Conversation panel. Click Send to Agent to deliver.
• Note: Lavish only changes the browser view; the underlying artifact remains plain Mermaid.

Saved Excalidraw scenes created before the font-loading fix do not contain a text-metrics version. To prevent clipping when these files are reopened, Lavish performs a one-time migration:

1. Font Loading: Lavish loads the required scene fonts.
2. Expansion: It expands only the stale auto-sized text width or height values.
3. Data Preservation: The process preserves every element's position, style, binding, identity, content, and other user-edited data.
4. Persistence: Once the migration runs, the current version is persisted so the repair only occurs once.

Lavish-axi passively detects severe layout failures (e.g., clipped text, viewport unreachability, or semantic occlusion) after fonts and animations settle.

• Viewing issues: Unresolved issues appear in a Layout issues button in the top bar. Clicking it opens a drawer listing issues with severity, explanation, viewport, and target identity.
• Actions: Use Reveal to highlight an issue in the artifact or Dismiss to ignore it for the current revision.
• Queuing fixes: Select one or more issues and click Queue selected fixes. This creates a single queued prompt tagged layout-warnings that is sent to the agent via the normal feedback path.
• Lifecycle: Issues move through states like Open, Queued for fix, Resolved, Still present (recurring), Unverified, and Returned. A check at one viewport does not clear an issue found at another.

Lavish-axi facilitates a human-in-the-loop feedback cycle for web artifacts:

1. Agent writes: An agent generates an artifact.html file.
2. Lavish-axi opens: Running lavish-axi <file_path> opens a local browser UI.
3. Human annotates: A human reviews the artifact, annotating text/elements, sending chat messages, or queuing layout issues from the inbox.
4. Agent polls: The agent runs lavish-axi poll, which waits and returns the prompts queued by the user.

Sessions are keyed by the canonical HTML file path, meaning agents do not need to manage opaque session IDs.

A regression occurred where leading and trailing glyphs were clipped in Excalidraw labels (e.g., Disposable adapter sidecar, Adapter Protocol v1).

Root Cause: The convertToExcalidrawElements function measured label bounds synchronously before Excalidraw had finished loading Excalifont. This caused the browser to use a narrower serif fallback font for measurements. When Excalifont eventually loaded, its wider glyphs were drawn into the stale, narrower bounds, resulting in horizontal clipping at the edges.

The Fix:

1. The Excalidraw scene-export boundary now loads required font subsets first.
2. Mermaid skeletons are re-materialized before mounting the editor.
3. Multiline wrapping is re-run using the loaded font metrics.

You can reproduce the difference between fixed-theme and theme-aware Mermaid diagrams using the provided HTML files.

1. Fixed Theme (Before): Use before.html to see the behavior where the diagram uses a fixed theme: "base" regardless of the page theme.
2. Theme-Aware (After): Use after.html to see the shipped implementation which uses the MERMAID_CDN_SNIPPET from src/design-reference.js.

To view them, run the following command:

lavish-axi <file>

(Replace <file> with before.html or after.html). You can then use the built-in Dark/Light toggle to verify that the theme-aware version updates correctly.

Once the skill is installed, you can invoke it directly in agents that support slash commands (such as Claude Code) or simply ask the agent to perform a visual task. The agent will automatically load the skill when it recognizes a task that is easier to grasp visually (e.g., plans, diagrams, tables, or reports).

Example slash command invocation:

/lavish let's discuss our plan here

Use the following commands to package or publish your artifacts:

• lavish-axi export: Writes a <name>.export.html file. This inlines local assets, strips the annotation SDK, and leaves remote CDN/font references as links.
• lavish-axi share: Publishes the local-inlined HTML to ht-ml.app.

Sharing Options:

• Use --password <password> to make the publication private and password-protected. This returns a secret update_key for future management.
• Use --token <token> or the LAVISH_AXI_HTML_APP_TOKEN env var for bearer token authentication.
• Use LAVISH_AXI_HTML_APP_API_URL to override the default ht-ml.app API base.

Limits:

• Per-asset inline cap: 10 MB (default).
• Per-bundle inline cap: 25 MB (default).
• Override via LAVISH_AXI_EXPORT_MAX_ASSET_BYTES and LAVISH_AXI_EXPORT_MAX_BUNDLE_BYTES.

To provide your agent with ambient context—including your live open sessions—at the start of every session, you can install the CLI globally and set up session hooks. This is useful for resuming in-flight reviews.

Supported tools for hooks: Claude Code, Codex, OpenCode, and GitHub Copilot CLI.

Note: You must restart your agent session after running the setup for the hooks to take effect.

npm install -g lavish-axi
lavish-axi setup hooks

Because Lavish is an AXI (Agentic eXecutable Interface), any capable agent can run the CLI directly without any prior installation. You can instruct your agent to use npx -y lavish-axi to generate artifacts like product or technical plans.

Use `npx -y lavish-axi` to write a product or technical plan for what we discussed.