Cross-Cutting Debugging Rules

Framework JS API — Read First, Never Assume

Before writing JavaScript that interacts with a reactive framework (Datastar, Alpine, Vue, Svelte, Solid, etc.), read the framework's API reference FIRST.

ES module frameworks often expose no global window.Framework API. Do not assume window.datastar, window.Alpine, etc. exist without confirmation. Many modern frameworks are pure ES modules — the API is only available through imports, not global scope.

Verify Binary Freshness After a Fix

When a code change doesn't take effect, check these timestamps:

1. Binary must be newer than source (or regenerated files like *_templ.go)
2. Server process start time must be newer than binary

If stale:

# Kill the process using the port
lsof -ti:<PORT> | xargs kill -9 2>/dev/null