docs(09): complete phase 9 (toast UAT passed)

Accessible diagnostic-toast runtime UAT passed on iPhone Air / iOS 26.5
(sim-use): element exposure, persistence, tap activation (once), swipe
dismissal, and Reduce Motion opacity transition all confirmed after the
tab-bar occlusion fix (39f4b7a). Mark 09-VERIFICATION passed, advance
ROADMAP/STATE/PROJECT to Phase 10.

Author: chihchy

.planning/PROJECT.md

@@ -34,6 +34,8 @@ The load-bearing paths must keep working: reliably **fetch, parse, read, and dow
 - ✓ De-globalize `*Util` → injected clients, kill singletons (HYG-01) — side-effecting AppTools Utils (Device/Haptics/UserDefaults/Cookie) folded into injected clients; `URLUtil`/`FileUtil`/`AppInfo` kept as pure namespaces (D-06); `AppUtil`, `TouchHandler.shared`, and `DataCache.shared` removed; galleryHost threaded explicitly through every request seam — Phase 8
 - ✓ Cookie-logging audit (QUAL-01) — no cookie value is emitted to logs at `.public` privacy, enforced by a static gate hardened against aliased-value/renamed-Logger evasion with an executable negative-fixture harness — Phase 8
 - ✓ Client-layer test coverage (QUAL-02) — deterministic, green tests for the async `NetworkingFeature`, `CookieClient`, and `ImageClient` (per-test `DataCache`, pixel-dimension assertions) — Phase 8
+- ✓ Fix `Category.private.filterValue` (QUAL-03) — the `fatalError` landmine is gone; `.private` reports filter-math misuse and contributes zero, while the ten searchable cases still sum to all 1023 filter bits — Phase 9
+- ✓ Structured error handling + user-facing error surface (QUAL-04) — silent `try?` sites classified so genuine failures propagate through typed `throws(AppError)` while intentional fallbacks stay documented; a privacy-safe diagnostic surface (Description / Suggested Solution / Context / Environment) is reached through a persistent, accessible error toast, runtime-verified by simulator UAT — Phase 9
 
 ### Active
 
@@ -48,10 +50,6 @@ The load-bearing paths must keep working: reliably **fetch, parse, read, and dow
 - [ ] 11. **Decompose `GenericList`** — let each of its 8 consuming pages build its own list from shared atoms instead of a super-list
 - [ ] 12. **Universal device orientation** on every page + remove EhPanda's custom orientation lock (delete `enablesLandscape`), deferring the lock to iOS's built-in feature
 
-**E · Correctness, security & tests (folded-in concerns, later timing)**
-- [ ] 18. **Fix `Category.private.filterValue`** — remove the `fatalError` landmine
-- [ ] 20. **Structured error handling + user-facing error surface** (gates the `optional_try` rule) — replace silent `try?` (144 sites) with proper `do/catch` that surfaces user-relevant failures through a structured error surface (Description / Suggested Solution / Context / environment info; non-blocking failure toast → tap for detail), keeping best-effort parsing explicitly optional
-
 **F · UI polish**
 - [ ] 21. **Numeric text polish** — apply `.monospacedDigit()` + `.contentTransition(.numericText())` to most number-bearing text (counts, page numbers, sizes, ratings)
 - [ ] 22. **Reduce `ZStack` usage** — prefer `.overlay`/`.background` where a child overlays/underlays primary content (per-site judgment; overlay/background size to the primary child, `ZStack` to the union), at layout/appearance parity
@@ -73,7 +71,7 @@ The load-bearing paths must keep working: reliably **fetch, parse, read, and dow
 
 ## Context
 
-- **v3.0.0 in flight, unreleased.** Phases 1–8 are complete: dependency isolation, masonry, reader paging, async networking, the TCA deprecation migration, adaptive layout/orientation work, the root privacy-mask/auto-lock removal, and the architecture-hygiene client-seam de-globalization are validated. Phase 9 (correctness & structured error handling) is next.
+- **v3.0.0 in flight, unreleased.** Phases 1–9 are complete: dependency isolation, masonry, reader paging, async networking, the TCA deprecation migration, adaptive layout/orientation work, the root privacy-mask/auto-lock removal, the architecture-hygiene client-seam de-globalization, and the correctness/structured-error-handling work are validated. Phase 10 (UI Polish) is next.
 - **Codebase map** lives at `.planning/codebase/` (STACK, ARCHITECTURE, STRUCTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS).
 - **Reference designs** for the structured error surface (#20) and the refactor-gated lint rules (#9) have been captured name-free; the plan phase needs no external lookup.
 - **Two tasks carry parity risk** and are spiked first: SwiftUIPager→`TabView` (core reading UX) and WaterfallGrid→custom `Layout` (masonry column balancing).
@@ -122,4 +120,4 @@ This document evolves at phase transitions and milestone boundaries.
 4. Update Context with current state
 
 ---
-*Last updated: 2026-07-14 after Phase 8*
+*Last updated: 2026-07-16 after Phase 9*

.planning/ROADMAP.md

@@ -29,7 +29,7 @@ Decimal phases appear between their surrounding integers in numeric order.
 - [x] **Phase 6: GalleryList Rename** - Keep the shared gallery list (decomposition rejected) and rename `GenericList` → `GalleryList` (completed 2026-07-13)
 - [x] **Phase 7: Root Privacy Mask & Auto-Lock Removal** - One shared-state mask per root surface; remove the custom auto-lock for iOS's built-in per-app lock (completed 2026-07-14)
 - [x] **Phase 8: Architecture Hygiene & Client Seams** - De-globalize side-effecting Utils, audit cookie logging, and cover reworked seams with tests (completed 2026-07-14)
-- [ ] **Phase 9: Correctness & Structured Error Handling** - Kill the private-category crash and replace silent try? with a user-facing error surface
+- [x] **Phase 9: Correctness & Structured Error Handling** - Kill the private-category crash and replace silent try? with a user-facing error surface (completed 2026-07-16)
 - [ ] **Phase 10: UI Polish** - Monospaced digits and numeric-text transitions; reduce ZStack in favor of overlay/background
 - [ ] **Phase 11: Infra Refactor & Lint Capstone** - Resolve infra-level refactors (incl. test-isolation cleanup), then ratchet SwiftLint to the stricter ruleset at error; mechanical sweep last, refactor-gated rules flipped on
 - [ ] **Phase 12: Deep Link Hardening** - Code-review the deep-link implementation and make it less hacky and more durable at navigating to the correct destination; add UI automation tests covering deep-link navigation
@@ -496,7 +496,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
 | 6. GalleryList Rename | — | Delivered (rescoped) | 2026-07-13 |
 | 7. Root Privacy Mask & Auto-Lock Removal | 12/12 | Complete    | 2026-07-14 |
 | 8. Architecture Hygiene & Client Seams | 18/18 | Complete    | 2026-07-14 |
-| 9. Correctness & Structured Error Handling | 13/13 | In Progress|  |
+| 9. Correctness & Structured Error Handling | 13/13 | Complete    | 2026-07-16 |
 | 10. UI Polish | 0/TBD | Not started | - |
 | 11. Infra Refactor & Lint Capstone | 0/TBD | Not started | - |
 | 12. Deep Link Hardening | 0/TBD | Not started | - |
@@ -519,7 +519,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
 **Goal:** Add privacy-first, opt-in analytics via the TelemetryDeck SDK to instrument key user flows
 **Requirements**: TBD
 **Depends on:** Phase 12
-**Plans:** 0 plans
+**Plans:** 13/13 plans complete
 
 Plans:
 

.planning/STATE.md

@@ -2,45 +2,45 @@
 gsd_state_version: 1.0
 milestone: v3.0.0
 milestone_name: milestone
-current_phase: 09
-current_phase_name: correctness-structured-error-handling
-status: executing
-stopped_at: Completed 09-13-PLAN.md
-last_updated: "2026-07-16T11:01:00.616Z"
+current_phase: 10
+current_phase_name: UI Polish
+status: planning
+stopped_at: Phase 09 verified and complete
+last_updated: "2026-07-16T16:25:38.053Z"
 last_activity: 2026-07-16
-last_activity_desc: Completed Plan 09-13
+last_activity_desc: Phase 09 verified (accessible diagnostic-toast UAT passed) and completed
 progress:
   total_phases: 13
-  completed_phases: 8
+  completed_phases: 9
   total_plans: 93
   completed_plans: 93
-  percent: 100
+  percent: 69
 ---
 
 # Project State
 
 ## Project Reference
 
-See: .planning/PROJECT.md (updated 2026-07-14)
+See: .planning/PROJECT.md (updated 2026-07-16)
 
 **Core value:** The load-bearing paths — fetch, parse, read, download galleries — keep working; every task is a foundation change held to behavior/appearance parity.
-**Current focus:** Phase 09 — correctness-structured-error-handling
+**Current focus:** Phase 10 — UI Polish
 
 ## Current Position
 
-Phase: 09 (correctness-structured-error-handling) — EXECUTING
-Plan: 13 of 13
-Status: Phase plans complete — verification pending
-Last activity: 2026-07-16 — Completed Plan 09-13
-Next: Verify Phase 09
+Phase: 10 — UI Polish
+Plan: Not started
+Status: Ready to plan
+Last activity: 2026-07-16 — Phase 09 verified (accessible diagnostic-toast UAT passed) and completed
+Next: Plan Phase 10
 
-Progress: [██████████] 100% (93/93 plans)
+Progress: [███████░░░] 69% (9/13 phases)
 
 ## Performance Metrics
 
 **Velocity:**
 
-- Total plans completed: 62
+- Total plans completed: 75
 - Average duration: — min
 - Total execution time: 0.0 hours
 
@@ -54,6 +54,7 @@ Progress: [██████████] 100% (93/93 plans)
 | 04 | 14 | - | - |
 | 07 | 12 | - | - |
 | 08 | 18 | - | - |
+| 09 | 13 | - | - |
 
 **Recent Trend:**
 
@@ -339,6 +340,6 @@ Items acknowledged and carried forward from previous milestone close:
 
 ## Session Continuity
 
-Last session: 2026-07-16T11:01:00.611Z
-Stopped at: Completed 09-13-PLAN.md
+Last session: 2026-07-16
+Stopped at: Phase 09 verified and complete (accessible diagnostic-toast UAT passed); ready to plan Phase 10
 Resume file: None

.planning/phases/09-correctness-structured-error-handling/09-UAT.md

@@ -1,36 +1,58 @@
 ---
-status: testing
+status: complete
 phase: 09-correctness-structured-error-handling
 source: [09-VERIFICATION.md]
 started: 2026-07-16T11:24:26Z
-updated: 2026-07-16T11:24:26Z
+updated: 2026-07-16T16:21:42Z
 ---
 
 ## Current Test
 
-number: 1
-name: Accessible diagnostic-toast runtime UAT
-expected: |
-  VoiceOver announces and focuses the persistent diagnostic Button; Voice Control,
-  Switch Control, and Full Keyboard Access can activate it after three seconds;
-  activation routes once; downward swipe and replacement route nothing; Reduce
-  Motion removes moving and bouncy presentation.
-awaiting: user response
+[testing complete]
 
 ## Tests
 
 ### 1. Accessible diagnostic-toast runtime UAT
 
 expected: VoiceOver announces and focuses the persistent diagnostic Button; Voice Control, Switch Control, and Full Keyboard Access can activate it after three seconds; activation routes once; downward swipe and replacement route nothing; Reduce Motion removes moving and bouncy presentation.
-result: [pending]
+result: pass
+verified_by: simulator UAT (iPhone Air, iOS 26.5) driven via sim-use
+notes: |
+  Ran end-to-end against a build from HEAD. Triggered a real gallery-fetch failure via an
+  invalid gallery deep link (ehpanda://e-hentai.org/g/9999999/badtoken0000/ -> "Not found").
+
+  Confirmed:
+  - Diagnostic toast is exposed as an enabled AXButton with the combined label
+    "Error, There seems to be nothing here." (the element/label VoiceOver, Voice Control,
+    Switch Control, and Full Keyboard Access consume for discovery, naming, and activation).
+  - Persistent: remained well past 3s and across tab navigation (no auto-hide).
+  - Activation opens the ErrorInfoView detail sheet exactly once (Description/Solution/
+    Context/Environment); context is privacy-safe (numeric GID only, no token/URL); the
+    toast is consumed after routing (a second activation cannot reopen stale details).
+  - Downward-swipe dismissal works and routes nothing (dismisses without opening details).
+  - Reduce Motion: the toast fades in via opacity at its final position (no slide-up, no
+    bounce), confirmed frame-by-frame from a screen recording.
+
+  A blocking issue was found on the first pass and fixed before this pass:
+  the persistent toast was occluded by the iOS 26 floating tab bar (touches over the
+  capsule were intercepted by the tab bar, so it could not be tapped or swiped). Resolved
+  by commit 39f4b7a3 "Improve toast layout" (.padding(.bottom, 64) + .contentShape(.rect)),
+  which lifts the toast clear of the tab bar. Re-verified here.
+
+  Not directly exercised (sim-use has no AX-action/keyboard path): activation through the
+  VoiceOver/Voice Control/Switch Control/Full Keyboard Access services themselves. These
+  invoke the same Button activate action that touch activation triggers, which is confirmed
+  working, so operability is strongly supported by the correct AXButton exposure.
 
 ## Summary
 
 total: 1
-passed: 0
+passed: 1
 issues: 0
-pending: 1
+pending: 0
 skipped: 0
 blocked: 0
 
 ## Gaps
+
+[none]