Components workstream #4274

Goal

Make packages/agentic/components trustworthy for beta adoption and eventually
production use. A consumer should be able to tell which components are ready,
every component should follow the same React Native contract and test model, and
the remaining Fluent catalog should be delivered in dependency order with real
macOS and Windows evidence.

Status

In progress. Three of nine direct work items are closed; six remain open.

PR #4296
completed the spec-system foundation and a substantial implementation-alignment
pass:

• Replaced copied web-oriented source specs with independently authored React
  Native contracts backed by a pinned Flex Marketplace release, immutable x3
  provenance, source locks, local contract validation, and authenticated drift
  reporting. This closes #4252.
• Added TabList with controlled and uncontrolled selection, roving focus,
  orientation-aware keyboard navigation, disabled-item skipping, and native set
  metadata. There are now 19 reviewed local component contracts.
• Fixed ten component-local defects and four shared or parent-infrastructure
  gaps, including focus modality and phase-locked shared animation behavior.
• Preserved repaired divergence IDs as resolved history. Ten reviewed
  divergences remain deferred: four need platform or interaction validation and
  six need separately reviewed public API decisions.
• Passed the complete uncached repository graph after merging current main
  (165 Lage tasks).

The FURN-only primitive boundary
(#4250) and
Callout platform inconsistencies
(#4291) are
also closed.

What is left

1. Define and publish the component readiness model and initial assessment
   (#4251).
2. Finish the uniform component-test contract and accessibility conformance
   registry (#4216,
   #4214).
3. Resolve Button versus ToggleButton API ownership before generating
   ToggleButton (#4215).
4. Complete Fabric FocusZone for macOS and React Native Windows while
   preserving Win32 Paper behavior
   (#4217).
5. Reconcile the missing-component catalog with the pinned 49-component release,
   the current 52-entry candidate catalog, and the newly implemented TabList,
   then deliver the remaining waves
   (#4273).
6. Record real macOS and React Native Windows Fabric keyboard, focus, and
   screen-reader evidence for every component promoted to beta.

Work items

Beta exit criteria

• The component contract source is pinned, provenance is recorded, and
  fork-safe validation plus authenticated drift reporting are available.
• All currently implemented components have reviewed local React Native
  contracts, usage guidance, and explicit web divergences.
• Every exported primitive has an explicit ownership and contract policy.
• Every exported component and primitive satisfies one enforced test
  coverage contract on the supported test platforms.
• Every exported higher-order component passes the shared accessibility
  conformance suite.
• Every exported component carries a consumer-visible readiness level
  computed from objective evidence.
• Button and ToggleButton have non-overlapping approved contracts.
• FocusZone works on macOS Fabric and React Native Windows Fabric, and its
  Win32 Paper coverage remains green.
• The refreshed wave 1 and wave 2 catalog is implemented at beta readiness
  or has an evidence-backed blocker.
• Every beta-marked component has documented macOS and React Native Windows
  Fabric validation.

Production exit criteria

• Every component in the approved catalog is production-ready or explicitly
  declined with rationale.
• Readiness is CI-gated so a component cannot be marked above its evidence.
• Keyboard, focus, and screen-reader behavior is validated on every
  supported desktop endpoint.
• Local contract integrity fails CI; authorized source drift is reviewed
  against the immutable pin without requiring private source access in
  public or fork CI.
• Every replacement for a legacy component has migration guidance and an
  explicit legacy-package disposition.

Agent context

Contract authority

Use this order of authority:

1. The pinned Flex Marketplace payload is the exact authoring input.
2. The pinned x3 commit provides immutable design lineage.
3. The reviewed local React Native SPEC.md is authoritative for FURN behavior,
   usage, accessibility, and intentional web divergence.
4. Mutable Marketplace or x3 HEAD is candidate drift for review, not an
   automatic contract update.

The merged source lock uses Marketplace commit
206c4996205b027f4d806ac4ac7366f1f0ab0d5a and x3 commit
334d3b82a08b610b0002fe922ce9b4dac4db64f2. Public and fork CI validate
committed contract metadata without reading private sources; authorized
maintainers run source refresh and candidate-drift discovery.

Remaining reviewed divergences

Platform or interaction validation is still required for Input whole-field
hover/focus treatment, ProgressBar determinate animation, and Switch keyboard
activation. Separately reviewed API decisions remain for Avatar and Skeleton
focusability, Checkbox-owned native props, Button/ToggleButton separation,
Button icon positions, and Divider sizing.

Dependencies and sequencing

• Readiness depends on the enforced component-test and accessibility evidence.
• ToggleButton depends on the Button contract decision.
• Focus-orchestrated components depend on FocusZone or an explicitly approved
  component-owned navigation model.
• Overlay components should establish Popover, anchoring, light-dismiss, and
  focus-trap foundations before dependent menus, dialogs, tooltips, and
  teaching surfaces.
• Platform readiness depends on the desktop-driver and Storybook work in
  #4275.
• Component styling depends on the unified theme contract tracked by
  #4276.

Merged evidence

• PR #4296 - Pivot agentic component specs and align implementations
• PR #4295 - Add appearance-aware Flex theme sources
• PR #4294 - Infrastructure: land the public desktop driver
• packages/agentic/components/SPEC-SOURCE.md
• packages/agentic/components/SPEC-MIGRATION.md
• packages/agentic/components/spec-source-lock.json
• packages/agentic/components/scripts/spec-contracts/