# Pauta 6.0.0: every rule > 405 rules from https://pauta-project.dev/6.0.0/, published 2026-11-10. Each page's prose, screenshots and mockups are on > the page itself (as Markdown at the page's address with `.md` for the trailing `/`); this file holds the rules alone. ## Using Pauta **Starting a new app:** create it from the GitHub template repository https://github.com/adriandeleon/adl-desktop-app-template (`gh repo create --template adriandeleon/adl-desktop-app-template`, or **Use this template** on GitHub), then run `scripts/rename.sh `. It is built to the edition its README and AGENTS.md name; audit it against this edition and add what is missing. **Building a feature:** read its page first (`.md`, below, has the prose, the rules and the spec tables), then copy from the code each rule's *Reference* names. Editora is the reference implementation. **Auditing an app:** the full procedure is the pauta-audit skill, https://pauta-project.dev/6.0.0/skills/pauta-audit/SKILL.md. It decides how to audit and how to write the report; an edition supplies only its rules. In short: 1. Find the edition the app implements: `pauta.version` in its `pom.xml`, or failing that its README. Read that edition's rules at `https://pauta-project.dev//rules.json`. If the app names none, ask which edition to audit against and offer the newest; with no one to ask, use the newest and say so in the report. Editions before 2.0.0 serve no rules.json: audit against 2.0.0 or newer, and report a failed rule that the app's own edition didn't have as upgrade work. 2. Take each rule in turn. *Check (code)*: when it has a *Command* (`check.command`), run it with `sh -c` from the app's repository root. Exit 0: the check passes; still read the rest of the rule and cite the file:line that meets it. Any other exit: the check fails, and what it printed is the evidence. Otherwise read or search the source as the check says: a search written inside the check's text lists lines to judge, and its exit code is no verdict; a check that names a test as "the surest evidence" passes on the behavior without it. *Check (test)*: the statement requires a test; find it, or the app's equivalent, and confirm the build runs it. *Check (by hand)*: the source can't confirm it; report it as manual, unless the source plainly shows it unmet, which is `fail`. A check that needs the website's repository or a repository setting says so: read it if you can reach it, and report `not-checked` if you can't. Some names in a rule's statement are required as written: a command id, a catalog key, a chord, a command-line flag, an environment variable, a property in pom.xml or pauta.json, and a file the repository must carry (a document at its root, or a resource or tool configuration the rule names: emacs.json, jreleaser.yml). A platform API the rule names (javafx.stage.Popup, SystemTray, Future.get()) is the requirement itself. Any other name (a class, method or constant of the app's own code, a CSS file or style class, a branch or workflow file, a file the app writes as it runs), and every name only a Check or Reference gives, is Editora's spelling, and the app's equivalent meets it. 3. A rule applies to every app unless it is limited: its text names the apps it covers ("An app with user documents…"), its page or section opens with an **Applies to** line (`appliesTo` in rules.json), or it details a rule that is limited. A limited rule the app is outside of is `limited` and needs no exception. 4. Read the app's `src/main/resources/com//pauta.json`, its recorded exceptions. An unmet rule it lists gets the entry's kind as its status (not-applicable, deviation, pending, or in a template app-only); MAYs need no entry. An unmet MUST or SHOULD it doesn't list is `fail`; so is an unmet MAY, which has no consequence. An entry for a rule that passes or is limited, and a deviation or pending entry with no link, are problems to report. A by-hand rule it lists as an exception gets that kind, not `manual`. Its `checked` list, which an app may keep or not, records the by-hand rules a person checked and found met (PAUTA-18): a `manual` result carries its entry, one with none is reported as not recorded, which is not a failure, and an entry older than the rule's `changed` is stale, a problem. 5. Report one result per rule: ID, level, status and evidence as `file:line`. The statuses: `fail`, `manual`, `not-checked`, `pending`, `deviation`, `not-applicable`, `app-only`, `limited`, `pass`. As JSON, the report follows https://pauta-project.dev/6.0.0/audit.schema.json. A failed MUST blocks a release; a `manual` or `not-checked` one does not. Cite a rule by its ID and edition, for example "KBD-07 (Pauta 6.0.0)". Each rule's address is the page's plus `#` and the ID in lowercase: `https://pauta-project.dev/6.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. ## Same on every OS (OS) https://pauta-project.dev/6.0.0/same-on-every-os/: The one list of places where Windows, macOS and Linux may differ, and the rules that keep everything else the same. ### Rules - **OS-01 · MUST.** Every command, setting and window exists on Windows, macOS and Linux, with the same default. Where the OS can't do what one asks, it stays where it is, disabled, and says why; it is never hidden. The only exceptions are the rows of the table under [Where the OS's way wins](https://pauta-project.dev/6.0.0/same-on-every-os/#where-the-oss-way-wins), on the page Same on every OS: the places where the app hands work to the OS or sits in the OS's own interface, such as the macOS application menu and the macOS form of a keymap's chords. - *Why:* a user who moves to another OS looks for a feature where they left it. A missing row looks like a different app; a disabled one with a reason explains itself. - *Check (code):* no command, menu row or settings row is registered or added inside an OS check, and no default in the settings model depends on the OS, unless a row of the table under [Where the OS's way wins](https://pauta-project.dev/6.0.0/same-on-every-os/#where-the-oss-way-wins) gives that difference: the rows of the macOS application menu, a default chord in its macOS form. An OS check is a test whose answer can differ among Windows, macOS and Linux; a gate that holds on all three alike (a command registered only when the app finds its own launcher, whatever the OS) is not one. A row the OS can't serve calls `setDisable` and carries its reason ([KBD-04](https://pauta-project.dev/6.0.0/keyboard/#kbd-04) for a command). - *Reference:* Editora [`ui/SettingsWindow.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsWindow.java) (the extended-window row, disabled on macOS "rather than hidden, so its note still explains why"). Editora doesn't hold the rule everywhere yet: its `file.saveAsAdmin` command ([`ui/WindowCommandRegistrar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowCommandRegistrar.java)) is registered with nothing that disables it on Windows, where it can do nothing. Termina removes its `hideMenuBar` command on macOS ([`ui/TerminalWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java)). - **OS-02 · MUST.** In an app's code, one class answers which OS the app runs on (this guide calls it `Os`, with `isWindows()`, `isMac()` and `isLinux()`; the names are the app's own), and no other class reads the `os.name` property. A class that only shows the OS's name, in About or a problem report, asks that one class for it. - *Why:* checks scattered through the code are how apps drift apart on one OS without anyone choosing it. In one class, every difference can be found with one search, and a test can run the app as any OS ([OS-03](https://pauta-project.dev/6.0.0/same-on-every-os/#os-03)). - *Check (code):* `grep -rl '"os.name"' src/main/java` lists one file, the `Os` class, and no other file works out the OS for itself. The Command also lists the files that compare `File.separatorChar` or `File.pathSeparatorChar` with a character (`File.separatorChar == '\\'` for "is this Windows"), the other way Editora does it. A class that only prints the name, in About or a problem report, reads the property too, so it is listed. A grep finds only the spellings it is given: when the Command passes, still read for a test that stands in for the OS some other way, such as a separator compared as a string or an environment variable only one OS sets. - *Command:* `[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; n=$(grep -rl '"os.name"' src/main/java | wc -l); s=$(grep -rlE "eparatorChar *[!=]= *'" src/main/java | wc -l); u=$(grep -rlE "\"os[.]name\"|eparatorChar *[!=]= *'" src/main/java | wc -l); [ "$n" -eq 1 ] && [ "$u" -eq 1 ] || { echo "$n files read os.name (one Os class should):"; grep -rl '"os.name"' src/main/java; echo "$s files compare a file or path separator with a character (only that class may):"; grep -rlE "eparatorChar *[!=]= *'" src/main/java; false; }` - *Reference:* no app yet. Every app reads `os.name` in several classes, Editora in about fifty, and eleven of Editora's classes tell Windows apart by a separator, eight of them without reading `os.name` ([`lsp/JavaRuntimes.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/lsp/JavaRuntimes.java), [`dap/DapManager.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/dap/DapManager.java), [`dap/InstalledAdapter.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/dap/InstalledAdapter.java)). Editora's [`process/DesktopActions.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/process/DesktopActions.java) has the `Os` enum to start from. - **OS-03 · SHOULD.** An app's tests can run as any OS: the one class that answers which OS the app runs on ([OS-02](https://pauta-project.dev/6.0.0/same-on-every-os/#os-02); this guide calls it `Os`) takes an override, and one test asserts that the command ids, the menu bar's rows and the settings pages are the same for Windows, macOS and Linux. - *Why:* CI runs the FX tests on one or two OSes ([REL-20](https://pauta-project.dev/6.0.0/release/#rel-20)); with the override, the comparison runs on every pull request on Linux alone. - *Check (test):* a test sets each OS in turn through the override and compares the three lists. - *Reference:* no app yet. Editora's [`KeymapsTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/command/KeymapsTest.java) (`guiKeymapsBindSameCommandSetOnBothPlatforms`) does it for the keymaps. - **OS-04 · MUST.** No behavior or layout of an app differs by OS: what a command, a key or a click does, where a control sits and how a window is drawn are the same on Windows, macOS and Linux. The only exceptions are the rows of the table under [Where the OS's way wins](https://pauta-project.dev/6.0.0/same-on-every-os/#where-the-oss-way-wins), on the page Same on every OS: the places where the app hands work to the OS or sits in the OS's own interface, such as the macOS form of a keymap's chords, the system menu bar, the OS's file dialogs, trash, tray and notifications, and the shells a terminal offers. Whether a command, setting or window exists, and its default, is [OS-01](https://pauta-project.dev/6.0.0/same-on-every-os/#os-01). - *Why:* a feature can be on every OS and still act or sit differently on one: Escape that closes the window on Linux only, a title on the left on Windows only. Each is something to relearn on the next machine, which is what the family exists to spare its users. - *Check (code):* list every place the code tests the OS. They are the callers of the methods of the class [OS-02](https://pauta-project.dev/6.0.0/same-on-every-os/#os-02) asks for and, in an app that has no such class yet, every file OS-02's Command prints (the files that read `os.name`, and the files that compare `File.separatorChar` or `File.pathSeparatorChar` with a character), together with the callers of whatever those files offer other classes to ask the OS by: a method (Editora's `KeymapManager.isMac()`, which ten files call and eight of them read no `os.name` themselves) or a constant. `grep -rnE 'isMac|isWindows|isLinux' src/main/java` lists the usual names; read the printed files for the app's own. Read each place. It passes when what it changes is what a row of the table under [Where the OS's way wins](https://pauta-project.dev/6.0.0/same-on-every-os/#where-the-oss-way-wins) gives that OS, or is nothing a user can see or do (the path of a binary, a process's arguments, a line ending). It fails when it changes anything else a user can see or do: what a command, a key or a click does, where something sits, how it is drawn or what it says. A place that gives an OS something other than what its row gives is judged by the rule that row links, where that rule covers it: a Windows notification raised as the tray's balloon and not a toast fails [TRAY-09](https://pauta-project.dev/6.0.0/tray-and-background/#tray-09), not this rule. It fails this rule when the row links no rule, or the rule it links does not cover the difference (a menu bar on one OS and a menu button on the others). - *Reference:* no app has been read through for it yet. The differences found so far, each on no row or short of its row: Mirada closes its window on Escape on Linux only ([`Command.escapeCloses`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Command.java)), follows the OS's accent color on macOS and Windows only ([`Theme.followsAccent`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Theme.java)), puts its title on the left on Windows only ([`TitleBar.Layout`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/TitleBar.java)) and has a menu bar on macOS only ([`ui/MacMenus.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/MacMenus.java)); Editora deletes a file for good on Windows ([`io/Trash.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/io/Trash.java)), keeps the user's key bindings apart by OS (`keybindings` and `keybindingsMac` in [`config/Settings.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/Settings.java)) and registers its WSL targets on Windows only ([`App`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java)); Termina believes the folder a shell reports for itself on Windows only ([`ProcessCwd.reportedDirectoryWins`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/pty/ProcessCwd.java)), and its Settings Sync keeps the user's key bindings in one file for macOS and another for Windows and Linux ([`sync/KeybindingsFile.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/sync/KeybindingsFile.java)). On a row, and passing: a click that takes `Cmd` on macOS and `Ctrl` elsewhere (Editora's [`editor/EditorBuffer.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/editor/EditorBuffer.java), Termina's [`link/LinkGesture.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/link/LinkGesture.java)), and the profiles Termina lists on Windows only, Command Prompt, PowerShell, Git Bash and the WSL distributions ([`shell/ShellDiscovery.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/shell/ShellDiscovery.java)). ## Conformance (PAUTA) https://pauta-project.dev/6.0.0/conformance/: How an app says which edition of Pauta it implements and how fully it conforms, and how it records the rules it does not meet: not applicable, a deliberate deviation, or work still pending. ### Complete, Core and Partial - **PAUTA-01 · MUST.** Every app implements Pauta: it names one edition (the `pauta.version` of [ABOUT-08](https://pauta-project.dev/6.0.0/templates/about/#about-08)) and states its conformance as [Complete, Core or Partial](https://pauta-project.dev/6.0.0/conformance/#complete-core-and-partial): Complete meets every MUST and every SHOULD (met, not applicable or a recorded deviation), Core every MUST with SHOULDs still pending, Partial not yet every MUST. - *Why:* an app that is in the family answers to these rules; saying which ones, and how far, is the first of them. - *Check (code):* `pom.xml` defines `pauta.version` and `src/main/resources/com//pauta.json` exists. - *Command:* `[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; { grep -q '' pom.xml || { echo 'no pauta.version in pom.xml'; false; }; } && { find src/main/resources -path '*/com/*' -name pauta.json | grep . || { echo 'no pauta.json'; false; }; }` - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`pom.xml`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/pom.xml) (`pauta.version`) and [`pauta.json`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/resources/com/example/app/pauta.json). - **PAUTA-02 · MUST.** An app's conformance is computed, never stored: one pure helper reads the exceptions and returns Partial when any MUST is pending, Core when any SHOULD is pending, and Complete otherwise. Nothing else enters it: the `checked` list ([PAUTA-18](https://pauta-project.dev/6.0.0/conformance/#pauta-18)) is a record, and a by-hand rule with no entry there leaves the result as it is. About, the Pauta window and the docs page take it from there; the README's badge and line ([PAUTA-15](https://pauta-project.dev/6.0.0/conformance/#pauta-15)), which can't call the helper, are held to it by a test. - *Why:* [*One source of truth for each fact*](https://pauta-project.dev/6.0.0/principles/#for-the-people-building-them). A conformance typed in by hand stays "Complete" after a pending exception is added. - *Check (code):* one helper returns the conformance (the template's `PautaConformance.of`): it is handed the exceptions and nothing of the `checked` list, returns Partial for a pending MUST, Core for a pending SHOULD and Complete otherwise, and deviation, not-applicable and app-only entries leave its result alone. About and the Pauta window call it, and nothing in the app's code stores a conformance. A test fails when the README's badge or line names another conformance than the helper returns: the statement requires that one. A unit test of the helper that covers all three results is the surest evidence for the rest. That the docs page shows the same conformance is read with the page itself, in the website's repository ([PAUTA-13](https://pauta-project.dev/6.0.0/conformance/#pauta-13)). - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`PautaConformance.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/PautaConformance.java) (`of`, which takes the exceptions alone, and `conformance`), tested by [`PautaConformanceTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/PautaConformanceTest.java), whose `theReadmeNamesTheEditionAndTheConformanceAndLinksTheDocsPage` holds the README. Its `Kind` has no `app-only` yet, so the test covers deviation and not-applicable entries and MAYs. - **PAUTA-03 · MUST.** A new app, one that has made no release yet, makes its first release at Core or Complete: the [New app checklist](https://pauta-project.dev/6.0.0/checklist/)'s MUSTs are release blockers, and recording one as pending does not lift that. An app with a release behind it is not covered: it may be at Partial, and says so ([Complete, Core and Partial](https://pauta-project.dev/6.0.0/conformance/#complete-core-and-partial)). A template repository is never released as an app, so this rule is for the app made from it and the template records no entry for it. - *Check (by hand):* in an app with no release yet (no numbered section in its `CHANGELOG.md`, no version tag), the About window of the build to be released says Core or Complete. An app that has released, and a template, are outside the rule. - *Reference:* no app yet. ### Exceptions - **PAUTA-04 · MUST.** Every MUST and SHOULD of the edition that the app does not meet has an exception, and every exception names a rule the app does not meet. An unmet rule with no entry is a failed audit, not an exception; an entry for a rule the app now meets is removed in the same change that meets it. A rule checked by hand counts like any other once a person has checked it in the running app: found unmet, it gets an exception; found met, a `checked` entry ([PAUTA-18](https://pauta-project.dev/6.0.0/conformance/#pauta-18)). Until then it has neither, and that is not a failed audit: the audit reports it as `manual`, not recorded. - *Why:* [*Never claim what is not true*](https://pauta-project.dev/6.0.0/principles/#for-the-people-using-the-apps). The list is the app's claim; it has to be whole and current. - *Check (code):* the audit of the app against its edition ([Coding agents and LLMs](https://pauta-project.dev/6.0.0/coding-agents/#audit-an-app)) is this check, so the audit judges this rule last, from its other results: no MUST or SHOULD is `fail`, and no result reports an entry for a rule that passes. The evidence names the rules that fail. A `manual` result with no `checked` entry is reported as not recorded (PAUTA-18), and a `not-checked` one as out of the audit's reach: neither is a failure of the app, and neither fails this check. An audit of part of the edition judges it from the rules in its scope and says so. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`pauta.json`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/resources/com/example/app/pauta.json), the only list of exceptions so far. The template carries no audit report (`docs/pauta-audit.json`) to show that the list is whole. - **PAUTA-05 · MUST.** A rule limited to apps with a feature needs no entry in an app without that feature. A rule is limited when its own text says so ("An app that stores a secret…"), when its page or section opens with an **Applies to** line (the [Tray and background](https://pauta-project.dev/6.0.0/tray-and-background/) page; `appliesTo` in `rules.json`), or when it details a rule that is limited (WELC-03 onward detail the Welcome page of [WELC-01](https://pauta-project.dev/6.0.0/templates/welcome/#welc-01)). Nothing else limits a rule: a scope is read from one of the three, never inferred from what the app lacks. `not-applicable` is for a rule that reads as applying to every app. - *Check (code):* no `not-applicable` entry names a rule whose text, page, section or parent rule already limits it. - *Reference:* no app yet. - **PAUTA-06 · MUST.** A `deviation` is a choice, not a gap, and only a SHOULD can have one: a SHOULD is expected unless the app has a stated reason, and the deviation is that reason. It links a decision record in `docs/decisions/` ([DOCS-13](https://pauta-project.dev/6.0.0/documentation/#docs-13)) that gives the context, what the app does instead, and what it costs. A MUST the app does not meet is `pending`, as is any work it has not done yet. - *Why:* a deviation keeps the conformance; a deviation from a MUST, or missing work called a deviation, would let the app say it is built to an edition it does not meet. - *Check (code):* every `deviation` entry names a SHOULD, and its `link` opens a file under `docs/decisions/` that names the rule's ID. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`PautaConformanceTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/PautaConformanceTest.java) (`eachKindHasWhatItNeeds`). - **PAUTA-07 · MUST.** A `pending` exception links an open issue in the app's own repository that names the rule's ID and edition, "MENU-14 (Pauta x.y.z)". One issue may hold several rules, one per page for example, if it names each one that way. Closing the issue removes its entries. - *Check (code):* every `pending` entry's `link` is an issue URL in the app's own repository; the source settles that much, and a link that is not one fails the rule. That the issue is open and names the entry's rule ID and edition is read from the issue itself (`gh issue view `), which is on GitHub and not in the checkout. An audit that cannot read the issues reports the rule as `not-checked` and says what would settle it. With no `pending` entry there is nothing to read, and the rule is met. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`PautaConformanceTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/PautaConformanceTest.java) (`eachKindHasWhatItNeeds`), whose pending entries link issues in the template's own repository. - **PAUTA-08 · MUST.** Each exception's `reason` is one plain sentence for the person using the app, in English like the changelog: what is different and, for a deviation, what they get instead. No rule text, no class names. - *Check (by hand):* read each reason in the Pauta window as a user would. The source settles two cases: a reason that runs to more than one sentence, or carries rule text or a class name, fails the rule, and with no exception there is no reason to read and the rule is met. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`PautaConformanceTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/PautaConformanceTest.java) (`eachKindHasWhatItNeeds`: a reason ends with a period and names no rule ID). - **PAUTA-16 · MUST.** A template repository, one that new apps are made from, sets `"template": true` in its `pauta.json` and records as `app-only` the rules that only an app made from it can meet. `app-only` leaves the conformance as it is, like `not-applicable`, and nothing but a template may use it. Making an app from the template sets `template` to `false`. From then on the app's everyday build passes but lists what it inherited: each `app-only` entry and each `pending` link to another repository. Its release build fails until each one is met, or recorded as `pending` with an issue in the app's own repository. An app that was not made from a template inherits nothing, and the rule asks nothing of it. - *Why:* a template can't have the website or screenshots of an app that doesn't exist yet, and an app must not inherit its template's issues as its own. A build that failed the moment the app was made would fail its first step; the release is where it has to be settled ([PAUTA-03](https://pauta-project.dev/6.0.0/conformance/#pauta-03)). - *Check (code):* in a template, `pauta.json` has `"template": true` and the script that makes an app from it sets it to `false`. Outside a template, an `app-only` entry or a `pending` link to another repository is what a template left behind: the test of [PAUTA-10](https://pauta-project.dev/6.0.0/conformance/#pauta-10) lists each one in the everyday build, and the release build runs it with them treated as failures, so no released app keeps an `app-only` entry. An app whose `pauta.json` has no `template` field, no `app-only` entry and no `pending` link to another repository, or that has no `pauta.json`, shows nothing inherited from a template: it is outside the rule, and an audit reports it as `limited`. - *Reference:* no app yet. The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`pauta.json`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/resources/com/example/app/pauta.json) has no `template` field, its `Kind` no `app-only`, and its [`scripts/rename.sh`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/scripts/rename.sh) sets none; its [`PautaConformanceTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/PautaConformanceTest.java) accepts a `pending` link to the template's own repository in an app made from it, in every build. - **PAUTA-18 · MUST.** `pauta.json`'s `checked` list is the record of the rules checked by hand, and this rule governs only the entries an app chooses to record: each one is well formed and not stale. An app that records none, with no `checked` list or an empty one, meets it. An entry is there only because a person checked the rule in the running app and found it met, and it holds the `rule`, the `edition` it was checked against and the `date`, and may hold the app's `version`, for a rule that is checked again with each release (the screen-reader pass of [ACC-07](https://pauta-project.dev/6.0.0/accessibility/#acc-07)): the audit reports it, and nothing expires by it. It says the rule was met when it was checked, not that the app still meets it. A rule found unmet gets an exception instead ([PAUTA-04](https://pauta-project.dev/6.0.0/conformance/#pauta-04)), never both. A by-hand rule with no entry has not been recorded as checked: it needs no exception and no issue, it does not change the computed conformance ([PAUTA-02](https://pauta-project.dev/6.0.0/conformance/#pauta-02)), and it does not fail this rule. The audit reports it as not recorded, so its report still says which by-hand rules nobody has recorded. An entry is stale when its `edition` is older than the rule's `changed` in the edition's `rules.json`, the edition in which the rule's level, scope or statement last changed, and only then: the app's test fails it ([PAUTA-10](https://pauta-project.dev/6.0.0/conformance/#pauta-10)) until it is removed and the rule checked again. - *Why:* an audit can only answer `manual` for these rules, and its report is written again each time. Without a record, a rule someone checked last week and a rule nobody ever looked at read the same. The record stays out of the conformance because nothing in the code tells an unchecked rule from a met one: counting it would make an app record as pending what it may well meet. - *Check (code):* every `checked` entry has a `rule`, an `edition` and a `date`; the rule is one of the edition's whose check is by hand (`check.kind` in `rules.json`); the edition is no older than the rule's `changed` (one newer than `pauta.version`, and a rule listed twice, are for the test of [PAUTA-10](https://pauta-project.dev/6.0.0/conformance/#pauta-10) to fail); and no rule has an exception as well. With no `checked` list, or an empty one, there is no entry to fail and the rule is met: the audit's `manual` results say which by-hand rules are not recorded, and that is no failure of this rule. That a person looked is the entry's own claim, which the code can't show. - *Reference:* no app records a by-hand check yet, so each meets the rule with nothing to hold: the [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`pauta.json`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/resources/com/example/app/pauta.json) has no `checked` list, its [`PautaConformanceTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/PautaConformanceTest.java) reads none, and the six apps have no `pauta.json`. ### The file - **PAUTA-09 · MUST.** An app's exceptions and its record of by-hand checks have one source: `pauta.json`, bundled with the app's resources (`src/main/resources/com//pauta.json`) and laid out as [The file](https://pauta-project.dev/6.0.0/conformance/#the-file) shows. Its `exceptions` list has `rule`, `level`, `url`, `kind` and `reason` on every entry, `link` on every deviation and pending entry, and one entry per rule. Its `checked` list is the app's to keep or not: an app that records no by-hand check leaves it out or empty, and what an entry of it holds is [PAUTA-18](https://pauta-project.dev/6.0.0/conformance/#pauta-18)'s. `"template": true` stands beside the two lists only in a template repository (PAUTA-16). - *Check (code):* `pauta.json` is among the app's bundled resources, under `src/main/resources/`; each exception has the fields its kind needs and no rule has two. The entries of the `checked` list are [PAUTA-18](https://pauta-project.dev/6.0.0/conformance/#pauta-18)'s to judge, and a file with no `checked` list passes. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`pauta.json`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/resources/com/example/app/pauta.json), read by [`PautaConformanceTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/PautaConformanceTest.java) (`parsesEveryField`, `everyEntryNamesARuleOfTheEditionWithItsLevelAndAddress`). The file has no `checked` list, which the rule allows. - **PAUTA-10 · MUST.** A test reads `pauta.json` against a copy of the edition's `rules.json` in `src/test/resources/pauta-rules.json` and fails when the copy's `edition` is not `pauta.version`, when an entry names a rule the edition does not have, when its `level` or `url` differs from the edition's, when a rule appears twice, when a deviation names a MUST, when a deviation or pending entry has no `link`, or when a `checked` entry ([PAUTA-18](https://pauta-project.dev/6.0.0/conformance/#pauta-18)) names a rule that is not checked by hand, a rule listed twice, a rule with an exception, an edition newer than `pauta.version`, or an edition older than the rule's `changed`, which makes the entry stale. Outside a template, it reports each `app-only` entry and each `pending` link that is not an issue in the app's own repository (the one the app's own code names; `AppInfo.GITHUB_REPO` in the template), and fails on them in the release build ([PAUTA-16](https://pauta-project.dev/6.0.0/conformance/#pauta-16)). - *Why:* moving to a newer edition changes levels, retires IDs and changes rules a person checked by hand; the test turns each stale entry into a failure. - *Check (test):* `PautaConformanceTest`, or the app's equivalent, runs in the build and has a case for each failure the rule lists. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`PautaConformanceTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/PautaConformanceTest.java) and its copy of the edition's rules, [`pauta-rules.json`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/resources/pauta-rules.json). Two parts aren't built yet: the template's (`app-only`, inherited links) and everything about `checked`. The test reads the `exceptions` list only. - **PAUTA-11 · SHOULD.** Moving to a newer edition is one change: replace `pauta-rules.json` with the new edition's, and the app's copy of the audit skill where it keeps one (the app template's is `.claude/skills/pauta-audit/SKILL.md`); remove the `checked` entries the new `rules.json` makes stale ([PAUTA-18](https://pauta-project.dev/6.0.0/conformance/#pauta-18)) and check those rules again; run the audit again and update `pauta.json`; then change `pauta.version`, the README and `AGENTS.md` together. - *Why:* each of these names or follows the edition. The test fails a `pauta-rules.json` or a `checked` entry left behind (PAUTA-10); nothing fails a skill copy left behind, which then audits the new rules by the old procedure. - *Check (by hand):* the change that raises `pauta.version` also replaces `pauta-rules.json` and the skill copy, where the app keeps one, leaves no `checked` entry older than its rule's `changed`, and touches `pauta.json` where the audit found something new. - *Reference:* [Move an app to a newer edition](https://pauta-project.dev/6.0.0/coding-agents/#move-an-app-to-a-newer-edition). ### Where it shows - **PAUTA-13 · MUST.** In the user docs: the app's website has a *Pauta conformance* page under `/docs/` ([DOCS-02](https://pauta-project.dev/6.0.0/documentation/#docs-02)) with the edition, the conformance and every exception, grouped by kind, each with its rule ID linked to the edition's rule, its reason and its link. The Pauta window's link to it is [PWIN-07](https://pauta-project.dev/6.0.0/templates/pauta-window/#pwin-07). - *Check (code):* the app names a website for its user docs ([DOCS-01](https://pauta-project.dev/6.0.0/documentation/#docs-01)): an app whose repository and About name none has nowhere to carry the page, and fails the rule from the app's checkout. The rest is in the website's repository (`-website`, [DOCS-02](https://pauta-project.dev/6.0.0/documentation/#docs-02)): its docs (the files of `src/content/docs/` in editora-website) have the page, and the page gives the edition `pauta.version` names, the conformance the app's exceptions give, and every exception of the app's `pauta.json` under its kind, each with its rule ID linked to the edition's rule, its reason and its link. A page that lists other rules than the file fails. With no `pauta.json`, which is [PAUTA-01](https://pauta-project.dev/6.0.0/conformance/#pauta-01)'s and [PAUTA-09](https://pauta-project.dev/6.0.0/conformance/#pauta-09)'s failure, there is no list to compare, and the page is judged on being there with the edition. An audit run from the app's checkout alone reports the rule as `not-checked` and says what would settle it. - *Reference:* no app yet. - **PAUTA-14 · SHOULD.** The website's *Pauta conformance* page ([PAUTA-13](https://pauta-project.dev/6.0.0/conformance/#pauta-13)) is generated from the app's `pauta.json`, like the Commands page ([DOCS-04](https://pauta-project.dev/6.0.0/documentation/#docs-04)), so it cannot list a different set from the app. - *Check (code):* the app's website repository has a generator that reads the app's `pauta.json` (beside the others in `scripts/`, in editora-website's layout), and its output is committed. An app that names no website has no page to generate: the rule fails with [PAUTA-13](https://pauta-project.dev/6.0.0/conformance/#pauta-13). An audit run from the app's checkout alone reports the rule as `not-checked` and says what would settle it. - *Reference:* no app yet; editora-website's [`scripts/GenCommands.java`](https://github.com/adriandeleon/editora-website/blob/1b6390c20c7a8aa3fc6af394b68c11454478d69d/scripts/GenCommands.java) is the pattern. - **PAUTA-15 · MUST.** An app's README shows its conformance: the README's Pauta badge ([README badges](https://pauta-project.dev/6.0.0/repository/#readme-badges-in-this-order)) and its "Built to" line (at Partial, "Working toward") name the edition and the conformance, and both link to the website's *Pauta conformance* page ([PAUTA-13](https://pauta-project.dev/6.0.0/conformance/#pauta-13)). The edition is the one `pauta.version` names ([ABOUT-08](https://pauta-project.dev/6.0.0/templates/about/#about-08)), and the conformance the one the app computes ([PAUTA-02](https://pauta-project.dev/6.0.0/conformance/#pauta-02)). - *Check (code):* `README.md` has the badge and the line; each names the edition `pauta.version` names and the conformance the app's exceptions give (Partial with a pending MUST, Core with a pending SHOULD, else Complete), the line opens "Working toward" at Partial and "Built to" otherwise, and both link the app's conformance page under its website's `/docs/`. A test that asserts it (the template's `theReadmeNamesTheEditionAndTheConformanceAndLinksTheDocsPage`) is the surest evidence, and PAUTA-02 requires one for the conformance. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`README.md`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/README.md) (the badge and the *Working toward* line), held by [`PautaConformanceTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/PautaConformanceTest.java) (`theReadmeNamesTheEditionAndTheConformanceAndLinksTheDocsPage`). Termina's and Mirada's READMEs have a badge that names the edition alone and links the edition; Mirada's has a "Built to" line, which names no conformance. The other four READMEs name no edition. - **PAUTA-17 · MUST.** For the app's coding agent: `AGENTS.md` has a section on Pauta (the app template heads it "Pauta") that names the edition `pauta.version` names and links that edition's `llms.txt` and `llms-full.txt` at its numbered address, never `latest/` ([Coding agents and LLMs](https://pauta-project.dev/6.0.0/coding-agents/#point-the-apps-agent-at-its-edition)). - *Why:* an agent that reads no rules builds without them, and one that reads `latest/` "fixes" MUSTs of a newer edition the app hasn't moved to. - *Check (code):* `AGENTS.md` has a section on Pauta, under whatever heading, that names the edition `pauta.version` names and links `https://pauta-project.dev//llms.txt` and `https://pauta-project.dev//llms-full.txt` with that number; the file links neither at `latest/` nor at another edition. A test that asserts it is the surest evidence. - *Reference:* the app template's [`AGENTS.md`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/AGENTS.md), Termina's [`AGENTS.md`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/AGENTS.md) and Mirada's [`AGENTS.md`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/AGENTS.md) have the section, each under the heading "Pauta". Termina's [`AppInfoTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/AppInfoTest.java) (`agentsAndReadmeNameTheSameEdition`) asserts the edition and the `llms.txt` link; the template's [`EditionTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/EditionTest.java) and Mirada's [`EditionTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/EditionTest.java) (`theReadmeAndAgentsNameTheSameEdition` in both) assert the edition the file names and not its links. Editora's and nux's `AGENTS.md` have no such section, and Torrenta and Modula have no `AGENTS.md`. ## Platform baseline (PLAT) https://pauta-project.dev/6.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: a newer JDK builds the app too, so no enforcer rule refuses one, in the main build or in any profile that turns itself on (an `` by JDK version, OS, property or file, or one that is `activeByDefault`; a profile turned on only by name, with `-P`, is not counted). CI builds every app on JDK 25, the current LTS: every workflow step that sets up a JDK sets up release 25, and the runtime an installer carries ([PLAT-02](https://pauta-project.dev/6.0.0/platform/#plat-02)) is that JDK's. A leg that builds a native image carries no JDK: it sets up a GraalVM 25 release instead, 25.0 or any later 25.x. The family moves to the next LTS together, in an edition of Pauta. - *Check (code):* `pom.xml` sets `maven.compiler.release` to 25 or later. Every enforcer `requireJavaVersion` rule that counts refuses no JDK from 25 up: its range has no upper bound and starts at 25 or below, as the open-ended `[25,)` does, or a bare `25`, which the enforcer reads as 25 or newer. The rules that count are those of the main build and those inside a profile that turns itself on, one whose `` holds a ``, an ``, a `` or a ``, or an `` that is `true`: such a profile is on without being asked for, so its rule is the build's rule wherever it activates. A rule in a profile turned on only by name with `-P` is not counted, and an app with no rule that counts passes. In the workflows, every step that uses a `setup-java` or `setup-graalvm` action (`actions/setup-java`, `graalvm/setup-graalvm`) names 25 or a 25.x release in its `java-version`, and in the `version` a GraalVM step may give beside it or instead. The Command reads the pom as text, with its XML comments left out, and a workflow line by line, not as YAML: a step ends at the next line that opens a list item. A version it cannot read as a number (an expression such as `${{ matrix.java }}`, a `java-version-file`) it prints as not judged and does not fail: read the matrix or the file it names. An enforcer range held in a property (`${…}`) it cannot follow: it prints the property and fails, so read the property's value. - *Command:* `[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; r=$(sed -n 's:.*\([0-9]*\)<.*:\1:p' pom.xml | head -n 1); p=$(tr -d ' \t\r\n' < pom.xml | tr '<' '\n' | sed -n '/^!--.*-->/!p' | sed -n '/^!--/,/-->/!p'); j=$({ printf '%s\n' "$p" | sed -n '/^profiles>/,/^\/profiles>/!p'; printf '%s\n' "$p" | sed -n '/^profile>/,/^\/profile>/{/^profile>/h;/^profile>/!H;/^\/profile>/{x;/\nactivation>.*\njdk>.*\n\/activation>/{p;d;};/\nactivation>.*\nos>.*\n\/activation>/{p;d;};/\nactivation>.*\nproperty>.*\n\/activation>/{p;d;};/\nactivation>.*\nfile>.*\n\/activation>/{p;d;};/\nactivation>.*\nactiveByDefault>true\n.*\/activation>/{p;d;};};}'; } | sed -n '/^requireJavaVersion>/,/^\/requireJavaVersion>/s/^version>//p'); w=$(for f in .github/workflows/*.yml .github/workflows/*.yaml; do [ -f "$f" ] || continue; for n in $(grep -nE '^[^#]*uses:[^#]*/setup-(java|graalvm)@' "$f" | cut -d: -f1); do c=0; for v in $(tail -n +"$n" "$f" | sed -n '1d;/^ *- /q;p' | grep -E '^ *(java-)?version:' | cut -d: -f2- | cut -d'#' -f1 | tr -d " '\"\r"); do c=1; if printf '%s\n' "$v" | grep -qE '^25([.+-].*)?$'; then :; elif printf '%s\n' "$v" | grep -q '^[0-9]'; then echo "$f:$n sets up release $v"; else echo "not judged: $f:$n version $v" >&2; fi; done; [ "$c" -eq 1 ] || echo "not judged: $f:$n version not given" >&2; done; done); [ "${r:-0}" -ge 25 ] && ! echo "$j" | grep -vxE '\[(1?[0-9]|2[0-5])([.][0-9]+)*,\)|(1?[0-9]|2[0-5])([.][0-9]+)*' | grep -q . && [ -z "$w" ] || { echo "maven.compiler.release ${r:-none}; requireJavaVersion in the main build and in profiles that turn themselves on:" ${j:-none}; [ -z "$w" ] || echo "$w"; false; }` - *Reference:* the app template's [`pom.xml`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/pom.xml) (one enforcer rule, `[25,)`) and [`.github/workflows/ci.yml`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/.github/workflows/ci.yml) (`java-version: '25'`); Termina's and Mirada's rules have the same range, and Modula and nux have no enforcer rule. Editora doesn't yet: beside the `[25,)` rule of its main build, its [`pom.xml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/pom.xml) has a profile, `formatter-needs-jdk25`, that activates on JDK `[26,)` and holds an enforcer rule with the range `[25,26)`, so a plain build on JDK 26 or newer stops unless it is told to skip the format check. Torrenta doesn't either: the rule in its main build has the range `[25,26)`. Mirada's profile of the same name skips the format check on those JDKs, says so, and refuses nothing ([`pom.xml`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/pom.xml)). No app's profile that activates by OS, property or file holds an enforcer rule (Termina's `os-windows` and `git-commit` and Modula's `app-image` among them), and no app has a profile that is `activeByDefault`. Every app's workflows set up 25. Mirada's native legs set up Oracle GraalVM with `version: '25.4'`, a GraalVM 25 release ([`.github/workflows/release.yml`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/.github/workflows/release.yml)); its jlink leg sets up JDK 25. - **PLAT-02 · SHOULD.** 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, and that image is what the release ships. - *Reference:* Editora [`pom.xml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/pom.xml) (`dist` profile). Mirada ships a GraalVM native image instead on every target GraalVM builds one for, all but Intel macOS, which gets the jlinked image: [`scripts/native-app-image.sh`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/scripts/native-app-image.sh) takes the Java runtime out of the app image, and users still install nothing. - **PLAT-03 · MUST.** The app builds on **JavaFX 27 or newer**. - *Check (code):* `pom.xml` sets `javafx.version` to 27 or later. - *Command:* `[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; v=$(sed -n 's:.*\([0-9]*\).*:\1:p' pom.xml | head -n 1); echo "javafx.version ${v:-none}"; [ "${v:-0}" -ge 27 ]` - *Reference:* Editora [`pom.xml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/pom.xml). - **PLAT-04 · MUST.** The app is one named JPMS module, whose `module-info.java` opens only what reflection, FXML and Jackson need. - *Check (code):* `src/main/java/module-info.java` declares one named module, not an `open module`, which opens every package; each `opens` line serves FXML, Jackson or another reflective reader. - *Reference:* Editora [`src/main/java/module-info.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/module-info.java) (its module is `com.editora`). The name is the app's to choose: the template's is `com.example.app`, and its [`scripts/rename.sh`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/scripts/rename.sh) gives the module the name of the app's Java package. - **PLAT-05 · MUST.** Controls use **AtlantaFX 3.x** (`atlantafx-base`). The light and dark themes it carries are [ICON-15](https://pauta-project.dev/6.0.0/icons-and-color/#icon-15). - *Check (code):* `pom.xml` depends on `atlantafx-base` 3.x. - *Reference:* Editora [`pom.xml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/pom.xml), [`ui/Themes.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Themes.java). - **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. - *Command:* `[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; ! for f in mvnw mvnw.cmd .mvn/wrapper/maven-wrapper.properties; do test -f "$f" || echo "missing $f"; done | grep .` - *Reference:* Editora [`mvnw`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/mvnw), [`.mvn/wrapper/`](https://github.com/adriandeleon/Editora/tree/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.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`. - *Command:* `[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; [ -d src/main/java ] || { echo 'no src/main/java'; exit 1; }; { grep -q 'NullAway:ERROR' pom.xml || { echo 'no -Xep:NullAway:ERROR in pom.xml'; false; }; } && ! find src/main/java -name '*.java' ! -name package-info.java ! -name module-info.java -exec dirname {} \; | sort -u | while read -r d; do grep -qs '@NullMarked' "$d/package-info.java" || echo "not @NullMarked: $d"; done | grep .` - *Reference:* Editora [`pom.xml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/pom.xml), [`docs/conventions.md#null-annotations-jspecify-checked-by-nullaway`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/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 in a Format job of its own: a job that runs `spotless:check` and neither builds nor tests. When CI runs and which of its jobs the default branch requires are [REL-19](https://pauta-project.dev/6.0.0/release/#rel-19). - *Why:* a check bound to a build phase fails in the same job as the tests, so the failed job does not say which of the two is wrong. - *Check (code):* the spotless plugin configures `palantirJavaFormat`, and in a workflow that runs on pull requests, which is where [REL-19](https://pauta-project.dev/6.0.0/release/#rel-19) has CI run and so where an unformatted change is failed, a job runs `spotless:check` and neither builds nor tests: no Maven `compile`, `test-compile`, `test`, `package`, `verify`, `integration-test`, `install` or `deploy` in the same job. The plugin's `check` goal bound to a phase (`./mvnw verify`) does not meet it alone. The Command reads a workflow line by line, not as YAML: a job is what lies between two keys at the indentation of the first key under `jobs:`, and a Maven run counts when its goal is on the line that names `mvn` or `mvnw` (a `name:` line is not a run). A Format job in a workflow of its own that a pull-request workflow calls (`workflow_call`, `uses: ./.github/workflows/`) meets the rule, and the Command follows that call. What it does not see, so read the workflow where one applies: a goal on a continuation line; a build started from a script; a job's `if:`. - *Command:* `[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; grep -q palantirJavaFormat pom.xml || { echo 'pom.xml configures no palantirJavaFormat'; exit 1; }; for f in .github/workflows/*.yml .github/workflows/*.yaml; do grep -qE '^( *-? *|on:.*[^A-Za-z0-9_-])pull_request(_target)?([^A-Za-z0-9_-]|$)' "$f" 2>/dev/null || { grep -qE '^( *-? *|on:.*[^A-Za-z0-9_-])workflow_call([^A-Za-z0-9_-]|$)' "$f" 2>/dev/null && grep -lE "^[^#]*uses:[^#]*\./$f" .github/workflows/* 2>/dev/null | xargs grep -lE '^( *-? *|on:.*[^A-Za-z0-9_-])pull_request(_target)?([^A-Za-z0-9_-]|$)' 2>/dev/null | grep -q .; } || continue; i=$(sed -n '/^jobs:/,$p' < "$f" | grep -E '^ +[A-Za-z0-9_-]+:' | head -n 1 | sed -n 's/^\( *\).*/\1/p'); for s in $(grep -nE '^[^#]*mvnw?(\.cmd)?[[:space:]]([^#]*[[:space:]])?spotless:check' "$f" | grep -vE '^[0-9]+: *-? *name:' | cut -d: -f1); do a=0; b=999999; for h in $(grep -nE "^$i[A-Za-z0-9_-]+:" "$f" | cut -d: -f1); do if [ "$h" -le "$s" ]; then a=$h; elif [ "$b" -eq 999999 ]; then b=$h; fi; done; m=; for t in $(grep -nE '^[^#]*mvnw?(\.cmd)?[[:space:]]([^#]*[[:space:]])?(compile|test-compile|test|package|verify|integration-test|install|deploy)([^A-Za-z0-9:_.=/-]|$)' "$f" | grep -vE '^[0-9]+: *-? *name:' | cut -d: -f1); do [ "$t" -ge "$a" ] && [ "$t" -lt "$b" ] && m="$m $f:$t"; done; [ -z "$m" ] && exit 0; echo "spotless:check at $f:$s shares its job with a build or test run:$m"; done; done; w=$(grep -lE '^[^#]*spotless:check' .github/workflows/* 2>/dev/null); echo "no job of its own runs spotless:check in a workflow that runs on pull requests (named in: ${w:-no workflow})"; exit 1` - *Reference:* Editora [`pom.xml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/pom.xml) (spotless plugin), [`.github/workflows/ci.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/ci.yml) (the `format` job, *Format*); the template, Termina and Mirada have the same job in their `ci.yml`. Torrenta and Modula do not yet: their `test` job runs `./mvnw verify`, the phase the check is bound to, and no job runs `spotless:check`. nux has no Spotless. - **PLAT-11 · MUST.** Tests run on **JUnit** (Jupiter, 5 or newer) over JavaFX's built-in **Headless** glass platform (`-Dglass.platform=Headless`), so FX tests need no display, no xvfb and no Monocle. **TestFX** MAY drive them; an app that doesn't use it starts the toolkit with `Platform.startup` and runs its steps on the FX thread. - *Check (code):* surefire's `systemPropertyVariables` set `glass.platform` to `Headless`; no Monocle dependency, and no xvfb in a step that runs tests (a release leg may use it to train the AOT cache, [REL-10](https://pauta-project.dev/6.0.0/release/#rel-10)). - *Reference:* Editora [`pom.xml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/pom.xml) (surefire), [`docs/testing.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/testing.md), [`FxTestSupport`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/FxTestSupport.java), with TestFX; Termina [`pom.xml`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/pom.xml) (surefire) and [`DialogAnswers`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/ui/DialogAnswers.java), without it. - **PLAT-12 · MUST.** A **JaCoCo** `check` runs at `mvn verify` with build-wide floors of **≥ 0.90 lines and ≥ 0.90 methods**, and no profile that activates by OS or by JDK version lowers a floor or skips the check. The rule is about the pom's profiles, not about where CI runs the gate: a workflow that runs the tests on some of its runners with JaCoCo skipped is the workflow's choice and passes. The branch floor and each package's own floor are [QUAL-03](https://pauta-project.dev/6.0.0/quality/#qual-03). - *Check (code):* an execution of the JaCoCo plugin's `check` goal, whatever its id (Editora's is `jacoco-check`), is bound to `verify` with `BUNDLE` limits of 0.90 `LINE` and 0.90 `METHOD`. Where a limit is a property (`${coverage.bundle.line}` in Termina), its value is 0.90 or more in the main `` and in every profile that sets it and activates by OS or by JDK version (an `` with an `` or a ``), and no such profile sets `jacoco.skip` or the check's ``. A `-Djacoco.skip` on a workflow's command line is not judged. - *Reference:* Editora [`pom.xml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/pom.xml) `jacoco-check`, with no profile that touches it; the template's and Mirada's are the same. Editora's [`full-tests.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/full-tests.yml) runs its tests on the other OSes with `-Djacoco.skip=true`, which the rule leaves to the workflow. Termina doesn't yet: its `os-windows` profile lowers the two floors to 0.45 and 0.47 on Windows ([`pom.xml`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/pom.xml)). Torrenta's check has a line floor and no method floor, and Modula and nux have no JaCoCo check. - **PLAT-13 · SHOULD.** The app logs through `java.util.logging` and no other logging API. The Debug Log captures it: [DIAG-02](https://pauta-project.dev/6.0.0/diagnostics/#diag-02). - *Check (code):* the app's own code imports no logging API other than `java.util.logging`. - *Command:* `[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; [ -d src/main/java ] || { echo 'no src/main/java'; exit 1; }; ! grep -rnE '^import (static )?(org\.slf4j|org\.apache\.logging|org\.apache\.commons\.logging|ch\.qos\.logback|org\.jboss\.logging|org\.tinylog)\.' src/main/java` - *Reference:* Editora [`ui/DebugLog.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/DebugLog.java). - **PLAT-14 · SHOULD.** Config files are JSON, read and written by Jackson as plain classes (POJOs). Their schema versions and migrations are [SET-09](https://pauta-project.dev/6.0.0/settings/#set-09). - *Check (code):* every class written to the config folder is read and written through Jackson's `ObjectMapper`; no store builds or parses its JSON by hand. - *Reference:* Editora [`config/Settings`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/Settings.java), [`config/migration/ConfigSchema.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/migration/ConfigSchema.java). ## Repository documents (REPO) https://pauta-project.dev/6.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 with these parts: logo, badges, a one-paragraph pitch, the hero screenshot, highlights, install, build, command line, config folder, license. Detail lives on the website, which the README links, so the README stays short: at most 250 lines. - *Check (code):* `README.md` has each of those parts, links to the website for the rest, and runs to at most 250 lines (`wc -l README.md`). - *Reference:* Editora [`README.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/README.md) (221 lines) and the template's [`README.md`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/README.md) (148); Termina's has 152 and Mirada's 172. Three are over the 250: Torrenta's runs to 433 lines, Modula's to 364 and nux's to 313. - **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's first section is `## [Unreleased]` and the others are headed by a SemVer number and a date (`## [x.y.z] - YYYY-MM-DD`); the entries of a section sit under `### Added`, `### Changed`, `### Fixed` or `### Removed`, whichever it has entries for (Keep a Changelog's other two, `### Deprecated` and `### Security`, are as good); and every entry starts with `- **`. - *Reference:* Termina [`CHANGELOG.md`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/CHANGELOG.md) and Mirada's, where every entry opens in bold. In Editora's [`CHANGELOG.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/CHANGELOG.md) 1,804 of 2,173 entries do: the older ones don't, and some sections have headings of its own (`### Performance`, `### Internal`, `### Packaging`), as some of Modula's and nux's do. Torrenta's sections are headed `## Unreleased` and `## 0.4.1 — 2026-10-28`, without the brackets. - **REPO-03 · MUST.** `LICENSE` is MIT, "Copyright (c) 2026 Adrián Arturo De León Saldivar", with the year the app started in: 2026 for the six apps, later for a newer one. - *Check (code):* `LICENSE` opens with `MIT License` and has that copyright line, with a year from 2026 on. - *Command:* `[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; tr -d '\r' < LICENSE | head -n 1 | grep -qx 'MIT License' && tr -d '\r' < LICENSE | grep -qxE 'Copyright \(c\) 20(2[6-9]|[3-9][0-9]) Adrián Arturo De León Saldivar' || { head -n 3 LICENSE; false; }` - *Reference:* Editora [`LICENSE`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/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…). The installers carry `NOTICE` too. - *Check (code):* `NOTICE` opens with the app's name, the copyright and the MIT sentence, and names every runtime dependency in `pom.xml` and every bundled font with its license; and the build puts `NOTICE` into what every installer carries (a `` that packages it into the application jar in Editora; an argument to `jpackage` or a packaging script does it as well). A test that asserts it is the surest evidence. - *Reference:* Editora [`NOTICE`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/NOTICE) and [`pom.xml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/pom.xml) (the `` that packages `LICENSE` and `NOTICE` into the application jar); two tests hold it: [`NoticeCoverageTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/packaging/NoticeCoverageTest.java) fails when a runtime dependency in `pom.xml` has no `NOTICE` entry, and [`BuildHygieneTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/packaging/BuildHygieneTest.java) when the pom no longer packages the two files. - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/AGENTS.md), [`CLAUDE.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/CONTRIBUTING.md). - **REPO-07 · MUST.** `docs/` holds `architecture.md`, `conventions.md`, `testing.md`, `gotchas.md`, `release.md`, `building-and-packaging.md` and `decisions/` (ADRs). The folder's index, `docs/README.md`, is [DOCS-12](https://pauta-project.dev/6.0.0/documentation/#docs-12). - *Check (code):* each of those paths exists under `docs/`. - *Reference:* Editora [`docs/`](https://github.com/adriandeleon/Editora/tree/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/TODO.md). - **REPO-09 · MUST.** `.github/ISSUE_TEMPLATE/bug_report.yml` is an issue form, and the in-app Report a Problem fills it: the link it opens names the form and carries the environment and the report as query parameters named by the ids of the form's two fields for them (Editora's ids are `environment` and `report`). - *Check (code):* the form is at that path and has a field for the environment and a field for the report, each with an `id`; and the link Report a Problem builds names the form's file and carries one query parameter per field, named by the field's id (`template=bug_report.yml&environment=…&report=…` in Editora). The ids are the app's to choose, as long as the form and the link agree. - *Reference:* Editora [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/ISSUE_TEMPLATE/bug_report.yml) and [`report/ProblemReport.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/report/ProblemReport.java), which builds the link. The template, Termina, Torrenta and Mirada have the same form, ids and link; Modula and nux have no issue form. - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/branding/editora-icon.svg), with [`editora.png`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/branding/editora.png), `.icns` and `.ico` beside it; the template keeps them in [`packaging/icons/`](https://github.com/adriandeleon/adl-desktop-app-template/tree/b1ba438e61bce02fcbc389f1775f34a7def1ee31/packaging/icons). - **REPO-11 · SHOULD.** Every script in `scripts/` is a Java source file the JDK runs as it is (`java scripts/Name.java`, a compact source file or an ordinary class) or an `sh` or bash script. - *Why:* every app already needs the JDK, and a Java script runs the same on Windows, macOS and Linux. A Python or Node script makes every contributor and CI runner install a second toolchain for one step. A script that runs on Windows is easier to keep in Java than in bash. - *Check (code):* no file under `scripts/` is Python, JavaScript, TypeScript, Ruby, Perl, Groovy, Lua, PHP, PowerShell or a batch file, and every shebang there names `sh`, `bash` or `java`. Data files beside the scripts (fixtures, lists, templates) are not scripts. - *Command:* `[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; [ -d scripts ] || exit 0; bad=$(find scripts -type f | while IFS= read -r f; do if printf '%s\n' "$f" | grep -qE '\.(py|js|mjs|cjs|ts|rb|pl|ps1|bat|cmd|groovy|kts|lua|php)$'; then echo "$f"; continue; fi; l=$(head -n 1 "$f" | tr -d '\r'); if printf '%s\n' "$l" | grep -q '^#!'; then printf '%s\n' "$l" | grep -qE '^#! *(/usr)?/bin/(env +(-S +)?)?((ba|da)?sh|java)( |$)' || echo "$f: $l"; fi; done); [ -z "$bad" ] || { printf '%s\n' "$bad"; false; }` - *Reference:* Editora [`scripts/`](https://github.com/adriandeleon/Editora/tree/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/scripts), whose Java scripts have their own tests, run by [`scripts/lib/RunTests.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/scripts/lib/RunTests.java) ([`docs/testing.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/testing.md)). ## Documentation (DOCS) https://pauta-project.dev/6.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 with 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, a landing page of at most 250 lines ([REPO-01](https://pauta-project.dev/6.0.0/repository/#repo-01)), is not it. - *Check (code):* the app names a website for its user docs: its README or its About links one, or the address `help.documentation` opens ([DOCS-06](https://pauta-project.dev/6.0.0/documentation/#docs-06)) is on one. The repository's own address on GitHub is not one. An app whose repository and About name no website has no user documentation to point at, and fails the rule from the app's checkout. The rest is in the website's repository: its docs (the files of `src/content/docs/` in editora-website) have a getting-started page, a keyboard reference (a keymaps page there), a settings or configuration page, an FAQ and a page per feature area, and the pages carry screenshots of the app's real window. The website is a repository of its own ([DOCS-02](https://pauta-project.dev/6.0.0/documentation/#docs-02)), which the app's checkout does not hold. An audit run from the app's checkout alone reports the rule as `not-checked` and says what would settle it. - *Reference:* editora-website [`src/content/docs/`](https://github.com/adriandeleon/editora-website/tree/1b6390c20c7a8aa3fc6af394b68c11454478d69d/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 the page's category and its place in it (editora-website's keys are `category` and `order`); the sidebar, the sitemap and the RSS feed follow. The app's repository carries none of them: a page kept in the app's `docs/` fails the rule when any section of it tells the app's user how to install or use something, even if the rest of the page is for contributors, and whether or not the website has it too. - *Check (code):* no page in the app's `docs/` has a section that tells the person using the app how to install or use something: one found there fails the rule from the app's checkout, whoever the rest of the page is written for. So does an app whose repository and About name no website for its user docs ([DOCS-01](https://pauta-project.dev/6.0.0/documentation/#docs-01)): its user docs live on none. The rest is in the website's repository: every docs page there (the files of `src/content/docs/` in editora-website) gives its category and its order in its frontmatter. An audit run from the app's checkout alone reports the rule as `not-checked` and says what would settle it. - *Reference:* editora-website [`README.md`](https://github.com/adriandeleon/editora-website/blob/1b6390c20c7a8aa3fc6af394b68c11454478d69d/README.md) (*Content*). Editora doesn't yet, though its [`AGENTS.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/AGENTS.md) says "User-facing feature documentation goes to the separate website repository": [`docs/plugins.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/plugins.md), a page for plugin authors, has a section that tells the user the three ways to install a plugin and one on troubleshooting plugins. Termina doesn't either: [`docs/reference/installing.md`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/docs/reference/installing.md) tells the person installing it which download to take, how to install each and how to check its signature, and its README sends the reader there. Nor does Torrenta: [`docs/headless.md`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/docs/headless.md), [`docs/webapi.md`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/docs/webapi.md) and [`docs/search-providers.md`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/docs/search-providers.md) are guides for the person using it. - **DOCS-03 · SHOULD.** Every link from the app into its user docs opens the running version's docs, the address `help.documentation` opens ([DOCS-06](https://pauta-project.dev/6.0.0/documentation/#docs-06)) as much as a link to one page. 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 one file (editora-website's `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/6.0.0/principles/#for-the-people-using-the-apps)). - *Check (code):* the address the app opens for its docs is its website's `/docs/v-` plus the app's version without `-SNAPSHOT`: another address, the unversioned `/docs/` among them, fails the rule from the app's checkout. An app that opens no docs address has no link to judge and nothing to fail here: the missing address is [DOCS-06](https://pauta-project.dev/6.0.0/documentation/#docs-06)'s. The rest is in the website's repository: it serves `/docs/v-/` and redirects the unversioned paths (in its `astro.config.mjs`, in editora-website). An audit run from the app's checkout alone reports the rule as `not-checked` and says what would settle it. - *Reference:* Editora [`AppInfo.docsUrl()`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/AppInfo.java), `releaseVersion()`; editora-website [`astro.config.mjs`](https://github.com/adriandeleon/editora-website/blob/1b6390c20c7a8aa3fc6af394b68c11454478d69d/astro.config.mjs), [`README.md`](https://github.com/adriandeleon/editora-website/blob/1b6390c20c7a8aa3fc6af394b68c11454478d69d/README.md) (*Versioned docs*). The app template builds the same address (`docsUrl()` in its [`AppInfo.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/AppInfo.java)). Termina and Mirada don't yet: each opens its site's unversioned `/docs/` (`DOCUMENTATION` in Termina's [`AppInfo.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/AppInfo.java), `DOCS_URL` in Mirada's [`AppInfo.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/AppInfo.java)). Torrenta, Modula and nux open no docs address. The other three sites carry a comment to port these routes when their app first deep-links. - **DOCS-04 · SHOULD.** The website's 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; What's new from `CHANGELOG.md`, and the Roadmap from `TODO.md` where the app keeps one ([REPO-08](https://pauta-project.dev/6.0.0/repository/#repo-08)); 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/6.0.0/principles/#for-the-people-building-them)). - *Check (code):* the website's repository holds the generators and their committed output (`scripts/` and `src/lib/` in editora-website) and a check of the ids and chords its docs quote (`npm run check:docs` there), and the site's build or its deploy workflow runs that check. An app that names no website has no docs to generate: the rule fails with [DOCS-01](https://pauta-project.dev/6.0.0/documentation/#docs-01). All the rest is in the website's repository. An audit run from the app's checkout alone reports the rule as `not-checked` and says what would settle it. - *Reference:* editora-website [`scripts/GenCommands.java`](https://github.com/adriandeleon/editora-website/blob/1b6390c20c7a8aa3fc6af394b68c11454478d69d/scripts/GenCommands.java) (every `Command.of` in Editora's `com.editora.ui`, [`WindowCommandRegistrar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowCommandRegistrar.java) holding most), [`GenRoadmap.java`](https://github.com/adriandeleon/editora-website/blob/1b6390c20c7a8aa3fc6af394b68c11454478d69d/scripts/GenRoadmap.java), [`GenFeatures.java`](https://github.com/adriandeleon/editora-website/blob/1b6390c20c7a8aa3fc6af394b68c11454478d69d/scripts/GenFeatures.java); [`scripts/check-doc-commands.mjs`](https://github.com/adriandeleon/editora-website/blob/1b6390c20c7a8aa3fc6af394b68c11454478d69d/scripts/check-doc-commands.mjs) (`npm run check:docs`), which exits non-zero on a missing id or a chord bound to another command. Nothing runs it yet: neither the `build` script in [`package.json`](https://github.com/adriandeleon/editora-website/blob/1b6390c20c7a8aa3fc6af394b68c11454478d69d/package.json) nor [`pages.yml`](https://github.com/adriandeleon/editora-website/blob/1b6390c20c7a8aa3fc6af394b68c11454478d69d/.github/workflows/pages.yml) calls it, so it fails the site only when someone runs it by hand. - **DOCS-05 · MUST.** The notes of a GitHub release, the text under its title, are written for the person using the app: they say what changed for them, and are not a list of commits or pull requests. In an app with a Welcome page, the page's *What's New* link opens this build's release, so those notes are what it shows. The bold one-line summary that opens each `CHANGELOG.md` entry is [REPO-02](https://pauta-project.dev/6.0.0/repository/#repo-02); the website's What's new is [DOCS-04](https://pauta-project.dev/6.0.0/documentation/#docs-04); taking the notes from the version's `CHANGELOG.md` section is [REL-04](https://pauta-project.dev/6.0.0/release/#rel-04). - *Check (code):* the release's notes are not generated from the history: the JReleaser configuration's `changelog` is not a `format` of commit hashes and titles, and no release step sets `generate_release_notes`. They come from text someone wrote, the version's `CHANGELOG.md` section or a notes file. And in an app with a Welcome page, the page's *What's New* link opens the build's own release page (`AppInfo.releaseNotesUrl()` in Editora). - *Reference:* Termina's [`jreleaser.yml`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/jreleaser.yml) takes the notes from a file (`changelog.external`) that [`scripts/release-notes.sh`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/scripts/release-notes.sh) writes from the version's `CHANGELOG.md` section; the app template, Torrenta and Mirada do the same. Editora doesn't yet: its [`jreleaser.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/jreleaser.yml) builds the notes from the commits (`format: '- {{commitShortHash}} {{commitTitle}}'`), and that list is what its *What's New* opens ([`AppInfo.releaseNotesUrl()`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/AppInfo.java), [`WelcomePane`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WelcomePane.java), `welcome.whatsNew`). Modula's [`release.yml`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/.github/workflows/release.yml) and nux's [`release.yml`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/.github/workflows/release.yml) have GitHub generate them (`generate_release_notes: true`). ### Reachable from the app - **DOCS-06 · MUST.** The `help.documentation` command opens the user docs in the browser. It is a command like any other, so it is in the palette and bindable, and where the app has a Help menu (the Help menu of a menu bar, or a Help submenu of the app's main menu, which [WIN-14](https://pauta-project.dev/6.0.0/window-shell/#win-14) defines) a **Documentation** row of that menu runs it through the registry like every other row. An app with a Welcome page repeats the command in the page's Help row. The row's place in the Help menu is [DOCS-07](https://pauta-project.dev/6.0.0/documentation/#docs-07). - *Check (code):* the command `help.documentation` is registered and opens the user docs' address in the browser; where the app has a Help menu, a row of that menu runs the command (the Help `MenuSpec` of Editora's `MenuBarModel` lists it), and a row beside a Help submenu is not in it; and in an app with a Welcome page, the page's Help row runs the same command through the registry (`welcome.documentation` in Editora's `WelcomePane`). - *Reference:* Editora [`WindowCommandRegistrar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowCommandRegistrar.java) (`help.documentation` → [`MainController.openDocumentation()`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java)), [`MenuBarModel`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarModel.java) (`menubar.help`), [`WelcomePane`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WelcomePane.java) (`welcome.documentation`). Mirada's macOS Help menu has the row ([`MacMenus`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/MacMenus.java)); its main menu doesn't yet: there the Documentation row sits beside the Help submenu, not in it ([`ui/TitleBar.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/TitleBar.java)). - **DOCS-07 · SHOULD.** Where the app has a Help menu (the Help menu of a menu bar, or a Help submenu of the app's main menu, which [WIN-14](https://pauta-project.dev/6.0.0/window-shell/#win-14) defines), its rows run in this order: Command Palette · Documentation · the keyboard reference ([DOCS-08](https://pauta-project.dev/6.0.0/documentation/#docs-08)) · Welcome Page · Check for Updates · Message Log · Debug Log · Report a Problem · Pauta Conformance · About. In an app with a Simple mode, that mode's Help menu keeps Command Palette, Documentation, Welcome Page and About. An app without a feature drops its row; nothing moves. - *Check (code):* the rows of the Help menu the app has are in that order, in the full menu and in Simple mode's where the app has one (both `menubar.help` menu specs in Editora). An app with a Help menu in a menu bar on one OS and a Help submenu in its main menu is judged on both. - *Reference:* Editora [`MenuBarModel`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarModel.java), both `MenuSpec("menubar.help", …)`, for the rows its Help menu has. It has no Welcome Page row, since `view.welcome` is still in the View menu ([WELC-03](https://pauta-project.dev/6.0.0/templates/welcome/#welc-03)), and no keyboard-reference row. Termina's [`MenuBarModel`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/MenuBarModel.java) (`documentation`, `whatsNew`, `keyboardShortcuts`, then `checkForUpdates`) and Mirada's macOS menu bar, [`MacMenus`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/MacMenus.java) (`PALETTE`, `DOCUMENTATION`, `SHORTCUTS`, then `CHECK_FOR_UPDATES`) put the keyboard reference there; Termina's What's New row, between the two, is its own. The Help submenu of Mirada's main menu doesn't follow the order yet: it holds Message Log, Debug Log, Report a Problem, then Check for Updates, and Documentation, the keyboard reference and About are rows of the main menu beside it ([`ui/TitleBar.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/TitleBar.java)). - **DOCS-08 · SHOULD.** Where the app has a Help menu (the Help menu of a menu bar, or a Help submenu of the app's main menu, which [WIN-14](https://pauta-project.dev/6.0.0/window-shell/#win-14) defines), a row of it opens 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 [`ShortcutsWindow`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/ShortcutsWindow.java), a row of its Help menu, and Mirada's [`ShortcutsWindow`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/ShortcutsWindow.java), a row of its macOS Help menu; in Mirada's main menu the row sits beside the Help submenu. Editora doesn't yet: its keybinding editor is a page of Settings ([Keyboard first](https://pauta-project.dev/6.0.0/keyboard/)), and no row of its Help menu opens it ([`MenuBarModel`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarModel.java)). - **DOCS-10 · MAY.** An app with a Search Everywhere picker opens per-command help from it as the Command Palette does: with a command highlighted, the palette's help chord ([PAL-08](https://pauta-project.dev/6.0.0/templates/command-palette/#pal-08)) opens the command's page, `/docs/v-/commands/`. The two pickers share the chord and the URL builder, so they can never disagree. - *Check (code):* Search Everywhere takes its help chord the way the palette does and builds the page's address with the palette's own method (Editora's `CommandPalette.docsUrl`). - *Reference:* Editora [`SearchEverywhereHost`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SearchEverywhereHost.java) (`CommandPalette.docsUrl`) and [`SearchEverywherePopup`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SearchEverywherePopup.java) (`docsChord`, from [`PickerKeys.freeChord`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/PickerKeys.java) as the palette's); [`CommandPalette.docsUrl`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CommandPalette.java). - **DOCS-11 · MAY.** Each page of the Settings window has a link to its docs page, *Help for* and the page's name, 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsWindow.java), [`SettingsFrameBits.helpUrl`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsFrameBits.java), `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) and lists every guide with one line; that the code wins is [DOCS-17](https://pauta-project.dev/6.0.0/documentation/#docs-17). Which guides the folder holds is [REPO-07](https://pauta-project.dev/6.0.0/repository/#repo-07). - *Check (code):* `docs/README.md` exists, says who it is for, and links each guide in `docs/`. - *Reference:* Editora's [`docs/README.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/README.md); the template's [`docs/`](https://github.com/adriandeleon/adl-desktop-app-template/tree/b1ba438e61bce02fcbc389f1775f34a7def1ee31/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/`](https://github.com/adriandeleon/Editora/tree/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/decisions) (18 records, from [`0001-richtextfx-fork.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/decisions/0001-richtextfx-fork.md)). - **DOCS-14 · MUST.** Three files have three jobs. `AGENTS.md` is the operational guide (what it holds is [REPO-05](https://pauta-project.dev/6.0.0/repository/#repo-05)). `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):* `CONTRIBUTING.md` links into `docs/`. Neither `AGENTS.md`, `CONTRIBUTING.md` nor a guide in `docs/` ([REPO-07](https://pauta-project.dev/6.0.0/repository/#repo-07)) holds exhaustive history: a record of past work, or a catalog that sets out to list every part of a subsystem or every command (Editora's `architecture-catalog.md` and `commands.md` are two). Where the app keeps such material, it is in files under `docs/reference/`; an app that keeps none needs no `docs/reference/` and passes on the link. An audit report (`docs/pauta-audit.md`) is not such material. - *Reference:* Editora's [`AGENTS.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/AGENTS.md) (*Documentation map*), [`CONTRIBUTING.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/CONTRIBUTING.md), [`docs/reference/README.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/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 (code):* no Javadoc comment in the main or the test sources is followed by another with only blank lines or `//` comments between them. A test that asserts it is the surest evidence. - *Reference:* Editora [`StackedJavadocTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/StackedJavadocTest.java), which fails the build on one. ### Kept in step - **DOCS-16 · MUST.** The docs change with the code. A change that affects behavior updates `CHANGELOG.md` and the contributor guides it touches in the same pull request, the website's user docs in a pull request on the website's repository opened with it, and `TODO.md` where the app keeps one ([REPO-08](https://pauta-project.dev/6.0.0/repository/#repo-08)); never as a follow-up. A reviewer treats a feature PR with no docs change as incomplete. - *Check (by hand):* read the app's most recently merged feature pull requests on GitHub, as many as it takes to see the habit: each one's diff touches `CHANGELOG.md`, the guides it concerns and, where the app keeps one, `TODO.md`, and one that changes what a user sees names the website's pull request. A recent one that changed behavior and touched none of them fails the rule. That `docs/conventions.md`, `CONTRIBUTING.md` and `AGENTS.md` state the rule shows it is asked, not that it is kept. The person reads GitHub, not the running app, and the rule is still checked by hand: an audit reports it as `manual`. - *Reference:* Editora [`docs/conventions.md#docs-in-the-same-pr`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/conventions.md#docs-in-the-same-pr), [`CONTRIBUTING.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/CONTRIBUTING.md) (step 4, which names the website repository), [`AGENTS.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/AGENTS.md); the template's [`docs/conventions.md`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/docs/conventions.md). Editora, the template, Mirada and nux keep a `TODO.md`; Termina, Torrenta and Modula keep none. - **DOCS-17 · MUST.** When documentation and code disagree, the code wins, and the documentation is fixed in the same change. `AGENTS.md` and `docs/README.md` say so, where a coding agent and a contributor start reading. Pauta applies the same rule to itself. - *Check (code):* `AGENTS.md` and `docs/README.md` say so. - *Reference:* Editora's [`AGENTS.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/AGENTS.md), [`docs/README.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/README.md). - **DOCS-18 · SHOULD.** An app's screenshots are retaken, not described: its capture hook or headless fixture ([QUAL-09](https://pauta-project.dev/6.0.0/quality/#qual-09)) 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 (by hand):* the README's hero, in its light and its dark form, and the website's screenshots show the current UI at 2×; they are rendered from the real window by the capture hook or headless fixture [QUAL-09](https://pauta-project.dev/6.0.0/quality/#qual-09) asks for, not drawn or described. - *Reference:* Termina's [`DevCapture.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/DevCapture.java) and Torrenta's [`DevCapture.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/DevCapture.java), and nux's [`ui/Screenshot.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/Screenshot.java) ([Shared features](https://pauta-project.dev/6.0.0/family/shared-features/)). None of the three renders at 2× yet: each writes what `scene.snapshot(null)` returns, the scene at its own size. Editora doesn't yet: it has no capture hook, and its headless fixture writes a screenshot from three FX tests only, when `-Deditora.test.shots=` is set, and at the scene's own size too ([`SplitViewFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/SplitViewFxTest.java)). ## Code quality gates (QUAL) https://pauta-project.dev/6.0.0/quality/: NullAway, coverage floors and the guard tests that pay for themselves across the family. - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/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 ([PLAT-12](https://pauta-project.dev/6.0.0/platform/#plat-12)), the build holds a branch floor (Editora's is 0.79), and 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 `BUNDLE` `BRANCH` limit and a `PACKAGE` line floor for each large package. - *Reference:* Editora [`pom.xml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/packaging/BuildHygieneTest.java), [`docs/testing.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/testing.md). - **QUAL-05 · SHOULD.** Extract the decision, then test it ([principle 12](https://pauta-project.dev/6.0.0/principles/#for-the-people-building-them)): what decides whether a control is enabled or shown, or where a key or a click leads, sits in a pure helper with unit tests. The headless FX harness is for a test whose point is controller or toolkit behavior. - *Check (code):* enablement, visibility and navigation rules sit in classes that import no `javafx` type, each with a unit test that does not carry the FX tests' tag ([QUAL-06](https://pauta-project.dev/6.0.0/quality/#qual-06)). - *Reference:* Editora [`docs/testing.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/testing.md) (*Prefer pure logic*): [`ui/Chrome`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Chrome.java), [`editops/TextNav`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/editops/TextNav.java), [`config/PathKeys`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/PathKeys.java), each with a plain unit test. - **QUAL-06 · MUST.** Every test class that boots the JavaFX toolkit carries one JUnit tag, the same for all of them (Editora's is `fx`), so the pure suite runs alone by excluding that tag (`-DexcludedGroups=fx` in Editora). - *Check (code):* every test class that boots the toolkit (`Platform.startup`, `FxToolkit`, or a helper that calls one, such as Editora's `FxTestSupport`) carries the app's FX tag in a JUnit `@Tag`, whatever the tag is called (`@Tag("fx")` in Editora). - *Reference:* Termina holds it by test: [`FxTestTagsTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/FxTestTagsTest.java) fails when a test source that names `Platform.startup(` or `FxToolkit.` has no `@Tag("fx")`. Editora states it in [`docs/testing.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/testing.md) and does not hold it fully yet: 33 of its `*FxTest` classes, 18 of them `ProjectMap*FxTest`, carry no tag. Torrenta doesn't yet: 26 of its test classes start the toolkit through its [`FxToolkit`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/test/java/com/torrenta/ui/FxToolkit.java) extension, and no test in the repository carries a tag. - **QUAL-07 · SHOULD.** Tests do not sleep. A scope owns the workers and FX callbacks (Editora's `AsyncTestScope`), and tests wait on latches. - *Check (code):* `grep -rn 'Thread.sleep' src/test` finds nothing. - *Reference:* Editora [`AsyncTestScope`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/AsyncTestScope.java), [`docs/testing.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/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 (code):* the fixture that builds a test window gives it a temp config folder, and points every other folder a command writes to (the one a configuration export lands in, say) at a temp folder too. A test that asserts it is the surest evidence. - *Reference:* Editora [`FxWindowFixture`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/FxWindowFixture.java) (a temp config folder and a temp export folder for each window); [`CommandSweepFxTest.leftInTheHomeDirectory`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/CommandSweepFxTest.java) looks in the home directory after running every command. - **QUAL-09 · MUST.** The app has a way to show its real window with nobody at the screen: a capture hook that saves a screenshot of it, or a headless fixture that builds it as the app does. That is what verifies UI work in the running app ([principle 13](https://pauta-project.dev/6.0.0/principles/#for-the-people-building-them)), with real key and mouse events, before a UI change is called done. - *Check (code):* the app has a capture hook (Termina's `DevCapture`) or a headless fixture (Editora's `FxWindowFixture`) that builds the real window through the code the app itself starts with. - *Reference:* Editora [`FxWindowFixture`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/FxWindowFixture.java) (the real [`MainController`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java) window, headless); Torrenta's [`DevCapture.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/DevCapture.java) and Termina's [`DevCapture.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/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`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/test/java/com/modula/DependenciesTest.java). - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/CommandSweepFxTest.java). - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/SettingsRoundTripFxTest.java). - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/packaging/ReleaseSupplyChainTest.java). ## Performance (PERF) https://pauta-project.dev/6.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. Two exceptions. At start-up, before the first window is shown, `start()` may wait once for the config read that [PERF-16](https://pauta-project.dev/6.0.0/performance/#perf-16) began before the toolkit, and may read the bundled resources that window is built from: its fonts, registered there or by a thread `start()` waits for once ([ICON-02](https://pauta-project.dev/6.0.0/icons-and-color/#icon-02) requires them before any CSS is applied), the message catalog, the keymap and its icons. Nothing else at start-up is excepted: a log file opened, a file or a store of the user's read (presets, profiles, schedules, themes the user added), a ledger read, a socket bound or a lock taken blocks the thread as it would anywhere, and so does a font registered on it after the first frame. And as the app quits, when no frame is left to block, the quit method ([WIN-13](https://pauta-project.dev/6.0.0/window-shell/#win-13)) or `Application.stop()` may make the last save on it: write the settings, the window state and the session, or wait for a write already under way. An app whose `start()` loads its settings itself, whether or not `main` read the file earlier, or waits for a read begun after the toolkit, has PERF-16's gap and none here. - *Check (code):* `grep -rnE 'Files\.[a-z]|File(Input|Output)Stream|File(Reader|Writer)|RandomAccessFile|getResourceAsStream|loadFont|HttpClient|openConnection|openStream|new Socket|SocketChannel\.open|ProcessBuilder|getRuntime\(\)\.exec|\.waitFor\(|Thread\.sleep|\.join\(\)|uture[A-Za-z]*\.get\(|\.get\([^)]*TimeUnit|invokeAndWait|\.await\(' src/main/java` lists the candidates: the lines that read or write a file or a bundled resource, open a connection, start or wait for a process, sleep, or wait for another thread. Each line is judged by reading what calls it. It is fine when only an executor's task or a thread's body reaches it; when `start()` reaches it before the first window is shown and it is one of the things the statement allows there, the one `join()` or `get()` on the config read begun before the toolkit, or the reading of a resource bundled with the app that the first window is built from: the registering of the fonts it draws with (Editora's `Fonts.loadForFirstPaint`) or the one wait for the thread that registers them, the message catalog (Editora's `Messages.init`), the keymap (Editora's `KeymapManager.loadNamed`) or the window's icons; or when it is the last save, made by the quit method or `Application.stop()`, which may do nothing else that blocks. It is a violation when an event handler, a listener, a `Platform.runLater` body, a timer's or an animation's callback, or `start()` reaches it on the FX thread, itself or through a method it calls: a handler that calls a settings store's `save()` writes the file on the FX thread. In `start()` everything else is a violation, before the first window is shown or after: a second wait for the config, a log file opened, a file or a store of the user's read (presets, profiles, schedules, a folder of themes the user added), a ledger read, a socket bound, a lock taken. Only the settings are left to [PERF-16](https://pauta-project.dev/6.0.0/performance/#perf-16): a load of them made in `start()` itself, whether or not `main` read the file earlier, and a wait for a read of them begun after the toolkit. A font registered on the FX thread after the first frame is a violation too. A grep finds only the spellings it is given: read the handlers and listeners too for parsing, searching, hashing or JSON done in place, and for a wait under another name. - *Reference:* Editora [`docs/performance.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/performance.md) §1; its one start-up wait is `takeBootstrap` in [`App.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java), which joins the `config-prefetch` read, and `Fonts.loadForFirstPaint`, called next, registers its first fonts ([`ui/Fonts.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Fonts.java)); the `config-prefetch` thread reads the catalog too, and `start()` reads it only when that thread picked another language (`Messages.init`). Mirada's `start()` makes the two waits the first exception allows: `settings()` joins the settings read, which also reads its catalog (in its jlink image that read begins after the toolkit, which is [PERF-16](https://pauta-project.dev/6.0.0/performance/#perf-16)'s gap and none here), and `Fonts.ready`, before the window is shown, joins the thread that registers its fonts ([`App.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/App.java), [`ui/Fonts.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Fonts.java)). For the last save, the app template's [`MainWindow.quit`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/MainWindow.java) waits for the settings write on a background thread and exits from there, which needs no exception, and its `Application.stop()` then waits for the writer once more on the FX thread (`Running.close` in [`ui/Startup.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Startup.java)), which the second exception allows; Termina's [`WindowManager.closeAll`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/WindowManager.java), run from `Application.stop()`, flushes its settings on the FX thread, which the second exception allows. No app has been read through for the rule yet, and none holds it everywhere. Found so far: Editora's `start()`, in that `App.java`, does on the FX thread, before its first window is shown, what no exception covers: its calls to `DebugLog.attachFile` (the Debug Log's session file), `SharedConfig.claimInstance` (the lock on a file in the config folder), `ProcessRegistry.reapOrphans` (the ledger of the servers it started), `McpServer.reapStaleEndpoint` (a stale `mcp-endpoint.json`) and `Themes.loadUserThemes` (the user themes' folders). Some of its handlers still touch the disk too, for example `renameFileTo` (`Files.exists`, `Files.move`) and `openPersonalDictionary` (`Files.writeString`) in [`ui/MainController.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java) and the new-folder prompt in [`ui/ProjectPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ProjectPanel.java) (`Files.createDirectories`). The app template's `start()` registers its fonts and reads its catalog, which the exception allows (`Fonts.load`, `Messages.init`), and opens the Debug Log's session file on the FX thread, which it does not (`DebugLog.attachFile`, all called from [`ui/Startup.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Startup.java)); once the window is shown it deletes a stale socket file and binds the socket for later launches there ([`SingleInstance.listen`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/instance/SingleInstance.java)), and after the first frame it registers its remaining font on the FX thread (`Fonts.loadDeferred`), neither of which an exception covers. Torrenta's `start()` reads its catalog, which the exception allows, and opens that file the same way (`DebugLog.attachFile` in its [`App.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/App.java)); its main window's constructor, before the window is shown, reads six stores of the user's (the profiles, the labels, the watch folders, the search providers, their definitions and the RSS feeds, in [`ui/MainWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java)), and `start()` reads `profiles.json` again once the window is shown (`Startup.profile`). Termina reads its settings, its first fonts, its catalog and its imported themes in `Application.init()`, off the FX thread (`prepare` in its [`App.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/App.java)); building its first window then reads the bundled keymap ([`ui/Keymap.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/Keymap.java), on the first `Keymap.defaultFor`) and decodes the window's icons ([`ui/Icons.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/Icons.java), `Icons.applyTo`) on the FX thread, which the exception allows, and once the window is shown `start()` deletes a stale socket file and binds the socket for later launches there, which it does not (`serve` in [`instance/SingleInstance.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/instance/SingleInstance.java)). It also registers its remaining font families on the FX thread after the first frame, which no exception covers ([`Fonts.loadRest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/Fonts.java), called from that `App.java`). Mirada, on macOS, compares two paths on the FX thread when it was started with a file and the OS hands it its first one (`Files.isSameFile` in [`os/MacOpenFiles.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/os/MacOpenFiles.java)). nux waits up to two seconds for the tray icon's removal in the handler of Settings' Save ([`AwtTray.dispose`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/tray/AwtTray.java), reached from [`TrayController.settingsSaved`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/app/TrayController.java)) and writes its `--screenshot` file from an animation's callback ([`ui/Screenshot.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/Screenshot.java)). Torrenta writes its settings from the listeners of its Settings rows (`saveQuietly` in [`ui/SettingsWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/SettingsWindow.java)) and asks the file store for the free space on each keystroke in a save-folder field (`updateFreeSpace` in [`ui/LocationDialog.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/LocationDialog.java)). Modula reads its presets and its schedules in its pane's constructor, before the window is shown (`config.loadPresets` and `config.loadSchedules` in [`ui/RadioPane.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/RadioPane.java)), writes its presets and settings from handlers (`config.savePresets` and `config.saveSettings` in that file) and, building its Settings window, starts `ffmpeg -version` and waits up to five seconds for it ([`Encoders.isAvailable`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/audio/Encoders.java)). - **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):* `grep -rnE 'new Thread\(|Thread\.(ofVirtual|ofPlatform|startVirtualThread)|\.(submit|execute|schedule|scheduleAtFixedRate|scheduleWithFixedDelay)\(|(supply|run)Async\(|\.(thenAccept|thenRun|thenApply|thenCompose|whenComplete|handle|exceptionally)(Async)?\(' src/main/java` lists the candidates: the lines that start a thread, hand a task to an executor, or add a step to a future that completes off the FX thread. Each line is judged by reading the task's body. It is fine when the body touches nothing a scene shows, or touches it only inside `Platform.runLater`. It is a violation when the body, or a method it calls, sets a control's value, changes an observable list a view shows, or reads a live node's state outside a `runLater`. A callback that a library runs on a thread of its own (a file watcher, a process's reader, a logging handler) is a task body too, and the grep does not list those: read the listeners the app gives its services as well. - *Reference:* Editora [`git/GitService.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/git/GitService.java): every task it gives its workers hands the result to its caller inside `Platform.runLater`. No app has been read through for the rule yet. - **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):* `grep -rn 'runLater' src/main/java` lists the candidates: the lines where another thread hands something to the FX thread. Each line is judged by reading it. It needs the guard when what it applies answers a request that can be made again before the answer comes: a search, a load, a status or completion query that typing, a selection or a refresh starts. There each request takes a mark that the next request replaces (a counter, as Editora's `AtomicLong.incrementAndGet`, or a helper that keeps the latest request only, as Editora's `LatestOnly`), and the answer is applied only while its mark is still the newest, compared inside the `runLater`. It is a violation when such an answer is applied with no comparison, or with one made only before the `runLater`. A line needs no guard when nothing newer can replace what it hands over: an event, a batch of a stream, a result asked for once at start-up. - *Reference:* Editora [`git/GitService.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/git/GitService.java) (`refresh`, with its `refreshGen` counter), [`search/SearchService.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/search/SearchService.java) and [`ui/LatestOnly.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/LatestOnly.java) ([`LatestOnlyTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/LatestOnlyTest.java)); Termina ([`work/LatestOnly.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/work/LatestOnly.java)) and Mirada ([`ui/LatestOnly.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/LatestOnly.java)) carry the same helper. No app has been read through for the rule yet. Found so far: nux applies each Refresh of its Events window, and each load of the Energy and Outages tabs of its History window, with no mark ([`ui/EventsWindow.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/EventsWindow.java), `offFx` in [`ui/HistoryWindow.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/HistoryWindow.java)), beside a Charts tab that numbers its loads and applies only the newest. - **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 [`terminal/TerminalExecutors.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/terminal/TerminalExecutors.java) (its `daemon(name)` thread factory); the canonical shape is in [The UI thread](https://pauta-project.dev/6.0.0/performance/#the-ui-thread). - **PERF-05 · MUST.** Blocking work stays off the common `ForkJoinPool`: no `supplyAsync` or `runAsync` without an executor runs a blocking call, and a `Process` subclass overrides `onExit()`, whose inherited version is a `waitFor()` on that pool. - *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 (a wait, a read or write of a file, a socket or a process), and every class that extends `Process` overrides `onExit()`. An app with no `Process` subclass has only the first half to show. - *Reference:* Editora [`process/ExitWatch.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/process/ExitWatch.java), [`docs/gotchas.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/gotchas.md). Editora's [`DapManager.reportJavaExit`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/dap/DapManager.java) still waits up to 3 s for an exit code in a `supplyAsync` on the common pool, and Termina's `handOff` in [`instance/SingleInstance.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/instance/SingleInstance.java) connects to a socket, writes and reads in one. ### Hot paths - **PERF-06 · MUST.** Redraws are coalesced to at most one per pulse, with a flag that one request is already queued. A redraw is the painting of what the app draws itself, a canvas, a chart or a grid of cells; in an app that paints nothing itself, it is the refresh of its list or view. - *Check (code):* a redraw request sets a flag (Editora's are named `…Pending`) and schedules one pass, and a request that finds the flag set schedules nothing. A handler that paints, or in an app that paints nothing refreshes its list or view, straight from its event has no such flag and fails: a chart drawn from its width listener and again from its height listener draws twice for one resize. Setting a control's own property in a handler (a label's text, a progress bar's value) is not a redraw: JavaFX draws the control once on the next pulse. - *Reference:* Editora [`docs/performance.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/performance.md) §2 (the `redrawPending` shape) and [`ui/WindowToolbar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowToolbar.java) (`scheduleEditStateRefresh`, with its `editStateRefreshPending` flag). [`ui/FxThrottle.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/FxThrottle.java) is another tool: a leading-edge throttle with a maximum wait and no such flag, which runs the first request of a burst at once and then at most one per interval. - **PERF-23 · MUST.** Work driven by text the user types waits for typing to pause (a debounce) when it leaves the FX thread or cannot finish within a frame: a search of files, a request to a server, a re-highlight. Filtering a list already in memory, as a command palette does, is exempt and runs on every keystroke. - *Check (code):* a listener on a text input's text that starts background work, or work too long for one frame, restarts a timer (a `PauseTransition`'s `playFromStart`, or the app's debounce helper) and the work runs when the timer fires; a listener that only filters or ranks an in-memory list needs none. - *Reference:* Editora [`ui/SearchInFilesPopup.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SearchInFilesPopup.java) (150 ms before `runSearch`), [`ui/SearchEverywherePopup.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SearchEverywherePopup.java) (120 ms), [`ui/WorkspaceSymbolPopup.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WorkspaceSymbolPopup.java) (150 ms before the language server is asked) and, for the editor's text, [`editor/SettledEditDispatcher.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/editor/SettledEditDispatcher.java), one timer that runs the re-highlight 150 ms after the last edit. Its [`ui/CommandPalette.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CommandPalette.java) and [`ui/QuickOpen.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/QuickOpen.java) filter their in-memory lists on every keystroke: the exempt case. Editora doesn't hold the rule everywhere yet: the debugger's completion ([`ui/DebugCompletion.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/DebugCompletion.java)) asks the debug adapter again on every change of the field's text while its list is open, with no timer, and [`ui/FileFinder.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/FileFinder.java) starts reading a folder as soon as the typed path names another one. - **PERF-07 · MUST.** An app that shows a stream as it arrives (the output of a process, log records, progress or readings from another thread) hands it to the FX thread in batches at least 16 ms apart, never one `runLater` per line or record. - *Check (code):* in an app that shows a stream, the thread that receives it appends to a buffer that the FX thread drains, with a minimum interval of 16 ms or more between drains, or once a pulse (pulses come a frame apart); no reader calls `Platform.runLater` once for each line or record. A stream is what arrives at its source's pace, however many items that is: a process's output, log records, the results of a scan handed over as each is found. A poll the app paces itself, one hand-over for each tick of a timer of 16 ms or more (a reading fetched every few seconds), already hands over that far apart and needs no buffer. An app whose FX thread is sent no stream, as one whose log window reads its store only when it opens or is refreshed, is not covered. - *Reference:* Editora [`process/OutputPump.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/process/OutputPump.java) (`MIN_DRAIN_INTERVAL_MILLIS`), [`ui/ConsoleAppender.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ConsoleAppender.java). Torrenta doesn't yet for its event log: the bridge in [`ui/EventLog.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/EventLog.java) (`logBridge`) hands each warning it catches to the FX thread in a `runLater` of its own. nux doesn't yet for its network scan: `scan` in [`service/DiscoveryService.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/service/DiscoveryService.java) hands each server it finds to the FX thread in a `runLater` of its own; its poll hands over one reading every five seconds ([`service/PollService.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/service/PollService.java)), which is paced already. Mirada's Debug Log window ([`ui/DebugLogWindow.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/DebugLogWindow.java)) reads the log when it opens and on Refresh, so no log stream reaches its FX thread. - **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, and a list the user or the data can grow without a limit the app sets is shown in a virtualized control (`ListView`, `TableView`, a fixed cell size), which builds nodes for the visible rows only. Filtering a list already in memory, as a command palette does, is exempt and runs on every keystroke. - *Check (code):* `grep -rnE 'textProperty\(\)|KEY_(TYPED|PRESSED)|setOnKey|setOnScroll|vvalueProperty|AnimationTimer|Timeline|PauseTransition|scheduleAtFixedRate' src/main/java` lists the first candidates: the listeners on text, keys and scrolling, and the timers. Each line is judged by reading what it runs on every keystroke, scroll or tick. It is fine when that handles the edited range or the visible rows, or filters or ranks a list already in memory. It is a violation when it reads, measures, styles or rebuilds the whole document or every item of a list. An editor's own stream of changes is a text listener too (Editora's `plainTextChanges`), which the grep does not list. `grep -rnE 'getChildren\(\)\.(add|addAll|setAll)\(' src/main/java` lists the second: the lines that put nodes into a pane. It is a violation where a loop makes one node for each item of a list the user or the data can grow without a limit the app sets (results, log records, files, transfers), which belongs in a `ListView` or `TableView`; it is fine where the pane holds a set of controls the code fixes, or a list the app caps at a number it names (a bar of at most five preset chips). - *Reference:* Editora [`editor/highlight/HighlightPass.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/editor/highlight/HighlightPass.java), which restyles only as far as an edit reaches. No app has been read through for the rule yet. Found so far, each a loop that makes a node for every item of a list nothing caps: Modula's preset bar (a chip for each preset, `rebuild` in [`ui/PresetBar.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/PresetBar.java)); nux's dashboard (a card for each saved profile it watches and for each UPS, rebuilt as readings arrive, `setFleet` and `setOverview` in [`ui/Dashboard.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/Dashboard.java)); Torrenta's rule and tags dialogs (a check box for each feed and each tag, [`ui/RuleDialog.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/RuleDialog.java), [`ui/TagsDialog.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/TagsDialog.java)); and Editora's crontab preview and pull-request checks card (a node for each job and each check run, [`editor/structured/CrontabPreview.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/editor/structured/CrontabPreview.java), [`ui/ChecksListCard.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ChecksListCard.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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/editor/minimap/Minimap.java) (the snapshot image reused at the same size), [`MinimapRows.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/editor/minimap/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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/editor/highlight/TextMateHighlighter.java), [`docs/gotchas.md`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/gotchas.md). ### Memory and size - **PERF-11 · MUST.** Everything that grows is bounded: logs, histories, consoles, caches, undo. The newest is kept. - *Check (code):* each store that grows while the app runs (a log, a history, a console's text, a cache, an undo stack) has a named cap, and the code that adds to it drops the oldest entry once the cap is passed. A test that fills a store past its cap and finds the oldest dropped is the surest evidence. - *Reference:* Editora [`ui/MessageLog.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MessageLog.java) (200 entries, the oldest dropped; [`MessageLogTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/MessageLogTest.java)), [`ui/DebugLog.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/DebugLog.java) (2,000 records, the oldest dropped; [`DebugLogTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/DebugLogTest.java)), and [`test/OutputCap.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/test/OutputCap.java), which keeps the head and the tail of one test's output (200,000 characters) with a note between them of how much was cut. The note is Editora's choice, not part of the rule. - **PERF-12 · MUST.** In an app that opens files or data the user picks, a large input is guarded before it loads: its size is checked before its content is read, or the read is capped, and what will not fit is never read in. The app refuses it with a message or opens only the part that fits. Where an input can open with less, without features the app runs over its content, as a file in an editor can open without highlighting or a minimap, the app steps down as the input grows: those features turn off past one threshold, and past another it opens read-only or capped. An input the app can only read in or refuse (an imported theme, a `.torrent` file) has nothing to step down to. - *Check (code):* the code that loads a picked file or import compares its size against a named limit before reading the content, or reads through a cap, and refuses or cuts what passes the limit. Where the app runs features over an input's content that the input can open without (an editor's highlighting, its minimap), a lower named threshold turns them off and a higher one opens the input read-only or capped. Where it runs none, the size check or the cap is the whole of the rule. - *Reference:* Editora, whose tiers are the example: [`EditorBuffer.LARGE_FILE_BYTES`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/editor/EditorBuffer.java) (5 MB: no highlighting, no minimap) and `HUGE_FILE_BYTES` (50 MB: read-only and cut to 50 MB), and [`ui/LoadHeapGuard.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/LoadHeapGuard.java), which caps a load at what the free heap affords ([`LoadHeapGuardTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/LoadHeapGuardTest.java)). Termina's theme import has nothing to step down to: `importFile` in [`ui/Themes.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/Themes.java) reads at most 8 MB and [`theme/ThemeImport.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/theme/ThemeImport.java) refuses a file over 4 MB. Torrenta doesn't yet for a `.torrent` file the user picks: `resolve` in [`session/Session.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/session/Session.java) reads it whole (`Files.readAllBytes`) without looking at its size. - **PERF-13 · MUST.** A closed window releases what it held: listeners, timers, executors, file watchers, native resources. - *Check (code):* the code that runs when a window closes (its close or hide handler, or the dispose method that handler calls) stops every timer and animation the window started, shuts down every executor, thread and file watcher it owns, frees its native resources (a process, a socket, a file handle), and removes each listener it added to something that outlives it: the shared settings, a service, another window. A test that opens and closes windows and finds nothing left running is the surest evidence. - *Reference:* Editora's [`MainController.disposeWindow`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java), which shuts down each owner of a window's workers in turn, one failure never skipping the rest ([`ui/WindowDisposal.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowDisposal.java)). Its tests: [`FxWindowFixtureLifecycleFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/FxWindowFixtureLifecycleFxTest.java), which finds a disposed window's workers shut down, and [`ClosedLspManagers`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/lsp/ClosedLspManagers.java). The app template ([`WindowLifecycleFxTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/ui/WindowLifecycleFxTest.java)), Termina ([`WindowLifecycleTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/ui/WindowLifecycleTest.java)) and Mirada ([`ClosedWindowTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/ui/ClosedWindowTest.java)) have such a test too. ### Start-up - **PERF-14 · MUST.** The first frame comes first: only what the first window shows is built before it. Everything else builds on first open: a closed panel's content, the Settings pages, the dialogs and the other windows. - *Check (code):* the code that builds the first window (`start()`, and the main window's constructor and what it calls) makes only what that window shows: no Settings window or page, no dialog, no other window and, in an app with tool panels, no closed panel's content. Each of those is made by the code that first opens it, through a supplier or a field filled on first use. A test that opens the first window and finds none of them built is the surest evidence. - *Reference:* Editora's lazy [`ToolWindow`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindow.java) suppliers, and its Settings pages, built on the first `show` ([`ui/SettingsWindow.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsWindow.java)). [`LazyToolWindowsFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/LazyToolWindowsFxTest.java) asserts the tool-panel part: no closed tool window has built its panel. Editora doesn't hold the rule in one place yet: it builds the shared Output console (`buildOutput`), an empty tab pane, with the window, because every build writes to it while it is closed, and the test leaves that panel out. The template's [`StartupDeferralFxTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/ui/StartupDeferralFxTest.java) and Mirada's [`StartupDeferralTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/ui/StartupDeferralTest.java) assert it for their first windows. Torrenta doesn't yet: the constructor of its main window makes the Log, the Statistics and the Settings windows (`new LogWindow`, `new StatisticsWindow`, `new SettingsWindow` in [`ui/MainWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java)). - **PERF-15 · MUST.** What nobody waits for starts after the first frame has painted: the update check, extra fonts, indexes and caches. - *Check (code):* the update check, the loading of fonts the first window does not draw with, and the building of indexes and caches start from a callback that runs once the first frame has painted (a pulse after the window is shown, as Editora's `loadRemainingAfterNextPaint` waits for), never from `main`, `init()` or the body of `start()`. A test that finds the deferred work not started before the first paint is the surest evidence. - *Reference:* Editora [`ui/UpdateCheckScheduler.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/UpdateCheckScheduler.java), [`Fonts.loadRemainingAfterNextPaint`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Fonts.java) ([`UpdateCheckSchedulerTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/UpdateCheckSchedulerTest.java), [`FontsDeferredLoadFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/FontsDeferredLoadFxTest.java), [`StartupDeferralFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/StartupDeferralFxTest.java)). The template (`FirstPaint.then` in [`ui/Startup.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Startup.java)), Termina (`FirstFrame.after` in its [`App.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/App.java)) and Mirada (`afterFirstPaint` in [`ui/ViewerWindow.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/ViewerWindow.java)) defer theirs the same way. Modula and nux don't yet: each starts its update check in the body of `start()` (`checkForUpdates` in [`ModulaApp.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ModulaApp.java), `maybeCheckForUpdates` in nux's [`App.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java)). - **PERF-16 · SHOULD.** The config read starts on a thread of its own before the toolkit does, so the two overlap and the wait for it that [PERF-01](https://pauta-project.dev/6.0.0/performance/#perf-01) allows at start-up, `start()` taking the result, is short. An app whose `start()` loads its settings itself does not meet this, whether or not `main` read the file earlier. - *Check (code):* `main` starts the config read on its own thread before `launch`, from an entry point that is not the `Application` subclass (the launcher starts the toolkit for one before its `main` runs), and `start()` takes that read's result instead of reading the files itself. A load `start()` makes only when the earlier read failed is a fallback and passes. - *Reference:* Editora's `config-prefetch` thread in [`App.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java) (`prefetchConfig`, joined once by `takeBootstrap`), entered through [`Launcher.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/Launcher.java). Mirada's `settings-read` thread in its [`App.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/App.java) (`readSettings`, joined by `settings()`) does the same in the native image, which enters through `Launcher`; its jlink image's main class is `App` itself, so there the toolkit is up before the read starts. Termina reads its settings in `Application.init()` (`prepare` in its [`App.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/App.java)): off the FX thread, so `start()` waits for nothing, but after the toolkit has started. The template (`ConfigStore.open` in [`ui/Startup.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Startup.java)), Torrenta ([`App.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/App.java)), Modula ([`ModulaApp.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ModulaApp.java)) and nux ([`App.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java), which also reads the file once in `main` for the language) load their settings inside `start()`. Torrenta's `main` reads the file once as well, on the main thread, for its tray and badge settings. - **PERF-17 · SHOULD.** The app ships precompiled stylesheets (`.bss`). The AOT cache, the other half of a fast start, is [REL-10](https://pauta-project.dev/6.0.0/release/#rel-10). - *Check (code):* the build converts the app's `.css` files to `.bss`, and the packaged app carries them. - *Reference:* Editora [`scripts/css2bss.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/scripts/css2bss.java), run by the `css-to-bss` execution in [`pom.xml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/pom.xml). No other app converts its own stylesheets yet. ### 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/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, Termina and Mirada; Editora [`perf/Startup.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/perf/Startup.java) (`EDITORA_PERF_SAMPLE=1`, with `EDITORA_PERF=1`); Mirada [`perf/FxSampler.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/perf/FxSampler.java) (`MIRADA_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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/MinimapDeferredRenderFxTest.java). - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/docs/performance.md). ## Keyboard first (KBD) https://pauta-project.dev/6.0.0/keyboard/: Commands, the Command Palette, keymaps, focus and accessibility. ### Commands - **KBD-01 · MUST.** Every user-facing action is a command (an id, a title and a runnable) registered in one command registry (Editora's `Command` and `CommandRegistry`). - *Check (code):* what a menu item, a toolbar button, a palette row or a key binding does is a registered command: the control runs the command's id through the registry, or calls what the command's runnable calls. No button, menu row or key handler does work no command can reach. - *Reference:* Editora [`command/Command.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/command/Command.java), [`command/CommandRegistry.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/command/CommandRegistry.java). Editora doesn't hold the rule everywhere yet: the Clear button of its Message Log ([`ui/MessageLogPopup.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MessageLogPopup.java)) empties the log in its own handler, and the Previous Run and Save Output buttons of its build console ([`ui/BuildToolPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/BuildToolPanel.java)) work the same way, with no command behind any of the three. Termina doesn't either. These buttons, among others, do their work in handlers of their own with no command behind them: Clear in its Message Log ([`ui/MessageLogWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/MessageLogWindow.java)), Refresh, Copy, Export and Clear in its Debug Log ([`ui/DebugLogWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/DebugLogWindow.java)), and Import theme in Settings ([`ui/SettingsWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/SettingsWindow.java)). - **KBD-02 · SHOULD.** Command ids are dotted and grouped by area, as in `file.open`, `view.toggleStatusBar` and `help.reportProblem`. A rule that names a command's id requires that id; these three are examples. - *Check (code):* every registered id is two or more names joined by dots, and the first is the area the command belongs to: `file.open`, and with a sub-area `git.log.checkout`. - *Reference:* Editora [`ui/MenuBarModel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarModel.java). - **KBD-03 · MUST.** A command's title comes from `command.` and its one-line palette description from `command..desc` in the message catalogs. - *Why:* a registered command is then localized and discoverable without extra work. - *Check (code):* every registered command has a `command.` and a `command..desc` key in the message catalogs, and the registry reads its title and description from them. A catalog parity test that walks the registered commands and fails on a missing key is the surest evidence. - *Reference:* the app template's [`CommandSweepFxTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/ui/CommandSweepFxTest.java) (`everyCommandIsLocalizedAndRuns`) and Mirada's [`CommandCatalogTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/ui/CommandCatalogTest.java) (`everyCommandHasItsTitleAndDescriptionInTheCatalog`) walk the registered commands. Editora [`i18n/messages.properties`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/i18n/messages.properties); its [`MessagesTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/i18n/MessagesTest.java) (`everyCommandTitleHasAMatchingDescription`) walks the catalog instead, so it finds a title with no description but not a registered command with neither. - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/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; the IntelliJ keymap may use IntelliJ's own Find Action chord, `Ctrl+Shift+A` (`Cmd+Shift+A`), instead. An app with one key table and no Emacs keymap, which is a terminal app's own keymap ([KBD-09](https://pauta-project.dev/6.0.0/keyboard/#kbd-09)) or the built-in table of an app that ships no keymap files, counts as one of the others: it binds `Ctrl+Shift+P` (`Cmd+Shift+P` on macOS). An app that ships no keymap files owes this chord and fails KBD-09 all the same: KBD-09 requires the files of every app. - *Check (code):* each bundled keymap binds that chord to the palette command, and so does the one key table of an app that has no keymap files. An app whose chord opens the palette from a handler, with no palette command registered, passes this rule and fails [PAL-01](https://pauta-project.dev/6.0.0/templates/command-palette/#pal-01) for the missing command. - *Reference:* Editora [`keymaps/emacs.json`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps/emacs.json) (`M-x`), [`cua.json`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps/cua.json) and [`vscode.json`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps/vscode.json) (`C-S-p`), [`cua.mac.json`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps/cua.mac.json) (`Cmd-S-p`), all to `palette.show`; [`intellij.json`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps/intellij.json) binds `C-S-a`. Termina's one keymap binds `Shortcut+Shift+P`, which is `Ctrl+Shift+P` in [`keymap.json`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/resources/com/termina/keymaps/keymap.json) and `Cmd+Shift+P` in [`keymap.mac.json`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/resources/com/termina/keymaps/keymap.mac.json), and nux, which ships no keymap file, binds the same chord in [`App`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java). Torrenta and Modula don't yet: Torrenta's one key table opens the palette with `Alt+X` alone ([`ui/Chords.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/Chords.java)), and Modula's key filter tests for `Ctrl` on every OS, so its chord is `Ctrl+Shift+P` on macOS too ([`ui/RadioPane.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/RadioPane.java)). - **KBD-06 · SHOULD.** The palette matches fuzzily over the command's title and over the words of its id or its keywords; the description is shown, not matched. 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/6.0.0/templates/command-palette/). - *Check (code):* the palette's matcher matches the query fuzzily against each command's title and finds a command by a word of its id or a keyword that its title doesn't carry; a query that spells a command's title ranks that command above the fuzzy hits; the description is drawn and never matched, and each row draws the binding the active keymap gives the command. A ranking test that asserts the order is the surest evidence. - *Reference:* Editora [`ui/CommandPalette.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CommandPalette.java) (`orderedMatches`), [`search/FuzzyMatch.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/search/FuzzyMatch.java). It scores the title first; when the title doesn't match, the id's namespace word as a keyword ([`Command.keywords`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/command/Command.java)); then the names IntelliJ and VS Code give the command ([`command/OtherIdeNames.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/command/OtherIdeNames.java)). It doesn't match the rest of the id or the description, which is shown under the list. [`CommandPaletteRankTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/CommandPaletteRankTest.java) holds the order (`aCommandIsFoundByItsNamespaceWhenItsTitleDoesNotCarryIt`, `aKeywordMatchRanksBelowEveryTitleMatch`, and for a typed title `anExactTitleLeadsAnotherCommandsAlias` and `aWholeOneWordTitleLeads`). - **KBD-07 · MUST.** The palette and every picker (a card that lists choices to filter and pick one from: [QOPEN-01](https://pauta-project.dev/6.0.0/templates/quick-open/#qopen-01)) are in-scene overlays in the window's root `StackPane`, never 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/OverlayHost.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/OverlayHost.java), the one host installed in the scene's root `StackPane`, which shows the palette ([`ui/CommandPalette.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CommandPalette.java)), the picker ([`ui/QuickOpen.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/QuickOpen.java)) and the picker's relatives ([QOPEN-12](https://pauta-project.dev/6.0.0/templates/quick-open/#qopen-12)). ### Keymaps - **KBD-09 · MUST.** Except in a terminal app, Emacs and CUA keymaps ship as JSON resources, `emacs.json` and `cua.json`, CUA with a `cua.mac.json` variant where Cmd replaces Ctrl. A terminal's keys belong to the program it runs (`C-a`, `M-x` reach the shell), so a terminal app ships one keymap of its own instead, `keymap.json` and `keymap.mac.json`, binding its commands to chords programs don't use. Neither file binds a plain `Ctrl` or `Alt` (`Option` on macOS) with a letter: off macOS that leaves `Ctrl+Shift+T`, not `Ctrl+T`, and on macOS `Cmd+T`, since no program in the terminal receives `Cmd`. - *Why:* an Emacs keymap in a terminal would take the shell's own keys away from it: `Ctrl+W` deletes a word, `Ctrl+C` interrupts, `Alt+F` and `Alt+B` move by word. The shell reads the same keys on macOS, where `Option` with a letter also types a character. - *Check (code):* `emacs.json`, `cua.json` and `cua.mac.json` are in the app's resources. In a terminal app, `keymap.json` and `keymap.mac.json` are there instead, and no default binding in either file is `Ctrl` alone or `Alt` alone with a letter. Read each chord as the OS reads it: a modifier that stands for the OS's own shortcut key (JavaFX's `Shortcut`, as Termina writes it) is `Ctrl` in `keymap.json` and `Cmd` in `keymap.mac.json`. - *Reference:* Editora [`src/main/resources/com/editora/keymaps/`](https://github.com/adriandeleon/Editora/tree/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps); Termina's [`keymaps/`](https://github.com/adriandeleon/Termina/tree/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/resources/com/termina/keymaps), whose [`KeymapTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/ui/KeymapTest.java) (`offMacOsAnApplicationChordNeverTakesPlainCtrlAndALetter`) holds the `Ctrl` half off macOS; no test holds the `Alt` half or reads `keymap.mac.json`, where every chord carries `Cmd` today. - **KBD-10 · SHOULD.** Except in a terminal app ([KBD-09](https://pauta-project.dev/6.0.0/keyboard/#kbd-09)), an app also ships IntelliJ, VS Code and Sublime keymaps as JSON resources beside its Emacs and CUA keymaps: `intellij.json`, `vscode.json` and `sublime.json`, each with its `.mac.json` variant. - *Check (code):* `intellij`, `vscode` and `sublime` `.json` and `.mac.json` files are in the resources. An app that ships a terminal's keymap, `keymap.json` and `keymap.mac.json` with no `emacs.json` and no `cua.json` ([KBD-09](https://pauta-project.dev/6.0.0/keyboard/#kbd-09)), needs none of them. - *Command:* `[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; has() { find src/main/resources -name "$1" | grep -q .; }; if has keymap.json && has keymap.mac.json && ! has emacs.json && ! has cua.json; then exit 0; fi; ! for k in intellij vscode sublime; do for f in "$k.json" "$k.mac.json"; do has "$f" || echo "missing $f"; done; done | grep .` - *Reference:* Editora [`src/main/resources/com/editora/keymaps/`](https://github.com/adriandeleon/Editora/tree/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps). Termina ships the terminal's two files only ([`keymaps/`](https://github.com/adriandeleon/Termina/tree/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/resources/com/termina/keymaps)). The app template and Mirada ship Emacs and CUA and none of these three yet; Torrenta, Modula and nux ship no keymap file. - **KBD-21 · MUST.** A keymap's `.mac.json` variant binds the same commands as the keymap it varies. A chord may differ, to put `Cmd` where the other has `Ctrl`, to follow the macOS keymap of the editor it copies, or where macOS keeps the chord for itself (`Cmd+Space`, `Cmd+Tab`). See [Same on every OS](https://pauta-project.dev/6.0.0/same-on-every-os/). - *Why:* a command with no chord on one OS is a command that user never finds from the keyboard. - *Check (code):* each keymap file and its `.mac.json` variant bind the same set of command ids: no command is bound in one and missing from the other. An app that ships no keymap files has no pair to compare and fails with [KBD-09](https://pauta-project.dev/6.0.0/keyboard/#kbd-09). A test that loads both and compares the commands they bind is the surest evidence. - *Reference:* Editora [`KeymapsTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/command/KeymapsTest.java) (`guiKeymapsBindSameCommandSetOnBothPlatforms`), Termina's [`KeymapTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/ui/KeymapTest.java) (`bothPlatformsBindTheSameCommands`) and the app template's [`KeybindingsTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/command/KeybindingsTest.java) (`cuaHasAMacVariantWhereCmdReplacesCtrl`). Mirada's [`cua.json`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/resources/com/mirada/keymaps/cua.json) and [`cua.mac.json`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/resources/com/mirada/keymaps/cua.mac.json) bind the same commands, with no test that compares the two. - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsKeymapsPage.java); conflicts from [`KeybindingEdits.conflicts`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/command/KeybindingEdits.java), and the defaults a chord would take from [`EditorSettingsCoordinator.takenDefaults`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/EditorSettingsCoordinator.java). - **KBD-13 · SHOULD.** No command's chord is written into translated text. Every other label that shows a chord (a hint, the palette, the status bar) shows the binding from the active keymap; tooltips are [TBAR-03](https://pauta-project.dev/6.0.0/toolbars-and-tooltips/#tbar-03) and menu rows [MENU-15](https://pauta-project.dev/6.0.0/menus/#menu-15). 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/command/KeyDispatcher.java)). ### Focus and accessibility - **KBD-15 · MUST.** Every interactive control is reachable with Tab and operable with Space or Enter. A control is the exception when the keyboard does what it does another way: the buttons of a toolbar stay out of the Tab order ([TBAR-02](https://pauta-project.dev/6.0.0/toolbars-and-tooltips/#tbar-02), which says what a toolbar is: a bar of labeled buttons is not one, and its buttons are held to this rule), and the find-bar and filter controls that [FIND-16](https://pauta-project.dev/6.0.0/templates/find-bar/#find-16) names may leave it. See [Accessibility](https://pauta-project.dev/6.0.0/accessibility/). - *Why:* a control that Tab can't reach is one a keyboard-only or screen-reader user can't use at all. - *Check (by hand):* first in the source, find every control the keyboard cannot focus: one the app takes out of the Tab order (`setFocusTraversable(false)` in the code, `-fx-focus-traversable: false` in a stylesheet), and a label or a pane that acts on a click. The keyboard does all that each one does another way: it is a button of a toolbar as [The toolbar](https://pauta-project.dev/6.0.0/toolbars-and-tooltips/#the-toolbar) defines one ([TBAR-02](https://pauta-project.dev/6.0.0/toolbars-and-tooltips/#tbar-02); a bar of labeled buttons, such as nux's, is not one), a find-bar or filter control that [FIND-16](https://pauta-project.dev/6.0.0/templates/find-bar/#find-16) lets leave the Tab order (one that fails FIND-16, such as an option's toggle that no command toggles, fails here too), a list whose text field moves its selection with the arrow keys, or a control whose every action, the rows of its right-click menu included, a registered command also runs. A control only the mouse can work fails the rule, and the source alone shows it. Then in the running app, Tab reaches every other control of each window and dialog, and Space or Enter works it. - *Reference:* the app template, where each control the keyboard cannot focus has its other way: the status bar's echo area, error count and update notice run commands (`view.messageLog`, `help.openNewRelease`: [`ui/StatusBar.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/StatusBar.java)), the Debug Log find bar's buttons are [FIND-16](https://pauta-project.dev/6.0.0/templates/find-bar/#find-16)'s ([`ui/DebugLogFindBar.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/DebugLogFindBar.java)), and the picker's list is moved from its field ([`ui/Picker.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Picker.java)). Editora doesn't hold the rule everywhere yet: the Clear button of its Message Log ([`ui/MessageLogPopup.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MessageLogPopup.java)) and the Previous Run and Save Output buttons of its build console ([`ui/BuildToolPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/BuildToolPanel.java)) are out of the Tab order with no command and no key behind them. Modula doesn't either: it takes every control of its window out of the Tab order ([`RadioPane.keepOutOfFocus`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/RadioPane.java)) and gives most of what they do a key or a palette row, but a preset's Rename and Remove are rows of its chip's right-click menu alone ([`ui/PresetBar.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/PresetBar.java)). Termina doesn't either: the regular-expression toggle of its find bar is out of the Tab order, and no command and no key toggles it ([`ui/SearchBar.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/SearchBar.java); [FIND-16](https://pauta-project.dev/6.0.0/templates/find-bar/#find-16) fails for it too). - **KBD-16 · MUST.** Every button, toggle, menu button, link, combo box, check box, radio button and text field shows the focus ring when the keyboard focuses it. The ring is one layer of `:focus-visible` rules in the app stylesheet, after every rule that sets a border or background on the same controls, since rules of equal specificity are decided by order. Its color and contrast are [ICON-12](https://pauta-project.dev/6.0.0/icons-and-color/#icon-12). - *Why:* a keyboard user who can't see where focus is can't use the window; the ring's color is a MUST, and so is drawing it. - *Check (code):* the app stylesheet holds the ring as one block of `:focus-visible` rules that covers each of these kinds of control the app uses (buttons, toggles, menu buttons, links, combo boxes, check boxes, radio buttons, text fields), and no rule after the block, of the same or higher specificity, sets again what the block sets on those controls (the border; on a text field, the background insets). A test that tabs to each control family and asserts the ring is the surest evidence. - *Reference:* Editora [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css) (*Keyboard focus*, one layer for every control), held by [`FocusRingFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/FocusRingFxTest.java), which tabs to each control family. Termina's [`app.css`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/resources/com/termina/styles/app.css) and Mirada's [`mirada.css`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/resources/com/mirada/styles/mirada.css) end with a layer of the same kind; neither app has a test that tabs to a control. - **KBD-22 · SHOULD.** The focus ring is 2 px wide at the default zoom and sits just outside the control with a 1 px gap: a border with negative insets, which adds nothing to the control's own, so focusing a control never moves the layout. Two kinds of control draw it inside instead, at the same 2 px and still without moving anything: a text field, whose own focus border is widened, and a control flush with the window's edge, where a ring outside would be cut off. - *Why:* a ring drawn on the control's own border is lost on a flat or filled button, and one that takes room makes the row jump as Tab moves along it. A text field already draws an accent border on focus, so a second ring around it would be one too many. - *Check (code):* in the `:focus-visible` rules of [KBD-16](https://pauta-project.dev/6.0.0/keyboard/#kbd-16), the one for the controls that take the outside ring (buttons, toggles, menu buttons, links, combo boxes, the boxes of check boxes and radio buttons, as many of them as the app has) sets `-fx-border-width: 2` and `-fx-border-insets: -3`; the one for text fields widens the field's focus border to 2 px instead (`-fx-background-insets: 0, 2px`); and a rule that draws the ring inside a control at the window's edge keeps the 2 px width and takes the room back out of the control's padding. - *Reference:* Editora [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css) (*Keyboard focus*), Termina's [`app.css`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/resources/com/termina/styles/app.css) and Mirada's [`mirada.css`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/resources/com/mirada/styles/mirada.css): the same outside ring, and the same text-field rule (Mirada's covers text areas too). Editora alone has the second exception: `.tool-stripe-button:focus-visible` draws the ring at `-fx-border-insets: 1` and gives 3 px of padding back, since the stripes sit against the window's edge. The app template's [`app.css`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/resources/com/example/app/styles/app.css) sets the ring's color only, so the ring is the theme's own 1 px border. - **KBD-18 · SHOULD.** A row that turns a setting on or off (in Settings, a panel or a dialog) uses a switch the keyboard operates: it takes focus, Space toggles it, and its accessible role is `TOGGLE_BUTTON`. - *Why:* a bare AtlantaFX `ToggleSwitch` is mouse-only. - *Check (code):* every row that turns a setting on or off uses a switch that takes focus, toggles on Space and sets `AccessibleRole.TOGGLE_BUTTON` (Editora has one class for it, `SettingSwitch`); a row that uses AtlantaFX's `ToggleSwitch` as it comes fails. - *Reference:* Editora [`ui/SettingSwitch.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingSwitch.java). ## Accessibility (ACC) https://pauta-project.dev/6.0.0/accessibility/: What a screen reader, a keyboard-only user and a user who turns motion off need from every app, and where each is a rule. ### Rules - **ACC-01 · MUST.** Every control a person can reach with Tab or the mouse has an accessible name: its own text, a `Label` whose `labelFor` is the control, or `setAccessibleText`. A row drawn from a graphic (a `CustomMenuItem`, a list cell that lays out its own nodes) carries its text too. A test holds it. - *Why:* a screen reader announces an unnamed control as "button", or says nothing. - *Check (test):* an FX test opens each window and dialog and fails on a control (a button, a toggle, a field, a combo box or any other `Control` a person can focus or click, in the Tab order or out of it) that has no text, no accessible text and no label pointing at it, and on a list cell or menu row that reads as nothing. JavaFX names a `CustomMenuItem` row from its content's accessible text, and a cell from its text or its graphic's, so a row that lays out its own nodes sets `setAccessibleText` on them. - *Reference:* Editora names its controls area by area ([`NamedControlsFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/NamedControlsFxTest.java)), and sets each row's text on the macOS system menu bar. Its in-window command rows, each a `CustomMenuItem` that draws an icon, a title and a chord ([`ui/MainMenuBar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainMenuBar.java)), carry no text and no accessible text yet; its submenus keep their own. No app has the test that sweeps every window for every control yet. Termina's [`IconOnlyButtonsFxTest.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/ui/IconOnlyButtonsFxTest.java) comes nearest: it opens the main window, the menus, Settings and About and fails an icon-only button with no name, and no other kind of control. Torrenta's one call to `setAccessibleText` is in a helper ([`ui/Icons.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/Icons.java), `name`) that names every button of its main toolbar and the Search view's Clear button, and no other control; Modula never calls it. - **ACC-02 · SHOULD.** A control the app builds from panes or draws itself says what it is and does what its role offers: `setAccessibleRole` with the role it acts as (`BUTTON`, `TOGGLE_BUTTON`, `LIST_VIEW`, `TREE_ITEM`), its state answered from `queryAccessibleAttribute` (selected, expanded, checked), `notifyAccessibleAttributeChanged` when the state changes, and the role's actions (`FIRE`, `EXPAND`, `COLLAPSE`) handled in `executeAccessibleAction`. - *Why:* without a role, a screen reader can't tell a status-bar segment that opens a picker from a label; and it presses a control through its action, not a mouse click, so a `BUTTON` that ignores `FIRE` can be found but not used. - *Check (code):* every `Pane`, `Region`, `Label` or `Canvas` that handles a click or a key sets an accessible role and overrides `executeAccessibleAction` for that role's actions. - *Reference:* Editora [`ui/SettingSwitch.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingSwitch.java) (the `TOGGLE_BUTTON` role; it handles `FIRE` only) and [`ui/MapAccessibleRows.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MapAccessibleRows.java) (`FIRE`, `EXPAND` and `COLLAPSE` on each row). Its status-bar segments ([`ui/StatusBar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/StatusBar.java)) take the `BUTTON` role but don't handle `FIRE` yet. - **ACC-03 · SHOULD.** An app that paints content on a `Canvas` (a map, a strip of images, a terminal grid) gives it to the screen reader: an accessible text that sums it up and, where a person moves through items in it, one accessible node for each item on screen. - *Check (code):* the canvas, or the node that stands for it, sets an accessible text, and where a person moves through items it exposes a node with a role and a name for each item on screen. A test that reads the accessible text, or the roles and names of those nodes, is the surest evidence. - *Reference:* Editora [`ui/MapAccessibleRows.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MapAccessibleRows.java) (the Project Map's rows on screen, as `TREE_ITEM` nodes under a `TREE_VIEW`), read by [`MapAccessibleRowsFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/MapAccessibleRowsFxTest.java). - **ACC-04 · SHOULD.** Motion follows the OS: while `Platform.getPreferences().isReducedMotion()` is true, an animation jumps to its end, and a change to the setting applies at once. - *Why:* sliding and fading can make a person dizzy or sick, and they turned motion off in the OS for that reason. - *Check (code):* every `Transition`, `Timeline` or `AnimationTimer` that moves, fades or flashes part of the UI starts through one helper that reads `reducedMotionProperty()`. - *Reference:* no app yet. Mirada fades its on-screen controls in and out ([`ui/OnScreenControls.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/OnScreenControls.java), a `FadeTransition`), and Editora's Project Map flashes a revealed row for 900 ms ([`ui/MapSurface.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MapSurface.java), an `AnimationTimer`); neither reads a motion setting. - **ACC-05 · SHOULD.** Color is never the only signal: a state shown in color (an error, a changed line, a status) also shows a word, a glyph or a shape. - *Why:* about one man in twelve can't tell red from green. - *Check (by hand):* look at a grayscale screenshot of each window and find every state still told apart. - *Reference:* Editora's echo area colors an error and also says what failed ([`ui/StatusBar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/StatusBar.java); [WIN-01](https://pauta-project.dev/6.0.0/window-shell/#win-01)). - **ACC-06 · SHOULD.** In an app whose window has more than one region (the content and at least one panel beside it), a command moves focus to the next region, another moves it to the previous one, and every keymap binds both. - *Why:* Tab walks through every control inside a region; with several panels open, a keyboard user needs a way to jump between them. - *Check (code):* the two commands are registered and bound in each bundled keymap. - *Reference:* Editora's `window.other` ("Cycle focus between the editor and tool windows", [`ui/WindowCommandRegistrar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowCommandRegistrar.java)), one command that cycles, bound only in the Emacs keymap (`C-x o`, [`keymaps/emacs.json`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps/emacs.json)). `F6`, the Windows convention, is taken in every other Editora keymap: CUA and VS Code bind it to `debug.pause`, IntelliJ to `lsp.move` and Sublime to `view.toggleSpellCheck`. - **ACC-07 · SHOULD.** Before a release, a person makes a pass with the screen reader on Windows and on macOS: with Narrator and with VoiceOver, open the Command Palette, run a command, and move through Settings, hearing each control's name and role. It is a step of its own in `docs/release.md` ([REPO-07](https://pauta-project.dev/6.0.0/repository/#repo-07)): the smoke test of [REL-29](https://pauta-project.dev/6.0.0/release/#rel-29) is a CI step, with nobody there to listen. - *Check (by hand):* `docs/release.md` has the step, naming Narrator and VoiceOver, and someone made the pass for this release. The file settles the first half: with no such step the rule is unmet, whoever listened. The pass itself is a person's to record, as a `checked` entry that carries the app's `version` ([PAUTA-18](https://pauta-project.dev/6.0.0/conformance/#pauta-18)). - *Reference:* no app yet. No app's `docs/release.md` names either screen reader, and Modula and nux have no `docs/release.md`. - **ACC-08 · SHOULD.** In an overlay list that keeps focus in its text field (the Command Palette, a picker: [QOPEN-01](https://pauta-project.dev/6.0.0/templates/quick-open/#qopen-01)), the row the arrow keys select is announced, with its state: the list tells the screen reader its focused item moved (`notifyAccessibleAttributeChanged(FOCUS_ITEM)`), and a row that can't run says so in its accessible text. - *Why:* the arrows move the highlight, not the focus, so a screen reader stays on the text field and reads nothing as the user moves through the list. - *Check (code):* the code that moves the selection calls `notifyAccessibleAttributeChanged(AccessibleAttribute.FOCUS_ITEM)` on the list, the list answers `FOCUS_ITEM` with the selected row, and a row that can't run says so in its accessible text. - *Reference:* no app yet. Editora's palette rows are graphics with no text ([`ui/CommandPalette.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CommandPalette.java)). - **ACC-09 · SHOULD.** In Windows' high-contrast mode the app switches to a high-contrast theme, and back when the mode ends: it follows `Platform.getPreferences()`'s `Windows.SPI.HighContrast`. - *Why:* JavaFX applies its own high-contrast stylesheet only over its built-in Modena theme, which AtlantaFX replaces, so without this the app ignores a setting the person turned on to read the screen at all. - *Check (code):* a listener on the preference switches the theme, and the theme list has a high-contrast theme. - *Reference:* no app yet. ## Window shell (WIN) https://pauta-project.dev/6.0.0/window-shell/: Status bar, themes, title bar, dialogs, Welcome, About, window state, zoom and quit. - **WIN-01 · MUST.** The main window has a status bar, shown by default; the user may hide it. 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 ([DIAG-01](https://pauta-project.dev/6.0.0/diagnostics/#diag-01)). - *Check (code):* the main window builds a status bar that is visible unless the user hid it; 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/StatusBar.java) (`status-echo-error`, `status-echo-warn`; a click runs `view.messageLog`) and the [Message Log template](https://pauta-project.dev/6.0.0/templates/message-log/). Editora hides and shows the bar with `view.toggleStatusBar` and a setting, and Zen mode hides it ([`ui/Chrome.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Chrome.java), `statusBar`). Termina doesn't meet the rule yet: its status bar is a setting that starts off ([`config/Settings.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/config/Settings.java), `showStatusBar`). - **WIN-03 · MUST.** In an app with a menu bar, the menu bar sits in the title bar by default on Windows and Linux: JavaFX 27's `HeaderBar` with `StageStyle.EXTENDED` carries the menu, and a setting that starts on lets the user fall back to a decorated window. On macOS the menus are in the system menu bar (`useSystemMenuBar`), and the window is decorated, or extended with a header that holds no menus. - *Why:* the family looks the same on every OS only if every app starts with the same title bar; an app that ships it off looks like another family. - *Check (code):* on Windows and Linux the main stage is created `StageStyle.EXTENDED` with a `HeaderBar` that holds the menu bar, and the setting that falls back to a decorated window defaults to on (in the title bar); on macOS the menu bar sets `useSystemMenuBar`, and a header, where the window has one, holds no menus. - *Reference:* the app template ([`config/Settings.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/config/Settings.java), `titleBarMenus = true`, read by [`Chrome.usesHeaderBar`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Chrome.java)). Editora ([`ui/ExtendedWindow.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ExtendedWindow.java), [`ui/MainMenuBar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainMenuBar.java)), Torrenta and Termina have the setting but start it off. Mirada has no setting: its [`ui/TitleBar.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/TitleBar.java) is a `HeaderBar` on a `StageStyle.EXTENDED` stage wherever JavaFX supports one, on macOS too. Its header holds the file name and buttons, the main menu's among them, and no menu bar; on macOS [`ui/MacMenus.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/MacMenus.java) puts the menus in the system menu bar. Modula and nux have no menu bar. - **WIN-04 · SHOULD.** Native dialogs go through one helper that attaches the app stylesheet. The UI font reaches every scene, a dialog's included, by [ICON-01](https://pauta-project.dev/6.0.0/icons-and-color/#icon-01). - *Why:* a dialog is its own scene and does not inherit the window's stylesheet. - *Check (code):* every `Alert` and `Dialog` the app builds passes through the helper. - *Reference:* Editora [`ui/Dialogs.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Dialogs.java) ([`Dialogs.styled`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Dialogs.java)), which attaches `app.css` only. The UI font reaches an Editora dialog another way: [`App.installUiFont`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java) adds `ui-font.css` to every window's scene ([ICON-01](https://pauta-project.dev/6.0.0/icons-and-color/#icon-01)). - **WIN-11 · MUST.** A dialog's buttons are in the same order on every OS, with Cancel to the left of every action, as the [Confirm dialog](https://pauta-project.dev/6.0.0/templates/confirm-dialog/) draws them (Cancel, Save and Discard where there are three: [CONF-05](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-05)): the dialog's `ButtonBar` gets one fixed order, never JavaFX's default for the OS. See [Same on every OS](https://pauta-project.dev/6.0.0/same-on-every-os/). - *Why:* JavaFX orders a `ButtonBar` by the OS it runs on (`BUTTON_ORDER_WINDOWS`, `_MAC_OS`, `_LINUX`), so the same confirmation puts its action on the left on Windows and on the right on macOS and Linux. - *Check (code):* the dialog helper ([WIN-04](https://pauta-project.dev/6.0.0/window-shell/#win-04)), or each dialog, calls `setButtonOrder` on the dialog pane's `ButtonBar` with one order string, the same on every OS, in which `C` (`CANCEL_CLOSE`) comes before the letter of every action button the dialogs use (`O` for `OK_DONE`, `Y`, `N`, `A`, `U` for `OTHER`). `BUTTON_ORDER_WINDOWS` on every OS fails: it puts `Y`, `N` and `O` before `C`. - *Reference:* no app yet. Editora's Git confirmations give their buttons the `OK_DONE` and `CANCEL_CLOSE` roles and leave the order to JavaFX. - **WIN-08 · SHOULD.** The main window's size, position and maximized state are restored on the next launch, and in an app that opens documents or sessions, so are the items that were open. `--no-session` skipping the restore is [CLI-04](https://pauta-project.dev/6.0.0/command-line/#cli-04). - *Check (code):* closing the window saves its size, position and maximized flag, and the open items in an app that has them, and the next launch reads them back and applies them. A test that saves the state and reads it back is the surest evidence. - *Reference:* Editora [`config/WorkspaceState.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/WorkspaceState.java) (`windowX` … `windowMaximized`), [`ui/WindowSessionCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowSessionCoordinator.java), [`App.noSessionFlag`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java); tests [`AppArgsTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/AppArgsTest.java), [`NoSessionStartupFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/NoSessionStartupFxTest.java) and, for the window's geometry, [`WindowManagerLaunchFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/WindowManagerLaunchFxTest.java) (`aWindowComesBackAtTheSizeAndPlaceItsSessionRecorded`, `aWindowThatWasMaximizedComesBackMaximized`), which restore a window from a saved `workspace-state.json`. No Editora test saves the geometry and reads it back. - **WIN-09 · SHOULD.** In an app with content to zoom (text, an image, a terminal), it zooms from the keyboard (`Ctrl+=`, `Ctrl+-` and `Ctrl+0`, with `Cmd` on macOS; `=` is the key that carries `+`), kept across launches. The UI zoom is [WIN-12](https://pauta-project.dev/6.0.0/window-shell/#win-12). - *Check (code):* the content's zoom in, out and reset are commands bound in every keymap, and the zoom level is a saved setting. - *Reference:* Editora `view.textZoomIn`, `view.textZoomOut` and `view.textZoomReset`, kept in [`Settings.fontZoom`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/Settings.java) and bound to `C-=`, `C--` and `C-0` ([`keymaps/cua.json`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps/cua.json)); Termina's `zoomIn`, `zoomOut` and `actualSize`, on `Shortcut+Equals`, `Shortcut+Minus` and `Shortcut+0` ([`keymaps/keymap.json`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/resources/com/termina/keymaps/keymap.json)), kept in `font.zoom` ([`config/Settings.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/config/Settings.java)). - **WIN-12 · MUST.** The app has a UI zoom: one setting scales the whole chrome, the menus ([MENU-16](https://pauta-project.dev/6.0.0/menus/#menu-16)), toolbar, tabs and status bar included. It applies at once, is kept across launches, and three commands zoom it in, out and back to the default. In an app with content of its own to zoom (an editor's text, a terminal's grid, an image) `Ctrl+=`, `Ctrl+-` and `Ctrl+0` (`Cmd` on macOS) stay with the content zoom ([WIN-09](https://pauta-project.dev/6.0.0/window-shell/#win-09)) and this rule fixes no chord for the UI zoom's commands; in an app without, those chords are the UI zoom's. - *Why:* a person who needs larger text gets it everywhere, and the menus can only follow a zoom that exists. - *Check (code):* the chrome's font sizes come from one root size the setting changes, and its fixed sizes are multiplied by the zoom, not written as absolute pixels. A change to the setting restyles every open window with no restart, and the value is saved with the settings and read back at start-up. Three registered commands zoom it in, out and back to the default. The rule names no ids for them: they are the app's own. In an app with a content zoom they are three more commands, with ids that are not the content zoom's (Mirada's `view.zoomIn` and Termina's `zoomIn` zoom the content), and the keymaps bind `=`, `-` and `0` with `Ctrl` (`Cmd` on macOS) to the content zoom's commands; in an app without, to the UI zoom's. - *Reference:* no app yet. Editora, Termina and Mirada zoom their content only (`view.textZoomIn`, `zoomIn`, `view.zoomIn`), and Editora writes its menu font as absolute pixels ([`MainMenuBar.UI_FONT_SIZE`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainMenuBar.java), `.context-menu` in [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css)). Torrenta, Modula, nux and the app template have no zoom command. - **WIN-13 · MUST.** Every quit entry point an app has runs one quit method: the Quit row and the `app.quit` command ([WIN-14](https://pauta-project.dev/6.0.0/window-shell/#win-14) says which of them an app must have), and the system's own Quit, which on macOS is the application menu's and the Dock's. That method asks what the [Confirm dialog](https://pauta-project.dev/6.0.0/templates/confirm-dialog/) rules require ([CONF-01](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-01)), closes open dialogs and runs the save the app runs when its window closes, so quitting loses nothing a close would have kept; what an app keeps across launches is [WIN-08](https://pauta-project.dev/6.0.0/window-shell/#win-08). A tray's Quit is [TRAY-04](https://pauta-project.dev/6.0.0/tray-and-background/#tray-04). - *Why:* a second way out skips what the first one does: the question about unsaved work, the saved window, or, in a tray app, the quit itself. Quitting from inside a dialog's nested event loop has aborted the JVM. - *Check (code):* one quit method. The Quit row and the quit command run it, where the app has them (an app with neither fails [WIN-14](https://pauta-project.dev/6.0.0/window-shell/#win-14), not this rule), and on macOS the system's Quit reaches it. JavaFX turns the application menu's and the Dock's Quit into a close request on every window (`GlassStage.requestClosingAllWindows`) unless the app catches Glass's quit action (`handleQuitAction`), so the quit handler calls the quit method, or, in an app with one main window, that window's close request does. In an app with one main window and no quit command, what the close request runs is the quit method, and it is judged as one; an app with several main windows whose close requests each ask for themselves has no quit method. The method itself asks before it discards anything [CONF-01](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-01) covers (unsaved work; an app with nothing to lose asks nothing), closes its open dialogs before it exits, and runs the same save a close of the window runs (the window state of [WIN-08](https://pauta-project.dev/6.0.0/window-shell/#win-08), in an app that keeps it). - *Reference:* the app template's [`MainWindow.quit`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/MainWindow.java): the `app.quit` command, which File → Quit runs, and the window's close request both call it, so macOS's Quit reaches it as a close request; it hides the other windows and dialogs, saves the window state and waits for the last settings write before it exits, and has nothing unsaved to ask about. That wait is the last save [PERF-01](https://pauta-project.dev/6.0.0/performance/#perf-01) allows as the app quits; the template makes it on a background thread all the same. Editora's File → Quit and `app.quit` run [`MainController.onQuit`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java), which asks about the quit once and then about each window's unsaved files; macOS's Quit doesn't reach it yet: [`MacOpenFiles`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/MacOpenFiles.java) wraps Glass's handler and passes `handleQuitAction` on to JavaFX's own, so each window gets a close request and asks for itself. Torrenta ([`MainWindow.quit`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java)), Modula ([`ModulaApp.quit`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ModulaApp.java)) and nux (`Platform.exit`, from `app.quit` and from the tray, in [`App`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java)) don't catch macOS's Quit either. Termina and Mirada have no quit command ([WIN-14](https://pauta-project.dev/6.0.0/window-shell/#win-14)). Mirada has one main window, and what its close request runs is its quit method: it asks about an unsaved edit, closes its tool windows and saves the window's place ([`ui/ViewerWindow.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/ViewerWindow.java), `mayClose`, `release`, `rememberPlace`), and macOS's Quit arrives there as a close request. Termina doesn't meet the rule yet: it has several windows and no quit method, so macOS's Quit arrives at each window as a close request and each asks for itself ([`TerminalWindow.close`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java)). - **WIN-14 · MUST.** Every app has a Quit, on every OS: the `app.quit` command, in the Command Palette, and, where the app has a File menu or a main menu, a Quit row in that menu that runs the command. A main menu is a menu button in the window that holds the app's commands as a menu bar would (Mirada's ☰, which it shows on every OS). A menu button that lists one kind of thing is not a main menu (nux's Profiles and Commands), and neither is a right-click menu (the only menu Modula has): an app with no File menu and no main menu meets the rule with the command alone. What Quit does is [WIN-13](https://pauta-project.dev/6.0.0/window-shell/#win-13). Closing the last window may end the app as well, but it is never the only way out. - *Why:* someone who quits one app of the family from the palette or the File menu looks for the same in the next. An app that ends only with its last window has no answer once it has a tray or a second window. - *Check (code):* `app.quit` is registered and the palette lists it. Where the app builds a File menu, a row of it runs `app.quit`; where it has no menu bar and a main menu instead, a row of that menu does. An app with neither menu passes on the command. - *Reference:* the app template's [`Commands.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Commands.java) (`app.quit`) and [`AppMenus.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/AppMenus.java) (Quit, the File menu's last row); Editora's `app.quit`, the last row of its File menu ([`ui/MenuBarModel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarModel.java)). Torrenta's File menu ends with Quit, and it registers the command as `quit`. Termina and Mirada have no Quit. Termina's File menu has Close Window and ends with Settings, Sync Now and Configure Profiles ([`ui/MenuBarModel.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/MenuBarModel.java)); Mirada's ☰ menu, on every OS ([`ui/TitleBar.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/TitleBar.java)), and, on macOS, its File menu ([`ui/MacMenus.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/MacMenus.java)) end with Close (`window.close`). nux has neither menu and meets the rule with `app.quit` ([`App`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java)). Modula has neither menu and no quit command: it quits from its tray and its window's close button ([`ModulaApp.quit`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ModulaApp.java)). - **WIN-15 · SHOULD.** On macOS, Settings is in the application menu, the one macOS names after the app, and runs the same command as the Settings row on Windows and Linux. Its row shows the chord the active keymap binds to that command (`Cmd+,` in the CUA keymap: [SET-01](https://pauta-project.dev/6.0.0/settings/#set-01)), appended to the title as [MENU-02](https://pauta-project.dev/6.0.0/menus/#menu-02) has the system menu bar's rows show theirs, and the item is given no key equivalent of its own. About, in the same menu, is [ABOUT-01](https://pauta-project.dev/6.0.0/templates/about/#about-01), and the Quit JavaFX puts there is [WIN-13](https://pauta-project.dev/6.0.0/window-shell/#win-13). - *Why:* it is where every Mac app has Settings, one of the places [the OS's way wins](https://pauta-project.dev/6.0.0/same-on-every-os/#where-the-oss-way-wins). A key equivalent set on the item is an accelerator under another name: macOS runs the item before the app's key dispatcher sees the key, and the menu goes on showing `⌘,` in a keymap that binds another chord, or none. - *Check (code):* on macOS the app inserts a Settings item into the application menu that runs the settings command. The item's title carries the chord the active keymap binds to that command and is written again when the keymap changes; the item is created without a key equivalent. - *Reference:* Mirada [`MacAppMenu.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/os/MacAppMenu.java) adds the item, and it runs `app.settings`. It doesn't show the keymap's chord yet: it creates the item with the native key equivalent `Cmd+,` (`createMenuItem(…, ',', COMMAND)`), which stays whatever the keymap binds, and Mirada's Emacs keymap binds `C-,` ([`keymaps/emacs.json`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/resources/com/mirada/keymaps/emacs.json)). Termina's [`MacAppMenu.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/MacAppMenu.java) adds About only. Editora, the app template, Torrenta, Modula and nux add nothing to that menu. - **WIN-10 · MAY.** The window has modes that change how much chrome it shows: Zen shows none, Expert keeps only the menu bar and the status bar, and Simple shows fewer menus, for new users. - *Check (code):* each mode is a command, and one truth table decides which chrome each mode shows. - *Reference:* Editora [`ui/WindowChromeCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowChromeCoordinator.java) (`toggleZen`, `toggleExpert`, `applySimpleMode`) over the truth table in [`ui/Chrome.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Chrome.java), where Expert hides the toolbar, the tabs, the breadcrumb and the tool stripes. ## Icons and color (ICON) https://pauta-project.dev/6.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):* every window's scene gets the font sheet (Editora's `ui-font.css`): a listener on `Window.getWindows()` adds it to each window's scene, and to a new scene when the window's scene changes, or every window and dialog the app builds adds it itself, none left out. A popup or a tooltip needs no call of its own: when JavaFX shows one, it gives it the scene stylesheets of the window it is shown from (`PopupWindow.applyStylesheetFromOwner`). No `.root` rule in the app stylesheet (Editora's `app.css`) sets `-fx-font-family`. - *Reference:* Editora [`App.installUiFont`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java), a listener on `Window.getWindows()`, and [`styles/ui-font.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/ui-font.css); the app template's [`ui/Themes.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Themes.java) (`installUiFont`, `hookUiFont`) and Mirada's [`ui/Fonts.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Fonts.java) (`installSheet`) do the same. Termina and Torrenta carry the same sheet with no listener: each window and dialog adds it by calling `Fonts.installUiFont`, about forty times in Torrenta. Termina doesn't meet the rule yet: its helper is called for seven windows and [`ui/Confirm.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/Confirm.java) adds the sheet to its questions, but four dialogs get none: the two alerts and the rename-tab `TextInputDialog` built in [`ui/TerminalWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java), and the `TextInputDialog` in [`ui/SettingsWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/SettingsWindow.java). Modula doesn't yet: the `.root` rule of its [`modula.css`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/resources/com/modula/modula.css) sets IBM Plex Mono for the whole window. - **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/`](https://github.com/adriandeleon/Editora/tree/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/fonts/inter), [`ui/Fonts.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Fonts.java) (`loadForFirstPaint`, called from [`App`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java)). Termina and Torrenta bundle the same four faces. Modula doesn't yet: its [`fonts/`](https://github.com/adriandeleon/Modula/tree/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/resources/com/modula/fonts) holds IBM Plex Mono only. ### 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/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:* Termina [`styles/`](https://github.com/adriandeleon/Termina/tree/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/resources/com/termina/styles) and the app template's [`styles/`](https://github.com/adriandeleon/adl-desktop-app-template/tree/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/resources/com/example/app/styles), whose two files match Editora's. Torrenta's `editora-dark.css` matches too; its [`editora-light.css`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/resources/com/torrenta/styles/editora-light.css) still has the earlier `-color-accent-fg`, `-color-warning-fg` and `-color-success-fg`, which Editora has since darkened. - **ICON-06 · SHOULD.** Brace, the palette's periwinkle for the keyboard (chord chips, the menus' chord column), is one token on `.root` (Editora's `-state-key`): 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 (code):* the token is a `ladder()` of `-color-bg-default`, and the color it resolves to on each bundled theme's default and subtle grounds is 4.5:1 or more against that ground. A contrast test that resolves the ladder against every bundled theme's grounds is the surest evidence. - *Reference:* Editora [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css) (`.root`), [`StyleContrastTest.theKeyboardPeriwinkleReadsOnEveryBundledAppTheme`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/StyleContrastTest.java). ### State colors - **ICON-07 · MUST.** Each state color is named once, as a token on `.root` (Editora's `-state-*`) that chains to one of the theme's roles (or a `ladder()` of its ground), and component rules use the token. - *Check (code):* each state color has one token (Editora's `-state-*`), declared once, in a `.root` block of the app stylesheet, as a `-color-*` role or a `ladder()` of the ground. A component rule that colors one of those states uses the token: none names the role behind it (`-color-danger-fg` for an error) or writes the ladder out again. - *Reference:* the app template's [`styles/app.css`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/resources/com/example/app/styles/app.css) (`.root`), held by [`StyleContrastTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/ui/StyleContrastTest.java) (`theStateTokensAreDeclaredOnceAtTheTopAndChainToARole`, and `severityColorsComeFromTheStateTokens`, which fails a component rule that names a danger, warning or success role). Termina meets it too: its [`styles/app.css`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/resources/com/termina/styles/app.css) declares `-state-red`, `-state-amber` and `-state-green` on `.root`, and no component rule of its stylesheets names the role behind one. The other five apps don't yet. Editora's [`styles/app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css) declares its tokens the same way (`.root`), but Editora doesn't hold the last clause: 78 declarations in that file's component rules name `-color-danger-fg`, `-color-warning-fg` or `-color-success-fg` directly, errors among them (`.crontab-error`, `.md-math-error`). Torrenta's tokens are on `.root` too (`-torrenta-*`), and two of its component rules write out the ladder of `-torrenta-up` again ([`styles/app.css`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/resources/com/torrenta/styles/app.css), `.speed-graph-up`, `.speed-graph-legend-up`). Torrenta doesn't hold the last clause either: 24 declarations in that file's component rules and five in `add-dialog.css` name `-color-danger-fg`, `-color-warning-fg` or `-color-success-fg` directly (`.port-dot.port-down`, `.add-fetch-failed`), not the `-torrenta-error`, `-torrenta-stall` and `-torrenta-done` tokens that chain to them. Mirada and nux have no token for a state (Mirada's one `-state-*` token is `-state-key`, the keyboard's): Mirada's [`styles/mirada.css`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/resources/com/mirada/styles/mirada.css) redefines the roles themselves on `.root`, as ladders, and four of its component rules name `-color-danger-fg` or `-color-warning-fg` (`.status-echo-error`, `.status-echo-warn` and the Message Log's two); nux's [`nux.css`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/resources/com/nux/nux.css) has no `.root` block, and three of its rules name `-color-warning-fg` or `-color-danger-fg` (`.on-battery-note`, `.settings-problem`, `.detail-warn`). Modula's [`modula.css`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/resources/com/modula/modula.css) has tokens its rules use (`-lock`, `-fault`), set as fixed hexes on `.root` and again on `.root.daylight`, chained to no role. - **ICON-08 · MUST.** App stylesheets take their colors from AtlantaFX `-color-*` tokens, or from tokens the app builds on them; no component rule carries a fixed color, whatever its spelling: a hex, an `rgb()`, `rgba()` or `hsb()` value, or a named color such as `white`. A fixed color may stand only in a token's definition, on `.root` or in a scoped block that sets `-color-*` tokens, and only where the theme has no role to build on: a scrim's or a shadow's color, a color drawn over an image or a canvas and not on the theme's ground, or a color inside a `ladder()` of the ground ([ICON-13](https://pauta-project.dev/6.0.0/icons-and-color/#icon-13)). The ground, ink or accent of the app's own windows given there as a fixed color, in place of the theme's role, fails this rule; a state color given so is [ICON-07](https://pauta-project.dev/6.0.0/icons-and-color/#icon-07)'s failure and is not counted here again. `transparent` is not a color. - *Why:* a fixed color suits one theme; the roles track every theme for free. - *Check (code):* every color in a component rule of the app's stylesheets is an AtlantaFX `-color-*` role or a token, and a fixed color stands only where a token is defined, in a `.root` block or in a scoped block that sets `-color-*` tokens: as the plain value of a token for a scrim, a shadow or what is drawn over an image or a canvas (an `rgba()` of black, say), or inside a `ladder()` of the ground. A token for the ground, ink or accent of the app's own windows whose value is a fixed color and no role fails; a state color's token with no role behind it is [ICON-07](https://pauta-project.dev/6.0.0/icons-and-color/#icon-07)'s to judge, not this rule's. A fixed color is a hex (`grep -nE '#[0-9a-fA-F]{3,8}\b'` over those stylesheets lists them), an `rgb()`, `rgba()`, `hsb()` or `hsba()` value, or a named color such as `white`; `transparent` is not one. No component rule holds one, whichever property it sets (a `-fx-*-color`, a `-fx-fill`, an effect's color), inside a `ladder()` or not. A test that fails a fixed color outside the token block is the surest evidence. - *Reference:* Termina's [`AppCssColorsTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/ui/AppCssColorsTest.java) (`componentRulesUseTokensNotLiteralColours`) and Mirada's [`StyleContrastTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/ui/StyleContrastTest.java) (`noRuleAfterTheTokenBlockHoldsAFixedColour`) fail a fixed color outside the `.root` block: a hex, an `rgb()` or an `hsb()` value, a shadow's color included, and in Mirada's a named color too. Both apps keep the scrim behind an overlay and their shadows' colors as tokens on `.root`. Editora's [`StyleContrastTest.severityAndDebugColoursComeFromTheStateTokens`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/StyleContrastTest.java) holds six selectors it names, and 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css) still carry fixed hexes, other rules an `rgba()` (the scrim of `.overlay-backdrop`, the diff and merge tints and shadows among them), and `.breakpoint-condition-mark` a fixed `white`. Torrenta doesn't either: `.speed-graph-up` and `.speed-graph-legend-up` in its [`styles/app.css`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/resources/com/torrenta/styles/app.css) hold a ladder of two hexes, and `.palette-backdrop` and two shadows an `rgba()`. Modula, nux and the app template write the palette's scrim as an `rgba()` background in a component rule, and a shadow's color the same way (`.palette-backdrop` and `.palette-card` in [`modula.css`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/resources/com/modula/modula.css) and [`nux.css`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/resources/com/nux/nux.css), `.overlay-backdrop` and `.command-palette` in the template's [`styles/app.css`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/resources/com/example/app/styles/app.css)), so none of the three meets the rule yet; nux also sets `-fx-text-fill: white` on `.status-pill` and `.update-badge`. - **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, Editora Light and Editora Dark: a line of UI text is `-color-fg-default` and secondary text `-color-fg-muted`. `-color-fg-subtle` (2.7:1 to 3.9:1, under 3:1 on Editora Light's subtle and inset grounds) is for disabled or decorative text only. An app whose default light and dark themes are another pair is held to the same on that pair. A test holds it. - *Check (test):* a contrast test computes muted ink on the default, subtle and overlay grounds of both flagship themes (Editora Light and Editora Dark), or of the app's own default light and dark themes where it ships another pair, and finds 4.5:1 or more; and it walks every rule of the app's stylesheets: it fails a rule that sets a text fill (`-fx-text-fill`, or `-fx-fill` on text) to `-color-fg-subtle` unless its selector is on a list the test names, of disabled and decorative selectors only. A test that checks a list of readable selectors instead passes every selector it doesn't name. - *Reference:* no app's test walks every rule yet. Editora's [`StyleContrastTest.textThatMustBeReadUsesTheMutedRoleNotSubtle`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/StyleContrastTest.java) computes the ratios and checks six selectors it names (the palette's and the switcher's hints, an unbound shortcut, the line numbers of the notes and structure trees, the blame date), so it passes while `.encryption-locked-hint` and `.pom-version-unknown` in [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css) set text a person reads in `-color-fg-subtle`. The app template's test of the same name ([`StyleContrastTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/ui/StyleContrastTest.java)) checks fifteen named selectors the same way. Mirada's [`StyleContrastTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/ui/StyleContrastTest.java) has no test for this rule, and Termina, Torrenta, Modula and nux have no contrast test of their stylesheets. - **ICON-10 · MUST.** Text in a role's tint (the theme's `-color--fg`, for the accent, success, warning and danger roles) reaches 4.5:1 on that role's subtle fill (`-color--subtle`) and on the default and subtle grounds (`-color-bg-default`, `-color-bg-subtle`), in both flagship themes, Editora Light and Editora Dark, or, in an app whose default light and dark themes are another pair, in that pair. A test holds it. - *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 (Editora Light and Editora Dark), or in the app's own default light and dark themes where it ships another pair, and finds 4.5:1 or more. - *Reference:* Editora [`StyleContrastTest.lightTintedTextReachesAaOnItsOwnGroundAndOnTheSubtleSurface`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/StyleContrastTest.java), `darkTintedTextStaysAa`. Mirada's [`StyleContrastTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/ui/StyleContrastTest.java) (`tintedTextReachesAaOnItsOwnFillAndOnBothGrounds`) holds it on Cupertino Light and Cupertino Dark, the pair it ships. - **ICON-11 · MUST.** Ink on an emphasis fill is `-color-fg-emphasis`, never a fixed white: the token is white in the light themes and a dark ink in the dark ones, 4.5:1 or more on the emphasis fill of the accent, success, warning and danger roles in the two themes [ICON-09](https://pauta-project.dev/6.0.0/icons-and-color/#icon-09) names. A test holds it. - *Why:* white on the dark accent is 1.68:1. - *Check (test):* a contrast test computes `-color-fg-emphasis` on the `-emphasis` fill of the accent, success, warning and danger roles, in both flagship themes (Editora Light and Editora Dark) or in the app's own default light and dark themes where it ships another pair, and finds 4.5:1 or more; and the rules that paint on an emphasis fill use it. - *Reference:* Editora [`StyleContrastTest.inkOnAnEmphasisFillIsTheThemesOnEmphasisColour`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/StyleContrastTest.java), and Mirada's test of the same name ([`StyleContrastTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/ui/StyleContrastTest.java)), on Cupertino Light and Cupertino Dark: each holds 4.5:1. - **ICON-12 · MUST.** One focus ring color, the theme's `-color-accent-emphasis`, named once on `.root` (Editora's `-focus-ring`) and drawn by the `:focus-visible` block in the app stylesheet ([KBD-16](https://pauta-project.dev/6.0.0/keyboard/#kbd-16)), at 3:1 or better on every surface: the default, subtle, inset and overlay grounds of the two themes [ICON-09](https://pauta-project.dev/6.0.0/icons-and-color/#icon-09) names (see [Keyboard first](https://pauta-project.dev/6.0.0/keyboard/)). A test holds it. - *Check (test):* a test reads the ring's token from `.root` (Editora's `-focus-ring`) and computes it on the default, subtle, inset and overlay grounds of both flagship themes (Editora Light and Editora Dark), or of the app's own default light and dark themes where it ships another pair, and finds 3:1 or more. - *Reference:* Editora [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css) (*Keyboard focus*), [`StyleContrastTest.theFocusRingIsAtLeastThreeToOneOnEverySurface`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/StyleContrastTest.java). - **ICON-13 · SHOULD.** A state color the AtlantaFX theme has no role for (Editora's Git olive and violet) is a `ladder()` of `-color-bg-default`, never one fixed hex for light themes and another for dark. Brace, the periwinkle, is [ICON-06](https://pauta-project.dev/6.0.0/icons-and-color/#icon-06). - *Why:* the old fixed light hexes read at 3.2:1 on Editora Dark. - *Check (code):* each such token is declared as a `ladder()` of `-color-bg-default`; none is a fixed hex, or a pair of hexes switched by theme. A contrast test that resolves each ladder on every bundled theme's ground is the surest evidence. - *Reference:* Editora [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css) (`-state-olive`, `-state-violet`, `-state-key`), [`StyleContrastTest.theGitOliveAndVioletFollowTheAppThemesGround`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/StyleContrastTest.java). - **ICON-14 · SHOULD.** The contrast tests are pure: they read the stylesheets and do the WCAG arithmetic without starting the toolkit, so they run with the unit tests on every OS. - *Why:* a test that starts the toolkit is an FX test, tagged and run apart from the unit tests ([QUAL-06](https://pauta-project.dev/6.0.0/quality/#qual-06)); a pure one fails the plain unit run on every OS, the first time a color changes. - *Check (code):* every test class that computes a contrast ratio reads the app's `.css` resources as text and starts no toolkit: none is an FX test. - *Reference:* the app template's [`StyleContrastTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/ui/StyleContrastTest.java) and Mirada's [`StyleContrastTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/ui/StyleContrastTest.java): each reads the stylesheets as text and uses `javafx.scene.paint.Color` for the arithmetic alone. Mirada's [`AccentTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/ui/AccentTest.java) is pure too, over the accent it derives from the system's, and so is Termina's [`ThemeTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/ui/ThemeTest.java), which holds the colors of its terminal schemes and not the chrome's stylesheet. Editora's [`StyleContrastTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/StyleContrastTest.java) is pure as well, but Editora doesn't meet the rule yet: FX tests compute contrast ratios on rendered nodes too, [`ChordChipThemeFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ChordChipThemeFxTest.java), [`DebugValuePopupThemeFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/DebugValuePopupThemeFxTest.java) and [`SettingsFrameFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/SettingsFrameFxTest.java) among them. ### Themes - **ICON-15 · MUST.** The app has light and dark themes and switches between them at run time, without a restart. - *Check (code):* the app has a light theme and a dark one, and picking a theme calls `Application.setUserAgentStylesheet` in the running app. - *Reference:* Editora [`ui/Themes.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Themes.java) (`applyAppTheme`). - **ICON-16 · MUST.** The theme setting offers "follow the system": a choice that 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, the place where the user picks a theme lists it, and while it is chosen a listener on `Platform.getPreferences().colorSchemeProperty()` re-applies the theme. - *Reference:* Mirada [`settings/Settings.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/settings/Settings.java) (`ThemeChoice.SYSTEM`), [`ui/Theme.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Theme.java); nux [`config/Advanced.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/config/Advanced.java) (`THEME_SYSTEM`), [`ui/Theme.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/Theme.java); Termina [`ui/Themes.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/Themes.java) (`SYSTEM_ID`, `followSystem`), with the listener in [`ui/WindowManager.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/WindowManager.java); the app template's [`ui/Themes.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Themes.java) (`ThemeChoice.SYSTEM`). Each lists the choice in its Settings. Editora, Torrenta and Modula don't offer it yet: Editora's and Torrenta's pickers list named themes only ([`ui/Themes.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Themes.java), Torrenta's [`ui/Theme.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/Theme.java)), and Modula's theme is one on/off setting, `daylight` ([`config/Settings.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/config/Settings.java)). - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Themes.java), falling back to [`Themes.DEFAULT`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Themes.java) (Editora Light). - **ICON-18 · SHOULD.** The state colors never decorate: in every theme amber means "not durable yet", a warning ([WIN-01](https://pauta-project.dev/6.0.0/window-shell/#win-01) requires a warning in the echo area in amber) or an update available in About ([ABOUT-10](https://pauta-project.dev/6.0.0/templates/about/#about-10) asks for it there), red "broken" and green "verified", and nothing is colored amber, red or green for any other reason. A theme may change the accent, the ground and the ink, never these meanings. - *Check (code):* every rule that uses the amber, red or green state token (Editora's `-state-amber`, `-state-red` and `-state-green`) marks one of the meanings in the table under [State colors](https://pauta-project.dev/6.0.0/icons-and-color/#state-colors). - *Reference:* Editora [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css). ### Icons - **ICON-19 · MUST.** In an app whose icons come in two families, one colored by its stroke and one by its fill, a glyph node carries the style class of one family, never both (Editora's two are `icon-line` and `toolbar-icon`). An app with one icon family, or with no icons in its window, has nothing to mix. - *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 (code):* the method that builds a line glyph adds the line family's class alone, the one that builds a filled glyph adds the filled family's alone (Editora's `Icons.line` and `Icons.of`), and no other code adds the second class to a glyph node. A test that builds every glyph and fails when one carries both classes is the surest evidence. - *Reference:* Editora [`ui/Icons.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Icons.java) (`line`, `of`) and [`editor/MenuIcons.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/editor/MenuIcons.java), whose glyphs [`MenuIconFamilyFxTest.aLineGlyphIsNeverAlsoTaggedAsAFilledOne`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/MenuIconFamilyFxTest.java) holds. Torrenta's [`IconsTest`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/test/java/com/torrenta/ui/IconsTest.java) (`everyGlyphIsAStyledScaledPath`) builds every glyph and fails one that carries both classes or neither. Termina, Mirada and Modula draw one family each. - **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 (code):* wherever an action is drawn (a toolbar button, a menu row, a tab's menu), its glyph comes from one icon class or one lookup keyed by the command. Where a second icon class holds a copy of its own, the copy has the same path data and style class. A test that compares the path data and style class of each action's glyph across the icon classes is the surest evidence. An app that draws no glyph anywhere has nothing to compare and passes; its missing icons are [MENU-14](https://pauta-project.dev/6.0.0/menus/#menu-14)'s. - *Reference:* Editora [`ui/MenuBarIcons.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarIcons.java) reuses [`Icons`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Icons.java); [`editor/MenuIcons.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/editor/MenuIcons.java) (the editor package may not depend on `ui`) copies each twin's family and path data verbatim, held by [`MenuIconFamilyFxTest.everySharedActionUsesTheSameGlyphInBothIconSets`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/MenuIconFamilyFxTest.java). Mirada gives a command's menu row and its button one glyph from one lookup ([`ui/Icons.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Icons.java), `forCommand`). - **ICON-23 · SHOULD.** In an app that shows files with an icon each (a project tree, file tabs, a list of files), 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/FileIconsTest.java). - **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`. An app that ships no glyph set and no font has nothing to credit here. - *Reference:* Editora [`NOTICE`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/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/6.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, one that shows a glyph or a symbol such as "?" or "···" and no word, has a name: one helper sets its tooltip and its accessible text from the same string, the chord included where the tooltip carries one ([TBAR-03](https://pauta-project.dev/6.0.0/toolbars-and-tooltips/#tbar-03)), so a screen reader says what a sighted user reads. - *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 gets its tooltip and its accessible text in one call that sets both from one string (Editora's `Icons.button`, `Icons.toolbarButton` and `Icons.name`). A button with a `setTooltip` and no `setAccessibleText` fails, and so does one whose tooltip is written again later, to add a chord, while its accessible text keeps the first string. - *Reference:* Editora [`ui/Icons.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Icons.java) (`button`, `toolbarButton`, `name`), used by its panel toolbars. Torrenta's copy of all three ([`ui/Icons.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/Icons.java)): its `name` is the one place Torrenta sets an accessible text, and it names every button of the main toolbar ([`MainWindow.toolButton`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java)) and names them again when the keys change. Termina's [`ui/IconNames.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/IconNames.java) (`name`), which binds both to one string. Five apps don't meet it yet. Editora sets the tooltip only on its main toolbar ([`WindowToolbar.setupButton`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowToolbar.java) and [`ToolbarCoordinator.buildExtraButton`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolbarCoordinator.java)) and on the floating buttons that leave Zen and Expert mode and bring the toolbar back ([`WindowChromeCoordinator.installZenOverlay`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowChromeCoordinator.java)), and its stripe buttons' accessible text is the tool window's title without the chord the tooltip carries ([`ToolWindowManager.register`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindowManager.java)). Torrenta's detail pane gives its "···" button a tooltip and no accessible text ([`ui/DetailPane.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/DetailPane.java)). Mirada's [`ui/Icons.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Icons.java) (`button`, `name`) makes the accessible text the command's title and puts the chord in the tooltip only. nux's [`App.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java) sets the tooltip and the accessible text of its "?" button from one string, then its `shortcut` helper writes the tooltip again as "About Nux (F1)" and leaves the accessible text. Modula's transport, Settings and Record buttons have a tooltip and no accessible text ([`ui/RadioPane.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/RadioPane.java)), and so has the "+" button of its preset row ([`ui/PresetBar.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/PresetBar.java)). - **TBAR-03 · MUST.** The tooltip of a button that runs a command names the command and its chord, read from the active keymap and never typed into a string: "Save (C-x C-s)". The name is the command's title ([KBD-03](https://pauta-project.dev/6.0.0/keyboard/#kbd-03)), which a tooltip may show without its category prefix, as a menu row may ([MENU-01](https://pauta-project.dev/6.0.0/menus/#menu-01)): "Save" for "File: Save". An unbound command shows its title alone. - *Check (code):* the tooltip shows the command's title, whole or without its category prefix, and the keymap's display chord for its id, and is rebuilt when the keymap changes. The chord is the one of the command the button runs, and no chord is typed into the string. A fixed key of the control itself (Enter in a find field) is no command's chord and may be written, as [KBD-13](https://pauta-project.dev/6.0.0/keyboard/#kbd-13) allows. - *Reference:* Editora [`ToolbarCoordinator.buildExtraButton`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolbarCoordinator.java) (the `command.` title, prefix and all) and [`ToolWindowManager.tooltipFor`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindowManager.java). Its main toolbar ([`WindowToolbar.setupButton`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowToolbar.java), `refreshToolbarTooltips`) takes the chord from the keymap and the name from a `tooltip.*` catalog key of its own: for most buttons that is the title without its prefix (`tooltip.save=Save` beside `command.file.save=File: Save`), for six another name, which doesn't meet the rule: "Find / Replace" for `find.show`, whose title is "Find: Incremental Search"; "Open" for `file.find` ("File: Find File…"); "Close Tab" for `buffer.close` ("Buffer: Close"); "Open Folder as Project…" for `project.open` ("Project: Open Folder…"); "New From Template" for `template.new` ("Template: New File From Template…"); and "Simple UI mode" for `view.toggleSimpleMode` ("View: Toggle Simple UI Mode"). Two more buttons miss it another way: `file.clearRecent` ("File: Clear Recent Files") reads "Clear recent files", and the pinned tail's Stop button, which stops the run as `run.stop` ("Run: Stop Program") does, is set up with no command id, so it reads "Stop the running program" and shows no chord. Torrenta's `toolbar.withChord`. Mirada's [`Icons.tooltip`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Icons.java) builds the same "label (key)" form with the chord from the keymap in use ([`Command.chord`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Command.java)), and [`TitleBar.relabel`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/TitleBar.java) names the header buttons again when the keys change; Termina's [`IconNames.withChord`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/IconNames.java) takes the chord from its keymap too, but its find bar's arrows don't meet the rule yet: [`ui/SearchBar.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/SearchBar.java) names them from `search.older` and `search.newer`, "Previous match, up (Enter)" and "Next match, down (Shift+Enter)", not from a command's title, and gives each arrow the chord of the command that steps the other way. The up arrow steps to an older match, as `findNext` does ([`ui/TerminalWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java)), and shows the chord of `findPrevious`; the down arrow steps to a newer one, as `findPrevious` does, and shows the chord of `findNext`. The Enter and Shift+Enter in the two strings are the field's own keys. Modula's and nux's tooltips are written in the code, not read from a command: Modula's carry no chord ([`ui/RadioPane.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/RadioPane.java)), and nux's add the display text of a `KeyCombination` to the button's label ([`App.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java), `shortcut`). - **TBAR-14 · SHOULD.** Every tooltip shows after the same delay, 400 ms, set where the app makes its tooltips and not tooltip by tooltip. - *Why:* JavaFX waits a full second, which reads as no tooltip at all on a row of icons, and a delay set here and there makes some buttons answer faster than their neighbors. - *Check (code):* every `Tooltip` the app creates gets a 400 ms show delay from one place: each is made by one factory that calls `setShowDelay`, or the stylesheet's `.tooltip` rule sets `-fx-show-delay: 400ms`. A tooltip made with `new Tooltip` outside the factory and given no delay fails, as does any other delay. - *Reference:* no app yet. Termina is nearest: [`ui/IconNames.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/IconNames.java) (`name`, `SHOW_DELAY`) sets 400 ms on every tooltip it makes, and [`ui/TerminalWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java) sets the same inline on a tab's folder tooltip, but the tooltip on a disabled row of its [`ui/CommandPalette.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/CommandPalette.java) sets none. Editora sets 300, 350 or 400 ms on some ([`editor/LazyTooltip.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/editor/LazyTooltip.java)'s callers, [`ui/StructurePanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/StructurePanel.java), [`ui/MapSurface.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MapSurface.java), [`ui/DiffViewerPane.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/DiffViewerPane.java)) and leaves the rest at JavaFX's second; Mirada sets 250 ms on one ([`ui/MarksBadge.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/MarksBadge.java)) and none on the others; the app template, Torrenta, Modula and nux set none. No app's stylesheet sets `-fx-show-delay`. - **TBAR-06 · SHOULD.** The bars an app stacks at the top of its main window are one chrome band: whichever of the menu bar, the toolbar and the tab strip it has share `-color-bg-subtle` and draw no hairline between them. The bars it stacks at the bottom, whichever of a breadcrumb, a bottom stripe and the status bar it has, do the same. An app with one bar at an edge has nothing to join there. - *Why:* three rules within forty pixels read as clutter, not structure. - *Check (by hand):* look at the top and the bottom of the main window in a light and a dark theme for a line between two bars, or a change of ground from one to the next. - *Reference:* Editora [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css) (`.menu-bar, .tool-bar`). ### The toolbar **Applies to:** an app with a toolbar: a bar of icon-only buttons in a window's chrome (its title bar, a band of its own under the title bar or the menu bar, or the header of a panel), each a shortcut to a command. Editora's and Torrenta's `ToolBar`, the toolbars of Editora's panels and Mirada's header buttons are toolbars. So is a [tool window stripe](https://pauta-project.dev/6.0.0/toolbars-and-tooltips/#tool-window-stripes), on every side: the label its bottom buttons add to the glyph does not change what they are. These are not toolbars: a bar of labeled buttons (nux's `ToolBar`, whose one icon-only button, "?", only [TBAR-01](https://pauta-project.dev/6.0.0/toolbars-and-tooltips/#tbar-01) covers); controls that belong to the window's content, icon-only or not (Modula's transport and footer controls, Mirada's controls over the image); the buttons at the end of a tab strip (Termina's "+" and its chevron); and a find bar's buttons ([FIND-16](https://pauta-project.dev/6.0.0/templates/find-bar/#find-16) is theirs). Controls that belong to the window's content include a row of preset chips with its add button (Modula's) and the buttons inside a panel's rows (Mirada's info panel), and an image, PDF or Diff viewer's own bar in the content area (Editora's) is content too. - **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/6.0.0/keyboard/#focus-and-accessibility) has the general focus rules. - *Check (code):* every button on a toolbar is taken out of the Tab order with `setFocusTraversable(false)`, where it is built or by the helper that builds it (Editora's `Icons.toolbarButton`). - *Reference:* Editora [`Icons.toolbarButton`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Icons.java), used by the toolbars of its Git and Markdown lint tool windows; Torrenta's copy of it, which builds every button of its main toolbar ([`MainWindow.toolButton`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java)); Mirada's header buttons: its [`Icons.button`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Icons.java) takes Rotate out of the Tab order, and [`ui/TitleBar.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/TitleBar.java) takes Info and ☰ out where it builds them. Editora doesn't yet, on these toolbars among others: the buttons of its main toolbar, built by [`WindowToolbar.setupButton`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowToolbar.java) and [`ToolbarCoordinator.buildExtraButton`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolbarCoordinator.java), the stripe buttons, the buttons of the Test Results panel's toolbar, built by `Icons.button` ([`ui/TestRunnerPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TestRunnerPanel.java)), and the float, maximize and close buttons in the header of every tool window ([`ui/ToolWindowPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindowPanel.java)) take focus. - **TBAR-04 · SHOULD.** A toolbar's groups of buttons are separated by spacing, not rules: where a toolbar holds `Separator` nodes, keep them (their padding is the gap) and make the line transparent. - *Check (code):* the stylesheet makes the line of every `Separator` on a toolbar transparent (Editora's `.tool-bar .separator:vertical > .line`, a transparent border), on a panel's toolbar as on the main one. A toolbar that holds no `Separator` (Mirada's header buttons) has nothing to restyle and passes. - *Reference:* Editora [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css), for its main toolbar. Editora doesn't meet the rule on its Debug panel's toolbar yet: the separators there carry a class of their own, `debug-toolbar-separator`, whose one rule sets their padding and leaves the line drawn ([`ui/DebugPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/DebugPanel.java)). Torrenta's separators still draw a line (`.main-toolbar .separator:vertical > .line` in its [`styles/app.css`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/resources/com/torrenta/styles/app.css)). - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowChromeCoordinator.java), for its main toolbar. - **TBAR-07 · SHOULD.** 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 a pseudo-class (Editora's `:open`) 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java), [`WindowChromeCoordinator`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowChromeCoordinator.java) (Simple mode), `.button:open` in [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css). Torrenta's Simple mode button carries `:on`, which its stylesheet fills (`.toolbar-button:on`), but Torrenta doesn't meet the rule yet: its palette button carries no pseudo-class while the palette shows ([`ui/MainWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java)). Its `:active` marks the alternative speed limit on a label of the status bar, not on a toolbar button. - **TBAR-08 · MUST.** A toolbar never holds the only way to an action: every icon on it (in Editora, every icon of the cluster the user can customize) 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 button on the toolbar runs a registered command, so the palette lists it, and a menu lists that command too: the menu bar, or the app's main menu where it has no bar ([WIN-14](https://pauta-project.dev/6.0.0/window-shell/#win-14) says what a main menu is). A button that only opens a menu (Editora's Recent, Mirada's ☰) is no action of its own. In an app whose toolbar is built from a catalog (Editora's `ToolbarCatalog`), every catalog item's command id is also in the menus' model. - *Reference:* Mirada's header buttons, Rotate and Info, which its ☰ menu lists too ([`ui/TitleBar.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/TitleBar.java)). Eleven of the twelve buttons of Torrenta's toolbar run a command that a menu row runs too ([`MainWindow.buildToolbar`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java)), but Torrenta doesn't meet the rule yet: the twelfth, the palette button, opens the palette from a handler of its own, as the View menu's Command Palette row does, and no command does ([PAL-01](https://pauta-project.dev/6.0.0/templates/command-palette/#pal-01)). Editora [`toolbar/ToolbarCatalog.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/toolbar/ToolbarCatalog.java): each item carries the `commandId` it runs, and the only items without one are declared special widgets, such as the Recent menu button ([`ToolbarCatalogTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/toolbar/ToolbarCatalogTest.java)). Editora doesn't meet the rule yet: three catalog items run commands that are in the palette and in no menu, `tool.todo`, `tool.bookmarks` and `view.toggleZen`, which [`ui/MenuBarModel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarModel.java) doesn't list. - **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 (code):* the user can reorder the toolbar's buttons, remove one and bring the default layout back (Editora: a customize mode in which a drag along the bar reorders its buttons and a drag off it removes one, and a menu row that restores the default); and the layout is written to the settings, which every window reads. A test that drives a reorder and a removal is the surest evidence. - *Reference:* Editora [`ui/ToolbarCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolbarCoordinator.java), [`ToolbarCustomizeModeFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ToolbarCustomizeModeFxTest.java), [`ToolbarCustomizationFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ToolbarCustomizationFxTest.java). 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. ### The main toolbar **Applies to:** an app with a main toolbar: a toolbar ([The toolbar](https://pauta-project.dev/6.0.0/toolbars-and-tooltips/#the-toolbar) says what one is) that is a band of its own across the top of the main window, as Editora's and Torrenta's `ToolBar` are. Mirada's header buttons, which share the title bar with the file's name, are a toolbar and not a main toolbar; nux's bar of labeled buttons is neither. - **TBAR-15 · SHOULD.** The main toolbar's icon cluster and its pinned tail (Settings and the other controls the user must always reach) are separate containers: when the window narrows, the cluster's icons go into the overflow chevron and the tail keeps every control. - *Why:* a `ToolBar` overflows from its end, so with everything in one bar a narrow window hides Settings and the project switcher first and keeps icons that are all in the menus anyway ([TBAR-08](https://pauta-project.dev/6.0.0/toolbars-and-tooltips/#tbar-08)). - *Check (code):* the tail's controls sit in a container of their own beside the `ToolBar` that holds the icon cluster, and are not items of that `ToolBar`, so its overflow cannot take them. A test that narrows the window and finds the cluster overflowing while the tail's last control stays flush with the bar's right edge is the surest evidence. - *Reference:* Editora [`WindowToolbar.appendFixedTail`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowToolbar.java), [`ToolbarOverflowFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ToolbarOverflowFxTest.java). Torrenta keeps Simple mode and Settings inside its `ToolBar`, after a spacer, so they are the first to overflow. - **TBAR-16 · SHOULD.** Settings closes the main toolbar at its right end, with the Simple mode toggle just before it in an app that has Simple mode, whether the mode is on or off. - *Why:* the same two buttons in the same place in every app, and the toggle is the way back out of a mode that empties much of the bar. - *Check (by hand):* look at the bar's right end with Simple mode off, then on. - *Reference:* Editora [`WindowToolbar.appendFixedTail`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowToolbar.java); Torrenta [`MainWindow.buildToolbar`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java). - **TBAR-17 · SHOULD.** A main toolbar button is disabled while its command can't act (Save on a saved file, Undo with nothing to undo, Cut and Copy with no selection, a split on a tab that can't be split), and the events that change that state update it; nothing polls. [KBD-04](https://pauta-project.dev/6.0.0/keyboard/#kbd-04) has the same state in the menus and the palette. - *Why:* a button that does nothing when clicked reads as a broken button. - *Check (code):* each button's disabled state is bound to its command's availability, or refreshed from the document's edit, selection and dirty events and on a tab switch. - *Reference:* Editora [`WindowToolbar.refreshEditState`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowToolbar.java), `refreshSplitButtons` and `refreshPasteState`, which reads the clipboard only on a tab switch, on focus and after a copy, never on a keystroke; the buttons added from the catalog ([`ToolbarCoordinator.buildExtraButton`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolbarCoordinator.java)) stay enabled. Torrenta [`MainWindow.toolButton`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java) binds each button's `disableProperty` to its command's `enabled`. - **TBAR-18 · SHOULD.** A command hides the main toolbar and shows it again, and the choice is kept across launches. - *Check (code):* a registered command toggles the bar, and the setting it writes is read back at startup. - *Reference:* Editora `view.toggleToolbar` ([`WindowChromeCoordinator.toggleToolbar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowChromeCoordinator.java)), with a floating button at the top right that brings a hidden bar back; Torrenta `toggle-toolbar`, kept as `settings.toolbar()`. - **TBAR-19 · SHOULD.** The main toolbar keeps its height when a control in it hides or shows (in Editora, the project switcher in Simple mode or with Projects off), so the tabs and the content under it never move. - *Check (by hand):* hide and show each control the bar can lose (in Editora, turn Simple mode on and off) and watch the top edge of what sits under the bar: it stays where it was. - *Reference:* Editora [`WindowToolbar.stabilizeToolbarHeight`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowToolbar.java), which pins the row's minimum height to the project switcher's. ### Tool window stripes **Applies to:** an app with tool window stripes. - **TBAR-12 · SHOULD.** A tool window stripe button takes its name from its tool window: the name its tooltip shows ([TBAR-03](https://pauta-project.dev/6.0.0/toolbars-and-tooltips/#tbar-03)) is the window's title, with the chord of the command that toggles the window, and it follows the title when the title changes. The button's right-click menu has *Open in Split* and *Hide*. - *Check (code):* the stripe button's tooltip is built from the tool window's title and the keymap's display chord for the window's command, and is built again when the title changes; the button has a right-click menu with those two rows. - *Reference:* Editora [`ToolWindowManager.register`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindowManager.java) (the menu) and `tooltipFor`, which `refreshTooltips` runs again on a keymap switch only. Editora doesn't meet the rule yet: a title change (the Project window becoming "Current Folder") reaches the button's accessible text and the bottom stripe's label, not its tooltip. - **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 (code):* the code that lays out the side stripes pads the stripe's top by the tab strip's measured height, so its first button starts where the editor's text does. A test that compares the first stripe button's top with the editor's first line is the surest evidence. - *Reference:* Editora [`ToolWindowManager.alignVerticalStripesWithEditorText`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindowManager.java), [`ToolWindowStripeAlignmentFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ToolWindowStripeAlignmentFxTest.java). ## Tabs and tool panels (TABS) https://pauta-project.dev/6.0.0/tabs-and-panels/: The tab strip and its states, reorder and reopen, and the tool panels that dock around the editor. ### Window title - **TABS-10 · SHOULD.** The window title names the file, the project and the app, with a `●` prefix for an unsaved file. An app with no files or projects names what the window shows in their place (a terminal, the working folder or the title its program set), or the app alone where there is nothing to name. - *Check (code):* the code that sets the stage title adds all three and the marker; in an app with no files or projects, what stands in for them, or the app's name alone. - *Reference:* Editora [`MainController.updateWindowTitle`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java). Termina's title follows the selected tab ([`TerminalTitle.window`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalTitle.java): the name the user gave the tab, the title the shell set or the working folder's path, and the app's name when it knows none). The app template, Modula and nux show the app's name. ### Tabs **Applies to:** an app whose main window holds documents or sessions in tabs the user opens and closes, as Editora's files and Termina's terminals are. The pages of a Settings window (nux's `TabPane`), the fixed sections of a detail pane (Torrenta's) and a strip that switches the window between views (Torrenta's Transfers, Search and RSS) are not such tabs: the user neither opens nor closes them. The Tabs rules cover every tab of the main window's strip, whatever it shows (Editora's image, hex and PDF viewer tabs as much as its editor tabs), not tabs inside a tool window (those of Editora's Terminal and Build Output panels). - **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/6.0.0/menus/) lists the ones that act on a tab. A terminal app's tabs are never saved or unsaved, so a terminal app has no close unmodified, and closing its window closes all its tabs, so it needs no close all; the other operations are its commands too. - *Check (code):* the registry holds a command for each operation, each has a row in the menu bar or in the tab's right-click menu, and that menu (Editora's `TabContextMenu`), on every tab of the strip, lists the ones that act on a tab; in a terminal app, each operation but close unmodified and close all. - *Reference:* Editora [`ui/WindowCommandRegistrar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TabContextMenu.java). Editora has no previous-tab command yet, and its image, hex and PDF viewer tabs have no right-click menu: `openImageTab`, `openHexTab` and `openPdfTab` in [`ui/FileWorkflowCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/FileWorkflowCoordinator.java) install none, and `installTabMenu` in [`ui/MainController.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java) is called for an editor's tab alone. Termina [`ui/TerminalWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java) (`closeTab`, `closeOtherTabs`, `closeTabsToTheLeft`, `closeTabsToTheRight`, `pinTab`, `reopenClosedTab`, `nextTab` and `previousTab` in `menuCommands`; the tab's menu in `buildTabMenu`). Its File menu closes the tab, the others, the ones to either side, or the window, which is its close all ([`ui/MenuBarModel.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/MenuBarModel.java)). - **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 label of its own (Editora's style class for it is `tab-title`). The tooltip is the full path, in which `~` may stand for the home folder. A terminal app's tab shows no file: its header has no file-type glyph, its title names the tab (the user's own name for it, the title the shell set, the running program or the working folder), and its tooltip is the working folder's full path. - *Why:* the graphic is what makes the header a drag handle and lets each state set its own color. - *Check (code):* every tab that shows a file, an editor's or a viewer's, gets `setText("")` and a graphic that holds the file-type glyph and the title in a label of its own (Editora's `.tab-title`); its tooltip is the file's path. In a terminal app: every tab's own text is empty, its graphic holds the title label and no file-type glyph, and the tooltip is the working folder of the tab's active pane. A path that writes the home folder as `~` is a full path. - *Reference:* Editora [`ui/TabHeaders.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TabHeaders.java), for its editor tabs (`bufferHeader`, `tooltip`). Its image, hex and PDF viewer tabs don't yet: `contentHeader`, which builds their header, sets no tooltip. Termina [`TerminalWindow.addTab`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java) (a `tab-title` label as the tab's graphic, and `installDirectoryTooltip`) over [`ui/TerminalTitle.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalTitle.java) (`tab`, and `tooltip`, which writes the home folder as `~`). - **TABS-03 · MUST.** A tab's header, the one graphic header of [TABS-02](https://pauta-project.dev/6.0.0/tabs-and-panels/#tabs-02), carries the tab's states: a `• ` prefix in amber italic for unsaved, a pin and bold for pinned, muted italic for read-only. A terminal app's tab is never unsaved or read-only, and its header says in their place what the tab is doing: the title is the running program's name while one runs, unless the user or the shell named the tab, and a mark beside the title says what happened while the tab was not selected (a notification, a bell, or output after a quiet spell), cleared when the tab is selected. A pinned terminal tab is drawn as any other pinned tab, with a pin and a bold title. - *Check (code):* the code that builds a tab's header marks it unsaved, pinned or read-only (Editora's style classes `dirty`, `pinned` and `read-only` on `.tab-header`) and adds the `• ` prefix and the pin, and the stylesheet gives each mark the look the rule names. In a terminal app: the stylesheet styles the pinned title, the code that names the tab puts the running program before the folder, and the header shows the mark and clears it when the tab is selected. - *Reference:* Editora [`ui/TabHeaders.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TabHeaders.java), [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css); the Unsaved, Pinned and Read-only rows of the [Spec](https://pauta-project.dev/6.0.0/tabs-and-panels/#spec) table. Termina [`ui/TerminalTitle.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalTitle.java) (`tab`), [`ui/TabMarks.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TabMarks.java) and `TabMarkState` in [`ui/TerminalWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java) (a dot after the title, in the terminal palette's magenta, yellow or cyan, and a pin), and `.tab-title.pinned` in its [`app.css`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/resources/com/termina/styles/app.css). - **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. A terminal app has three of them ([TABS-01](https://pauta-project.dev/6.0.0/tabs-and-panels/#tabs-01)), and each skips its pinned tabs too. - *Check (code):* every bulk close the app has (close others, close all, close unmodified, close to the left and to the right) builds the list of tabs it will close without the pinned ones: it tests each tab for pinned before taking it (Editora's `closeOtherTabs`, `closeAllTabs`, `closeUnmodifiedTabs`, `eligibleToLeft` and `eligibleToRight`). A test that asserts it is the surest evidence. - *Reference:* Editora [`ui/MainController.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java). Termina [`ui/TabRanges.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TabRanges.java) (`closing`, which leaves out every pinned position and which each bulk close of [`ui/TerminalWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java) goes through) and [`TabRangesTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/ui/TabRangesTest.java). - **TABS-05 · MUST.** Pinning moves the tab to the end of the pinned group, unpinning to just after it. - *Check (code):* the code that pins or unpins a tab then moves it to the boundary between the pinned tabs and the rest, the index equal to the number of other pinned tabs in its strip: the last place of the pinned group for a tab just pinned, the first place after the group for one just unpinned (Editora's `togglePin`, which calls `moveToPinBoundary`). - *Reference:* Editora [`ui/MainController.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java) (`togglePin`), [`ui/EditorArea.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/EditorArea.java) (`moveToPinBoundary`). Termina [`ui/TerminalWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java) (`togglePin`, which counts the other pinned tabs and moves the tab to that index). - **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 (code):* each window keeps a list of the tabs it closed, newest first and no longer than twenty; the command takes the newest entry and opens it. In an app whose tabs hold files, an entry is the file, whether an editor's tab or a viewer's showed it, with the caret where the tab has one; closing a file again replaces its earlier entry, and reopening puts the caret back. In a terminal app, an entry holds the tab's panes with each one's shell and directory, their arrangement, the names the user gave them and the tab's place in the strip, and no scrollback. A test over the list is the surest evidence. - *Reference:* Editora [`ui/ClosedTabs.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ClosedTabs.java), [`ClosedTabsTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ClosedTabsTest.java); `C-S-t` in the CUA keymap. Editora doesn't yet for its image, hex and PDF viewer tabs: `rememberClosed` in [`ui/MainController.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java) records the file of an editor's tab alone, so a closed viewer tab does not come back. Termina [`ui/ClosedTabs.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/ClosedTabs.java) and [`ClosedTabsTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/ui/ClosedTabsTest.java), on `Ctrl+Shift+Z` (`Cmd+Z` on macOS). - **TABS-07 · SHOULD.** Tabs reorder by dragging, with this feedback: 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TabHeaders.java); Termina `installTabDrag` and the pure [`TabReorder.insertIndex`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TabReorder.java). 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.** In an app whose tabs hold files, 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. The tab's tooltip names the file's Git status too, so color is not the status's only sign ([ACC-05](https://pauta-project.dev/6.0.0/accessibility/#acc-05)). A terminal app's tabs hold no files, so the rule passes it by. - *Check (code):* the code that styles a tab gives it, for its file's Git status, the style class the Project tree gives that file's row, read-only or not, and the stylesheet lets the unsaved tab's amber win over it; and the code that sets the tab's tooltip adds the status in words (modified, added, untracked and the rest) when the file has one. A test that finds the tree's class on a changed file's tab, and the status in its tooltip, is the surest evidence. - *Reference:* for the colors, Editora [`ui/TabGitStatus.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TabGitStatus.java), [`TabGitStatusTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/TabGitStatusTest.java). For the tooltip, no app yet: Editora's tab tooltip is the file's full path (`tooltip` in [`ui/TabHeaders.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TabHeaders.java)), so the tint is the tab's only sign of the status. Its Project tree adds a letter to the color; its tabs add no word, glyph or shape. - **TABS-09 · SHOULD.** An app whose tabs hold files has a switcher that lists the open files in tab order. A command opens it; the arrows or the active keymap's line chords move, Enter or releasing Ctrl (the Control key, on macOS too) activates, Esc or the keymap's cancel chord cancels, and Backspace, Delete or the keymap's delete-character chord closes the highlighted file. The switcher's width is fixed to the longest path on each open, so it never resizes while you move. A terminal app's tabs hold no files, so the rule passes it by. - *Check (by hand):* open it with several tabs; move with the arrows and with the active keymap's line chords, close a file from it, cancel it, and open it again to activate another file; the list keeps its width. - *Reference:* Editora [`ui/Switcher.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Switcher.java), which reads its keys through [`ui/PickerKeys.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/PickerKeys.java) and the keymap, and [`SwitcherFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/SwitcherFxTest.java). In Editora's Emacs keymap `C-x C-b` opens it (`switcher.show`), `C-n` and `C-p` move, `C-g` cancels and `C-d` closes the file ([`keymaps/emacs.json`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps/emacs.json)); no other Editora keymap binds `switcher.show`. - **TABS-12 · SHOULD.** A command hides the tab bar. - *Check (code):* a registered command hides the tab header, with any number of tabs open. One that hides it only while the window has a single tab does not meet the rule. - *Reference:* Editora `view.toggleTabBar`, `.tab-pane.no-tab-header` in [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css). Termina doesn't yet: the nearest it has is a setting, with a palette command that toggles it, that hides the strip only while the window has one tab (`settings.hideTabBar` in [`ui/SettingCommands.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/SettingCommands.java)). ### Tool panels **Applies to:** an app with tool panels: a tool panel is a panel docked at an edge of the main window, beside or under the content, that the user shows and hides as a whole, the content taking its room while it is hidden. A sidebar, a detail pane, an info panel and a thumbnail strip are tool panels, on a stripe or not. A section that folds in place and leaves its heading showing is content (nux's All variables table, a `TitledPane` under its dashboard), and so are a terminal's split panes: neither is a tool panel. Nor is a bar of the window's chrome that a command hides (a toolbar, a status bar, a tab strip). - **TABS-13 · MUST.** Every tool panel has a command that shows and hides it, with the id `tool.`, as Editora's `tool.project` is, and where the app has a stripe, the panel's stripe button runs that command. In the Emacs keymap, `M-1` through `M-9` and then `M-0` run those commands, one chord to a panel: an app with fewer than ten panels uses the first of the chords, and one with more chooses the ten panels that get them. An app with one key table and no Emacs keymap ([KBD-09](https://pauta-project.dev/6.0.0/keyboard/#kbd-09)) owes none of these chords. - *Check (code):* every tool panel has a registered command whose id is `tool.` and the panel's own id, which shows the panel when it is hidden and hides it when it shows; a stripe button, where the app has stripes, runs that command, and one that toggles the panel directly and skips what the command does first fails; and `emacs.json`, in an app that ships one, binds `M-1`, `M-2` and on through `M-0` to those commands, one for each panel up to ten. - *Reference:* Editora registers a `tool.` command for each of its tool windows ([`ui/WindowCommandRegistrar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowCommandRegistrar.java)) and binds ten of them to `M-1` … `M-0` ([`keymaps/emacs.json`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps/emacs.json)). It doesn't meet the stripe clause yet: [`ToolWindowManager.register`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindowManager.java) gives each stripe button the manager's own `toggle`, not the command, so the button skips what some commands do first (`tool.remote` refreshes its panel; `tool.project` and `tool.notes` test that the feature is on). Nor does every one of its commands hide a panel that shows: `tool.gitLog`, for one, only opens its panel (`openGitLog` in [`ui/GitWindowCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/GitWindowCoordinator.java)), and so do the `tool.` commands of its build tools (`registerCommands` in [`ui/BuildCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/BuildCoordinator.java)). Torrenta and Mirada don't meet the rule yet. Torrenta has no `tool.` command: its two panels' commands are `toggle-sidebar` and `toggle-detail` ([`ui/MainWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java)), and it ships no keymap file, so it owes no chord. Mirada's two are `view.properties` and `view.thumbnails` ([`ui/Command.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Command.java)), and its [`keymaps/emacs.json`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/resources/com/mirada/keymaps/emacs.json) binds them to `i` and `t`, where the rule requires `M-1` and `M-2`. - **TABS-15 · SHOULD.** Panel state is restored: which panels are open, where each sits and every divider position go to the session-state file ([SET-08](https://pauta-project.dev/6.0.0/settings/#set-08); Editora's is `workspace-state.json`) and come back on the next launch. In an app with [tool window stripes](https://pauta-project.dev/6.0.0/tabs-and-panels/#tool-window-stripes) that includes each window's side and order, the stripe buttons the user hid, and the windows that float. - *Check (code):* the session state holds each of those, and the code that builds the panels reads them back at startup. - *Reference:* Editora [`ui/ToolWindowManager.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindowManager.java), [`config/WorkspaceState.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/WorkspaceState.java). - **TABS-19 · SHOULD.** Closing the panel that holds keyboard focus returns focus to where it was in the content (in Editora, the editor). - *Check (code):* the code that closes a panel keeps the content's last focus owner and refocuses it on close. - *Reference:* Editora [`ToolWindowManager.focusEditor`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindowManager.java), a weak reference to the last editor focus owner. ### Tool window stripes **Applies to:** an app with tool window stripes. - **TABS-16 · SHOULD.** Tool windows 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindow.java), [`ToolWindowManager.MAX_PER_SIDE`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindowManager.java). - **TABS-17 · SHOULD.** A tool window 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindowDock.java), [`ToolWindowVisibilityTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ToolWindowVisibilityTest.java) (an empty stripe shows while dragging). - **TABS-18 · SHOULD.** Tool windows float, maximize, resize and close from the keyboard, and at most one window is maximized at a time. - *Check (code):* floating, maximizing, resizing and closing a tool window are each a registered command, so the palette runs them without the mouse; and maximizing one first restores the one that was maximized. - *Reference:* Editora `view.floatToolWindow` (palette only), `view.maximizeToolWindow` (`C-x f`), `view.closeFocusedToolWindow` (`C-x 0`), the resize commands (`C-x S-.`, `C-x S-,`, `C-x S-6`); [`ui/ToolWindowManager.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindowManager.java) keeps one `maximized` panel and restores it before it maximizes another. - **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 (code):* the stripe keeps two values for a tool window, the user's saved show/hide choice and whether the context offers the window now, shows the button only when both hold, and never writes the first when the second changes. A test that asserts it is the surest evidence. - *Reference:* Editora [`ui/ToolWindowVisibility.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindowVisibility.java), [`ToolWindowVisibilityTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ToolWindowVisibilityTest.java). - **TABS-21 · SHOULD.** A tool window whose content needs more room than the default share of its side can ask for more on its first open (Editora's Debug window asks for 42 %); the user's own size wins afterwards. - *Check (code):* a tool window can ask for a larger share of the side on its first open (Editora's `setFirstOpenShare`), the docking code grants it only while the user has set no size for that window, and the other windows keep the side's size. A test that asserts it is the surest evidence. - *Reference:* Editora [`ToolWindow.setFirstOpenShare`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindow.java), [`ToolWindowFirstOpenShareTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ToolWindowFirstOpenShareTest.java). - **TABS-22 · SHOULD.** A stripe button badges a spinner while its window has something under way. - *Check (code):* a tool window has a busy state, and its stripe button shows a spinner badge while the state holds and hides it when it ends. A test that asserts it is the surest evidence. - *Reference:* Editora [`ToolWindow.busy`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolWindow.java), [`ToolWindowManagerFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ToolWindowManagerFxTest.java). - **TABS-23 · SHOULD.** Tool windows 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/GitPathScope.java). ## Menus (MENU) https://pauta-project.dev/6.0.0/menus/: The menu bar and right-click menus: an icon and the chord on every row, one font, one menu at a time, and a press anywhere else closes it. ### Look and feel - **MENU-14 · MUST.** Every row of every menu the app draws carries an icon that depicts it. A command row wears its command's glyph; a row that names a thing rather than an action (a recent file, a branch, a project) wears that thing's icon; a submenu wears its family's. Only a check or radio row goes without, because its mark fills the icon column. Where the icon set has no glyph that depicts a command, the app adds one (a Material 24 dp path, or a line glyph in the kit's style) instead of leaving the row blank or borrowing another command's. - *Why:* a menu is scanned before it is read, and the glyph is what the eye finds first; the same glyph on the toolbar, in the palette and in the menu ([ICON-20](https://pauta-project.dev/6.0.0/icons-and-color/#icon-20)) is learned once. A blank cell breaks the column, and a borrowed glyph says something else. - *Check (code):* every row the app adds to a menu it draws is given a glyph where the row is built, and only check and radio rows are built without one. On a plain `MenuItem` the glyph is its graphic. A menu-bar row ([MENU-02](https://pauta-project.dev/6.0.0/menus/#menu-02)) is a `CustomMenuItem` whose `getGraphic()` is null: its glyph is the node inside the icon column of its content (Editora's `menu-item-icon`), and an empty column fails. A submenu's graphic is the same row layout, read the same way. Where the glyphs come from a table keyed by command id, the table has an entry for every command a menu lists, and none is another command's glyph. A test that opens the menu bar's menus and the right-click menus of a tab, an editor, a list row and the toolbar, and fails on a visible row with no glyph, is the surest evidence. - *Reference:* Editora [`ui/MenuBarIcons.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarIcons.java), [`editor/MenuIcons.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/editor/MenuIcons.java), [`ui/TabContextMenu.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TabContextMenu.java); Termina's tab menu has an icon on every row. Mirada's [`MenusFxTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/ui/MenusFxTest.java) (`everyRowOfEveryMenuHasAGlyph`) opens its header menu, its zoom menu and the image's right-click menu and fails on a row with no glyph. Editora doesn't yet pass: about half its menu-bar rows have no glyph, and [`MenuBarIconsTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/MenuBarIconsTest.java) holds that a command without a fitting glyph gets none, which this rule reverses; many right-click and drop-down rows have none either (Run All Requests in a `.http` file, the CSV grid's menu, the Markdown preview's). - **MENU-15 · MUST.** In every menu the app draws itself, a row whose command has a chord in the active keymap shows that chord, in right-click menus, drop-downs and the toolbar's overflow as in the in-window menu bar: right-aligned in the menu's chord column, in the keyboard color, the one color the app keeps for chords and key chips (Editora's token for it is `-state-key`; [ICON-06](https://pauta-project.dev/6.0.0/icons-and-color/#icon-06) says how the color is made), at the size [MENU-16](https://pauta-project.dev/6.0.0/menus/#menu-16) gives. An unbound command leaves the cell empty, never a wrong chord, and a keymap switch rewrites every cell. The menus a platform draws are outside this rule: the macOS system menu bar, whose rows append the chord to the title ([MENU-02](https://pauta-project.dev/6.0.0/menus/#menu-02)), and a tray icon's menu, which shows none. - *Why:* the menu is where a user learns the keys. A right-click menu that hides them teaches the mouse, while the palette and the toolbar's tooltips already show the same chord. - *Check (code):* in the in-window menu bar, in every right-click menu and in every drop-down, a row that runs a command has a chord cell, right-aligned in one column of the menu, that the code fills with the active keymap's display chord for the command's id and leaves empty for an unbound command: a label of the row's own (Editora's `menu-item-chord`) or, outside the menu bar, the item's accelerator text, never a chord typed into a string. The cell is filled again on each showing or when the keymap changes, and the stylesheet draws it in the app's keyboard color at [MENU-16](https://pauta-project.dev/6.0.0/menus/#menu-16)'s size. An app whose menu rows run only commands that have no chord (nux's drop-downs: its one key table binds none of their commands) has nothing to show, and passes. A row of the macOS system menu bar is not judged here, since [MENU-02](https://pauta-project.dev/6.0.0/menus/#menu-02) has its chord appended to its title, and neither is a tray icon's menu. A test that binds a command, opens a right-click menu that lists it, finds its chord, and finds the new chord after a keymap switch is the surest evidence. - *Reference:* Editora [`MainMenuBar.rowContent`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainMenuBar.java) and `alignChordColumns`, `.menu-item-chord` in [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css), for the menu bar. Editora's right-click menus show no chords yet: a row there is a plain `MenuItem`, not the menu bar's row. The app template's right-click menus show them: [`ui/CommandMenu.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/CommandMenu.java) draws each row as the menu bar's ([`AppMenus.inWindowRow`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/AppMenus.java)) and re-reads its chord on every showing (`refresh`). The template doesn't meet the rule either: it colors the chord `-color-fg-muted`, not a keyboard color (`.menu-item-chord` in its [`app.css`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/resources/com/example/app/styles/app.css)), and so does Termina's menu bar ([`app.css`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/resources/com/termina/styles/app.css)). No app has a test that opens a right-click menu and reads a chord from it. - **MENU-16 · MUST.** Every menu the app draws itself (the in-window menu bar, right-click menus, the drop-down of a menu button or a split button, the toolbar's overflow) draws its titles in Inter 14 px regular and its chords in Inter 11 px at the default zoom, scaled by the UI zoom ([WIN-12](https://pauta-project.dev/6.0.0/window-shell/#win-12)), whatever node it was opened from: the size is set on `.context-menu` and its rows' labels from one value the zoom sets, never inherited from the node. The macOS system menu bar and a tray icon's menu are the platform's, drawn in the platform's font, and outside this rule. - *Why:* a popup inherits the font of the node it was shown from, and `em` resolves against it: Editora's toolbar menu once rendered at the bar's 18 px, a third larger than every other menu, and a file tree's or a monospace editor's font leaks the same way. - *Check (code):* the stylesheet sets the font family and the size on `.context-menu` and on its rows' title and chord labels from one value, in pixels and never in `em`, so the font of the node a menu was opened from cannot reach it; and the code that applies the UI zoom rewrites that value, so the 14 px and the 11 px scale with the zoom. A test that opens a menu from the toolbar, an editor and a tree row and reads Inter 14 px from each row's title, and 14 px times the zoom after the UI zoom changes, is the surest evidence. - *Reference:* Editora `.context-menu` and `.menu-item-chord` in [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css), [`MainMenuBar.UI_FONT_SIZE`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainMenuBar.java), [`ToolbarMenuFontFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ToolbarMenuFontFxTest.java) and [`ContextMenuFontFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ContextMenuFontFxTest.java). Editora writes 14 px and 11 px as absolute pixels and has no UI zoom yet ([WIN-12](https://pauta-project.dev/6.0.0/window-shell/#win-12)), so its menus keep their size whatever opens them but don't scale. - **MENU-18 · SHOULD.** At the default zoom a menu row is 34 px high (padding 8 × 12), its icon column is 22 px wide with 8 px to the title, and its chord starts at least 18 px after the title column. The popup's card has a radius of 8 and a shadow of radius 16 at offset Y 16: the offset is at least the radius. - *Why:* one row in every app is what makes the menus one family's. And a menu is a native window sized to its root with the effect included, so a shadow that reaches above the menu is invisible window over the bar the menu hangs from, and the pointer lands on it instead of the next menu button. - *Check (code):* the stylesheet sets the row's padding and the popup's radius and shadow, with the shadow's offset no smaller than its radius; the row's layout sets the icon column's width and the chord's margin. - *Reference:* Editora `.menu-item` and `.context-menu` in [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css), and [`MainMenuBar.ICON_COLUMN`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainMenuBar.java) and `rowContent`; [`MenuPopupBoundsFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/MenuPopupBoundsFxTest.java) holds the shadow below the popup. No other app draws that card. Termina, Torrenta and the app template get the row's padding from the Editora themes they ship, and keep those themes' popup: a radius of 4 and a shadow of radius 6 (8 in the dark theme) at offset Y 2 (`.menu-item` and `.context-menu` in each one's `editora-light.css` and `editora-dark.css`). Termina's [`ui/MenuRows.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/MenuRows.java) has the same 22 px column and 18 px chord margin; the app template's [`ui/AppMenus.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/AppMenus.java) has an 18 px icon column (`ICON_SLOT`) and a 16 px chord margin. Mirada and nux write no radius or shadow for `.context-menu` and take their AtlantaFX theme's popup (Cupertino, Primer). Modula's [`modula.css`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/resources/com/modula/modula.css) gives `.context-menu` a radius of 8 and a shadow of radius 20 at offset Y 6, and its rows a padding of 4 × 8. ### The menu bar **Applies to:** an app with a menu bar. - **MENU-01 · MUST.** Every menu-bar item is a command from the registry, with the command's title ([KBD-03](https://pauta-project.dev/6.0.0/keyboard/#kbd-03)), its chord from the active keymap and its enabled state from the command's gate. A row may show the title without its category prefix ("Save As…" for "File: Save As…"); it never carries a title of its own. The bar assembles and refreshes; it holds no behavior of its own. - *Check (code):* the bar's model lists command ids only, beside the separators and the submenus that group them, and every row runs its id through the registry. A row that is no command id fails: one built by hand, with a title and a handler of its own. - *Reference:* Editora [`ui/MenuBarModel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarModel.java) over [`command/CommandRegistry.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/command/CommandRegistry.java), [`ui/MainMenuBar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainMenuBar.java): the model's entries are command ids, separators and the titles of its submenus. Torrenta and Termina don't meet the rule yet. Rows of Torrenta's View menu, the Command Palette, Toolbar, Sidebar and Simple Mode rows among them, are built by hand with `menu.*` titles and handlers of their own ([`ui/MainWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java)). Termina's model ([`ui/MenuBarModel.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/MenuBarModel.java)) holds rows that are no command id: the New Tab With Profile submenu, whose rows carry each profile's name and open the tab from a handler of their own (`profileBarRows` in [`ui/TerminalWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java)), and, off macOS, the zoom row, one row of buttons for its four zoom commands. - **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 menu-bar row calls `setAccelerator`; each row of the in-window bar is a `CustomMenuItem` whose content lays out the icon, the title, a spacer and the chord; and where the bar is the macOS system menu bar, a row's text is the title with the chord appended and the row has no graphic. - *Reference:* Editora [`ui/MainMenuBar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/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 (code):* each menu's on-showing handler reads every row's enabled state from its command again, and the code that switches the keymap or the locale rewrites every row's title and chord. A test that changes a command's state after the window is built (a repository detected late) and finds the row enabled is the surest evidence. - *Reference:* Editora [`MainMenuBar.refreshEnablement`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainMenuBar.java), [`MenuBarEnablementFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/MenuBarEnablementFxTest.java). - **MENU-04 · SHOULD.** An app with a Simple mode shows a shorter menu in it, 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainMenuBar.java), [`MenuBarModel.menus(simple)`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarModel.java). - **MENU-17 · SHOULD.** The in-window menu bar, the one an app shows on Windows and Linux ([WIN-03](https://pauta-project.dev/6.0.0/window-shell/#win-03)), is reachable from the keyboard in every keymap. JavaFX opens the bar's first menu on `F10` and on a lone `Alt`; a keymap that binds `F10` to something else binds a command that focuses the menu bar instead. So does a terminal app, where a plain `F10` goes to the program it runs. The macOS system menu bar is reached with the OS's own keys and asks nothing of the app. - *Why:* the menus are a keyboard user's map of the app; a chord that never reaches them hides it. - *Check (by hand):* on Windows or Linux, in each keymap, reach the first menu with the keyboard alone and walk the bar with the arrows. - *Reference:* no app yet. Editora's CUA, VS Code and Sublime keymaps bind `F10` to `debug.stepOver` ([`keymaps/cua.json`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps/cua.json)), and no command focuses the bar. Termina leaves a plain `F10` to the program in the terminal ([`ui/ViewKeys.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/ViewKeys.java)) and has no such command either. ### Right-click menus **Applies to:** an app with a right-click menu: a menu the app builds and opens on a right-click, the Menu key or `Shift+F10`, over something in one of its windows. The stock Cut, Copy and Paste menu that JavaFX gives a text field does not make an app one, and neither does a tray icon's menu, which the platform draws: nux has both and no right-click menu. - **MENU-05 · MUST.** In an app with a right-click menu, every list row, tree row, tab, editor and read-only console has one, with the actions for *that* thing, and every action in a right-click menu is a command ([KBD-01](https://pauta-project.dev/6.0.0/keyboard/#kbd-01)). The rule covers the lists, trees, tabs, editors and read-only consoles in the app's windows. A log shown as text, the Debug Log among them, is a read-only console and has its right-click menu. A list that only navigates, switching what its window shows (a Settings sidebar, a list of pages), has no actions of its own and is outside the rule, as are the overlay list of a picker or a palette and a plain text area in a dialog. - *Check (code):* list the lists, trees, tab strips, editors and read-only consoles in the app's windows, the text of the Debug Log window and of any other log shown as text among the consoles, and find the right-click menu each one installs; then read every row of every right-click menu the app builds: its action is one a registered command runs too, by the command's id through the registry or by calling what the command calls, so the palette reaches it. A row whose action no command runs fails, as does a list, tree, tab strip, editor or console with no menu; the stock Cut, Copy and Paste menu that JavaFX gives a text area is not one. A list that only switches what its window shows (a Settings sidebar, a list of pages), the overlay list of a picker or a palette and a plain text area in a dialog are not judged. - *Reference:* the app template's [`ui/CommandMenu.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/CommandMenu.java), which builds each menu from registered command ids and runs a row through the registry (`onRow` for a list row, `onConsole` for a read-only console, its Debug Log among them: [`ui/DebugLogWindow.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/DebugLogWindow.java); [`RightClickMenusFxTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/ui/RightClickMenusFxTest.java)). Editora's [`ui/TabContextMenu.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TabContextMenu.java) and [`ui/ConsoleContextMenu.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ConsoleContextMenu.java) are menus this rule describes ([`ui/RowContextMenu.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/RowContextMenu.java) builds none: it sends the keyboard's request to the selected row's own menu), but their rows are built by hand and call the window's methods, not a command id, so nothing holds that each row has a command. Editora, Termina, Mirada, Torrenta and Modula don't meet the rule yet, in these places among others. In Editora the trees and the list of the Hierarchy, References and Undo History panels have no right-click menu ([`ui/HierarchyPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/HierarchyPanel.java), [`ui/ReferencesPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ReferencesPanel.java), [`ui/UndoHistoryPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/UndoHistoryPanel.java)), and the Customize Toolbar… row of the toolbar's menu turns on a mode that no command does (`showContextMenu` in [`ui/ToolbarCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolbarCoordinator.java)). In Termina the list of the Message Log has no menu ([`ui/MessageLogWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/MessageLogWindow.java)), and neither has Mirada's ([`ui/MessageLogView.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/MessageLogView.java)). The Debug Log windows of Editora, Torrenta, Termina and Mirada show the log in a read-only `TextArea` and give it no menu (Editora's [`ui/DebugLogWindow.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/DebugLogWindow.java), Torrenta's [`ui/DebugLogWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/DebugLogWindow.java), Termina's [`ui/DebugLogWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/DebugLogWindow.java) and Mirada's [`ui/DebugLogWindow.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/DebugLogWindow.java)). In Torrenta the rows of the files and peers menus, Ban Peer among them, run handlers that no command reaches ([`ui/DetailPane.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/DetailPane.java)). In Modula the Rename… and Remove rows of a preset chip's menu ([`ui/PresetBar.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/PresetBar.java)) run no command, and its command list has neither ([`ui/RadioPane.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/RadioPane.java), `commands`). - **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 (code):* the code that opens a right-click menu closes the one already showing before the next appears, in every window: the app keeps one menu and shows it again at the new place, or hides the showing menu in the handler of the press or the request that opens the next. Menus that each row or cell owns, with nothing to close the one shown last, fail. A test that right-clicks another row with a menu open and finds one menu showing is the surest evidence. - *Reference:* Editora [`ui/ContextMenuDismissal.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ContextMenuDismissal.java) closes every open right-click menu on the press that opens the next ([`ContextMenuDismissalFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ContextMenuDismissalFxTest.java)), and its toolbar keeps one menu and shows it again, so a second right-click on the bar moves it ([`ToolbarCoordinator`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ToolbarCoordinator.java), [`ToolbarContextMenuDismissFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ToolbarContextMenuDismissFxTest.java)); Termina's [`ui/OneMenu.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/OneMenu.java) closes every other menu as one starts to show ([`OneMenuTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/ui/OneMenuTest.java)), and the app template's [`RightClickMenusFxTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/ui/RightClickMenusFxTest.java) (`aRightClickOnAnotherRowLeavesOneMenu`) holds it for a list's rows. Modula's [`RadioPane`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/RadioPane.java) hides its own previous menu before it shows a new one, but Modula doesn't meet the rule yet: each preset chip owns a menu ([`ui/PresetBar.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/PresetBar.java)), and no code closes the pane's menu when a chip's opens: the pane's press filter skips the right button, and the chip answers the menu request before the pane's handler can. - **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 (code):* the app installs a mouse-press filter, on every window or on the scene of each window that has a right-click menu, that hides a showing right-click menu on a press outside the menu, a press inside its owner control included, and does not consume the press; a press in another window of the app closes the menu too, by the same filter or by the stock auto-hide. A right-click menu left with the stock auto-hide alone fails, since JavaFX ignores a press on the owner node. A test that presses inside the owner control and in another window and finds the menu closed is the surest evidence. - *Reference:* Editora [`ContextMenuDismissal.install()`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ContextMenuDismissal.java), called once in [`App`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java) at startup for every current and future window; [`ContextMenuDismissalFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ContextMenuDismissalFxTest.java), and for the toolbar's menu, whose owner is the whole bar, [`ToolbarContextMenuDismissFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ToolbarContextMenuDismissFxTest.java). The app template installs the same class at start-up. Mirada turns auto-hide off on its three menus and closes them from a press filter on the scene of each window that has one ([`ui/Popups.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Popups.java), `closeOnPressOutside`). Termina's terminal view hides its menu from its own press filter, but its tab menus have the stock auto-hide alone ([`ui/TerminalWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java)); so have Modula's preset chips ([`ui/PresetBar.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/PresetBar.java)), beside a pane menu that its own filter closes, and every right-click menu in Torrenta. nux has no right-click menu. - **MENU-08 · MUST.** Escape closes a right-click menu and focus goes back where it was. In a terminal app the Escape that closes the menu 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 (the right-click menus' [Spec](https://pauta-project.dev/6.0.0/menus/#spec)); Termina's `onKeyPressed` filter hides the menu and consumes the key ([`TerminalView`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalView.java)). - **MENU-09 · MUST.** The Menu key and `Shift+F10` open the right-click menu of the selected row, scrolled into view first, so every row action a mouse can reach the keyboard can too. In a view with no rows (an editor, a terminal, an image) they open the focused view's menu. The chord is the same on macOS, where keyboards have no Menu key: `Shift+F10`, with no `Cmd` form. - *Why:* those keys arrive at the focused control, not at a row's cell, so a menu installed on cells never saw them. - *Check (code):* each list, tree or table whose rows have a right-click menu answers the keyboard's request (JavaFX's `ContextMenuEvent` with `isKeyboardTrigger()`, which it raises for both keys, or a key handler of the app's own for the Menu key and `Shift+F10`) by scrolling the selected row into view and showing that row's menu anchored to the row; a view with no rows shows its own menu for the same keys; and no branch gives macOS another chord. A test that sends the request to a tree and a list and finds the selected row's menu, anchored to that row, is the surest evidence. - *Reference:* Editora [`RowContextMenu.install(tree)`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/RowContextMenu.java), [`RowContextMenuFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/RowContextMenuFxTest.java): it answers the request JavaFX raises for those keys (`ContextMenuEvent.isKeyboardTrigger`). Termina's [`ui/ViewKeys.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/ViewKeys.java) and Mirada's [`Popups.isMenuKey`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Popups.java) read the key press themselves, the same on every OS. One of Editora's keymaps gives the chord to a command as well: IntelliJ's binds `S-f10` to `run.rerun` ([`keymaps/intellij.json`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps/intellij.json)), a clash [`RowContextMenuFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/RowContextMenuFxTest.java) does not cover: it raises the request itself and presses no key. The app template's [`ui/RowContextMenu.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/RowContextMenu.java) answers the same request for a list's rows ([`RightClickMenusFxTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/ui/RightClickMenusFxTest.java), `theMenuKeyOpensTheSelectedRowsMenuAtThatRow`). - **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):* in an editor, select a word, right-click elsewhere and paste: the text lands at the click; then right-click inside a selection and copy: the selection is what was copied. In a list, select one row and right-click another: the menu that opens is the clicked row's, and its actions act on that row. An app with no editor is judged on its lists alone. - *Reference:* Editora [`editor/ContextMenuTarget.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/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):* a menu that exists once per open file is not built with the file: its items are created in the handler of its first request, and an on-showing handler sets their labels, enablement and visibility and then collapses the separators (Editora's `LazyContextMenu.of(build)`). - *Reference:* Editora [`ui/LazyContextMenu.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/LazyContextMenu.java), [`LazyContextMenuFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/LazyContextMenuFxTest.java). A read-only console's menu is just Select All and Copy, both disabled while it is empty ([`ConsoleContextMenu`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ConsoleContextMenu.java)). - **MENU-12 · SHOULD.** A destructive row is styled as dangerous, its text in `-color-danger-fg` (Editora's style class for it is `danger`). What the action does before it destroys anything is not this rule's: the [Confirm dialog](https://pauta-project.dev/6.0.0/templates/confirm-dialog/) rules hold it ([CONF-01](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-01), [CONF-03](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-03): it asks first with a button that names it, or is undoable). - *Check (code):* rows that delete, discard or reset carry the style class that colors their text `-color-danger-fg` (Editora's `danger`). Whether the action asks first is judged under CONF-01 and CONF-03, not here. - *Reference:* Editora `.menu-item.danger` in [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css), [`ui/BranchPopup.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/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 (code):* the terminal view decides whether to show its menu from the mouse mode, Shift and the trigger: a right-click while a program has the mouse goes to the program unless Shift is held, and a request from the keyboard always shows the menu. A test of that decision is the surest evidence. - *Reference:* Termina's [`TerminalView.shouldShowMenu`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalView.java), [`ContextMenuContentionTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/ui/ContextMenuContentionTest.java). ## Tray and background (TRAY) https://pauta-project.dev/6.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. **Applies to:** an app whose work goes on without its window, as Torrenta's, Modula's and nux's does. ### The icon and its menu - **TRAY-01 · MUST.** The tray is a StatusNotifierItem on Linux, with no AWT fallback, and AWT's `SystemTray` on Windows and macOS. The app creates it on a background thread, never on the FX thread, and no sooner than the code that shows the main window, so the first frame never waits for the tray. - *Why:* D-Bus and AWT can block, and neither is worth a stalled first frame. On Linux AWT's tray is the XEmbed one, which GNOME dropped in 3.26 and Wayland never had, so there is nothing worth falling back to. - *Check (code):* on Linux the code that creates the tray makes the StatusNotifierItem or reports that there is no tray, and no branch of it falls back to AWT's tray (Torrenta's `Trays.create`, which makes an `AwtTray` off Linux only); on Windows and macOS it makes the AWT `SystemTray` icon; and the main window runs it on a background thread that it starts as it shows itself, or later. - *Reference:* Torrenta [`tray/Trays.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/tray/Trays.java) (`create`) and [`MainWindow.installTray`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java), which `show` calls and which starts a `tray-init` thread; the [Spec](https://pauta-project.dev/6.0.0/tray-and-background/#spec) table. Modula and nux don't pass yet: on Linux their `Trays.create` falls back to `AwtTray` when `SniTray` fails (Modula [`tray/Trays.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/tray/Trays.java), nux [`tray/Trays.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/tray/Trays.java)). ### Behavior - **TRAY-02 · MUST.** An app that lives behind a tray icon is fully usable when no icon comes up. No icon is a normal outcome (stock GNOME has no StatusNotifier host), not an error, and the main window then says in its status line why there is none and that closing the window quits the app. - *Why:* the bug they actually hit is silence: the box says close to tray, and closing quits. - *Check (code):* when the attempt to create the tray returns none, the code sets the main window's status message (the echo area of its status bar, where it has one) to the reason and to the fact that closing the window quits; and the tray's menu holds no action the window lacks. - *Reference:* Torrenta [`MainWindow.installTray`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java) ("No tray icon (…); closing the window quits Torrenta", `status.noTray`); Modula's status says closing the window will quit it ([`RadioPane.reportNoTray`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/RadioPane.java)). nux doesn't pass yet: when no tray comes it shows the window, if it was hidden, and says nothing ([`TrayController.onCreated`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/app/TrayController.java)). - **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`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java), Modula's `installCloseBehaviour`, nux's [`TrayController.closeHidesWindow`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/app/TrayController.java) and `updateImplicitExit`. - **TRAY-04 · MUST.** The tray's Quit runs the app's one quit method ([WIN-13](https://pauta-project.dev/6.0.0/window-shell/#win-13)), and a quit ends the program with the window showing or hidden to the tray: the close handler never takes a quit for a close and hides the window, and the method exits outright, since closing the last window no longer does ([TRAY-03](https://pauta-project.dev/6.0.0/tray-and-background/#tray-03)). - *Why:* a close hides a tray app's window, so a quit that goes through a close leaves the program running behind its icon. The tray's Quit also arrives while a dialog may be open, and quitting from inside a nested event loop aborted the JVM, which is why the quit method closes dialogs first. - *Check (code):* the tray's Quit callback runs the quit method on the FX thread; the method marks the quit, so the close handler doesn't hide the window, tears down when the window is already hidden, and calls `Platform.exit`. On macOS the app menu's and the Dock's Quit reach the method too ([WIN-13](https://pauta-project.dev/6.0.0/window-shell/#win-13)): JavaFX turns them into a close request on every window (`GlassStage.requestClosingAllWindows`), and a tray app that doesn't catch Glass's quit action hides to the tray instead of quitting. - *Reference:* Torrenta [`MainWindow.quit`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java) for the tray and File → Quit: it sets `quitting`, which the close handler reads, closes open dialogs and waits for their loops, then closes the window or, when it is hidden, shuts down directly. It doesn't catch macOS's Quit yet, so there Quit hides the window. Modula's tray Quit runs [`ModulaApp.quit`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ModulaApp.java) and nux's calls `Platform.exit` ([`App`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java)), as its `app.quit` command does; neither closes open dialogs first or catches macOS's Quit. - **TRAY-05 · SHOULD.** `--minimized` starts the app with no window in front, in one of two ways. With the tray setting on it comes up behind the icon: the window is not shown until the tray attempt has answered, and if the icon that was asked for does not come, the window is shown after all. With the tray setting off there is no icon to wait for, and the window starts minimized. - *Why:* a start at login can then never leave a program with no way back: a hidden window has its icon, and a minimized one is on the taskbar or in the Dock. A person who turned the tray off asked for the minimized window. A person who asked for an icon looks for the icon, so when none comes the window is what tells them, with the reason on its status bar ([TRAY-02](https://pauta-project.dev/6.0.0/tray-and-background/#tray-02)). - *Check (code):* with the tray setting on, a `--minimized` start leaves the window hidden until the tray attempt answers, and shows it when the attempt returns no tray; with the setting off it shows the window minimized and waits for nothing. - *Reference:* Torrenta [`MainWindow.show`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java) and `installTray`, which calls `showFromTray` when no icon comes. nux's [`App`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java) and [`TrayController.onCreated`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/app/TrayController.java) do the same with the tray setting on; with it off nux doesn't pass yet: it ignores the flag and shows the window. Modula has no `--minimized`. - **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 (code):* the code that turns start at login on or off writes or removes one entry for the OS it runs on, and keeps no setting of its own for it: the XDG entry with a quoted `Exec`, the installed launcher's `StartupWMClass` and `X-KDE-autostart-after=panel`; the LaunchAgent; the `Run` value. The box's state is read back from the entry, with `StartupApproved` on Windows, and start behind the tray icon adds `--minimized` to the entry's command. A test of each platform's entry, byte for byte, is the surest evidence. - *Reference:* Torrenta [`os/Autostart.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/os/Autostart.java), [`os/AutostartSpec.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/os/AutostartSpec.java), [`AutostartSpecTest`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/test/java/com/torrenta/os/AutostartSpecTest.java). nux's [`autostart/AutostartSpec.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/autostart/AutostartSpec.java) is the earlier version: the same three entries, without `X-KDE-autostart-after` and without reading `StartupApproved`. - **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`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/os/Autostart.java). - **TRAY-12 · MAY.** A dock badge: an app may put a figure of its own on the macOS dock icon through AWT's `Taskbar` and 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. The badge is cleared when there is nothing to show and has its own switch. Torrenta's is the download rate on the dock and a count on the launcher, cleared when nothing downloads. - *Check (code):* the badge is set through AWT's `Taskbar` on macOS and through the `LauncherEntry` signal on Linux, and not at all on Windows; the code clears it when there is nothing to show (in Torrenta, when nothing downloads); and a setting of its own turns it off. A test of the badge's state is the surest evidence. - *Reference:* Torrenta [`os/Badges.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/os/Badges.java), [`BadgeState`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/os/BadgeState.java), [`BadgeStateTest`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/test/java/com/torrenta/os/BadgeStateTest.java). - **TRAY-13 · SHOULD.** A second launch brings the hidden window forward: the [single-instance hand-off](https://pauta-project.dev/6.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`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java). - **TRAY-14 · SHOULD.** A tray makes AWT headful on Windows and macOS only, where the tray is AWT's ([TRAY-01](https://pauta-project.dev/6.0.0/tray-and-background/#tray-01)); on Linux the app stays headless with its tray on. [CLI-09](https://pauta-project.dev/6.0.0/command-line/#cli-09) holds the rule this is part of, for an app with a tray or without one: the whole list of uses that may make AWT headful, and that `main` decides it once, at start-up. Because it is decided once, a tray turned on later tells the user to restart ("restart to show the tray icon"), never that the tray is unsupported. - *Check (code):* the code that decides `java.awt.headless` at start-up counts the tray setting as a reason on Windows and macOS and never on Linux, and the code that creates the tray, finding AWT headless on Windows or macOS, reports that a restart will show the icon. A test of the decision per OS is the surest evidence. - *Reference:* Torrenta [`os/AwtUse.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/os/AwtUse.java) (`headful`, which `App.main` asks once with the tray, badge and handler settings), [`AwtUseTest`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/test/java/com/torrenta/os/AwtUseTest.java) (`awtIsHeadfulOnlyWhereSomethingAwtIsWanted`); [`Trays.usesAwt`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/tray/Trays.java) and [`TraysTest`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/test/java/com/torrenta/tray/TraysTest.java) for the tray alone, and `Trays.create`, which gives the restart reason (`tray.reason.restart`) when AWT was left headless. Modula and nux never set `java.awt.headless`, so AWT is headful on every OS. ### Notifications **Applies to:** every app that sends desktop notifications, with a tray or without one: Torrenta and nux for their own events, Editora and Termina for a program's OSC 9 and OSC 777. - **TRAY-09 · MUST.** Desktop notifications go through one notifier: `notify-send` on Linux, `osascript` with `display notification` on macOS, a PowerShell toast on Windows. On Linux an app may also fall back to `gdbus` against the freedesktop service where `notify-send` is missing; the rule does not ask for it. Each is a short program, and the text reaches the program as data (an argument, or an environment variable a fixed script reads), never as part of a script. It runs off the FX thread, and the call times out after ten seconds or less; a failure is logged and never breaks the app. - *Why:* text from a torrent name or a remote shell then cannot run anything. - *Check (code):* one class builds every notification's command line: `notify-send` on Linux, `osascript` on macOS, PowerShell on Windows. Each carries the title and the message as arguments or environment variables of their own, and the script it runs is fixed and never has the text concatenated into it. The program runs on a background thread with a timeout of ten seconds or less that kills it, and a failure is written to the app's log, never thrown further and never dropped: an exception from starting the program or waiting for it, a program that is not there to run, the timeout, and an exit code that is not zero. A test of each platform's command line is the surest evidence. - *Reference:* Torrenta [`automation/Notifiers.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/automation/Notifiers.java), [`ProcessNotifier`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/automation/ProcessNotifier.java), [`NotifierTest`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/test/java/com/torrenta/automation/NotifierTest.java) (it ships [`toast.ps1`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/resources/com/torrenta/automation/toast.ps1), which takes the title and message as parameters); on Linux it runs `notify-send` and has no fallback. It runs each on a virtual thread with a ten-second ceiling and reports a failure to its event log, the first of a session only: the ones after it are dropped ([`automation/Automation.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/automation/Automation.java), `notify`), so Torrenta doesn't meet the last clause yet. Termina's [`ui/DesktopNotifier.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/DesktopNotifier.java) builds its command lines as the rule asks on every OS: the text is an argument of `notify-send` and of `osascript` (a fixed `on run argv` script), a GVariant string for `gdbus`, and on Windows two environment variables that a fixed PowerShell script (`-EncodedCommand`) reads; the program is killed after five seconds and an exception from running it is logged ([`DesktopNotifierTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/ui/DesktopNotifierTest.java)). Termina doesn't meet the last clause in full yet: `post` logs nothing when it finds no tool to run (on Linux, neither `notify-send` nor `gdbus`), when it kills the tool at the timeout, or when the tool exits with an error. Editora's [`terminal/DesktopNotifier.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/terminal/DesktopNotifier.java) builds the same command lines with the same five seconds, but doesn't meet the rule yet: its `post` catches a failure and drops it, with nothing logged. Both fall back to `gdbus`, and so does nux. nux doesn't meet the rule on Windows yet: its [`service/Notifier`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/service/Notifier.java) has no PowerShell toast, and hands the notification to the tray, which shows AWT's balloon ([`tray/AwtTray.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/tray/AwtTray.java), `displayMessage`). Nor does it on macOS: it escapes the title and the message into an AppleScript string (`appleScriptEscape`) and passes the whole script to `osascript -e`. It logs no failure either: a tool that is missing or fails hands the notification to the tray, or to nothing. Its timeout is in the measure: it kills the tool after five seconds. - **TRAY-10 · MUST.** Desktop notifications are for what happened while the window was away: the app posts none for an event whose window, or whose tab, is the one in front. Each kind of event has a switch of its own, and where the app notifies of several kinds, most of the switches start off. - *Check (code):* the code that posts a notification first tests that the window, or the tab the event belongs to, is not the one in front; each notified kind of event has its own setting; and where the app notifies of several kinds, more of those settings default to off than to on. - *Reference:* Editora ([`ui/TerminalPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TerminalPanel.java)) and Termina ([`ui/TabMarks.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TabMarks.java)) relay a program's own OSC 9 and OSC 777 notifications, one event with one switch, and post nothing while that terminal is focused and in view. Torrenta notifies on added, finished, seeding done, error and updated, each with its switch and only *finished* on at first, and a Test button in Settings shows one now ([`automation/AutomationSettings.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/automation/AutomationSettings.java)); it posts them while its window has focus too ([`automation/Automation.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/automation/Automation.java)). nux has one switch for all its power events and a rule per UPS (all, critical or none), not a switch per event, and also posts while its window is in front ([`App`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java)). - **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. ## Settings (SET) https://pauta-project.dev/6.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. An app with one key table and no CUA keymap, which is a terminal app's own keymap ([KBD-09](https://pauta-project.dev/6.0.0/keyboard/#kbd-09)) or the built-in table of an app that ships no keymap files, binds the chord in that table. - *Check (code):* a registered command opens Settings, and the CUA keymap binds it to `Ctrl+,` (`C-,` in Editora's `cua.json`) and, on macOS, to `Cmd+,` (`Cmd-,` in `cua.mac.json`). In an app with one key table (a terminal app's `keymap.json` and `keymap.mac.json`, or a table in code), that table binds the two. - *Reference:* Editora `view.settings`, bound in [`keymaps/cua.json`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps/cua.json) and [`cua.mac.json`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/keymaps/cua.mac.json) (and in the VS Code and Sublime keymaps; IntelliJ's uses `C-M-s`). Termina, a terminal app, binds `settings` to `Shortcut+Comma` in its one keymap ([`keymaps/keymap.json`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/resources/com/termina/keymaps/keymap.json) and [`keymap.mac.json`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/resources/com/termina/keymaps/keymap.mac.json)). Torrenta and nux, which ship no keymap files, bind the same chord in code ([`ui/Chords.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/Chords.java); nux's [`App.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java), `Shortcut+Comma`). Modula doesn't yet: its Settings command has no chord ([`ui/RadioPane.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/RadioPane.java), `commands`). - **SET-02 · MUST.** The Settings window has a sidebar of pages with icons on the left, the open page on the right, and a search field on top. - *Check (by hand):* open Settings: the pages are listed in a sidebar on the left, each with an icon, the open page fills the right, and the search field sits above both. - *Reference:* Editora [`ui/SettingsWindow.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsWindow.java), [`ui/SettingsSidebarNav.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsSidebarNav.java), [`ui/SettingsIcons.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsIcons.java). - **SET-03 · MUST.** The Settings window's 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 (code):* the Settings search matches a query against each row's title, description, visible text, card or section heading, page name and keywords; its score puts a title hit above a description hit and a whole word above a word start; and it opens the page of the best match and hides every row, heading and card that does not match. A unit test that ranks a title hit above a keyword hit and a whole word above part of one is the surest evidence. - *Reference:* Editora [`ui/SettingsSearch.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsSearch.java), [`SettingsSearchTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/SettingsSearchTest.java) (`aTitleHitOutranksAKeywordHitAndAWholeWordOutranksPartOfOne`). Torrenta's search doesn't rank a whole word above part of one yet: its score looks only at where the text was found, title, description or keywords ([`ui/SettingsWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/SettingsWindow.java), `rank`). - **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. A setting that cannot apply until a restart says so on its own row. - *Check (code):* the Settings window has no Save or Apply button, and each control writes its setting and applies it when it changes; a text field commits its value on Enter and when it loses focus (Editora's `commitOnEnterOrBlur`), and a value that fails validation is marked and not written; and every setting the app reads only at startup (the language, the window's style) names the restart in its own row's text. - *Reference:* Editora [`SettingsWindow.commitOnEnterOrBlur`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsWindow.java); [`SettingsSyncPage`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsSyncPage.java)'s branch field marks an invalid branch. Rows that wait for a restart say so: Editora's interface language ("Applies after restarting Editora.", `settings.uiLanguage.note`), and Torrenta's tray icon, which on Windows and macOS "applies after restarting Torrenta" (`settings.general.trayIcon.desc`, in [`ui/SettingsWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/SettingsWindow.java)). nux doesn't yet: its Settings window writes nothing until its Save button is pressed, and has a Cancel beside it ([`ui/SettingsWindow.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/SettingsWindow.java)). - **SET-05 · SHOULD.** A setting changed in one window reaches every other open window of the app. - *Check (code):* every window reads its settings from one model the windows share, and a change to that model is announced to each open window, which applies it. An FX test that changes a setting in one window and finds it applied in the other is the surest evidence. - *Reference:* Editora: every window holds the same [`config/SharedConfig.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/SharedConfig.java), which announces each change (`onSettingsChanged`); [`CrossWindowSettingsFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/CrossWindowSettingsFxTest.java). ### Adding a setting touches five places - **SET-06 · MUST.** Every setting the Settings window shows has a palette command that flips the field or prompts for its value. A key that [SET-16](https://pauta-project.dev/6.0.0/settings/#set-16) keeps out of the UI has no row, and takes no command. - *Check (code):* list the settings the Settings window's rows change and the commands the palette lists; each setting has a command that flips it or prompts for its value. A row that only shows something, or runs an action, has no setting to give a command to. A test that fails on a row with no command is the surest evidence. - *Reference:* Termina [`ui/SettingCommands.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/SettingCommands.java), a command for each setting or the reason a row needs none ([`SettingCommandsTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/ui/SettingCommandsTest.java), `everySettingsRowHasACommandOrSaysWhyNot`), and Mirada [`ui/SettingsPages.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/SettingsPages.java), where every row names its command ([`SettingsPagesTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/ui/SettingsPagesTest.java), `everyPageHasRowsAndEveryRowAPaletteCommand`). Editora has its `view.toggle…` and picker commands ([`ui/WindowCommandRegistrar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowCommandRegistrar.java)) but not one for every setting yet: `terminalNotifications`, for one, is only a Settings row. Modula's palette changes one of its settings, the daylight theme ([`ui/RadioPane.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/RadioPane.java), `commands`), and nux's three: the tray metric, the notification rule and start at login ([`App.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java), `registerCommands`). ### Config folder and schema - **SET-07 · MUST.** Config lives in `~/.`, a folder in the user's home on Windows, macOS and Linux alike, unless `_CONFIG_DIR` or a command-line flag ([CLI-02](https://pauta-project.dev/6.0.0/command-line/#cli-02)) names another folder. A flag wins over the variable, since what is typed on the command line is the more specific instruction: `--config-dir` first, then `--dev`, then the variable. - *Check (code):* one resolver picks the folder from `--config-dir`, `--dev`, the environment variable and the default, with `--config-dir` first, `--dev` next, the variable after it and the default last, whichever of the two flags is typed first; and the default is `/.` on Windows, macOS and Linux alike: the resolver doesn't branch on the OS, or a test resolves the default as each OS and finds the same folder. - *Reference:* no app has all of it yet. Editora ([`App`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java) and [`ConfigManager.configDirFor`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/ConfigManager.java), [`ConfigDirTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/config/ConfigDirTest.java)), Termina ([`config/Settings.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/config/Settings.java), `defaultFile`) and the app template ([`config/ConfigDir.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/config/ConfigDir.java)) put `--config-dir` first and have one default for every OS, but the variable wins over `--dev`, which only changes the default. In Mirada either flag wins over the variable, but the two flags set one value and the one typed last wins, so `--config-dir X --dev` gives `~/.mirada-dev` ([`Launch.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/Launch.java), `parse`); and its default depends on the OS ([`settings/Settings.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/settings/Settings.java), `defaultFile` and `folder`): `~/Library/Application Support/Mirada` on macOS, `%APPDATA%\Mirada` on Windows, `~/.mirada` elsewhere. Torrenta has `--config-dir`, the variable and the default in that order and no `--dev` ([`store/ConfigDir.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/store/ConfigDir.java)). Modula and nux read a fixed `~/.modula` and `~/.nux`, with no flag and no variable. - **SET-08 · SHOULD.** Preferences live in one file and session state (where the window was, what was open) in another, and every other store has a file of its own. Editora's are `settings.json` and `workspace-state.json`. - *Check (code):* preferences and session state are separate files: the file that holds what the user chose in Settings holds no window geometry and no list of open items. - *Reference:* Editora [`config/ConfigManager.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/ConfigManager.java) (`SETTINGS_FILE_NAME`, `WORKSPACE_FILE_NAME`), [`config/WorkspaceState.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/WorkspaceState.java); Termina [`config/Settings.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/config/Settings.java), which writes the same two names and sorts each key into one of them (`isStateKey`). Torrenta and Mirada keep the window's bounds in their preferences file (`ui.window.bounds` and `window.bounds` in `settings.properties`), and the app template keeps them in `settings.json` ([`config/Settings.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/config/Settings.java), `window`). - **SET-09 · MUST.** Every config file the app writes and reads back carries a schema version, and each version has a `v → v+1` migration step. A purely additive field uses an identity step. Which files are config files is in [SET-22](https://pauta-project.dev/6.0.0/settings/#set-22); a plain list with one item to a line, such as a word list, has no shape to version and is exempt. - *Check (code):* the store of every config file ([SET-22](https://pauta-project.dev/6.0.0/settings/#set-22) says which files those are) declares a schema version (`SCHEMA_VERSION` in Editora), writes it into the file and reads it back, and the migrations hold one step for every version below the current one, an identity step where the version only added a field. - *Reference:* Editora [`config/migration/ConfigMigrations.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/migration/ConfigMigrations.java), [`ConfigSchema.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/migration/ConfigSchema.java) (one entry for each store), [`ConfigMigrationsTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/config/migration/ConfigMigrationsTest.java); its `dictionary.txt`, one word to a line, is the kind of list the rule exempts. Termina ([`config/ConfigJson.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/config/ConfigJson.java), for `settings.json` and `workspace-state.json`) and Mirada ([`settings/Migrations.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/settings/Migrations.java), for `settings.properties` and `bookmarks.properties`) do it too, and so does the app template for `settings.json` ([`config/Migrations.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/config/Migrations.java)), though not for its `sync/base.json`. Nor does Termina for the color schemes it imports: each is a file Termina writes whole, in a format of its own, and reads back at start (`themes/.properties`, [`theme/ThemeFile.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/theme/ThemeFile.java)), so a config file by [SET-22](https://pauta-project.dev/6.0.0/settings/#set-22), and it carries no version. Torrenta's files ([`store/Settings.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/store/Settings.java) and the other stores beside it) and Modula's ([`config/ConfigStore.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/config/ConfigStore.java): `settings.properties`, `presets.txt`, `schedules.txt`, each line a record with fields) carry no version, and nux writes `schema=1` into its file and never reads it ([`config/ConfigStore.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/config/ConfigStore.java), `format` and `parse`). - **SET-10 · MUST.** A config file whose schema version ([SET-09](https://pauta-project.dev/6.0.0/settings/#set-09)) is higher than the running build's is kept as a backup beside it (Editora names it `.v.bak`) and defaults load. - *Why:* an older build never clobbers a newer config. - *Check (code):* the load of each config file compares the file's schema version with the build's, and for a higher one keeps the file as a backup beside it and loads the defaults. A test that loads such a file and finds the backup beside it and the defaults loaded is the surest evidence. - *Reference:* Editora [`ConfigVersioningTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/config/ConfigVersioningTest.java) (`tooNewSettingsAreBackedUpAndDefaultsLoaded`). Termina ([`config/Settings.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/config/Settings.java)), Mirada ([`settings/ConfigFile.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/settings/ConfigFile.java), `newerBackupOf`) and the app template ([`config/ConfigStore.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/config/ConfigStore.java)) do the same, under the same name. Torrenta, Modula and nux read no version ([SET-09](https://pauta-project.dev/6.0.0/settings/#set-09)), so they cannot tell a newer file, and nor can Termina for an imported color scheme, which carries none. - **SET-11 · MUST.** 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 a backup (Editora names it `.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 (code):* the load clamps each value to its range as it reads it and puts the default in place of an unknown one; a file the parser cannot decode is kept as a backup and the defaults load; and the load catches what the parser throws besides an `IOException` (a malformed `\uXXXX` escape in a `.properties` file throws an `IllegalArgumentException`), so no file stops the start. A test that loads out-of-range numbers and an unparseable file of that kind is the surest evidence. - *Reference:* Editora [`config/migration/ConfigMigrations.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/migration/ConfigMigrations.java) (`keepCorrupt`), [`ConfigLoadProblemsTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/config/ConfigLoadProblemsTest.java) (`outOfRangeNumbersAreClampedOnLoad`, `anUnparseableFileIsReportedWithItsBackup`); Termina [`config/Settings.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/config/Settings.java), [`SettingsTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/config/SettingsTest.java) (`aMalformedEscapeNoLongerStopsTheAppStarting`); Mirada [`settings/ConfigFile.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/settings/ConfigFile.java), which moves a file that will not decode to `.corrupt.bak` ([`ConfigFileTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/settings/ConfigFileTest.java), `aFileThatWillNotDecodeIsKeptAsABackup`). Torrenta, Modula and nux keep no backup, and in Torrenta and nux a malformed escape stops the app from starting. - **SET-22 · MUST.** A config file is written whole or not at all: the app writes a temporary file beside it and moves that into place, so a crash mid-write never leaves a half-written file. A config file is any file the app writes as a whole and reads back as its state: the settings, the session state, a store of bookmarks or presets, what a sync engine keeps beside its clone. A file the app only appends to (a log, a ledger, a word list) is not one, and neither is a file in the working tree of a sync repository's clone, which Git holds a committed copy of and the next sync writes again. Nor is a file the app writes for one run and deletes at exit, such as one that tells another process where this run listens. - *Why:* without it, a crash or a full disk in the middle of a save leaves a file that will not decode, and the corrupt-file path of [SET-11](https://pauta-project.dev/6.0.0/settings/#set-11), a backup and then defaults, is what the person gets for it. - *Check (code):* every write of a config file as a whole (a store's save, an import, a sync engine's own state outside its clone) goes to a temporary file in the same folder and ends in a move onto the target (`Files.move`). `ATOMIC_MOVE` is the surest form; a move that only replaces the target passes too, since the statement asks for the temporary file and the move. An append to a log, a ledger or a list is not such a write, and neither is a write into a sync clone's working tree, nor the write of a file the app deletes when it exits. - *Reference:* Editora [`config/ConfigWriter.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/ConfigWriter.java) (`writeAtomicOrThrow`: a temporary file of its own beside the target, forced to disk, then moved; [`ConfigWriterTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/config/ConfigWriterTest.java), `atomicReplacementFailuresKeepThePreviousConfiguration`), which its settings and stores go through. Editora's `mcp-endpoint.json` is not a config file: its MCP server writes it for the run when it starts and deletes it when it stops, as the last window closes ([`mcp/McpServer.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/mcp/McpServer.java), `writeEndpointFile` and `stop`), and one that a crash left behind is deleted at the next launch (`reapStaleEndpoint`). Every other app's settings store does it too: Torrenta [`store/Settings.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/store/Settings.java) (`save`), Termina [`config/Settings.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/config/Settings.java) (`writeOne`, `moveIntoPlace`), Mirada [`settings/Settings.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/settings/Settings.java) (`write`), Modula [`config/ConfigStore.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/config/ConfigStore.java) (`writeAtomically`), nux [`config/ConfigStore.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/config/ConfigStore.java) (`save`) and the app template's [`config/ConfigStore.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/config/ConfigStore.java) (`writePending`). The template's [`config/ConfigImport.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/config/ConfigImport.java) (`apply`) doesn't yet: an import writes `settings.json` and the zip's other files in place. Nor does its [`sync/SyncEngine.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/sync/SyncEngine.java) (`write`) for `sync/base.json`, the merge base it keeps beside the clone and reads back at the next sync. Termina's [`sync/SyncEngine.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/sync/SyncEngine.java) and Torrenta's [`sync/SyncEngine.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/sync/SyncEngine.java) write in place only inside the clone, and keep their merge base as a Git ref (`refs/termina/base`, `refs/torrenta/base`). - **SET-12 · MUST.** Export configuration writes a timestamped `.zip` of the config folder; Import restores from one. - *Check (code):* the export command writes a `.zip` that carries the time of the export in its name and the config folder's files among its entries, and the import command reads such a zip and restores its files. A test of each is the surest evidence. - *Reference:* Editora [`config/ConfigExporter.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/ConfigExporter.java), [`config/ConfigImport.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/ConfigImport.java), [`ConfigExporterTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/config/ConfigExporterTest.java) (`zipNameDropsLeadingDotAndEmbedsVersionUserTime`, `exportZipsAllFilesWithRelativeEntries`), [`ConfigImportTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/config/ConfigImportTest.java) (`theTickedPartsReplaceTheirsHereAndNothingElseChanges`: Editora's import restores the parts the user ticks). ### Secrets stay out of files - **SET-13 · MUST.** An app that stores a secret the user gave it (a password, a token, a key) puts none in a config file. Each goes 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. Where no keychain answers, as in a Linux session with no Secret Service, the secret is kept in memory for the session only and its row in Settings says so: it is never written to a file instead. A run with no window says so on standard error. A key or token the app generates itself is not such a secret: it may live in a file only the owner can read, outside the settings files (Torrenta's `keys/.key`). Whether a credential is kept from one session to the next is the app's to decide: one it keeps is this rule's, and one it only holds for the session, and asks for again in the next, is [SET-14](https://pauta-project.dev/6.0.0/settings/#set-14)'s. - *Check (code):* the rule covers an app that keeps a password, an API key or a token the user gave it from one session to the next; an app that keeps none is outside it. In an app it covers, no such secret is a field of the settings model or is written to any other file; reads and writes go through the secret store, and every caller reaches it from a background thread, never from a handler on the FX thread; the store's fallback, for when no keychain answers, holds the secret in memory and writes no file, and the secret's row in Settings says when it is kept for the session only, as a line on standard error does in a run with no window. A key or token the app generates is not judged as such a secret where it is in a file of its own, outside the settings files, that the app makes readable by its owner alone (owner-only permissions, where the file system has them). - *Reference:* Editora [`secrets/SecretStore.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/secrets/SecretStore.java), [`config/ApiKeyVault.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/ApiKeyVault.java). Editora doesn't yet: [`Settings`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/Settings.java) keeps the AI keys as a fallback for when no keychain answers, and saving a key from Settings writes the keychain on the FX thread. Its Settings row does say which of the two holds the key. The bearer token Editora's MCP server generates is in a file of its own for the run, `mcp-endpoint.json`, made owner-only where the file system has POSIX permissions and deleted when the server stops ([`mcp/McpServer.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/mcp/McpServer.java), `writeEndpointFile`), which the rule allows. Torrenta uses no keychain: its proxy password and the password of its Remote access certificate file (`proxy.password` and `webapi.httpsPassword` in `settings.properties`, [`store/Settings.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/store/Settings.java)), its Torznab keys (`search-providers.json`) and its remote-profile passwords (`profiles.json`) are in plain text in its config folder; of its Remote access password it keeps only a hash. The keys Torrenta generates for the updatable torrents it publishes are where the rule allows: a file each, outside the settings files and owner-only where the file system has permissions (`keys/.key`, [`store/KeyStore.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/store/KeyStore.java)). Termina, Mirada and Modula store no secret, so the rule does not cover them: Termina's sync signs in through the user's own Git and `gh` ([`sync/SyncAccount.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/sync/SyncAccount.java)), and the other two ask for none. nux's one credential is for the session only, and so are the SSH passwords and passphrases Editora asks for ([SET-14](https://pauta-project.dev/6.0.0/settings/#set-14)). - **SET-14 · MUST.** An app that asks for a credential it does not keep from one session to the next holds it in memory for the session only and never writes it. Whether to keep a credential is the app's to decide: one it keeps is [SET-13](https://pauta-project.dev/6.0.0/settings/#set-13)'s, in the keychain and never in a config file, and this rule covers only one it does not keep. Work that needs such a credential waits until the user has signed in this session; do not "fix" that by writing the password to a file. - *Check (code):* for each credential the app asks the user for (a login, a password, a passphrase), find whether the app keeps it for the next session. One it keeps is [SET-13](https://pauta-project.dev/6.0.0/settings/#set-13)'s and is not judged here. One it does not keep is a field of a runtime object, absent from every config class, and no code writes it to a file. An app that asks for no credential, or keeps every one it asks for, is outside the rule. - *Reference:* nux's UPS login: the user name and password it asks for are two fields of a runtime object ([`app/CommandRunner.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/app/CommandRunner.java)), in no config class. Editora asks for an SSH password or a key's passphrase while a login runs ([`vfs/LoginPrompt.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/vfs/LoginPrompt.java)) and stores neither: a saved connection holds the host, the user and the key's path ([`config/ConnectionStore.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/ConnectionStore.java)). What an app keeps is [SET-13](https://pauta-project.dev/6.0.0/settings/#set-13)'s alone: Editora's AI keys, and Torrenta's proxy, Torznab and remote-profile secrets. Termina, Mirada and Modula ask for no credential. - **SET-15 · MUST.** An app with Settings Sync refuses a repository URL with a password or token in it, and says what to use instead: a Git credential helper or an SSH URL ([Settings Sync](https://pauta-project.dev/6.0.0/templates/settings-sync/)). A problem report's redaction is [DIAG-11](https://pauta-project.dev/6.0.0/diagnostics/#diag-11). - *Check (by hand):* paste `https://user:token@host/repo.git` as the sync repository: the page refuses it, with a message that says what to use instead. - *Reference:* Editora [`ui/SettingsSyncPage.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsSyncPage.java) (`settings.sync.repo.credentials`), which asks [`sync/SyncEngine.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/sync/SyncEngine.java) (`hasCredentials`) as the URL is typed, when the field commits and again at Connect. - **SET-16 · MUST.** 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. An option weakens security when it switches off a check or a question the app otherwise makes to protect the user; a feature, such as remote access or a proxy, is not such an option. - *Check (code):* no Settings row or command writes the key of an option that switches off a check or a question the app otherwise makes to protect the user, whichever of its values is the weaker one: on for nux's `tlsTrustAll`, off for a check the app makes by default. - *Reference:* nux's trust-all TLS (`tlsTrustAll` in [`config/Config.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/config/Config.java)), and Termina's paste confirmation, which only its config file turns off ([`SecurityOptionsTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/config/SecurityOptionsTest.java), `noControlOrCommandWritesAWeakeningOption`). Editora doesn't yet: *Require registry signature* for plugins is a Settings checkbox and the `plugins.toggleRequireSignature` command. ### Settings Sync (Git / GitHub) **Applies to:** an app with Settings Sync. - **SET-18 · SHOULD.** Settings Sync is set up by pasting a repository URL, or with **Create on GitHub** through the `gh` CLI. The account that can read the repository is pinned per clone, so machines with two GitHub accounts work. - *Check (code):* the Sync page takes a repository URL in a field and offers a Create on GitHub action that runs `gh`; and the sync code finds which of the signed-in GitHub accounts can read the repository, records it with the clone, and uses that account for the clone from then on. A test that remembers the first account that can read the repository and uses it without asking again is the surest evidence. - *Reference:* Editora [`sync/SyncAccount.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/sync/SyncAccount.java), [`SyncAccountTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/sync/SyncAccountTest.java), [`ui/SettingsSyncPage.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsSyncPage.java). - **SET-19 · SHOULD.** Settings Sync runs automatically (on change and at start) and on demand. Machine-local keys (window size, paths) never sync. - *Check (code):* a sync starts by itself after startup and after a local change, and a command starts one on demand (`sync.now` in Editora); and no machine-local key or file (window size, a path) is among those the sync sends to the repository. - *Reference:* Editora [`ui/SettingsSync.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsSync.java) (after startup, after a local change, on an interval, and `sync.now`), [`sync/SyncCategory.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/sync/SyncCategory.java); Torrenta [`sync/SyncKeys.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/sync/SyncKeys.java). - **SET-20 · SHOULD.** When Settings Sync finds one entry changed on both sides, *this machine wins*, and a backup is taken before any sync that replaces local files. - *Check (code):* the merge keeps this machine's value for an entry both sides changed, and the sync copies the local files to a backup before it replaces them. A merge test where both sides changed one entry is the surest evidence. - *Reference:* Editora [`sync/SyncMerge.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/sync/SyncMerge.java), [`SyncMergeTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/sync/SyncMergeTest.java). - **SET-21 · SHOULD.** Settings Sync shows its status as a pill in Settings and as echo messages; its failures go to the Message Log. - *Check (by hand):* point Sync at a repository that does not exist: the pill in Settings shows the failure, the echo area says it, and the Message Log keeps it. - *Reference:* Editora [`ui/SettingsSyncPage.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsSyncPage.java), [`SyncStatus`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SyncStatus.java). ## Diagnostics and support (DIAG) https://pauta-project.dev/6.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. Esc closes it; Clear empties it. What opens it, a click on the echo area, is [WIN-01](https://pauta-project.dev/6.0.0/window-shell/#win-01)'s to require; the [Message Log template](https://pauta-project.dev/6.0.0/templates/message-log/) has the rest. - *Check (code):* every message the echo area shows is added, with its time, to one log held in memory and never written to disk; the log drops its oldest entry past a fixed count and lists the rest newest first with `HH:mm:ss` times; and its window closes on Esc and has a Clear action that empties it. A test that records messages newest first, evicts the oldest past the cap, and clears is the surest evidence. - *Reference:* Editora [`ui/MessageLog.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MessageLog.java) ([`MessageLogTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/MessageLogTest.java)), [`ui/MessageLogPopup.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/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 a session file in the config folder, keeping the previous session's file so a crash is still visible next launch. Editora names the two `-session.log` and `-session.prev.log`. - *Check (code):* a handler on the root `java.util.logging` logger and the uncaught exception handler feed one bounded buffer in memory and a session file in the config folder, and at start the last session's file is kept under a second name before the new one is begun. Tests that bound the buffer and find the session file written and the previous one kept are the surest evidence. - *Reference:* Editora [`ui/DebugLog.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/DebugLog.java) ([`DebugLogTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/DebugLogTest.java), [`DebugLogSessionFileTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/DebugLogSessionFileTest.java)). - **DIAG-03 · MUST.** The Debug Log opens in a modeless window with Refresh, Copy, Clear, Export and Report a Problem. The window's find bar is [FIND-01](https://pauta-project.dev/6.0.0/templates/find-bar/#find-01). - *Why:* it is the only way to see logs in a packaged build. - *Check (code):* the Debug Log's window is a stage with no modality, so the main window keeps working while it is open, and it carries the five actions: Refresh, Copy, Clear, Export and Report a Problem. - *Reference:* Editora [`ui/DebugLogWindow.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/DebugLogWindow.java). Termina's, Mirada's and the app template's windows have the five actions too; Torrenta's has no Export ([`ui/DebugLogWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/DebugLogWindow.java)). Modula and nux have no Debug Log ([DIAG-02](https://pauta-project.dev/6.0.0/diagnostics/#diag-02)). - **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 posts an error to the echo area, and opens no dialog. - *Reference:* Editora [`DebugLog.install()`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/DebugLog.java) for the install and the log. The echo message is posted by Termina ([`ui/WindowManager.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/WindowManager.java), through `DebugLog.onUncaught`), the app template ([`ui/Startup.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Startup.java)) and Mirada ([`App.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/App.java), `uncaught`). Editora's handler and Torrenta's ([`ui/DebugLog.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/DebugLog.java)) log the exception but do not yet post one. - **DIAG-05 · MUST.** The **update check** reads GitHub `/releases/latest`. The automatic check runs once per app session (not per window), at most once a day, and starts at least three seconds after the first frame ([PERF-15](https://pauta-project.dev/6.0.0/performance/#perf-15)); a check the user asks for ([DIAG-10](https://pauta-project.dev/6.0.0/diagnostics/#diag-10)) runs when asked. It never downloads or installs anything by itself. - *Check (code):* the code that starts the automatic check waits for the first frame and then a delay of three seconds or more before it asks GitHub's `/releases/latest` for the app's repository (Editora's `AfterFirstPaint`, then a pause of five seconds); it asks once for the whole process, however many windows open, and not at all when the last check, whose time the app keeps from one session to the next, was less than a day ago, or when the setting is off ([DIAG-10](https://pauta-project.dev/6.0.0/diagnostics/#diag-10)); and what it does with the answer is show it: no code downloads or installs a release. A test that asserts the wait, the one check a session and the two skips is the surest evidence. - *Reference:* Editora [`update/UpdateCheck.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/update/UpdateCheck.java), [`ui/UpdateCheckScheduler.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/UpdateCheckScheduler.java) ([`UpdateCheckSchedulerTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/UpdateCheckSchedulerTest.java), `waitsForTheFirstPaintThenTheDelayThenStampsAndChecks` and `onlyOnceASessionAndNotWhenOffOrNotDue`), [`ui/UpdateCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/UpdateCoordinator.java); Editora waits five seconds (`UpdateCheckScheduler.DELAY`). Termina ([`App.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/App.java), three seconds after its first frame), Mirada ([`update/UpdateCoordinator.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/update/UpdateCoordinator.java), `scheduleStartupCheck`, five seconds) and the app template ([`ui/UpdateCoordinator.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/UpdateCoordinator.java), started from [`ui/Startup.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Startup.java) after the first paint, five seconds) wait the same way. Three apps don't wait yet: Torrenta starts its check as soon as its engine is ready ([`ui/MainWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java), `maybeCheckForUpdates`), and Modula ([`ModulaApp.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ModulaApp.java), `checkForUpdates`) and nux ([`App.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java), `maybeCheckForUpdates`) start theirs inside `start()`. - **DIAG-09 · MUST.** When the update check ([DIAG-05](https://pauta-project.dev/6.0.0/diagnostics/#diag-05)) finds a newer version, the status bar says so, naming the version and linking its release. About's line for the last check is [ABOUT-02](https://pauta-project.dev/6.0.0/templates/about/#about-02). - *Check (code):* when a check finds a newer version, the app shows a notice in the status bar that names that version, and the notice, or a link beside it in the bar, opens that release's page (Editora's `UpdateCoordinator` shows a status-bar segment whose click opens the release). - *Reference:* Editora [`ui/UpdateCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/UpdateCoordinator.java). Mirada ([`ui/StatusBar.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/StatusBar.java)) and the app template ([`ui/StatusBar.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/StatusBar.java)) show a link in the bar, and Torrenta a badge there that opens the release ([`ui/MainWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java), `updateBadge`). Termina and Modula don't link the release yet: their status message names the version and nothing in the bar opens it (Termina's `status.updateAvailable`, posted from [`ui/WindowManager.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/WindowManager.java); Modula's [`ui/RadioPane.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/RadioPane.java), `setAvailableUpdate`). nux doesn't meet it either: it has no status bar, and shows a button in its toolbar that opens the release ([`App.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java), `refreshUpdateNotice`). - **DIAG-10 · MUST.** **Check for Updates** runs the update check ([DIAG-05](https://pauta-project.dev/6.0.0/diagnostics/#diag-05)) by hand, as a command in the palette and in the Help menu, where the app has a Help menu (the Help menu of a menu bar, or a Help submenu of the app's main menu, which [WIN-14](https://pauta-project.dev/6.0.0/window-shell/#win-14) defines), and Settings has an off switch for the automatic check. - *Check (code):* the command (`help.checkForUpdates` in Editora) is registered and, in an app with a Help menu, listed there, and the scheduler skips the automatic check while the setting is off. - *Reference:* Editora [`ui/MenuBarModel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarModel.java) (`help.checkForUpdates`), [`ui/SettingsWindow.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsWindow.java) (`settings.checkForUpdates`), [`ui/UpdateCheckScheduler.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/UpdateCheckScheduler.java). Mirada lists the command in the Help submenu of its main menu ([`ui/TitleBar.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/TitleBar.java), `help`) and in the Help menu of its macOS menu bar. nux, which has no menu bar, registers the command for its palette (`app.checkUpdates` in [`App.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java)). - **DIAG-06 · MUST.** **Report a Problem** is a command, listed in the Help menu where the app has one, that builds a report: the app's version, the OS, the runtime, a summary of the settings and the recent Debug Log. Its redaction is [DIAG-11](https://pauta-project.dev/6.0.0/diagnostics/#diag-11), its window [DIAG-12](https://pauta-project.dev/6.0.0/diagnostics/#diag-12) and the limit on the issue link's length [DIAG-13](https://pauta-project.dev/6.0.0/diagnostics/#diag-13). The same report from the command line, for when the app cannot start, is [CLI-05](https://pauta-project.dev/6.0.0/command-line/#cli-05). - *Check (code):* the command (`help.reportProblem` in Editora) is registered and, in an app with a Help menu, listed there, and the text it builds carries the app's version, the OS, the Java and JavaFX versions, a summary of the settings and the end of the Debug Log. - *Reference:* Termina [`report/ProblemReport.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/report/ProblemReport.java) ([`ProblemReportTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/report/ProblemReportTest.java), `itCarriesTheEnvironmentTheUsefulSettingsAndTheEndOfTheLog`), the app template's [`report/ProblemReport.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/report/ProblemReport.java) and Mirada's [`report/ProblemReport.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/report/ProblemReport.java). Editora's ([`report/ProblemReport.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/report/ProblemReport.java), `help.reportProblem` in [`ui/MenuBarModel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarModel.java)) and Torrenta's ([`report/ProblemReport.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/report/ProblemReport.java)) carry the system details and the last two session logs, and no settings summary yet. Modula and nux have no problem report. - **DIAG-11 · MUST.** An app's problem report ([DIAG-06](https://pauta-project.dev/6.0.0/diagnostics/#diag-06)) is **redacted** before it is shown: home paths, user names, e-mail addresses, credentials and tokens are replaced. - *Check (code):* the text the Report a Problem window shows has been through the redactor, and the redactor replaces home paths, user names, e-mail addresses, credentials in URLs and tokens. Redaction tests that cover each of the five are the surest evidence. - *Reference:* Editora [`report/Redactor.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/report/Redactor.java) ([`RedactorTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/report/RedactorTest.java)), applied in [`ProblemReport.assemble`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/report/ProblemReport.java) before the window gets the text. The other four apps with a report do it too: Termina ([`RedactorTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/report/RedactorTest.java)), Torrenta ([`RedactorTest`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/test/java/com/torrenta/report/RedactorTest.java)), Mirada ([`RedactorTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/report/RedactorTest.java)) and the app template ([`ReportTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/report/ReportTest.java), `redactsPrivateDetails`). - **DIAG-12 · MUST.** The Report a Problem window shows the report in a field the user can edit. Its submit action copies the report, as edited, to the clipboard and opens a GitHub issue prefilled from the repository's `bug_report.yml` form. Nothing is uploaded: the user submits the issue. - *Check (code):* the window's report field is editable; its submit action puts the field's text on the clipboard and opens a new-issue link that names `bug_report.yml` as its template and carries the report in the form's fields; and the report's code opens that link in the browser and makes no network request of its own. - *Reference:* Editora [`ui/ReportProblemWindow.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ReportProblemWindow.java) ([`ReportProblemWindowFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/ReportProblemWindowFxTest.java), `theEditedReportIsCopiedAndFilledIntoTheIssue`), [`ProblemReport.issueUrl`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/report/ProblemReport.java). Termina's [`ui/ReportProblemWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/ReportProblemWindow.java), Torrenta's [`ui/ReportProblemWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/ReportProblemWindow.java), Mirada's [`ui/ReportProblemWindow.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/ReportProblemWindow.java) and the app template's [`ui/ReportProblemWindow.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/ReportProblemWindow.java) do the same. The five differ in one thing the rule does not ask. Only Termina sends everything as the user left it: its environment block (version, runtime, OS) is a second editable field. The other four fill the form's environment field from the block as the app built it, whatever the user edits: Editora and Torrenta show the block at the top of the editable report, Mirada shows it as a label, and the app template does not show it. - **DIAG-13 · MUST.** When the issue link that Report a Problem prefills ([DIAG-12](https://pauta-project.dev/6.0.0/diagnostics/#diag-12)) would be longer than 7,500 characters, the report stays out of the link: the form's report field asks the user to paste the report from the clipboard, where DIAG-12 has put it. - *Check (code):* the code that builds the issue link puts the report in the form's report field while the link stays within 7,500 characters, and past that puts the paste hint in that field instead. A test that builds the link for a short report and for a long one is the surest evidence. - *Reference:* Editora [`ProblemReport.issueUrl`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/report/ProblemReport.java) (`MAX_URL_LENGTH`, 7500; [`ProblemReportTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/report/ProblemReportTest.java), `aShortReportGoesIntoTheIssueLinkItself` and `aLongReportLeavesThePasteHintInstead`). Torrenta ([`ProblemReportTest`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/test/java/com/torrenta/report/ProblemReportTest.java), `aShortReportGoesInTheLinkAndALongOneLeavesTheHint`), Mirada ([`ProblemReportTest`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/test/java/com/mirada/report/ProblemReportTest.java), `aLongReportAsksForAPaste`) and the app template ([`ReportTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/report/ReportTest.java), `issueLinkFillsTheFormOrFallsBackToTheClipboard`) do the same at the same limit. Termina has the limit (`MAX_LINK_LENGTH`; [`ProblemReportTest`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/report/ProblemReportTest.java), `aLongReportFallsBackToTheClipboard`) but not the hint yet: past it, its link leaves the form's report field empty, and only its own window says to paste ([`report/ProblemReport.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/report/ProblemReport.java), `link`; `report.paste`). - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/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 (code):* unsaved documents are written to snapshot files from a background thread while the user works, and the first window opened after a crash finds the abandoned session's snapshots and offers them back. A test that finds an abandoned session's snapshots and offers them to the first window only is the surest evidence. - *Reference:* Editora [`recovery/RecoveryService.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/recovery/RecoveryService.java) ([`RecoveryServiceTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/recovery/RecoveryServiceTest.java), [`CrashRecoveryFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/CrashRecoveryFxTest.java)). ## Command line and launch (CLI) https://pauta-project.dev/6.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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java), [`App.helpText`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java); [`AppArgsTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/AppArgsTest.java). - **CLI-02 · MUST.** `--config-dir ` uses another config folder, and `--dev` uses `~/.-dev`, a folder in the user's home on Windows, macOS and Linux alike. - *Check (code):* the config folder is resolved from both flags before anything reads `~/.`, and what `--dev` resolves to is `/.-dev` on Windows, macOS and Linux alike, with no branch on the OS. - *Reference:* Editora [`App.main`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java) ([`ConfigManager.configDirFor`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/ConfigManager.java), [`App.devFlag`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java)). - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java). - **CLI-04 · SHOULD.** An app that reopens what was open in its last session (documents, tabs, folders) takes `--no-session`, which starts it without them. - *Check (by hand):* launch with `--no-session` and find only the items given on the command line. - *Reference:* Editora [`App.helpText`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java). Mirada reopens nothing from its last session, so the rule does not cover it; it takes the flag and does nothing with it ([`Launch.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/Launch.java)). - **CLI-05 · MUST.** `--report` writes a redacted problem report to a file in the current folder, prints the file's path and opens the GitHub issue, without starting the GUI. Where the current folder can't be written, the file goes to the temp folder. - *Why:* the person who ran the command is looking at that folder, and has to attach the file. A report in the config folder is hidden from them, and one printed to the terminal is cut by its scrollback. - *Check (code):* `main` handles `--report` before `launch`: it writes the redacted report to a file in the current folder, or in the temp folder when that one can't be written, prints the file's path and opens the new-issue page. A test that runs the report command in a folder and finds the redacted report there, with its path printed, is the surest evidence. - *Reference:* Editora [`report/ReportCommand.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/report/ReportCommand.java) ([`ReportCommandTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/report/ReportCommandTest.java)); Torrenta's [`ReportCommand.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/report/ReportCommand.java) does the same. The app template and Mirada write theirs beside the settings, and Termina prints its report without writing a file ([`ReportCommand.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/report/ReportCommand.java)). - **CLI-12 · MUST.** An option the app does not know stops the launch: it names the option on standard error, says how to get help, and exits with status 2 before the GUI starts. That holds for an option with one dash as for one with two: it is never ignored and never taken for a file. Two kinds of argument are not unknown options. In an app that opens files named on its command line, a lone `-`, and every argument after `--`, is one of those files, whatever it starts with; that sentence does not cover an app that opens none. And the JVM options a launcher can leave among the program's arguments, `--add-exports`, `--add-opens` and `-p`, are skipped by name, each with its value, whether the value is the next argument or follows `=` in the same one (`--add-exports=…`): never refused, and the value never opened as a file. On Windows the message prints in the console, which is [CLI-11](https://pauta-project.dev/6.0.0/command-line/#cli-11). - *Why:* a mistyped `--config-dir` that is ignored starts the app on the real settings, which is the one thing the flag was typed to avoid. Status 2 is what a script tests for a usage error. `--` is how a file whose name starts with a dash is opened at all. A launcher's own option is not the user's mistake, so it must not stop the app; it is skipped by name because a parser that skips whatever it does not know is the one that ignores a typo. - *Check (code):* the parser `main` runs before the GUI refuses an option the app does not define, with two dashes or with one, and `main` then prints the option and how to get help on standard error and exits with status 2 before `launch`. In an app that opens files named on its command line, the parser takes a lone `-`, and a name that starts with a dash after `--`, for files; in an app that opens none, this part has nothing to find. And the parser skips `--add-exports`, `--add-opens` and `-p` with their values, in both forms a launcher writes (`--add-exports ` and `--add-exports=`), with no error and no file. A test that hands the parser each of these arguments is the surest evidence. - *Reference:* no app does all of it yet. The app template's [`cli/CommandLine.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/cli/CommandLine.java) comes nearest: it refuses an unknown option with one dash or two ([`Main.run`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/Main.java) prints the message and returns 2) and takes `-` and whatever follows `--` for files ([`CommandLineTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/cli/CommandLineTest.java)), but it refuses `--add-exports`, in either form, as it does any other. Termina's [`cli/CommandLine.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/cli/CommandLine.java) and Torrenta's [`cli/CommandLine.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/cli/CommandLine.java) refuse both kinds of unknown option with status 2, and the launcher's options with them. Torrenta, which opens the `.torrent` files and magnet links named on its command line, also refuses `-` and `--`: anything that starts with a dash and is not a magnet link. Termina opens no files from its command line, so that part of the rule does not cover it (it refuses `-` as an unexpected argument and `--` as an unknown option); the launcher's options are all it misses. Mirada's [`Launch.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/Launch.java) exits 2 on an unknown option with two dashes, `--add-exports` and `--add-opens` among them, and takes `-` and whatever follows `--` for files, but it takes a single-dash option, `-p` included, for a file too. Editora skips every option it does not know without a word, a lone `-` included, and has no `--` ([`App.fileTargets`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java)); that is how it gets past a leaked `--add-exports`, `--add-opens` or `-p`, whose value it opens only when a file of that name exists ([`AppArgsTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/AppArgsTest.java)). nux reads `--minimized` and `--screenshot=` and ignores every other argument ([`App.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java)), and Modula reads none ([`ModulaApp.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ModulaApp.java)); neither opens files, so what they miss is the refusal. - **CLI-13 · SHOULD.** The short flags are the same in every app: `-h` for `--help`, and both `-v` and `-V` for `--version`. - *Check (code):* the command-line parser takes `-h` for `--help`, and `-v` and `-V` for `--version`. - *Reference:* Termina's [`cli/CommandLine.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/cli/CommandLine.java) and Torrenta's [`cli/CommandLine.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/cli/CommandLine.java); the `--help` text of both lists `-h` and `-v` and leaves `-V` out. Editora takes `-h` and `-V` but not `-v`, the app template `-h` and `-v` but not `-V`, Mirada has no short flags, and Modula and nux take neither flag in any form. - **CLI-11 · MUST.** On Windows, `--help`, `--version` and `--report` print in the console they were typed in, and so does the message that refuses an unknown option ([CLI-12](https://pauta-project.dev/6.0.0/command-line/#cli-12)). A GUI launcher has no console, so the installer also carries a console launcher (jpackage's `win-console`) that runs the same entry point, or `main` attaches to the parent's console before it prints. - *Why:* without it, the three flags and a mistyped option print nothing from cmd or PowerShell, and the command line differs on one OS. - *Check (code):* the Windows jpackage configuration adds a launcher with `win-console=true` that runs the app's own main class and lets the three flags and an unknown option reach it, or `main` calls `AttachConsole` before printing. - *Reference:* Torrenta meets it with its second launcher, `torrenta-nox`: [`src/jpackage/torrenta-nox-windows.properties`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/jpackage/torrenta-nox-windows.properties) sets `win-console=true`, and its [`pom.xml`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/pom.xml) adds that launcher to the image on Windows (the `os-windows` profile picks the file), beside the main launcher and on the same module and main class. The launcher's own `arguments=--headless` applies only when the person gives none (its [`CLAUDE.md`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/CLAUDE.md) says so), so `torrenta-nox --help`, `--version`, `--report` and an option it does not know reach `main` as typed, and `main` refuses the unknown option and answers the three flags before it looks for `--headless` ([`App.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/App.java)). No other app has a `win-console` launcher or calls `AttachConsole`. Mirada's one Windows executable is its native image, copied over jpackage's launcher ([`native-app-image.sh`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/scripts/native-app-image.sh)); whether it prints in the console depends on how that image is linked, which Mirada's files do not say, and no Windows run has confirmed it. - **CLI-06 · SHOULD.** An app that opens files or folders (documents, images, a `.torrent`) opens the ones named as arguments on its command line, which its `--help` lists as `[files…]`. - *Check (by hand):* launch with two files and find both open, and run `--help` and find `[files…]` in its usage line. - *Reference:* Editora [`App.fileTargets`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java). Termina, Modula and nux open no files, so the rule does not cover them. ### Launch - **CLI-07 · MUST.** One instance runs per config folder, unless a launch asks for another with `--new-instance` ([CLI-03](https://pauta-project.dev/6.0.0/command-line/#cli-03)). Any other second launch hands its arguments, when it has any, to the running app over a local endpoint and exits. In an app that opens files, the `openFiles` Apple Events of macOS reach the running app too. - *Check (code):* the first launch on a config folder becomes the primary and listens on a local endpoint; a second launch without `--new-instance` sends it its arguments and exits; and, in an app that opens files, a handler for the macOS open-files event passes them to the running app (Editora's `MacOpenFiles`). A test that makes the first launch primary and delivers a second launch's arguments to it is the surest evidence. - *Reference:* Editora [`ipc/SingleInstance.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ipc/SingleInstance.java) ([`SingleInstanceTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ipc/SingleInstanceTest.java)), [`MacOpenFiles.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/MacOpenFiles.java). nux doesn't yet: its second launch asks the running app to show its window and exits, handing over none of its arguments ([`instance/SingleInstance.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/instance/SingleInstance.java), `NUX-SHOW`), and what lets a second instance run on the folder is a setting (`singleInstance`, read in `main` of [`App.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java)), not `--new-instance`. - **CLI-08 · SHOULD.** An advisory lock tells two processes on one config folder about each other. - *Check (code):* each process takes an advisory file lock in its config folder, and can tell that another process already holds one there. A test that takes the lock from two processes is the surest evidence. - *Reference:* Editora [`config/InstanceLock.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/InstanceLock.java) ([`InstanceLockTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/config/InstanceLockTest.java)). - **CLI-09 · SHOULD.** `main` sets `java.awt.headless=true` before any AWT class loads. Only these uses make AWT headful, in an app that has them: the tray on Windows and macOS, and on macOS the dock badge, the open-file handlers and Move to Trash. Linux never needs it. `main` decides once, before that point, which of them the settings ask for on this OS. What a tray app says when its tray is turned on after that is [TRAY-14](https://pauta-project.dev/6.0.0/tray-and-background/#tray-14). - *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):* `main` calls `System.setProperty("java.awt.headless", …)` before `launch` and before anything that loads an AWT class, and the value is `"true"` unless one of the listed uses is wanted on this OS: always on Linux, on Windows unless the tray is on, and on macOS unless the tray, the dock badge, an open-file handler or, in an app that trashes through AWT, Move to Trash is. - *Reference:* Editora [`App.main`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java), always headless, as Termina ([`App.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/App.java)) and the app template ([`Main.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/Main.java)) are. Torrenta [`os/AwtUse.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/os/AwtUse.java) (`headful`, which its `App.main` asks once: never on Linux, for the tray on Windows, and for the tray, the dock badge or the open-file handlers on macOS). Mirada [`App.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/App.java) (headless except on macOS, for Move to Trash: [`os/Trash.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/os/Trash.java), `headless`). Modula and nux never set the property, so AWT is headful on every OS, Linux included. - **CLI-10 · SHOULD.** An app that starts external tools (`git`, a compiler, `ffmpeg`) resolves them through the login shell's `PATH` on macOS and Linux. Windows has no login shell's `PATH` to ask for, and the one the app inherits is used there. - *Why:* a `.app` launched from Finder inherits a stripped `PATH`. - *Check (code):* on macOS and Linux, every process the app starts gets a `PATH` that includes the login shell's. An app that starts no external tool is outside the rule. - *Reference:* Editora [`process/ProcessRunner.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/process/ProcessRunner.java) (`augmentedPath`; on Windows its login-shell probe returns nothing and the inherited `PATH` is used). ## Internationalization (INTL) https://pauta-project.dev/6.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 at least six languages: English (the base), Spanish, Portuguese, French, Italian and German. - *Check (code):* the six `messages*.properties` files are in the app's `i18n` resources. - *Reference:* Editora [`src/main/resources/com/editora/i18n/`](https://github.com/adriandeleon/Editora/tree/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/i18n/Messages.java) (`LANGUAGES`, `available()`); [`MessagesTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/i18n/MessagesTest.java)'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 with the window 1024 px wide, open each window and Settings page, and find no row cut off. - *Reference:* Editora [`messages_de.properties`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/i18n/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. JavaFX falls back to whatever font the OS has, so without a bundled one the text looks different on each OS, and a minimal Linux install may have none. - *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 the catalog, by its key, through one lookup in one class (`tr("some.key")` in Editora's `Messages`). - *Check (code):* no source file passes a string literal in a text position: a control's constructor, `setText`, `setPromptText`, `setTitle`, a tooltip, a menu item or a command's label. Each takes its text from the catalog's lookup, which is one method of one class (Editora's `Messages.tr`). A test that scans the sources and fails on such a literal is the surest evidence. - *Reference:* Editora [`i18n/Messages.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/i18n/Messages.java). The tests that hold the rule are Torrenta's [`UiStringSweepTest`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/test/java/com/torrenta/i18n/UiStringSweepTest.java) (`noStringLiteralInATextPosition`) and nux's [`NoLiteralUiTextTest`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/test/java/com/nux/i18n/NoLiteralUiTextTest.java) (`userFacingTextGoesThroughTheCatalogue`). Editora's [`MessagesTest.everyLiteralKeyUsedInTheSourcesExists`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/i18n/MessagesTest.java) checks only that every key a `tr("…")` call names is in the base catalog, not that no literal reaches a control. - **INTL-08 · MUST.** Every catalog has every key of the base catalog, and no more, each with a non-empty value. - *Check (code):* compare each translated catalog's keys with the base catalog's: none is missing, none is extra, and no value is empty. A parity test that fails the build on any of the three is the surest evidence. - *Reference:* Editora [`MessagesTest.translationCatalogsHaveExactlyTheBaseKeySet`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/i18n/MessagesTest.java), `translationsAreNonEmptyAndDistinctFromKeys`. - **INTL-09 · SHOULD.** In a catalog value with a placeholder, a literal apostrophe is doubled; in a value without one, it is written once. Inside a `{0,choice,…}` limb ([INTL-12](https://pauta-project.dev/6.0.0/i18n/#intl-12)) that itself holds a placeholder, it is written four times; in a limb without one it is doubled, like the rest of the value. - *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. A choice limb that holds a placeholder is parsed a second time as a pattern of its own, and each pass halves the apostrophes. - *Check (code):* in every catalog, a value with a placeholder has no lone apostrophe and a value without one has no doubled apostrophe; a choice limb that holds a placeholder writes a literal apostrophe four times, and a limb that holds none writes it twice. Catalog tests that fail each of the four mistakes are the surest evidence. - *Reference:* Editora [`MessagesTest.aValueWithAPlaceholderNeverHasALoneApostrophe`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/i18n/MessagesTest.java), `aValueWithoutAPlaceholderNeverDoublesAnApostrophe`. The choice limbs are held by Torrenta's [`MessagesTest.apostrophesInsideChoiceLimbsAreQuotedForTheRightNumberOfPasses`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/test/java/com/torrenta/i18n/MessagesTest.java) (`diagnosis.unavailable` in its [`messages_fr.properties`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/resources/com/torrenta/i18n/messages_fr.properties) writes "n''''est" in a limb with `{1}`); Editora's test has no such case. - **INTL-10 · SHOULD.** Identifiers such as line numbers and ports use `{0,number,#}`, so they are not digit-grouped. - *Check (code):* in every catalog, a placeholder the code fills with an identifier (a line number, a port) carries the `number,#` format, as in `{0,number,#}`, and is never a bare `{0}`. A test that formats each identifier argument in every locale and fails on a grouped number is the surest evidence. - *Reference:* Editora [`MessagesTest.identifierArgumentsAreNeverDigitGrouped`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/i18n/MessagesTest.java). - **INTL-11 · SHOULD.** Technical identifiers stay untranslated: command ids, setting keys, file names and protocol names read the same in every language. The `--help` and `--version` text is [CLI-01](https://pauta-project.dev/6.0.0/command-line/#cli-01). - *Check (code):* compare each translated catalog with the base, key by key: a command id, a setting key, a file name or a protocol name in the base value appears, spelled the same, in the translated value. A made-up example name inside a value (`name.gpg`) is not an identifier, and may be translated. - *Reference:* Editora's catalogs ([`messages.properties`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/i18n/messages.properties) and its translations). - **INTL-12 · SHOULD.** A message with a count words it for the count, with a `{0,choice,…}` limb for each form the language needs: never "file(s)". - *Why:* "(s)" is English; other languages change more than one ending, and the translator can only get it right with the forms written out. - *Check (code):* no catalog value has a placeholder and `(s)`; a message with a count has a `{0,choice,…}` pattern with a limb for each form its language needs, and every such pattern parses. A catalog test that fails a value with a placeholder and `(s)`, and parses every `choice` pattern in every catalog, is the surest evidence. - *Reference:* Torrenta's `omni.targets.matching` in [`messages.properties`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/resources/com/torrenta/i18n/messages.properties), parsed in every language by [`MessagesTest.placeholdersMatchAcrossLanguagesAndEveryPatternParses`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/test/java/com/torrenta/i18n/MessagesTest.java). That test only parses the patterns: no app has the `(s)` test yet, and Editora's base catalog has 22 values with a placeholder and `(s)` (`find.replaced`, "Replaced {0} occurrence(s)"). - **INTL-13 · SHOULD.** A chord's modifiers read the same in every language: `Ctrl`, `Alt`, `Shift` and the macOS glyphs are never translated ("Ctrl", not "Strg"). - *Why:* the keymaps, the docs and the screenshots use one spelling, and a user who changes the language keeps the chords they learned. - *Check (code):* the code that writes a chord out takes its modifier names from constants, not the catalog, and no catalog value writes a modifier in another language: a catalog test looks for Strg, Umschalt, Maj, Mayús and Maiusc. - *Reference:* Editora [`command/ChordFormat.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/command/ChordFormat.java) writes chords with untranslated modifiers. Its catalogs do not hold the rule yet: they translate modifiers in prose ("Strg+D", "Mayús+Tab", "Maj+Entrée") and in the Project Map help's key names ([`messages_de.properties`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/i18n/messages_de.properties), `project.map.help.key.control=Strg`, read by [`ui/ProjectMapHelp.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ProjectMapHelp.java)). No app has the catalog test yet. - **INTL-14 · MUST.** The app starts in the language the user chose in its settings, where it offers that choice; with none chosen, in the system's language when it ships a catalog for it; otherwise in English. The locale that formats dates and numbers keeps the system's region: with no language chosen it is the system's locale whole, whatever language the menus are in, and with one chosen it is still the system's locale when that is the system's own language, and the bare language only when it is another. That locale is the JVM's default once the app has started: the app sets it wherever it is not the locale the JVM started with. The message catalog formats its values with it too, never with a locale of its own made from the bare language. - *Why:* `de-AT` collapsed to `de` writes an Austrian's numbers and dates the German way, and an English UI on a French system has no reason to change how its dates are written. Apps that settle this differently format the same date two ways side by side, and so does one app whose catalog formats a message's number with another locale than the rest of the window. - *Check (code):* the start-up code takes the stored choice, the system's locale and the catalogs the app ships and gives the language and the locale as the four cases ask: none chosen with a catalog for the system's language (the system's locale whole); none chosen without one (English, the system's locale kept whole); the system's own language chosen (its region kept); another language chosen (the bare language). It sets that locale as the JVM's default (`Locale.setDefault`) as it starts, wherever that is not the locale the JVM started with: an app that offers no language choice and ships no catalogs leaves the default alone, which is the system's locale whole, and meets this part. And the catalog's lookup formats a value with the default locale (`new MessageFormat(pattern)`, or `MessageFormat.format`), not with one it builds from the language code (`Locale.forLanguageTag`). A test that covers the four cases is the surest evidence. - *Reference:* Termina [`i18n/Messages.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/i18n/Messages.java) (`resolve`, `defaultLocale`, and `tr`, which formats with the default locale) with [`MessagesTest.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/test/java/com/termina/i18n/MessagesTest.java) (`automaticKeepsTheOperatingSystemsLocaleWhole`, `anExplicitChoiceMovesTheLocaleButKeepsAMatchingCountry`). Torrenta carries the same two functions and tests and sets the default from them ([`Startup.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/Startup.java), `language`), but doesn't meet the rule yet: its catalog formats every message with the bare language ([`i18n/Messages.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/i18n/Messages.java), `locale`), so a number inside a message loses the region the rest of the window keeps. nux's [`i18n/Messages.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/i18n/Messages.java) (`uiLocale`, [`UiLocaleTest`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/test/java/com/nux/i18n/UiLocaleTest.java)) keeps the region when the language is the system's, but with none chosen and no catalog for the system's language it sets bare English. Editora ([`App.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/App.java)) and Mirada ([`App.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/App.java)) set the default to the bare language every time, so the region is lost; Mirada's catalog formats with the bare language as well ([`i18n/Messages.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/i18n/Messages.java)). The app template resolves the language the same way and never sets the default locale: JavaFX's own strings stay in the system's language, and its messages are formatted with the bare language ([`i18n/Messages.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/i18n/Messages.java)). Modula ships no catalogs and offers no language choice, and leaves the JVM's locale as the system set it, which is the locale the rule asks for: it meets this rule, and its missing catalogs are [INTL-01](https://pauta-project.dev/6.0.0/i18n/#intl-01)'s. ## Command Palette (PAL) https://pauta-project.dev/6.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 a Command Palette, one in each main window, opened by the `palette.show` command. A Settings, About or log window needs none of its own. Its chords, `M-x` in the Emacs keymap and `Ctrl+Shift+P` (`Cmd+Shift+P` on macOS) in the others (`Ctrl+Shift+A` allowed in the IntelliJ keymap), are [KBD-05](https://pauta-project.dev/6.0.0/keyboard/#kbd-05). - *Check (code):* each main window builds one palette, and the command registered as `palette.show` opens it (in Editora the window controller builds one `CommandPalette`). A window that is not a main window (Settings, About, a log, a history or events window) is not judged. - *Reference:* Editora [`ui/CommandPalette.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CommandPalette.java), built once in [`MainController`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java). - **PAL-02 · MUST.** The palette lists every registered command, with its title and description ([KBD-03](https://pauta-project.dev/6.0.0/keyboard/#kbd-03)). - *Check (code):* the palette's rows come from the whole registry, filtered only by the query; a command that cannot run stays listed, grayed; each row shows its command's title; and the palette shows the description of the command under the cursor, in the row or in a line of the card. A palette that shows no description fails this rule; that every command has one is [KBD-03](https://pauta-project.dev/6.0.0/keyboard/#kbd-03)'s. - *Reference:* Editora [`CommandPalette.filter`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CommandPalette.java) (`registry.all()`), [`MessagesTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/i18n/MessagesTest.java); the page's [Spec](https://pauta-project.dev/6.0.0/templates/command-palette/#spec). Torrenta's, Modula's and nux's palettes don't yet. Torrenta's lists only the commands that can run now: `show` in [`ui/CommandPalette.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/CommandPalette.java) drops every disabled command, after `offeredCommands` in [`ui/MainWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java) has dropped what the engine cannot run and what Simple mode hides; and it shows no description, since its [`Command`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/Command.java) has none. Modula's leaves out one (`stereo`, while its control is disabled, in [`ui/RadioPane.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/RadioPane.java)), and its rows show a title and a shortcut, with no description ([`ui/CommandPalette.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/CommandPalette.java)). nux's lists its whole registry, and each row shows the title and the command's id, with no description: its commands have none ([`ui/CommandPalette.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/CommandPalette.java), `CommandCell`; [`command/CommandRegistry.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/command/CommandRegistry.java)). - **PAL-10 · SHOULD.** The palette is 620 px wide, its rows 36 px high with 8 visible before the list scrolls, at the default zoom ([WIN-12](https://pauta-project.dev/6.0.0/window-shell/#win-12)), and its field's prompt reads "Run command…", in words from the catalog (Editora's key for them is `palette.prompt`). - *Why:* the palette is the one window every app shares; a different width or prompt is the first thing a person moving between apps notices. - *Check (code):* the palette's width, row height and visible rows come from constants of these values, and its prompt is read from the catalog, where the English is "Run command…". The rule asks for the words, not for a catalog key. - *Reference:* Editora [`ui/CommandPalette.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CommandPalette.java) (`ROW_HEIGHT`, `VISIBLE_ROWS`), Torrenta, Termina and the app template's [`ui/Picker.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Picker.java). Mirada's [`ui/CommandPalette.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/CommandPalette.java) matches the three sizes and reads the same words from the catalog under another key, `palette.runCommandPrompt`. Modula's is 420 px with a literal "Type a command…", and nux's 540 px with a `palette.prompt` that reads "Type a command…". ### Behavior - **PAL-04 · SHOULD.** Every open starts with an empty query: the palette does not keep the last one, so it opens on the whole list ([PAL-02](https://pauta-project.dev/6.0.0/templates/command-palette/#pal-02)). - *Check (code):* `show` clears the field and filters on the empty query before the card appears. - *Reference:* Editora [`CommandPalette.show`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CommandPalette.java). - **PAL-05 · SHOULD.** Typing in the palette filters its list, and the first *enabled* match is selected. - *Check (code):* after each filter the palette selects the first row whose command can run, stepping over disabled rows at the top (Editora's `selectFirstEnabled`). A test that asserts it, with a disabled command at the top, is the surest evidence. - *Reference:* Editora [`CommandPalette.selectFirstEnabled`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CommandPalette.java), [`CommandPaletteDisabledFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/CommandPaletteDisabledFxTest.java). - **PAL-06 · SHOULD.** The active keymap's line and page chords move the selection, as do ↑ ↓ and Page Up/Down, which always work. In Editora they are the chords of its `nav.lineDown`, `nav.lineUp`, `nav.pageDown` and `nav.pageUp` commands, `C-n` and `C-p` among them in the Emacs keymap. Enter, or a click on an enabled row, runs the command. The palette closes first, then the command runs. - *Check (code):* the palette's key handler looks a press up in the active keymap and moves on the commands it binds for a line and a page up and down, not on fixed letters, and on ↑ ↓ and Page Up/Down whatever the keymap; the run path hides the card before it calls the registry, and does nothing on a disabled row. - *Reference:* Editora [`CommandPalette.runSelected`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CommandPalette.java), [`PickerKeys.resolve`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/PickerKeys.java), the only palette that asks the keymap. The others move on fixed keys: the app template's [`ui/Picker.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Picker.java) on the arrows, the page keys and `Ctrl+N` and `Ctrl+P` whatever the keymap; Termina's [`ui/PaletteKeys.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/PaletteKeys.java) and Mirada's [`ui/PaletteKeys.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/PaletteKeys.java) on a fixed table of Emacs chords beside them (`EMACS`: `C-n`, `C-p`, `C-v`, `M-v`); Torrenta's [`ui/CommandPalette.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/CommandPalette.java) (`onKey`) on the arrows and `Ctrl+N` and `Ctrl+P`, with no page keys; Modula's [`ui/CommandPalette.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/CommandPalette.java) and nux's [`ui/CommandPalette.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/CommandPalette.java) on the arrows alone. - **PAL-07 · SHOULD.** The active keymap's cancel chord, Esc or a click on the scrim cancels the palette, and focus returns to where it was. In Editora the chord is that of its `edit.cancel` command, `C-g` in the Emacs keymap. - *Check (code):* Esc, the chord the active keymap binds to the cancel command, and a press on the backdrop all hide the overlay, and hiding focuses the node that had focus before it opened. In an app with one key table (a terminal app's keymap, or the built-in table of an app that ships no keymap files), the chord is the one that table binds to a cancel command; where it binds none, Esc and the backdrop are all there is to test. - *Reference:* Editora [`PickerKeys`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/PickerKeys.java) (`isCancel`), [`OverlayHost`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/OverlayHost.java) (`previousFocus`), the only one that asks the keymap for the chord. `Ctrl+G` is fixed in the app template's [`ui/OverlayHost.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/OverlayHost.java) and in the `EMACS` table of Termina's [`ui/PaletteKeys.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/PaletteKeys.java) and Mirada's [`ui/PaletteKeys.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/PaletteKeys.java). Torrenta's, Modula's and nux's palettes cancel on Esc and on a press on the backdrop: none of the three apps has a keymap or a cancel command, so the chord asks nothing more of them. - **PAL-08 · SHOULD.** In the palette, a help chord opens the selected command's page in the docs on the website, for the running version. The chord is the first of `Ctrl+H`, `F1` and `Shift+F1` that the active keymap leaves free. It is the same on macOS, where `Ctrl+H` is the Control key and has no `Cmd` form (`C-h` in Emacs notation). - *Check (code):* the palette's help chord is the first of the three that the active keymap neither binds nor starts a longer chord with, and the URL it opens is built from the app's versioned docs address and the selected command's id. - *Reference:* Editora [`CommandPalette`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CommandPalette.java) ([`PickerKeys.freeChord`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/PickerKeys.java) over `C-h`, `f1` and `S-f1`; `docsUrl`), [`AppInfo.docsUrl`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/AppInfo.java). No other app's palette has a help chord yet. - **PAL-09 · SHOULD.** A live keymap switch re-renders the palette's key chips, its opener chip and its 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CommandPalette.java), called from [`SettingsReapply`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsReapply.java). ## QuickOpen picker (QOPEN) https://pauta-project.dev/6.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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/QuickOpen.java) (one generic class, instantiated more than seventy times), driven by [`PickerKeys`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/PickerKeys.java). Editora still asks with a `ChoiceDialog` in three places: the Git reset mode and the merge parent to revert against ([`ui/GitWindowCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/GitWindowCoordinator.java)), and the settings backup to restore ([`ui/SettingsResetFlow.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsResetFlow.java)). - **QOPEN-02 · SHOULD.** In an app with a picker (a card, opened by a command, for choosing one thing from a list by typing; a Command Palette that lists only commands is not one, and nor is a menu, a combo box or a field's completion list), 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. That it is never a `javafx.stage.Popup` is [KBD-07](https://pauta-project.dev/6.0.0/keyboard/#kbd-07). - *Check (code):* each picker shows its card through the overlay host the palette uses and sets a title and a prompt text. - *Reference:* Editora [`QuickOpen.setOverlayHost`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/QuickOpen.java), [`ui/OverlayHost.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/OverlayHost.java); the page's [Spec](https://pauta-project.dev/6.0.0/templates/quick-open/#spec). ### Behavior **Applies to:** an app with a picker: a card, opened by a command, for choosing one thing from a list by typing (a Command Palette that lists only commands is not one, and nor is a menu, a combo box or a field's completion list). - **QOPEN-03 · SHOULD.** A picker reads its items fresh on every showing and snapshots them, so typing filters a stable list. A source that answers late (an outline the language server has not returned yet) has the picker read its items again and keep the query (`reload()` in Editora). - *Check (code):* showing a picker calls its items supplier, and a late source makes the picker read the items again while it keeps the query (Editora's `show` and `reload`). - *Reference:* Editora [`QuickOpen.show`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/QuickOpen.java), [`QuickOpen.reload`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/QuickOpen.java). - **QOPEN-04 · SHOULD.** With nothing typed, a picker's 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):* a picker's empty query passes the items through unsorted and selects the value in force when the picker was given one (Editora's `setCurrentItem`). - *Reference:* Editora [`QuickOpen.filter`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/QuickOpen.java), `setCurrentItem`. - **QOPEN-05 · SHOULD.** Typing in a picker ranks its rows by fuzzy score, and ties keep the supplier's order, so rows do not shuffle under the cursor between keystrokes. - *Check (code):* the last tiebreak of the picker's sort is the supplier's index. - *Reference:* Editora [`QuickOpen.filter`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/QuickOpen.java). - **QOPEN-06 · SHOULD.** In a picker, the active keymap's line and page chords move the selection (in Editora, the chords of its `nav.lineDown`, `nav.lineUp`, `nav.pageDown` and `nav.pageUp` commands), 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 picker's key handler moves on the commands the active keymap binds for a line and a page up and down, and on the fixed keys whatever the keymap; the accept path hides the card before it calls the choice handler. - *Reference:* Editora [`QuickOpen`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/QuickOpen.java) (`hide()` then `onChoose`), [`PickerKeys.resolve`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/PickerKeys.java), the only picker that asks the keymap. The app template's [`ui/Picker.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Picker.java) moves on the arrows, the page keys and a fixed `Ctrl+N` and `Ctrl+P`, and has no `Ctrl+Home` or `Ctrl+End`; Mirada's picker is its palette, whose [`ui/PaletteKeys.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/PaletteKeys.java) carries a fixed table of Emacs chords (`EMACS`) beside the fixed keys. Termina, Torrenta, Modula and nux have no picker ([Uses](https://pauta-project.dev/6.0.0/templates/quick-open/#uses)). - **QOPEN-07 · SHOULD.** The active keymap's cancel chord, Esc or a click on the scrim cancels a picker, and the overlay host restores focus. In Editora the chord is that of its `edit.cancel` command, `C-g` in the Emacs keymap. A picker that previewed something undoes it. - *Check (code):* Esc, the chord the active keymap binds to the cancel command, and a press on the backdrop each hide the picker; hiding gives the focus back to the node that had it before the picker opened; and a picker that previewed a row runs its undo when it is dismissed without a choice. A test that asserts the undo is the surest evidence. - *Reference:* Editora [`OverlayHost`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/OverlayHost.java) (`previousFocus`; it cancels on [`PickerKeys.isCancel`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/PickerKeys.java)), [`QuickOpenPreviewFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/QuickOpenPreviewFxTest.java) (`dismissingRestoresWhatWasPreviewed`). `Ctrl+G` is fixed in the app template's [`ui/OverlayHost.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/OverlayHost.java) and in the `EMACS` table of Mirada's [`ui/PaletteKeys.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/PaletteKeys.java). - **QOPEN-08 · MAY.** A picker previews the highlighted row as the selection moves and undoes the preview on cancel (Editora's 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. Editora's theme and keymap pickers do not preview; they apply on Enter. - *Check (code):* a previewing picker previews from its selection listener once it is showing, never for the row it opens on, restores what it previewed when dismissed, and does not restore after a choice. A test that asserts it is the surest evidence. - *Reference:* Editora [`QuickOpen.setPreview(onPreview, onCancelled)`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/QuickOpen.java), [`QuickOpenPreviewFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/QuickOpenPreviewFxTest.java). - **QOPEN-09 · MAY.** A row action acts on the highlighted row and keeps the picker open (Editora's breakpoints picker enables or removes one), re-reading the list afterwards and keeping the cursor in place. - *Check (code):* a row action's key runs the action on the highlighted row without hiding the card, and the picker then reads its items again and keeps the cursor on that row. A test that asserts it is the surest evidence. - *Reference:* Editora [`QuickOpen.addRowAction(key, legend, action)`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/QuickOpen.java), [`QuickOpenPreviewFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/QuickOpenPreviewFxTest.java) (`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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/QuickOpen.java) ([`BreakpointsPicker`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/BreakpointsPicker.java)); [`NavigationCoordinator`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/NavigationCoordinator.java) (`status.nav.noRecentLocations`). - **QOPEN-11 · SHOULD.** The overlay host a picker shows in holds one card at a time; opening a picker replaces whatever card was up. - *Check (code):* showing a card in the overlay host removes the previous card before it adds the new one, and keeps the original focus owner (Editora's `OverlayHost.show`). - *Reference:* Editora [`OverlayHost.show`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/OverlayHost.java). - **QOPEN-12 · SHOULD.** A picker's relatives, the other list overlays an app has (in Editora the open-files switcher, the find-file field, the multi-select picker, and the branch and stash popups), move, accept and cancel with the same keys as the picker. - *Check (code):* each of those overlays moves, accepts and cancels on the keys the picker does: the moves of [QOPEN-06](https://pauta-project.dev/6.0.0/templates/quick-open/#qopen-06), Enter, and the cancel chord and Esc of [QOPEN-07](https://pauta-project.dev/6.0.0/templates/quick-open/#qopen-07). In Editora each maps its keys through the helper the picker uses (`PickerKeys`), which is one way to hold it. - *Reference:* Editora [`Switcher`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/Switcher.java), [`FileFinder`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/FileFinder.java), [`MultiSelectPicker`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MultiSelectPicker.java), [`BranchPopup`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/BranchPopup.java), [`GitStashPopup`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/GitStashPopup.java). ## Welcome page (WELC) https://pauta-project.dev/6.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 in tabs 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WelcomePane.java), [`MainController.addWelcomeTab`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java). - **WELC-02 · SHOULD.** An app whose window *is* its content, and can start with nothing in it (a list with no items, a viewer with nothing open), shows its own empty state in place of a Welcome page ([WELC-01](https://pauta-project.dev/6.0.0/templates/welcome/#welc-01)), 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. An app that always opens into content (a terminal with its shell, a radio, a monitor) has no empty state to judge. - *Reference:* Torrenta [`ui/Welcome.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/Welcome.java); Mirada [`ui/ViewerWindow.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/ViewerWindow.java) (`offerToOpen`, `viewer.emptyHint`); both are described under [In the apps](https://pauta-project.dev/6.0.0/templates/welcome/#in-the-apps). ### Behavior **Applies to:** an app with a Welcome page ([WELC-01](https://pauta-project.dev/6.0.0/templates/welcome/#welc-01)). - **WELC-03 · SHOULD.** The Welcome 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 where the app has a Help menu, in the place [DOCS-07](https://pauta-project.dev/6.0.0/documentation/#docs-07) gives it), and when a switch to another project leaves the tab strip empty (Editora's project swap). In an app that can start straight into one view, as Editora does for a standalone diff, that startup suppresses the page while its worker reads the files. - *Check (code):* those three paths open the one Welcome tab, and where the app has a Help menu, a row inside it runs `view.welcome`; a startup that goes straight to a view holds a flag that skips the page. - *Reference:* Editora [`MainController.addWelcomeTab`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java), `showWelcomeIfNoTabs`; [`WindowSessionCoordinator`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WindowSessionCoordinator.java) (`suppressWelcome`). Editora's menu row is in View, not in Help yet ([`MenuBarModel`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarModel.java)). - **WELC-04 · SHOULD.** Closing the last tab does not bring the Welcome page back. The empty content area shows its own quiet hint instead: the app's ways in, each with its chord (in Editora: Open File, Open Folder, Command Palette and Welcome Page), and takes focus so chords still reach the window. - *Check (code):* closing the last tab shows the hint in the empty content area, not the Welcome page, and gives it the focus; opening a tab hides it. A test that asserts it is the surest evidence. - *Reference:* Editora [`ui/EditorEmptyState.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/EditorEmptyState.java), [`EditorEmptyStateFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/EditorEmptyStateFxTest.java). - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WelcomePane.java). - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/config/RecentFiles.java), [`WelcomePane`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WelcomePane.java). - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WelcomePane.java); [`MainController`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java) (`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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WelcomePane.java). - **WELC-09 · SHOULD.** In an app with saved remote sites, they 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WelcomePane.java) (`remoteSites`, `welcome.remote`). - **WELC-10 · SHOULD.** The Welcome page's Customize links run the commands that pick the keymap and the app theme (Editora's are `keymap.select` and `theme.setAppTheme`); a change made there re-renders the page, chords included. - *Check (code):* the two Customize links run the app's keymap and theme picker commands through the registry, and applying a keymap or a theme refreshes the Welcome page. - *Reference:* Editora [`WelcomePane`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/WelcomePane.java) (`customizeRow`), refreshed by [`SettingsReapply`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsReapply.java). - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java). ## About window (ABOUT) https://pauta-project.dev/6.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 the `help.about` command, by Help → About where the app has a Help menu (the Help menu of a menu bar, or a Help submenu of the app's main menu, which [WIN-14](https://pauta-project.dev/6.0.0/window-shell/#win-14) defines), and on macOS by the About item of the application menu, the one macOS names after the app. The app adds that item itself: JavaFX builds the menu with Hide and Quit and no About. - *Why:* on macOS that menu is where every app keeps About, so it is one of the places [the OS's way wins](https://pauta-project.dev/6.0.0/same-on-every-os/#where-the-oss-way-wins). - *Check (code):* `help.about` is registered and opens the About window; where the app has a Help menu, a row inside that menu runs the command (a row beside a Help submenu is not in it); and on macOS the app inserts an About item into the application menu that opens the same window. - *Reference:* Editora [`ui/AboutDialog.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/AboutDialog.java) and [`ui/MenuBarModel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MenuBarModel.java) (`help.about` ends the Help menu), and the app template's [`ui/Commands.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Commands.java) and [`ui/AppMenus.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/AppMenus.java), do the Help row and the command. Neither adds the macOS item yet, and nor do Torrenta, Modula and nux. Termina ([`ui/MacAppMenu.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/MacAppMenu.java)) and Mirada ([`os/MacAppMenu.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/os/MacAppMenu.java)) do: JavaFX has no public API for that menu, so both insert the item into the one Glass keeps (`MacApplication.getAppleMenu`). Neither is the whole rule: Termina's command is `about`, not `help.about`, and Mirada's About row sits beside the Help submenu of its main menu, not in it ([`ui/TitleBar.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/TitleBar.java), `finish`). - **ABOUT-02 · MUST.** About shows the version and build, the runtime, the license, links to the app's home page, its source code and its releases, and the result of the last update check. The Pauta edition is [ABOUT-05](https://pauta-project.dev/6.0.0/templates/about/#about-05). - *Check (code):* the About window shows the version and the build as the build recorded them (in Editora both come from `AppInfo`, which `--version` prints from too); the Java and JavaFX versions; the license; a link that opens the app's home page (its website, or its repository's page on the host where About links no website), one that opens its source code (the repository) and one that opens its releases (the repository's releases page or its latest release), each there whatever the update check answered; and the update checker's last answer whatever it was (an update, up to date, a failed check or not checked yet), not only an update that is available. One link meets two of the three when the page it opens is both: the repository's page is the home page and the source code where About links no website, and a releases page of the repository holds its source too (Editora's "Source code and releases"). A link to the running build's release notes, and a link shown only when an update is available, are not the link to the releases. - *Reference:* Editora [`ui/AboutDialog.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/AboutDialog.java), [`AppInfo`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/AppInfo.java) (`HOMEPAGE`, its website, and `RELEASES_PAGE`, the repository's latest release, behind "Source code and releases"); the page's [Spec](https://pauta-project.dev/6.0.0/templates/about/#spec). Four apps lack a link. Termina's About ([`ui/AboutWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/AboutWindow.java)) links its website and not its source code, and its releases only when an update is available. Mirada's ([`ui/AboutWindow.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/AboutWindow.java)) links its repository and the running build's release notes, and its releases only when an update is available. Modula's About ([`ui/AboutWindow.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/AboutWindow.java)) links its repository and never its releases; it also shows no Java version, and it shows the update check only when an update is available. nux's ([`ui/AboutWindow.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/AboutWindow.java)) has the runtime lines and links its repository; it shows the update check, and with it the link to its releases, only when there is a newer version. - **ABOUT-03 · SHOULD.** About's *Copy details* button copies the environment block and leaves the window open; its label becomes "Copied". - *Check (code):* the button's handler puts the environment block's text on the clipboard and sets the button's label to the copied text (Editora's `about.copied`); the button sits in the content, not the dialog's button bar, so pressing it can't close the window. - *Reference:* Editora [`AboutDialog`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/AboutDialog.java) (`about.copyDetails`, `about.copied`). - **ABOUT-04 · SHOULD.** About's 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):* About's update status falls back to the not-checked text when the checker has no result. - *Reference:* Editora [`AboutDialog`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/AboutDialog.java) (`about.notChecked`); the [Update status states](https://pauta-project.dev/6.0.0/templates/about/#update-status-states). - **ABOUT-10 · SHOULD.** In About, an available update stands out: "Update available" is bold in amber, a color no link or label in About uses, while the links stay in the accent, "up to date" is green, a failed check red and the last-checked line muted (Editora's tokens for the four are `-state-amber`, `-state-accent`, `-state-green` and `-state-red`). - *Why:* in the accent every link wears, the one line that asks for action reads as one more link. - *Check (code):* the style of About's update-available line (the app template's `.about-update-available`) is bold in the amber token, and no other About style uses that token; the up-to-date line is in the green token, a failed check in the red and the last-checked line in the muted color, and the links keep the accent. - *Reference:* the [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s `.about-update-available` in [`styles/app.css`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/resources/com/example/app/styles/app.css), set by [`ui/AboutDialog.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/AboutDialog.java). No released app does yet: Editora's `.about-update` in [`app.css`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/resources/com/editora/styles/app.css) is `-state-accent`, the links' color. ### Pauta edition and conformance - **ABOUT-05 · MUST.** About names the Pauta edition in two places: a link, *Built to Pauta x.y.z*, among its other links (at Partial it reads *Working toward Pauta x.y.z*, [ABOUT-09](https://pauta-project.dev/6.0.0/templates/about/#about-09)), and a line `Pauta: x.y.z` in the environment block, right after the commit, so *Copy details* carries it. - *Check (code):* one of About's links reads *Built to Pauta* and the edition, or *Working toward Pauta* and the edition at Partial, in words from the catalog, and About's environment block writes a `Pauta:` line right after the commit line. The rule asks for the words, not for a catalog key: the app template's and Termina's key is `about.pauta`, Mirada's `about.pautaLink`. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`ui/AboutDialog.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/AboutDialog.java) and [`AppInfo.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/AppInfo.java); Termina's [`ui/AboutWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/AboutWindow.java) and [`AppInfo.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/AppInfo.java); Mirada's [`ui/AboutWindow.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/AboutWindow.java) (`about.pautaLink`) and [`AppInfo.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/AppInfo.java). - **ABOUT-06 · MUST.** About's edition link ([ABOUT-05](https://pauta-project.dev/6.0.0/templates/about/#about-05)) opens the edition's own address, `https://pauta-project.dev//`, which never changes, not `latest/`, which moves on to newer editions. - *Check (code):* the URL About's edition link opens is built from the edition number (`pauta.version`) and never contains `latest`. An About with no edition link has nothing to open: the rule fails with [ABOUT-05](https://pauta-project.dev/6.0.0/templates/about/#about-05), which requires the link, and the evidence names that rule. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`AppInfo.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/AppInfo.java) (`pautaUrl`); Termina's [`AppInfo.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/AppInfo.java) (`pautaUrl`); Mirada's [`AppInfo.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/AppInfo.java) (`pautaUrl`). - **ABOUT-07 · MUST.** The Pauta edition About names 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. An app at Partial names the edition it is working toward instead, and says so ([ABOUT-09](https://pauta-project.dev/6.0.0/templates/about/#about-09)). - *Check (code):* read which words About uses for the edition ([ABOUT-09](https://pauta-project.dev/6.0.0/templates/about/#about-09)). *Working toward* meets the rule. An About that names no edition claims none: this rule has nothing to judge and passes, and the missing edition is [ABOUT-05](https://pauta-project.dev/6.0.0/templates/about/#about-05)'s finding. *Built to* is judged last, from the audit's other results: audited against the edition the app names (`pauta.version`), with that edition's own rules (`https://pauta-project.dev//rules.json`), not the newest edition's, the app has no MUST that is `fail` or `pending`. The evidence names the MUSTs that are. An audit of part of the edition judges the rule from the MUSTs in its scope and says so. Only the rules of the edition the app names settle a *Built to*: an audit run against another edition reports the rule as `not-checked` and names the edition whose rules would settle it. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template), which is at Partial: its About says *Working toward Pauta 4.1.0* ([`ui/AboutDialog.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/AboutDialog.java), `editionKey`) and so does its README. Termina and Mirada don't meet it yet. Termina's About says "Built to Pauta 2.0.2" ([`pom.xml`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/pom.xml), `pauta.version`), an edition that already required a find bar in its Debug Log, the UI font on every scene and the command ids `help.about` and `palette.show`, none of which it has. Mirada's says "Built to Pauta 4.0.1", an edition that already required its settings in `~/.mirada` on every OS. - **ABOUT-08 · MUST.** The Pauta edition an app names has one source: a `pauta.version` property in `pom.xml`, which the build filters into the app's resources and the app reads from there, like its own version (`build-info.properties` and `AppInfo` in the app template). The README's badge and "Built to" line, which name that edition too, are [PAUTA-15](https://pauta-project.dev/6.0.0/conformance/#pauta-15). - *Check (code):* `pom.xml` defines `pauta.version`; a resource the build filters carries it (the app template's `build-info.properties`); and the edition the app shows is read from that resource (the template's `AppInfo`), never from a literal in its code. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`pom.xml`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/pom.xml), `build-info.properties` and [`AppInfo.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/AppInfo.java); Termina's the same, with [`AppInfo.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/AppInfo.java), and Mirada's, with its [`pom.xml`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/pom.xml) and [`AppInfo.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/AppInfo.java). - **ABOUT-09 · MUST.** About shows the app's conformance, Complete, Core or Partial, as the conformance helper computes it from `pauta.json` ([PAUTA-02](https://pauta-project.dev/6.0.0/conformance/#pauta-02)) and never higher: a link, *Pauta conformance: Core*, right after the edition's link, that runs the `help.pauta` command and so opens the Pauta window ([PWIN-01](https://pauta-project.dev/6.0.0/templates/pauta-window/#pwin-01)), and a line `Pauta conformance: Core (2 exceptions)` in the environment block, right after the `Pauta:` line; with one it says `(1 exception)`, with none `(no exceptions)`. At Partial the edition's link reads *Working toward Pauta x.y.z*: the app does not meet that edition yet, so it does not say it is built to it. - *Why:* [*Never claim what is not true*](https://pauta-project.dev/6.0.0/principles/#for-the-people-using-the-apps). - *Check (code):* About calls the conformance helper and holds no conformance name of its own; its conformance link runs `help.pauta`; the environment block has the conformance line after the `Pauta:` line; and at Partial the edition's link reads *Working toward Pauta* and the edition (the app template's key for it is `about.pautaWorkingToward`). - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`ui/AboutDialog.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/AboutDialog.java) and [`PautaConformance.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/PautaConformance.java) (`environmentLine`). Termina's and Mirada's About show the edition but not the conformance. ## Pauta window (PWIN) https://pauta-project.dev/6.0.0/templates/pauta-window/: The window that shows which edition of Pauta the app implements, how fully it conforms, and every exception it records, opened from About, the Help menu and the Command Palette. ### Rules - **PWIN-01 · MUST.** Every app has a Pauta window, opened by the `help.pauta` command: from the Command Palette like every command, and from a *Pauta Conformance* row in the Help menu where the app has a Help menu (the Help menu of a menu bar, or a Help submenu of the app's main menu, which [WIN-14](https://pauta-project.dev/6.0.0/window-shell/#win-14) defines). The row's place in that menu is [DOCS-07](https://pauta-project.dev/6.0.0/documentation/#docs-07), and About's *Pauta conformance* link, which runs the same command, is [ABOUT-09](https://pauta-project.dev/6.0.0/templates/about/#about-09). - *Check (code):* a command with the id `help.pauta` is registered and opens the Pauta window, and where the app has a Help menu, a row inside that menu runs the command (the app template's Help menu is a list of command ids that holds `help.pauta`). A row beside a Help submenu is not in it. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`ui/Commands.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Commands.java) (`help.pauta`, which runs `openPauta`) and [`ui/AppMenus.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/AppMenus.java) (`help.pauta` in `menu.help`, just above `help.about`). No released app has a Pauta window yet. - **PWIN-02 · MUST.** The Pauta window shows the edition, the conformance with one sentence that says what it means, a count of exceptions by kind, and every exception: the rule's ID, its level (MUST or SHOULD), the kind, the reason, and for a deviation or a pending exception its link. - *Check (by hand):* open the Pauta window and compare it with the app's `pauta.json`, entry by entry. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`ui/PautaWindow.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/PautaWindow.java). - **PWIN-03 · MUST.** The Pauta window reads the exceptions from `pauta.json` and the edition from the build, as About does ([ABOUT-08](https://pauta-project.dev/6.0.0/templates/about/#about-08); `AppInfo` in the template), and takes the conformance from the same helper as About ([PAUTA-02](https://pauta-project.dev/6.0.0/conformance/#pauta-02)). No edition, conformance or exception is written in the window's own code. - *Check (code):* the Pauta window loads the exceptions through the one loader of `pauta.json`, reads the edition where About reads it, and calls the conformance helper; its code holds no rule ID, edition number or conformance name of its own. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`ui/PautaWindow.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/PautaWindow.java) (`PautaConformance.of`). - **PWIN-04 · MUST.** Every link in the Pauta window opens a fixed address, never one under `latest/`: the edition's link opens the edition's own address, the one [ABOUT-06](https://pauta-project.dev/6.0.0/templates/about/#about-06) gives About's link, and each rule ID opens the rule's address in that edition (the entry's `url` in `pauta.json`). The edition's link, in the Pauta window and in About, runs the `help.pautaRules` command, so the palette reaches it too. - *Why:* an app built to an edition answers to that edition's rules; `latest/` moves on. - *Check (code):* `help.pautaRules` is registered and opens the edition's address, built from `pauta.version`; the edition's link in the Pauta window and the one in About both run that command; and each rule ID in the Pauta window opens its entry's `url`. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`ui/Commands.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Commands.java) (`help.pautaRules`, which opens `AppInfo.pautaUrl()`), run by the edition's link in [`ui/PautaWindow.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/PautaWindow.java) and [`ui/AboutDialog.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/AboutDialog.java); `PautaWindow` opens each rule ID at its entry's `url`. - **PWIN-05 · SHOULD.** The Pauta window lists pending exceptions first, then deviations, then app-only (in a template), then not-applicable; within a kind, MUSTs before SHOULDs, then by ID. - *Why:* what the app still owes is what a reader came to find. - *Check (code):* the list the Pauta window draws is sorted by kind in that order, then MUSTs before SHOULDs, then by rule ID (the app template's `PautaConformance.sorted`). A test that asserts it is the surest evidence. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`PautaConformance.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/PautaConformance.java) (`sorted`), tested by [`PautaConformanceTest`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/test/java/com/example/app/PautaConformanceTest.java). Its `Kind` has three kinds, pending, deviation and not-applicable: it sorts those and cannot read `app-only` yet. - **PWIN-06 · SHOULD.** The Pauta window's *Copy as text* button copies the edition, the conformance and the list as Markdown, one line per exception, and leaves the window open; its label becomes "Copied". - *Check (code):* the button's handler copies the edition, the conformance and one line per exception as Markdown and sets the button's label to the copied text (the template's `pauta.copied`); the button sits in the content, not the button bar, like About's *Copy details*, so pressing it can't close the window. - *Reference:* the app template's [`ui/PautaWindow.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/PautaWindow.java) (`pauta.copy`, `pauta.copied`), built like Editora's About *Copy details*. - **PWIN-07 · SHOULD.** A *Conformance in the docs* link runs the `help.pautaDocs` command, which opens the app's docs page ([PAUTA-13](https://pauta-project.dev/6.0.0/conformance/#pauta-13)) for this version, `/docs/v-/pauta/`, where the site serves versioned docs ([DOCS-03](https://pauta-project.dev/6.0.0/documentation/#docs-03)), and `/docs/pauta/` until it does. The README's badge links the unversioned page, which always shows the latest release. - *Check (code):* `help.pautaDocs` is registered and builds the URL from the app's docs base, like Help → Documentation. - *Reference:* the app template's [`AppInfo.pautaDocsUrl()`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/AppInfo.java), registered as `help.pautaDocs` in [`ui/Commands.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Commands.java). - **PWIN-08 · SHOULD.** With no exceptions, the Pauta window says so in one line where the list would be, naming the app and the edition (for an app called Mirada, "No exceptions: Mirada meets every MUST and SHOULD of Pauta x.y.z."), and its copy button still works. - *Check (by hand):* with an empty `exceptions` array in `pauta.json`, open the Pauta window. - *Reference:* The [app template](https://github.com/adriandeleon/adl-desktop-app-template)'s [`ui/PautaWindow.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/PautaWindow.java) (`pauta.none`). ## Confirm dialog (CONF) https://pauta-project.dev/6.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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CloseCoordinator.java) (unsaved changes, Quit) and [`GitCoordinator.confirmDestructive`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/GitCoordinator.java); Torrenta [`ui/RemoveConfirm.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/RemoveConfirm.java), which asks it for the torrent list, the RSS tab and every list in Settings. Modula and nux don't yet: the Remove row of a Modula preset's menu ([`ui/PresetBar.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/PresetBar.java), `removePreset` in [`ui/RadioPane.java`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/src/main/java/com/modula/ui/RadioPane.java)) and nux's Profiles → Delete (`withProfileRemoved`, called from [`App.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java)) remove at once, with no question and no undo. - **CONF-02 · MUST.** In an app that asks before a destructive action (before it removes, deletes, discards or overwrites something, ends a running program, or runs a command that cannot be taken back), the question names the thing and what happens to it. A question that warns before something is run or pasted and destroys nothing (Termina's before a multi-line paste), and a question before a harmless command (nux's before a UPS command it does not count as risky), are not questions before a destructive action. This list says which questions the rules on a question's form cover; it is wider than what [CONF-01](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-01) requires a question or an undo for, which is only what the user made. - *Check (code):* the string of every question before a destructive action 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`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/RemoveConfirm.java), [`Actions.removeQuestion`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/Actions.java). - **CONF-03 · MUST.** In an app that asks before a destructive action, the question's confirming button carries the action's own verb (Delete files, Remove, Discard, Quit), never OK or Yes, and is drawn in red, the danger style (Editora's style class for it is `danger`). - *Check (code):* in every question before a destructive action ([CONF-02](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-02) says which those are), the confirming button's `ButtonType` is named with the action's verb, never OK or Yes, and its button is given the red danger style (the `danger` style class in Editora). Where the buttons' words come from is [CONF-14](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-14)'s. - *Reference:* Torrenta [`RemoveConfirm.ask`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/RemoveConfirm.java) meets it: the action is named with its verb and styled `danger`. Four other questions of Torrenta's, in [`ui/SettingsWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/SettingsWindow.java) (disconnecting sync, Reset to Defaults, Reset All Shortcuts and taking a shortcut back from another command), don't yet: the confirming button says OK and is not red. Its question before connecting sync is not one of them: it destroys nothing (what the repository holds comes to this machine, and a value that differs here is kept), like Editora's ([`ui/SettingsSyncPage.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsSyncPage.java)). Termina's [`ui/Confirm.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/Confirm.java), Mirada's [`ui/Confirm.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Confirm.java) and the app template's [`ui/Confirm.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Confirm.java) meet it too: the action is named with its verb and styled `danger`. Editora meets it in some questions and not in others. [`GitCoordinator.confirmDestructive`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/GitCoordinator.java), which every destructive Git action asks through, [`MainController.styleUnsavedChangesButtons`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java) and `styleQuitButtonAsDanger` name and style the action, and so do its Local History purges ([`ui/HistoryCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/HistoryCoordinator.java)). It doesn't yet where the answer is the stock OK, as in these among others: the Project panel's file delete (`confirmDelete` in [`ui/ProjectPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ProjectPanel.java)), deleting a project ([`ui/MainController.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java)), deleting a note ([`ui/NotesCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/NotesCoordinator.java)), deleting a macro ([`ui/MacroSettingsPane.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MacroSettingsPane.java)), Replace in Files ([`ui/SearchCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SearchCoordinator.java)), and Revert and overwriting a file from Save As (`confirmRevertDialog` and `confirmOverwrite` in [`ui/FileWorkflowCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/FileWorkflowCoordinator.java)); nor where the action is named and not red, as in: deleting a remote site ([`ui/RemoteSitesPane.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/RemoteSitesPane.java)), deleting a TODO pattern ([`ui/TodoSettingsPane.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TodoSettingsPane.java)), resetting the settings ([`ui/SettingsResetFlow.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsResetFlow.java)), discarding recovery records ([`ui/RecoveryCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/RecoveryCoordinator.java)) and removing a plugin ([`ui/PluginDialogs.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/PluginDialogs.java)). nux's risky-command question names Run, with no red ([`ui/CommandConfirmation.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/CommandConfirmation.java)). - **CONF-14 · MUST.** Every dialog with two or more buttons words each button from the message catalog, never with JavaFX's stock OK, Yes, No, Cancel, Apply or Close, which are worded in the JVM's locale. That is every JavaFX `Dialog` the app shows, whatever it is for: a question, before a destructive action ([CONF-02](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-02)) or not, a text prompt, a pick from a list, a form. Only a message with one button is outside the rule. Like [CONF-08](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-08) and [CONF-12](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-12), it reaches past the question before a destructive action. - *Why:* a stock button is labeled from JavaFX's own resources, in the JVM's locale, so under menus in the language chosen in Settings a dialog can still say "Cancel" in another. - *Check (code):* in every `Dialog` the app shows with two or more buttons (an `Alert` of any type, a `TextInputDialog`, a `ChoiceDialog`, a `Dialog` the app fills itself), each button shows a string from the message catalog: its `ButtonType` is built with one, or its button's text is set from the catalog before the dialog is shown. None is left as `ButtonType.OK`, `ButtonType.YES`, `ButtonType.NO`, `ButtonType.CANCEL`, `ButtonType.APPLY` or `ButtonType.CLOSE`, and none is the stock OK or Cancel that an `Alert` of type `CONFIRMATION`, a `TextInputDialog` and a `ChoiceDialog` come with. A dialog whose stock buttons are swapped for catalog-worded ones before it is shown passes (Torrenta's `StockButtons.translate`). A dialog with one button is not judged. An app that shows no dialog with two or more buttons has nothing to judge, and passes. - *Reference:* Torrenta: [`RemoveConfirm.ask`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/RemoveConfirm.java) names the action from the catalog and takes Cancel from its [`StockButtons`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/StockButtons.java) (`cancel()`, the catalog's word on the `CANCEL_CLOSE` role), and every other dialog of two buttons goes through `StockButtons.translate`, which swaps the stock OK and Cancel for the catalog's: the four alerts that ask in its Settings ([`ui/SettingsWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/SettingsWindow.java): connecting and disconnecting sync, Reset to Defaults and the shortcuts), its nine text prompts and its two picks from a list ([`ui/MainWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java), [`ui/DetailPane.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/DetailPane.java) and `ui/SettingsWindow.java`). Modula's one dialog is a message with one button, so it has nothing to judge. Termina, Mirada and the app template meet it in their questions and not in their text prompts. Termina's [`ui/Confirm.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/Confirm.java), which its removals, its close-running-program question and its multi-line paste warning ask through, names both buttons from the catalog, and so does its Import configuration question ([`ui/ConfigTransfer.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/ConfigTransfer.java)); its Rename Tab prompt words OK from the catalog and keeps the stock Cancel (`askForTabName` in [`ui/TerminalWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java)), and the prompt its setting commands ask a value through (`settingHost` in the same file) and its Create on GitHub prompt (`createSyncRepositoryOnGitHub` in [`ui/SettingsWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/SettingsWindow.java)) are `TextInputDialog`s with the stock OK and Cancel. Mirada's [`ui/Confirm.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/Confirm.java) and its note form ([`ui/NoteDialog.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/NoteDialog.java)) name both buttons from the catalog; its Rename prompt (`rename` in [`ui/ViewerWindow.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/ViewerWindow.java)) is a `TextInputDialog` with the stock OK and Cancel. The app template's [`ui/Confirm.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Confirm.java) names both from the catalog; its text prompts ([`ui/Prompts.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/Prompts.java), and `promptCreateOnGitHub` in [`ui/SettingsWindow.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/SettingsWindow.java)) keep the stock OK and Cancel, and its Report a Problem form names Submit beside a stock `ButtonType.CANCEL` ([`ui/ReportProblemWindow.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/ReportProblemWindow.java)). Editora doesn't yet. Its unsaved-changes and Quit questions name every button from the catalog (`unsavedAlert` and `confirmQuit` in [`ui/CloseCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CloseCoordinator.java)), but of its 64 `CONFIRMATION` alerts, 26 keep the stock OK and Cancel, the Project panel's file delete (`confirmDelete` in [`ui/ProjectPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ProjectPanel.java)) and Replace in Files ([`ui/SearchCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SearchCoordinator.java)) among them, and 22 more name the action beside a stock `ButtonType.CANCEL`, among them [`GitCoordinator.confirmDestructive`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/GitCoordinator.java), which every destructive Git action asks through. Its warnings that ask do the same: the four trust questions of [`ui/TrustPrompts.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TrustPrompts.java) name the action beside a stock Cancel, and the question before its MCP server is enabled (`confirmEnableMcp` in [`ui/MainController.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java)) keeps the stock OK and Cancel. So do its prompts and forms, these among them: the Create on GitHub prompt ([`ui/SettingsSyncPage.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsSyncPage.java)), the reset-mode and revert-merge picks ([`ui/GitWindowCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/GitWindowCoordinator.java)), the pick of a settings backup ([`ui/SettingsResetFlow.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsResetFlow.java)), a macro's command picker ([`ui/MacroSettingsPane.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MacroSettingsPane.java)) and the Java cleanups form ([`ui/JavaCleanupsDialog.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/JavaCleanupsDialog.java)) keep the stock OK and Cancel, and the login form ([`ui/RemoteCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/RemoteCoordinator.java)) and the forms that export and import the configuration ([`ui/ExportConfigDialog.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ExportConfigDialog.java), [`ui/ConfigImportFlow.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ConfigImportFlow.java)) name the action beside a stock `ButtonType.CANCEL`. nux doesn't in any of its four dialogs of two buttons: the question before a risky command names Run beside a stock `ButtonType.CANCEL`, the one before a harmless command is a `CONFIRMATION` alert with the stock OK and Cancel ([`ui/CommandConfirmation.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/CommandConfirmation.java)), its credentials form adds `ButtonType.OK` and `ButtonType.CANCEL` ([`ui/CredentialsDialog.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/CredentialsDialog.java)), and its Save Profile prompt is a `TextInputDialog` with the stock pair (`saveCurrentAsProfile` in [`App.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/App.java)). - **CONF-04 · MUST.** In an app that asks before a destructive action, Cancel is the way out of the question: Escape and the window's close button both answer Cancel, and nothing is lost on a dismissal. - *Check (code):* in every question before a destructive action ([CONF-02](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-02) says which those are), 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/GitCoordinator.java), [`CloseCoordinator.unsavedAlert`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CloseCoordinator.java); Torrenta [`RemoveConfirm.ask`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/RemoveConfirm.java). - **CONF-13 · MUST.** In an app that asks before a destructive action, every such question has one default button, and it is never the red one (Editora's `danger` style class): Cancel where the only action is destructive, Save where saving is an option ([CONF-05](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-05)). The dialog opens with keyboard focus on the default button, so Enter in a question that has just opened keeps what the user has, on every OS, and the red action runs only from its own button: a click, or the focus moved to it with Tab and then Space, which presses the focused button on every OS. - *Why:* Enter is the key a hurried hand presses, and Escape already cancels ([CONF-04](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-04)): with Cancel as the default, no single key destroys anything. JavaFX makes a button with the `OK_DONE` role the default by itself, so a named action is the default unless the dialog says otherwise. It also presses a focused button on Enter on Windows and Linux but not on macOS, so a question with no default button answers Enter differently on each OS. With Cancel as the default one difference is left, and it is JavaFX's: once Tab has put the focus on the red button, Enter runs it on Windows and Linux and answers Cancel on macOS. Space is the key that does the same everywhere. - *Check (code):* in every question before a destructive action ([CONF-02](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-02) says which those are), the code calls `setDefaultButton(true)` on Cancel, or on Save in the unsaved-changes question, and `setDefaultButton(false)` on the destructive action, so that one is not left a default button too, and it does both before the dialog is shown. JavaFX gives the opening focus to the first button that is a default button, so with one default button the dialog opens with the focus on it. No such question leaves the red action, or no button at all, as the default. - *Reference:* Termina [`ui/Confirm.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/Confirm.java) (`Options.cancelIsDefault`, which its close-running-program question sets) and nux [`ui/CommandConfirmation.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/CommandConfirmation.java) (a risky UPS command): each unsets the action's default and sets Cancel's as it builds the dialog, before it is shown. Editora does it in about twenty of its questions, each by hand: deleting for good what the trash cannot take ([`ProjectPanel.cancelByDefault`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ProjectPanel.java)), closing a terminal with a program running ([`ui/TerminalCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TerminalCoordinator.java)), resetting settings ([`ui/SettingsResetFlow.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsResetFlow.java)), trusting a folder ([`ui/TrustPrompts.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TrustPrompts.java)) among them. The rest don't yet: Editora's Git confirmations and Local History purges ([`ui/HistoryCoordinator.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/HistoryCoordinator.java)), Torrenta's `RemoveConfirm`, Mirada's `Confirm`, the app template's `Confirm`, and Termina's removals and its Import configuration question leave the red action as the default, so Enter runs it; Torrenta's four Settings questions ([CONF-03](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-03)) leave OK as the default, and so do questions of Editora's that keep the stock OK, its delete to the trash (`confirmDelete` in [`ui/ProjectPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ProjectPanel.java), which moves the default only when a file cannot go to the trash), its Revert and its Save As overwrite among them; Editora's unsaved-changes and Quit questions have no default button. nux's question before a command it does not count as risky leaves the stock OK as the default too, but it is not a question before a destructive action ([CONF-02](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-02)). ### States - **CONF-05 · SHOULD.** A question before unsaved changes are lost, where saving is an option, has three answers, drawn in this order: Cancel, Save in green and Discard in red (Editora's style classes for the two are `success` and `danger`), with Cancel to the left of the actions as in every dialog ([WIN-11](https://pauta-project.dev/6.0.0/window-shell/#win-11)). A Save that fails leaves the tab open. - *Check (code):* the unsaved-changes alert draws Cancel, Save and Discard in that order, on the `ButtonBar`'s one fixed order and not the order its `ButtonType`s were added in, and styles Save and Discard; and when Save is chosen and the save fails, the close is abandoned, so the tab stays open. - *Reference:* Editora [`CloseCoordinator.unsavedAlert`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CloseCoordinator.java), [`MainController.styleUnsavedChangesButtons`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java), for the three answers and their styles; it still draws them Save, Discard, Cancel. - **CONF-06 · SHOULD.** A question about ending a running program, which is not the user's data, words the button Close, in red like every confirming button ([CONF-03](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-03)). Cancel is its default button, as in every question with a red action ([CONF-13](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-13)), so dismissing the dialog by any route keeps the program alive. - *Check (code):* the close-running-program alert names its action Close. Its red and its default button are [CONF-03](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-03)'s and [CONF-13](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-13)'s to judge. - *Reference:* Termina [`ui/TerminalWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java) (`dialog.closeAnyway`), through [`ui/Confirm.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/Confirm.java). - **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`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/UndoStack.java)); Editora [`ClosedTabs`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ClosedTabs.java). ### Behavior - **CONF-08 · SHOULD.** Every confirmation question, whether or not it is before a destructive action, comes before anything changes, and its action runs only on the action button. For a question before a destructive action both are MUSTs already ([CONF-01](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-01), [CONF-04](https://pauta-project.dev/6.0.0/templates/confirm-dialog/#conf-04)); what this rule adds is every other question, such as a warning before something is pasted or run. - *Check (code):* every confirmation helper returns true on the action button alone, and its caller acts only on true, for the questions that are not before a destructive action as for those that are. - *Reference:* Torrenta [`RemoveConfirm.ask`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/RemoveConfirm.java); Editora [`GitCoordinator.confirmDestructive`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/GitCoordinator.java). For a question that is not before a destructive action: Termina's multi-line paste warning, asked through [`ui/Confirm.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/Confirm.java), whose `ask` is true for the action button alone, and nux's question before a harmless command ([`ui/CommandConfirmation.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/CommandConfirmation.java), `confirmed`). - **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`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/Actions.java); Editora [`CloseCoordinator.confirmSweep`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/CloseCoordinator.java). - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/GitBranchCoordinator.java) (Force with Lease after a rejected push), `confirmForceDelete` (Delete Anyway after `NOT_FULLY_MERGED`). - **CONF-12 · SHOULD.** A confirmation 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 (code):* the header and the question of every kind are built by pure functions, which need no dialog to call, and the confirmation helper has a hook that answers the dialog in a test without showing it. A test that asserts it is the surest evidence. - *Reference:* Torrenta [`RemoveConfirm.header`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/RemoveConfirm.java), `question`, `answerForCapture`; [`RemoveConfirmTest`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/test/java/com/torrenta/ui/RemoveConfirmTest.java). ## Find bar (FIND) https://pauta-project.dev/6.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 (an editor, a read-only console, a terminal's scrollback, a log shown as text, such as the Debug Log), the app has a find bar that is part of the window, never a popup. A log shown as a list of entries is narrowed by a filter instead ([FIND-03](https://pauta-project.dev/6.0.0/templates/find-bar/#find-03)). - *Why:* every app has a Debug Log ([DIAG-03](https://pauta-project.dev/6.0.0/diagnostics/#diag-03)), and a log is read by searching it. - *Check (code):* each view of searchable text, the Debug Log window among them, has a find bar that is a node in its window's scene graph (docked or floating); no `Popup` or `Stage` is created for it. A log drawn as a `ListView` or a `TableView` is not such a view. An app with no Debug Log window has no find bar there either, so it does not meet this rule: it fails with [DIAG-03](https://pauta-project.dev/6.0.0/diagnostics/#diag-03), which requires the window, and the evidence names that rule. - *Reference:* Editora [`ui/FindReplaceBar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/FindReplaceBar.java) (the editor's find and replace), with [`ui/ConsoleFindBar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ConsoleFindBar.java) and [`ui/TerminalFindBar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TerminalFindBar.java) as the same shape over a console and a terminal; Termina [`ui/SearchBar.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/SearchBar.java). Editora doesn't meet it in every console yet: the build console has the bar ([`ui/BuildToolPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/BuildToolPanel.java)); the Run, External Tools and Debug consoles ([`ui/RunPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/RunPanel.java), [`ui/ExternalToolPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ExternalToolPanel.java), [`ui/DebugPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/DebugPanel.java)) are read-only text areas with none. Over a log window, the app template's [`ui/DebugLogFindBar.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/DebugLogFindBar.java), a row in its Debug Log window. No released app's Debug Log has a find bar yet. Editora's Message Log ([`ui/MessageLogPopup.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MessageLogPopup.java)) and Torrenta's log window ([`ui/LogWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/LogWindow.java)) are lists, which [FIND-03](https://pauta-project.dev/6.0.0/templates/find-bar/#find-03) covers. - **FIND-02 · MUST.** A find bar searches as its query is typed and shows a match count. - *Check (code):* in each find bar the app has, the query field's text listener runs the search and updates the count label. A view where [FIND-01](https://pauta-project.dev/6.0.0/templates/find-bar/#find-01) asks for a find bar and the app has none fails this rule with FIND-01, and so does an app with no find bar and no Debug Log window at all; the evidence names that rule. - *Reference:* Editora [`FindReplaceBar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/FindReplaceBar.java) (`debounce`, `find.count`); Termina [`SearchBar`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/SearchBar.java) (`search.count`); the app template's [`ui/DebugLogFindBar.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/DebugLogFindBar.java) (`searching`, `find.count`). - **FIND-03 · MUST.** A list is narrowed by a filter box where text is searched by a find bar. In an app whose main content is a list, a filter box over that list takes the place of a find bar there, with the same field and the same Escape. The main content is a list when it is a list or a table of items that grows without bound and that the user finds things in; Torrenta, with its torrents, is the one such app today. In every app, a log shown as a list of entries (a Message Log, an event log, a Debug Log drawn as a list or a table) is covered the same way: a filter field over the list narrows it, and it needs no find bar. An event log and a log tab that lists one item's events count as logs shown as a list (nux's event log, the Log tab of Torrenta's detail pane); a table of readings or of history does not. - *Check (code):* in an app whose main content is a list (a list or a table of items that grows without bound and that the user finds things in), a filter field sits over that list and filters it as it is typed, and Escape pressed in it leads back to the list, as it leads back to the text from a find bar ([FIND-07](https://pauta-project.dev/6.0.0/templates/find-bar/#find-07)). Whether the first Escape empties the box before the next one leaves it is [FIND-14](https://pauta-project.dev/6.0.0/templates/find-bar/#find-14)'s. In every app, each log shown as a list or a table of entries has a filter field over it that narrows the entries as it is typed; check boxes that narrow a log by level are not one. An event log and a tab that lists one item's events are such logs; a table of readings or of history is not judged. - *Reference:* Torrenta [`Omnibox`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/Omnibox.java), [`FilterQuery`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/FilterQuery.java), [`MainWindow.onOmniboxKey`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java). Over a log shown as a list: Editora's [`ui/MessageLogPopup.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MessageLogPopup.java), a filter field over its `ListView` (`applyFilter`), and the Message Logs of Torrenta ([`ui/MessageLogPopup.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MessageLogPopup.java)), Mirada ([`ui/MessageLogView.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/MessageLogView.java)) and the app template ([`ui/MessageLogView.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/MessageLogView.java)), each a filter field over a `ListView`. Four logs don't meet it yet: Torrenta's [`ui/LogWindow.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/LogWindow.java) filters its table by level with three check boxes and has no field to type in; the Log tab of Torrenta's detail pane ([`ui/DetailPane.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/DetailPane.java), `buildLog`) lists the selected torrent's events with no filter; and Termina's Message Log ([`ui/MessageLogWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/MessageLogWindow.java)) and nux's event log ([`ui/EventsWindow.java`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/src/main/java/com/nux/ui/EventsWindow.java)) are a list and a table with no filter. ### Behavior - **FIND-04 · SHOULD.** A command opens each find bar, and run while its bar is already open it finds the next match. For the main window's own text (the editor; the terminal in a terminal app) the command is `find.show`, bound to `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 (`Cmd+G` in place of `F3` in CUA on macOS); a terminal binds it to `Ctrl+Shift+F`, `Cmd+F` on macOS, since a plain `Ctrl+letter` belongs to the shell. Any other bar (over a log window, or over a console or a terminal panel beside the editor) has a command with an id of its own, as the app template's `debugLog.find` is for its Debug Log. - *Check (code):* each bundled keymap binds that chord to `find.show`; every other find bar is opened by a registered command of its own; and each of these commands, run while its bar is shown, steps to the next match. - *Reference:* Editora `keymaps/*.json` and [`MainController.findShowOrNext`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MainController.java), which finds the next match while the editor's bar is open. No other bar does both yet. Termina's find command ([`TerminalWindow`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalWindow.java), `menu.find`, [`MenuAction.appChord`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/MenuAction.java)) runs [`TerminalView.showSearch`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalView.java), which puts the caret back in the field of a bar that is already open. So do Editora's `terminal.find` over its terminal panel ([`TerminalCoordinator.find`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TerminalCoordinator.java)) and the app template's `debugLog.find` over its Debug Log ([`MainWindow.findInDebugLog`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/MainWindow.java)), which that window also runs on a fixed `Ctrl/Cmd+F`. Editora's console bar has no command: the find command's chord pressed in the console opens it (`ConsoleNav.onCommand` in [`ui/BuildToolPanel.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/BuildToolPanel.java)), as does a button in the panel's header. - **FIND-05 · SHOULD.** Typing in a find bar highlights every match, the active one distinctly, and selects and scrolls to the match the search starts on. In a document (an editor, a console, a log) that is the first match at or after the caret as it was when the bar opened, so refining the query does not run away down the document. In a terminal it is the newest match at or above the bottom of the view, since a terminal is searched upward ([FIND-06](https://pauta-project.dev/6.0.0/templates/find-bar/#find-06)). A view that can draw one selection and nothing else, such as a log in a plain text area, shows the active match alone, and the count ([FIND-02](https://pauta-project.dev/6.0.0/templates/find-bar/#find-02)) says how many there are. - *Check (code):* every match in view is painted while the bar is open, not only the active one, unless the view can draw a single selection only. In a document the search starts from an anchor saved when the bar opens, not from the current selection; in a terminal, from the bottom row of the view. - *Reference:* Editora [`FindReplaceBar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/FindReplaceBar.java) (`searchAnchor`, `recompute`) over the editor. Over a terminal, Editora's [`terminal/TerminalView.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/terminal/TerminalView.java) (`startIndex`, `drawSearch`) and Termina's [`TerminalView`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalView.java) (`drawSearchMatches`) with [`ScrollbackSearch.initial`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/ScrollbackSearch.java). Editora's [`ConsoleFindBar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ConsoleFindBar.java) and the app template's [`ui/DebugLogFindBar.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/DebugLogFindBar.java) don't yet: each searches from the current selection (`refine`), not from an anchor saved when the bar opened. Editora's console is a `CodeArea`, which could paint every match, and its bar paints the active one only. The template's log is a `TextArea`, which draws one selection and nothing else, so its bar rightly shows the active match alone. - **FIND-06 · MUST.** In a find bar, Enter steps to the next match and Shift+Enter to the previous one, wrapping around at the ends. In a find bar over a terminal the directions are up and down the scrollback: Enter steps up to older output, Shift+Enter down. - *Check (code):* in each find bar the app has, the query field's key handler steps to the next match on Enter and to the previous one on Shift+Enter (over a terminal, up to older output on Enter and down on Shift+Enter), and a step past the last match goes on to the first, and back. A view where [FIND-01](https://pauta-project.dev/6.0.0/templates/find-bar/#find-01) asks for a find bar and the app has none fails this rule with FIND-01, and so does an app with no find bar and no Debug Log window at all; the evidence names that rule. - *Reference:* Editora [`ConsoleFindBar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ConsoleFindBar.java), [`TerminalFindBar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TerminalFindBar.java); Termina [`SearchBar`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/SearchBar.java). Editora's editor bar ([`FindReplaceBar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/FindReplaceBar.java)) 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. Over a log window, the app template's [`ui/DebugLogFindBar.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/DebugLogFindBar.java) steps and wraps the same way. - **FIND-07 · MUST.** Escape or the close button closes a find bar: its highlights go, a search still pending is canceled so nothing moves after the bar is gone, and focus returns to the text the bar searched (the editor, the console, the shell or the log). In a find bar over a terminal, the Escape that closes the bar does not reach the shell. - *Check (code):* in each find bar the app has, the close path, run by Escape in the field and by the close button, stops the debounces, cancels the running search, clears the highlights and focuses the text the bar searched. In a find bar over a terminal, the field's key handler consumes the Escape it closes the bar on, so the terminal never sends that key to the shell. A view where [FIND-01](https://pauta-project.dev/6.0.0/templates/find-bar/#find-01) asks for a find bar and the app has none fails this rule with FIND-01, and so does an app with no find bar and no Debug Log window at all; the evidence names that rule. - *Reference:* Editora [`FindReplaceBar.hideBar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/FindReplaceBar.java); over a log window, the app template's [`ui/DebugLogFindBar.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/DebugLogFindBar.java) (`close`). Over a terminal, Termina's [`SearchBar`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/SearchBar.java) (`onKey`) and Editora's [`TerminalFindBar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TerminalFindBar.java) each close the bar on Escape and consume the key. - **FIND-08 · SHOULD.** A terminal with a find bar keeps its own key and mouse filters off the bar: they leave every event aimed at the bar alone, so what is typed or clicked there never reaches the shell. The Escape that closes the bar is [FIND-07](https://pauta-project.dev/6.0.0/templates/find-bar/#find-07)'s. - *Check (code):* no key or mouse filter of the terminal acts on an event aimed at the find bar: the filters return early for an event whose target is inside the bar (Termina's `fromSearchBar`), or the bar is outside the node the filters are on, so its events never pass them. - *Reference:* Termina [`TerminalView.fromSearchBar`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TerminalView.java), which its key, mouse and scroll handlers ask first. - **FIND-09 · SHOULD.** In a find bar's fields, the keymap's caret and editing chords (`C-a`, `C-e`, `C-k`, `C-y` in the Emacs keymap; `Ctrl+V/X/C/Z` in CUA, `Cmd+V/X/C/Z` on macOS) 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):* in each find bar's fields, the active keymap's caret and editing chords are handled by the field and never run the document's commands (Editora installs its shared text-input keymap on the fields), and the commands for next, previous, replace and close still run while a find field has the focus. - *Reference:* Editora [`TextInputKeymap.installShared`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/command/TextInputKeymap.java), installed on [`FindReplaceBar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/FindReplaceBar.java)'s find and replace fields. Editora's [`ConsoleFindBar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ConsoleFindBar.java) and [`TerminalFindBar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TerminalFindBar.java) don't yet: neither installs it on its field. Nor does Termina's find field: its [`TextInputKeys`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/TextInputKeys.java) is installed on the palette only. - **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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/FindReplaceBar.java) (`find.notFound`); Termina [`SearchBar`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/SearchBar.java) (`search.none`). - **FIND-11 · SHOULD.** In a find bar that replaces (an editor's), Replace keeps each match's case when *AB* (preserve case) is on. - *Check (code):* with preserve case on, the replace path gives each replacement the casing of the match it replaces (Editora's `PreserveCase.apply`). A test that asserts it is the surest evidence. - *Reference:* Editora [`FindReplaceBarFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/FindReplaceBarFxTest.java) (`preserveCaseFollowsEachMatchesCasing`). - **FIND-12 · SHOULD.** In a find bar that replaces, Replace and Replace All run under a time budget, as the search does: a replacement that outruns it stops and says so in the status line (in Editora's words, "Replace stopped: the pattern is too slow") instead of hanging the window. How long the budget is is the app's own. - *Check (code):* Replace and Replace All match under a time budget, as the search does, and when it runs out they stop and say so in the status line (Editora's `find.replaceTimeout`) instead of hanging the window. A test that asserts it, with a catastrophic regular expression in Replace All, is the surest evidence. - *Reference:* Editora `find.replaceTimeout`, [`FindReplaceBarFxTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/FindReplaceBarFxTest.java) (`catastrophicRegexInReplaceAllAbortsInsteadOfHanging`). - **FIND-13 · SHOULD.** In an app whose main content is a list ([FIND-03](https://pauta-project.dev/6.0.0/templates/find-bar/#find-03) says which apps those are), the filter box filters the names as plain words are typed, turns `key:value` terms into chips and runs a command after `>`. A command puts the focus in the box (`filter` in Torrenta), bound to `Ctrl+K`, `Cmd+K` on macOS, and the box draws that command's chord as a key badge. - *Check (code):* the box's text listener filters the names by the plain words, turns a `key:value` term into a chip and runs the command typed after `>`; a registered command focuses the box, on `Ctrl+K` (`Cmd+K` on macOS); and the badge in the box is read from that command's chord, not written out. - *Reference:* Torrenta [`Omnibox`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/Omnibox.java), [`MainWindow.buildFilterBar`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java). - **FIND-14 · SHOULD.** In an app whose main content is a list ([FIND-03](https://pauta-project.dev/6.0.0/templates/find-bar/#find-03) says which apps those are), Escape in the 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`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java). - **FIND-15 · SHOULD.** In an app whose main content is a list ([FIND-03](https://pauta-project.dev/6.0.0/templates/find-bar/#find-03) says which apps those are), 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 (in Torrenta, undo and the saved views' `Ctrl+Alt+1…9`, `Cmd+Alt+1…9` on macOS) do not fire while a text field has focus: `Ctrl+Z` (`Cmd+Z` on macOS) 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`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java), [`MainWindow`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java) window chords. - **FIND-16 · MUST.** A control of a find bar or of a filter box leaves the Tab order only when the keyboard does what it does another way: a registered command does the same, or the bar's own field handles a key that does. So the Next, Previous and Close buttons may leave it, since Enter, Shift+Enter and Escape in the field do the same ([FIND-06](https://pauta-project.dev/6.0.0/templates/find-bar/#find-06), [FIND-07](https://pauta-project.dev/6.0.0/templates/find-bar/#find-07)), and so may a field's clear button, since the field's editing keys empty it. An option's toggle (match case, whole word, regular expression) stays in it unless a command toggles that option. A list app's filter box leaves it ([FIND-15](https://pauta-project.dev/6.0.0/templates/find-bar/#find-15)) because its command puts the focus there ([FIND-13](https://pauta-project.dev/6.0.0/templates/find-bar/#find-13)). A terminal's bar is no exception: Tab belongs to the shell only while the terminal has the focus, so a toggle taken out of the Tab order there needs a command like any other. - *Why:* [KBD-15](https://pauta-project.dev/6.0.0/keyboard/#kbd-15) lets a control out of the Tab order only when the keyboard does its work another way. A toggle that is out of it with no command can be changed with the mouse alone. - *Check (code):* for every control of a find bar or filter box that is set not focus-traversable, a registered command does what the control does, or the bar's field handles a key that does: Enter, Shift+Enter or Escape for Next, Previous and Close, the editing keys for a clear button. A toggle that is not focus-traversable has a command that toggles its option. An app with no find bar and no filter box has no such control: nothing breaks this rule and it passes, the missing bar being [FIND-01](https://pauta-project.dev/6.0.0/templates/find-bar/#find-01)'s finding. - *Reference:* Editora's [`FindReplaceBar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/FindReplaceBar.java) keeps every button and option box in the Tab order, all but the clear button inside each field. Its [`ConsoleFindBar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/ConsoleFindBar.java) and [`TerminalFindBar.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/TerminalFindBar.java) take Previous, Next and Close out of it, which Shift+Enter, Enter and Escape in the field do, and leave the field and the match-case toggle in. The app template's [`DebugLogFindBar.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/DebugLogFindBar.java) takes the same three out: Previous and Next run `debugLog.findPrevious` and `debugLog.findNext`, Close is the field's Escape, and the Match Case box stays in. Torrenta's filter box is out of it and reached by its `filter` command ([`MainWindow.buildFilterBar`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MainWindow.java)). In Mirada's [`BookmarksWindow.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/BookmarksWindow.java) the three kind toggles are out of it and have a command each (`bookmarks.listAll`, `bookmarks.listBookmarked`, `bookmarks.listNotes`). Termina's [`SearchBar.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/SearchBar.java) leaves only its field in the Tab order: the two arrows and Close are the field's Enter, Shift+Enter and Escape, and the arrows its `findNext` and `findPrevious` commands too, but its regex toggle doesn't meet the rule yet: it is out of the Tab order and no command toggles it. ## Message Log (MLOG) https://pauta-project.dev/6.0.0/templates/message-log/: The family's Message Log: the session's status-bar messages, newest first, opened from the status bar. ### Spec - **MLOG-08 · SHOULD.** The Message Log is a card in the window's in-scene overlay host, anchored just above the status bar's echo area, never a separate window: 773 px wide, its list 336 px high, at the default zoom, holding the newest 200 messages of the session (the cap [DIAG-01](https://pauta-project.dev/6.0.0/diagnostics/#diag-01) asks for). - *Why:* the log answers "what just happened?" next to the line that said it; a separate window, or another size and cap, makes the same log look and behave differently from app to app. - *Check (code):* the log adds its node to the overlay host (no `Stage`), with width 773, list height 336 and a cap of 200. - *Reference:* Editora [`ui/MessageLogPopup.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MessageLogPopup.java) (`WIDTH`, `LIST_HEIGHT`) and [`ui/MessageLog.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MessageLog.java) (`MAX_ENTRIES`); the app template's [`ui/MessageLogView.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/MessageLogView.java). Torrenta's card is 640 × 300, and Termina's log is a separate window that keeps 500 messages. ### Behavior - **MLOG-02 · SHOULD.** A click on the status bar's unread-error count opens the Message Log, as a click on the echo area does ([WIN-01](https://pauta-project.dev/6.0.0/window-shell/#win-01)), and so does the `view.messageLog` command. - *Check (code):* the unread-error count runs `view.messageLog` on a click, and the command is registered. - *Reference:* Editora [`StatusBar`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/StatusBar.java) (`echo`, `unreadErrors`), [`StatusBar.showMessageLog`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/StatusBar.java). - **MLOG-03 · SHOULD.** The active keymap's cancel chord or a click outside closes the Message Log, as Esc does. - *Check (code):* the Message Log closes on the chord the active keymap binds to its cancel command, not on a fixed `Ctrl+G`, and a press outside the log closes it: on the backdrop, where the log is the in-scene card [MLOG-08](https://pauta-project.dev/6.0.0/templates/message-log/#mlog-08) asks for. In an app with one key table (a terminal app's keymap, or the built-in table of an app that ships no keymap files), the chord is the one that table binds to a cancel command; where it binds none, Esc and the press outside are all there is to test. - *Reference:* Editora [`OverlayHost`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/OverlayHost.java), which hides the card on a press on its backdrop and on [`PickerKeys.isCancel`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/PickerKeys.java): Esc, or the chord the keymap binds to `edit.cancel` (Editora's id; `C-g` in its Emacs keymap). Its [`MessageLogPopup`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MessageLogPopup.java) also closes on `Ctrl+G` whatever the keymap, though the CUA keymap binds `C-g` to `nav.goToLine`; its handler reads `Alt+G` too, which the Emacs keymap's `M-g` prefix takes first. Elsewhere the chord is fixed: `Ctrl+G` in the app template ([`ui/OverlayHost.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/OverlayHost.java)), Termina ([`ui/MessageLogWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/MessageLogWindow.java)) and Mirada ([`ui/MessageLogView.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/MessageLogView.java)). Torrenta's ([`ui/MessageLogPopup.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MessageLogPopup.java)) closes on Esc and on a press on its backdrop: Torrenta has no keymap and no cancel command, so the chord asks nothing more of it. - **MLOG-04 · SHOULD.** The Message Log copies the selected entries on the platform's copy chord, `Ctrl+C` (`Cmd+C` on macOS), in every keymap, and on the active keymap's copy chord too. - *Check (code):* the Message Log's key handling copies the selected entries on C with the platform's shortcut modifier down (`isShortcutDown`), whatever the active keymap binds to copy, and also on the chord the active keymap binds to its copy command (`M-w` in an Emacs keymap), read from the keymap and not written into the handler. - *Reference:* for the platform's chord, Editora [`MessageLogPopup.copySelection`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MessageLogPopup.java), on a fixed shortcut-down C, and the Message Logs of Torrenta ([`ui/MessageLogPopup.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/ui/MessageLogPopup.java)), Termina ([`ui/MessageLogWindow.java`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/src/main/java/com/termina/ui/MessageLogWindow.java)), Mirada ([`ui/MessageLogView.java`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/src/main/java/com/mirada/ui/MessageLogView.java)) and the app template ([`ui/MessageLogView.java`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/src/main/java/com/example/app/ui/MessageLogView.java)), each the same way. For the keymap's chord, no app yet: none of the five reads the keymap's copy binding in its log, and Editora's Emacs keymap binds copy to `M-w`, which its log does not read. Editora doesn't hold the first half under that keymap on Windows and Linux either: the keymap starts longer chords with `C-c`, a prefix the window's key dispatcher ([`command/KeyDispatcher.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/command/KeyDispatcher.java)) consumes in a scene filter, ahead of the log's own. - **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 post the message as an error directly (Editora's status bar has an error channel for that). - *Check (code):* one function gives a message's severity from its key by those rules (Editora's `StatusSeverity.ofKey`). A test that asserts it is the surest evidence. - *Reference:* Editora [`ui/StatusSeverity.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/StatusSeverity.java) (`ofKey`), [`StatusSeverityTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/StatusSeverityTest.java). - **MLOG-06 · SHOULD.** Opening the Message Log, or clearing it, resets the unread-error count. - *Check (code):* opening the Message Log marks it read, and clearing it zeroes the count (Editora's `markRead` and `clear`). - *Reference:* Editora [`MessageLog.markRead`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MessageLog.java), [`MessageLog.clear`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/MessageLog.java), [`StatusBar.showMessageLog`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/StatusBar.java). - **MLOG-07 · SHOULD.** An unread error is never evicted from the Message Log silently: the unread-error count keeps it even when the entry drops off the end. - *Check (code):* the Message Log counts unread errors apart from the entries it holds, so dropping an unread error at the cap leaves the count as it was. A test that asserts it is the surest evidence. - *Reference:* Editora [`MessageLogSeverityTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/ui/MessageLogSeverityTest.java) (`anEvictedErrorStillCounts`). ## Settings Sync (SYNC) https://pauta-project.dev/6.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". Such data is what a person builds up in the app by hand and would set up again on another computer: snippets, templates, shortcuts, profiles, presets, bookmarks, saved views. - *Check (by hand):* open Settings, search "sync", and land on the Sync page. An app that keeps none of the data the statement lists is outside the rule. - *Reference:* Editora [`ui/SettingsSync.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsSync.java) (the service) and [`ui/SettingsSyncPage.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsSyncPage.java), built by [`SettingsWindow`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/ui/SettingsWindow.java) (`Category.SYNC`). Termina, Torrenta and the app template have Settings Sync too. Modula, Mirada and nux keep such data (presets, bookmarks, profiles) and have no Settings Sync yet. - **SYNC-02 · SHOULD.** In an app with Settings Sync ([SYNC-01](https://pauta-project.dev/6.0.0/templates/settings-sync/#sync-01)), 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. Refusing a URL with a password or token in it is [SET-15](https://pauta-project.dev/6.0.0/settings/#set-15). - *Check (code):* the app's sync code runs `git` against the URL the user gave, with their own Git credentials, and talks to no server or account of the app's own. - *Reference:* Editora [`sync/`](https://github.com/adriandeleon/Editora/tree/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/sync) package ([`SyncEngine`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/sync/SyncEngine.java), [`SyncMerge`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/sync/SyncMerge.java), [`SyncAccount`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/sync/SyncAccount.java)), [`SyncEngine.hasCredentials`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/main/java/com/editora/sync/SyncEngine.java); Termina carries the same package, Torrenta its own [`sync/`](https://github.com/adriandeleon/torrenta/tree/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/sync) with [`SyncEngine`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/sync/SyncEngine.java) and [`SyncAccount`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/src/main/java/com/torrenta/sync/SyncAccount.java); the page's [Spec](https://pauta-project.dev/6.0.0/templates/settings-sync/#spec). ## Packaging, signing and release (REL) https://pauta-project.dev/6.0.0/release/: jpackage, JReleaser, the five-target matrix, macOS/Linux/Windows signing and CI. ### Targets - **REL-01 · MUST.** jpackage builds the installers for five targets, Linux x64 and arm64, macOS arm64 and x64, and Windows x64, each on its own runner, through a Maven profile that packages the app (`dist` in Editora). - *Check (code):* the release workflow's build matrix has a leg for each of the five targets (`linux-x64`, `linux-arm64`, `macos-arm64`, `macos-x64` and `windows-x64` in Editora), each on a runner of that OS and architecture, and each leg builds with a profile of `pom.xml` that runs jpackage, whatever the profile is called. The runner images under [Targets](https://pauta-project.dev/6.0.0/release/#targets) are Editora's: another image of the same OS and architecture meets it (Termina, Torrenta, Mirada, Modula and nux build macOS arm64 on `macos-latest`). - *Reference:* Editora [`release.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/release.yml) (the `build` job), [`pom.xml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/pom.xml) (`dist`). The template and the five other apps name their profile `dist` too. - **REL-02 · SHOULD.** Downloads are named `--.`. - *Check (code):* the release-asset check builds the expected names this way. - *Reference:* Editora [`scripts/release/CheckRelease.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/scripts/release/CheckRelease.java) (`expectedAssets`). - **REL-03 · MUST.** **JReleaser** (`jreleaser.yml`) builds nothing: it creates the GitHub release, attaches every file and `checksums_sha256.txt`, and runs the packagers of [REL-12](https://pauta-project.dev/6.0.0/release/#rel-12) and [REL-13](https://pauta-project.dev/6.0.0/release/#rel-13) where the app has them. - *Check (code):* `jreleaser.yml` has no step that compiles or packages the app: it attaches the build matrix's files and the checksums file, and its `brew` and `winget` packagers, where the app has them, take those same files. The job that runs it needs the build jobs. - *Reference:* Editora [`jreleaser.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/jreleaser.yml), the `release` job in [`release.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/release.yml). - **REL-04 · SHOULD.** The release notes are the version's section of `CHANGELOG.md`. - *Check (code):* the release job gives that section to the step that publishes (JReleaser, by [REL-03](https://pauta-project.dev/6.0.0/release/#rel-03)) as the release's notes. - *Reference:* Torrenta [`scripts/release/ReleaseNotes.java`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/release.yml). - **REL-06 · SHOULD.** The default branch 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 the default branch ends in `-SNAPSHOT`, and `release.yml` has the bump job. - *Reference:* Editora's `bump` job in [`release.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/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 the one that publishes compares the gathered files with the expected list. - *Reference:* Editora's "Verify the expected release assets" step in [`release.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/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` to the fully qualified name of the app's own class that extends `Application`: `com.editora.App` in Editora, `com.modula.ModulaApp` in Modula. - *Reference:* Editora [`packaging/linux/Editora.desktop`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/packaging/linux/Editora.desktop), Torrenta [`packaging/linux/Torrenta.desktop`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/packaging/linux/Torrenta.desktop), Modula [`packaging/linux/Modula.desktop`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/packaging/linux/Modula.desktop). The template, Termina, Mirada and nux set theirs the same way. - **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/`](https://github.com/adriandeleon/torrenta/tree/52d47c02ac57d8671d1e58d268b96a5532dbb00a/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 packaging build (Editora's `dist` profile) runs a training launch with `-XX:AOTCacheOutput`, and the Linux release legs install `xvfb`. - *Reference:* Editora [`scripts/aot_build.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/scripts/aot_build.java); Termina's and Mirada's [`scripts/aot-train.sh`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/scripts/aot-train.sh). ### Install methods - **REL-11 · MUST.** The GitHub release offers every download of every target: the `.dmg`, `.msi`, `.deb`, `.rpm`, `.AppImage` and `.tar.gz`, with checksums. Which target gets which type is under [Targets](https://pauta-project.dev/6.0.0/release/#targets). - *Check (code):* the files the release attaches include each of these types and a checksums file: the files `jreleaser.yml` lists or, in a workflow that publishes another way, the ones its publishing step uploads. That JReleaser is what publishes is [REL-03](https://pauta-project.dev/6.0.0/release/#rel-03). - *Reference:* Editora [`jreleaser.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/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.** The Homebrew and winget packagers ([REL-12](https://pauta-project.dev/6.0.0/release/#rel-12), [REL-13](https://pauta-project.dev/6.0.0/release/#rel-13)) read one repository secret, a classic personal access token with `repo` scope (`PACKAGES_TOKEN` in Torrenta, Termina and the app template). Without it JReleaser skips both packagers, 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):* the release workflow passes a secret of the repository to JReleaser as the two packagers' token, whatever the secret is called, and leaves both packagers out when it is empty. - *Reference:* the publishing jobs of Torrenta's [`release.yml`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/.github/workflows/release.yml), Termina's [`release.yml`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/.github/workflows/release.yml) and the app template's [`release.yml`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/.github/workflows/release.yml), which read `PACKAGES_TOKEN` and exclude the packagers without it. ### 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`, or a script it runs, 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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/release.yml), [`packaging/macos/Editora.entitlements`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/packaging/macos/Editora.entitlements). All six apps sign, notarize, staple and run `spctl`; Editora, Termina, Mirada, Modula and nux then launch the notarized app. Torrenta does not yet: its "Smoke-test the packaged app" step launches the signed app before it is notarized, and its "Notarize the dmg (macOS)" step in [`release.yml`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/.github/workflows/release.yml) ends at `spctl`. Mirada's steps are in [`scripts/sign-mac.sh`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/scripts/sign-mac.sh) and [`scripts/notarize-mac.sh`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/scripts/notarize-mac.sh). - **REL-16 · MUST.** Linux downloads are signed with the one shared OpenPGP release key ("Adrian De Leon (release signing)") in a job of their own, apart from the build legs (`sign-linux` in Editora): `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):* the release workflow has a job apart from the build legs, whatever it is called, that reads the release key and its passphrase from the repository's secrets (`LINUX_GPG_KEY` and `LINUX_GPG_PASSPHRASE` in Editora), signs each `.rpm` and `.deb` and writes an `.asc` beside every Linux file; and `packaging/linux/signing-key.asc` exists, and the release attaches that public key (as `editora-signing-key.asc` in Editora). - *Reference:* Editora [`scripts/release/sign-linux-packages.sh`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/scripts/release/sign-linux-packages.sh), [`scripts/release/check-linux-signatures.sh`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/scripts/release/check-linux-signatures.sh). Done in Editora, the app template, Torrenta, Termina, Mirada and Modula, all with the same key; nux has no `sign-linux` job and no committed key 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 (code):* the release workflow has an `actions/attest-build-provenance` step whose subjects cover every file the release attaches. The test that keeps the two lists the same is [QUAL-15](https://pauta-project.dev/6.0.0/quality/#qual-15)'s. - *Reference:* Editora's "Attest build provenance" step in [`release.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/release.yml), [`ReleaseSupplyChainTest`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/src/test/java/com/editora/packaging/ReleaseSupplyChainTest.java). Done in Editora, the app template, Termina and Mirada. ### CI/CD (GitHub Actions) - **REL-19 · MUST.** The CI workflow (`ci.yml` in Editora) runs on every push to the default branch and every pull request, with two checks: the format check of [PLAT-10](https://pauta-project.dev/6.0.0/platform/#plat-10) (`spotless:check`; the job Editora names **Format**) and the build with its tests (`./mvnw verify`, coverage gate included; Editora's **Build & Test**), on the JDK [PLAT-01](https://pauta-project.dev/6.0.0/platform/#plat-01) names. Both are required status checks for the default branch. - *Check (code):* the CI workflow triggers on `push` to the default branch and on `pull_request`. One of its jobs is the Format job of [PLAT-10](https://pauta-project.dev/6.0.0/platform/#plat-10), which runs `spotless:check` and neither builds nor tests, and its jobs between them run the whole suite and `verify` with the coverage gate: one job that runs `./mvnw verify`, or, as in Editora, jobs that run `test` in shards and one that runs `verify` over their results. What the jobs are called is the app's own. A workflow that lacks a trigger or one of the two checks fails the rule. That the default branch requires both is a repository setting, which no file shows. An audit run from the app's checkout alone reports the rule as `not-checked` and says what would settle it. - *Reference:* Editora [`ci.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/ci.yml), on `master` (its `format` job, its four `tests` shards and its `build` job, which runs `verify` over the shards' results); the app template's [`ci.yml`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/.github/workflows/ci.yml) and Termina's [`ci.yml`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/.github/workflows/ci.yml), on `master`, and Mirada's [`ci.yml`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/.github/workflows/ci.yml), on `main`, each with a job for `spotless:check` and one for `verify`. Torrenta ([`ci.yml`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/.github/workflows/ci.yml)), Modula ([`build.yml`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/.github/workflows/build.yml)) and nux ([`ci.yml`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/.github/workflows/ci.yml)) don't yet: none has a format check of its own. Torrenta's and Modula's one test job runs `./mvnw verify`, which their poms bind `spotless:check` to, so a single status stands for both checks; nux's pom has no Spotless, and its job runs `./mvnw test`, not `verify`. Modula's and nux's builds have no coverage gate either ([PLAT-12](https://pauta-project.dev/6.0.0/platform/#plat-12)). No file of any of them shows the required checks. - **REL-20 · MUST.** The tests run on all three OSes: the pure suite (no JavaFX toolkit) on Linux, macOS and Windows, and the FX suite on Linux and at least one more. They run there every day or on every pull request. How the runs are split is the app's own: one workflow that runs everything on every pull request meets this, and so does a quick workflow for pull requests with a fuller one on a schedule. A release waits for these runs on its own commit, on all three OSes: that it waits at all is [REL-30](https://pauta-project.dev/6.0.0/release/#rel-30). - *Why:* path separators, line endings, case-insensitive file systems and process spawning fail on one OS only, and the pure suite is where they show; the FX suite catches layout and focus differences. The FX suite is the slow one (three shards on macOS in Editora), so it is asked on two OSes and not three: the third is covered by the pure suite alone. - *Check (code):* taken together, the workflows' test jobs run the pure suite on `ubuntu-*`, `macos-*` and `windows-*` runners and the FX suite on `ubuntu-*` and one more, under a `schedule` or a `pull_request` trigger that needs no label; and the tests a release waits for ([REL-30](https://pauta-project.dev/6.0.0/release/#rel-30)) ran on those runners, in the release workflow itself or in the run it reads. - *Reference:* Editora splits them: [`ci.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/ci.yml) runs the whole suite on Linux on every pull request, and [`full-tests.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/full-tests.yml) the pure suite on Windows and macOS and the FX suite on macOS, in three shards, daily, on a pull request labeled `full-ci` and before every release: the "Check that the Full tests passed on this commit" step in [`release.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/release.yml). It lists flaky tests in the job summary ([`scripts/ci/ReportFlakes.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/scripts/ci/ReportFlakes.java)). The app template splits them the same way, and its release calls [`full-tests.yml`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/.github/workflows/full-tests.yml) itself. Termina ([`ci.yml`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/.github/workflows/ci.yml)), Torrenta ([`ci.yml`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/.github/workflows/ci.yml)), Mirada ([`ci.yml`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/.github/workflows/ci.yml)), Modula ([`build.yml`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/.github/workflows/build.yml)) and nux ([`ci.yml`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/.github/workflows/ci.yml)) run the whole suite on the three OSes on every pull request. - **REL-21 · MUST.** The release workflow (`release.yml` in Editora) runs on a version tag (`v*` meets it; the version-shaped `v[0-9]+.[0-9]+.[0-9]+*` is the better pattern, since a tag like `vendor-import` doesn't match it), with `workflow_dispatch` as a dry run that builds and signs and publishes nothing. The tag matching the pom is [REL-05](https://pauta-project.dev/6.0.0/release/#rel-05), the tests it waits for [REL-30](https://pauta-project.dev/6.0.0/release/#rel-30), the release-asset check [REL-07](https://pauta-project.dev/6.0.0/release/#rel-07), and the bump to the next snapshot [REL-06](https://pauta-project.dev/6.0.0/release/#rel-06). - *Check (code):* the release workflow triggers on a tag pattern that starts with `v` and on `workflow_dispatch`. A dispatched run goes through the build and signing jobs and publishes nothing: the step that publishes runs in a mode that publishes nothing (JReleaser's `--dry-run`), or the job that publishes runs only for a tag (an `if:` on the ref). - *Reference:* Editora [`release.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/release.yml), whose "JReleaser" step takes `release --dry-run` on a dispatch; the template, Termina, Torrenta and Mirada pass JReleaser `--dry-run` the same way. Modula's [`release.yml`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/.github/workflows/release.yml) and nux's [`release.yml`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/.github/workflows/release.yml), which have no JReleaser, run their publishing job only for a tag (`if: startsWith(github.ref, 'refs/tags/…')`). - **REL-30 · MUST.** A release is cut only from a commit whose tests passed: the release workflow runs the suite before it builds the installers, or a preflight job reads CI's result for the tagged commit and stops when it is not green. - *Why:* the build legs often skip the tests (`-DskipTests`), and a tag can be pushed on any commit, so without this a release can be cut from code whose checks failed or never ran. - *Check (code):* in the release workflow, every job that publishes needs, directly or through the jobs between, a job that settles the tests on the tagged commit: it runs them (a Maven run that reaches the `test` phase, `./mvnw test`, `package`, `verify` or `install`, with no `-DskipTests` and no `-Dmaven.test.skip`, or a call to the full-tests workflow), or it reads the conclusion of the CI run on `GITHUB_SHA` and fails on anything but success. - *Reference:* both ways are in use, and all seven release workflows meet it. A preflight that reads CI: Editora's "Check that CI passed on this commit" step in [`release.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/release.yml) ([`scripts/release/CheckRelease.java`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/scripts/release/CheckRelease.java) `ci`, which waits up to 30 minutes for the required checks; its build legs run `-DskipTests`), and Torrenta's "Require CI on this commit" step in [`release.yml`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/.github/workflows/release.yml), which reads the newest `ci.yml` run on the commit and starts one when there is none. The suite in the release: the template's `full-tests` job in [`release.yml`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/.github/workflows/release.yml) calls `full-tests.yml` before `build`; the "Build, test and package" step of Termina's [`release.yml`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/.github/workflows/release.yml) and Mirada's [`release.yml`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/.github/workflows/release.yml) runs `./mvnw … verify` on every build leg; Modula's "Build the installer" step in [`release.yml`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/.github/workflows/release.yml) runs `package` with the tests; nux's build legs run a "Test" step (`./mvnw test`) before they package, in [`release.yml`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/.github/workflows/release.yml). In each of the five the job that publishes needs the build legs, directly or through the signing and asset-check jobs. Mirada's [`codecs.yml`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/.github/workflows/codecs.yml) also creates a GitHub release, of the codec libraries its build downloads by checksum: that is a dependency, not a release of the app, and the app's own release runs the suite with them. - **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/`, and in a composite action under `.github/actions/` where the repository has one, ends in a 40-character SHA and a comment naming its version (`# v6.1.0`, `# 2.5.0`, `# v2`), never a branch such as `# main`. The `v2` in Editora's and Torrenta's `jreleaser/release-action … # v2` names that action's `v2` line, whose head the SHA is; the template, Termina and Mirada pin its 2.5.0 release. - *Command:* `[ -f pom.xml ] || { echo 'not an app root: no pom.xml here'; exit 1; }; [ -d .github/workflows ] || { echo 'no .github/workflows'; exit 1; }; ! grep -rhE '^[[:space:]]*-?[[:space:]]*uses:' .github/workflows .github/actions 2>/dev/null | grep -vE 'uses:[[:space:]]*\./' | grep -vE '@[0-9a-f]{40}[[:space:]]+#[[:space:]]*v?[0-9]'` - *Reference:* Editora [`.github/workflows/`](https://github.com/adriandeleon/Editora/tree/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.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`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/dependabot.yml). - **REL-24 · MUST.** Every workflow starts from `permissions: contents: read`, or from less; only a job that needs write access asks for it, in its own block. - *Check (code):* each workflow has a top-level `permissions` that grants no write: `contents: read`, or less (`permissions: {}`); and every `write` sits in a job's own `permissions`. - *Reference:* Editora [`release.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/release.yml): `release` (publish), `bump` (the pull request) and `preflight` (start a Full tests run). Modula's [`notify-catalog.yml`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/.github/workflows/notify-catalog.yml) starts from `permissions: {}`. - **REL-25 · SHOULD.** Every `actions/setup-java` step caches Maven's repository (`cache: maven`). The JDK it sets up is [PLAT-01](https://pauta-project.dev/6.0.0/platform/#plat-01)'s. - *Check (code):* each `setup-java` step has `cache: maven`. - *Reference:* Mirada ([`ci.yml`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/.github/workflows/ci.yml)), Modula and nux, on every step. Editora ([`ci.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/ci.yml), [`release.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/release.yml)), the app template, Termina and Torrenta each have a `setup-java` step without it. Editora sets up Temurin for its tests and Liberica for the release build, for linux-aarch64 coverage. - **REL-26 · MUST.** Every job that runs steps has `timeout-minutes`. A job that calls a reusable workflow (`uses:` in place of `steps:`) takes no `timeout-minutes`: GitHub does not accept the key there, and the called workflow's own jobs carry theirs. - *Check (code):* in every workflow, every job with `steps:` sets `timeout-minutes` on the job itself; a timeout on one of its steps does not stand for it. A job with `uses:` and no `steps:` is not judged. - *Reference:* every job of Editora's five workflows ([`ci.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/ci.yml), [`full-tests.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/full-tests.yml), [`release.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/release.yml) and the rest), of the template's three, Termina's two and Mirada's five sets one; the template's `full-tests` job in [`release.yml`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/.github/workflows/release.yml), which calls `full-tests.yml`, carries none, as the rule says, and nor does the `winget` job of Mirada's [`release.yml`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/.github/workflows/release.yml), which calls `winget.yml`. Torrenta, Modula and nux don't yet: the two jobs of Torrenta's [`ci.yml`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/.github/workflows/ci.yml) and the one of its [`engine-soak.yml`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/.github/workflows/engine-soak.yml) set none (its `release.yml` does); no job in Modula's three workflows ([`build.yml`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/.github/workflows/build.yml), [`release.yml`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/.github/workflows/release.yml), [`notify-catalog.yml`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/.github/workflows/notify-catalog.yml)) or in nux's two ([`ci.yml`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/.github/workflows/ci.yml), [`release.yml`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/.github/workflows/release.yml)) sets one: each app has it on one step only, the one that notarizes. - **REL-31 · MUST.** Every workflow that runs on pull requests has a `concurrency` group that cancels a superseded pull-request run, and never a run on the default branch. - *Check (code):* every workflow with a `pull_request` trigger has a `concurrency` block whose `group` is shared by the runs of one pull request and by no run on the default branch (keyed by `github.ref`, or by the pull request's number), and whose `cancel-in-progress` is true for a pull-request run: true, or an expression that is true there. And in that workflow `cancel-in-progress` is never true for a run on the default branch, whatever starts it (a push, a schedule, or a run started by hand, which `workflow_dispatch` allows on any branch): it is an expression that is false there, and it may be plain true only in a workflow that nothing can start on the default branch. A workflow with no `pull_request` trigger is not judged. - *Reference:* Editora [`ci.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/ci.yml) and [`full-tests.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/full-tests.yml) (`cancel-in-progress: ${{ github.event_name == 'pull_request' }}`, in a group keyed by the pull request's number). The template's ([`ci.yml`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/.github/workflows/ci.yml), [`full-tests.yml`](https://github.com/adriandeleon/adl-desktop-app-template/blob/b1ba438e61bce02fcbc389f1775f34a7def1ee31/.github/workflows/full-tests.yml)), Termina's ([`ci.yml`](https://github.com/adriandeleon/Termina/blob/6de43a19b7185a25c01cdf506a6286719b1991ff/.github/workflows/ci.yml)) and Mirada's ([`ci.yml`](https://github.com/adriandeleon/Mirada/blob/a3a84ec5e8227b1886e3dd920ab2b030aa3a2ba1/.github/workflows/ci.yml)) pull-request workflows use the same expression, Termina's and Mirada's in a group keyed by `github.ref`. Editora's third pull-request workflow, [`terminal-image.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/terminal-image.yml), doesn't yet: its `cancel-in-progress` is plain true, and beside pull requests and pushes to `probe/**` it can be started by hand, so a second run started on `master` cancels the first. Torrenta, Modula and nux don't either: Modula's [`build.yml`](https://github.com/adriandeleon/Modula/blob/518300a4c2114909315fbd3a73acc999fb4c16b5/.github/workflows/build.yml) and nux's [`ci.yml`](https://github.com/adriandeleon/nux/blob/d374ec4ee3f2eff0f7d378797884e6b81520ce20/.github/workflows/ci.yml) run on pull requests with no `concurrency` block, so they cancel nothing, and Torrenta's [`ci.yml`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/.github/workflows/ci.yml) sets `cancel-in-progress: true` for its pushes to `master` as well. - **REL-27 · MUST.** A CI run leaves its results where they can be read without running it again: it uploads the surefire reports even when tests fail, uploads the JaCoCo report, and writes the coverage totals to the job summary. - *Check (code):* the step that uploads the surefire reports runs under `if: always()`, a step uploads the JaCoCo report, and a step appends the coverage totals to `$GITHUB_STEP_SUMMARY`. - *Reference:* Editora's "Upload test reports and coverage data" and "Summarise coverage" steps in [`ci.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/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 in [`release.yml`](https://github.com/adriandeleon/Editora/blob/c9a28545f5be0b1411dc07ab7ca07bed010d13fd/.github/workflows/release.yml) 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):* the release workflow runs the packaged launcher on each OS (a Linux, a macOS and a Windows leg) before the step that publishes. - *Reference:* Torrenta's "Smoke-test the packaged app" step in [`release.yml`](https://github.com/adriandeleon/torrenta/blob/52d47c02ac57d8671d1e58d268b96a5532dbb00a/.github/workflows/release.yml) runs the launcher in the image of each of its three targets, one per OS. Editora runs only the notarized macOS app (`--version`, `--check-terminal`).