docs: link known limitations to tracked issues

README.md

@@ -220,6 +220,13 @@ for bundle contents and local validation.
 - [Framework roadmap](docs/roadmap/ModernFormsNext-Framework-Roadmap.md)
 - [Release process](RELEASING.md)
 
+## Known limitations
+
+ModernFormsNext 1.10.0 is stable on its primary Windows path, while several Designer, Android,
+cross-platform, compatibility, and manual-validation boundaries remain. The central
+[known-limitations index](docs/known-limitations.md) classifies them by type and severity and links
+to current issues and detailed subsystem documentation.
+
 ## Samples
 
 | Sample | Role |

docs-site/index.md

@@ -8,6 +8,9 @@ Start with the [project overview](content/README.md) or [getting started](conten
 Use the [API reference](api/index.md) for the public surface generated from the matching Release
 assemblies and XML documentation.
 
+Review the [known limitations](content/docs/known-limitations.md) before relying on platform,
+Designer, compatibility, or manual-validation behavior.
+
 > [!NOTE]
 > Windows is the primary and best-supported runtime target. Android support is experimental; use
 > the platform status documentation to distinguish implemented behavior from planned parity.

docs-site/toc.yml

@@ -10,6 +10,8 @@
   href: content/docs/samples.md
 - name: Platform status
   href: content/docs/platform-specific-features.md
+- name: Known limitations
+  href: content/docs/known-limitations.md
 - name: Architecture
   href: content/docs/architecture.md
 - name: Changelog

docs/1.10.0-release-notes.md

@@ -147,7 +147,9 @@ See [Migrating ModernFormsNext 1.9.0 applications to 1.10.0](migrations/1.9.0-to
 
 - `PathGeometry` does not yet include SVG import, arc segments, geometry groups, or a general
   `Stretch` contract.
-- Brush interpolation requires compatible brush kinds and compatible gradient-stop structures.
+- Brush interpolation supports compatible built-in brush kinds, including different non-empty stop
+  counts. Cross-kind gradient geometry, empty-to-populated gradients, Glass/NoBrush/null, and custom
+  or derived brushes remain discrete.
 - Custom animation/effect metadata is deliberately constrained in the Designer; arbitrary project
   code is not executed for preview.
 - Android remains experimental and is not presented as a complete `Application.Run(Form)` or

docs/android-backend.md

@@ -167,6 +167,9 @@ validation role.
   disposal behavior run as `net10.0` tests. Deployment remains an explicit device/emulator step
   through repository scripts.
 
+See the [central known-limitations index](known-limitations.md) for issue mapping and validation
+priorities. Automated host tests and successful Android builds are not physical-device evidence.
+
 ## Troubleshooting
 
 - `NotDeclared`: add the exact `<uses-permission>` reported by the diagnostic to the application

docs/animations.md

@@ -550,7 +550,7 @@ focus ring
 ```
 
 Ripple is not implemented by individual renderers. `IInteractionEffectClip` can provide a custom
-Skia clip for future shape/geometry controls. The built-in
+Skia clip for advanced geometry-aware effects. The built-in
 `ControlBoundsInteractionEffectClip.Instance` clips to scaled bounds and the resolved border
 radius. Each effect reuses its `InteractionEffectRenderContext` between frames; it borrows the
 target-local canvas for the current render call, so effects must never retain either object.
@@ -596,8 +596,10 @@ final-value path. Positive duration scale is captured when each animation starts
 Windows reads `SPI_GETCLIENTAREAANIMATION` during framework startup and refreshes it from the
 existing WindowKit message-only window on `WM_SETTINGCHANGE`. This adds no polling loop, timer, or
 native handle. The experimental Android backend reads `Settings.Global.ANIMATOR_DURATION_SCALE`
-and `TRANSITION_ANIMATION_SCALE` when a usable Activity context exists and refreshes on foreground
-entry. Android intentionally has no live settings observer in this stage.
+when a usable Activity context exists. While animation policy has subscribers and the Activity is
+usable, a `ContentObserver` refreshes the value through the main-Looper dispatcher. The
+subscription is removed while the host is backgrounded or unused, and foreground entry refreshes
+the snapshot.
 
 ## Diagnostics and faults
 
@@ -641,8 +643,8 @@ conservative generated shape and never executes project code or reflects arbitra
 
 The current Designer has dirty/save support but no transaction-based undo/redo stack. Therefore a
 successful collection commit participates in normal save/reload and code regeneration, but it does
-not claim undo/redo integration. Custom interaction-effect types and custom easing delegates remain
-code-first.
+not claim undo/redo integration. Explicitly attributed project effects can use the safe source-
+described metadata path; unsupported custom effects and custom easing delegates remain code-first.
 
 ## Windows and experimental Android
 
@@ -678,8 +680,6 @@ stops when no runnable work remains.
 - The Designer supports built-in effects, explicitly source-described project effects, layout
   transitions, visual-state transitions, and built-in easing identifiers. Custom easing delegates,
   general `AnimationDefinition` activation, and Designer undo/redo remain code-first/unavailable.
-- Android platform preference refresh occurs on startup/foreground or explicit refresh; there is no
-  live `ContentObserver` in this experimental stage.
 - Android is experimental; physical-device frame pacing, multi-touch rendering,
   platform settings changes, background/foreground, and orientation changes still require manual
   validation.
@@ -690,5 +690,6 @@ See [the scheduler architecture](architecture/ui-animation-scheduler.md), the
 [composable-animation architecture decision](architecture/decisions/ADR-Composable-Animations-And-Interaction-Effects.md),
 the [animation platform polish decision](architecture/decisions/ADR-Animation-Platform-Polish.md),
 the [Designer animation/effect contract](designer-animation-effects.md),
+the [central known-limitations index](known-limitations.md),
 and **Animations and Interaction Effects** in `samples/ControlGallery` for implementation rationale
 and interactive checks.

docs/architecture.md

@@ -17,7 +17,7 @@ ModernFormsNext (UI Framework)
         ↓
 WindowKit (Platform Abstraction)
         ↓
-Platform Backend (Windows, Linux, etc.)
+Platform Backend (supported Windows, experimental Android)
         ↓
 Rendering (SkiaSharp)
 ```
@@ -63,13 +63,14 @@ This layer allows the framework to keep a consistent API while delegating platfo
 
 ## Platform Backends
 
-Each supported platform can provide its own backend.
+Each platform can provide its own backend. Windows is the supported full runtime backend; Android
+is an experimental shared-control host. The repository does not currently provide supported Linux
+or macOS application backends.
 
-Examples:
+Current implementations:
 
-- Windows backend
-- Linux backend
-- macOS backend
+- supported Windows backend;
+- experimental Android backend foundation and Skia control surface.
 
 Responsibilities:
 
@@ -140,6 +141,8 @@ Planned and possible future areas include:
 
 - improved platform support
 - more advanced rendering features
-- animation systems
 - additional modern controls
 - deeper customization of platform services
+
+See [Known limitations](known-limitations.md) for the current platform, rendering, and tooling
+boundaries rather than treating possible future backends as supported implementations.

docs/architecture/animated-layout.md

@@ -7,10 +7,10 @@ It lets a control move and resize smoothly after application code or a layout en
 rectangle. It does not introduce another visual tree, layout engine, timer, or platform-specific
 control implementation.
 
-The first version interpolates the complete `RectangleF` (`X`, `Y`, `Width`, and `Height`) as one
-value. Navigation transitions, designer editing, and Android-specific runtime integration remain
-separate work. Selected visual-state content metrics build on this foundation through the linked
-layout-aware contract below.
+The implementation interpolates the complete `RectangleF` (`X`, `Y`, `Width`, and `Height`) as one
+value. Navigation transitions remain separate work. The Designer serializes a safe known-easing
+subset, Android uses the shared Choreographer-backed scheduler, and selected visual-state content
+metrics build on this foundation through the linked layout-aware contract below.
 
 ## Logical and presentation geometry
 
@@ -131,20 +131,21 @@ card.Bounds = new Rectangle(100, 50, 400, 200);
 ```
 
 `LayoutTransition` is expandable in a property grid. `Enabled` and `Duration` are ordinary editable
-properties. Easing remains a code-first delegate and is hidden from designer serialization until a
-future known-easing editor can represent it without serializing arbitrary delegates.
+properties. The ModernFormsNext Designer stores built-in easing identifiers without serializing
+arbitrary delegates; custom easing delegates remain code-first.
 
 ## Current limitations
 
 - transitions are configured per control; there is no inherited container policy;
 - controls without positive source and target area snap instead of animating through zero size;
 - parent overflow and clipping behavior is unchanged;
-- the Visual Studio Designer has no transition editor or preview integration yet;
-- Android uses the shared scheduler contract, but broader Android animation-runtime work remains
-  deferred to issue #29;
+- the Designer edits and round-trips transition configuration but does not run a live transition
+  preview;
+- Android uses the shared scheduler and Choreographer frame source, but broad emulator and
+  physical-device validation remains outstanding;
 - layout-aware visual-state composition is defined in
-  [Layout-aware visual-state metrics](layout-aware-visual-state-metrics.md); Designer editing of
-  custom transition definitions remains deferred to issue #28.
+  [Layout-aware visual-state metrics](layout-aware-visual-state-metrics.md); metrics outside padding
+  and border widths remain discrete.
 
 The ControlGallery **Animated layout** page provides manual checks for movement, resizing, rapid
 retargeting, hit testing, nested content, and disabling a transition mid-flight.

docs/architecture/brush-interpolation.md

@@ -129,9 +129,10 @@ brush per frame. Scheduler batching retains the existing one-invalidation-batch-
   discrete fallback.
 - Color channels use the existing sRGB interpolation; linear-light or color-space selection is not
   introduced here.
-- No new Designer editor or serialized transition format is added; that belongs to issue #28.
-- The planner is platform-neutral. Experimental Android compiles against it, but full device frame
-  pacing and runtime validation remain part of issue #29.
+- The Designer serializes known visual-state transition/easing metadata, but it does not live-
+  preview transitions and custom delegate easing remains code-first.
+- The planner is platform-neutral and the Android scheduler integration is implemented. Full
+  physical-device frame-pacing and rendering validation remains outstanding.
 
 See also [Paint and gradient architecture](paint-and-gradients.md),
 [UI animation scheduler architecture](ui-animation-scheduler.md), and

docs/architecture/decisions/ADR-Animation-Platform-Polish.md

@@ -1,6 +1,12 @@
 # ADR: Animation platform policy, ripple overflow, and Designer effects
 
-Status: Accepted for the animation platform polish draft
+Status: Accepted; implemented in 1.9.0 and extended in 1.10.0
+
+Implementation note (2026-08-18): the Android provider now observes
+`Settings.Global.ANIMATOR_DURATION_SCALE` while the lifecycle is foreground and animation policy
+has subscribers. Issue #28 expanded the detached Designer model to attributed project effects and
+added layout/visual-state transition editors. The sections below describe the accepted design with
+those delivered amendments.
 
 ## Context
 
@@ -53,16 +59,15 @@ ModernFormsNext behavior.
 
 ### Experimental Android source
 
-The Android provider reads `Settings.Global.ANIMATOR_DURATION_SCALE` and
-`TRANSITION_ANIMATION_SCALE`. A finite zero value in either setting requests reduced motion; both
-values must be positive to permit animations. The application context is sufficient, so no
-foreground `Activity` is required.
+The Android provider reads `Settings.Global.ANIMATOR_DURATION_SCALE`. A finite zero value requests
+reduced motion; a positive value permits animations and scales newly started durations. The
+provider uses the current Activity when one is usable.
 
-Android live observation is intentionally limited in this experimental backend. The scheduler
-refreshes the provider when the shared lifecycle reports `Foreground`. This avoids a permanent
-`ContentObserver` and its `Handler` ownership while still reflecting changes after resume. Missing
-context, inaccessible settings, malformed values, and platform exceptions use the same safe
-fallback as Windows. Device/emulator runtime behavior must not be claimed from compile-time or
+Live observation is lifecycle- and subscription-aware. A main-Looper `ContentObserver` exists only
+while the shared lifecycle is foreground and the provider has subscribers; it is removed when the
+host backgrounds or the final subscriber leaves. Foreground entry also refreshes the snapshot.
+Missing context, inaccessible settings, malformed values, and platform exceptions use the same
+safe fallback as Windows. Device/emulator runtime behavior must not be claimed from compile-time or
 abstraction tests alone.
 
 ### Threading and lifetime
@@ -91,9 +96,9 @@ shared scheduler; disposal and cancellation clear their handles and visual state
 
 The runtime `InteractionEffectCollection` remains the owner-attached collection. Designer-only
 editing lives in `ModernFormsNext.Designer` and supports the built-in `RippleEffect` and
-`PressScaleEffect`. Issue #28 extends the same detached contract to explicitly attributed project
-effects discovered from source. Missing or changed project types are retained as unavailable
-definitions and never instantiated by Designer.
+`PressScaleEffect`. The completed issue #28 extends the same detached contract to explicitly
+attributed project effects discovered from source. Missing or changed project types are retained as
+unavailable definitions and never instantiated by Designer.
 
 The `.mfdesign` value is a deterministic structured object containing `Count` and ordered `ItemN`
 entries. Each entry stores a type discriminator and supported serializable properties. Generated
@@ -136,15 +141,15 @@ touch pointer may move keyboard focus but does not cancel the earlier touch sequ
 
 ## Known limitations
 
-- Android refreshes on foreground instead of observing the global setting continuously.
-- Android runtime behavior requires a device or emulator for confirmation.
-- The Designer initially supports only `RippleEffect` and `PressScaleEffect` and their safe,
-  deterministic properties; arbitrary easing delegates and custom clip implementations are not
-  serialized.
+- Android runtime behavior still requires broad emulator and physical-device confirmation.
+- The Designer supports built-in and explicitly attributed source-discovered effects, but arbitrary
+  easing delegates, custom clip implementations, and live effect preview are not serialized or
+  executed.
 - Designer undo/redo remains unavailable because the existing Designer session has no command
   transaction stack.
-- This work does not add animated layout, gradient-stop morphing, Shapes/Geometry, new large
-  effects, or broader Android runtime stabilization.
+- Cell/row/action-cell targeting, new large effects, and broader Android runtime stabilization
+  remain separate work. Animated layout, normalized gradient-stop interpolation, and
+  Shapes/Geometry were delivered later in 1.10.0.
 
 ## Consequences
 

docs/architecture/decisions/ADR-Composable-Animations-And-Interaction-Effects.md

@@ -4,6 +4,11 @@
 - Date: 2026-07-23
 - Scope: `ModernFormsNext`, `ModernFormsNext.WindowKit`, platform hosts, Designer, and ControlGallery
 
+Implementation note (2026-08-18): ModernFormsNext 1.10.0 added animated bounds, padding and border-
+width visual-state interpolation, a broader brush compatibility planner, detached Designer editors,
+and the Android Choreographer/settings-provider integration. Those later additions amend the
+original first-release limitations without changing this ADR's single-scheduler decision.
+
 ## Context
 
 ModernFormsNext already has a process-wide `AnimationScheduler`, typed interpolators, monotonic
@@ -153,7 +158,7 @@ ripple is not added to individual control renderers.
 
 Effects use `IInteractionEffectClip`. The built-in bounds clip respects the current
 `ControlStyle.Border` corner radius. The abstraction intentionally accepts a control and a Skia
-canvas so future Shapes/Geometry implementations can provide a path without changing effect APIs.
+canvas so advanced geometry-aware effects can provide a path without changing effect APIs.
 The canvas is borrowed and is never retained.
 
 ### Repaint batching and performance
@@ -202,10 +207,14 @@ No runtime-success claim is made without a device or emulator.
 
 ## Known limitations
 
-- Layout-property interpolation is intentionally not provided by visual-state transitions.
-- Incompatible brush structures switch discretely.
+- Visual-state layout interpolation is intentionally limited to padding and border widths; other
+  layout metrics switch discretely.
+- Cross-kind gradient geometry, Glass/NoBrush/null, empty-to-populated gradients, and custom brush
+  structures switch discretely.
 - Legacy renderers that draw specialized item focus indicators continue to own those indicators;
   the final focus-overlay hook is available for new effects and control-specific migration.
-- Android frame pacing, multi-touch visuals, background/foreground behavior, and orientation
-  changes require device or emulator validation.
-- Designer collection editors are intentionally minimal; complex effect editing is code-first.
+- Android frame pacing, multi-touch visuals, background/foreground behavior, setting changes, and
+  orientation changes require broad device or emulator validation.
+- Designer editors support the safe detached metadata subset and known easing identifiers. Custom
+  delegate easing, general `AnimationDefinition` activation, live effect preview, and Designer-wide
+  undo/redo remain unavailable.

docs/architecture/decisions/ADR-Paint-And-Gradient-System.md

@@ -1,9 +1,13 @@
 # ADR: Evolve Brush as the canonical paint value
 
-- Status: Accepted for implementation
+- Status: Accepted; implemented
 - Date: 2026-07-19
 - Scope: `ModernFormsNext.Drawing`, control brush properties, dynamic resources, and Skia rendering
 
+Implementation note (2026-08-18): ThemeManager, strict theme JSON, brush interpolation, and the
+1.10.0 Shape/Geometry system now consume this completed paint foundation. Historical references to
+future downstream consumers describe the stage boundary, not their current repository status.
+
 ## Context
 
 ModernFormsNext 1.8.0 already exposes a public `Brush` hierarchy for solid, linear, radial, sweep,