A widget that can render a JSON protocol with a catalog and separate state.

[gspencergoog]

Description

This PR introduces the initial, feature-complete implementation of the fcp_client package, a client-side library for the Flutter Composition Protocol (FCP).

This package allows a Flutter application to render and manage a user interface based on JSON payloads sent from a server, strictly following the protocol defined in the project's documentation. The implementation was developed following the detailed plan in docs/FCP Implementation Plan.md.

Here's the summary of the protocol:

The Flutter Composition Protocol (FCP) is a framework for rendering Flutter user interfaces from a JSON definition. The design is guided by principles of strict separation of concerns, versioning, and targeted updates, with schemas constrained for compatibility with structured data generation models. It draws inspiration from existing solutions like Remote Flutter Widgets (RFW) while introducing a more formalized, contract-driven approach to enhance stability and predictability.

Features Implemented

This PR delivers the full feature set specified in the FCP documentation, covering all 5 implementation milestones:

• Milestone 1: Core Models & Static Rendering

  • All FCP data models (DynamicUIPacket, WidgetNode, etc.) implemented using Dart extension types for type safety without code generation.
  • A robust layout engine (FcpView) that can parse the non-recursive node list and render a static Flutter widget tree.
  • A CatalogService for loading the client's capabilities catalog and a WidgetCatalogRegistry for mapping widget types to builders.

• Milestone 2: State Management & Data Binding

  • A central FcpState manager (ChangeNotifier) to hold dynamic UI data.
  • A BindingProcessor service that resolves data paths and applies declarative transformations (format, condition, map).
  • The UI now reactively rebuilds when the state changes.

• Milestone 3: Event Handling

  • The FcpView exposes an onEvent callback to send user interactions to a backend.
  • Widget builders are wired to construct and emit a standard EventPayload, including contextual arguments.

• Milestone 4: Targeted Updates

  • State Patcher: Processes StateUpdate payloads using the json_patch standard to efficiently update the FcpState object.
  • Layout Patcher: Processes LayoutUpdate payloads (add, remove, update) to make surgical changes to the UI's structure.
  • An FcpViewController provides a clean, stream-based API for dispatching both state and layout updates to the FcpView.

• Milestone 5: Advanced Features & Refinement

  • ListViewBuilder: A special builder that uses Flutter's ListView.builder for efficiently rendering dynamic lists, including support for scoped item. bindings.
  • Data Type Validation: Integrates the json_schema package to validate incoming state against schemas defined in the WidgetCatalog.
  • Robust Error Handling: The layout engine now validates widgets and properties against the catalog, rendering a descriptive error widget instead of crashing on violations.

Key Architectural Decisions & Learnings

The development journey, chronicled in docs/JOURNEY.md, led to several key decisions and learnings that shaped the final architecture:

• Testing Strategy: Integration tests are implemented in a dedicated test fixture application (test_fixtures/m1_integration), which is the correct pattern for testing a Flutter package.
• Layout Engine: The engine was significantly refactored to be a ChangeNotifier itself. It now passes a Map of named children (e.g., appBar, body) to widget builders instead of a flat list, making builders more robust and less prone to ordering errors.
• API Documentation: The entire public API surface has been documented with comprehensive doc comments (///) to ensure the package is easy for developers to understand and use.

Testing

The package has extensive test coverage:

• Unit Tests: Core services like the BindingProcessor, LayoutPatcher, StatePatcher, and DataTypeValidator are thoroughly tested. All data models are also validated.
• Widget Tests: The FcpView is tested for rendering, event handling, state/layout updates, error handling, and the ListViewBuilder.
• Integration Tests: A test fixture app in test_fixtures/m1_integration verifies the end-to-end functionality in a running application.

All 74 tests pass, ensuring the package is stable and correct.

[gspencergoog]

/gemini review