toolbar_Basic.md
# Readscape V1.0 — Reading Toolbar Spec


## Declaration
Use Apple Vision Pro native design patterns only.
All values reference `DesignSystem.Layout.*` / `DesignSystem.Animation.*` tokens.
Do NOT hardcode any numeric values.


## High-Level Requirement
Create a simple collapsible toolbar with 3 buttons: Mode/Environment/Layout.
- Follow native visionOS toolbar behavior like Control Center or Safari address bar.
- Phase 1: buttons display current selection only (submenu functionality reserved for Phase 2)

## Technical Constraints  
- Must NOT modify any FROZEN components

---

## 1. Native visionOS Style
- **Material:** `.glassBackgroundEffect(in: Capsule())` — matches main window glass material
- **Position:** Attached to window bottom via native `.ornament(attachmentAnchor: .scene(.bottom))` — no manual offset
- **Behavior:** Like native visionOS Control Center toolbar
- **Hover:** `.contentShape(.hoverEffect, Capsule())` + `.hoverEffect(.highlight)` — let visionOS handle the visual effect while ensuring correct hover geometry

---


## 2. Component Structure


### Collapsed State (Default)

- **Shape:** Perfect circle, 68×68pt (`toolbarCollapsedWidth` × `toolbarCollapsedHeight`)
- **Background:** `.glassBackgroundEffect(in: Capsule())` — `Capsule()` on a square frame renders as a circle
- **Icon:** `circle.dotted` (size: `toolbarCollapsedIconSize` = 40pt)
- **Icon Container:** `toolbarCollapsedIconContainerWidth` × `toolbarCollapsedIconContainerHeight` (44×44pt)
- **Hover:** MUST remain circular — `Capsule()` on square frame guarantees this

### Expanded State
- **Shape:** Capsule (pill), height: `toolbarExpandedHeight` (68pt), width: auto-adaptive
- **Background:** `.glassBackgroundEffect(in: Capsule())`
- **Content:** HStack of 3 `ToolbarButton` components (reused from `DesignSystem.swift`)
- **Width:** Auto-adaptive via hidden `PreferenceKey` measurement view (NOT `.fixedSize()` on shell)

---


## 3. Button Configuration

| Button | Icon | Default Label |
|--------|------|---------------|
| Mode | `book.pages.fill` | "Standard" |
| Environment | `mountain.2.circle` | "Passthrough" |  
| Layout | dynamic via `LayoutMode.iconName` | "Landscape" |

- Layout icon switches between `rectangle.landscape.rotate` and `rectangle.portrait.rotate` based on `selectedLayout`
- Button spacing: `toolbarExpandedButtonSpacing` (8pt)
- Content padding: `toolbarExpandedContentPadding` (12pt)


## 4. States & Animations

### 4.1 Fluid Morph (Collapsed → Expanded)
- **Technique:** Single `Color.clear` container with animated frame width + `Capsule()` shape
  - Collapsed: `frame(width: toolbarCollapsedWidth, height: toolbarCollapsedHeight)` — circle
  - Expanded: `frame(width: measuredExpandedWidth, height: toolbarExpandedHeight)` — capsule
- **Spring animation:** `DesignSystem.Animation.standardSpring`
- **Content transition:** `.transition(.opacity)` — icons/labels fade in during expand, fade out during collapse
- **Width measurement:** Hidden measurement view using `PreferenceKey` pre-calculates expanded width for smooth animation

### 4.2 Collapse Trigger
- **Manual Trigger:** User taps outside toolbar area (full-screen `Color.clear` tap target)
- **Auto Trigger:** User is NOT gazing at toolbar (`!isHovering`) AND `toolbarAutoCollapseTimeout` (3 seconds) elapses
- **Animation:** Reverse of expand animation (same spring)

---

## 5. Implementation Requirements

### 5.1 New File Creation
Create new file: `ReadingToolbar.swift`

### 5.2 Required Enums (in `ReadingEnums.swift`)

```swift
enum ToolbarState { case collapsed, expanded }

enum ReadingMode: String, CaseIterable, Identifiable {
    case standard = "Standard"
    case translation = "Translation"
    case `extension` = "Extension"
}

enum EnvironmentMode: String, CaseIterable, Identifiable {
    case passthrough = "Passthrough"
    case pineForest = "Pine Forest"
    case sunsetBeach = "Sunset Beach"
    case minimalistRoom = "Minimalist Room"
}

enum LayoutMode: String, CaseIterable, Identifiable {
    case landscape = "Landscape"
    case portrait = "Portrait"
    // Dynamic iconName: landscape → rectangle.landscape.rotate, portrait → rectangle.portrait.rotate
}
```

### 5.3 Additive Tokens (in `DesignSystem.swift`)

```swift
extension DesignSystem.Animation {
    static let toolbarAutoCollapseTimeout: Duration = .seconds(3)
}
```

### 5.4 ToolbarViewModel Integration
Properties in `ToolbarViewModel.swift`:
```swift
var selectedMode: ReadingMode = .standard
var selectedEnvironment: EnvironmentMode = .passthrough
var selectedLayout: LayoutMode = .landscape
```

### 5.5 ReadingView Integration
Attach via native ornament modifier in `ReadingView.swift`:

```swift
.ornament(attachmentAnchor: .scene(.bottom)) {
    ReadingToolbar()
}
```

---

## 6. Revision History & Post-Implementation Updates

### 6.1 Refactored Positioning to Native Ornaments
Removed manual 24pt vertical offsets. The toolbar positioning has been migrated to the native visionOS `.ornament` API to ensure flawless system-level centering and depth layering.

### 6.2 Material Changes  
Migrated from `Material.bar` to `.glassBackgroundEffect()` to establish visual consistency with the system's 3D glass rendering pipeline.

### 6.3 Fixed Hover Target Masking
Added `.contentShape(.hoverEffect, Capsule())` prior to applying `.hoverEffect(.highlight)`. This ensures that the hover state geometry dynamically adapts — rendering as a perfect circle when collapsed and expanding smoothly into a capsule layout.

### 6.4 Fixed Collapsed Tap Target Competing with Window
**Problem:** On real Vision Pro hardware, tapping the upper half of the collapsed toolbar frequently failed to trigger expand. The lower half worked reliably. Root cause: the ornament's upper half overlaps with the window content area, where `ReadingTextView`'s `.scrollInputBehavior(.enabled, for: .look)` competes for gaze-based input resolution.

**Fix:** Moved tap handling from `collapsedContent` overlay to the shell level:
1. Added `.contentShape(Capsule())` on the shell for interaction hit-testing — gives the entire glass surface tap priority over the window behind it
2. Added `.onTapGesture` at shell level (guarded by `!isExpanded`) — the glass surface itself is the tap target
3. Simplified `collapsedContent` to icon-only (no frame, contentShape, or tap gesture needed)

This ensures the full 68pt circle is a single, shell-level tap target that the system resolves with higher priority than the overlapping window content.

### 6.5 ToolbarButton Selected State Color
**Change:** Selected button background color migrated from `DesignSystem.Color.tintAccent.opacity(0.15)` to `Color.white.opacity(0.15)` — the native visionOS glass UI selected state background color. Icon and label foreground color for the selected state remains `DesignSystem.Color.tintAccent`