Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 12 additions & 16 deletions apps/desktop/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1834,12 +1834,12 @@ To check a bundle, point the DSN at a local listener, such as `http://<key>@127.
**Help > Stim Tutorial…** and the setup guide's **Take the Tutorial** button open
an inspector-width trailing column. It replaces the inspector until closed;
Cmd-Opt-I returns to the inspector. A new tutorial path opens it once, after open
sheets close. UserDefaults stores progress, skipped steps and whether the Commands section is open.
sheets close. UserDefaults stores progress and skipped steps.
Unfinished tours resume at launch when status lists the tracked path; archived
ones show Done. Closing preserves progress. Restart shows the agent prompt and
resets progress at once; see below for which worktrees count afterwards.
The three-minute workspace warning starts at the first Copy of the run prompt
and survives relaunch. Copying commands does not start it. Only archives
and survives relaunch. Only archives
removed after this run started can complete the tutorial.

The panel clones appandflow/stim-tutorial and follows: a tutorial workspace
Expand All @@ -1854,28 +1854,24 @@ tutorial version is 2, from the repository's `expo.extra.stimTutorial`. A stored
version 1 record is dropped and starts over on a version 2 workspace. Restart and
"take the tutorial" start a fresh record at the current time that forgets the old tour paths even
while the old worktrees are still registered; only linked worktrees whose creation time is after
that start count, and the oldest one becomes the tour. Both optional steps
keep Skip available.
that start count, and the oldest one becomes the tour. Every step has one Next
button: it records the step as done when its non-optional ticks are all done or
its checkpoint completed, and as skipped otherwise. Detected steps advance on
their own.
Pair a Phone opens the Pair a Phone wizard, which
turns on serving itself when the server is off. A pairing that exists when the step starts shows Done Already,
followed by "Open Stim on your phone: the tutorial workspaces are there".

Add Remote Machine opens the existing wizard using the tour workspace as its
checkout. With no machine configured, Skip is the primary action. Once a machine
checkout. Once a machine
is approved, the step shows a prompt that names the approved machine, or asks you to
name it when none is recorded. The commands include that name. Approval completes the step and preserves its handoff across status polls;
name it when none is recorded. Approval completes the step and preserves its handoff across status polls;
an iOS build offloaded after the step started ticks the optional "Build ran on another
Mac" check. Completed optional steps stay expanded so their handoff remains
visible. The tutorial never starts the server or pairs or grants access. Mark done
appears after two minutes.

Each step with a prompt shows it first, then a collapsed "Commands your agent will run"
section; whether it is open is a per-user `tutorial.commandsExpanded` preference. The prompts and the
short command lists come from `TUTORIAL_ASKS` and each step's `commands` in
`tutorial-data.ts`, with the tracked paths, the agent-device state directory and the
simulator UDID substituted; the guide's own `manual` lists are unchanged. Create the
Tutorial has no commands. Desktop never runs the commands. Make a Change has a Run iOS button that calls the same `ActionCenter.runApp` as the
Build section's Run, and is disabled while a build or action runs in the workspace.
visible. The tutorial never starts the server or pairs or grants access.

A step with a prompt shows it with a Copy button. The prompts come from `TUTORIAL_ASKS` in
`tutorial-data.ts`, with the tracked paths substituted.
The panel cannot see a removal refusal from an agent-run command: the finish
step keeps showing the finish prompt. Check the agent's output and revert the
tutorial edit before retrying.
Expand Down
161 changes: 108 additions & 53 deletions apps/desktop/Sources/StimDesktop/Design/TutorialAnchors.swift
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import StimKit
import SwiftUI

enum TutorialAnchorID: Hashable {
case sidebarRow, buildSection, cacheBadge, deviceTile, viewerControl, logsTab, agentActions, replay, archivedFilter
case launchNoticeShow, deviceControl, viewerScreen, logsTab, agentActions, replay, archivedFilter
}

struct TutorialAnchorKey: Hashable {
Expand All @@ -18,36 +18,39 @@ struct TutorialAnchorPreference: PreferenceKey {
}

struct TutorialHint {
static let glowSeconds = 4.0

var step: String?
/// The first change's worktree.
var path: String?
var secondPath: String?
var selectedPath: String?
var ticks: [TutorialTick] = []
var showMe: () -> Void

var anchor: TutorialAnchorID? {
/// The controls this step points at, most specific first; the first one on screen glows.
var targets: [(anchor: TutorialAnchorID, callout: String)] {
switch step {
case "sidebar": return .sidebarRow
case "build": return .buildSection
case "rebuild": return .cacheBadge
case "device": return .deviceTile
case "logs", "refresh": return .logsTab
case "agent": return .agentActions
case "finish", "delete", "done": return .archivedFilter
default: return nil
case "build": return [(.launchNoticeShow, "Click Show to watch the build")]
case "device":
return [(.viewerScreen, "Tap the Tap me button and watch the counter"), (.deviceControl, "Open the live view")]
case "agent":
return (tick("viewed") ? [(.replay, "Play the replay")] : [(.agentActions, "See what your agent did")])
+ [(.deviceControl, "Open the live view")]
case "logs": return [(.logsTab, "Open Logs")]
case "finish", "done": return [(.archivedFilter, "Find the run in Archived")]
default: return []
}
}

var callout: String {
switch step {
case "sidebar": return "Select the tutorial workspace"
case "build": return "Follow the iOS build"
case "rebuild": return "See the cache outcome in build details"
case "device": return "Open the live view, then tap Log an error."
case "logs", "refresh": return "Open Logs"
case "agent": return "Watch Agent actions and Replay"
case "finish", "delete", "done": return "Find the run in Archived"
default: return "Follow the tutorial workspace"
}
/// The worktrees whose controls this step may point at.
var paths: [String] { (step == "device" ? [path, secondPath] : [path]).compactMap { $0 } }

var offersShowMe: Bool {
["device", "agent", "logs", "finish", "done"].contains(step ?? "")
}

func tick(_ id: String) -> Bool { ticks.contains { $0.id == id && $0.done } }
}

private struct TutorialHintKey: EnvironmentKey {
Expand Down Expand Up @@ -80,38 +83,25 @@ private struct TutorialHighlights: ViewModifier {
func body(content: Content) -> some View {
content.overlayPreferenceValue(TutorialAnchorPreference.self) { anchors in
GeometryReader { geometry in
if let hint, let id = hint.anchor {
let match =
anchors.first {
$0.key.id == id && ($0.key.workspace == nil || $0.key.workspace == hint.path)
} ?? anchors.first {
hint.step == "rebuild" && $0.key.id == .buildSection && $0.key.workspace == hint.path
} ?? anchors.first {
hint.step == "device" && $0.key.id == .viewerControl
}
?? anchors.first {
hint.step == "agent" && $0.key.id == .replay
}
if let match, hint.path == hint.selectedPath || id == .sidebarRow || id == .archivedFilter,
geometry[match.value].intersects(CGRect(origin: .zero, size: geometry.size))
{
let rect = geometry[match.value]
RoundedRectangle(cornerRadius: Radius.control)
.stroke(Palette.accent, lineWidth: 2)
.frame(width: rect.width + 6, height: rect.height + 6)
.position(x: rect.midX, y: rect.midY)
.allowsHitTesting(false)
Text(hint.callout).font(.stim(.footnote, weight: .semibold))
.foregroundStyle(Palette.text)
.padding(.horizontal, Space.md).padding(.vertical, Space.sm)
.background(RoundedRectangle(cornerRadius: Radius.control).fill(Palette.surface))
.fixedSize(horizontal: true, vertical: false)
.position(
x: max(140, min(geometry.size.width - 140, rect.midX)),
y: rect.maxY + 38 < geometry.size.height ? rect.maxY + 22 : max(20, rect.minY - 22)
)
.allowsHitTesting(false)
} else if showFallback, hint.path != nil, hint.path != hint.selectedPath {
if let hint {
let bounds = CGRect(origin: .zero, size: geometry.size)
let onPage = hint.selectedPath.map(hint.paths.contains) == true
let found = hint.targets.lazy.compactMap { target -> (TutorialAnchorID, String, CGRect)? in
guard
let anchor = anchors.first(where: {
$0.key.id == target.anchor && ($0.key.workspace == nil || hint.paths.contains($0.key.workspace!))
})
else { return nil }
let rect = geometry[anchor.value]
let global = [.archivedFilter, .launchNoticeShow].contains(target.anchor)
guard global || onPage, rect.intersects(bounds) else { return nil }
return (target.anchor, target.callout, rect)
}.first
if let found {
TutorialGlow(
rect: found.2, bounds: geometry.size, callout: found.1,
restartKey: "\(hint.step ?? "")|\(hint.selectedPath ?? "")|\(found.0)")
} else if showFallback, hint.offersShowMe, hint.path != nil, !onPage {
Button("Show Me", action: hint.showMe)
.buttonStyle(.stim(.secondary))
.accessibilityLabel("Show the tutorial workspace")
Expand All @@ -123,3 +113,68 @@ private struct TutorialHighlights: ViewModifier {
}
}
}

/// A pulsing glow with a capsule label that fades after a few seconds, and shows again when the target changes or
/// comes back after an absence.
private struct TutorialGlow: View {
static let fadeSeconds = 0.6
static let pulsePeriod = 1.4

var rect: CGRect
var bounds: CGSize
var callout: String
var restartKey: String
@Environment(\.accessibilityReduceMotion) private var reduceMotion
@State private var faded = false
@State private var gone = false

var body: some View {
Group {
if !gone {
TimelineView(reduceMotion ? .animation(minimumInterval: 3600) : .animation) { context in
let phase =
reduceMotion ? 0 : (sin(context.date.timeIntervalSinceReferenceDate * 2 * .pi / Self.pulsePeriod) + 1) / 2
glow(phase: phase)
}
.opacity(faded ? 0 : 1)
.allowsHitTesting(false)
.accessibilityHidden(true)
}
}
.task(id: restartKey) {
gone = false
faded = false
try? await Task.sleep(for: .seconds(TutorialHint.glowSeconds))
if Task.isCancelled { return }
withAnimation(.easeOut(duration: Self.fadeSeconds)) { faded = true }
try? await Task.sleep(for: .seconds(Self.fadeSeconds))
if !Task.isCancelled { gone = true }
}
}

private func glow(phase: Double) -> some View {
let size = CGSize(width: rect.width + 6, height: rect.height + 6)
let aboveY = rect.minY - 18
return ZStack {
RoundedRectangle(cornerRadius: Radius.control + 3)
.stroke(Palette.accent.opacity(0.45 + 0.25 * phase), lineWidth: 4 + 2 * phase)
.blur(radius: 6 + 2 * phase)
.frame(width: size.width, height: size.height)
.position(x: rect.midX, y: rect.midY)
RoundedRectangle(cornerRadius: Radius.control + 3)
.strokeBorder(Palette.accent.opacity(0.4), lineWidth: 1)
.frame(width: size.width, height: size.height)
.position(x: rect.midX, y: rect.midY)
Text(callout).font(.stim(.footnote, weight: .semibold))
.foregroundStyle(Palette.onPrimary)
.padding(.horizontal, Space.md).padding(.vertical, Space.xs)
.background(Capsule().fill(Palette.accent))
.shadow(color: Palette.accent.opacity(0.4), radius: 6)
.fixedSize(horizontal: true, vertical: false)
.position(
x: max(140, min(bounds.width - 140, rect.midX)),
y: aboveY >= 14 ? aboveY : min(rect.maxY + 18, bounds.height - 14)
)
}
}
}
15 changes: 2 additions & 13 deletions apps/desktop/Sources/StimDesktop/TutorialModel.swift
Original file line number Diff line number Diff line change
Expand Up @@ -222,26 +222,15 @@ final class TutorialModel: ObservableObject {
syncFollowers()
}

func skip() {
progress.skip(now: Date())
refresh()
}
func markDone() {
progress.markDone(now: Date())
func next() {
progress.next(now: Date())
refresh()
}
func copiedPrompt(now: Date = Date()) {
progress.copiedRunPrompt(now: now)
refresh(now: now)
}

func commands(for step: TutorialStep) -> String {
tutorialCommands(
step.commands, tourPath: tourPath, repository: workspace?.worktree?.repository ?? snapshot?.record.clonePath,
stateDir: workspace?.agentDevice?.stateDir,
udid: workspace?.ios?.udid, second: snapshot?.record.secondPath)
}

private func refresh(now: Date = Date()) {
guard statusLoaded else { return }
update(
Expand Down
1 change: 0 additions & 1 deletion apps/desktop/Sources/StimDesktop/Views/BuildSection.swift
Original file line number Diff line number Diff line change
Expand Up @@ -452,7 +452,6 @@ struct BuildOutcomeBadge: View {
var body: some View {
if let label = build.outcomeLabel {
Pill(label, tone: build.outcome == "hit" ? .success : .warning, size: .small)
.tutorialAnchor(.cacheBadge)
}
}
}
Expand Down
3 changes: 0 additions & 3 deletions apps/desktop/Sources/StimDesktop/Views/BuildSheet.swift
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,6 @@ struct BuildSheet: View {
cli: cli, env: app, run: run, archive: archive, logsExpired: logsExpired, readsServer: readsServer,
dismiss: { dismiss() }
)
.tutorialAnchor(.buildSection, workspace: app.path)
.id(page == nil ? run.id : "\(app.path)|\(run.id)")
.padding(Space.xxl)
if archive == nil, run.running == nil, run.id == runs.first?.id { nextBuild }
Expand All @@ -103,7 +102,6 @@ struct BuildSheet: View {
.frame(maxWidth: .infinity, maxHeight: .infinity)
}
}
.tutorialHighlights(showFallback: false)
.font(.stim(.callout))
.background(Palette.background)
.frame(minWidth: 980, idealWidth: 980, minHeight: 720, idealHeight: 720)
Expand Down Expand Up @@ -342,7 +340,6 @@ private struct BuildRunDetail: View {
tone: run.running?.cacheLookupOutcome == "hit" || run.last?.cacheHit == .local || run.last?.cacheHit == .remote
? .success : .warning
)
.tutorialAnchor(.cacheBadge, workspace: env.path)
}
if let reason = run.missReason { MissReasonView(reason: reason) }
if let note = run.running?.recheckNote { Text(note).foregroundStyle(Palette.tertiary) }
Expand Down
1 change: 1 addition & 0 deletions apps/desktop/Sources/StimDesktop/Views/DeviceTile.swift
Original file line number Diff line number Diff line change
Expand Up @@ -331,6 +331,7 @@ struct DeviceTile: View {
.lineLimit(1)
.fixedSize()
.accessibilityHidden(true)
.tutorialAnchor(.deviceControl, workspace: workspace)
}
if case .remote = device {
Pill(tone: .warning) { Text("billable") }
Expand Down
Loading
Loading