feat(annotations): complete DSL surface — composite tests, See selectors, P0 bugfixes (v0.9.6) (#109)

Closes every gap identified in the v0.9.5 audit of flutter_probe_annotation
and flutter_probe_gen. Goes from ~70% coverage of the ProbeScript surface
to full parity, with comprehensive golden tests cross-validated against
the Go parser.

P0 correctness bugs (would silently break user tests at runtime):
  * Mock path is now quoted in the emitted 'when the app calls ...' line.
    Was unquoted, so the Go lexer split on '/' and the parser only kept
    the first IDENT segment — Mock(path: '/api/products') silently became
    /api. Now emits 'when the app calls GET "/api/products"' and the
    full path round-trips.
  * See suffixes (state + containing + matching) now compose additively
    instead of overwriting. See('x', state: SeeState.enabled, containing:
    'y') used to silently drop the state; now emits both.

P1 missing feature:
  * @ProbeCompositeTest DSL — Device, OnDevice, Sync classes. Emitter
    walks devices then body, rendering <alias>: groups and sync "label"
    barriers. Round-trips through the Go parser's full composite test
    machinery (parser.go:1433+).

P1 incoherent surface:
  * Press and Pinch are now @deprecated — the Go parser has no case for
    them, emitted text fell through to parseRecipeCall. Use GoBack() in
    place of Press('back').

P2 under-modeled assertions:
  * See.id(key) / See.selector(Selector) factories — assertions can now
    target by ValueKey or any rich selector (Ordinal, Below/Above/
    LeftOf/RightOf, InContainer, TypeSel). Same on DontSee. The Go
    parser always supported this; the DSL just didn't expose it.
  * WaitUntil.idAppears(key) / .idDisappears(key) — emits unquoted #key
    so the Go parser's WaitSelector branch (parser.go:846) matches.

P3 robustness:
  * Emitter no longer indexes hard-coded arrays by enum.index. Reads
    the enum constant identifier via _name. Reordering Direction,
    HttpMethod, or SeeState no longer silently corrupts output.

Comprehensive tests (the user's strictness ask):
  * 6 new golden fixture pairs in probe_gen/test/fixtures/:
    - mock_and_call    (catches P0 #1 regression)
    - see_states       (catches P0 #2 regression + new selector forms)
    - composite_chat   (exercises every composite construct)
    - wait_variants    (every wait kind + id-based)
    - examples_inline  (data-driven Examples)
    - kitchen_sink     (one of every step + selector + control flow)
  * Builder tests: 5 → 11 (one per golden + existing 5).
  * Cross-language goldens: 4 → 10. Every Dart-emitted .probe round-
    trips through internal/parser/parser.go via golden_integration_test.

Docs:
  * New website page: website/src/content/docs/probescript/annotations.md
    — full reference for the DSL with every step class, selector kind,
    and composite syntax. Added to Starlight sidebar.
  * docs/wiki/Annotations.md version refs bumped.
  * README.md highlights composite tests in the annotation section.
  * Per-package CHANGELOGs detail the changes.

Versions bumped to 0.9.6:
  probe_agent, probe_annotation, probe_gen pubspec.yaml + CHANGELOG.md
  vscode/package.json
  docs/wiki/Home.md
  website/src/content/docs/tools/mcp.md verify snippet
  probe_gen depends on flutter_probe_annotation: ^0.9.6

Verification (all green before commit):
  go test ./...            16/16 packages pass
  staticcheck ./...        zero issues
  dart analyze (annot)     no issues found
  dart test    (annot)     3/3 const tests pass
  dart analyze (gen)       no issues found
  dart test    (gen)       11/11 builder tests pass (5 existing + 6 new)
  go test ...GoldenIntegration  10/10 Dart goldens parse cleanly
  dart pub publish --dry-run    both packages 0 errors
  Astro build              37 pages generated successfully

Author: pbertsch

CHANGELOG.md

@@ -6,6 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.6] - 2026-05-12
+
+### Fixed
+- **`flutter_probe_gen`: `Mock` path silently truncated.** The emitter wrote the path unquoted (`when the app calls GET /api/products`), so the Go lexer split on `/` and the parser only recorded the first IDENT segment. Now emits the canonical quoted form. Caught by a new `mock_and_call` golden + the existing cross-language integration test.
+- **`flutter_probe_gen`: `See` suffixes silently dropped.** When `state`, `containing`, and `matching` were all set on a single assertion, only the last branch's text reached the output. Now composes all three suffixes additively: `see "x" is enabled contains "y" matching "z"`. Caught by a new `see_states` golden covering the matrix.
+
+### Added
+- **`flutter_probe_annotation`: `@ProbeCompositeTest` annotation.** The flagship multi-device composite testing feature finally has a DSL surface. Pair with `Device(alias, target: …)`, `OnDevice(alias, steps: […])` per-device groups, and `Sync(label)` cross-device barriers. Emitter generates standard `composite test` / `devices` / `<alias>:` / `sync` blocks that the existing CLI runner picks up unchanged.
+- **`flutter_probe_annotation`: `See.id` / `See.selector` factories** — assertions can now target by `ValueKey` or any rich selector (Ordinal, Below/Above/LeftOf/RightOf, InContainer, TypeSel) rather than only by literal visible text. Same factories on `DontSee`. The Go parser always supported this; the DSL just didn't expose it.
+- **`flutter_probe_annotation`: `WaitUntil.idAppears` / `.idDisappears`** — emits unquoted `#key` selector form (Go parser's WaitSelector branch), which is more reliable than text matching for stable `ValueKey`-tagged widgets.
+- **`flutter_probe_gen`: 6 new golden fixtures.** `mock_and_call`, `see_states`, `composite_chat`, `wait_variants`, `examples_inline`, `kitchen_sink`. The kitchen sink fixture exercises one of every step, selector kind, and control-flow construct. Every fixture round-trips through `internal/parser/golden_integration_test.go`. Total golden coverage went from 4 → 10 fixtures, builder tests from 5 → 11.
+
+### Changed
+- **`flutter_probe_annotation`: `Press` and `Pinch` are now `@Deprecated`.** The Go parser has no `press` or `pinch` case, so emitted text fell through to `parseRecipeCall` and was misinterpreted. Marked deprecated until runtime support lands. Use `GoBack()` in place of `Press('back')`.
+- **`flutter_probe_gen`: emitter no longer coupled to enum declaration order.** `_direction`, `_httpMethod`, and the `See` state lookup now read the enum constant identifier (`_name` field) instead of indexing a hard-coded array by `.index`. Reordering `Direction`, `HttpMethod`, or `SeeState` no longer silently corrupts emitted ProbeScript.
+
+### Docs
+- New website page: [Annotation-driven Tests](https://flutterprobe.dev/probescript/annotations/) — full reference for the annotation DSL with every step class, selector kind, and the new composite test syntax.
+
 ## [0.9.5] - 2026-05-12
 
 ### Fixed

README.md

@@ -369,18 +369,18 @@ run dart:
 
 Co-locate `.probe` tests with the Flutter widgets they exercise. Two Dart packages handle this:
 
-- **`flutter_probe_annotation`** — `@ProbeSuite`, `@ProbeTest`, `@ProbeRecipe` decorators plus a fully type-checked step DSL (all 31 ProbeScript verbs, all 6 selector kinds, hooks, loops, conditionals, recipes, examples).
+- **`flutter_probe_annotation`** — `@ProbeSuite`, `@ProbeTest`, `@ProbeRecipe`, `@ProbeCompositeTest` decorators plus a fully type-checked step DSL (all 31 ProbeScript verbs, all 6 selector kinds, hooks, loops, conditionals, recipes, examples, multi-device composite tests).
 - **`flutter_probe_gen`** — a `build_runner` builder that reads the annotations and emits matching `.probe` files into `tests/generated/`.
 
 Add to your Flutter app's `pubspec.yaml`:
 
 ```yaml
 dependencies:
-  flutter_probe_annotation: ^0.9.3
-  flutter_probe_agent: ^0.9.3
+  flutter_probe_annotation: ^0.9.6
+  flutter_probe_agent: ^0.9.6
 
 dev_dependencies:
-  flutter_probe_gen: ^0.9.3
+  flutter_probe_gen: ^0.9.6
   build_runner: ^2.15.0
 ```
 
@@ -415,7 +415,9 @@ probe test tests/        # picks up tests/generated/login_screen.probe
 
 Test definitions are now type-checked by `flutter analyze` — a misspelt step name is a compile error rather than a runtime surprise. Selectors stay in sync with widget code because they live in the same file. The generated `.probe` file goes through the same parser, agent, and reporter as a hand-written one.
 
-Full reference: [`docs/wiki/Annotations.md`](docs/wiki/Annotations.md).
+**v0.9.6** completes the annotation surface: full composite-test DSL (`@ProbeCompositeTest`, `Device`, `OnDevice`, `Sync`), id/selector-based `See`/`DontSee`, `WaitUntil.idAppears`, and composable `state` + `containing` + `matching` assertions. Plus fixes for two emitter bugs (`Mock` paths and `See` suffix dropping).
+
+Full reference: [flutterprobe.dev/probescript/annotations](https://flutterprobe.dev/probescript/annotations/) (or [`docs/wiki/Annotations.md`](docs/wiki/Annotations.md) on GitHub).
 
 ## CLI Commands
 

docs/wiki/Annotations.md

@@ -28,11 +28,11 @@ tests. Annotations:
 ```yaml
 # pubspec.yaml
 dependencies:
-  flutter_probe_annotation: ^0.9.3
-  flutter_probe_agent: ^0.9.3
+  flutter_probe_annotation: ^0.9.6
+  flutter_probe_agent: ^0.9.6
 
 dev_dependencies:
-  flutter_probe_gen: ^0.9.3
+  flutter_probe_gen: ^0.9.6
   build_runner: ^2.15.0
 ```
 

docs/wiki/Home.md

@@ -18,7 +18,7 @@ Welcome to the FlutterProbe wiki. This documentation covers architecture details
 
 ## Project Status
 
-FlutterProbe is in active development. Current version: **0.9.5**.
+FlutterProbe is in active development. Current version: **0.9.6**.
 
 ### Repository Structure
 

internal/parser/golden_integration_test.go

@@ -49,9 +49,11 @@ func TestGoldenIntegration_DartEmittedFiles(t *testing.T) {
 				t.Fatalf("parser rejected golden %s:\n%v\n--- contents ---\n%s",
 					filepath.Base(path), err, string(data))
 			}
-			// Sanity: every golden defines at least one test, recipe, or hook.
-			if len(prog.Tests) == 0 && len(prog.Recipes) == 0 && len(prog.Hooks) == 0 {
-				t.Errorf("golden %s parsed but produced no tests/recipes/hooks",
+			// Sanity: every golden defines at least one test, composite test,
+			// recipe, or hook.
+			if len(prog.Tests) == 0 && len(prog.CompositeTests) == 0 &&
+				len(prog.Recipes) == 0 && len(prog.Hooks) == 0 {
+				t.Errorf("golden %s parsed but produced no tests/composite tests/recipes/hooks",
 					filepath.Base(path))
 			}
 		})

probe_agent/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.9.6 - 2026-05-12
+
+- Version bump to match CLI v0.9.6. No agent code changes — annotation DSL
+  completeness work is in the flutter_probe_annotation &
+  flutter_probe_gen packages.
+
 ## 0.9.5 - 2026-05-12
 
 - **Fix: iOS/Impeller screenshots** — `take_screenshot` previously called

probe_agent/pubspec.yaml

@@ -3,7 +3,7 @@ description: >-
   On-device E2E test agent for FlutterProbe. Embeds in your Flutter app and
   executes test commands via direct widget-tree access with sub-50ms latency.
 
-version: 0.9.5
+version: 0.9.6
 homepage: https://flutterprobe.dev
 repository: https://github.com/AlphaWaveSystems/flutter-probe
 issue_tracker: https://github.com/AlphaWaveSystems/flutter-probe/issues

probe_annotation/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.9.6 - 2026-05-12
+
+### Added
+
+- **`@ProbeCompositeTest`** — declare multi-device composite tests as
+  annotations. Pair with `Device(alias, target: ...)` declarations,
+  `OnDevice(alias, steps: [...])` per-device step groups, and
+  `Sync(label)` cross-device barriers. The generated `.probe` block
+  uses the standard `composite test` / `devices` / `sync` syntax that
+  the CLI runner already understands.
+- **`See.id(key)` / `See.selector(Selector)`** — target assertions by
+  `ValueKey` or by rich selector (Ordinal, Below/Above/LeftOf/RightOf,
+  InContainer, TypeSel). Same factories on `DontSee`. Previously,
+  `See`/`DontSee` only accepted a literal text string — the parser
+  always supported every selector kind but the DSL didn't expose it.
+- **`WaitUntil.idAppears(key)` / `.idDisappears(key)`** — emit
+  unquoted `wait until #key appears`, exercising the Go parser's
+  WaitSelector branch. More reliable than text matching for widgets
+  with stable `ValueKey`s.
+- **Composable `See` suffixes** — `See('x', state: SeeState.enabled,
+  containing: 'y')` now emits `see "x" is enabled contains "y"`
+  (both suffixes present). Previously the second suffix silently
+  overwrote the first.
+
+### Changed
+
+- **`Press` and `Pinch` are now `@Deprecated`** with a clear note —
+  the Go-side parser has no `press` or `pinch` case and emitted text
+  would be misparsed as a recipe call. They'll be re-enabled when
+  runtime support lands. Use `GoBack()` in place of `Press('back')`.
+
 ## 0.9.5 - 2026-05-12
 
 - Version bump to match CLI v0.9.5. No annotation API changes.

probe_annotation/lib/src/annotations.dart

@@ -114,3 +114,70 @@ class ProbeRecipe {
     this.steps = const [],
   });
 }
+
+/// Declares a multi-device composite test. The annotated class becomes a
+/// `composite test "name"` block in the generated `.probe` file.
+///
+/// Devices are declared by alias (`A`, `B`, `Sender`, etc.) and steps are
+/// scoped per-device using [OnDevice]. [Sync] barriers between [OnDevice]
+/// groups force every device to reach the same checkpoint before any
+/// device proceeds.
+///
+/// Example — chat between two users on two simulators:
+///
+/// ```dart
+/// @ProbeCompositeTest(
+///   name: 'alice sends bob a message',
+///   tags: ['composite', 'smoke'],
+///   devices: [
+///     Device('A', target: 'iPhone 15 Simulator'),
+///     Device('B', target: 'Pixel 9 Emulator'),
+///   ],
+///   body: [
+///     OnDevice('A', steps: [
+///       Open(),
+///       Tap(text: 'Sign in as Alice'),
+///     ]),
+///     OnDevice('B', steps: [
+///       Open(),
+///       Tap(text: 'Sign in as Bob'),
+///     ]),
+///     Sync('both signed in'),
+///     OnDevice('A', steps: [
+///       Tap(text: 'New message'),
+///       Type('hello bob'),
+///       Tap(text: 'Send'),
+///     ]),
+///     OnDevice('B', steps: [
+///       WaitUntil.appears('hello bob'),
+///       See('hello bob'),
+///     ]),
+///   ],
+/// )
+/// class ChatComposite {}
+/// ```
+class ProbeCompositeTest {
+  final String name;
+  final List<String> tags;
+  final List<Device> devices;
+
+  /// Composite body — must contain only [OnDevice] and [Sync] elements.
+  final List<Step> body;
+
+  const ProbeCompositeTest({
+    required this.name,
+    this.tags = const [],
+    this.devices = const [],
+    this.body = const [],
+  });
+}
+
+/// One device entry in a [ProbeCompositeTest.devices] list. The [alias]
+/// is referenced by [OnDevice]; [target] is an optional human-readable
+/// device name shown in the generated `.probe` header and in failure
+/// messages.
+class Device {
+  final String alias;
+  final String? target;
+  const Device(this.alias, {this.target});
+}