# Pauta 2.0.0: every rule > 352 rules from https://pauta-project.dev/2.0.0/, published 2026-11-06. Each page's prose, screenshots and mockups are on > the page itself; this file holds the rules alone. ## Using Pauta **Building a feature:** read the rules on its page first, then copy from the code each rule's *Reference* names. Editora is the reference implementation. **Auditing an app:** 1. Find the edition the app implements: `pauta.version` in its `pom.xml`, the About window, or its README. Read that edition's rules at `https://pauta-project.dev//rules.json`; if the app names none, use this one. 2. Take each rule in turn. *Check (code)*: read or search the source as the check says. *Check (test)*: find the named test, or the app's equivalent, and confirm the build runs it. *Check (by hand)*: source can't settle it; report it as manual. 3. Report one line per rule: its ID, its level, pass / fail / not applicable / manual, and the evidence as `file:line`. A failed MUST blocks a release. 4. A rule applies to every app unless its text names the apps it covers ("An app with user documents…"). Cite a rule by its ID and edition, for example "KBD-07 (Pauta 2.0.0)". Each rule's address is the page's plus `#` and the ID in lowercase: `https://pauta-project.dev/2.0.0/keyboard/#kbd-07`. Levels: **MUST**: A release blocker for a new app. **SHOULD**: Expected unless the app has a stated reason. **MAY**: A pattern worth copying when the app grows into it. ## Platform baseline (PLAT) https://pauta-project.dev/2.0.0/platform/: JDK, JavaFX, AtlantaFX, NullAway, Maven Wrapper, tests and coverage: the stack every app shares. - **PLAT-01 · MUST.** The app builds on **JDK 25 or newer**. `maven.compiler.release` 25 is the floor, not the ceiling: build and bundle a current JDK. - *Check (code):* `pom.xml` sets `maven.compiler.release` to 25 and the enforcer's `requireJavaVersion` to the open-ended range `[25,)`. - *Reference:* Editora `pom.xml`. - **PLAT-02 · MUST.** The installers carry a jlinked runtime; users never install Java. - *Check (code):* the `dist` profile's jpackage step builds a jlinked app image (`jLinkOptions`) and wraps the installer around it. - *Reference:* Editora `pom.xml` (`dist` profile). - **PLAT-03 · MUST.** The app builds on **JavaFX 27 or newer**. - *Check (code):* `pom.xml` sets `javafx.version` to 27 or later. - *Reference:* Editora `pom.xml`. - **PLAT-04 · SHOULD.** The app is one named JPMS module, `com.`, whose `module-info.java` opens only what reflection, FXML and Jackson need. - *Check (code):* `src/main/java/module-info.java` declares `module com.`; each `opens` line serves FXML, Jackson or another reflective reader. - *Reference:* Editora `src/main/java/module-info.java`. - **PLAT-05 · MUST.** Controls use **AtlantaFX 3.x** (`atlantafx-base`), with light and dark themes. - *Check (code):* `pom.xml` depends on `atlantafx-base` 3.x; the theme list offers at least one light and one dark theme. - *Reference:* Editora `pom.xml`, `ui/Themes.java`. - **PLAT-06 · MUST.** App stylesheets take their colors from AtlantaFX `-color-*` tokens, or from state tokens built on them; no component rule carries a fixed hex. See [Icons and color](https://pauta-project.dev/2.0.0/icons-and-color/). - *Check (code):* `grep -nE '#[0-9a-fA-F]{3,8}\b' app.css` finds hexes only where a token is defined (a `ladder()` of the ground, a scoped `-color-*` block), not in a component's `-fx-*-color` or `-fx-fill`. - *Reference:* Editora `app.css`; `StyleContrastTest.severityAndDebugColoursComeFromTheStateTokens` holds the severity and debug colors. Editora's `app.css` still has fixed hexes in a few component rules (the breakpoint markers, the execution arrow, the editor area's defaults). - **PLAT-07 · SHOULD.** The app bundles **Inter** (Regular, Bold, Italic, BoldItalic and `OFL.txt`), registers it with `Font.loadFont` before any stylesheet, and attaches `ui-font.css` to every scene and dialog pane. - *Why:* the family has one look on every OS. - *Check (code):* the four Inter `.ttf` files and `OFL.txt` are in the resources; one place loads them before the first stylesheet, and one listener adds `ui-font.css` to every window's scene. - *Reference:* Editora `ui/Fonts.java`; `App.installUiFont`. - **PLAT-08 · MUST.** The build is **Maven** with the **Maven Wrapper** committed (`mvnw`, `mvnw.cmd`, `.mvn/wrapper/`), so `./mvnw` works on a clean machine. - *Check (code):* `mvnw`, `mvnw.cmd` and `.mvn/wrapper/maven-wrapper.properties` are in the repository. - *Reference:* Editora `mvnw`, `.mvn/wrapper/`. - **PLAT-09 · MUST.** Nullness is declared with **JSpecify** and checked by **NullAway** on **Error Prone** at compile time. Every package is `@NullMarked` in its own `package-info.java`. - *Check (code):* the compiler arguments include `-Xep:NullAway:ERROR`; every source package has a `package-info.java` with `@NullMarked`. - *Reference:* Editora `pom.xml`, `docs/conventions.md#null-annotations-jspecify-checked-by-nullaway`. - **PLAT-10 · MUST.** Code is formatted by **Spotless** with Palantir Java Format, and CI fails an unformatted change. - *Check (code):* the spotless plugin configures `palantirJavaFormat`, and a CI job runs `spotless:check`. - *Reference:* Editora `pom.xml` (spotless plugin), `.github/workflows/ci.yml` (*Format*). - **PLAT-11 · MUST.** Tests run on **JUnit** (Jupiter, 5 or newer) and **TestFX** over JavaFX's built-in **Headless** glass platform (`-Dglass.platform=Headless`), so FX tests need no display, no xvfb and no Monocle. - *Check (code):* surefire's `systemPropertyVariables` set `glass.platform` to `Headless`; no Monocle dependency and no xvfb step in CI. - *Reference:* Editora `pom.xml` (surefire), `docs/testing.md`, `FxTestSupport`. - **PLAT-12 · MUST.** A **JaCoCo** `check` runs at `mvn verify`: **≥ 0.90 lines, ≥ 0.90 methods**, ≥ 0.79 branches, plus per-package floors. - *Check (code):* the `jacoco-check` execution is bound to `verify` with `BUNDLE` limits of 0.90 `LINE` and 0.90 `METHOD`. - *Reference:* Editora `pom.xml` `jacoco-check`. - **PLAT-13 · SHOULD.** The app logs through `java.util.logging`, captured in-app by the Debug Log. - *Check (code):* the Debug Log adds a handler to the root `java.util.logging` logger; the app's own code imports no other logging API. - *Reference:* Editora `ui/DebugLog.java`. - **PLAT-14 · SHOULD.** JSON config files are Jackson POJOs, each with a `SCHEMA_VERSION`. - *Check (code):* every class written to the config folder declares `SCHEMA_VERSION` and a `schemaVersion` field. - *Reference:* Editora `config/Settings`, `config/migration/ConfigSchema.java`. ## Repository documents (REPO) https://pauta-project.dev/2.0.0/repository/: README, CHANGELOG, LICENSE, NOTICE, AGENTS.md and the rest of the files every repository carries. - **REPO-01 · MUST.** `README.md` is a landing page of about 200 lines: logo, badges, a one-paragraph pitch, the hero screenshot, highlights, install, build, command line, config folder, license. Detail lives on the website. - *Check (code):* `README.md` is near 200 lines and has those parts, with links to the website for the rest. - *Reference:* Editora `README.md`. - **REPO-02 · MUST.** `CHANGELOG.md` follows [Keep a Changelog 1.1](https://keepachangelog.com/en/1.1.0/) and SemVer: an `## [Unreleased]` section with Added / Changed / Fixed / Removed, and each entry opens with a bold one-line summary written for users. - *Check (code):* the file names Keep a Changelog and Semantic Versioning, starts with `## [Unreleased]`, and every entry starts with `- **`. - *Reference:* Editora `CHANGELOG.md`. - **REPO-03 · MUST.** `LICENSE` is MIT, "Copyright (c) 2026 Adrián Arturo De León Saldivar". - *Check (code):* `LICENSE` opens with `MIT License` and that copyright line. - *Reference:* Editora `LICENSE`. - **REPO-04 · MUST.** `NOTICE` gives the app name, the copyright, "licensed under the MIT License", then every bundled third-party component with its license (Inter is OFL, AtlantaFX is MIT, OpenJFX is GPLv2+CPE…). It ships inside the installers too. - *Check (test):* a test fails when a runtime dependency in `pom.xml` has no `NOTICE` entry, and another when `LICENSE` and `NOTICE` are not packaged. - *Reference:* Editora `NOTICE`, `NoticeCoverageTest`, `BuildHygieneTest`. - **REPO-05 · MUST.** `AGENTS.md` holds the operational rules for coding agents: essential commands, worktree-per-task, the change checklist. It is not a changelog. A short `CLAUDE.md` points to it. - *Check (code):* `AGENTS.md` has sections for commands, worktrees and the change checklist; `CLAUDE.md` is a few lines that send the reader to `AGENTS.md`. - *Reference:* Editora `AGENTS.md`, `CLAUDE.md`. - **REPO-06 · MUST.** `CONTRIBUTING.md` says how to build, test, format, and open a PR. - *Check (code):* `CONTRIBUTING.md` names the build, test and format commands and the PR step. - *Reference:* Editora `CONTRIBUTING.md`. - **REPO-07 · MUST.** `docs/` holds `architecture.md`, `conventions.md`, `testing.md`, `gotchas.md`, `release.md`, `building-and-packaging.md` and `decisions/` (ADRs). - *Check (code):* each of those paths exists under `docs/`. - *Reference:* Editora `docs/`. - **REPO-08 · MAY.** `TODO.md` holds the open list, kept in the same PR as the change. - *Check (code):* `TODO.md` exists at the root. - *Reference:* Editora `TODO.md`. - **REPO-09 · MUST.** `.github/ISSUE_TEMPLATE/bug_report.yml` is an issue form whose field ids (`environment`, `report`) the in-app Report a Problem fills. - *Check (code):* the form has fields with `id: environment` and `id: report`. - *Reference:* Editora `.github/ISSUE_TEMPLATE/bug_report.yml`. - **REPO-10 · MUST.** `branding/` holds the source SVG of the icon. The PNG, ICNS and ICO generated from it sit beside it or in `packaging/`. - *Check (code):* `branding/` has an `.svg`; the `jpackage` icon paths in `pom.xml` point at the generated files. - *Reference:* Editora `branding/editora-icon.svg`, with `editora.png`, `.icns` and `.ico` beside it; the template keeps them in `packaging/icons/`. ## Documentation (DOCS) https://pauta-project.dev/2.0.0/documentation/: User docs on the app's website, developer docs in docs/, and the Help menu that opens them. Every app documents itself, and the docs change in the same PR as the code. ### User documentation - **DOCS-01 · MUST.** Every app has user documentation: a *Getting started* page (install, first launch, the first thing to do), one page per feature area, the keyboard reference, the Settings, and an FAQ. It is written for the person using the app, in their words, with screenshots from the real window. The README's 200 lines are not it. - *Check (code):* the website repository's `src/content/docs/` has a getting-started page, a keymaps page, a settings or configuration page, an FAQ and a page per feature area. - *Reference:* editora-website `src/content/docs/` (43 pages in nine categories, from *Getting started* to *Help*); torrenta-website (19), termina-website (16), mirada-website (11). - **DOCS-02 · MUST.** The user docs live on the app's website, under `/docs/`, in the app's `-website` repository, beside the feature pages, the screenshots, the news posts and the blog. Each docs page is a Markdown file whose frontmatter gives its `category` and `order`; the sidebar, the sitemap and the RSS feed follow. The app's repository never carries a second copy. - *Check (code):* every file in the website's `src/content/docs/` has `category` and `order` in its frontmatter; the app's `docs/` holds no user guide. - *Reference:* editora-website `README.md` (*Content*); Editora's `AGENTS.md`: "User-facing feature documentation goes to the separate website repository". - **DOCS-03 · SHOULD.** Deep links from the app open the running version's docs. Pages live under `/docs/v-/…`; bare `/docs` and every unversioned slug redirect to the current version, so a link in a page never carries a version and a bump just regenerates `src/lib/version.ts`. The app builds the base from its own version with `-SNAPSHOT` dropped, so a development build points at the release it is working toward instead of a path that would always 404. - *Why:* a release that pointed at another release's docs would claim what is not true ([*Never claim what is not true*](https://pauta-project.dev/2.0.0/principles/#for-the-people-using-the-apps)), so this becomes a must the day the app links to a specific page. - *Check (code):* the app's docs URL is `/docs/v-` plus its version without `-SNAPSHOT`; the site's `astro.config.mjs` serves `/docs/v-/` and redirects the unversioned paths. - *Reference:* Editora `AppInfo.docsUrl()`, `releaseVersion()`; editora-website `astro.config.mjs`, `README.md` (*Versioned docs*). The other three sites carry a comment to port these routes when their app first deep-links. - **DOCS-04 · SHOULD.** Docs are generated where the app is the source. The Commands and Keybindings pages are generated from the app's command registrations, `messages.properties` and keymaps; the Roadmap and What's new from `TODO.md` and `CHANGELOG.md`; the version from `pom.xml`. The output is committed, so the site builds without the app checked out. A check fails the site when a docs page quotes a command id that does not exist or a chord that is bound to a different command. - *Why:* one fact, one source ([*One source of truth for each fact*](https://pauta-project.dev/2.0.0/principles/#for-the-people-building-them)). - *Check (code):* the website's `scripts/` holds the generators, their output under `src/lib/` is committed, and `npm run check:docs` runs the id and chord check. - *Reference:* editora-website `scripts/GenCommands.java` (every `Command.of` in Editora's `com.editora.ui`, `MainController` holding most), `GenRoadmap.java`, `GenFeatures.java`; `scripts/check-doc-commands.mjs` (`npm run check:docs`). - **DOCS-05 · MUST.** Release notes are written for users. Each `CHANGELOG.md` entry opens with a bold one-line summary ([Repository documents](https://pauta-project.dev/2.0.0/repository/)); the GitHub release carries the section, the Welcome page's *What's New* opens this build's release, and the website's What's new is generated from the same file. - *Check (code):* the Welcome page's *What's New* opens `AppInfo.releaseNotesUrl()`; the website's What's new is generated from `CHANGELOG.md`. - *Reference:* Editora `AppInfo.releaseNotesUrl()`, `WelcomePane` (`welcome.whatsNew`); editora-website `GenRoadmap.java`. ### Reachable from the app - **DOCS-06 · MUST.** **Help → Documentation** opens the user docs in the browser. It is a command (`help.documentation`), so it is in the palette, bindable and in the menu through the registry like every other row; it is the first row of the Help menu after the Command Palette, and the Welcome page's Help row repeats it. - *Check (code):* `help.documentation` is registered, follows `palette.show` in the Help `MenuSpec`, and the Welcome page's Help row runs it through the registry. - *Reference:* Editora `WindowCommandRegistrar` (`help.documentation` → `MainController.openDocumentation()`), `MenuBarModel` (`menubar.help`), `WelcomePane` (`welcome.documentation`). - **DOCS-07 · SHOULD.** The Help menu runs in this order: Command Palette · Documentation · Check for Updates · Message Log · Debug Log · Report a Problem · About. Simple mode keeps Command Palette, Documentation and About. An app without a feature drops its row; nothing moves. - *Check (code):* both `menubar.help` menu specs list those command ids in that order. - *Reference:* Editora `MenuBarModel`, both `MenuSpec("menubar.help", …)`. - **DOCS-08 · SHOULD.** Help has a keyboard reference: a searchable window of every key, grouped as the menus are, or the keybinding editor. - *Check (by hand):* open it from Help, search for a command, and find its key. - *Reference:* Termina's and Mirada's `ShortcutsWindow`; Editora's keybinding editor ([Keyboard first](https://pauta-project.dev/2.0.0/keyboard/)). - **DOCS-09 · MUST.** Every command has a one-line description (`command..desc`), shown under the title in the palette. It is the in-app documentation of the command. - *Check (test):* the parity test fails when a `command.` title has no `.desc`. - *Reference:* Editora `messages.properties`, `MessagesTest.everyCommandTitleHasAMatchingDescription` ([Code quality gates](https://pauta-project.dev/2.0.0/quality/)). - **DOCS-10 · MAY.** The palette opens per-command help. With a command highlighted, `C-h` opens its page, `/docs/v-/commands/`; where the keymap binds `C-h`, the first free of `F1` and `Shift+F1` does. Search Everywhere shares the URL builder so the two pickers can never disagree. - *Check (code):* the palette and Search Everywhere both build the URL with `CommandPalette.docsUrl`. - *Reference:* Editora `CommandPalette.docsUrl`, `setDocsOpener`; `PickerKeys.freeChord`. - **DOCS-11 · MAY.** Each page of the Settings window has a *Help for <page>* link to its docs page, from one map of page to slug. - *Check (code):* one map from Settings page to docs slug feeds every page's help link. - *Reference:* Editora `SettingsWindow`, `SettingsFrameBits.helpUrl`, `settings.help`. ### Developer documentation - **DOCS-12 · MUST.** `docs/` has an index. `docs/README.md` says who the folder is for (contributors; user docs live on the website), states that the code wins when the two disagree, and lists every guide with one line. The set is the one [Repository documents](https://pauta-project.dev/2.0.0/repository/) names: `architecture.md`, `conventions.md`, `testing.md`, `gotchas.md`, `release.md`, `building-and-packaging.md` and `decisions/`. - *Check (code):* `docs/README.md` exists, says those two things, and links each guide in `docs/`. - *Reference:* Editora's `docs/README.md`; the template's `docs/`. - **DOCS-13 · SHOULD.** Every choice a newcomer would question has a decision record: a fork, a rejected dependency, a storage format, an escape hatch. It is one numbered Markdown file, `docs/decisions/NNNN-slug.md`, with the context, the decision and what it costs. - *Check (code):* `docs/decisions/` holds `NNNN-slug.md` files, each with context, decision and consequences. - *Reference:* Editora's `docs/decisions/` (18 records, from `0001-richtextfx-fork.md`). - **DOCS-14 · MUST.** Three files have three jobs. `AGENTS.md` is the operational guide, kept short (commands, worktree-per-task, the change checklist). `CONTRIBUTING.md` is the short version for a person, pointing into `docs/`. `docs/` holds the durable explanations. Exhaustive history goes to `docs/reference/`, not into any of the three. - *Check (code):* `AGENTS.md` and `CONTRIBUTING.md` link into `docs/`; long catalogs sit under `docs/reference/`. - *Reference:* Editora's `AGENTS.md` (*Documentation map*), `CONTRIBUTING.md`, `docs/reference/README.md`. - **DOCS-15 · SHOULD.** Javadoc sits on its member: a doc comment above another doc comment documents nothing. Comments say why, not what. - *Check (test):* a test fails the build on a Javadoc comment followed by another. - *Reference:* Editora `StackedJavadocTest`. ### Kept in step - **DOCS-16 · MUST.** Docs change in the same PR. A change that affects behavior updates `CHANGELOG.md`, `TODO.md`, the contributor guides it touches and the website's user docs in the same change, never as a follow-up. A reviewer treats a feature PR with no docs change as incomplete. - *Check (code):* `docs/conventions.md`, `CONTRIBUTING.md` and `AGENTS.md` state the rule; in review, a feature PR's diff touches `CHANGELOG.md`. - *Reference:* Editora `docs/conventions.md#docs-in-the-same-pr`, `CONTRIBUTING.md` (step 4), `AGENTS.md`. - **DOCS-17 · MUST.** When documentation and code disagree, the code wins, and the documentation is fixed in the same change. The same rule this guide applies to itself. - *Check (code):* `AGENTS.md` and `docs/README.md` say so. - *Reference:* Editora's `AGENTS.md`, `docs/README.md`. - **DOCS-18 · SHOULD.** Screenshots are retaken, not described. The capture hook renders the real window at 2× after any UI change, for the README (its hero in light and dark), the website and bug reports. - *Why:* a stale screenshot claims what is not true. - *Check (code):* the app has a capture hook or a headless harness that writes the real window to a PNG. - *Reference:* `DevCapture` ([Shared features](https://pauta-project.dev/2.0.0/family/shared-features/)); Editora's headless harness. - **DOCS-19 · MUST.** The README defers. It is about 200 lines: pitch, hero, highlights, install, build, command line, config folder, license, and links into the website's docs. It carries no feature catalog, so it changes only when those facts do. - *Check (code):* `README.md` is near 200 lines and links to the website's docs instead of listing every feature. - *Reference:* [Repository documents](https://pauta-project.dev/2.0.0/repository/); Editora `docs/conventions.md#docs-in-the-same-pr`. ## Code quality gates (QUAL) https://pauta-project.dev/2.0.0/quality/: NullAway, coverage floors and the guard tests that pay for themselves across the family. - **QUAL-01 · MUST.** NullAway is an error, not a warning. A new package starts with its own `package-info.java` carrying `@NullMarked`. - *Check (code):* the compiler arguments say `-Xep:NullAway:ERROR`; every source package has a `package-info.java` with `@NullMarked`. - *Reference:* Editora `pom.xml`, `docs/conventions.md` (*Null annotations*). - **QUAL-02 · SHOULD.** A NullAway report is fixed, not suppressed: put `@Nullable` on what may be null. - *Check (code):* `grep -rn '@SuppressWarnings("NullAway")' src/main` finds nothing. - *Reference:* Editora; one suppression is left, in `recovery/RecoveryCodec.java`. - **QUAL-03 · SHOULD.** Coverage floors are a regression net, not a target. Beyond the build-wide floor of 0.90 lines and methods, each package of 300+ lines gets its own floor about three points below its measured level; when a package's coverage rises, its floor is ratcheted up. - *Check (code):* the `jacoco-check` rules in `pom.xml` carry a `PACKAGE` line floor for each large package. - *Reference:* Editora `pom.xml` `jacoco-check`. - **QUAL-04 · SHOULD.** When a guide quotes the coverage floors, a test fails when the quoted table and the pom disagree. - *Check (test):* a build test reads the `jacoco-check` rules from `pom.xml` and compares them with the guide's table. - *Reference:* Editora `BuildHygieneTest.theCoverageFloorsQuotedInTheTestingGuideAreTheOnesTheBuildEnforces`, `docs/testing.md`. - **QUAL-05 · MUST.** Extract the decision, then test it ([principle 12](https://pauta-project.dev/2.0.0/principles/#for-the-people-building-them)). Prefer a pure decision helper plus unit tests; use the headless FX harness only when controller or toolkit behavior is the point. - *Check (code):* enablement, visibility and navigation rules sit in classes that import no `javafx` type, each with a unit test not tagged `fx`. - *Reference:* Editora `docs/testing.md` (*Prefer pure logic*): `ui/Chrome`, `editops/TextNav`, `config/PathKeys`, each with a plain unit test. - **QUAL-06 · MUST.** FX tests are tagged `@Tag("fx")`, so the pure suite runs alone with `-DexcludedGroups=fx`. - *Check (code):* every test class that boots the toolkit (`FxTestSupport`, `FxToolkit`) carries `@Tag("fx")`. - *Reference:* Editora `docs/testing.md`. Editora does not hold it fully yet: about twenty `*FxTest` classes, most of them `ProjectMap*FxTest`, carry no tag. - **QUAL-07 · SHOULD.** Tests do not sleep. Workers and FX callbacks are owned by a scope (`AsyncTestScope`), and tests wait on latches. - *Check (code):* `grep -rn 'Thread.sleep' src/test` finds nothing. - *Reference:* Editora `AsyncTestScope`, `docs/testing.md`. Many older Editora tests still poll with `Thread.sleep`. - **QUAL-08 · SHOULD.** A test window writes only inside its temp folders, never in the real home directory. - *Check (test):* the command sweep checks the home directory after running every command. - *Reference:* Editora `CommandSweepFxTest.leftInTheHomeDirectory`. - **QUAL-09 · MUST.** UI work is verified in the running app ([principle 13](https://pauta-project.dev/2.0.0/principles/#for-the-people-building-them)): a capture hook or headless screenshot of the real window, with real key and mouse events, before a UI change is called done. - *Check (code):* the app has a capture hook (`DevCapture`) or a headless fixture that builds the real window. - *Reference:* Editora `FxWindowFixture` (the real `MainController` window, headless); Torrenta and Termina `DevCapture.java`. - **QUAL-10 · SHOULD.** A guard that cannot fail is decoration. When you add a drift or parity test, break the thing it guards once and watch it fail. - *Check (by hand):* break what the new test guards, run it, and see it fail. - *Reference:* Modula's `DependenciesTest`. - **QUAL-11 · SHOULD.** A command sweep runs every registered command in a real headless window. - *Check (test):* one FX test iterates the registry and runs each command. - *Reference:* Editora `CommandSweepFxTest`. - **QUAL-12 · MUST.** A message parity test holds that every locale has every key and every `command.` has a `.desc`. - *Check (test):* the test fails on a key missing from a locale or a command title without `.desc`. - *Reference:* Editora `MessagesTest`. - **QUAL-13 · SHOULD.** A settings round trip shows that every switch, number and choice survives a restart. - *Check (test):* one FX test sets every control, reloads the settings and reads each back. - *Reference:* Editora `SettingsRoundTripFxTest`. - **QUAL-14 · SHOULD.** A contrast test holds that text tokens keep their ratios in every theme. - *Check (test):* a pure test reads the stylesheets and does the WCAG arithmetic. - *Reference:* Editora `StyleContrastTest`. - **QUAL-15 · SHOULD.** A release supply-chain test keeps the signing and attestation steps where they are. - *Check (test):* a test reads the workflows and fails when a signing, notarization or attestation step moves or goes. - *Reference:* Editora `ReleaseSupplyChainTest`. ## Performance (PERF) https://pauta-project.dev/2.0.0/performance/: Keep the JavaFX application thread free, coalesce work, bound memory, and measure: the rules that keep every app responsive. ### The UI thread - **PERF-01 · MUST.** Never block the JavaFX application thread. No file or network I/O, no process start or wait, no parsing, searching, hashing or JSON of any size on it, and no `Thread.sleep`, `Future.get()`, `join()` or `Process.waitFor()` there. - *Check (code):* event handlers, listeners and `Platform.runLater` bodies call no `Files.*`, `HttpClient.send`, `ProcessBuilder.start`, `waitFor`, `Future.get`, `join` or `Thread.sleep`; that work runs on an executor or a virtual thread. - *Reference:* Editora `docs/performance.md` §1. - **PERF-02 · MUST.** Touch the scene graph only on the FX thread. Background work hands its result back with `Platform.runLater`; nothing else creates, changes or reads live nodes. - *Check (code):* every executor task or thread body that ends in UI work wraps that work in `Platform.runLater`. - *Reference:* every Editora service, for example `git/GitService.java`. - **PERF-03 · MUST.** A background result is applied under a generation guard, so an answer to an old request never overwrites a newer one. - *Check (code):* each request takes a generation (`AtomicLong.incrementAndGet`) or goes through `LatestOnly`, and its result is applied only while that generation is still current, checked again inside the `runLater`. - *Reference:* Editora `git/GitService.java`, `search/SearchService.java`, `ui/LatestOnly.java` (`LatestOnlyTest`). - **PERF-04 · SHOULD.** Every thread is named and is a daemon. - *Why:* a thread dump then says what is running, and a stray worker never keeps the app alive after its last window closes. - *Check (code):* every `Executors.new…` and `new Thread` gets a name and `setDaemon(true)`, through a thread factory such as `daemon("my-feature")`; virtual threads are daemons already. - *Reference:* Editora `daemon("my-feature")` in the shape below, `terminal/TerminalExecutors.java`. - **PERF-05 · MUST.** Blocking work stays off the common `ForkJoinPool`, and a `Process` subclass overrides `onExit()`. - *Why:* the common pool has one worker fewer than the machine has cores, so a few blocked waits (`CompletableFuture.supplyAsync` of a `waitFor`) starve every other user of it. - *Check (code):* no `supplyAsync` or `runAsync` without an executor wraps a blocking call, and every class that extends `Process` overrides `onExit()`. - *Reference:* Editora `process/ExitWatch.java`, `docs/gotchas.md`. Editora's `DapManager.reportJavaExit` still waits up to 3 s for an exit code in a `supplyAsync` on the common pool. ### Hot paths - **PERF-06 · MUST.** Redraws are coalesced to at most one per pulse with a `pending` flag, and text-driven work waits for typing to pause. - *Check (code):* a redraw request sets a `pending` flag and schedules one pass; listeners on text go through a debounce. - *Reference:* Editora `ui/FxThrottle.java`. - **PERF-07 · MUST.** Streams (process output, logs, progress) reach the FX thread in batches at least 16 ms apart, never one `runLater` per line. - *Check (code):* a reader thread appends to a buffer that the FX thread drains, with a minimum interval between drains. - *Reference:* Editora `process/OutputPump.java` (`MIN_DRAIN_INTERVAL_MILLIS`), `ui/ConsoleAppender.java`. - **PERF-08 · MUST.** Work only on what is visible and only on what changed: no O(document) or O(list) work per keystroke, scroll or tick. Anything that can grow is shown in a virtualized control (`ListView`, `TableView`, a fixed cell size). - *Check (code):* a listener on text, scroll or a timer re-processes the edited range or the visible rows, never the whole document or list; growing lists are `ListView` or `TableView`, not a `VBox` of nodes. - *Reference:* Editora `editor/highlight/HighlightPass.java`, `editor/minimap/MinimapRows.java`. - **PERF-09 · SHOULD.** A hot path allocates little: it reuses buffers and arrays, and caches data a repaint only reads. - *Check (code):* the per-frame and per-keystroke code allocates no new arrays or images when the size has not changed. - *Reference:* Editora `editor/minimap/Minimap.java` (the snapshot image reused at the same size), `MinimapRows.java`. - **PERF-10 · SHOULD.** CSS stays cheap: no `applyCss()` on a large subtree, stable style classes, and spans of the same style merged before they are applied. - *Check (code):* `applyCss()` is called only on small nodes; style classes are not toggled per keystroke. - *Reference:* Editora `SpanMerger` in `editor/highlight/TextMateHighlighter.java`, `docs/gotchas.md`. ### Memory and size - **PERF-11 · MUST.** Everything that grows is bounded: logs, histories, consoles, caches, undo. The newest is kept, with a note of what was cut. - *Check (test):* each such store has a test that fills it past its cap and finds the oldest dropped. - *Reference:* Editora `ui/MessageLog.java` (200, `MessageLogTest`), `ui/DebugLog.java` (`DebugLogTest`), `test/OutputCap.java`. - **PERF-12 · MUST.** Large inputs are guarded by size and shape before they load: expensive features turn off past one threshold, the input opens read-only or capped past another, and what will not fit the free heap is refused. - *Check (code):* the loader compares the size against named thresholds before reading the content. - *Reference:* Editora `EditorBuffer.LARGE_FILE_BYTES` (5 MB) and `HUGE_FILE_BYTES` (50 MB), `ui/LoadHeapGuard.java` (`LoadHeapGuardTest`). - **PERF-13 · MUST.** A closed window releases what it held: listeners, timers, executors, file watchers, native resources. - *Check (test):* a test opens and closes windows and checks nothing is left running. - *Reference:* Editora `FxWindowFixture.dispose` (`FxWindowFixtureLifecycleFxTest`), `ClosedLspManagers`. ### Start-up - **PERF-14 · MUST.** The first frame comes first: only what the first window shows is built before it; tool windows, panels and pages build on first open. - *Check (test):* a test opens a window and finds no closed tool window's panel built before the first paint. - *Reference:* Editora's lazy `ToolWindow` suppliers, `LazyToolWindowsFxTest`. - **PERF-15 · MUST.** What nobody waits for starts after the first frame has painted: the update check, extra fonts, indexes and caches. - *Check (test):* a test finds the deferred work not started before the first paint. - *Reference:* Editora `ui/UpdateCheckScheduler.java`, `Fonts.loadRemainingAfterNextPaint` (`UpdateCheckSchedulerTest`, `FontsDeferredLoadFxTest`, `StartupDeferralFxTest`). - **PERF-16 · SHOULD.** Config is read off the FX thread, before the toolkit needs it. - *Check (code):* `main` starts the config read on its own thread before `launch`. - *Reference:* Editora's `config-prefetch` thread in `App.java`. - **PERF-17 · SHOULD.** The app ships precompiled stylesheets (`.bss`) and an AOT cache trained on a real session. - *Check (code):* the build converts the `.css` files to `.bss` and runs a training launch for the AOT cache. - *Reference:* Editora `scripts/css2bss.java`, `scripts/aot_build.java`; Termina's and Mirada's `scripts/aot-train.sh`. ### Measure, don't guess - **PERF-18 · SHOULD.** Every change on a hot path says what it costs in its pull request: added FX-thread work, allocation per keystroke or scroll, extra layout passes, memory. "Negligible" is an answer; no answer is not. - *Check (by hand):* read the app's recent pull requests that touch a hot path. - *Reference:* Editora `docs/performance.md` (its opening paragraph). - **PERF-19 · SHOULD.** Start-up is measured by a script that takes the median of several cold launches, and by phase marks in the app. - *Check (code):* the repository has the script, and `main` and the first paint record phase marks. - *Reference:* `scripts/measure-startup.sh` in Editora and Mirada; Editora `perf/Startup.java`. - **PERF-20 · SHOULD.** The app can sample its FX thread when something stalls. - *Check (code):* an environment variable or property turns on a sampler of the FX thread's stack. - *Reference:* Editora `perf/Startup.java` (`EDITORA_PERF_SAMPLE=1`). - **PERF-21 · SHOULD.** Each hot path that once regressed keeps a headless test. - *Check (test):* the fix for a hot-path regression adds a headless test that fails on the old code. - *Reference:* Editora `MinimapDeferredRenderFxTest`. - **PERF-22 · SHOULD.** A suspected regression gets a number before and after, from temporary `System.nanoTime` instrumentation if nothing better exists. - *Check (by hand):* the pull request that fixes it states both numbers. - *Reference:* Editora `docs/performance.md`. ## Keyboard first (KBD) https://pauta-project.dev/2.0.0/keyboard/: Commands, the Command Palette, keymaps, focus and accessibility. ### Commands - **KBD-01 · MUST.** Every user-facing action is a `Command` (id, title, runnable) registered in one `CommandRegistry`. - *Check (code):* menu items, toolbar buttons, palette rows and key bindings run a command id through the registry; no control's handler does work no command can reach. - *Reference:* Editora `command/Command.java`, `command/CommandRegistry.java`. - **KBD-02 · SHOULD.** Command ids are dotted and grouped by area: `file.open`, `view.toggleStatusBar`, `help.reportProblem`. - *Check (code):* every registered id matches `.`. - *Reference:* Editora `ui/MenuBarModel.java`. - **KBD-03 · MUST.** A command's title comes from `command.` and its palette description from `command..desc` in the message catalogs. - *Why:* a registered command is then localized and discoverable without extra work. - *Check (test):* a catalog parity test fails when a registered command has no `command.` or `command..desc` key. - *Reference:* Editora `i18n/messages.properties`, `MessagesTest`. - **KBD-04 · SHOULD.** A command that cannot run in the current context is shown grayed, with a tooltip that says why, not hidden. - *Check (code):* the palette and menus list a disabled command with a reason, rather than filtering it out. - *Reference:* Editora `ui/Chrome.java` (`paletteEnabled`, `disabledReason`). ### Command Palette - **KBD-05 · MUST.** The Command Palette opens with `M-x` in the Emacs keymap and `Ctrl+Shift+P` (`Cmd+Shift+P` on macOS) in the others. - *Check (code):* each bundled keymap binds that chord to the palette command. - *Reference:* Editora `keymaps/emacs.json` (`M-x`), `cua.json` and `vscode.json` (`C-S-p`), `cua.mac.json` (`Cmd-S-p`), all to `palette.show`. - **KBD-06 · SHOULD.** The palette matches fuzzily over title, id and description; a query that names a command's title outranks a fuzzy hit. Each row shows the command's binding in the active keymap. See the [Command Palette template](https://pauta-project.dev/2.0.0/templates/command-palette/). - *Check (test):* a ranking test puts the title match first. - *Reference:* Editora `ui/CommandPalette.java`, `search/FuzzyMatch.java`. - **KBD-07 · MUST.** The palette is an in-scene overlay in the window's root `StackPane`, not a `javafx.stage.Popup`. - *Why:* on Windows a Popup does not reliably take OS keyboard focus, and the whole app can stop receiving keystrokes. - *Check (code):* the palette and every picker add their node to the root `StackPane`; none creates a `Popup`. - *Reference:* Editora `ui/CommandPalette.java`. - **KBD-08 · SHOULD.** The same picker serves every other list choice: recent files, themes, keymaps, a setting's values. - *Check (code):* no second list-picker class or `ChoiceDialog` for those choices. - *Reference:* Editora `ui/QuickOpen.java`. ### Keymaps - **KBD-09 · MUST.** Emacs and CUA keymaps ship as JSON resources, CUA with a `.mac.json` variant where Cmd replaces Ctrl. - *Check (code):* `emacs.json`, `cua.json` and `cua.mac.json` are in the app's resources. - *Reference:* Editora `src/main/resources/com/editora/keymaps/`. - **KBD-10 · SHOULD.** IntelliJ, VS Code and Sublime keymaps ship the same way, each with its `.mac.json` variant. - *Check (code):* `intellij`, `vscode` and `sublime` `.json` and `.mac.json` files are in the resources. - *Reference:* Editora `src/main/resources/com/editora/keymaps/`. - **KBD-11 · MUST.** Keymaps are applied in layers: base keymap → user overrides → plugin keymaps → the user's own bindings again. An app without plugins has the first two. - *Why:* the user always has the last word, and a plugin can still use a chord the user freed. - *Check (code):* one place applies the layers in that order. - *Reference:* Editora `ui/KeymapLayers.java`. - **KBD-12 · SHOULD.** A keymap editor in Settings lists every command with its chord, is searchable, and warns of conflicts. - *Check (by hand):* open Settings → Keymap, search, and bind a chord that is taken. - *Reference:* Editora `ui/SettingsKeymapsPage.java`; conflicts from `KeybindingEdits.takenDefaults`. - **KBD-13 · SHOULD.** No command's chord is written into translated text. Every label shows the binding from the active keymap. Fixed keys of a control (Enter, Tab, Esc, arrows) and keys meant for another program may be written. - *Check (code):* no message catalog value names a command's chord (`Ctrl+`, `Cmd+`, `C-x`, `M-x`); chords are rendered by one formatter. - *Reference:* Editora `command/ChordFormat.java`, the one place a binding is rendered. Editora's `command.edit.universalArgument` title still carries `C-u`. - **KBD-14 · SHOULD.** A multi-key prefix (`C-x …`) shows a which-key style hint listing the possible next keys. - *Check (by hand):* press `C-x` in the Emacs keymap and wait. - *Reference:* no app lists the next keys yet. Editora echoes only the pending prefix (`C-x -`) in the status bar (`command/KeyDispatcher.java`). ### Focus and accessibility - **KBD-15 · SHOULD.** Every interactive control is reachable with Tab and operable with Space or Enter. Toolbar buttons are the exception: they stay out of the Tab order (see [Toolbars and tooltips](https://pauta-project.dev/2.0.0/toolbars-and-tooltips/)). - *Check (by hand):* Tab through every window and dialog without the mouse. - *Reference:* Editora; `FocusRingFxTest` holds that every control family draws the focus ring when Tab reaches it. - **KBD-16 · SHOULD.** The keyboard focus ring is one layer of `:focus-visible` rules at the end of `app.css`. - *Check (test):* an FX test tabs to each control family and asserts the ring. - *Reference:* Editora `app.css` (*Keyboard focus*, one layer for every control), `FocusRingFxTest`. - **KBD-17 · MUST.** Icon-only buttons are built by one helper that sets both the tooltip and the accessible text. - *Check (code):* no icon-only `Button` is built outside the helper. - *Reference:* Editora `ui/Icons.java` (`Icons.button`). Editora's main toolbar doesn't yet: `WindowToolbar.setupButton` and `ToolbarCoordinator.buildExtraButton` set the tooltip but no accessible text. - **KBD-18 · SHOULD.** On/off rows use a keyboard-operable switch with the `TOGGLE_BUTTON` role. - *Why:* a bare AtlantaFX `ToggleSwitch` is mouse-only. - *Check (code):* no `new ToggleSwitch` outside the switch class. - *Reference:* Editora `ui/SettingSwitch.java`. - **KBD-19 · SHOULD.** Readable text uses `-color-fg-muted` or stronger; `-color-fg-subtle` (about 3:1) is for disabled or decorative text only. - *Check (test):* a pure contrast test over the stylesheets. - *Reference:* Editora `StyleContrastTest`. - **KBD-20 · SHOULD.** Rows wrap instead of truncating to "…". - *Check (by hand):* run the app in German at 1024 px wide; no test catches a cut row. - *Reference:* Editora `messages_de.properties`. ## Window shell (WIN) https://pauta-project.dev/2.0.0/window-shell/: Status bar, themes, title bar, dialogs, Welcome, About, window state and zoom. - **WIN-01 · MUST.** A status bar is always present (it can be toggled). Its left side is the *echo area*: one line of feedback for the last action, errors in red and warnings in amber. Clicking it opens the Message Log. - *Check (code):* the echo label switches between an error and a warning style class, and its click handler runs the Message Log command. - *Reference:* Editora `ui/StatusBar.java` (`status-echo-error`, `status-echo-warn`; a click runs `view.messageLog`) and the [Message Log template](https://pauta-project.dev/2.0.0/templates/message-log/). - **WIN-02 · MUST.** Light and dark AtlantaFX themes and a "follow the system" choice, switchable at run time without a restart. Semantic colors: amber is not durable yet (unsaved, read-only), red is broken, green is verified or added. See [Icons and color](https://pauta-project.dev/2.0.0/icons-and-color/). - *Check (code):* one place applies the app theme to every open window, and the theme list has a system choice that follows the OS color scheme as it changes. - *Reference:* Editora `ui/Themes.java` (`applyAppTheme`) switches at run time and `ui/WindowColorScheme.java` tells every window's frame which scheme it is in; Mirada `ui/Theme.java` (`ThemeChoice.SYSTEM`) follows the system. Editora has no system choice yet. - **WIN-03 · SHOULD.** The title bar uses JavaFX 27's `HeaderBar` with `StageStyle.EXTENDED` to carry the menu or tabs, with a decorated-window fallback, and `useSystemMenuBar` on macOS. - *Check (code):* the main stage is created `StageStyle.EXTENDED` with a `HeaderBar`, a setting falls back to a decorated window, and the menu bar sets `useSystemMenuBar` on macOS. - *Reference:* Editora `ui/ExtendedWindow.java`, `ui/MainMenuBar.java`. - **WIN-04 · SHOULD.** Native dialogs go through one helper that attaches the app stylesheet and the UI font. - *Why:* a dialog is its own scene and inherits neither. - *Check (code):* every `Alert` and `Dialog` the app builds passes through the helper. - *Reference:* Editora `ui/Dialogs.java` (`Dialogs.styled`). - **WIN-05 · MUST.** A destructive action asks first, and says what it does. Removing, deleting, discarding or overwriting something the user made goes through one confirm helper: the question names the thing ("Remove 3 torrents?"), the confirm button names the action (Remove, Discard, Overwrite), never OK or Yes, and Escape cancels. Where the action can be undone instead, the undo is better than the question. See the [Confirm dialog template](https://pauta-project.dev/2.0.0/templates/confirm-dialog/). - *Check (code):* each destructive action calls the one confirm helper before it changes anything, or records an undo. - *Reference:* Torrenta `RemoveConfirm` and `UndoStack`; Editora's save decisions (`ui/CloseCoordinator.java`); Termina's and Editora's reopen-closed-tab. - **WIN-06 · SHOULD.** A Welcome page when there is nothing to restore: Start actions (which run commands), Recent items, a Customize block (keymap and theme) and Help links. See the [Welcome template](https://pauta-project.dev/2.0.0/templates/welcome/). - *Check (by hand):* start the app with no session to restore. - *Reference:* Editora `ui/WelcomePane.java`. - **WIN-07 · MUST.** About shows the version, the build, the Pauta edition the app implements, the runtime (Java and JavaFX versions), the license, links, and the result of the last update check. See the [About template](https://pauta-project.dev/2.0.0/templates/about/). - *Check (code):* the About window reads the version, build and edition from `AppInfo` and shows the update checker's last answer. - *Reference:* Editora `ui/AboutDialog.java`. No app names its Pauta edition yet. - **WIN-08 · SHOULD.** Window size, position, maximized state and open items are restored on the next launch; `--no-session` skips the restore. - *Check (test):* a round-trip test of the saved workspace state, and a test that `--no-session` is honored. - *Reference:* Editora `config/WorkspaceState.java` (`windowX` … `windowMaximized`), `ui/WindowSessionCoordinator.java`, `App.noSessionFlag`; tests `WorkspaceStateV29Test`, `AppArgsTest`, `NoSessionStartupFxTest`. - **WIN-09 · SHOULD.** UI and content zoom from the keyboard (`Ctrl/Cmd +`, `-`, `0`), kept across launches. - *Check (code):* zoom in, out and reset are commands bound in every keymap, and the zoom level is a saved setting. - *Reference:* Editora zooms content only: `view.textZoomIn`, `view.textZoomOut` and `view.textZoomReset`, kept in `Settings.fontZoom`. - **WIN-10 · MAY.** Modes: Zen (no chrome), Simple (fewer menus for new users), Expert. - *Check (code):* each mode is a command, and one truth table decides which chrome each mode shows. - *Reference:* Editora `ui/WindowChromeCoordinator.java` (`toggleZen`, `applySimpleMode`) over the truth table in `ui/Chrome.java`. ## Icons and color (ICON) https://pauta-project.dev/2.0.0/icons-and-color/: Inter and JetBrains Mono, the Caret & Ink palette, state colors that mean one thing, themes, and the two icon families. ### Type - **ICON-01 · MUST.** Inter is attached by a *scene* stylesheet on every window's scene, dialogs, popups and tooltips included, not by a rule in the app stylesheet. - *Why:* dialogs, the Settings window, the palette, context menus and tooltips each live in a scene of their own that does not share `app.css`, and a scene sheet is re-applied cleanly when the theme switches at run time (`setUserAgentStylesheet`). AtlantaFX neither bundles nor names Inter, and JavaFX does not fall through a font-family list, so without the sheet the whole interface renders in the platform's "System" face. - *Check (code):* a listener on `Window.getWindows()` adds `ui-font.css` to each window's scene, and to a new scene when the window's scene changes; no `.root` rule in `app.css` sets `-fx-font-family`. - *Reference:* Editora `App.installUiFont`, `styles/ui-font.css`. Termina and Torrenta carry the same sheet. - **ICON-02 · MUST.** The app bundles Inter's four faces and registers them before any CSS is applied; it never maps the platform's own UI font. - *Why:* an earlier macOS-only sheet used San Francisco, which JavaFX faux-bolds; Inter has a real bold on every platform. - *Check (code):* `Inter-Regular`, `Inter-Bold`, `Inter-Italic` and `Inter-BoldItalic` `.ttf` are under the app's `fonts/inter/` with their `OFL.txt`, and `Font.loadFont` runs on them before the first window is shown. - *Reference:* Editora `src/main/resources/com/editora/fonts/inter/`, `ui/Fonts.java` (`loadForFirstPaint`, called from `App`). Termina and Torrenta bundle the same four faces. - **ICON-03 · SHOULD.** A line of UI text is `-color-fg-default` and secondary text `-color-fg-muted`; `-color-fg-subtle` (about 3:1) is for disabled or decorative text only. - *Check (test):* a test lists the selectors of text that must be read and fails when one uses `-color-fg-subtle`. - *Reference:* Editora `StyleContrastTest.textThatMustBeReadUsesTheMutedRoleNotSubtle`. ### The palette: Caret & Ink - **ICON-04 · SHOULD.** A theme file follows the vendored AtlantaFX community themes: a `.root` block of `-color-*` tokens, then component rules that reference only those tokens. - *Check (code):* the file's first rule is `.root`, and no rule after it holds a `#` hex. - *Reference:* Editora `styles/atlantafx-themes/editora-light.css`, `editora-dark.css`. - **ICON-05 · SHOULD.** A new app ships the Caret & Ink pair as its default theme, with `editora-light.css` and `editora-dark.css` copied unchanged into its own `styles/`. - *Why:* the palette is the family's, not the editor's. - *Check (code):* the app's two files are identical to Editora's. - *Reference:* Torrenta and Termina `styles/`. Both copies of `editora-dark.css` match Editora's; both copies of `editora-light.css` still have the earlier `-color-accent-fg`, `-color-warning-fg` and `-color-success-fg`, which Editora has since darkened. - **ICON-06 · SHOULD.** Brace (`-state-key`) is a `ladder()` over `-color-bg-default` that picks a deep ink on a light ground and a lighter periwinkle the darker the ground gets, and reads at 4.5:1 or more on every bundled theme's default and subtle surfaces. - *Why:* Brace has no AtlantaFX role, so it has to be a literal. - *Check (test):* a contrast test resolves the ladder against every bundled theme's grounds. - *Reference:* Editora `app.css` (`.root`), `StyleContrastTest.theKeyboardPeriwinkleReadsOnEveryBundledAppTheme`. ### State colors - **ICON-07 · MUST.** Each state color is named once, as a `-state-*` token on `.root` that chains to one of the theme's roles (or a `ladder()` of its ground), and component rules use the token. - *Check (code):* the `-state-*` tokens are declared only in the `.root` block at the top of `app.css`, each chaining to a `-color-*` role or a `ladder()`. - *Reference:* Editora `styles/app.css` (`.root`). - **ICON-08 · MUST.** No fixed hex in a component rule. - *Why:* a hex suits one theme; the roles track every theme for free. - *Check (code):* outside the `.root` token block, `app.css` holds no `#` hex. A test fails a severity or debug color that is not a state token. - *Reference:* Editora `StyleContrastTest.severityAndDebugColoursComeFromTheStateTokens`. Editora doesn't yet pass the whole check: `.breakpoint-marker`, `.exec-arrow`, `.view-mode-bar`, `.recent-remove`, `.personal-note-tooltip-content`, the fold-gutter markers and the default editor and Markdown preview palettes in `app.css` still carry fixed hexes. - **ICON-09 · MUST.** Readable text uses `-color-fg-muted` or stronger, which is 4.5:1 on the default, subtle and overlay grounds in both flagship themes. - *Check (test):* a contrast test computes muted ink on each ground, and fails a readable selector set in `-color-fg-subtle`. - *Reference:* Editora `StyleContrastTest.textThatMustBeReadUsesTheMutedRoleNotSubtle`. - **ICON-10 · MUST.** Tinted text (`-color--fg`) reaches 4.5:1 on its own subtle fill and on both grounds. - *Check (test):* a contrast test computes each role's `-fg` on its `-subtle`, on `-color-bg-subtle` and on `-color-bg-default`, in both flagship themes. - *Reference:* Editora `StyleContrastTest.lightTintedTextReachesAaOnItsOwnGroundAndOnTheSubtleSurface`, `darkTintedTextStaysAa`. - **ICON-11 · MUST.** Ink on an emphasis fill is `-color-fg-emphasis`, never white. - *Why:* white on the dark accent is 1.68:1. - *Check (test):* a contrast test computes `-color-fg-emphasis` on each role's `-emphasis`, and the rules that paint on an emphasis fill use it. - *Reference:* Editora `StyleContrastTest.inkOnAnEmphasisFillIsTheThemesOnEmphasisColour`. - **ICON-12 · MUST.** One focus ring, `-focus-ring: -color-accent-emphasis`, drawn by the `:focus-visible` block at the end of `app.css`, at 3:1 or better on every surface (see [Keyboard first](https://pauta-project.dev/2.0.0/keyboard/)). - *Check (test):* a test reads `-focus-ring` from `.root` and computes it on the default, subtle, inset and overlay grounds. - *Reference:* Editora `app.css` (*Keyboard focus*), `StyleContrastTest.theFocusRingIsAtLeastThreeToOneOnEverySurface`. - **ICON-13 · SHOULD.** A brand hue the theme has no role for (periwinkle, olive, violet) is a `ladder()` of `-color-bg-default`, never a fixed pair. - *Why:* the old fixed light hexes read at 3.2:1 on Editora Dark. - *Check (test):* a contrast test resolves each ladder on every bundled theme's ground. - *Reference:* Editora `app.css` (`-state-olive`, `-state-violet`, `-state-key`), `StyleContrastTest.theGitOliveAndVioletFollowTheAppThemesGround`. - **ICON-14 · SHOULD.** A pure test reads the stylesheets and does the WCAG arithmetic. - *Why:* a contrast regression is invisible in a code diff. - *Check (code):* a test class reads the app's `.css` resources and computes contrast ratios without starting the toolkit. - *Reference:* Editora `StyleContrastTest`. Mirada's `AccentTest` checks that the accent reads as text on both grounds; Termina's `ThemeTest` keeps every chromatic color of its terminal schemes legible. ### Themes - **ICON-15 · MUST.** The app has light and dark themes and switches between them at run time, without a restart (see [Window shell](https://pauta-project.dev/2.0.0/window-shell/)). - *Check (code):* picking a theme calls `Application.setUserAgentStylesheet` in the running app. - *Reference:* Editora `ui/Themes.java` (`applyAppTheme`). - **ICON-16 · MUST.** A "follow the system" choice applies the light or dark theme to match the system's color scheme, and changes with it. - *Check (code):* the theme setting has a system value, and a listener on `Platform.getPreferences().colorSchemeProperty()` re-applies the theme. - *Reference:* Mirada `settings/Settings.java` (`ThemeChoice.SYSTEM`), `ui/Theme.java`. Editora doesn't yet: its theme picker lists named themes only. - **ICON-17 · MUST.** A theme name the app does not know falls back to the first-run default theme. - *Check (code):* the lookup from a saved name to a theme ends in the default, not an exception. - *Reference:* Editora `Themes.themeFor`, falling back to `Themes.DEFAULT` (Editora Light). - **ICON-18 · SHOULD.** Semantic colors never decorate: a theme may change the teal, the ground and the ink, but amber still means "not durable yet", red "broken" and green "verified". - *Check (code):* every rule that uses `-state-amber`, `-state-red` or `-state-green` marks one of the meanings in the State colors table. - *Reference:* Editora `app.css`. ### Icons - **ICON-19 · MUST.** A glyph node carries one family's style class, `icon-line` or `toolbar-icon`, never both. - *Why:* a line glyph is colored by its stroke, and any `X .toolbar-icon` fill rule (there are dozens) would paint its outline solid. A glyph that moves family moves its CSS with it. - *Check (test):* a test builds every line glyph and fails when one also carries `toolbar-icon`. - *Reference:* Editora `ui/Icons.java` (`line`, `of`), `MenuIconFamilyFxTest.aLineGlyphIsNeverAlsoTaggedAsAFilledOne`. - **ICON-20 · MUST.** The same action wears the same glyph wherever it is reached: Save is one floppy on the toolbar, in the File menu and in a tab's menu. - *Check (test):* a test compares the path data and style class of each action's glyph across the icon classes. - *Reference:* Editora `ui/MenuBarIcons.java` reuses `Icons`; `editor/MenuIcons.java` (the editor package may not depend on `ui`) copies each twin's family and path data verbatim, held by `MenuIconFamilyFxTest.everySharedActionUsesTheSameGlyphInBothIconSets`. - **ICON-21 · MUST.** An icon-only control has a name: it is built through `Icons.button` or `Icons.toolbarButton`, which set the tooltip and the accessible text together (see [Keyboard first](https://pauta-project.dev/2.0.0/keyboard/)). - *Check (code):* no icon-only `Button` is given a graphic outside those helpers without `Icons.name`. - *Reference:* Editora `ui/Icons.java`. Editora doesn't yet pass the check on its main toolbar: `WindowToolbar.setupButton` and `ToolbarCoordinator.buildExtraButton` set only the tooltip (see [Toolbars and tooltips](https://pauta-project.dev/2.0.0/toolbars-and-tooltips/)). - **ICON-22 · SHOULD.** No invented glyph. A row gets an icon only where an existing glyph genuinely depicts it, and the icon column stays reserved so a menu with a mix stays aligned (see [Menus](https://pauta-project.dev/2.0.0/menus/)). - *Why:* a picture that does not mean the thing beside it has to be read and then discounted. - *Check (test):* a test holds that a command with no fitting glyph maps to none. - *Reference:* Editora `ui/MenuBarIcons.java`, `MenuBarIconsTest.aCommandWithNoFittingGlyphGetsNoneRatherThanAnInventedOne`. - **ICON-23 · SHOULD.** A file's icon comes from a pure function from file name to icon key, unit-tested without the toolkit, and any type it does not know gets the generic document glyph, so a new type never regresses the look. - *Check (test):* a unit test resolves names to keys, an unknown one to the generic key. - *Reference:* Editora `ui/FileIcons.java`: `iconKeyFor(name)` resolves the key, `forFileName` turns it into a node; brand logos from Simple Icons, category glyphs (image, archive, PDF, table, lock, JSON, settings) from Material. `FileIconsTest.unknownAndNullFallBackToGeneric`. - **ICON-24 · MUST.** Every glyph set and font the app ships is credited in `NOTICE` with its license. - *Check (code):* each icon source named in the icon classes and each family under `fonts/` has an entry in `NOTICE`. - *Reference:* Editora `NOTICE`: Material Design Icons (Apache-2.0), Simple Icons (CC0; the logos stay their owners' trademarks), Inter and the monospace faces (OFL), and the glyph sets inside the bundled Symbols Nerd Font, Octicons and Seti UI (MIT) among them. ## Toolbars and tooltips (TBAR) https://pauta-project.dev/2.0.0/toolbars-and-tooltips/: Icon-only buttons that have a name, groups by spacing, one chrome band, the customizable toolbar, and tooltips that share the menus' card. ### Rules - **TBAR-01 · MUST.** Every icon-only button has a name: one helper sets its tooltip and its accessible text from the same string. - *Why:* a hand-rolled button gets the tooltip and forgets the name, which is how Editora once had seven copies of the helper drifting apart, and how a screen reader comes to announce "button". - *Check (code):* every icon-only `Button` is built by `Icons.button` or `Icons.toolbarButton`, or passed to `Icons.name`; none calls `setTooltip` without `setAccessibleText`. - *Reference:* Editora `ui/Icons.java` (`button`, `toolbarButton`, `name`); Torrenta's copy of all three. nux sets both by hand on its "?" button for the same reason. Editora doesn't yet on its main toolbar: `WindowToolbar.setupButton` and `ToolbarCoordinator.buildExtraButton` set the tooltip only. - **TBAR-02 · MUST.** Toolbar buttons stay out of the Tab order: the command, the palette and the menus reach the action, and Tab is for the content. The [keyboard page](https://pauta-project.dev/2.0.0/keyboard/#focus-and-accessibility) has the general focus rules. - *Check (code):* every button on a toolbar is built by `Icons.toolbarButton` or calls `setFocusTraversable(false)`. - *Reference:* Editora `Icons.toolbarButton`, used by the tool window toolbars (Git, Diff, Markdown lint); Termina's search bar buttons; Mirada's header buttons. Editora doesn't yet on its main toolbar: the buttons built by `WindowToolbar.setupButton` and `ToolbarCoordinator.buildExtraButton`, and the stripe buttons, take focus. - **TBAR-03 · MUST.** The tooltip names the command and its chord, read from the active keymap and never typed into a string: "Save (C-x C-s)". An unbound command shows its title alone. - *Check (code):* the tooltip is built from the command's title and the keymap's display chord for its id, and is rebuilt when the keymap changes. - *Reference:* Editora `WindowToolbar.setupButton` (`refreshToolbarTooltips`), `ToolbarCoordinator.buildExtraButton` and `ToolWindowManager.tooltipFor`; Torrenta's `toolbar.withChord`. Mirada's header buttons use the same "label (key)" form with the key written into the string. - **TBAR-04 · SHOULD.** Groups are separated by spacing, not rules: keep the `Separator` nodes (their padding is the gap) and make the line transparent. - *Check (code):* the stylesheet sets `.tool-bar .separator:vertical > .line` to a transparent border. - *Reference:* Editora `app.css`. Torrenta's separators still draw a line. - **TBAR-05 · SHOULD.** Hiding a button group (Simple mode, a build tool that is not detected) hides the leading, trailing and doubled separators it leaves, so no gap stands on its own, and shows them all again when nothing is hidden. - *Check (code):* every change to a toolbar item's visibility ends in one pass over the bar's separators. - *Reference:* Editora `WindowChromeCoordinator.collapseToolbarSeparators`. - **TBAR-06 · SHOULD.** One chrome band: the menu bar, the toolbar and the tab strip share `-color-bg-subtle` and draw no hairline between them; the breadcrumb, the bottom stripe and the status bar do the same at the bottom. - *Why:* three rules within forty pixels read as clutter, not structure. - *Check (by hand):* look at the top and the bottom of a window in a light and a dark theme for a line between the bands. - *Reference:* Editora `app.css` (`.menu-bar, .tool-bar`). - **TBAR-07 · MUST.** A toggle looks on while it is on: a button that opens an overlay (Find, the palette, a split) and the Simple mode button carry the `:open` pseudo-class while their state holds, so the way back out does not look like the way in. - *Check (code):* each such button sets a pseudo-class from its state, and the stylesheet gives that state a fill. - *Reference:* Editora `MainController.OPEN`, `WindowChromeCoordinator` (Simple mode), `.button:open` in `app.css`. Torrenta uses `:on` for Simple mode and `:active` for the alternative speed limit. - **TBAR-08 · MUST.** The toolbar never holds the only way to an action: every icon in the customizable cluster is also in the menus and the palette. - *Why:* that is what makes it safe to hide icons in a narrow window and to let the user remove them. - *Check (code):* every toolbar catalog item runs a registered command that a menu also lists. - *Reference:* Editora `toolbar/ToolbarCatalog.java`: each item carries the `commandId` it runs; the only items without one are declared special widgets, such as the Recent menu button (`ToolbarCatalogTest`). - **TBAR-09 · MAY.** The toolbar is customizable: the user reorders, removes and restores its buttons, and the layout is saved in Settings and shared by every window. - *Check (test):* FX tests drive customize mode, reorder and removal. - *Reference:* Editora `ui/ToolbarCoordinator.java`, `ToolbarCustomizeModeFxTest`, `ToolbarCustomizationFxTest`. The cluster is a list of catalog ids in Settings (`toolbarLayout`), sanitized on read. The bar's right-click menu offers *Customize Toolbar…* (or *Done*), *Configure…* (the Settings page) and *Restore Default*. In customize mode the bar tints, buttons drag to reorder with an accent insertion line and drag off the bar to remove; Escape leaves the mode. - **TBAR-10 · MUST.** The bar's right-click menu is one menu, reused across right-clicks, so showing it again moves it, and it closes on a press anywhere, the toolbar included. - *Check (test):* an FX test right-clicks the bar twice and finds one menu, then presses on the bar and elsewhere in the window and finds it closed. - *Reference:* Editora `ToolbarCoordinator`, `ContextMenuDismissal`, `ToolbarContextMenuDismissFxTest`. See [Menus](https://pauta-project.dev/2.0.0/menus/). - **TBAR-11 · SHOULD.** The bar's right-click menu is the size of every other menu (14 px), not the bar's 18 px. - *Why:* a popup inherits the font of the node it was shown from; the `.context-menu` rule that pins menus to 14 px is what keeps this one in line. - *Check (test):* an FX test opens the menu from the bar and reads its font size. - *Reference:* Editora `app.css` (`.context-menu`), `ToolbarMenuFontFxTest`. - **TBAR-12 · SHOULD.** Tool window stripes are toolbars: a stripe button is built like a toolbar button, with the chord in its tooltip, accessible text bound to the window's title, and a right-click menu with *Open in Split* and *Hide*. - *Check (code):* the stripe button's tooltip comes from the same title-and-chord format, and its `accessibleTextProperty` is bound to the tool window's title. - *Reference:* Editora `ToolWindowManager.register`, `tooltipFor`. - **TBAR-13 · SHOULD.** The right stripe's first icon lines up with the editor's first line of text, not with the tab strip. - *Check (test):* an FX test compares the first stripe button's top with the editor's first line. - *Reference:* Editora `ToolWindowStripeAlignmentFxTest`. ## Tabs and tool panels (TABS) https://pauta-project.dev/2.0.0/tabs-and-panels/: The tab strip and its states, reorder and reopen, and the tool panels that dock around the editor. ### Tabs - **TABS-01 · MUST.** Every tab operation is a command, so it can be bound to a chord, is in the palette and has a menu row: close, close others, close all, close unmodified, close to the left and right, pin, reopen closed, next and previous. The tab's [right-click menu](https://pauta-project.dev/2.0.0/menus/) lists the ones that act on a tab. - *Check (code):* each operation has a registered command id, and `TabContextMenu` lists the per-tab ones. - *Reference:* Editora `ui/WindowCommandRegistrar.java` (`buffer.close`, `buffer.closeOthers`, `buffer.closeAll`, `buffer.closeUnmodified`, `buffer.closeLeft`, `buffer.closeRight`, `buffer.togglePin`, `buffer.reopenClosed`, `buffer.next`), `ui/TabContextMenu.java`. Editora has no previous-tab command yet. - **TABS-02 · MUST.** The header is the title: the Tab's own text stays empty, and a graphic header carries the file-type glyph, the markers and the title in a `.tab-title` label. The tooltip is the full path. - *Why:* the graphic is what makes the header a drag handle and lets each state set its own color. - *Check (code):* every editor tab gets `setText("")` and a graphic with a `.tab-title` label; its tooltip is the file's path. - *Reference:* Editora `ui/TabHeaders.java`. - **TABS-03 · MUST.** The one header carries the states: a `• ` prefix in amber italic for unsaved, a pin and bold for pinned, muted italic for read-only. - *Check (code):* `app.css` styles `.tab-header.dirty`, `.tab-header.pinned` and `.tab-header.read-only` `.tab-title`, and the header sets those classes. - *Reference:* Editora `ui/TabHeaders.java`, `app.css`; the Unsaved, Pinned and Read-only rows of the Spec table below. - **TABS-04 · MUST.** Bulk close skips pinned tabs: close others, close all, close unmodified and close to the left or right never close a pinned tab. - *Check (code):* `closeOtherTabs`, `closeAllTabs`, `closeUnmodifiedTabs` and `eligibleToLeft` / `eligibleToRight` all filter on the pinned set. - *Reference:* Editora `ui/MainController.java`. - **TABS-05 · MUST.** Pinning moves the tab to the end of the pinned group, unpinning to just after it. - *Check (code):* `togglePin` calls `moveToPinBoundary`. - *Reference:* Editora `ui/MainController.java` (`togglePin`), `ui/EditorArea.java` (`moveToPinBoundary`). - **TABS-06 · MUST.** Reopen Closed Tab brings back the files whose tabs this window closed, newest first, bounded to twenty, a file listed once, with the caret where it was. In a terminal app the *tab* comes back (its shells, their directories, the pane arrangement, the names the user gave them, its place in the strip) and not the scrollback. - *Why:* the process is gone, and pretending otherwise would be worse than saying so. - *Check (test):* a unit test over the closed-tab list holds the order, the bound, the single entry per file and the caret. - *Reference:* Editora `ui/ClosedTabs.java`, `ClosedTabsTest`; `C-S-t` in the CUA keymap. Termina `ui/ClosedTabs.java`, on `Ctrl+Shift+Z` (`Cmd+Z` on macOS). - **TABS-07 · SHOULD.** Tabs reorder by dragging, with the feedback shown above: the dragged header dimmed and an accent line on the edge where it will land. - *Check (by hand):* drag a tab along the strip and watch the landing edge. - *Reference:* Editora `TabHeaders.enableTabDrag`; Termina `installTabDrag` and the pure `TabReorder.insertIndex`. In Termina a double-click on a tab renames it, and a pane dragged onto a tab joins it (the whole header outlined, `tab-drop-into`). - **TABS-08 · SHOULD.** A tab shows its file's Git status in the Project tree's colors: modified accent, added green, untracked olive, renamed violet, deleted muted, conflict red. A read-only tab still shows it; an unsaved one shows amber. - *Check (test):* a test gives a changed file the same style class the Project tree uses. - *Reference:* Editora `ui/TabGitStatus.java`, `TabGitStatusTest`. - **TABS-09 · SHOULD.** A switcher lists the open files in tab order: `C-x C-b` (Emacs) opens it, `C-n` / `C-p` or the arrows move, Enter or releasing Ctrl activates, `C-g` or Esc cancels, `C-d` or Backspace closes the highlighted file. Its width is fixed to the longest path on each open, so it never resizes while you move. - *Check (by hand):* open it with several tabs and move through it; the list keeps its width. - *Reference:* Editora `ui/Switcher.java`, `SwitcherFxTest`. - **TABS-10 · SHOULD.** The window title names the file, the project and the app, with a `●` prefix for an unsaved file. - *Check (code):* the code that sets the stage title adds all three and the marker. - *Reference:* Editora `MainController.updateWindowTitle`. - **TABS-11 · SHOULD.** Tabs sit in the title bar through JavaFX 27's `HeaderBar`; see [Window shell](https://pauta-project.dev/2.0.0/window-shell/). - *Check (by hand):* the tab strip shares the title bar's row. - *Reference:* Termina `ui/TerminalWindow.java`. - **TABS-12 · SHOULD.** A command hides the tab bar. - *Check (code):* a registered command toggles the tab header. - *Reference:* Editora `view.toggleTabBar`, `.tab-pane.no-tab-header` in `app.css`. ### Tool panels - **TABS-13 · MUST.** A command toggles each panel (`tool.`: `M-1` … `M-0` in the Emacs keymap for ten of them), and the stripe button is the same command with a glyph. - *Check (code):* every tool window registers a `tool.` command, and its stripe button runs it. - *Reference:* Editora `ui/ToolWindowManager.java`, `keymaps/emacs.json`. - **TABS-14 · MUST.** A panel's content is built on first use. - *Check (test):* an FX test holds that no closed tool window builds its panel before the first paint. - *Reference:* Editora `LazyToolWindowsFxTest`. - **TABS-15 · MUST.** Panel state is restored: which windows are open, on which side, in what order, hidden or shown, floating, and every divider position go to `workspace-state.json` and come back on the next launch. - *Check (code):* the workspace state holds each of those, and the manager reads them back at startup. - *Reference:* Editora `ui/ToolWindowManager.java`, `config/WorkspaceState.java`. - **TABS-16 · SHOULD.** Panels dock on three sides, left, right and bottom, and a side holds at most two windows stacked (Project over Structure, two consoles along the bottom). - *Why:* past that a side stops being a dock and becomes a list of slivers. - *Check (code):* the sides are an enum of three and the per-side limit is two. - *Reference:* Editora `ToolWindow.Side`, `ToolWindowManager.MAX_PER_SIDE`. - **TABS-17 · SHOULD.** A panel re-docks by dragging its stripe button to another stripe, with the same dim-and-accent-line feedback as a tab; an empty stripe appears as a dashed accent drop zone for the duration of the drag. - *Check (by hand):* drag a stripe button to the opposite side. - *Reference:* Editora `ui/ToolWindowDock.java`, `ToolWindowVisibilityTest` (an empty stripe shows while dragging). - **TABS-18 · SHOULD.** Panels float, maximize, resize and close from the keyboard, and at most one window is maximized at a time. - *Check (code):* the commands are registered and bound in the Emacs keymap. - *Reference:* Editora `view.floatToolWindow`, `view.maximizeToolWindow` (`C-x f`), `view.closeFocusedToolWindow` (`C-x 0`), the resize commands (`C-x S-.`, `C-x S-,`, `C-x S-6`). - **TABS-19 · SHOULD.** Closing the panel that holds keyboard focus returns focus to where it was in the editor. - *Check (code):* the manager keeps the last editor focus owner and refocuses it on close. - *Reference:* Editora `ToolWindowManager.focusEditor`, a weak reference to the last editor focus owner. - **TABS-20 · SHOULD.** Hidden is not unavailable: the user's show/hide choice for a stripe button is kept apart from a context-driven hide (the Commit window outside a Git repository), so the second never clobbers the first. - *Check (test):* a unit test holds that a button shows only when visible and available. - *Reference:* Editora `ui/ToolWindowVisibility.java`, `ToolWindowVisibilityTest`. - **TABS-21 · SHOULD.** A bottom window that is unusable at the default height asks for more on its first open; the user's own size wins afterwards. - *Check (test):* a test opens an output window taller while the others keep the side's size. - *Reference:* Editora `ToolWindow.setFirstOpenShare`, `ToolWindowFirstOpenShareTest`. - **TABS-22 · SHOULD.** A stripe button badges a spinner while its window has something under way. - *Check (test):* an FX test badges a busy window's stripe button without changing its size. - *Reference:* Editora `ToolWindow.busy`, `ToolWindowManagerFxTest`. - **TABS-23 · SHOULD.** Panels follow the active document where they should: the Git UI follows the active tab's repository, the status bar's environment segment the active `.http` file, Local History the file whose tab menu opened it. - *Check (by hand):* switch between tabs from two repositories with the Git window open. - *Reference:* Editora `ui/GitPathScope.java`. ## Menus (MENU) https://pauta-project.dev/2.0.0/menus/: The menu bar and right-click menus: icons, the chord column, one menu at a time, and a press anywhere else closes it. ### The menu bar - **MENU-01 · MUST.** Every menu-bar item is a command from the registry, with its title from `command.`, its chord from the active keymap and its enabled state from the command's gate. The bar assembles and refreshes; it holds no behavior of its own. - *Check (code):* the bar's model lists command ids only, and every row runs its id through the registry. - *Reference:* Editora `ui/MenuBarModel.java` over `command/CommandRegistry.java`, `ui/MainMenuBar.java`. - **MENU-02 · MUST.** Menu-bar rows use no `KeyCombination` accelerators. In the in-window bar each row is a `CustomMenuItem` laying out icon, title, spacer and chord. On the macOS system menu bar (`useSystemMenuBar`) the chord is appended to the title and rows carry no icon. - *Why:* Emacs chords are multi-key, which a `KeyCombination` cannot express, and on macOS an accelerator would bypass the key dispatcher. The native macOS menu draws text only and no graphics, which is also the platform's convention. - *Check (code):* no `setAccelerator` in the menu-bar classes. - *Reference:* Editora `ui/MainMenuBar.java` (`rowContent`, `refresh`). - **MENU-03 · SHOULD.** Enablement is re-read every time a menu opens, and titles and chords on a keymap or locale change. - *Why:* a menu built before Git finished detecting a repository must not stay grayed out. - *Check (test):* an FX test detects a repository after the window is built and finds the menu enabled. - *Reference:* Editora `MainMenuBar.refreshEnablement`, `MenuBarEnablementFxTest`. - **MENU-04 · SHOULD.** Simple mode shows a shorter menu, rebuilt only when the mode actually changes. - *Check (code):* the bar rebuilds only when the simple flag differs from the current one. - *Reference:* Editora `MainMenuBar.setSimple`, `MenuBarModel.menus(simple)`. ### Right-click menus - **MENU-05 · MUST.** Every list row, tree row, tab, editor and read-only console has a right-click menu with the actions for *that* thing, each one a command. - *Check (by hand):* right-click each kind of thing; every row's action is also in the palette. - *Reference:* Editora `ui/TabContextMenu.java`, `ui/RowContextMenu.java`, `ui/ConsoleContextMenu.java`. - **MENU-06 · MUST.** One right-click menu at a time: a right-click while a menu is open replaces it, and the first one closes before the second shows. - *Why:* JavaFX stacks a second menu beside the first when each row owns its own `ContextMenu`, and the stale one is then no longer dismissible. - *Check (test):* an FX test right-clicks another row with a menu open and finds one menu showing. - *Reference:* Editora `ui/ContextMenuDismissal.java` closes every open right-click menu on the press that opens the next (`ContextMenuDismissalFxTest`); Modula's `RadioPane` hides the previous menu before showing a new one; Termina keeps one menu per view and shows it again. - **MENU-07 · MUST.** A press anywhere outside a right-click menu closes it, including inside the control the menu was opened on. The press is not consumed: a click in a list still selects the row, and a right-click on another row opens that row's menu straight away. Drop-downs opened by a plain click (menu buttons, choice boxes, the menu bar) keep the stock behavior, and a menu that turned auto-hide off is left alone. - *Why:* JavaFX's auto-hide deliberately ignores a press on the menu's *owner node*, so a stock menu on a tree or a text area stays open when the user clicks another row or the text. - *Check (test):* an FX test clicks inside the owner control and in another window, and the menu closes. - *Reference:* Editora `ContextMenuDismissal.install()`, called once in `App` at startup for every current and future window; `ContextMenuDismissalFxTest`. - **MENU-08 · MUST.** Escape closes a right-click menu and focus goes back where it was. In a terminal the Escape does not reach the shell. - *Check (by hand):* open a menu, press Escape, and type: the keys reach the control that had focus. - *Reference:* the stock `ContextMenu` hide-on-Escape (Spec below); Termina's `onKeyPressed` filter hides the menu and consumes the key (`TerminalView`). - **MENU-09 · MUST.** The Menu key and Shift+F10 open the selected row's menu, scrolled into view first, so every row action a mouse can reach the keyboard can too. - *Why:* those keys arrive at the focused control, not at a row's cell, so a menu installed on cells never saw them. - *Check (test):* an FX test sends a keyboard request to a tree and a list and finds the selected row's menu, anchored to that row. - *Reference:* Editora `RowContextMenu.install(tree)`, `RowContextMenuFxTest`. - **MENU-10 · SHOULD.** A right-click selects first. In an editor, a right-click outside every selection moves the caret to the click (so Paste lands there); inside a selection it keeps carets and selections (so Cut and Copy act on what was clicked). From the keyboard the target is the caret. In a list, the menu is the clicked row's. - *Check (by hand):* select a word, right-click elsewhere and paste; then right-click inside a selection and copy. - *Reference:* Editora `editor/ContextMenuTarget.java`. - **MENU-11 · SHOULD.** A menu attached to something that exists once per open file is built when first shown, and set up for each showing: an `onShowing` handler sets the labels, enablement and visibility for *this* showing, then collapses the separators. - *Why:* such a menu is built for every file and opened for almost none. - *Check (code):* per-file menus are created through `LazyContextMenu.of(build)`. - *Reference:* Editora `ui/LazyContextMenu.java`, `LazyContextMenuFxTest`. A read-only console's menu is just Select All and Copy, both disabled while it is empty (`ConsoleContextMenu`). - **MENU-12 · SHOULD.** A destructive row carries the `danger` class. The action follows the [window shell](https://pauta-project.dev/2.0.0/window-shell/) rule: it asks first with a button that names it, or is undoable. - *Check (code):* rows that delete, discard or reset add `danger` to their style classes. - *Reference:* Editora `.menu-item.danger` in `app.css`, `ui/BranchPopup.java`. - **MENU-13 · MAY.** In a terminal view, a program that grabbed the mouse owns the right-click; Shift+right-click always opens the menu, and the keyboard request is never contested. - *Check (test):* a pure test of when the menu shows, per mouse mode, Shift and trigger. - *Reference:* Termina's `TerminalView.shouldShowMenu`, `ContextMenuContentionTest`. ## Tray and background (TRAY) https://pauta-project.dev/2.0.0/tray-and-background/: An app that keeps working behind a tray icon: the icon and its menu, close to tray, start at login, desktop notifications. ### The icon and its menu - **TRAY-01 · MUST.** The tray comes from the shared `tray/` package: a StatusNotifierItem on Linux, AWT's `SystemTray` on Windows and macOS, created off the FX thread after the first frame. - *Why:* D-Bus and AWT can block, and neither is worth a stalled first frame. - *Check (code):* `Trays.create` picks `SniTray` on Linux and `AwtTray` elsewhere, and the window calls it from a background thread. - *Reference:* Torrenta `tray/Trays.java`, `MainWindow.installTray`; the Spec table below. ### Behavior - **TRAY-02 · MUST.** The app is fully usable without a tray. No icon is a normal outcome (stock GNOME has no StatusNotifier host), not an error, and the reason is said where the person will look. - *Why:* the bug they actually hit is silence: the box says close to tray, and closing quits. - *Check (code):* when the tray attempt returns no tray, the status bar says why and that closing quits. - *Reference:* Torrenta `MainWindow.installTray` ("No tray icon (…); closing the window quits Torrenta", `status.noTray`); Modula's status says closing the window will quit it (`RadioPane.reportNoTray`). - **TRAY-03 · MUST.** Closing the window hides it only while an icon is actually up and the setting says so, both read at close time; otherwise a close quits. `Platform.setImplicitExit(false)` is set only once a tray exists, and turning the tray off brings a hidden window back. - *Why:* the checkbox can change while the window is open, and hiding a window that leaves no icon behind is how a program becomes unreachable. - *Check (code):* the close handler tests that a tray exists and reads the live setting; `setImplicitExit(false)` sits after the tray is created. - *Reference:* Torrenta `MainWindow.setOnCloseRequest`, Modula's `installCloseBehaviour`, nux's `TrayController.closeHidesWindow` and `updateImplicitExit`. - **TRAY-04 · MUST.** Quit is explicit and one path: the tray's Quit, File → Quit and the system's Quit all run the same method, which closes open dialogs first and saves the window geometry. - *Why:* quitting from inside a nested event loop aborted the JVM. - *Check (code):* every quit entry point calls the one quit method. - *Reference:* Torrenta `MainWindow.quit`. - **TRAY-05 · SHOULD.** `--minimized` comes up behind the icon. The window is never shown until the tray attempt has answered; if no icon comes, the window is shown after all. With the tray setting off, Torrenta starts minimized instead and nux ignores the flag. - *Why:* a start at login can then never leave a program with no way back. - *Check (code):* a `--minimized` start shows the window when the tray attempt returns none. - *Reference:* Torrenta `MainWindow.show`, nux's `App`. - **TRAY-06 · SHOULD.** Start at login writes the OS's own entry, and nothing else: an XDG autostart entry in `~/.config/autostart` (quoted `Exec`, `StartupWMClass` matching the installed launcher, `X-KDE-autostart-after=panel` so a tray host is up first), a LaunchAgent in `~/Library/LaunchAgents`, the `HKCU\…\Run` value on Windows (read together with `StartupApproved`, where Task Manager keeps the person's "off"). The entry is the one truth: turned off in GNOME Tweaks, KDE's Autostart page or Task Manager, the box shows unticked. The one setting beside it is *start behind the tray icon*, written into the entry as `--minimized`. - *Check (test):* a pure test of the exact bytes of each platform's entry. - *Reference:* Torrenta `os/Autostart.java`, `os/AutostartSpec.java`, `AutostartSpecTest`; nux's design. - **TRAY-07 · SHOULD.** Only the app writes the login entry, and only from an installed package: the installers never do it, and a run from source says it has nothing to start. - *Why:* an installer runs for every account. - *Check (code):* the entry's target comes from `jpackage.app-path`, and is absent when it is unset. - *Reference:* Torrenta `os/Autostart.java`. - **TRAY-08 · SHOULD.** Every start-at-login call runs off the FX thread. - *Why:* it may block on the file system or `reg.exe`. - *Check (code):* every `Autostart` read and write starts on a worker thread. - *Reference:* Torrenta `SettingsWindow` (`autostart-read`, `autostart-write`) and `MainWindow` (`autostart-refresh`); nux's `App` (`nux-autostart`). - **TRAY-09 · MUST.** Desktop notifications go through one `Notifier`: `notify-send` on Linux (nux and Termina fall back to `gdbus` against the freedesktop service), `osascript` with `display notification` on macOS, a PowerShell toast on Windows. Each is a short program run with the title and message as arguments, never as part of a script, off the FX thread and bounded to a few seconds; a failure is logged and never breaks the app. - *Why:* text from a torrent name or a remote shell then cannot run anything. - *Check (test):* a test holds that each platform's command line passes the text as arguments and that a missing program is a problem, not an exception. - *Reference:* Torrenta `automation/Notifiers.java`, `ProcessNotifier`, `NotifierTest` (it ships `toast.ps1`); nux's `service/Notifier` raises it through the tray icon, which it keeps as the last resort on every platform; Termina's `DesktopNotifier`. - **TRAY-10 · MUST.** Notifications are for what happened while the window was away, with one switch per event and few on by default. - *Check (code):* each notified event has its own setting, and most default to off. - *Reference:* Torrenta notifies on added, finished, seeding done, error and updated, with only *finished* on at first, and a Test button in Settings shows one now (`automation/AutomationSettings.java`); nux notifies on power events with a rule per UPS; Termina and Editora relay a program's own OSC 9 and OSC 777 notifications. - **TRAY-11 · SHOULD.** A notification is never the only place a state is said: the in-app status already shows it. - *Check (by hand):* trigger each notified event with notifications off; the window still shows it. - *Reference:* Torrenta's status bar and transfer list. - **TRAY-12 · MAY.** A dock badge: Torrenta puts the download rate on the macOS dock icon through AWT's `Taskbar` and a count on a Linux launcher that honors Unity's `LauncherEntry` signal (KDE, Dash to Dock); nothing on Windows, whose taskbar badges only AWT's own windows. It is cleared when nothing downloads and has its own switch. - *Check (test):* a pure test of the badge state. - *Reference:* Torrenta `os/Badges.java`, `BadgeState`, `BadgeStateTest`. - **TRAY-13 · SHOULD.** A second launch brings the hidden window forward: the [single-instance hand-off](https://pauta-project.dev/2.0.0/command-line/) shows a window hidden to the tray before it opens what it was given. - *Check (by hand):* close to the tray, then launch the app again with a file. - *Reference:* Torrenta `MainWindow.showFromTray`. - **TRAY-14 · SHOULD.** AWT stays headless unless the tray needs it. Linux never needs it; Windows and macOS lift the guard only when the tray setting is on, decided in `main`. A tray turned on later says "restart to show the tray icon" rather than "unsupported". - *Check (test):* a test holds that AWT is headful only where the tray is AWT's and wanted. - *Reference:* Torrenta `Trays.usesAwt`, `os.AwtUse`, `TraysTest`. ## Settings (SET) https://pauta-project.dev/2.0.0/settings/: The Settings window with search, live apply, versioned config and Git/GitHub sync. ### The Settings window - **SET-01 · MUST.** The Settings window opens from a palette command, bound to `Ctrl+,` (`Cmd+,` on macOS) in the CUA keymap. - *Check (code):* a registered command opens Settings, and `cua.json` and `cua.mac.json` bind it. - *Reference:* Editora `view.settings`, bound in `keymaps/cua.json` and `cua.mac.json` (and in the VS Code and Sublime keymaps; IntelliJ's uses `C-M-s`). - **SET-02 · MUST.** The window has a sidebar of pages with icons on the left, the page on the right, and a search field on top. - *Check (by hand):* open Settings; the search field sits above the sidebar and the page. - *Reference:* Editora `ui/SettingsWindow.java`, `ui/SettingsSidebarNav.java`, `ui/SettingsIcons.java`. - **SET-03 · MUST.** Search finds a row by its title, description, visible text, its card or section heading, its page name and English keywords. Title hits rank above description hits; whole words above word starts. The page with the best match opens, and every non-matching row, heading and card is hidden. - *Check (test):* a unit test ranks a title hit above a keyword hit and a whole word above part of one. - *Reference:* Editora `ui/SettingsSearch.java`, `SettingsSearchTest`. - **SET-04 · MUST.** Settings apply live, with no Save button. Text fields commit on Enter or focus loss; invalid values are marked and never committed. - *Check (code):* no Save or Apply button in the window; text fields commit through `commitOnEnterOrBlur`. - *Reference:* Editora `SettingsWindow.commitOnEnterOrBlur`; `SettingsSyncPage`'s branch field marks an invalid branch. - **SET-05 · SHOULD.** A change made in one window reaches every other open window. - *Check (test):* an FX test changes a setting in one window and finds it applied in the other. - *Reference:* Editora: every window holds the same `config/SharedConfig.java`, which announces each change (`onSettingsChanged`); `CrossWindowSettingsFxTest`. ### Adding a setting touches five places - **SET-06 · MUST.** Every setting has a palette command that flips the field or prompts for its value. - *Check (by hand):* for each row in Settings, find a palette command that changes it. - *Reference:* Editora's `view.toggle…` and picker commands (`ui/WindowCommandRegistrar.java`). Editora does not have one for every setting yet: `terminalNotifications`, for one, is only a Settings row. ### Config folder and schema - **SET-07 · MUST.** Config lives in `~/.`: `~/.-dev` for `--dev`, any folder via `--config-dir` or `_CONFIG_DIR`. - *Check (code):* one resolver picks the folder, in the order `--config-dir`, the environment variable, the default. - *Reference:* Editora `App` and `ConfigManager.configDirFor`, `ConfigDirTest`. - **SET-08 · SHOULD.** `settings.json` holds preferences, `workspace-state.json` session state, and other stores their own JSON files. - *Check (code):* the config folder's file names are constants in the config package. - *Reference:* Editora `config/ConfigManager.java`, `config/WorkspaceState.java`. - **SET-09 · MUST.** Every versioned file has a `SCHEMA_VERSION` and a `v → v+1` migration step. A purely additive field uses an identity step. - *Check (code):* each store declares `SCHEMA_VERSION`, and the migrations have one step per version. - *Reference:* Editora `config/migration/ConfigMigrations.java`, `ConfigSchema.java`, `ConfigMigrationsTest`. - **SET-10 · MUST.** A file newer than the running build is backed up to `.v.bak` and defaults load. - *Why:* an older build never clobbers a newer config. - *Check (test):* a test loads a too-new `settings.json` and finds the backup and the defaults. - *Reference:* Editora `ConfigVersioningTest` (`tooNewSettingsAreBackedUpAndDefaultsLoaded`). - **SET-11 · SHOULD.** Never trust a config file. Clamp every value to its valid range when it is **read**, not only when it is written; an unknown value falls back to its default; a file that cannot be decoded is kept as `.corrupt.bak` and defaults load. A bad file never stops the app from starting. - *Why:* config is plain JSON (or properties) and people edit it by hand. A hand-edited two-million-line scrollback must not exhaust memory at the next launch (Termina). - *Check (test):* a test loads out-of-range numbers and an unparseable file. - *Reference:* Editora `ConfigLoadProblemsTest` (`outOfRangeNumbersAreClampedOnLoad`, `anUnparseableFileIsReportedWithItsBackup`). - **SET-12 · MUST.** Export configuration writes a timestamped `.zip` of the config folder; Import restores from one. - *Check (test):* tests over the zip's name and contents, and an import that replaces only the ticked parts. - *Reference:* Editora `config/ConfigExporter.java`, `config/ConfigImport.java`, `ConfigExporterTest`, `ConfigImportTest`. ### Secrets stay out of files - **SET-13 · SHOULD.** No secret goes in a config file. API keys and tokens go to the operating system's keychain: macOS Keychain, Windows Credential Manager, the Secret Service on Linux. Calls may block on a prompt, so they run off the FX thread. - *Check (code):* no key or token field in the settings model; reads and writes go through the secret store. - *Reference:* Editora `secrets/SecretStore.java`. - **SET-14 · SHOULD.** A credential the app can ask for again lives in memory for the session only and is never written. Work that needs it waits until the user has signed in this session; do not "fix" that by storing the password. - *Check (code):* the credential is a field of a runtime object, absent from every config class. - *Reference:* nux's UPS login (`app/CommandRunner.java`). - **SET-15 · SHOULD.** A secret in the wrong place is refused. A repository URL with a password or token in it is refused, with the fix ([Settings Sync](https://pauta-project.dev/2.0.0/templates/settings-sync/)); a problem report redacts tokens, hosts and home paths before anyone sees it ([Diagnostics](https://pauta-project.dev/2.0.0/diagnostics/)). - *Check (by hand):* paste `https://user:token@host/repo.git` as the sync repository. - *Reference:* Editora `ui/SettingsSyncPage.java` (`settings.sync.repo.credentials`). - **SET-16 · SHOULD.** An option that weakens security has no UI: it exists only as a key in the config file, so nobody turns it on by clicking. - *Check (code):* no Settings row or command writes such a key. - *Reference:* nux's trust-all TLS (`tlsTrustAll` in `config/Config.java`). ### Settings Sync (Git / GitHub) - **SET-17 · SHOULD.** Settings, keybindings and user data can sync, optionally, through a Git repository the user owns. - *Check (by hand):* set up Sync on two machines and change a setting on one. - *Reference:* Editora `sync/SyncEngine.java`, `docs/subsystems/settings-sync.md`. Editora syncs key bindings and user data (snippets, abbreviations, templates, the dictionary), not the rest of `settings.json`; Torrenta syncs its settings file (`sync/SyncEngine.java`). - **SET-18 · SHOULD.** Setup is by pasting a repo URL, or **Create on GitHub** through the `gh` CLI. The account that can read the repo is pinned per clone, so machines with two GitHub accounts work. - *Check (test):* a test remembers the first account that can read the repository and uses it without asking again. - *Reference:* Editora `sync/SyncAccount.java`, `SyncAccountTest`, `ui/SettingsSyncPage.java`. - **SET-19 · SHOULD.** Sync runs automatically (on change and at start) and on demand. Machine-local keys (window size, paths) never sync. - *Check (code):* one pure class decides which keys or files travel, and machine-local ones are not among them. - *Reference:* Editora `ui/SettingsSync.java` (after startup, after a local change, on an interval, and `sync.now`), `sync/SyncCategory.java`; Torrenta `sync/SyncKeys.java`. - **SET-20 · SHOULD.** On a same-entry conflict *this machine wins*, and a backup is taken before any sync that replaces local files. - *Check (test):* a merge test where both sides changed one entry keeps this machine's. - *Reference:* Editora `sync/SyncMerge.java`, `SyncMergeTest`. - **SET-21 · SHOULD.** Sync status shows as a pill in Settings and as echo messages; failures go to the Message Log. - *Check (by hand):* point Sync at a repository that does not exist and read the pill and the log. - *Reference:* Editora `ui/SettingsSyncPage.java`, `SyncStatus`. ## Diagnostics and support (DIAG) https://pauta-project.dev/2.0.0/diagnostics/: Message Log, Debug Log, update notification, Report a Problem, Doctor and crash recovery. - **DIAG-01 · MUST.** The **Message Log** is a session-only, bounded history of every echo-area message with `HH:mm:ss` times, newest first. Clicking the status message opens it; Esc closes it; Clear empties it. - *Check (test):* a test records messages newest first, evicts the oldest past the cap, and clears. - *Reference:* Editora `ui/MessageLog.java` (`MessageLogTest`), `ui/MessageLogPopup.java`. - **DIAG-02 · MUST.** The **Debug Log** captures all `java.util.logging` records and uncaught exceptions in memory (bounded) **and** mirrors them to `-session.log` in the config folder, keeping the previous one as `-session.prev.log` so a crash is still visible next launch. - *Check (test):* tests bound the buffer and find the session file written and the previous one kept. - *Reference:* Editora `ui/DebugLog.java` (`DebugLogTest`, `DebugLogSessionFileTest`). - **DIAG-03 · MUST.** The Debug Log opens in a modeless window with Refresh, Copy, Clear, Export and Report a Problem. - *Why:* it is the only way to see logs in a packaged build. - *Check (by hand):* open the Debug Log and keep working in the main window while it is open. - *Reference:* Editora `ui/DebugLogWindow.java`. - **DIAG-04 · MUST.** An **uncaught exception handler** is installed at the start of `main`, before the toolkit starts, and routes to the Debug Log and an echo message. Never a stack trace dialog. - *Check (code):* `main` calls the install method before any argument handling or `launch`, and the handler shows no dialog. - *Reference:* Editora `DebugLog.install()`. Editora, Torrenta and Termina log the exception but do not yet post an echo message. - **DIAG-05 · MUST.** The **update notification** reads GitHub `/releases/latest` once per app session (not per window), at most once a day, a few seconds after the first frame. A newer version shows a status-bar notice and a line in About; "Check for Updates" runs it by hand; Settings has an off switch. It never downloads or installs by itself. - *Check (test):* a test waits for the first paint and the delay, then checks once a session and not when off or not due. - *Reference:* Editora `update/UpdateCheck.java`, `ui/UpdateCheckScheduler.java` (`UpdateCheckSchedulerTest`), `ui/UpdateCoordinator.java`. - **DIAG-06 · MUST.** Help → **Report a Problem** builds a report (version, OS, runtime, settings summary, recent Debug Log), **redacts** it (home paths, user names, e-mail addresses, credentials, tokens), shows it editable, copies it to the clipboard and opens a prefilled GitHub issue from `bug_report.yml`. Over about 7,500 characters the link falls back to "paste from the clipboard". ` --report` does the same from the command line for when the app cannot start. Nothing is uploaded. - *Check (test):* redaction tests cover home paths, user names, e-mail addresses, credentials in URLs and tokens; a report test puts a short report in the link and leaves the paste hint for a long one. - *Reference:* Editora `report/ProblemReport.java`, `report/Redactor.java`, `report/ReportCommand.java`, `ui/ReportProblemWindow.java` (`RedactorTest`, `ProblemReportTest`). - **DIAG-07 · SHOULD.** A **Doctor** page checks the environment (external tools, versions, permissions, paths), with a status per row and a fix or link for each failure. - *Check (by hand):* open the Doctor with a tool missing and find its row failed, with what to install. - *Reference:* Editora `doctor/*`, `ui/DoctorPane.java`. - **DIAG-08 · SHOULD.** An app with user documents snapshots unsaved work off the FX thread and offers it back after a crash. - *Check (test):* a test finds an abandoned session's snapshots and offers them to the first window only. - *Reference:* Editora `recovery/RecoveryService.java` (`RecoveryServiceTest`, `CrashRecoveryFxTest`). ## Command line and launch (CLI) https://pauta-project.dev/2.0.0/command-line/: The flags every app accepts and the single-instance hand-off. ### Flags - **CLI-01 · MUST.** `--help` and `--version` print before the GUI starts, in plain English, not translated. - *Check (code):* `main` handles both and exits before `launch`, printing fixed English text rather than catalog messages. - *Reference:* Editora `App.main`, `App.helpText`; `AppArgsTest`. - **CLI-02 · MUST.** `--config-dir ` uses another config folder, and `--dev` uses `~/.-dev`. - *Check (code):* the config folder is resolved from both flags before anything reads `~/.`. - *Reference:* Editora `App.main` (`ConfigManager.configDirFor`, `App.devFlag`). - **CLI-03 · SHOULD.** `--new-instance` starts a second process instead of handing off to the running one. - *Check (code):* the flag skips the single-instance hand-off. - *Reference:* Editora `App.newInstanceFlag`. - **CLI-04 · SHOULD.** `--no-session` does not restore the last session. - *Check (by hand):* launch with `--no-session` and find only the items given on the command line. - *Reference:* Editora `App.helpText`. - **CLI-05 · MUST.** `--report` writes a redacted problem report and opens the GitHub issue, without starting the GUI. - *Check (test):* a test runs the report command and finds the redacted report written. - *Reference:* Editora `report/ReportCommand.java` (`ReportCommandTest`). - **CLI-06 · SHOULD.** `[files…]` opens these items. - *Check (by hand):* launch with two files and find both open. - *Reference:* Editora `App.fileTargets`. ### Launch - **CLI-07 · MUST.** One instance runs per config folder. A second launch hands its arguments to the running app over a local endpoint and exits; on macOS, `openFiles` Apple Events reach the running app. - *Check (test):* a test makes the first launch primary and delivers a second launch's arguments to it. - *Reference:* Editora `ipc/SingleInstance.java` (`SingleInstanceTest`), `MacOpenFiles.java`. - **CLI-08 · SHOULD.** An advisory lock tells two processes on one config folder about each other. - *Check (test):* a test takes the lock from two processes. - *Reference:* Editora `config/InstanceLock.java` (`InstanceLockTest`). - **CLI-09 · SHOULD.** `main` sets `java.awt.headless=true` before any AWT class loads. - *Why:* on macOS, AWT's native toolkit and JavaFX contend for the one AppKit run loop and can hang; headless Java2D still draws to images. - *Check (code):* `System.setProperty("java.awt.headless", "true")` is among the first statements of `main`. - *Reference:* Editora `App.main`. - **CLI-10 · SHOULD.** External tools are resolved through the login shell's `PATH`. - *Why:* a `.app` launched from Finder inherits a stripped `PATH`. - *Check (code):* every process the app starts gets a `PATH` that includes the login shell's. - *Reference:* Editora `process/ProcessRunner.java` (`augmentedPath`). ## Internationalization (INTL) https://pauta-project.dev/2.0.0/i18n/: Six languages as the floor, and the rules that keep every catalog in step. ### Languages - **INTL-01 · MUST.** The app ships a message catalog for each of the six languages above, English as the base. - *Check (code):* the six `messages*.properties` files are in the app's `i18n` resources. - *Reference:* Editora `src/main/resources/com/editora/i18n/`. - **INTL-02 · SHOULD.** A new language is a `messages_.properties` with every key, listed in the Settings language picker and in the parity test. - *Check (code):* the language's code is in `Messages`' language list (which the picker shows) and in the catalog list the parity test walks. - *Reference:* Editora `i18n/Messages.java` (`LANGUAGES`, `available()`); `MessagesTest`'s `LOCALES` and `ALL_CATALOGS`, after which `translationCatalogsHaveExactlyTheBaseKeySet` holds it to the same keys as the others. - **INTL-03 · SHOULD.** Every value is translated for real: no English value is shipped in another language's catalog. - *Check (code):* compare each catalog's values with the base; a value identical to the English one is a name, a term or a bare pattern that stays the same in that language ("Git: Pull (Rebase)", "{0} · {1}"), never an untranslated sentence. No test catches it, so it is also checked in review. - *Reference:* Editora `messages_*.properties`. - **INTL-04 · SHOULD.** The layout holds in every language at 1024 px wide: rows wrap, never cut. German is today's longest. - *Check (by hand):* run the app in each language at 1024 px wide (see [Quality](https://pauta-project.dev/2.0.0/quality/)). - *Reference:* Editora `messages_de.properties`. - **INTL-05 · SHOULD.** A Chinese, Japanese or Korean catalog comes with a font fallback for its script. - *Why:* Inter has no CJK glyphs. - *Check (by hand):* run the app in that language and look for missing-glyph boxes. - *Reference:* no app yet. - **INTL-06 · SHOULD.** An Arabic or Hebrew catalog sets `NodeOrientation.RIGHT_TO_LEFT` on every scene. - *Check (code):* the scene setup sets the node orientation from the current language. - *Reference:* no app yet. ### Rules - **INTL-07 · SHOULD.** No raw English literal is passed to a control: every string comes from `tr("some.key")` in one `Messages` class. - *Check (test):* a test scans the sources for `tr("…")` calls and fails when a key is missing from the base catalog. - *Reference:* Editora `i18n/Messages.java`, `MessagesTest.everyLiteralKeyUsedInTheSourcesExists`. - **INTL-08 · MUST.** Every catalog has every key of the base catalog, and no more, each with a non-empty value. - *Check (test):* a parity test fails the build when a key is missing, extra or empty in any catalog. - *Reference:* Editora `MessagesTest.translationCatalogsHaveExactlyTheBaseKeySet`, `translationsAreNonEmptyAndDistinctFromKeys`. - **INTL-09 · SHOULD.** In a value with a placeholder, a literal apostrophe is doubled; in a value without one, it is written once. - *Why:* a value with a placeholder is a `MessageFormat` pattern, where a lone apostrophe starts a quoted section and can swallow the placeholder after it; a value without one is shown exactly as written. - *Check (test):* catalog tests fail a lone apostrophe beside a placeholder and a doubled one without. - *Reference:* Editora `MessagesTest.aValueWithAPlaceholderNeverHasALoneApostrophe`, `aValueWithoutAPlaceholderNeverDoublesAnApostrophe`. - **INTL-10 · SHOULD.** Identifiers such as line numbers and ports use `{0,number,#}`, so they are not digit-grouped. - *Check (test):* a test formats each identifier argument in every locale and fails on a grouped number. - *Reference:* Editora `MessagesTest.identifierArgumentsAreNeverDigitGrouped`. - **INTL-11 · SHOULD.** Technical identifiers and the `--help` and `--version` text stay untranslated, outside the catalogs. - *Check (code):* the usage text is a literal in the launcher, not a `tr` call. - *Reference:* Editora `App.java` (the usage text). ## Command Palette (PAL) https://pauta-project.dev/2.0.0/templates/command-palette/: The family's command palette: a 620 px in-scene card that finds and runs any command from the keyboard. ### Rules - **PAL-01 · MUST.** Every app has one Command Palette per window, opened by `palette.show`: `M-x` in the Emacs keymap and `Ctrl+Shift+P` (`Cmd+Shift+P` on macOS) in the others. - *Check (code):* the window builds one `CommandPalette`, and each bundled keymap binds that chord to `palette.show`. - *Reference:* Editora `ui/CommandPalette.java`, built once in `MainController`; `keymaps/emacs.json` (`M-x`), `cua.json` and `vscode.json` (`C-S-p`), `cua.mac.json` (`Cmd-S-p`). - **PAL-02 · MUST.** The palette lists every registered command, with its title from `command.` and its description from `command..desc`. - *Check (code):* the palette's rows come from the whole registry, filtered only by the query; a command that cannot run stays listed, grayed. A catalog parity test fails on a command title with no `.desc`. - *Reference:* Editora `CommandPalette.filter` (`registry.all()`), `MessagesTest`; the Spec table below. - **PAL-03 · MUST.** The palette is an in-scene overlay in the window's root `StackPane`, over a faint scrim, not a `javafx.stage.Popup`. - *Why:* on Windows a popup does not reliably take keyboard focus. - *Check (code):* the palette shows its card through the overlay host installed in the root `StackPane`; no `Popup` is created for it. - *Reference:* Editora `ui/OverlayHost.java` (`install`), `CommandPalette.show`. ### Behavior - **PAL-04 · SHOULD.** The palette opens from the `palette.show` command, by its chord or a menu item, with an empty query that lists every command. - *Check (code):* `show` clears the field and filters on the empty query before the card appears. - *Reference:* Editora `CommandPalette.show`. - **PAL-05 · SHOULD.** Typing filters the list, and the first *enabled* match is selected. - *Check (test):* a test with a disabled command at the top finds the cursor on the first enabled row. - *Reference:* Editora `CommandPalette.selectFirstEnabled`, `CommandPaletteDisabledFxTest`. - **PAL-06 · SHOULD.** ↑ ↓, `C-n` `C-p` and Page Up/Down move the selection; Enter, or a click on an enabled row, runs the command. The palette closes first, then the command runs. - *Check (code):* the run path hides the card before it calls the registry, and does nothing on a disabled row. - *Reference:* Editora `CommandPalette.runSelected`, `PickerKeys`. - **PAL-07 · SHOULD.** Esc, `C-g` or a click on the scrim cancels, and focus returns to where it was. - *Check (code):* the cancel key and a press on the backdrop both hide the overlay, and hiding focuses the node that had focus before it opened. - *Reference:* Editora `PickerKeys` (`CANCEL`), `OverlayHost` (`previousFocus`). - **PAL-08 · SHOULD.** `C-h`, or the first of `C-h`, `F1`, `Shift+F1` the active keymap leaves free, opens the selected command's page on the website, for the running version. - *Check (code):* the docs chord is the first free one of the three, and the URL is built from the app's versioned docs address. - *Reference:* Editora `CommandPalette` (`PickerKeys.freeChord`, `docsUrl`), `AppInfo.docsUrl`. - **PAL-09 · SHOULD.** A live keymap switch re-renders the key chips, the opener chip and the key legend. - *Check (code):* applying a new keymap calls the palette's rebind method, which rebuilds the opener, the legend and the rows. - *Reference:* Editora `CommandPalette.refreshBindings`, called from `SettingsReapply`. ## QuickOpen picker (QOPEN) https://pauta-project.dev/2.0.0/templates/quick-open/: The family's list picker: the palette card with a title and a prompt, for choosing one thing from a list by typing. ### Rules - **QOPEN-01 · SHOULD.** One picker serves every list choice: recent files, themes, keymaps, a setting's values, a branch to compare with. - *Check (code):* those choices are instances of one generic picker class; there is no second list-picker class or `ChoiceDialog` for them. - *Reference:* Editora `ui/QuickOpen.java` (one generic class, instantiated more than seventy times), driven by `PickerKeys`. - **QOPEN-02 · SHOULD.** The picker is the palette's card in the shared in-scene overlay host, with a title naming the command over the field and a prompt in the field; never a `javafx.stage.Popup`. - *Check (code):* the picker shows its card through the overlay host and sets a title and a prompt text. - *Reference:* Editora `QuickOpen.setOverlayHost`, `ui/OverlayHost.java`; the Spec table below. ### Behavior - **QOPEN-03 · SHOULD.** The items are read fresh on every showing and snapshotted, so typing filters a stable list. A source that answers late (an outline the language server has not returned yet) calls `reload()`. - *Check (code):* `show` calls the items supplier; `reload` re-reads it and keeps the query. - *Reference:* Editora `QuickOpen.show`, `QuickOpen.reload`. - **QOPEN-04 · SHOULD.** With nothing typed the list keeps the supplier's own order (recency for recent files, document order for symbols), with the current value pre-selected when there is one. - *Check (code):* the empty query passes the items through unsorted and selects the `setCurrentItem` value. - *Reference:* Editora `QuickOpen.filter`, `setCurrentItem`. - **QOPEN-05 · SHOULD.** Typing ranks by fuzzy score, and ties keep the supplier's order, so rows do not shuffle under the cursor between keystrokes. - *Check (code):* the sort's last tiebreak is the supplier's index. - *Reference:* Editora `QuickOpen.filter`. - **QOPEN-06 · SHOULD.** The active keymap's line and page chords (`nav.lineDown`, `nav.pageUp`, …) move the selection, as do ↑ ↓, Page Up/Down and `Ctrl+Home`/`Ctrl+End` (`Cmd` on macOS), which always work; plain Home and End stay with the field's caret. Enter or a click on a row chooses; the card hides first, then the choice runs, so focus is already back where it belongs. - *Check (code):* the accept path hides the card before it calls the choice handler. - *Reference:* Editora `QuickOpen` (`hide()` then `onChoose`), `PickerKeys.resolve`. - **QOPEN-07 · SHOULD.** Esc, `C-g` or a click on the scrim cancels, and the host restores focus. A picker that previewed something undoes it. - *Check (test):* a test previews a row, dismisses the picker and finds the preview undone. - *Reference:* Editora `OverlayHost` (`previousFocus`), `QuickOpenPreviewFxTest` (`dismissingRestoresWhatWasPreviewed`). - **QOPEN-08 · MAY.** A picker previews the highlighted row as the selection moves and undoes the preview on cancel (Recent Locations shows each place and returns to the origin on Esc). A preview without an undo is worse than none, and nothing is previewed for the row the picker opens on, only for one the user moved to. The theme and keymap pickers do not preview; they apply on Enter. - *Check (test):* opening previews nothing, moving previews, choosing does not restore. - *Reference:* Editora `QuickOpen.setPreview(onPreview, onCancelled)`, `QuickOpenPreviewFxTest`. - **QOPEN-09 · MAY.** A row action acts on the highlighted row and keeps the picker open (the breakpoints picker enables or removes one), re-reading the list afterwards and keeping the cursor in place. - *Check (test):* a row action runs on the highlighted row and the picker stays up. - *Reference:* Editora `QuickOpen.addRowAction(key, legend, action)`, `QuickOpenPreviewFxTest` (`aRowActionActsOnTheHighlightedRowAndKeepsThePickerOpen`). - **QOPEN-10 · SHOULD.** A picker that can open on an empty list shows a placeholder sentence in it, never a blank card. A picker with nothing to offer may instead say so in the status line and not open. - *Check (code):* each picker whose source can be empty either calls `setPlaceholder` or returns before `show` with a status message. - *Reference:* Editora `QuickOpen.setPlaceholder` (`BreakpointsPicker`); `NavigationCoordinator` (`status.nav.noRecentLocations`). - **QOPEN-11 · SHOULD.** The host shows one card at a time; opening a picker replaces whatever card was up. - *Check (code):* the host's `show` removes the previous card before it adds the new one, and keeps the original focus owner. - *Reference:* Editora `OverlayHost.show`. - **QOPEN-12 · SHOULD.** The picker's relatives move, accept and cancel with the same keys as the picker. - *Check (code):* each relative maps its keys through `PickerKeys`. - *Reference:* Editora `Switcher`, `FileFinder`, `MultiSelectPicker`, `BranchPopup`, `GitStashPopup`. ## Welcome page (WELC) https://pauta-project.dev/2.0.0/templates/welcome/: The family's start page: Start actions with their chords, recent items a digit away, Customize and Help, shown when there is nothing to restore. ### Rules - **WELC-01 · SHOULD.** An app that opens files or projects shows a Welcome page when there is no session to restore. - *Check (code):* startup with nothing restored opens the Welcome page. - *Reference:* Editora `ui/WelcomePane.java`, `MainController.addWelcomeTab`. - **WELC-02 · SHOULD.** An app whose window *is* its content shows its own empty state instead, with the same ingredients: the ways in, each with its chord. - *Check (by hand):* start the app with nothing in it and read the empty state's keys. - *Reference:* Torrenta `ui/Welcome.java` (see In the apps below). ### Behavior - **WELC-03 · SHOULD.** The page is shown at startup when there is no session to restore (so always with `--no-session`), by the `view.welcome` command (Help → Welcome Page), and when the tab strip is empty after a project swap. Standalone diff startup suppresses it while its worker reads the files. - *Check (code):* those three paths open the one Welcome tab; the diff startup holds a flag that skips it. - *Reference:* Editora `MainController.addWelcomeTab`, `showWelcomeIfNoTabs`; `WindowSessionCoordinator` (`suppressWelcome`). - **WELC-04 · SHOULD.** Closing the last file tab does not bring the page back. The editor area shows its own quiet hint instead: Open File, Open Folder, Command Palette and Welcome Page, each with its chord, and takes focus so chords still reach the window. - *Check (test):* closing the last tab shows the hint and opening a tab hides it. - *Reference:* Editora `ui/EditorEmptyState.java`, `EditorEmptyStateFxTest`. - **WELC-05 · SHOULD.** The page is rebuilt on every show, so the recents, the Projects and Git toggles, the keymap and the theme are current. A refresh keeps the focus where it was. - *Check (code):* showing the page calls `refresh`, which re-requests focus when the page had it. - *Reference:* Editora `WelcomePane.refresh`. - **WELC-06 · SHOULD.** The recent lists offer no file that no longer exists and no project whose root is gone. Remote files are kept unchecked. - *Check (code):* the recent files pass through the same filter as the toolbar's dropdown; projects are kept only when their root is a directory. - *Reference:* Editora `RecentFiles.showable`, `WelcomePane`. - **WELC-07 · SHOULD.** Remove from recent files asks first, through the caller, then refreshes the page. - *Check (code):* the remover the page is given shows a confirmation before it removes the entry. - *Reference:* Editora `WelcomePane.setRecentRemover`; `MainController` (`dialog.removeRecent.*`). - **WELC-08 · SHOULD.** The digits 1 to 9 open the numbered entries: typed characters only, with no modifier, so chords and Enter are untouched. - *Check (code):* the digit handler is on `KEY_TYPED` and ignores Ctrl, Alt and Meta. - *Reference:* Editora `WelcomePane.onKeyTyped`. - **WELC-09 · SHOULD.** Saved SFTP sites appear as their own section; a click opens the connection form prefilled. The section is hidden when there are none. - *Check (code):* the page adds a Remote Sites section only when the saved-sites list is not empty. - *Reference:* Editora `WelcomePane` (`remoteSites`, `welcome.remote`). - **WELC-10 · SHOULD.** Customize runs `keymap.select` and `theme.setAppTheme`; a change made there re-renders the page, chords included. - *Check (code):* the Customize links run those two commands. - *Reference:* Editora `WelcomePane` (`customizeRow`). - **WELC-11 · SHOULD.** The Welcome tab is not a document: its menu is Close only, with no Save, Rename or Pin, and the title bar shows the app or project name, not a file. - *Check (code):* the Welcome tab's context menu holds one Close item. - *Reference:* Editora `MainController.addWelcomeTab`. ## About window (ABOUT) https://pauta-project.dev/2.0.0/templates/about/: The family's About panel: identity, update status, license, links and copyable environment details. ### Rules - **ABOUT-01 · MUST.** Every app has an About window, reached by Help → About, the `help.about` command, and on macOS the application menu's About item. - *Check (code):* `help.about` is registered and listed in the Help menu, and the macOS application menu's About item runs it. - *Reference:* Editora `ui/AboutDialog.java`, `ui/MenuBarModel.java` (`help.about` in the Help menu). - **ABOUT-02 · MUST.** About shows the version and build, the Pauta edition (see below), the runtime, the license, links, and the result of the last update check. - *Check (code):* the window reads the version, build and edition from `AppInfo`, the same text as `--version`, and shows the update checker's last answer. - *Reference:* Editora `ui/AboutDialog.java`, `AppInfo`; the Spec table below. - **ABOUT-03 · SHOULD.** *Copy details* copies the environment block and leaves the window open; its label becomes "Copied". - *Check (code):* the button sits in the content, not the dialog's button bar, so pressing it can't close the window. - *Reference:* Editora `AboutDialog` (`about.copyDetails`, `about.copied`). - **ABOUT-04 · SHOULD.** The update status claims nothing before a check has answered: with no answer, or with the check switched off, it says it has not checked, never "up to date". - *Check (code):* the status falls back to the not-checked text when the checker has no result. - *Reference:* Editora `AboutDialog` (`about.notChecked`); the states below. ### Pauta edition - **ABOUT-05 · MUST.** The edition appears in two places: a link, *Built to Pauta 2.0.0*, among the others, and a line `Pauta: 2.0.0` in the environment block, right after the commit, so *Copy details* carries it. - *Check (code):* the links use the `about.pauta` key, and the environment block writes a `Pauta:` line after the commit. - *Reference:* no app yet. - **ABOUT-06 · MUST.** The link opens the edition's own address, `https://pauta-project.dev//` (for example `https://pauta-project.dev/2.0.0/`), which never changes, not `latest/`, which moves on to newer editions. - *Check (code):* the URL is built from the edition number and never contains `latest`. - *Reference:* no app yet. - **ABOUT-07 · MUST.** The number is the edition the app meets, not the newest. Moving to a newer edition means reading its changelog for new or stronger MUSTs, meeting them, then changing the number. - *Check (by hand):* audit the app against the MUSTs of the edition it names. - *Reference:* no app yet. - **ABOUT-08 · MUST.** The edition has one source: a `pauta.version` property in `pom.xml`, filtered into `build-info.properties` and read by `AppInfo`, like the app's own version. The README's Pauta badge and its "Built to" line name the same edition and change with it. - *Check (code):* `pom.xml` defines `pauta.version`, `build-info.properties` carries it, `AppInfo` reads it, and the README names the same number. - *Reference:* no app yet. ## Confirm dialog (CONF) https://pauta-project.dev/2.0.0/templates/confirm-dialog/: The family's question before a destructive action: it names the thing, the button names the action in red, and Escape cancels. ### Rules - **CONF-01 · MUST.** Before anything the user made is removed, deleted, discarded or overwritten, the app asks first, unless the action can be taken back instead. - *Check (code):* each destructive action calls a confirmation before it changes anything, or records an undo. - *Reference:* Editora `ui/CloseCoordinator.java` (unsaved changes, Quit) and `GitCoordinator.confirmDestructive`; Torrenta `ui/RemoveConfirm.java`, which asks it for the torrent list, the RSS tab and every list in Settings. - **CONF-02 · MUST.** The question names the thing and what happens to it. - *Check (code):* every confirmation string names the thing, by an argument for its name or count or in its own words ("Quit Editora?"), and says what happens to it. - *Reference:* Editora `dialog.unsaved.header`, `dialog.discard.tracked`; Torrenta `RemoveConfirm.question`, `Actions.removeQuestion`. - **CONF-03 · MUST.** The confirming button carries the action's own verb (Delete files, Remove, Discard, Quit), never OK or Yes, in the `danger` style. - *Check (code):* the action's `ButtonType` is named from the catalog and its button gets the `danger` style class. - *Reference:* Editora `GitCoordinator.confirmDestructive`, `MainController.styleUnsavedChangesButtons`, `styleQuitButtonAsDanger`; Torrenta `RemoveConfirm.ask`. - **CONF-04 · MUST.** Cancel is the way out: Escape and the window's close button both answer Cancel, and nothing is lost on a dismissal. - *Check (code):* Cancel has the `CANCEL_CLOSE` role, and the result defaults to Cancel when the dialog closes any other way (`showAndWait().orElse(cancel)`). - *Reference:* Editora `GitCoordinator.confirmDestructive`, `CloseCoordinator.unsavedAlert`; Torrenta `RemoveConfirm.ask`. ### States - **CONF-05 · SHOULD.** When saving is an option the question has three answers, in this order: Save (the `success` style, green), Discard (`danger`) and Cancel. A Save that fails leaves the tab open. - *Check (code):* the unsaved-changes alert sets Save, Discard and Cancel in that order and styles the first two. - *Reference:* Editora `CloseCoordinator.unsavedAlert`, `MainController.styleUnsavedChangesButtons`. - **CONF-06 · SHOULD.** A question about ending a running program, which is not the user's data, words the button Close and makes Cancel the default button, so dismissing the dialog by any route keeps the program alive. - *Check (code):* the close-running-program alert calls `setDefaultButton(true)` on Cancel. - *Reference:* Termina `ui/TerminalWindow.java` (`dialog.closeAnyway`). - **CONF-07 · SHOULD.** Where the action can be taken back, the app asks nothing and offers Undo instead. - *Check (by hand):* close a clean tab and reopen it with Reopen Closed Tab; in Mirada, trash an image and undo. - *Reference:* Mirada moves an image to the trash at once and offers Undo; Torrenta asks before removing a torrent but also keeps the removal on its undo stack for ten minutes (`UndoStack.KEEP_MS`); Editora `ClosedTabs`. ### Behavior - **CONF-08 · SHOULD.** The question comes before anything changes, and the action runs only on the action button. - *Check (code):* the helper returns true on the action button alone, and the caller acts only on true. - *Reference:* Torrenta `RemoveConfirm.ask`; Editora `GitCoordinator.confirmDestructive`. - **CONF-09 · SHOULD.** One gesture asks one question. An action on many things asks once with the count ("Remove these 3 torrents?", Torrenta's "Apply to many torrents" for a bulk command). Closing every tab asks per unsaved buffer, selecting each tab first so the user sees what the question is about, and remembers a Discard answer for exactly the state that was shown. - *Check (code):* a bulk command builds one question with a plural count; the close-all sweep selects each tab before it asks. - *Reference:* Torrenta `Actions.removeQuestion`; Editora `CloseCoordinator.confirmSweep`. - **CONF-10 · SHOULD.** A delete that cannot be undone says so; one that leaves the files says that instead. - *Check (code):* "This cannot be undone." appears only in the strings of actions that cannot be undone. - *Reference:* Editora `dialog.discard.tracked`; Torrenta `actions.removeQuestion.delete`. - **CONF-11 · SHOULD.** A dangerous alternative (Force with Lease, Delete Anyway) is offered beside the safe one (Pull, then Push), in red, and only once the safe one has failed. - *Check (code):* the force path is reached only from the safe command's failure result. - *Reference:* Editora `GitBranchCoordinator.offerAfterRejection` (Force with Lease after a rejected push), `confirmForceDelete` (Delete Anyway after `NOT_FULLY_MERGED`). - **CONF-12 · SHOULD.** The question can be tested without a screen: its words come from pure code, and a capture hook answers the dialog, so a UI test never presses a native button. - *Check (test):* a unit test covers the header and question for every kind, and UI tests set the capture answer. - *Reference:* Torrenta `RemoveConfirm.header`, `question`, `answerForCapture`; `RemoveConfirmTest`. ## Find bar (FIND) https://pauta-project.dev/2.0.0/templates/find-bar/: The family's find bar: in-scene, incremental, with a count; Enter and Shift+Enter step, Escape gives the keyboard back. ### Rules - **FIND-01 · MUST.** Wherever there is text to search, the app has a find bar that is part of the window, never a popup. - *Check (code):* the bar is a node in the window's scene graph (docked or floating); no `Popup` or `Stage` is created for it. - *Reference:* Editora `ui/FindReplaceBar.java` (the editor's find and replace), with `ui/ConsoleFindBar.java` and `ui/TerminalFindBar.java` as the same shape over a console and a terminal; Termina `ui/SearchBar.java`. - **FIND-02 · MUST.** The bar searches as you type and shows a match count. - *Check (code):* the query field's text listener runs the search (debounced) and updates the count label. - *Reference:* Editora `FindReplaceBar` (`debounce`, `find.count`); Termina `SearchBar` (`search.count`). - **FIND-03 · MUST.** A list app filters instead of finding, with the same field and the same Escape. - *Check (code):* the list's filter field filters as it is typed, and Escape in it empties it or gives focus back to the list. - *Reference:* Torrenta `Omnibox`, `FilterQuery`, `MainWindow.onOmniboxKey`. ### Behavior - **FIND-04 · SHOULD.** The find command (`find.show`) opens the bar: `C-s` in the Emacs keymap and `Ctrl/Cmd+F` in CUA, Sublime, VS Code and IntelliJ, with `F3` as well in CUA and Sublime. A terminal uses `Ctrl+Shift+F`, `Cmd+F` on macOS, since a plain `Ctrl+letter` belongs to the shell. The command while the bar is already open finds the next match (Editora) or puts the caret back in the field (Termina). - *Check (code):* each bundled keymap binds that chord to the find command; the command steps when the bar is shown. - *Reference:* Editora `keymaps/*.json`, `MainController.findShowOrNext`; Termina `TerminalWindow` (`menu.find`, `MenuAction.appChord`). - **FIND-05 · SHOULD.** Typing highlights every match and selects and scrolls to the first one at or after the caret. The anchor is the caret at open time, so refining the query does not run away down the document. - *Check (code):* the search starts from an anchor saved when the bar opens, not from the current selection. - *Reference:* Editora `FindReplaceBar` (`searchAnchor`, `recompute`). - **FIND-06 · MUST.** Enter steps to the next match and Shift+Enter to the previous one, wrapping around at the ends. In a terminal the directions are up and down the scrollback. - *Check (code):* the query field's key handler steps forward on Enter and backward on Shift+Enter. - *Reference:* Editora `ConsoleFindBar`, `TerminalFindBar`; Termina `SearchBar`. Editora's editor bar (`FindReplaceBar`) does not yet: its field steps forward on Enter, and back only with the previous button, `find.showBackward` (`C-r`, `Shift+F3`) or `find.previous`. Alt+Enter there turns every match into a caret. - **FIND-07 · MUST.** Escape or the close button closes the bar: the highlights go, a search still pending is canceled so nothing moves after the bar is gone, and focus returns to the editor, the console or the shell. - *Check (code):* the close path stops the debounces, cancels the running search, clears the highlights and focuses the text it searched. - *Reference:* Editora `FindReplaceBar.hideBar`. - **FIND-08 · SHOULD.** In a terminal, Escape is consumed in the field and never reaches the shell, and the terminal's own key and mouse filters leave every event aimed at the bar alone. - *Check (code):* the field consumes Escape, and the terminal's filters return early for events from the bar. - *Reference:* Termina `SearchBar`, `TerminalView.fromSearchBar`. - **FIND-09 · SHOULD.** The keymap's caret and editing chords (`C-a`, `C-e`, `C-k`, `C-y`, `Ctrl+V/X/C/Z`) act on the field, not on the document. Find's own chords stay global, so next, previous, replace and close work while the field has focus. - *Check (code):* the find fields install the shared text-input keymap. - *Reference:* Editora `TextInputKeymap.installShared`; Termina's and Mirada's `TextInputKeys`. - **FIND-10 · SHOULD.** Nothing found is one status-line message ("Not found: x") or the count "No matches". No beep, no dialog. - *Check (code):* the no-match path sets `find.notFound` or `search.none` and opens nothing. - *Reference:* Editora `FindReplaceBar` (`find.notFound`); Termina `SearchBar` (`search.none`). - **FIND-11 · SHOULD.** Replace keeps each match's case when *AB* (preserve case) is on. - *Check (test):* a test replaces with preserve case on and finds each match's casing kept. - *Reference:* Editora `FindReplaceBarFxTest` (`preserveCaseFollowsEachMatchesCasing`). - **FIND-12 · SHOULD.** A replacement that is too slow stops with "Replace stopped: the pattern is too slow" instead of hanging the window. - *Check (test):* a catastrophic regex in Replace All aborts. - *Reference:* Editora `find.replaceTimeout`, `FindReplaceBarFxTest` (`catastrophicRegexInReplaceAllAbortsInsteadOfHanging`). - **FIND-13 · SHOULD.** A list app's filter box filters the names as plain words are typed, turns `key:value` terms into chips and runs a command after `>`. `Ctrl+K` focuses it and is drawn in the box as a key badge. - *Check (code):* the box's text listener filters, and its badge is read from the filter command's chord. - *Reference:* Torrenta `Omnibox`, `MainWindow.buildFilterBar`. - **FIND-14 · SHOULD.** Escape in a filter box peels one layer: a box with something in it empties, an empty one gives the list back. - *Check (code):* the box's Escape handler clears a non-empty box and otherwise focuses the list. - *Reference:* Torrenta `MainWindow.onOmniboxKey`. - **FIND-15 · SHOULD.** The filter box is out of the Tab order, so a fresh launch does not land every keystroke in it, and the window's own chords (undo, `Ctrl+Alt+1…9`) do not fire while a text field has focus: `Ctrl+Z` there is the field's own undo. - *Check (code):* the box is not focus-traversable, and the window's chord handlers return early when the focus owner is a `TextInputControl`. - *Reference:* Torrenta `MainWindow.buildFilterBar`, `MainWindow` window chords. ## Message Log (MLOG) https://pauta-project.dev/2.0.0/templates/message-log/: The family's Message Log: the session's status-bar messages, newest first, opened from the status bar. ### Rules - **MLOG-01 · MUST.** Every app with a status bar keeps a Message Log: the session's status-bar messages, newest first, opened from the status bar. - *Check (code):* every status-bar message is also added to one log model, and a view lists that model. - *Reference:* Editora `ui/MessageLog.java` (the model, no JavaFX) and `ui/MessageLogPopup.java` (the view); Torrenta carries the same pair. ### Behavior - **MLOG-02 · SHOULD.** A click on the echo line or on the unread-error count opens the log, as does the `view.messageLog` command. - *Check (code):* both status-bar nodes run `view.messageLog` on a click. - *Reference:* Editora `StatusBar` (`echo`, `unreadErrors`), `StatusBar.showMessageLog`. - **MLOG-03 · SHOULD.** Esc, `C-g` or a click outside closes the log. - *Check (code):* the card's key handler hides it on Escape and `C-g`; the overlay's backdrop hides it on a press. - *Reference:* Editora `MessageLogPopup`, `OverlayHost`. - **MLOG-04 · SHOULD.** `Ctrl+C` (`Cmd+C` on macOS) copies the selected entries. - *Check (code):* the card's key handler copies the selection on the shortcut-down C. - *Reference:* Editora `MessageLogPopup.copySelection`. - **MLOG-05 · SHOULD.** A message's severity comes from its key: a `status.*` key whose last segment contains `fail` or `error` is an error, one containing `cannot` or `invalid` a warning. Name new keys accordingly, or report through the error channel directly. - *Check (test):* a severity test classifies keys by those rules. - *Reference:* Editora `ui/StatusSeverity.java` (`ofKey`), `StatusSeverityTest`. - **MLOG-06 · SHOULD.** Opening the log, or clearing it, resets the unread-error count. - *Check (code):* opening the log marks it read, and `clear` zeroes the count. - *Reference:* Editora `MessageLog.markRead`, `MessageLog.clear`, `StatusBar.showMessageLog`. - **MLOG-07 · SHOULD.** An unread error is never evicted silently: the count keeps it even when the entry drops off the end. - *Check (test):* an error pushed past the capacity still counts as unread. - *Reference:* Editora `MessageLogSeverityTest` (`anEvictedErrorStillCounts`). ## Settings Sync (SYNC) https://pauta-project.dev/2.0.0/templates/settings-sync/: The family's Sync settings page: keep user data the same on every computer through a Git repository the user owns. ### Rules - **SYNC-01 · SHOULD.** An app with user data worth carrying between computers offers Settings Sync, on a page of its own in the Settings window that the Settings search finds by "sync". - *Check (by hand):* open Settings, search "sync", and land on the Sync page. - *Reference:* Editora `ui/SettingsSync.java` (the service) and `ui/SettingsSyncPage.java`, built by `SettingsWindow` (`Category.SYNC`). - **SYNC-02 · SHOULD.** The store is a Git repository the user owns, reached through their own Git credentials (a credential helper or an SSH key), with no server or account of ours. A URL with a password or token in it is refused. - *Check (code):* the sync package runs `git` against the user's URL, and the page refuses a URL with credentials in it. - *Reference:* Editora `sync/` package (`SyncEngine`, `SyncMerge`, `SyncAccount`), `SyncEngine.hasCredentials`; Termina carries the same package, Torrenta its own `sync/` with `SyncEngine` and `SyncAccount`; the Spec table below. ## Packaging, signing and release (REL) https://pauta-project.dev/2.0.0/release/: jpackage, JReleaser, the five-target matrix, macOS/Linux/Windows signing and CI. ### Targets - **REL-01 · MUST.** jpackage builds the installers for the five targets in the table above, each on its own runner, through the Maven `dist` profile. - *Check (code):* the release workflow's build matrix lists `linux-x64`, `linux-arm64`, `macos-arm64`, `macos-x64` and `windows-x64` on those runners, and `pom.xml` has a `dist` profile. - *Reference:* Editora `release.yml` (the `build` job), `pom.xml` (`dist`). - **REL-02 · SHOULD.** Downloads are named `--.`. - *Check (code):* the release-asset check builds the expected names this way. - *Reference:* Editora `scripts/release/CheckRelease.java` (`expectedAssets`). - **REL-03 · MUST.** **JReleaser** (`jreleaser.yml`) only creates the GitHub release: it builds nothing, and attaches every file and `checksums_sha256.txt`. - *Check (code):* `jreleaser.yml` attaches the build matrix's files and runs after the build jobs. - *Reference:* Editora `jreleaser.yml`, the `release` job in `release.yml`. - **REL-04 · SHOULD.** The release notes are the version's section of `CHANGELOG.md`. - *Check (code):* the release job hands JReleaser that section as the changelog. - *Reference:* Torrenta `scripts/release/ReleaseNotes.java`. Editora's release notes are still its commit list. - **REL-05 · MUST.** The Maven version is the single source of truth: a tag `vX.Y.Z` releases the version in `pom.xml`. - *Check (code):* the release workflow fails when the tag and the pom version differ. - *Reference:* Editora's "Check the tag against the pom version" step in `release.yml`. - **REL-06 · SHOULD.** `master` carries a `-SNAPSHOT` version, and a post-release job opens the pull request that bumps it to the next snapshot. - *Check (code):* the pom's version on `master` ends in `-SNAPSHOT`, and `release.yml` has the bump job. - *Reference:* Editora's `bump` job in `release.yml`. - **REL-07 · SHOULD.** A **release-asset check** fails the run before publishing when an expected file is missing. - *Why:* GitHub releases are immutable. - *Check (code):* a step before JReleaser compares the gathered files with the expected list. - *Reference:* Editora's "Verify the expected release assets" step in `release.yml`. - **REL-08 · SHOULD.** On Linux, a `.desktop` file's `StartupWMClass` is the JavaFX app class. - *Why:* the running window then belongs to the menu entry and shows its icon. - *Check (code):* `packaging/linux/.desktop` sets `StartupWMClass=com..App`. - *Reference:* Editora `packaging/linux/Editora.desktop`, Torrenta `packaging/linux/Torrenta.desktop`. - **REL-09 · SHOULD.** On Linux, AppStream metainfo has the id `io.github.adriandeleon.`. - *Check (code):* `packaging/linux/io.github.adriandeleon..metainfo.xml` carries that ``. - *Reference:* Torrenta `packaging/linux/`. Editora's metainfo id (`com.editora.Editora`) predates the rule. - **REL-10 · SHOULD.** Packaging trains an **AOT cache** (JDK 25 Leyden) to cut start-up time; Linux legs run the training under `xvfb`. - *Check (code):* the `dist` build runs a training launch with `-XX:AOTCacheOutput`, and the Linux release legs install `xvfb`. - *Reference:* Editora `scripts/aot_build.java`. ### Install methods - **REL-11 · MUST.** The GitHub release offers every download on every platform: the `.dmg`, `.msi`, `.deb`, `.rpm`, `.AppImage` and `.tar.gz`, with checksums. - *Check (code):* `jreleaser.yml` attaches each of these types. - *Reference:* Editora `jreleaser.yml`. - **REL-12 · SHOULD.** On macOS (Apple Silicon) the app installs with `brew install --cask adriandeleon/tap/`: JReleaser's `brew` packager writes the cask to [`adriandeleon/homebrew-tap`](https://github.com/adriandeleon/homebrew-tap). A cask takes exactly one artifact, so it serves Apple Silicon, and Intel Macs use the `macos-x64` DMG. - *Why:* the official homebrew-cask repository has notability rules a new project does not meet, so the family shares one personal tap. - *Check (code):* `jreleaser.yml` has a `brew` packager for that tap; `jreleaser package --basedir .` writes the cask locally, to check it without releasing. - *Reference:* Torrenta and Termina `jreleaser.yml`; Editora has no packager yet. - **REL-13 · SHOULD.** On Windows x64 the app installs with `winget install AdrianDeLeon.`: JReleaser's `winget` packager opens a pull request on [`microsoft/winget-pkgs`](https://github.com/microsoft/winget-pkgs) from the `adriandeleon` fork. The package identifier is `AdrianDeLeon.`, the moniker the app's lower-case name. - *Check (code):* `jreleaser.yml` has a `winget` packager with that identifier; `jreleaser package --basedir .` writes the manifests locally. - *Reference:* Torrenta and Termina `jreleaser.yml`; Editora has no packager yet. - **REL-14 · SHOULD.** Both packagers read a `PACKAGES_TOKEN` secret, a classic personal access token with `repo` scope. Without it JReleaser skips both, and the GitHub release still publishes. - *Why:* the workflow's own token cannot write to the tap or open a pull request on the fork. - *Check (code):* `release.yml` passes `PACKAGES_TOKEN` to JReleaser and leaves the packagers out when it is empty. - *Reference:* Torrenta and Termina `release.yml`. ### Signing - **REL-15 · MUST.** The macOS `.dmg` is signed with the Developer ID Application certificate (team 8JKSF797L8), with the hardened runtime and per-app entitlements, notarized with `notarytool`, stapled and checked with `spctl`; then the notarized app is launched once. - *Check (code):* `release.yml` imports `MACOS_CERT_P12` and `MACOS_CERT_PASSWORD`, notarizes with `APPLE_API_KEY_P8`, `APPLE_API_KEY_ID` and `APPLE_API_ISSUER`, staples, runs `spctl` and launches the app. - *Reference:* Editora's "Import signing certificate (macOS)" and "Notarize DMG (macOS)" steps in `release.yml`, `packaging/macos/Editora.entitlements`. Done in all six apps. - **REL-16 · MUST.** Linux downloads are signed with the one shared OpenPGP release key ("Adrian De Leon (release signing)") in a separate `sign-linux` job: `rpmsign` for the `.rpm`, a debsigs origin signature for the `.deb`, and an armored `.asc` beside every file. The public key is committed as `packaging/linux/signing-key.asc` and attached to each release. - *Check (code):* `release.yml` has a `sign-linux` job that reads `LINUX_GPG_KEY` and `LINUX_GPG_PASSPHRASE` and runs the shared scripts, and `packaging/linux/signing-key.asc` exists. - *Reference:* Editora `scripts/release/sign-linux-packages.sh`, `scripts/release/check-linux-signatures.sh`. Done in Editora, Torrenta, Termina and Modula; Mirada partly; nux not yet. - **REL-17 · SHOULD.** The Windows `.msi` is signed with Authenticode, once the certificate is chosen. - *Check (code):* the Windows leg signs the `.msi` before it is uploaded. - *Reference:* no app yet. **Open decision**: SignPath Foundation (free for OSS), a Certum Open Source certificate, or Azure Trusted Signing. Until then MSIs are unsigned and SmartScreen warns. - **REL-18 · MUST.** Every download has a GitHub **build provenance attestation** (`actions/attest-build-provenance`), which `gh attestation verify` checks. - *Check (test):* a test keeps the attested files and the files JReleaser attaches the same list. - *Reference:* Editora's "Attest build provenance" step in `release.yml`, `ReleaseSupplyChainTest`. Done in Editora, Termina and Mirada. ### CI/CD (GitHub Actions) - **REL-19 · MUST.** `ci.yml` runs on every push to `master` and every pull request: **Format** (`spotless:check`) and **Build & Test** (`./mvnw verify`, coverage gate included) on JDK 25. Both are required status checks for `master`. - *Check (code):* `ci.yml` triggers on `push` to `master` and on `pull_request`, with the two jobs; the repository's rules for `master` require both. - *Reference:* Editora `ci.yml`. - **REL-20 · SHOULD.** `full-tests.yml` runs the full suite on Linux, macOS and Windows daily, on a pull request labeled `full-ci`, and before every release, and lists flaky tests in the job summary. - *Check (code):* `full-tests.yml` has a `schedule` and a `pull_request` trigger gated on the label, and the release preflight waits for its run on the tagged commit. - *Reference:* Editora `full-tests.yml`, `scripts/ci/ReportFlakes.java`, and the "Check that the Full tests passed on this commit" step in `release.yml`. - **REL-21 · MUST.** `release.yml` runs on a `v*` tag that matches the pom version, with `workflow_dispatch` as a dry run. It runs the five-target matrix, the signing jobs, attestations, the release-asset check, JReleaser, then the bump to the next snapshot. A dry run builds and signs and publishes nothing. - *Check (code):* `release.yml` triggers on the tag pattern and `workflow_dispatch`, and a dispatch runs JReleaser with `--dry-run`. - *Reference:* Editora `release.yml`. - **REL-22 · MUST.** Every workflow pins each third-party action to a commit SHA, with its version in a comment (`actions/setup-java@b843ebf… # v6.1.0`). - *Check (code):* every `uses:` in `.github/workflows/` ends in a 40-character SHA and a `# vX.Y.Z` comment. - *Reference:* Editora `.github/workflows/`. - **REL-23 · MUST.** Dependabot updates `github-actions` and `maven` weekly. - *Check (code):* `.github/dependabot.yml` lists both ecosystems with `interval: weekly`. - *Reference:* Editora `.github/dependabot.yml`. - **REL-24 · MUST.** Every workflow starts from `permissions: contents: read`; only a job that needs write access asks for it, in its own block. - *Check (code):* each workflow's top-level `permissions` is `contents: read`, and every `write` sits in a job's own `permissions`. - *Reference:* Editora `release.yml`: `release` (publish), `bump` (the pull request) and `preflight` (start a Full tests run). - **REL-25 · SHOULD.** Every workflow sets up JDK 25 with `actions/setup-java` and `cache: maven`. - *Check (code):* each `setup-java` step has `java-version: '25'` and `cache: maven`. - *Reference:* Editora uses Temurin in `ci.yml` and `full-tests.yml`, and Liberica for the release build, for linux-aarch64 coverage. - **REL-26 · MUST.** Every job has `timeout-minutes`, and `concurrency` cancels a superseded pull-request run, never a run on `master`. - *Check (code):* every job sets `timeout-minutes`; `cancel-in-progress` is true only for `pull_request` events. - *Reference:* Editora `ci.yml` (`cancel-in-progress: ${{ github.event_name == 'pull_request' }}`). - **REL-27 · MUST.** CI uploads the surefire reports even when tests fail, and the JaCoCo report; it writes the coverage totals to the job summary. - *Check (code):* the test reports upload under `if: always()`, and a step appends the totals to `$GITHUB_STEP_SUMMARY`. - *Reference:* Editora's "Upload test reports and coverage data" and "Summarise coverage" steps in `ci.yml`. - **REL-28 · MUST.** Signing skips cleanly when the secrets are absent (forks, dry runs), so they still build; a tag without them fails. - *Check (code):* each signing step checks its secrets first, skips without them, and fails on a tag push. - *Reference:* Editora's "Import signing certificate (macOS)" step checks `MACOS_CERT_P12` first. - **REL-29 · MUST.** The packaged app is launched once on each OS before a release (a smoke test). - *Check (code):* `release.yml` runs the packaged launcher on every target before JReleaser. - *Reference:* Torrenta's "Smoke-test the packaged app" step runs the launcher in every target's image. Editora runs only the notarized macOS app (`--version`, `--check-terminal`).