Add deterministic manifest-backed static assets

.claude/skills/apple-platform-guide/usage/action-sheet.md

@@ -0,0 +1,89 @@
+# UI::ActionSheet
+
+A modal sheet of choices presented at the bottom of the screen on iOS. **Tier 3 (iOS-gated).** Cross-platform code uses `UI::ActionSheetWithWebFallback` which delegates to the iOS gated class on `-Dios` builds and an accessible web fallback elsewhere.
+
+## Default experience
+
+- **iOS:** Routes through SwiftKit's `ConfirmationDialogFacade` which uses SwiftUI's `.confirmationDialog(titleKey:isPresented:titleVisibility:actions:message:)`. **Phase 10D-polish iter 2 (2026-05-27)** extended the facade to take parallel `actionLabels` / `actionStyles` / `actionTokens` arrays so the iOS surface honors any number of actions. The cancel-style button is automatically pinned at the bottom by SwiftUI; destructive-style buttons render in red.
+- **iPadOS:** Same as iOS but presented as a popover anchored to the source view by SwiftUI default.
+- **macOS:** `NSAlert(alertStyle: .informational)` with the actions as alert buttons (system-drawn).
+- **web (wide / narrow):** Use `UI::ActionSheetWithWebFallback`. Wide → modal centered card; narrow → bottom-anchored sheet with vanilla-JS swipe-to-dismiss.
+- **Android:** Material `BottomSheetDialogFragment`.
+
+## Crystal API
+
+```crystal
+# Minimal invocation (iOS only — Tier 3 gate)
+sheet = UI::ActionSheet.new("Title", "Optional message")
+sheet.add_action("Primary") { do_thing }
+sheet.add_action("Cancel", :cancel)
+sheet.is_presented = true
+
+# Cross-platform — use the with-fallback wrapper
+sheet = UI::ActionSheetWithWebFallback.new("Title", "Optional message")
+sheet.add_action("Primary") { do_thing }
+sheet.add_action("Cancel", :cancel)
+sheet.is_presented = true
+```
+
+```crystal
+# Realistic Voyager invocation
+# samples/initiative-cross-platform-ui-voyager/screens/todos_screen.cr:249-275
+if share_id = state.pending_share_todo_id
+  target = state.find_todo(share_id)
+  sheet_title = target ? "Share \"#{target.title}\"" : "Share todo"
+  share_sheet = UI::ActionSheetWithWebFallback.new(sheet_title, "Choose how to share this todo.")
+  share_sheet.add_action("Copy to Clipboard") {
+    Voyager.dispatch(:copy_pending_share)
+    nil
+  }
+  share_sheet.add_action("Print This Todo") {
+    Voyager.dispatch(:print_pending_share)
+    nil
+  }
+  share_sheet.add_action("Cancel", :cancel) {
+    Voyager.dispatch(:cancel_pending)
+    nil
+  }
+  share_sheet.is_presented = true
+  share_sheet.test_id = "voyager-todos-share-sheet"
+  share_sheet.accessibility_label = "Share options"
+  root << share_sheet.as(UI::View)
+end
+```
+
+## Behavior contract
+
+- **Callbacks:** Each `Action#action : Proc(Nil)?` fires when the user taps that button. **Phase 10D-polish iter 2:** all actions fire (no longer dropped at the binary-degradation boundary).
+- **Dismissal paths:**
+  - Tap action → dismisses, fires the chosen action's Proc.
+  - Tap Cancel → dismisses, fires cancel action (if any).
+  - iOS swipe-down from sheet handle → fires no action; the screen is responsible for clearing the pending flag.
+- **Focus / keyboard:** System-managed. Destructive style highlights the action red (iOS).
+- **Reduced motion:** SwiftUI handles automatically.
+- **Reactivity:** `is_presented` is a plain property today (not reactive like `UI::Sheet`); the Voyager pattern is to mutate state + Rerender, which produces a new ActionSheet view tree.
+
+## Customization knobs
+
+| Property | Type | Default | Effect |
+|----------|------|---------|--------|
+| `title` | `String` | `""` | Sheet title. Empty hides the title row. |
+| `message` | `String` | `""` | Secondary message. Empty hides the message row. |
+| `actions` | `Array(Action)` | `[]` | Action list. Each carries `label`, `style` (`:default` / `:destructive` / `:cancel`), and optional `Proc(Nil)?`. |
+| `is_presented` | `Bool` | `false` | Modal visibility. |
+
+## Override path
+
+**Default chrome is system-resolved.** ActionSheet inherits SwiftUI's `.confirmationDialog` chrome which is system-drawn.
+
+**Override paths:**
+
+- **Multi-action support:** RESOLVED by Phase 10D-polish iter 2 (`B-ACTIONSHEET-MULTI-ACTION`). The iOS facade now iterates `view.actions` natively; all actions render and fire callbacks. The action list can be any length; SwiftUI handles layout.
+- **Material override:** ActionSheet does not support material override (system-drawn chrome by HIG mandate).
+- **Tier 3 gating:** building without `-Dios` fails compile at any `UI::ActionSheet.new(...)` site. Use `UI::ActionSheetWithWebFallback` for cross-platform code.
+
+## Evidence
+
+- **Canonical example:** `samples/initiative-cross-platform-ui-voyager/screens/todos_screen.cr:249-275`
+- **Screenshot:** `docs/initiative-cross-platform-ui/handoff/phase-10-d-polish-screenshots/04_actionsheet_share.png`
+- **Spec coverage:** `spec/web/ui/views/action_sheet_with_web_fallback_spec.cr`

.claude/skills/apple-platform-guide/usage/alert.md

@@ -0,0 +1,83 @@
+# UI::Alert
+
+A modal alert dialog for critical confirmations — title, message, and a small set of role-differentiated action buttons. SwiftUI's `.alert(...)` is fully system-drawn; the framework forwards the title + message + buttons and lets the platform paint the chrome.
+
+## Default experience
+
+- **iOS:** SwiftUI `.alert(title, isPresented:, actions:, message:)`. System-drawn modal card centered over the host scene, blurred backdrop, vibrant title, secondary message, role-coloured buttons (destructive = red, cancel = bold/blue). Tapping any button dismisses the alert.
+- **iPadOS:** identical to iOS.
+- **macOS:** AppKit visit emits `NSAlert` (system-drawn modal sheet attached to the host window). Destructive role uses NSAlert critical style.
+- **web wide:** HTML `<dialog>` overlay with backdrop; framework-rendered (no SwiftUI). Role buttons styled via `.--destructive` / `.--cancel` CSS classes.
+- **web narrow:** same as web wide.
+- **Android:** Material `AlertDialog`.
+
+## Crystal API
+
+```crystal
+# Minimal invocation
+alert = UI::Alert.new("Delete?", "This action cannot be undone.")
+alert.add_button("Cancel", :cancel)
+alert.add_button("Delete", :destructive) { state.delete }
+alert.is_presented = true
+```
+
+```crystal
+# Realistic Voyager invocation
+# samples/initiative-cross-platform-ui-voyager/screens/todos_screen.cr:225-247
+if delete_id = state.pending_delete_todo_id
+  target = state.find_todo(delete_id)
+  title_text = target ? "Delete \"#{target.title}\"?" : "Delete this todo?"
+  alert = UI::Alert.new(title_text, "This can't be undone.")
+  alert.add_button("Cancel", :cancel) {
+    Voyager.dispatch(:cancel_pending)
+    nil
+  }
+  alert.add_button("Delete", :destructive) {
+    Voyager.dispatch(:confirm_delete)
+    nil
+  }
+  alert.is_presented = true
+  alert.test_id = "voyager-todos-delete-alert"
+  alert.accessibility_label = "Confirm delete"
+  root << alert.as(UI::View)
+end
+```
+
+## Behavior contract
+
+- **Callbacks:** Each `AlertButton#action : Proc(Nil)?` fires synchronously when the user taps the corresponding button. No callback fires on system-dismiss (escape on macOS, tap-outside on web); the convention is to wire dismiss-equivalent to the Cancel button.
+- **Dismissal paths:**
+  - Button tap → dismisses, fires action.
+  - macOS escape key → triggers the `:cancel`-roled button if any; else dismisses without action.
+  - iOS swipe-to-dismiss NOT applicable (system alerts are modal-only).
+- **Focus / keyboard:** System-managed. Default focus on the trailing button (typically destructive or confirmation) per HIG.
+- **Reduced motion:** SwiftUI / AppKit handle reduced motion automatically; alerts already use minimal animation.
+- **Reactivity:** `is_presented=` is reactive — the property setter pushes through the SwiftKit bridge so post-render mutation drives the alert presentation. The Voyager pattern: mutate `state.pending_delete_todo_id` + dispatch Rerender → the screen's `build(ctx)` re-emits the alert with `is_presented = true`.
+
+## Customization knobs
+
+| Property | Type | Default | Effect |
+|----------|------|---------|--------|
+| `title` | `String` | (required) | Bold title. |
+| `message` | `String` | `""` | Secondary message. Empty = no message line. |
+| `buttons` | `Array(AlertButton)` | `[]` | Action buttons (label + style symbol + optional `Proc(Nil)?`). |
+| `is_presented` | `Bool` | `false` | Modal visibility. Reactive setter. |
+| `material_semantic` | `Symbol?` | `nil` | Per HIG, alert chrome is `:system_resolved` — this property is inert on the active SwiftUI `.alert` path; preserved for cross-platform symmetry. |
+
+`AlertButton#style` accepts `:default`, `:cancel`, `:destructive`. SwiftUI maps these to `ButtonRole.destructive` / `.cancel` / nil.
+
+## Override path
+
+**Default chrome is system-resolved.** Apple HIG explicitly recommends letting the system paint alert chrome — overriding is generally inappropriate.
+
+**Override paths:**
+
+- **Button order:** SwiftUI controls placement based on role. To force a specific order, ship buttons in the order you want (the framework preserves the array order).
+- **Custom backdrop / colors:** NOT supported. The `material_semantic` property is preserved for API symmetry but does nothing on the active `.alert` path (documented in `swift/AssetPipelineSwiftKit/Sources/AssetPipelineSwiftKit/Facades/AlertFacade.swift:7-15`). If a brand needs custom alert chrome, use `UI::Sheet` with `surface_style: :grouped_card` and a custom button row instead. **Backlog item: `B-ALERT-CUSTOM-CHROME`** — `docs/initiative-cross-platform-ui/architecture/intent-backlog.md`.
+- **Confirmation alerts with destructive default focus:** ship the destructive button last; SwiftUI auto-focuses the trailing action.
+
+## Evidence
+
+- **Canonical example:** `samples/initiative-cross-platform-ui-voyager/screens/todos_screen.cr:225-247`
+- **Screenshot:** `docs/initiative-cross-platform-ui/handoff/phase-10-d-polish-screenshots/03_alert_delete_confirm.png`
+- **Spec coverage:** `spec/web/ui/views/alert_spec.cr`

.claude/skills/apple-platform-guide/usage/date-picker.md

@@ -0,0 +1,84 @@
+# UI::DatePicker
+
+A calendar-based date selection control. Renders as iOS's native `UIDatePicker` chrome (compact field that opens a calendar popover on tap), `NSDatePicker` on macOS, or a native picker on Android. Date / time / datetime modes are selectable via the `mode` property.
+
+## Default experience
+
+- **iOS:** SwiftUI `DatePicker(label, selection: ..., displayedComponents: .date)` — renders as the compact field that taps to reveal a calendar popover (iOS 14+ default). `mode == :time` switches to `.hourAndMinute`; `mode == :datetime` to `[.date, .hourAndMinute]`.
+- **iPadOS:** identical to iOS.
+- **macOS:** SwiftUI `DatePicker` on macOS renders as a stepper-styled textfield with a calendar-icon affordance. Date-only mode = simple field; datetime mode = field + time stepper.
+- **web wide:** HTML `<input type="date" />` / `<input type="time" />` / `<input type="datetime-local" />`.
+- **web narrow:** same as web wide (mobile browsers provide native date-pickers automatically).
+- **Android:** Material `DatePicker` modal.
+
+## Crystal API
+
+```crystal
+# Minimal invocation
+picker = UI::DatePicker.new(UI::DatePickerMode::Date)
+picker.label = "Deadline"
+picker.on_change = ->(t : Time) { ... }
+```
+
+```crystal
+# Realistic Voyager invocation
+# samples/initiative-cross-platform-ui-voyager/screens/todos_screen.cr:391-422
+picker = UI::DatePicker.new(UI::DatePickerMode::Date)
+picker.label = "Deadline"
+picker.accessibility_label = "Todo deadline"
+picker.test_id = "voyager-editor-sheet-deadline"
+if !seed_deadline.empty?
+  begin
+    picker.selected_date = Time.parse_utc(seed_deadline, "%Y-%m-%d")
+  rescue Time::Format::Error
+    picker.selected_date = Time.utc
+  end
+else
+  picker.selected_date = Time.utc
+end
+picker.on_change = ->(t : Time) {
+  d2 = Voyager.dispatcher
+  unless d2.nil?
+    d2.current_form_state.update("deadline", t.to_utc.to_s("%Y-%m-%d"))
+  end
+  nil
+}
+body << picker.as(UI::View)
+```
+
+## Behavior contract
+
+- **Callbacks:** `on_change : Proc(Time, Nil)?` — fires on every value change. iOS may fire multiple times during scrubbing.
+- **Dismissal paths:** The popover dismisses on tap-outside or selecting a date (system-managed). The picker itself is inline.
+- **Focus / keyboard:** Field is focusable via Tab; keyboard input opens the system date picker dropdown.
+- **Reduced motion:** SwiftUI handles automatically.
+- **Reactivity:** `selected_date` is NOT reactive today — setting it post-render does not push to the SwiftUI side. To change the displayed date after mount, mutate domain state + Rerender.
+
+## Customization knobs
+
+| Property | Type | Default | Effect |
+|----------|------|---------|--------|
+| `selected_date` | `Time` | `Time.utc` | Initial / current date. |
+| `mode` | `DatePickerMode` | `Date` | `Date` / `Time` / `DateTime`. |
+| `minimum_date` | `Time?` | `nil` | Earliest selectable date (inclusive). |
+| `maximum_date` | `Time?` | `nil` | Latest selectable date (inclusive). |
+| `label` | `String` | `""` | Caption shown alongside the picker. |
+| `on_change` | `Proc(Time, Nil)?` | `nil` | Change handler. |
+| `style` | `DatePickerStyle` | `Automatic` | **Phase 10D-polish iter 2.** `Automatic` / `Compact` / `Graphical` / `Wheels`. Maps to SwiftUI `.datePickerStyle(.compact)` / `.graphical` / `.wheel`. `Automatic` lets the platform pick (iOS date mode defaults to `.graphical`; we recommend `Compact` for in-form usage so the picker shows as an inline button with a calendar popover). |
+
+## Override path
+
+**Public knobs cover mode + bounds + change handler + style.**
+
+**Override paths:**
+
+- **Picker style (compact vs graphical vs wheels):** RESOLVED by Phase 10D-polish iter 2 (`B-DATEPICKER-STYLE-PROPERTY`). Set `picker.style = UI::DatePickerStyle::Compact` / `Graphical` / `Wheels` / `Automatic`.
+- **Nilable / clearable state:** today the picker has no nil value; "no date" must be represented in app state. The Voyager pattern uses a sibling `Clear` button that resets the FormState entry to empty string (`samples/initiative-cross-platform-ui-voyager/screens/todos_screen.cr:432-444`).
+- **iOS class-init gap with `Time.local`:** `Time.local` segfaults on iOS due to `[[crystal-ios-class-init-gap]]`. Use `Time.utc` for seed values; date-only mode doesn't care about timezone. Backlog: `B-CRYSTAL-IOS-TIME-LOCAL` (covered by the broader iOS class-init gap remediation).
+- **Date display year offset:** the Crystal-to-Swift epoch conversion path (`view.selected_date.to_unix.to_f64` → `Date(timeIntervalSince1970:)`) currently shows an incorrect year (`May 27, 3995` instead of `May 27, 2026` in the editor screenshot). **Backlog item: `B-DATEPICKER-EPOCH-CONVERSION`** — needs investigation of whether Crystal `to_unix` is returning the wrong base, or Swift is misinterpreting the Float64. Tracked in `docs/initiative-cross-platform-ui/architecture/intent-backlog.md`.
+
+## Evidence
+
+- **Canonical example:** `samples/initiative-cross-platform-ui-voyager/screens/todos_screen.cr:391-422`
+- **Screenshot:** `docs/initiative-cross-platform-ui/handoff/phase-10-d-polish-screenshots/06_datepicker_deadline.png` (note: year display is off — backlog `B-DATEPICKER-EPOCH-CONVERSION`)
+- **Spec coverage:** `spec/web/ui/views/date_picker_spec.cr`