Pro Transition — Complete UI Specification

Line coverage: ProTransitionManagerTestable.swift 100% · refreshed 2026-05-27 by /coverage-explore

State Diagram

flowchart TD
    Start([App launched]) --> A["<b>[A] Welcome Letter</b>
Day 1
(copy varies by fresh install vs upgrade)"]
    A --> Day4Check{"Day 4
first switcher open?"}
    Day4Check -->|Yes| H["<b>[H] Day 4 Pro Tour Popover</b>"]
    Day4Check -->|"No switcher use"| SkipH["Skipped"]
    H --> Silent["Silent trial
Days 5-11"]
    SkipH --> Silent

    Silent --> D12{"Day 12
Active at 10-11:30 or 15:30-17?"}
    D12 -->|Yes| B["<b>[B] Heads-Up Popover</b>"]
    D12 -->|No| SkipB["Skipped"]
    B --> Badge["Badge dot on icon
Days 13-14"]
    SkipB --> Badge

    Badge --> Exp["<b>Day 15: Trial expired</b>
Remove badge dot
Degradable feature (Auto size) downgrades immediately;
style/shortcutStyle also downgrade. First switcher use
post-expiry triggers free-pass + [C] for any user;
engaged users also get one last Pro switcher session
(read() returns remembered values during free-pass)"]

    Exp --> Fork{"First event
after expiration?"}
    Fork -->|"Hard-gated feature triggered
(search, lockSearch, shortcut ≥ 2)"| FP["Free pass
Execute action once"]
    Fork -->|"First switcher open"| FP
    Fork -->|"10-11:30 or 15:30-17 arrives
no trigger fired"| D["<b>[D] Proactive Day 15</b>"]
    Fork -->|"No activity"| RetryD["Retry next day"]
    RetryD --> Fork

    FP --> C["<b>[C] Full Upgrade Window</b>"]
    C --> PostC["Hard-gate now active"]

    D --> Fork2{"Hard-gated feature
triggered later?"}
    Fork2 -->|Yes| FP2["Free pass
Execute action once"]
    Fork2 -->|"Never — only
degradable features used"| ToD21["To Day 21"]
    FP2 --> C

    PostC --> D21{"Day 21+
Active at 10-11:30 or 15:30-17?"}
    ToD21 --> D21
    D21 -->|Yes| F["<b>[F] Day 21 Popover</b>"]
    D21 -->|"Inactive until Day 35"| SkipF["Skip Day 21"]

    F --> D35{"Day 35+
Active at 10-11:30 or 15:30-17?"}
    SkipF --> D35
    D35 -->|Yes| G["<b>[G] Day 35 Final Window</b>"]
    D35 -->|"Inactive until Day 49"| GiveUp["Give up"]

    G -->|"Get Pro"| P(["✓ Purchased
All prompts stop, all gates removed"])
    G -->|"Don't ask again"| OO(["Opted out"])
    G -->|"Close ×"| SS

    GiveUp --> SS(["<b>Steady State</b>
E popover on every hard-gate attempt
Degradable: silent fallback
Purchase in Preferences"])
    OO --> SS

Note: Purchase at any point in the flow → all prompts stop, all gates removed, all indicators cleared. This exit applies from every state.

Note: [E] Hard-Gate Popover runs in parallel from the moment hard-gate is active. Any hard-gated feature attempt → [E]. This continues in Steady State, even after opt-out.

State Variables

Implementation note: hasPurchased is not stored — it is derived from LicenseManager.shared.state == .pro. All day references in the spec are 1-indexed (Day 1 = first day); in code, daysSinceTrialStart is 0-indexed (Day 1 = 0, Day 12 = 11, Day 15 = 14).

UI Components

Feature Gating Reference

All Pro prefs (style, size, shortcut style) downgrade to their Free equivalent immediately on trial expiry. ProTransitionManager.onProLockEngaged() fires on the state transition into .trialExpired / .proExpired, snapshotting the user's Pro selection into remembered* fields and writing the Free equivalent to stored. The user visually notices the degradation (e.g. Titles → Thumbnails) — this is the passive signal that something changed. Settings renders a gray "ghost" outline/background on the remembered option so the user sees what they used to have alongside the new Free selection. Any click on a Pro UI element while locked jumps to the Upgrade tab. On purchase, onProUnlocked() restores remembered → stored.

During an active free-pass session (ProTransitionManager.isFreePassSessionActive), PreferenceDefinition.read() reads the remembered* index back instead of stored — so the switcher renders the user's Pro selection for one last summon before [C]. Stored values stay at the Free equivalent throughout, so the Settings UI continues to show the locked experience even if it happens to read mid-session.

The difference between degradable and hard-gated prefs is what the user sees on the locked switcher:

• Pure degradable (Auto size only): silent fallback. No tailored header — [C] still fires on first switcher open with the .nonEngaged aspirational copy.
• Degradable + hard-gated (style, shortcut style): silent fallback PLUS the first switcher open reads back the remembered Pro selection for one last Pro session, then [C] shows with a tailored header.

The first post-expiration switcher open always triggers free-pass + [C] (one-shot, gated by hasTriggeredPostExpirationSwitcher). [D] Proactive Day 15 only fires if [C] hasn't fired yet (i.e. the user never opened AltTab after expiry). [C] Full Upgrade also fires on the first explicit hard-gate attempt (search, lockSearch, shortcut ≥ 2) via the free-pass ladder if the switcher wasn't opened first.

isProAvailable vs isProLocked

• isProAvailable — true for .trial and .pro. Used by hard-gate entry points (search, lockSearch, + shortcut beyond 1) to decide whether to execute directly or consult the free-pass ladder.
• isProLocked — true for .proExpired and .trialExpired (unconditionally — no grace period). Used by preference getters (appearanceStyle, appearanceSize, shortcutStyle) to downgrade to Free equivalents and by the Settings UI to show ghost affordances and intercept Pro clicks. Also gates the onSwitcherShown() post-expiration trigger. During an active free-pass session (ProTransitionManager.isFreePassSessionActive) the getters read from remembered* instead of stored so the user's Pro selection is honored for that one session — Settings continues to read free because the stored value never changes mid-session.

Edge Cases

Test scenarios

Mirrors ProTransitionTests.swift 1:1. The tests drive ProTransitionManagerTestable — a pure state struct + decision functions (evaluateTimedAction, evaluateHardGate, evaluateSwitcherOpen, shouldShowBadgeDot, isSchedulingComplete, isInTimeWindow) — so the entire flow above is verified deterministically without AppKit, windows, or real time.

Timed action: Day 1 Welcome

• testDay1_welcomeShows — [A] shows on first launch.
• testDay1_welcomeBlocksAllOtherActions — [A] is exclusive that day.

Timed action: Day 12 Heads-Up

• testDay12_headsUpShowsInTimeWindow — [B] shows on Day 12 inside the time window.
• testDay12_headsUpSkippedOutsideTimeWindow — skipped outside the window.
• testDay12_headsUpNotShownTwice — once-ever.
• testDay12_tooEarly — not before Day 12.

Timed action: Day 15 Proactive

• testDay15_proactiveShowsIfNoHardGate — [D] shows if no hard-gate fired yet.
• testDay15_proactiveSkippedIfFullUpgradeAlreadyShown — skipped once [C] has shown.
• testDay15_proactiveSkippedOutsideTimeWindow — window-gated.

Timed action: Day 21 Reminder

• testDay21_reminderShows — [F] shows ~Day 21.
• testDay21_reminderNotShownTwice — once-ever.

Timed action: Day 35 Final

• testDay35_finalShows — [G] shows ~Day 35.
• testDay49_givesUp — gives up after Day 49.

Timed action: Pro user

• testProUser_noTimedActions — purchasers get no prompts.
• testProUser_noTimedActionsEvenOnDay35 — still none at Day 35.

Hard-gate: trial active

• testHardGate_allowedDuringTrial — gated features run during the trial.
• testHardGate_allowedForProUser — and for Pro users.

Hard-gate: free pass

• testHardGate_freePassOnFirstAttempt — first post-expiry attempt gets a one-time free pass.
• testHardGate_fullUpgradeAfterFreePass — then [C] shows.

Hard-gate: post-[C] popover

• testHardGate_popoverAfterFullUpgrade — [E] fires on every hard-gate attempt after [C].

Hard-gate: [D]-shown-but-free-pass-unused edge

• testHardGate_freePassStillAvailableAfterProactiveDay15 — free pass survives a prior [D].

Hard-gate: opted out

• testHardGate_popoverStillFiresAfterOptOut — [E] still fires after opt-out (user-initiated).

Badge dot

• testBadgeDot_showsOnDays13and14 · testBadgeDot_notShownBeforeDay13 · testBadgeDot_removedOnDay15 · testBadgeDot_notShownForProUser

Scheduling completeness

• testSchedulingComplete_forProUser · testSchedulingComplete_afterOptOutAndDay35 · testSchedulingNotComplete_optedOutButDay35NotShown · testSchedulingComplete_allEventsShown · testSchedulingComplete_allEventsShown_fullUpgradeInsteadOfProactive

Time window (10:00–11:30 / 15:30–17:00)

• testTimeWindow_10am · testTimeWindow_1130am · testTimeWindow_330pm · testTimeWindow_4pm · testTimeWindow_5pm — inside.
• testTimeWindow_9am_outside · testTimeWindow_1131am_outside · testTimeWindow_1pm_gap · testTimeWindow_2pm_outside · testTimeWindow_230pm_outside · testTimeWindow_329pm_outside · testTimeWindow_501pm_outside · testTimeWindow_midnight — outside.

Switcher open: Day 4 Pro tour

• testSwitcherOpen_day4TourFiresFirstTime · testSwitcherOpen_day4TourNotShownTwice · testSwitcherOpen_day4TourSkippedOnDay3 · testSwitcherOpen_day4TourSkippedOnDay5 · testSwitcherOpen_day4TourSkippedForProUser

Switcher open: post-expiration trigger

• testSwitcherOpen_postExpirationFires · testSwitcherOpen_postExpirationNoopAfterTriggered · testSwitcherOpen_postExpirationNoopAfterFreePassConsumed · testSwitcherOpen_postExpirationNoopDuringTrial · testSwitcherOpen_proUserNoop

Full flows

• testFullFlow_degradableOnly — user who never trips a hard gate.
• testFullFlow_hardGateUser — user who does.
• testPurchase_stopsEverything — purchase halts all prompts/gates.
• testFullFlow_postExpirationSwitcherTrigger — engaged user: Day-15 open → free-pass + [C].
• testFullFlow_nonEngagedUser — non-engaged: Day-15 open → free-pass + [C] (.nonEngaged); [D] suppressed.

Edge case: Day 35 close ⨉ vs opt-out

• testDay35_closeDoesNotOptOut · testDay35_optOutStopsTimedButNotHardGate

Cross-event ordering (Day 21 vs Day 35)

• testDay35_skipsDay21WhenDueSimultaneously · testDay21_notShownOnOrAfterDay35 · testDay21_notShownPastDay49

Day 35 retry window

• testDay35_retriesOnDay36 · testDay35_retriesOnDay48

Day 49 give-up

• testSchedulingComplete_pastDay49EvenWithoutDay35

Day 12 skip-entirely

• testDay12_skipsEntirelyOnDay13 · testDay12_skipsEntirelyOnDay14

Day 15 Proactive — direct coverage

• testDay15_proactiveNotShownIfAlreadySeen · testDay15_proactiveShowsOnLaterDayIfStillNotShown