From 2500cc4b1a2a0672058fef86e9d9fc50c163fc68 Mon Sep 17 00:00:00 2001 From: Florian Schroedl Date: Thu, 5 Mar 2026 14:12:36 +0100 Subject: [PATCH] docs: document squint watcher blank page pitfall and recovery The squint watcher can produce truncated .mjs files when it detects file changes mid-save, causing Vite to serve a broken module and the browser page to go blank with no terminal errors. Document how to detect this (check .mjs line count) and recover (touch source file + hard refresh, or restart the tmux pane). --- AGENTS.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 6290c9a..6053f3d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -281,6 +281,28 @@ Toggle with: `document.documentElement.dataset.theme = "dark" | "light"` 4. **No lazy seq flattening in Eucalypt** — use `into` with `mapcat`/`map` to build hiccup vectors eagerly 5. **Eucalypt render arg order** — `(eu/render hiccup container)`, hiccup first 6. **Eucalypt import** — `(:require ["eucalypt" :as eu])`, quoted string for npm package +7. **Blank page from squint watcher race condition** — The squint watcher can produce truncated/empty `.mjs` files when it detects a file change mid-save. Vite picks up the broken module and the page goes blank with no terminal errors (the crash is browser-side only). This commonly happens during rapid edits or when multiple files change at once. + + **How to detect:** Page is blank, no compile errors in the tmux pane. Verify with: + ```sh + wc -l dev/squint/.compiled/ui/.mjs # Should be >1 line + ``` + + **How to recover:** + ```sh + # Option A: touch the source file to trigger recompile + touch src/ui/.cljc + # Then hard-refresh the browser (Ctrl+Shift+R) + + # Option B: restart the squint tmux pane + # Kill existing processes and recreate: + tmux split-window -v -t ui-dev \ + "bash -c 'cd dev/squint && npx squint watch & cd dev/squint && npx vite --port 4002'" + tmux select-layout -t ui-dev tiled + # Then hard-refresh the browser + ``` + + **After recovering**, always verify the compiled output is complete before committing. ## Replicant Pitfalls