dusk

<!-- Generated by ac:init-project 2026-05-22. Source-grounded against 0.0.2. -->

# CLAUDE.md

Guidance for Claude Code working inside the `fluttersdk_dusk` repo. Path-scoped rules under `.claude/rules/{tests,extensions,commands,docs}.md` cover their subsystems; this file is the root spec.

## Stack

Flutter SDK package (Dart 3.4+, Flutter 3.22+). Plugin of `fluttersdk_artisan ^0.0.5`: contributes `DuskArtisanProvider` with 32 CLI commands and 31 MCP tool descriptors backed by 28 `ext.dusk.*` VM Service extensions plus 3 `artisan:dusk:*` substrate-routed tools.

Production deps (hosted only): `fluttersdk_artisan ^0.0.5`, `image ^4.0.0`, `meta ^1.16.0`, `fluttersdk_wind_diagnostics_contracts ^1.0.0`. Dev deps: `flutter_test`, `flutter_lints >=5.0.0 <7.0.0`, `yaml ^3.1.0`. Debug-only at the consumer call site: the consumer wraps `DuskPlugin.install()` in `if (kDebugMode)` so release builds tree-shake the subsystem on dart2js (web) and dart2native (mobile/desktop AOT).

Two CLI surfaces. `bin/fluttersdk_dusk.dart` is the Flutter-free wrapper (`dart run fluttersdk_dusk <cmd>`); `lib/cli.dart` exports `FluttersdkDuskArtisanProvider` (typedef alias of `DuskArtisanProvider`) for consumer-side `lib/app/_plugins.g.dart` auto-discovery. `install.yaml` at the package root drives `plugin:install fluttersdk_dusk` via the artisan PluginInstaller. After install the consumer's `./bin/fsa` (~110ms warm AOT) is the recommended entry point.

## Commands

| Command | When |
|---|---|
| `flutter test --coverage --exclude-tags=integration --timeout=30s` | Default runner (CI gate). Emits `coverage/lcov.info`; 80% line floor enforced. |
| `dart format lib/ test/ bin/` | Must produce zero diff (CI runs `--output=none --set-exit-if-changed`). |
| `dart analyze lib/ test/ bin/` | Zero issues across all three roots. |
| `flutter pub get` | Resolve deps. |
| `dart pub publish --dry-run` | Pre-publish validation. Exits 65 on warnings, 0 on a clean archive. |
| `flutter test test/integration --tags=integration` | Manual opt-in CDP smoke run (requires Chrome on PATH; excluded from default CI). |

## Golden Rules (apply on every change)

1. **Doc sync.** Any behavioral or interface change must update `README.md`, `ARCHITECTURE.md`, `CHANGELOG.md` (under `## [Unreleased]`), the matching page under `doc/**/*.md`, and `llms.txt` in the same change. See `.claude/rules/docs.md` for the surface-to-file map.
2. **Coverage at or above 80%.** CI enforces via lcov parse in `.github/workflows/ci.yml:42-44`. Verify locally after behavioral changes: `awk -F: '/^LF:/{lf+=$2} /^LH:/{lh+=$2} END{ if (lf==0) exit 1; printf "%.2f%%\n", (lh/lf)*100 }' coverage/lcov.info`. Drops below 80% block the change.
3. **CHANGELOG always under `[Unreleased]`.** Every behavioral or interface change lands a bullet under `## [Unreleased]` in `CHANGELOG.md`. Keep-a-Changelog 1.1.0 ordering: Added, Changed, Deprecated, Removed, Fixed, Security. Promote to a dated section on tag push.
4. **Green gate plus TDD.** `dart format lib/ test/ bin/` zero diff, `dart analyze lib/ test/ bin/` zero issues, `flutter test --exclude-tags=integration` all green. Red-green-refactor for behavioral changes: failing test first that fails for the right reason, then implementation that turns it green.

## Architecture

Single barrel: `lib/dusk.dart` re-exports the public API. Subsystem layout under `lib/src/`:

| Path | Purpose |
|---|---|
| `extensions/` | 17 files: `ext_snapshot`, `ext_pointer`, `ext_text_input`, `ext_screenshot`, `ext_scroll`, `ext_wait_find`, `ext_modal_router`, `ext_navigation`, `ext_evaluate`, `ext_close_app`, `ext_find`, `ext_console`, `ext_exceptions`, `ext_checkbox`, `ext_observe`, `ext_focus`, plus `register_dusk_extensions` aggregator. See `.claude/rules/extensions.md`. |
| `commands/` | 32 `ArtisanCommand` subclasses (one file each). See `.claude/rules/commands.md`. |
| `cdp/` | `cdp_client.dart` (JSON-RPC over `/json` + WebSocket, 30s timeout), `chrome_finder.dart`, `device_presets.dart` (8 named presets). |
| `utils/` | `actionability_gate.dart` (6-check gate), `dusk_exceptions.dart`, `error_envelope.dart`, `chrome_reaper.dart`. |
| `dusk_plugin.dart` | `DuskPlugin.install()` entry, enricher list, navigate adapter hook. Idempotent. Wraps the app root in a `RepaintBoundary` (no `GlobalKey`) so `ext.dusk.screenshot` finds it via render-tree walk. |
| `ref_registry.dart` | `e<N>` (snapshot-frozen, dedup-by-`node.id`) + `q<N>` (re-resolvable predicate handles) dual token system. |
| `dusk_snapshot_enricher.dart` | FROZEN typedef: `String? Function(Element element, RefRegistry refs)`. |
| `dusk_navigate_adapter.dart` | FROZEN typedef: `Future<bool> Function(String route)`. |
| `dusk_artisan_provider.dart` | `DuskArtisanProvider extends ArtisanServiceProvider`: `commands()` returns 32 entries, `mcpTools()` returns 31 const `McpToolDescriptor`s. |
| `bin/fluttersdk_dusk.dart` | Flutter-free CLI wrapper (no `dart:ui` import). |
| `lib/cli.dart` | Codegen barrel exporting `FluttersdkDuskArtisanProvider` typedef alias for consumer-side `_plugins.g.dart` auto-discovery. |
| `install.yaml` | V1 plugin manifest (zero stubs, post-install bootstrap message, `executables:` anchor). |

## VM Service surface

28 `ext.dusk.*` extensions registered via `registerExtensionIdempotent` (from `fluttersdk_artisan`) for hot-restart safety: `snap`, `tap`, `hover`, `drag`, `dblclick`, `right_click`, `triple_click`, `type`, `clear`, `press_key`, `focus`, `blur`, `scroll`, `select_option`, `set_checkbox`, `screenshot`, `wait_for`, `wait_for_network_idle`, `find`, `observe`, `dismiss_modals`, `navigate`, `navigate_back`, `get_routes`, `evaluate`, `close_app`, `console`, `exceptions`. Two internal helpers (`find_by_text`, `find_by_label`) back the `dusk:wait` polling loop and are not MCP-surfaced. Handler signature: `Future<ServiceExtensionResponse> Function(String method, Map<String, String> params)`. Parse integers via `int.tryParse(params['key'] ?? '')`. Return `.result(jsonEncode(payload))` or `.error(ServiceExtensionResponse.extensionError, msg)` with JSON-encoded `errorDetail` (Flutter framework convention).

Three MCP tools route through the `artisan:dusk:*` substrate prefix instead of a VM extension because they need out-of-isolate execution: `dusk_hot_reload_and_snap` (in-isolate self-reload would deadlock), `dusk_resize_viewport`, `dusk_device_profile` (both drive Chrome DevTools Protocol from a non-Flutter Dart context).

## Off-limits (FROZEN contracts, alpha-2 cycle)

These cannot change without a coordinated bump across `fluttersdk_dusk` + `magic` + `wind`:

1. `DuskSnapshotEnricher` typedef shape (`lib/src/dusk_snapshot_enricher.dart:23`): `String? Function(Element, RefRegistry)`.
2. `DuskNavigateAdapter` typedef shape (`lib/src/dusk_navigate_adapter.dart:19`): `Future<bool> Function(String route)`.
3. `DuskPlugin.install()` and `DuskPlugin.registerNavigateAdapter()` signatures, plus the `DuskPlugin.enrichers` live-read list that magic appends to via `MagicDuskIntegration` (`lib/src/dusk_plugin.dart:39,52,59`).
4. `RefRegistry` public method signatures: `register`, `lookup`, `registerQuery`, `lookupQuery`, `disposeAll`, `resetForTesting` (`lib/src/ref_registry.dart:190,251,264,274,316,363`). Magic-side enrichers call these directly.
5. `DuskActionabilityException` reason-substring vocabulary (`lib/src/utils/dusk_exceptions.dart:51`): `"defunct (element no longer mounted)"`, `"not enabled"`, `"zero rect"`, `"off-viewport (rect=..., viewport=...)"`, `"not stable (rect changed by Xpx)"`, `"obscured by other widget (top=...)"`. Agents branch on these substrings.
6. Actionability-gate evaluation order (`lib/src/utils/actionability_gate.dart`): (0) defunct preflight, (1) enabled, (2) zero-rect, (3) off-viewport (auto-`showOnScreen` if a `Scrollable` ancestor exists), (4) not-stable (2-frame rect drift > 0.5px; opt-out `--no-checkStable`), (5) receives-events (hit-test path includes target or descendant; opt-out `--no-checkReceivesEvents`). New checks append; do not reorder.
7. `e<N>` and `q<N>` token spaces are disjoint. Never mint `e<N>` from `ext.dusk.find`/`observe` or `q<N>` from `ext.dusk.snap`.
8. The 6 alpha-1 MCP tool names (`dusk_snap`, `dusk_tap`, `dusk_screenshot`, `dusk_hover`, `dusk_drag`, `dusk_type`) and their backing `ext.dusk.*` method names. Renames break pinned consumer scripts and agent prompts.
9. `install.yaml` at the package root is load-bearing for `plugin:install fluttersdk_dusk`. Do not delete; it carries the post-install bootstrap message and the `executables:` mapping anchor.
10. No new production dependencies beyond `fluttersdk_artisan`, `image`, `meta`, `fluttersdk_wind_diagnostics_contracts`.

## Style

- `final class` on new concrete record types and command impls. `abstract class` for handler shared bases when one exists.
- `Element` references inside enrichers are never retained across calls; the enricher contract is synchronous and stateless.
- Every `developer.registerExtension` call routes through `registerExtensionIdempotent` (from `fluttersdk_artisan`); duplicate registration on hot-restart would otherwise throw `ArgumentError`.
- Numbered step comments (`// 1.`, `// 2.`) inside handler bodies that have three or more distinct phases (parse params, actionability check, synthesise event, return payload).
- Docblocks (`///`) on public classes and the public contracts only; skip decorative docstrings on trivial getters.
- No mockito. Stub via contract inheritance or plain fakes inside the test file. `RefRegistry.resetForTesting()` in `tearDown` to prevent ref state leaking between tests.