ade-web

name	ade-web
description	Launch the ADE desktop app's renderer as a standalone web app (Vite-only preview) seeded with real data from the ADE database. Works from any lane worktree without interfering with running ADE sockets or runtimes. Use when asked to start, run, or preview the ADE desktop web renderer, open the ADE web app, or view ADE UI in a browser.
metadata	{"author":"ADE","version":"0.1.0"}

ade-web — Launch the ADE Desktop Web Renderer

Starts the ADE desktop renderer as a browser-accessible web app on http://localhost:5173, seeded with a snapshot of the real ADE database. Safe to run alongside the ADE beta or any other running ADE runtime — it does not touch sockets or start new runtimes.

When to use

• User asks to run, start, preview, or open the ADE web app / desktop web renderer
• User wants to visually inspect or iterate on ADE desktop UI changes in a browser
• User asks to launch ADE web from a specific lane or worktree

Procedure

1. Resolve the workspace root

The web renderer must run from the current lane's worktree, not the main project checkout.

WORKTREE_ROOT="$(pwd)"

If pwd is not already inside .ade/worktrees/<lane>/, resolve it:

# If inside a worktree, pwd is already correct.
# If at the project root, there is no lane context — ask the user which lane.

Confirm the desktop app exists at $WORKTREE_ROOT/apps/desktop/package.json.

2. Kill any stale Vite on port 5173

lsof -ti :5173 2>/dev/null | xargs kill 2>/dev/null

Do not kill processes on any other port. Do not touch ADE runtime sockets (/tmp/ade-runtime-dev.sock, ~/.ade-beta/sock/ade.sock, etc.).

3. Seed the database snapshot

Export real data from the global ADE database into the browser mock:

cd "$WORKTREE_ROOT/apps/desktop" && node ./scripts/export-browser-mock-ade-snapshot.mjs

This reads .ade/ade.db from the primary project root (auto-detected even from worktrees) and writes src/renderer/browser-mock-ade-snapshot.generated.json.

If this fails with "No database", the user hasn't opened the project in ADE desktop yet. The renderer will still work with built-in demo data.

4. Start the Vite dev server

cd "$WORKTREE_ROOT/apps/desktop" && npm run dev:vite

This runs vite --port 5173 --strictPort. The predev:vite hook re-exports the snapshot automatically, so step 3 is optional if you go straight here.

Wait for the VITE ready message confirming it's listening.

5. Open in the ADE browser (optional)

If the user wants it in ADE's built-in browser:

ade actions run built_in_browser createTab --socket --text --arg url=http://localhost:5173/work

Or navigate an existing tab:

ade actions run built_in_browser navigate --socket --text --arg url=http://localhost:5173/work

Use --socket to communicate with the running ADE instance. This does not start a new runtime or interfere with the existing socket.

Important constraints

• Never start a runtime or bridge. Do not run dev:vite:live, dev:browser-bridge, or ensureRuntime. These may detect version mismatches and restart the user's running ADE beta/dev runtime.
• Never start or manage the ADE socket directly. The Vite-only preview uses browserMock.ts to stub window.ade — it does not need a runtime connection. The --socket flag on ade actions run above is fine; it connects to the running desktop instance rather than managing the socket itself.
• Always run from the worktree. All cd commands, file reads, and file edits must target paths under $WORKTREE_ROOT, never the main project checkout. When grep or find returns absolute paths rooted at the main checkout, translate them to the worktree before editing.
• Port 5173 only. Do not change the port. The desktop app's Vite config uses --strictPort so it will error if the port is taken rather than silently picking another.

Cleanup

When done, kill the Vite server:

lsof -ti :5173 2>/dev/null | xargs kill 2>/dev/null

Troubleshooting

Problem	Fix
Port 5173 is already in use	Kill the stale process: lsof -ti :5173 | xargs kill
No database at ...	Run export-browser-mock-ade-snapshot.mjs with ADE_PROJECT_ROOT=/path/to/ADE pointing at the main checkout
ERR_CONNECTION_REFUSED in ADE browser	Vite died — restart with npm run dev:vite from the worktree
Mock data instead of real data	Re-run the export script, then restart Vite or hard-refresh the browser
proxy error: /health ECONNREFUSED 127.0.0.1:18765	Expected — this is the browser bridge port. Vite-only mode doesn't use it. Ignore.