Standardize isolated Flutter component previews

[ElbertePlinio]

Goal

Standardize a fast, isolated workflow for agents to render and verify one Flutter widget without starting the full app, auth, routing, or backend stack.

Decision

Use one workflow with three lanes, selected in this order:

1. Flutter Widget Previewer — preferred for interactive visual iteration when the project SDK supports flutter widget-preview start; generate a temporary @Preview adapter with the app's real theme, localization, and inherited dependencies.
2. Widget-test capture harness — preferred for deterministic state matrices, exact logical sizes, overflow detection, semantics/accessibility checks, and optional project-owned golden baselines.
3. Temporary web entrypoint — fallback only when the previewer is unavailable or cannot host the widget correctly.

PickLab should expose the public workflow through an MCP prompt and docs. The detailed agent automation should also be available as a portable global skill named flutter-component-preview.

No new PickLab runtime command is planned: an agent must still supply valid Dart that constructs the target widget and its state, so a generic CLI generator would be brittle and unsafe.

Workflow contract

• Discover the repo's Flutter/FVM command, target widget, theme, localization delegates, providers/inherited widgets, router/media dependencies, fonts, and representative states before generating anything.
• Prefer existing test wrappers/builders and fixture conventions; do not create a second app/test convention.
• Accept explicit widget states/data and configurable viewport matrices. Defaults: 390, 768, and 1440 logical pixels at DPR 1 unless the project or request says otherwise.
• Exercise normal and stress states: long/empty/error content where applicable, text scaling, semantics, tap-target/contrast guidelines, overflow/exceptions, and responsive breakpoints.
• Use real project fonts/assets. Report when rendering is non-deterministic or differs between widget-test and Chromium engines.
• Keep generated adapters, tests, screenshots, and logs temporary unless the user explicitly asks for permanent preview definitions or golden baselines.
• Track every generated path and remove only those paths in guaranteed cleanup. A failed or interrupted run must print cleanup instructions.
• Never modify production routing, app startup, committed feature code, existing golden baselines, or user-owned untracked files.
• Prefer artifacts outside the source tree. If Flutter requires an in-package temporary Dart target, use a unique path, verify it did not exist, and delete it after the run.
• End with evidence for each requested size/state and a source-tree cleanliness check.

Acceptance criteria

• PickLab registers a preview-flutter-component MCP prompt with target widget, states, and viewport arguments.
• The prompt teaches the lane-selection policy and composes existing PickLab browser/desktop sessions, screenshots, evidence reports, and human-blocker handling.
• Prompt tests cover discovery, all three lanes, responsive capture, accessibility/text scaling, production-routing protection, and guaranteed cleanup language.
• PickLab README lists the prompt and its intended use; release draft records the user-facing workflow.
• A portable global flutter-component-preview skill is added through agent-config-sync and distributed only to compatible harnesses.
• Shared global Flutter instructions contain one short trigger pointing agents to the skill; the workflow is not duplicated in global AGENTS/CLAUDE files.
• The skill uses the PickLab prompt when available and retains a tool-agnostic fallback for repos without PickLab.
• Smoke validation in a representative Flutter app captures supplied states at 390/768/1440, runs text-scale and semantics checks, and leaves no generated source files behind.
• Existing PickLab prompt tests, typecheck, and focused package tests pass.

PR plan

• PR 1 — PickLab public workflow
  • Depends on: none
  • Touches: MCP prompt registration/tests, README prompt list, release draft
  • Validation: focused prompt test, typecheck, build
  • Link: pending
• PR 2 — Portable global skill and trigger
  • Depends on: none; may land before PR 1 using its fallback path
  • Touches: chezmoi canonical skill, skill target registry, shared Flutter instruction template
  • Validation: agent-config-sync check, check-live, apply, representative Flutter smoke run
  • Link: pending
• Cross-check prompt and skill terminology after both slices land

Non-goals

• A generic Dart code generator that guesses widget constructors or provider state.
• Permanent preview routes or changes to the production app entrypoint.
• Automatically accepting or updating golden baselines.
• Replacing full-flow integration tests.

Release gating

No feature flag. This is an additive prompt/skill workflow and can ship in the next PickLab release.

Current status: Planned
Next action: implement the PickLab prompt slice, then validate the portable skill against a real Flutter component.