feat: introduce a2ui_core library

.github/workflows/flutter_packages.yaml

@@ -172,4 +172,4 @@ jobs:
         working-directory: ${{ matrix.package.path }}
         run: |
           dart pub global activate layerlens
-          layerlens --fail-on-cycles  --except "lib/src/schema"
+          layerlens --fail-on-cycles  --except "lib/src/schema" --except "lib/src/core"

packages/a2ui_core/lib/a2ui_core.dart

@@ -2,8 +2,37 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+/// Core A2UI protocol implementation for Dart.
+library;
+
+export 'src/common/cancellation.dart';
+export 'src/common/data_path.dart';
+// Common utilities.
+export 'src/common/errors.dart';
+// Reactivity layer (extends listenable primitives with batch + computed).
+export 'src/common/reactivity.dart';
+// Protocol models.
+export 'src/core/catalog.dart';
+export 'src/core/common.dart';
+export 'src/core/common_schemas.dart';
+export 'src/core/component_model.dart';
+// Rendering support.
+export 'src/core/contexts.dart';
+// State management.
+export 'src/core/data_model.dart';
+export 'src/core/messages.dart';
+export 'src/core/minimal_catalog.dart';
+export 'src/core/surface_model.dart';
+// Listenable primitives from the shared notifier layer.
+// ValueNotifier is intentionally excluded here because reactivity.dart provides
+// an enhanced version with batch and dependency-tracking support.
 export 'src/listenable/error_reporting.dart'
     show ListenableError, ListenableErrorDetails;
 export 'src/listenable/notifiers.dart'
-    show ChangeNotifier, GenUiListenable, GenUiValueListenable, ValueNotifier;
+    show ChangeNotifier, GenUiListenable, GenUiValueListenable;
 export 'src/listenable/primitives.dart' show VoidCallback;
+export 'src/processing/basic_functions.dart';
+export 'src/processing/expressions.dart';
+// Processing & expressions.
+export 'src/processing/processor.dart';
+export 'src/rendering/binder.dart';

packages/a2ui_core/lib/src/common/cancellation.dart

@@ -0,0 +1,59 @@
+// Copyright 2025 The Flutter Authors.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/// A signal that can be used to cancel an operation.
+class CancellationSignal {
+  bool _isCancelled = false;
+
+  final _listeners = <void Function()>[];
+
+  /// Whether the operation has been cancelled.
+  bool get isCancelled => _isCancelled;
+
+  /// Cancels the operation.
+  void cancel() {
+    if (_isCancelled) return;
+    _isCancelled = true;
+    final List<void Function()> listeners = List.of(_listeners);
+    _listeners.clear();
+    for (final listener in listeners) {
+      listener();
+    }
+  }
+
+  /// Adds a listener to be notified when the operation is cancelled.
+  void addListener(void Function() listener) {
+    if (_isCancelled) {
+      listener();
+    } else {
+      _listeners.add(listener);
+    }
+  }
+
+  /// Removes a listener.
+  void removeListener(void Function() listener) {
+    _listeners.remove(listener);
+  }
+
+  /// Throws a [CancellationException] if the operation has been cancelled.
+  void throwIfCancelled() {
+    if (_isCancelled) {
+      throw const CancellationException();
+    }
+  }
+}
+
+/// An exception thrown when an operation is cancelled.
+class CancellationException implements Exception {
+  /// Creates a [CancellationException].
+  const CancellationException([this.message]);
+
+  /// A message describing the cancellation.
+  final String? message;
+
+  @override
+  String toString() => message == null
+      ? 'CancellationException'
+      : 'CancellationException: $message';
+}

packages/a2ui_core/lib/src/common/data_path.dart

@@ -0,0 +1,82 @@
+// Copyright 2025 The Flutter Authors.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:collection/collection.dart';
+
+/// A class for handling JSON Pointer (RFC 6901) paths.
+class DataPath {
+  final List<String> segments;
+
+  DataPath(this.segments);
+
+  /// Parses a JSON Pointer string into a [DataPath].
+  factory DataPath.parse(String path) {
+    if (path.isEmpty || path == '/') {
+      return DataPath([]);
+    }
+
+    var normalized = path;
+    if (path.startsWith('/')) {
+      normalized = path.substring(1);
+    }
+
+    if (normalized.endsWith('/')) {
+      normalized = normalized.substring(0, normalized.length - 1);
+    }
+
+    if (normalized.isEmpty) {
+      return DataPath([]);
+    }
+
+    final List<String> segments = normalized.split('/').map((s) {
+      return s.replaceAll('~1', '/').replaceAll('~0', '~');
+    }).toList();
+
+    return DataPath(segments);
+  }
+
+  /// The number of segments in the path.
+  int get length => segments.length;
+
+  /// Whether the path is empty (points to the root).
+  bool get isEmpty => segments.isEmpty;
+
+  /// Whether the path starts with a slash (is absolute).
+  bool get isAbsolute =>
+      true; // All parsed paths are treated as absolute for now in our context
+
+  /// Joins this path with another path or segment.
+  DataPath append(Object? other) {
+    if (other is DataPath) {
+      return DataPath([...segments, ...other.segments]);
+    } else if (other is String) {
+      if (other.startsWith('/')) {
+        return DataPath.parse(other);
+      }
+      return DataPath([...segments, ...DataPath.parse(other).segments]);
+    }
+    return DataPath([...segments, other.toString()]);
+  }
+
+  /// Returns the parent path.
+  DataPath? get parent {
+    if (segments.isEmpty) return null;
+    return DataPath(segments.sublist(0, segments.length - 1));
+  }
+
+  @override
+  String toString() {
+    if (segments.isEmpty) return '/';
+    return '/${segments.map((s) => s.replaceAll('~', '~0').replaceAll('/', '~1')).join('/')}';
+  }
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is DataPath &&
+          const ListEquality<String>().equals(segments, other.segments);
+
+  @override
+  int get hashCode => const ListEquality<String>().hash(segments);
+}

packages/a2ui_core/lib/src/common/errors.dart

@@ -0,0 +1,44 @@
+// Copyright 2025 The Flutter Authors.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/// Base class for all A2UI specific errors.
+class A2uiError implements Exception {
+  final String message;
+  final String code;
+
+  A2uiError(this.message, [this.code = 'UNKNOWN_ERROR']);
+
+  @override
+  String toString() => '$runtimeType [$code]: $message';
+}
+
+/// Thrown when JSON validation fails or schemas are mismatched.
+class A2uiValidationError extends A2uiError {
+  final Object? details;
+
+  A2uiValidationError(String message, {this.details})
+    : super(message, 'VALIDATION_ERROR');
+}
+
+/// Thrown during DataModel mutations (invalid paths, type mismatches).
+class A2uiDataError extends A2uiError {
+  final String? path;
+
+  A2uiDataError(String message, {this.path}) : super(message, 'DATA_ERROR');
+}
+
+/// Thrown during string interpolation and function evaluation.
+class A2uiExpressionError extends A2uiError {
+  final String? expression;
+  final Object? details;
+
+  A2uiExpressionError(String message, {this.expression, this.details})
+    : super(message, 'EXPRESSION_ERROR');
+}
+
+/// Thrown for structural issues in the UI tree (missing surfaces, duplicate
+/// components).
+class A2uiStateError extends A2uiError {
+  A2uiStateError(String message) : super(message, 'STATE_ERROR');
+}

packages/a2ui_core/lib/src/common/reactivity.dart

@@ -0,0 +1,164 @@
+// Copyright 2025 The Flutter Authors.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import '../listenable/notifiers.dart' as notifiers;
+
+/// Alias for [notifiers.GenUiListenable].
+typedef Listenable = notifiers.GenUiListenable;
+
+/// Alias for [notifiers.GenUiValueListenable].
+typedef ValueListenable<T> = notifiers.GenUiValueListenable<T>;
+
+bool _inBatch = false;
+final _pendingNotifiers = <ValueNotifier<Object?>>{};
+
+/// Executes [callback] and defers notifications until it completes.
+void batch(void Function() callback) {
+  if (_inBatch) {
+    callback();
+    return;
+  }
+
+  _inBatch = true;
+  try {
+    callback();
+  } finally {
+    _inBatch = false;
+    final List<ValueNotifier<Object?>> toNotify = _pendingNotifiers.toList();
+    _pendingNotifiers.clear();
+    for (final notifier in toNotify) {
+      notifier.forceNotify();
+    }
+  }
+}
+
+/// A value holder that notifies listeners when the value changes.
+///
+/// Extends [notifiers.ChangeNotifier] for robust listener management and adds
+/// batch-aware notification and automatic dependency tracking for use with
+/// [ComputedNotifier].
+class ValueNotifier<T> extends notifiers.ChangeNotifier
+    implements notifiers.GenUiValueListenable<T> {
+  T _value;
+
+  ValueNotifier(this._value);
+
+  @override
+  T get value {
+    _DependencyTracker.instance?._reportRead(this);
+    return _value;
+  }
+
+  set value(T newValue) {
+    if (_value == newValue) return;
+    _value = newValue;
+    if (_inBatch) {
+      _pendingNotifiers.add(this);
+      return;
+    }
+    notifyListeners();
+  }
+
+  /// Notifies listeners unconditionally, even if the value hasn't changed.
+  ///
+  /// Use this when the held value is a mutable container (e.g. a [Map] or
+  /// [List]) whose contents changed in place without changing the reference.
+  void forceNotify() {
+    if (_inBatch) {
+      _pendingNotifiers.add(this);
+      return;
+    }
+    notifyListeners();
+  }
+}
+
+/// A derived notifier that automatically tracks and listens to other
+/// [ValueListenable] dependencies, recalculating its value only when they
+/// change.
+class ComputedNotifier<T> extends ValueNotifier<T> {
+  final T Function() _compute;
+  final Set<notifiers.GenUiValueListenable<Object?>> _dependencies = {};
+
+  ComputedNotifier(this._compute) : super(_initialValue(_compute)) {
+    _subscribePendingDeps();
+  }
+
+  // Stack-based pending deps to handle reentrant ComputedNotifier creation
+  // (e.g. when _compute itself creates a nested ComputedNotifier).
+  static final List<Set<notifiers.GenUiValueListenable<Object?>>>
+  _pendingDepsStack = [];
+
+  static T _initialValue<T>(T Function() compute) {
+    final tracker = _DependencyTracker();
+    final T value = tracker.track(compute);
+    _pendingDepsStack.add(tracker.dependencies);
+    return value;
+  }
+
+  void _subscribePendingDeps() {
+    final Set<notifiers.GenUiValueListenable<Object?>> deps = _pendingDepsStack
+        .removeLast();
+    for (final dep in deps) {
+      dep.addListener(_onDependencyChanged);
+    }
+    _dependencies.addAll(deps);
+  }
+
+  void _updateDependencies() {
+    final tracker = _DependencyTracker();
+    final T newValue = tracker.track(_compute);
+
+    final Set<notifiers.GenUiValueListenable<Object?>> newDeps =
+        tracker.dependencies;
+
+    // Unsubscribe from old dependencies no longer needed.
+    for (final notifiers.GenUiValueListenable<Object?> dep
+        in _dependencies.difference(newDeps)) {
+      dep.removeListener(_onDependencyChanged);
+    }
+
+    // Subscribe to new dependencies.
+    for (final notifiers.GenUiValueListenable<Object?> dep
+        in newDeps.difference(_dependencies)) {
+      dep.addListener(_onDependencyChanged);
+    }
+
+    _dependencies.clear();
+    _dependencies.addAll(newDeps);
+
+    super.value = newValue;
+  }
+
+  void _onDependencyChanged() {
+    _updateDependencies();
+  }
+
+  @override
+  void dispose() {
+    for (final notifiers.GenUiValueListenable<Object?> dep in _dependencies) {
+      dep.removeListener(_onDependencyChanged);
+    }
+    _dependencies.clear();
+    super.dispose();
+  }
+}
+
+class _DependencyTracker {
+  static _DependencyTracker? instance;
+  final Set<notifiers.GenUiValueListenable<Object?>> dependencies = {};
+
+  T track<T>(T Function() callback) {
+    final _DependencyTracker? previous = instance;
+    instance = this;
+    try {
+      return callback();
+    } finally {
+      instance = previous;
+    }
+  }
+
+  void _reportRead(notifiers.GenUiValueListenable<Object?> listenable) {
+    dependencies.add(listenable);
+  }
+}