day-script-protocol 0.7.2

Shared dayscript wire protocol and YAML format for Day
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
// Copyright © The Daybrite Project
// SPDX-License-Identifier: MPL-2.0

//! Dayscript's shared wire protocol and on-disk format.
//!
//! This leaf crate depends only on serde, JSON and YAML. The CLI and embedded engine share
//! request/reply types and document validation without linking any UI, localization or transport.

use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;

pub mod format;
pub mod ids;
pub use ids::{EvidenceClass, IdCatalog, IdDeclaration, IdEvidence};
mod memory;
pub use format::{FailurePolicy, FormatError, Script, ScriptStep, steps_from_yaml, steps_to_yaml};
pub use memory::MemorySize;

/// Default implicit-wait budget, in seconds.
pub const DEFAULT_TIMEOUT_SECS: f64 = 5.0;

/// Which captures a run keeps.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ShotPolicy {
    Never,
    #[default]
    OnFailure,
    Always,
}

#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct Request {
    pub token: String,
    pub step: Step,
}

/// Native UI integration or deterministic Day request/response testing.
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum DialogMode {
    Native,
    Scripted,
}

#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(tag = "op", rename_all = "snake_case")]
pub enum Step {
    /// Compiled declaration registry, independent of the mounted tree.
    IdCatalog,
    /// Cumulative mounted families, diagnostic only.
    IdMounted,
    WaitFor {
        id: String,
        /// Upper bound in seconds for the implicit retry wait (§14.3), for elements that
        /// appear only after slow work (a login round-trip, a first sync). Defaults to the
        /// shared step timeout.
        #[serde(default)]
        timeout_secs: Option<f64>,
    },
    WaitIdle,
    /// Sample current process memory once. Exceeding the optional byte limit is a
    /// non-retryable failure. Host `only_on`/`skip_on` gates allow per-target budgets.
    MemoryUsage {
        #[serde(default)]
        fail_if_above: Option<MemorySize>,
    },
    /// Transport control for background reporting. Zero stops the stream; otherwise
    /// sample every 100..=60000 ms. Samples are unsolicited replies, not script steps.
    MemoryWatch {
        interval_ms: u64,
    },
    /// Programmatic scroll (docs/scroll.md §dayscript). With `edge`/`x`+`y`, `id` must name a
    /// `scroll` piece; with neither, `id` names any element and its nearest enclosing scroll
    /// reveals it. Unanimated, so the next step sees the settled position.
    /// Native navigation menus also accept `top`/`bottom` on UIKit and Material.
    ScrollTo {
        id: String,
        /// `"top"` | `"bottom"` | `"leading"` | `"trailing"`.
        #[serde(default)]
        edge: Option<String>,
        #[serde(default)]
        x: Option<f64>,
        #[serde(default)]
        y: Option<f64>,
    },
    Tap {
        id: String,
        /// Skip an absent element after UI transitions settle. Intended for idempotent
        /// fixture cleanup; existing elements still pass the visibility/enabled gates.
        #[serde(default)]
        if_present: bool,
        #[serde(default)]
        repeat: Option<u32>,
        /// Tap at this point in the element's coordinate space instead of its center, which is
        /// what canvas hit-testing needs (`- tap: { id: canvas, at: [40, 60] }`).
        #[serde(default)]
        at: Option<[f64; 2]>,
        /// Modifier keys "held" for the tap (`modifiers: [shift]` / `[primary]` / `[alt]`):
        /// the executor stands them in through `day::modifiers()` while dispatching, so
        /// modifier-dependent taps (shift-click multi-select) are drivable synthetically.
        #[serde(default)]
        modifiers: Vec<String>,
    },
    /// A non-text key press, delivered the way the platform delivers one: to whatever holds
    /// focus (`- focus: { id: canvas }` then `- key: { key: ArrowRight, modifiers: [shift] }`,
    /// docs/menus.md). Names follow the web `KeyboardEvent.key` vocabulary. On a piece that
    /// took the full route (`Decorate::keyboard`) a name outside that vocabulary, pressed
    /// with nothing but Shift, types: `key: a` arrives as the text "a", the way a real press
    /// does, and `modifiers: [control]` is the physical Control key of a chord, which types
    /// nothing.
    Key {
        key: String,
        /// The piece to deliver to. Omit to send it wherever focus is, which is what a real
        /// key press does (docs/menus.md); pair it with a `focus:` step to drive the whole
        /// route. Name an `id` to address one piece's handler regardless of focus.
        #[serde(default)]
        id: Option<String>,
        #[serde(default)]
        modifiers: Vec<String>,
    },
    /// A synthetic pointer drag over one element, in its own coordinate space: `Began` at
    /// `from`, a few `Changed` samples along the segment, `Ended` at `to`, the same
    /// `Event::Drag` stream a native recognizer delivers, so `.on_drag` state machines
    /// (canvas move/resize) run their whole preview→commit path. Injected, like every
    /// dayscript step: green here says the app logic holds, not that the platform recognizer
    /// fires; verify that with real input (docs/agent.md).
    Drag {
        id: String,
        from: [f64; 2],
        to: [f64; 2],
        /// Intermediate `Changed` samples between the endpoints (default 4).
        #[serde(default)]
        steps: Option<u32>,
        /// Modifier keys "held" for the whole drag, named as in [`Step::Tap`], for gestures
        /// whose meaning they change (a shift-drag that adds to a selection rather than
        /// replacing it). They stand in for every phase, press through release, because that
        /// is how a real drag reads them: once, when it starts.
        #[serde(default)]
        modifiers: Vec<String>,
    },
    /// A synthetic pointer hover over one element (`.on_hover`, docs/canvas.md "Interaction"):
    /// the pointer enters at `at` (element coordinates; the center when omitted), or, with
    /// `leave: true`, leaves. Injected, like [`Step::Drag`].
    Hover {
        id: String,
        #[serde(default)]
        at: Option<[f64; 2]>,
        #[serde(default)]
        leave: bool,
    },
    /// A synthetic two-finger pan over one element (`.on_pan`, docs/shapes.md): `Began`, a few
    /// `Changed` samples whose deltas add up to `by`, `Ended`. Injected, like [`Step::Drag`].
    Pan {
        id: String,
        by: [f64; 2],
        /// `Changed` samples (default 4).
        #[serde(default)]
        steps: Option<u32>,
    },
    /// A synthetic pinch over one element (`.on_pinch`, docs/shapes.md): `Began` at scale 1,
    /// `Changed` samples toward `scale`, `Ended` at `scale` (cumulative, as the platforms
    /// report it), centered on the element. Injected, like [`Step::Drag`].
    Pinch {
        id: String,
        scale: f64,
        /// `Changed` samples (default 4).
        #[serde(default)]
        steps: Option<u32>,
    },
    /// A synthetic two-finger rotation over one element (`.on_rotate`, docs/canvas.md):
    /// `Began` at 0, `Changed` samples toward `rotation` (radians, positive clockwise),
    /// `Ended` at `rotation` (cumulative, as the platforms report it), centered on the
    /// element. Injected, like [`Step::Drag`].
    Rotate {
        id: String,
        rotation: f64,
        /// `Changed` samples (default 4).
        #[serde(default)]
        steps: Option<u32>,
    },
    /// Deliver `Event::Submitted` to the element: the scripted stand-in for the platform's
    /// submit gesture (Enter in a `text_area` with `.on_submit`, a field's return key).
    Submit {
        id: String,
    },
    Input {
        id: String,
        #[serde(default)]
        text: Option<String>,
        /// Localized alternative to `text`: resolve this Fluent key (with `args`) in the run's
        /// locale and type the result, for locale-portable queries (e.g. a localized fruit name).
        #[serde(default)]
        key: Option<String>,
        #[serde(default)]
        args: Option<BTreeMap<String, serde_json::Value>>,
    },
    SetValue {
        id: String,
        value: f64,
    },
    Toggle {
        id: String,
        #[serde(default)]
        value: Option<bool>,
    },
    /// Invoke a list row without changing selection. Out-of-range indices are ignored.
    Activate {
        id: String,
        index: usize,
    },
    Select {
        id: String,
        index: i64,
        /// Skip an absent element after UI transitions settle, as `tap`'s does. For a
        /// control that only some layouts have: the pane switcher a phone shows where a wide
        /// window shows both panes.
        #[serde(default, skip_serializing_if = "std::ops::Not::not")]
        if_present: bool,
    },
    /// Drag-reorder a list row programmatically: row `from` drops at row `to` through the same
    /// guard → commit path a native drag takes (docs/list.md); the app's `reorder_guard` may
    /// deny or retarget it. Fails (non-retryably) when the list isn't `.reorderable()` or the
    /// guard denies the move.
    Reorder {
        id: String,
        from: usize,
        to: usize,
    },
    /// Undo one unit of the app's history, through the installed undo bridge, the same
    /// handler ⌘Z and the Edit menu reach (docs/model.md). Portable: it needs no undo
    /// button and no scriptable menu item on the target. Fails (non-retryably) when the
    /// app never installed an undo stack.
    Undo,
    /// Redo one unit, [`Step::Undo`]'s mirror.
    Redo,
    /// Disclose or collapse a tree row programmatically (docs/tree.md). The row is resolved
    /// by its `.row_id` string; the step emits the same `Event::TreeExpanded` a native
    /// disclosure does, so the piece's expansion signal (and through it the native row)
    /// follows. Retryable while the row id is unknown (a pending reload may still produce it).
    Expand {
        id: String,
        row: String,
        #[serde(default = "default_true")]
        expanded: bool,
    },
    /// Move a tree row programmatically: `row` lands under `parent` (absent = the root) at
    /// `index` (absent = dropped onto the parent, i.e. append), through the same guard → commit
    /// path a native drag takes (docs/tree.md). Fails (non-retryably) when the tree isn't
    /// `.movable()` or a guard (structural or the app's) denies the move.
    TreeMove {
        id: String,
        row: String,
        #[serde(default)]
        parent: Option<String>,
        #[serde(default)]
        index: Option<usize>,
    },
    /// Delete a list row programmatically: row `row` goes through the same guard → commit path
    /// a native swipe takes (docs/list.md); the app's `delete_guard` may refuse it. Fails
    /// (non-retryably) when the list isn't `.deletable()` or the guard refuses.
    ///
    /// This is how a walkthrough asserts deletion on every target, including the desktops whose
    /// toolkits answer `Cap::ListDelete = Unsupported` and have no gesture to simulate: the step
    /// drives the guard → commit path, not the platform's gesture recognizer.
    DeleteRow {
        id: String,
        row: usize,
    },
    /// Activate a list row's swipe action programmatically: pull row `row`'s offer for `edge`
    /// (`trailing`, the default, or `leading`) and run action `action` (an index into the
    /// offer, default 0, the one a native full swipe activates), through the same
    /// offer → commit path a native gesture takes (docs/list.md). `label:` (literal) or
    /// `key:` (a Fluent key resolved in the run's locale) pins which button may be pressed.
    /// Offers are state-dependent ("Mark as Read" vs "Mark as Unread"), and the pin is
    /// checked before the press: a mismatched offer refuses the activation and fails the
    /// step with the row's state untouched, so a stale pin (leftover state from an aborted
    /// earlier run) fails once instead of flipping state and poisoning every later run.
    /// Fails (non-retryably) when the list offers no swipe actions or the row's offer has
    /// no such action.
    ///
    /// This is how a walkthrough exercises swipe actions on every target, including the
    /// toolkits that answer `Cap::ListSwipeActions = Unsupported` and show no affordance:
    /// the step drives the offer → commit path, not the platform's gesture recognizer.
    SwipeRow {
        id: String,
        row: usize,
        #[serde(default)]
        edge: Option<String>,
        #[serde(default)]
        action: usize,
        #[serde(default)]
        label: Option<String>,
        #[serde(default)]
        key: Option<String>,
    },
    /// Evaluate JavaScript in a web view node and assert on the result
    /// (docs/webview-eval.md), the step that proves a page rendered, where
    /// `assert_visible` only proves the native view exists. `script` runs in the page;
    /// its value (a string compares as itself, anything else as its JSON) must contain
    /// `contains:` and/or equal `text:`; with neither, a successful evaluation alone
    /// passes. Retryable while the reply is pending, the script throws, or the assertion
    /// mismatches (a page mid-load settles within the wait); fails non-retryably when the
    /// id names no web view or no webview piece is linked. Only meaningful where the
    /// backend's eval arm exists (`eval_support()`; docs/webview-eval.md keeps the list);
    /// elsewhere the step fails after the wait, so gate it with `only_on:`.
    WebEval {
        id: String,
        script: String,
        #[serde(default)]
        contains: Option<String>,
        #[serde(default)]
        text: Option<String>,
        /// Override the shared wait for a cold browser engine or a slow page load.
        #[serde(default)]
        timeout_secs: Option<f64>,
    },
    /// Invoke an app-menu item programmatically (docs/menus.md): match a unique `Action`
    /// leaf in the installed app-menu model by exact `item` label, or by `key`, a Fluent
    /// key resolved in the run's locale (locale-portable; a standard-role item also
    /// matches its role's core-catalog key, so the auto Preferences item is
    /// `key: day_preferences`). `path` disambiguates with ancestor submenu labels (suffix
    /// match). Items that run a native selector instead of a day action (role items with
    /// id 0) are not invokable this way.
    /// Choose an item from an element's context menu (`.context_menu`, `.context_menu_fn`;
    /// docs/menus.md), as a right click or long press followed by a choice would, or from a
    /// `menu_button`'s menu, as a press and a choice would. `id` names the element; the item is addressed as [`Step::Menu`] addresses one: `item_id:` (the name the
    /// app gave it), `item:` (the literal label) or `key:`, with `path` for submenus. A
    /// provider menu is asked at the element's origin.
    ContextMenu {
        id: String,
        /// Skip an absent element after UI transitions settle, as `tap` does: for idempotent
        /// fixture cleanup through a row's menu.
        #[serde(default)]
        if_present: bool,
        #[serde(default)]
        item_id: Option<String>,
        #[serde(default)]
        item: Option<String>,
        #[serde(default)]
        key: Option<String>,
        #[serde(default)]
        path: Option<Vec<String>>,
    },
    /// Choose an app-menu item. Address it by `id:` (the name the app gave it with
    /// `MenuEntry::id`) in preference to anything else: a label is localized, and an item that
    /// shows a check mark rewrites its label as the state moves, so neither is a stable
    /// address. `item:` matches the literal label, `key:` a built-in role key (`day_copy`) or a
    /// Fluent key resolved in the run's locale.
    Menu {
        #[serde(default)]
        id: Option<String>,
        #[serde(default)]
        item: Option<String>,
        #[serde(default)]
        key: Option<String>,
        #[serde(default)]
        path: Option<Vec<String>>,
    },
    /// Drive a window-toolbar item by its id (docs/toolbars.md). With neither `text:` nor
    /// `on:` this runs a button's command; `text:` types into a search item; `on:` sets a
    /// toggle. Each goes through the same dispatch the native control fires, so it exercises
    /// the app's wiring; it does not prove the native widget drew (a screenshot does). With
    /// `submit: true` a search item's text is then submitted, as its Return or Search key does.
    Toolbar {
        item: String,
        #[serde(default)]
        text: Option<String>,
        /// Localized alternative to `text`, exactly as [`Step::Input`] takes one: resolve this
        /// Fluent key (with `args`) in the run's locale and type the result. A toolbar search
        /// field that filters on localized text needs this: a literal query written in English
        /// matches nothing once the run switches locale.
        #[serde(default)]
        key: Option<String>,
        #[serde(default)]
        args: Option<BTreeMap<String, serde_json::Value>>,
        #[serde(default)]
        on: Option<bool>,
        /// A segmented item's choice, by index (docs/toolbars.md). The step fails rather than
        /// guessing if the item is not segmented or the index is out of range.
        #[serde(default)]
        index: Option<usize>,
        /// Submit a search item's `text` (or `key`) after typing it (docs/search.md).
        #[serde(default)]
        submit: bool,
    },
    AssertVisible {
        id: String,
    },
    /// Fail if the id is in the tree: the assertion for a subtree a `when` has not mounted
    /// (a property row that does not apply, a page's absent chrome). `assert_visible` cannot
    /// say this: a missing id is an error there, and an error is not a pass.
    AssertMissing {
        id: String,
    },
    /// Fail if the element is on screen: pass when it is missing, has an empty frame, or its
    /// native widget reports itself hidden. For what a toolkit hides rather than removes (a
    /// collapsed pane, a closed popover), where `assert_missing` would see it present.
    AssertHidden {
        id: String,
    },
    AssertText {
        id: String,
        #[serde(default)]
        text: Option<String>,
        #[serde(default)]
        key: Option<String>,
        #[serde(default)]
        args: Option<BTreeMap<String, serde_json::Value>>,
        /// Upper bound in seconds for the implicit retry wait (§14.3), for text that changes only
        /// after slow work (a download finishing, an upload's receipt). Defaults to the shared
        /// step timeout.
        #[serde(default)]
        timeout_secs: Option<f64>,
    },
    AssertValue {
        id: String,
        value: serde_json::Value,
    },
    /// Check an element's frame (docs/testing.md): its size, and its origin relative to
    /// `relative_to`'s (or to the window content when absent), in points, within `tolerance`
    /// (default 1). Day's layout must match, and so must the native widget's frame where the
    /// toolkit reads it back; where it cannot, the reply's `data` lists the frame as unread.
    AssertFrame {
        id: String,
        #[serde(default)]
        width: Option<f64>,
        #[serde(default)]
        height: Option<f64>,
        #[serde(default)]
        x: Option<f64>,
        #[serde(default)]
        y: Option<f64>,
        #[serde(default)]
        relative_to: Option<String>,
        #[serde(default)]
        tolerance: Option<f64>,
    },
    /// Check the color of one point of an element in an in-process capture (docs/testing.md).
    /// `x` and `y` are fractions of the element's frame (0.5, 0.5 is its center); `color` is
    /// `#rrggbb`, matched per channel within `tolerance` (default 64 of 255, which absorbs color
    /// management, such as a Display P3 capture reading sRGB red as `#ea3323`, and antialiasing,
    /// but not a different color). A toolkit with no capture
    /// (`Cap::Snapshot` unsupported) passes it as unread.
    SamplePixel {
        id: String,
        x: f64,
        y: f64,
        color: String,
        #[serde(default)]
        tolerance: Option<u8>,
    },
    /// Check that the app asked to open `url` during this test run (docs/testing.md). While
    /// `run_tests` runs, `open_url` records instead of opening anything.
    AssertOpenedUrl {
        url: String,
    },
    /// Check that the app announced `text` to the screen reader during this test run
    /// (`day::announce`, docs/accessibility.md). The announcement still reaches the toolkit.
    AssertAnnounced {
        text: String,
    },
    /// Compare the NATIVE widget with what is expected (docs/testing.md): the state the
    /// platform reports through `Toolkit::read_native`, not Day's tree. Only the fields given
    /// are checked. A field the toolkit cannot read passes and is listed as unread in the
    /// reply's `data`, so a gap is recorded rather than hidden. `enabled` is also checked
    /// against Day's own state, so a disagreement between the two fails either way.
    AssertNative {
        id: String,
        #[serde(default)]
        text: Option<String>,
        #[serde(default)]
        number: Option<f64>,
        #[serde(default)]
        checked: Option<bool>,
        #[serde(default)]
        enabled: Option<bool>,
        #[serde(default)]
        visible: Option<bool>,
    },
    /// Fail if any piece kind rendered a `⟨kind⟩` placeholder, i.e. the backend had no renderer
    /// for it. Placeholders are invisible to every other assertion (the app still renders, the
    /// screenshot still looks plausible), so this is the only step that catches a missing or
    /// silently-dropped renderer. `allow` lists the kinds a target is expected to lack, which
    /// makes the script itself the per-target gap ledger; anything outside it is a failure.
    AssertNoPlaceholders {
        #[serde(default)]
        allow: Vec<String>,
    },
    /// Close the secondary window opened under `window` (`day::open_window`'s key;
    /// the preferences window is `day.preferences`), through the same async confirm →
    /// teardown path a title-bar close takes (docs/windows.md; on the cover-fallback tier
    /// this dismisses the cover). An already-closed window is a success (closing is
    /// idempotent). With no `window`, the app's initial window, whose close ends the app
    /// (docs/windows.md close policy), so follow it with `expect_exit`. GTK routes that close
    /// through the title bar's path today; the other desktop toolkits' `close_window` duties
    /// still look only at secondary windows, so there the step is a no-op and `expect_exit`
    /// times out.
    CloseWindow {
        #[serde(default)]
        window: Option<String>,
    },
    Screenshot {
        name: String,
        /// Capture the secondary window opened under this key (`day::open_window`'s `key`)
        /// instead of the primary (docs/windows.md). On the cover-fallback tier the key
        /// resolves to the primary window, whose fullscreen cover is the content: the same
        /// pixels, no special case. A missing key fails retryably (the window may still be
        /// opening).
        #[serde(default)]
        window: Option<String>,
        /// Whether the reply carries the engine's capture (`png_base64`).
        ///
        /// On a device target the runner captures through `simctl`/`adb` and that image
        /// (whole screen, system chrome and all) is what the gallery publishes, so a payload
        /// rendered here would be encoded, shipped over the socket and dropped on the floor.
        /// Measured at 819ms per shot on the iOS simulator (33.6s across one walkthrough
        /// variant, ~4.5 minutes across a CI job's eight), so the runner asks for it only
        /// where it will be used, and re-asks with this set if the device capture fails.
        ///
        /// Defaults to `true`: an older runner, `day drive`, or a hand-written step says
        /// nothing and still gets the image. The idle wait above happens either way; it is
        /// what makes a capture land on a settled frame, not an artifact of the encoding.
        #[serde(default = "default_true")]
        in_process: bool,
    },
    Pause {
        secs: f64,
    },
    /// Deliver a deep-link URL in-process (docs/deep-links.md): the URL maps to its route
    /// through the same `day_spec::route_of_url` every platform intake uses, then navigates,
    /// identical to a warm OS delivery. Proves routing, params, and back-stack seeding on
    /// every backend, including mock; OS registration and intake are the runner tier's job.
    DeepLink {
        url: String,
    },
    /// Deliver an original external URL to on_open_url (with normal routing fallback).
    OpenUrl {
        url: String,
    },
    /// Navigate to a registered route (reset-to semantics; "" = root). docs/navigation.md.
    Navigate {
        route: String,
    },
    /// Pop one navigation level. Bare, it is Day's own rail (`day_core::nav_back`), which pops
    /// the model and lets the backend follow. `native: true` presses the platform's back
    /// affordance instead (`Toolkit::native_back`): the bar's `shouldPop`, the dispatcher's
    /// callbacks, the native pop, then the backend's report of it to Day as a user back, which
    /// is the code a real tap runs and the bare step never reaches (docs/navigation.md).
    NavBack {
        // Skipped when false so a recorded bare back still writes as `- nav_back:`.
        #[serde(default, skip_serializing_if = "std::ops::Not::not")]
        native: bool,
    },
    /// Assert the current route path ("" = root).
    AssertRoute {
        route: String,
    },
    /// Select presentation behavior for subsequent Day dialogs and file pickers.
    /// Existing requests must be answered before switching.
    DialogMode {
        mode: DialogMode,
    },
    /// Assert that no Day presentation requests remain unanswered.
    AssertNotPresented,
    /// Assert a presentation is pending (native or scripted), optionally checking its title.
    AssertPresented {
        #[serde(default)]
        title: Option<String>,
    },
    /// Answer the open modal: a button `index`, a prompt `text`, a file `path` (open/save
    /// pickers; relative paths resolve against the app temp dir, writable on every target), or
    /// `dismiss`.
    Respond {
        #[serde(default)]
        button: Option<i64>,
        #[serde(default)]
        text: Option<String>,
        #[serde(default)]
        path: Option<String>,
        #[serde(default)]
        dismiss: bool,
    },
    /// Diff the native accessibility tree against Day's expectations (role/label/value/identifier)
    /// for every id'd node, or just `id` (§13, §14.2). Backends that can't read their native tree
    /// (`found = false`) are skipped; role is only compared when both sides map to a known `Role`.
    A11yAudit {
        #[serde(default)]
        id: Option<String>,
    },
    /// List the `#[day::test]` cases the binary registers (docs/testing.md); the reply's
    /// `data` is the listing.
    Tests,
    /// Run the registered tests whose names match `filter` (globs; empty = all), keeping
    /// captures per `shots`. Retryable while the run is in progress, so the runner's wait loop
    /// polls it; `timeout_secs` bounds the whole run, `case_timeout_secs` each case. The
    /// reply's `data` is the report.
    RunTests {
        #[serde(default)]
        filter: Vec<String>,
        #[serde(default)]
        shots: ShotPolicy,
        #[serde(default)]
        timeout_secs: Option<f64>,
        /// Each case's time limit where the case sets none (default 30 s); `0` turns every
        /// limit off, for a run held at a debugger's breakpoint.
        #[serde(default)]
        case_timeout_secs: Option<f64>,
    },
    /// Move native focus to the control: the real Toolkit duty, not a synthetic event, so
    /// keyboards and end-editing flows engage (docs/focus.md). `focused: false` resigns it.
    Focus {
        id: String,
        #[serde(default)]
        focused: Option<bool>,
    },
    /// Assert the control's focus state as Day resolved it (`NodeProbe.focused`; retryable, since
    /// focus lands a turn after the request). `focused` defaults to `true`.
    AssertFocused {
        id: String,
        #[serde(default)]
        focused: Option<bool>,
    },
    /// Expect the app to terminate: the only step that tolerates the app dying (docs/break.md's
    /// crash-reporting flow, docs/agent.md). Must be the last step: a preceding step triggered an
    /// exit or crash, and `expect_exit` treats the connection dropping within `within`
    /// seconds (default 15) as success; the app surviving the window is the failure. Handled
    /// runner-side (`day-cli`), so the in-app engine never executes it; this arm is defensive.
    ExpectExit {
        #[serde(default)]
        within: Option<f64>,
    },
    /// Force the window's size class (docs/size-classes.md) without resizing anything: the
    /// cheap way to drive a responsive layout on a backend whose window cannot be resized from a
    /// script (the phones, an emulator). `width` is `compact` | `medium` | `expanded` | `large` |
    /// `extra-large`; `height` is `compact` | `medium` | `expanded` and defaults to `expanded`.
    ///
    /// This reports a class the way a backend would, so everything downstream (an automatic
    /// nav host re-presenting, a piece that lays out from `day::size_class()`) runs its real
    /// path. What it does not do is change the window's actual pixels: a screenshot after this
    /// step shows the new layout at the old size. Drive a real resize from the runner instead
    /// (Playwright's `setViewportSize` on web, the simulator's rotation on iOS) when the
    /// geometry itself is what's under test.
    /// `width: auto` releases the override and restores the class the window itself reports, so
    /// the steps after an adaptive sweep run at the device's real geometry again. A script that
    /// forces `expanded` and never lets go leaves a phone laying out a split whose detail pane
    /// falls off the screen: the layout is correct, the window just isn't that wide.
    SizeClass {
        width: String,
        #[serde(default)]
        height: Option<String>,
    },
    /// Change the window's actual geometry, and wait until the app has reported the new size
    /// (docs/size-classes.md). The runner performs the resize (a device's window belongs to the
    /// system, not to the app) and this half is the barrier: without it the next step races the
    /// platform's resize animation.
    ///
    /// `size_class:`'s complement, and the difference matters: that step reports a class the
    /// window is not actually at, so a screenshot after it shows the new layout at the old size.
    /// This one moves the pixels.
    Resize {
        #[serde(default)]
        width: Option<f64>,
        #[serde(default)]
        height: Option<f64>,
        /// `resize: auto`: back to the device's geometry.
        #[serde(default)]
        restore: bool,
    },
}

impl Step {
    /// The implicit-wait budget for this step, seconds: its own `timeout_secs` when declared
    /// (and positive), else the shared [`DEFAULT_TIMEOUT_SECS`].
    pub fn wait_budget_secs(&self) -> f64 {
        match self {
            Step::WaitFor {
                timeout_secs: Some(t),
                ..
            }
            | Step::AssertText {
                timeout_secs: Some(t),
                ..
            }
            | Step::WebEval {
                timeout_secs: Some(t),
                ..
            }
            | Step::RunTests {
                timeout_secs: Some(t),
                ..
            } if *t > 0.0 => *t,
            _ => DEFAULT_TIMEOUT_SECS,
        }
    }
}

impl Step {
    /// The stable snake-case operation name used on the wire and in script files.
    pub const fn op(&self) -> &'static str {
        match self {
            Self::WaitFor { .. } => "wait_for",
            Self::WaitIdle => "wait_idle",
            Self::MemoryUsage { .. } => "memory_usage",
            Self::MemoryWatch { .. } => "memory_watch",
            Self::IdCatalog => "id_catalog",
            Self::IdMounted => "id_mounted",
            Self::ScrollTo { .. } => "scroll_to",
            Self::Tap { .. } => "tap",
            Self::Key { .. } => "key",
            Self::Drag { .. } => "drag",
            Self::Hover { .. } => "hover",
            Self::Pan { .. } => "pan",
            Self::Pinch { .. } => "pinch",
            Self::Rotate { .. } => "rotate",
            Self::Submit { .. } => "submit",
            Self::Input { .. } => "input",
            Self::SetValue { .. } => "set_value",
            Self::Toggle { .. } => "toggle",
            Self::Activate { .. } => "activate",
            Self::Select { .. } => "select",
            Self::Reorder { .. } => "reorder",
            Self::Undo => "undo",
            Self::Redo => "redo",
            Self::Expand { .. } => "expand",
            Self::TreeMove { .. } => "tree_move",
            Self::DeleteRow { .. } => "delete_row",
            Self::SwipeRow { .. } => "swipe_row",
            Self::WebEval { .. } => "web_eval",
            Self::ContextMenu { .. } => "context_menu",
            Self::Menu { .. } => "menu",
            Self::Toolbar { .. } => "toolbar",
            Self::AssertVisible { .. } => "assert_visible",
            Self::AssertMissing { .. } => "assert_missing",
            Self::AssertHidden { .. } => "assert_hidden",
            Self::AssertText { .. } => "assert_text",
            Self::AssertValue { .. } => "assert_value",
            Self::AssertFrame { .. } => "assert_frame",
            Self::SamplePixel { .. } => "sample_pixel",
            Self::AssertOpenedUrl { .. } => "assert_opened_url",
            Self::AssertAnnounced { .. } => "assert_announced",
            Self::AssertNative { .. } => "assert_native",
            Self::AssertNoPlaceholders { .. } => "assert_no_placeholders",
            Self::CloseWindow { .. } => "close_window",
            Self::Screenshot { .. } => "screenshot",
            Self::Pause { .. } => "pause",
            Self::DeepLink { .. } => "deep_link",
            Self::OpenUrl { .. } => "open_url",
            Self::Navigate { .. } => "navigate",
            Self::NavBack { .. } => "nav_back",
            Self::AssertRoute { .. } => "assert_route",
            Self::DialogMode { .. } => "dialog_mode",
            Self::AssertNotPresented => "assert_not_presented",
            Self::AssertPresented { .. } => "assert_presented",
            Self::Respond { .. } => "respond",
            Self::A11yAudit { .. } => "a11y_audit",
            Self::Tests => "tests",
            Self::RunTests { .. } => "run_tests",
            Self::Focus { .. } => "focus",
            Self::AssertFocused { .. } => "assert_focused",
            Self::ExpectExit { .. } => "expect_exit",
            Self::SizeClass { .. } => "size_class",
            Self::Resize { .. } => "resize",
        }
    }
}

/// Defaults to on for fields introduced after the first protocol version.
fn default_true() -> bool {
    true
}

#[derive(Serialize, Deserialize, Debug, Default, PartialEq)]
pub struct Reply {
    #[serde(default, skip_serializing_if = "<[IdEvidence]>::is_empty")]
    pub id_evidence: Box<[IdEvidence]>,
    pub ok: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    /// Set on failures that may succeed after a wait (element not found yet, assert pending).
    #[serde(default)]
    pub retryable: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub png_base64: Option<String>,
    #[serde(default)]
    pub screenshot_unsupported: bool,
    /// Acknowledged render checkpoint. Absent when talking to an older app or when
    /// freshness can only be established by an in-process snapshot.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub capture_revision: Option<u32>,
    /// App-side policy acknowledgment. Older apps omit it; runners must retain
    /// animation pauses until the app confirms that fast motion is active.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub fast_animations: Option<bool>,
    /// Internal retry cadence: frame checkpoints can complete on the next display tick.
    #[serde(skip)]
    pub capture_pending: bool,
    /// A step's structured answer (`tests`, `run_tests`, `memory_usage`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub data: Option<serde_json::Value>,
    /// Unsolicited telemetry on a connection that explicitly enabled `memory_watch`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub memory_sample: Option<Box<MemorySample>>,
    /// The step never ran: the app's main thread did not pick it up within the engine's
    /// budget. Every later step would wait the full budget and fail the same way, so a runner
    /// abandons the flow on this rather than on the error text. Older apps omit it.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub main_thread_stalled: bool,
}

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub struct MemorySample {
    pub bytes: Option<u64>,
    pub metric: String,
}

impl Reply {
    pub fn ok() -> Self {
        Reply {
            ok: true,
            ..Default::default()
        }
    }
    pub fn fail(msg: impl Into<String>, retryable: bool) -> Self {
        Reply {
            ok: false,
            error: Some(msg.into()),
            retryable,
            ..Default::default()
        }
    }
}

#[cfg(test)]
mod close_window_tests {
    use super::*;

    /// `close_window: {}` is the initial window; a key still names a secondary one.
    #[test]
    fn close_window_defaults_to_the_initial_window() {
        let step: Step = serde_json::from_str(r#"{"op":"close_window"}"#).expect("parse");
        assert_eq!(step, Step::CloseWindow { window: None });
        let step: Step =
            serde_json::from_str(r#"{"op":"close_window","window":"day.preferences"}"#)
                .expect("parse");
        assert_eq!(
            step,
            Step::CloseWindow {
                window: Some("day.preferences".into())
            }
        );
    }
}