Update README.md to articulate DataContext and UI properties

- Add DataContext Inheritance warning regarding local value assignments.
- Add Horizontal/VerticalContentAlignment to Control features.
- Clarify Foreground/Background dependency properties on UIElement.
- Log action in .jules/codex.md.

Co-authored-by: tedd <493224+tedd@users.noreply.github.com>

Author: google-labs-jules[bot]

.jules/codex.md

@@ -85,3 +85,6 @@
 **Observation:** The README.md exhibited documentation drift regarding the newly integrated `Separator` component. It lacked explicit articulation of this control, which inherits from `Control`, explicitly sets `Focusable = false`, and renders a horizontal line using the `\u2500` character to match the DOS-era styling, implementing standard XAML parity for menus and layouts.
 
 **Strategic Action:** Synchronized the README.md to articulate the `Separator` architecture under the 'Rich Control Suite' section. This ensures epistemological alignment with the current framework capabilities for menu and layout separators.
+## 2024-07-09 - DataContext Inheritance and Content Alignment
+**Observation:** The documentation lacked explicit articulation regarding the adverse effects of explicit local value assignments on `DataContext` inheritance. Furthermore, it omitted architectural details regarding `HorizontalContentAlignment`, `VerticalContentAlignment`, `Foreground`, and `Background` property definitions on `UIElement` vs `Control`.
+**Strategic Action:** Explicitly document that local `DataContext` assignments break WPF-isomorphic inheritance. Add sections detailing `HorizontalContentAlignment`/`VerticalContentAlignment` on `Control` and `Foreground`/`Background` on `UIElement` to eliminate speculative assumptions about property locations.

README.md

@@ -169,11 +169,13 @@ class Program
 ### Core System
 At the heart of Tedd.TUI is the `UIElement` class, which provides the foundation for:
 - **Visual Tree:** A hierarchical structure of elements allowing for complex composition. Any `UIElement` can dynamically ascend the visual tree to resolve its root host via the `GetRoot()` API, enabling recursive topological queries.
+- **HorizontalContentAlignment & VerticalContentAlignment:** To achieve WPF parity for content alignment, `Control` defines `HorizontalContentAlignment` and `VerticalContentAlignment` dependency properties, which are bound to the `HorizontalAlignment` and `VerticalAlignment` of internal `ContentPresenter` elements using `RelativeSource.TemplatedParent` within control templates.
+- **Foreground and Background:** Unlike standard WPF where they reside on `Control`, the `Foreground` and `Background` dependency properties are defined directly on `UIElement`, with `ForegroundProperty` configured to inherit (`isInherited: true`).
 - **Dependency Properties:** A property system that supports value inheritance, change notification, and memory conservation. `DependencyObject` implements `ClearValue` to deterministically remove local property overrides (allowing fallback to default or inherited values), while `SetValue(null)` explicitly stores a null value rather than deleting the entry, maintaining strict WPF isomorphism. Dependency Property value precedence within `DependencyObject.GetValue()` is resolved using discrete `_localValues` and `_triggerValues` dictionaries rather than a monolithic store: a local value assigned after a trigger becomes active overrides that trigger, otherwise an active trigger value overrides any pre-existing local value, followed by ordinary local values, inherited values, and finally default metadata. In other words, the effective order is post-trigger local override > trigger > local > inherited > default. Dependency Property accessors utilize C# expression-bodied members (`get => ...; set => ...;`) to minimize lexical boilerplate. Furthermore, API signatures deviate slightly from standard WPF: `DependencyProperty.Register` accepts default values directly rather than wrapped in a `PropertyMetadata` object.
 
 ### Data Binding
 Tedd.TUI implements a hierarchical data binding infrastructure analogous to WPF, systematically driven by the `DataContext` inherited dependency property. This established framework capability mitigates the need for speculative manual state synchronization.
-- **DataContext Inheritance:** The `DataContext` property is an explicitly defined inherited dependency property. The `DependencyObject` base architecture resolves inherited values by recursively querying `InheritanceParent` (which maps to `Parent` in `UIElement`). Assigning a `DataContext` at the visual root (e.g., `TuiWindow`) makes the data model available to descendant elements that have not set a local `DataContext`. Propagation is implemented in `UIElement.OnPropertyChanged` for inherited dependency properties by enumerating `GetVisualChild` and calling `OnPropertyChanged(dp)` on children that do not have a local value, which in turn updates bindings.
+- **DataContext Inheritance:** The `DataContext` property is an explicitly defined inherited dependency property. The `DependencyObject` base architecture resolves inherited values by recursively querying `InheritanceParent` (which maps to `Parent` in `UIElement`). Assigning a `DataContext` at the visual root (e.g., `TuiWindow`) makes the data model available to descendant elements that have not set a local `DataContext`. Explicit local value assignments on child controls (e.g., within `OnDataContextChanged` overrides or container setters) incorrectly override and break this WPF-isomorphic inheritance mechanism. Propagation is implemented in `UIElement.OnPropertyChanged` for inherited dependency properties by enumerating `GetVisualChild` and calling `OnPropertyChanged(dp)` on children that do not have a local value, which in turn updates bindings.
 - **INotifyPropertyChanged:** Models must implement `System.ComponentModel.INotifyPropertyChanged`. The internal `BindingExpression` autonomously hooks and unhooks to `PropertyChanged` events upon `DataContext` mutations, re-evaluating reflection paths when property names match or signify wholesale updates.
 - **Binding Resolutions:** The `SetBinding` method establishes a dynamic link between a target dependency property and a source property. While bindings default to resolving against the ambient `DataContext`, the framework exposes robust `RelativeSource` topologies:
   - `Self`: Targets the `UIElement` itself.