webspace_app CLAUDE.md

CLAUDE.md

WebSpace: Flutter app managing multiple websites with per-site cookie isolation via flutter_inappwebview. Platforms: iOS, Android, macOS, Linux (WPE WebKit fork).

Style (output, code, commits)

• No preamble, no closing fluff, no em-dashes, no emoji.
• Don't use the phrase "load-bearing".
• Code first; explain only the non-obvious.
• Default to no code comments. Only add when the why is non-obvious (hidden constraint, workaround for a specific bug, surprising behavior). Never restate what the code does. Never reference the current task or PR.
• Commit messages: short subject (<70 chars, imperative), 1-2 line body for the why if needed. No marketing prose, no bullet lists of every changed file, no "this commit also...".
• Don't speculate. Read the code or docs before asserting an API/version/flag.

Git

• Never push to master. Branch first.
• git pull --rebase always.
• Before pushing a branch, check it still exists on remote; if merged+deleted, branch fresh from master.
• Translations ride their own commit. A change that adds or renames a user-facing string commits the code plus lib/l10n/app_en.arb; the other 66 app_*.arb files go in a second commit on top of it. A 67-file translation diff otherwise buries the change a reviewer actually needs to read. Applies equally to a key rename (the settings-hints subtitle/hint move) and to adding a locale. Ordering matters: the code commit on its own fails l10n_coverage (it enforces key parity across every locale), so put the translation commit immediately after and push them together. CI runs the pushed head, not each commit, so the pair is green even though the first half is not; a bisect that lands between them will fail l10n, which is the accepted cost of the split.
• Don't commit derivatives. If a file is the output of a script, parser, compiler, dumper, or any build step that reads from elsewhere — it doesn't belong in the repo. Commit the inputs (sources you author, pinned upstream refs) and the runner (build.rs, scripts, Cargo features); regenerate the output at build time into $OUT_DIR/build//target/. Same applies to vendored third-party source: if a script can fetch + assemble it from upstream at a pinned ref, don't check the upstream tree in. Concrete check before staging: "could I delete this file and reproduce it by running one command from a clean clone?" — if yes, it's a derivative; ignore it. See rust/webspace_adblock/build.rs for an example.