Native Settings and the preference flow

What the user gets

One window, five pages (a tab strip; Ctrl+Tab, Ctrl+Shift+Tab and Ctrl+PageUp/PageDown also switch pages):

Below every page, Settings shows the running app version, taken from the same Cargo workspace version as the executable’s file properties. GitHub Releases opens GitHub Releases in your default browser. Check now makes one bounded GitHub request on a worker, only when clicked. The disabled button shows “Checking…” while Settings remains usable. The status says “You have the latest version.”, “Version X.Y.Z is available”, or “Couldn’t check for updates.” An available result makes GitHub Releases open that release’s validated page, and explains updating: run the new setup, or exit and replace the portable exe. Nothing is downloaded or installed.

Check for updates automatically starts unchecked for new installs and upgrades. Apply or OK saves consent; Cancel discards it. There is no first-run prompt. When enabled, a one-shot timer waits at least three minutes after startup, resume or unlock, and checks at most once per 24 hours. Failed checks are quiet and wait for the next daily opportunity. A manual check also advances that deadline. One tray notification per newer version says “ElevenClock-rs X.Y.Z is available”; clicking opens the validated release page. Windows may suppress notifications (for example, Do Not Disturb); they are not retried.

Both buttons support Tab then Enter or Space; status changes are announced to screen readers. A release-opening failure appears in the Settings status. Closing Settings cancels a manual check; automatic checks continue without the dialog. Turning the option off, locking, suspending or pausing cancels automatic work and removes its wakeup; late results cannot notify. Exit never waits for the network. Requests time out after ten seconds overall, accept at most 64 KiB, never overlap, and respect server rate-limit backoff, persisted across restarts. Managed copies show “managed by your organization” beside the version, hide both buttons and the automatic checkbox and reject request dispatch, because their launcher handles updates. See ADR 0003 for data sent and GitHub retention.

Buttons: Exit ElevenClock-rs, Reset to defaults, OK, Cancel, Apply.

The window uses the Windows 11 text font (Segoe UI Variable) and the Mica material behind its title bar, through the documented DWMWA_SYSTEMBACKDROP_TYPE. The client area keeps standard themed controls, so it follows high contrast and screen readers unchanged; Windows builds without Mica simply show the plain title bar.

Flow

Preview and year-boundary semantics

The preview always shows the current time and the documented examples, with the ISO week-year each belongs to, so the difference between %g (ISO week-year) and %y (calendar year) is visible instead of implied:

The token help beside the editor lists every directive the core accepts (a test compares it with format::DIRECTIVES) and explains that %G/%g are the year the ISO week belongs to. Two-line formats show line 1 ↵ line 2.

Messages (always beside the control)

Fit is measured, not guessed: Runtime hands the draft to the same DirectWrite measurement the overlay surface uses (Renderer::plan_fit), against the clock slot discovered for each taskbar the selection would use, at that taskbar’s DPI, using the same worst-case lines (leap day, ISO week 53, AM/PM). If a taskbar has no proven clock slot, or nothing was discovered yet, there is nothing to measure and Apply is not blocked; the paint path still reports a later overflow, and Settings shows that as a notice when it is open.

Implementation notes

• All rules live in the portable clock_windows::settings_model (Draft, SettingsController, Evaluation, Problems, ApplyOutcome, LayoutCheck) and are unit-tested on any OS with a fake store and a fake layout.
• SettingsWindow owns the PreferenceSession and is serviced from the one message loop. Window procedures only queue values; nothing re-enters the runtime from a callback.
• preferences_store::UnavailableStore is used when the per-user data folder cannot be resolved: the clock runs on defaults, and every save fails visibly instead of being lost at the next start.
• Multi-line edit controls send no EN_CHANGE when their text is set from outside the process (automation, some assistive technology), so the controls, not the notifications, are read at the start of every command. Input that arrives as a sent message never wakes GetMessageW, so each queued event also posts a wake message to the dialog.

Fit-check caching

Settings retains one draft format’s sampled worst-case candidates. Repeated fit checks reuse successful measurements while rendered text, selected clock slots, DPI, font size and the runtime appearance/font revision are unchanged. A different format replaces the candidate cache; unavailable or failed measurements are never cached as successful fits. Both caches are bounded to the current draft/check. Operation-count guards for this cache and for the worst-case resampling are listed in contributing.

Action audit

Audited for issue #82: the existing small typed interaction::MenuCommand model already owns command IDs and the fixed menu. No additional action abstraction is needed for current behavior.

Pause/Resume is available through the shared menu; Settings does not duplicate it. Settings opening and Exit are unconditional requests, so their small native adapters contain no competing availability policy. Unsupported preference versions disable saving in the Settings model and remain protected at the store boundary. These layers enforce different boundaries rather than duplicating action policy. Revisit this audit when adding an entry point or conditional action; centralize proven shared availability/behavior in portable typed logic and test every affected source. Do not unify draft commands, OS registration and clock actions speculatively.