zpaper-draft

Type to search...

to open search from anywhere

/doc/src-tauri/CLAUDE.md

CLAUDE.md at /doc/src-tauri/CLAUDE.md

Path: doc/src-tauri/CLAUDE.md

doc/src-tauri/ CLAUDE.md

Tauri v2 wrapper for the zudo-doc site. Spawns the doc dev/serve sidecar, shows a loading screen, and swaps to the real site once the sidecar is ready.

Launch error / retry pattern

When the sidecar fails to come up, the loading HTML stays visible and turns into a retry panel. The flow has three pieces.

launch-error event contract

emit_launch_error in src/main.rs sends a launch-error Tauri event to the loading window with this payload:

{ "reason": "timeout" | "sidecar_exited", "logPath": "/absolute/path/to/sidecar.log" }
  • reason: "timeout" — wait_for_ready polled the dev server URL and never saw a successful response within the timeout budget.
  • reason: "sidecar_exited" — the spawned sidecar process exited (clean or crash) before the URL became reachable.
  • logPath is an absolute path to the captured sidecar stdout/stderr log so the user can copy it.

frontend/index.html registers a window.__TAURI__.event.listen('launch-error', ...) handler at load time and reveals the error panel (reason text, log path, Retry button, Copy button). The user can retry from the panel.

retry_launch Tauri command

#[tauri::command] async fn retry_launch(...) re-runs the sidecar startup. It is debounced via the retry_in_flight flag on AppState — concurrent invocations short-circuit while a retry is already running. The frontend Retry button is disabled while in flight (and re-enabled after retry_launch resolves or a fresh launch-error arrives) to mirror the guard.

Internally, retry_launch reuses do_refresh so the sidecar-restart logic (kill old child, spawn new one, wait for ready, swap window) stays single-source. Don’t fork a parallel restart path here.

app.withGlobalTauri requirement

tauri.conf.json must keep app.withGlobalTauri: true. The bundled frontend/index.html is plain HTML loaded via tauri:// and has no bundler in the loop, so it reaches the Tauri JS API through the window.__TAURI__ global. The tauri_conf_enables_global_tauri test in src/main.rs enforces this — do not flip it to false.

Reference pointers

  • Reference implementation: $HOME/.claude/doc/src-tauri/ (CCResDoc) — same launch-error + retry pattern, kept as a canonical sample.
  • tauri-wisdom doc: /pj/zudo-tauri/docs/architecture/loading-screen/ — design rationale and the loading-screen architecture this code is based on.

Keep in sync with blog/src-tauri/

blog/src-tauri/ and doc/src-tauri/ duplicate the launch-recovery code by design — there is no shared crate yet. Any change to the recovery pattern in one MUST be mirrored in the other. Touch points:

  • Cargo.toml — serde_json regular dependency (used to build the event payload).
  • src/main.rs — ReadyResult, wait_for_ready signature, emit_launch_error, retry_launch, the retry_in_flight guard on AppState.
  • tauri.conf.json — app.withGlobalTauri (must remain true).
  • frontend/index.html — launch-error listener, Retry button + disable-while-in-flight, Copy button, retry_launch invoke.