# N1 Settings The Settings destination for the Flutter client: server connection and the server-side workspace, in native Material controls and Cupertino controls on iOS. ## Files - `lib/features/settings/settings_screen.dart` — `SettingsScreen`. - `lib/features/settings/settings_controller.dart` — draft/validation, shared client actions, ping-on-connected, workspace persistence, dispose ownership. - `lib/features/settings/settings_store.dart` — `SettingsStore`, `SharedPreferencesSettingsStore`, `MemorySettingsStore`. - `lib/features/settings/settings_copy.dart` — the web/Android words, workspace validation, connection-card lines. - `lib/features/settings/default_endpoint.dart` — same-origin web default. - `lib/features/settings/settings_controls.dart`, `settings_sections.dart`, `settings_trust_warning.dart`, `settings_layout.dart`, `settings_keys.dart`. - `lib/features/settings/settings.dart` — public barrel for manager registration. - `test/features/settings/*` — copy, persistence, controller and widget tests. - `tool/settings_probe.dart`, `tool/settings_probe_server.dart`, `tool/settings_probe_capture.dart` — isolated browser fixture/capture entry. ## Manager registration ```dart import 'package:pipelines_app/features/settings/settings.dart'; SettingsScreen(client: sharedPipelinesClient) // optional: initialEndpoint: Uri?, store: SettingsStore?, ping: PingCallback? ``` `SettingsScreen` takes the shell's single `PipelinesClient`. It subscribes to `client.states`, sends `ping` once per connected transition (plus once when the screen opens against an already-connected client), and offers Connect / Disconnect / Reconnect. It never calls `client.dispose()` and never opens a connection on construction, so registering/rebuilding the screen cannot start a second socket or tear down another feature's connection. While connected it shows `Server build {version} ({commit})` and `Server time {time}` from the ping reply. Until that reply arrives the card says `Loading server details…`, so a request in flight is never reported as an unavailable value. Only a completed reply that omits a field renders `Server build unavailable` / `Server time unavailable`; a failed ping renders one explicit `Server details unavailable: …` line instead of repeating both "unavailable" lines. No zero or stale value is substituted. Disconnect and reconnect clear the previous server's details. Connection card copy and state lines follow `web/src/settings.js` and `SettingsScreen.kt`: `Not connected`, `Connecting (attempt N)…`, `Connected`, `Disconnected` + reason + `Retrying with backoff…`, plus the trusted-LAN/VPN warning. A dropped socket's attempt/backoff state comes from the transport. Workspace validation is the web rule: blank is untouched (no error), a relative path is rejected, Save is enabled only for a trimmed absolute path. The saved line is `Saved workspace: /path` or `Saved workspace: (none)`, and the helper states that the path is an absolute directory on the execution server, not the phone's storage. Save failures keep the previous saved value and say so. ## Persistence `shared_preferences` keys are owned by this feature: - `pipelines.next.serverUrl.v1` - `pipelines.next.workspace.v1` No legacy Android/web key (`server_url`, `workspace`, `pipelines.web.serverUrl.v2`, `pipelines.web.workspace.v1`, notification keys) is read, migrated or written. The endpoint is validated and persisted before `client.connect` is attempted, matching the web's write-before-connect behaviour; a value that fails to connect stays stored. When the store write itself fails, the screen still connects and says the value applies to this session only. Credentials in a URL are rejected before any write or socket. Only those two strings are stored; nothing else. The web `shared_preferences` implementation may namespace its keys internally; the logical keys above are the independent feature keys and tests assert the legacy keys stay untouched. ## Web default endpoint `defaultServerUrl()` returns `''` on native builds. On web it derives `ws(s):///connect` from `Uri.base` (`kIsWeb`, no `dart:html`), so the screen starts from the configurable same-origin proxy and no server host or production endpoint is baked into the app. The field remains editable and only the validated value is persisted. ## Verification - `flutter test test/features/settings` — 39 tests pass (copy/default endpoint, persistence keys/legacy isolation, controller connect/validation/ping/ disconnect/reconnect/backoff/dispose ownership/workspace errors, Material and Cupertino widgets, invalid URL, pending vs completed-empty ping, failed-ping single line, field labels in semantics, narrow + 2× text with full labels and helper copy, unmount ownership). - `flutter test` (full app) — 52 tests pass. - `flutter analyze` — no issues; `dart format --set-exit-if-changed` clean on the 19 Dart settings/test/tool files. - `flutter build web` (main) and `flutter build web -t tool/settings_probe.dart` — both built. - Real browser evidence from an isolated loopback probe server (`/connect` answers `ping` with `probe-1.2.3`/`abc1234`/time), headless Chrome over CDP: `settings-idle`, `settings-connected`, `settings-validation` (clicked Connect after an `http://` draft), `settings-workspace` (typed `/srv/pipelines`, clicked Save), `settings-dark`, `settings-ios`, `settings-narrow` (390×844, 1.6× text). See `public/settings-captures/manifest.md`. - Fix verification with a 6 s delayed pong: at 1.5 s the card shows `Connected` + `Loading server details…` (no "unavailable"), and after the pong it shows the real build/time. At 320×700/2× and 390×844/2× the full `Server URL`/`Workspace path (on the server)` labels and the complete helper and error sentences render (no ellipsis or line cap). See `public/settings-fix-captures/manifest.md`. - The 20 candidate paths are new and currently **untracked** (`??`, none ignored); landing must `git add` them. The candidate is left uncommitted per the stage instruction. ## Gaps / not done - Notifications are not part of this screen yet. The queue item names them, but the task scope here was connection/workspace and the project has no notification plugin; adding one needs a dependency decision. - No Templates card: navigation into the templates feature is shell/feature registration work owned elsewhere. - No protocol-mismatch warning (the web page shows one); it needs a shared protocol-version constant not present in the app yet. - Mobile builds/devices and the real production server were not used. The Cupertino rendering is shown through the web probe with an iOS platform theme, not on an actual iOS device. - The probe's `connected` capture is an automatic fixture connect; validation and workspace-save captures use actual browser clicks/typing. The main web entry (`lib/main.dart`) is still the scaffold and was not modified.