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.