diff --git a/README.md b/README.md index e8ac01f..fff211a 100644 --- a/README.md +++ b/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 | diff --git a/docs-site/index.md b/docs-site/index.md index 15cd7d6..ac0d0ac 100644 --- a/docs-site/index.md +++ b/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. diff --git a/docs-site/toc.yml b/docs-site/toc.yml index ed59b8d..9e39b9c 100644 --- a/docs-site/toc.yml +++ b/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 diff --git a/docs/1.10.0-release-notes.md b/docs/1.10.0-release-notes.md index 2d99c1d..b440e4f 100644 --- a/docs/1.10.0-release-notes.md +++ b/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 diff --git a/docs/android-backend.md b/docs/android-backend.md index f144c89..ff2e182 100644 --- a/docs/android-backend.md +++ b/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 `` reported by the diagnostic to the application diff --git a/docs/animations.md b/docs/animations.md index 123b9d4..6d862bf 100644 --- a/docs/animations.md +++ b/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. diff --git a/docs/architecture.md b/docs/architecture.md index 0ea3cb9..0914c37 100644 --- a/docs/architecture.md +++ b/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. diff --git a/docs/architecture/animated-layout.md b/docs/architecture/animated-layout.md index 271b245..bc2d837 100644 --- a/docs/architecture/animated-layout.md +++ b/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. diff --git a/docs/architecture/brush-interpolation.md b/docs/architecture/brush-interpolation.md index 08672a6..11f4bdf 100644 --- a/docs/architecture/brush-interpolation.md +++ b/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 diff --git a/docs/architecture/decisions/ADR-Animation-Platform-Polish.md b/docs/architecture/decisions/ADR-Animation-Platform-Polish.md index 3cf2ec6..5d7823a 100644 --- a/docs/architecture/decisions/ADR-Animation-Platform-Polish.md +++ b/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 diff --git a/docs/architecture/decisions/ADR-Composable-Animations-And-Interaction-Effects.md b/docs/architecture/decisions/ADR-Composable-Animations-And-Interaction-Effects.md index a3e8435..ac17848 100644 --- a/docs/architecture/decisions/ADR-Composable-Animations-And-Interaction-Effects.md +++ b/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. diff --git a/docs/architecture/decisions/ADR-Paint-And-Gradient-System.md b/docs/architecture/decisions/ADR-Paint-And-Gradient-System.md index 510d0a7..4eefb8b 100644 --- a/docs/architecture/decisions/ADR-Paint-And-Gradient-System.md +++ b/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, diff --git a/docs/architecture/decisions/ADR-UI-Animation-Scheduler.md b/docs/architecture/decisions/ADR-UI-Animation-Scheduler.md index 9551e69..4a2022f 100644 --- a/docs/architecture/decisions/ADR-UI-Animation-Scheduler.md +++ b/docs/architecture/decisions/ADR-UI-Animation-Scheduler.md @@ -3,6 +3,10 @@ - **Status:** Accepted - **Date:** 2026-07-19 +Implementation note (2026-08-18): the tick-source seam now selects Android Choreographer when the +surface is eligible, and later releases added composition, native animation settings, ThemeManager, +Shape, Designer metadata, and animated layout without adding another scheduler. + ## Context ModernFormsNext has public control animation helpers and an animated `Switch`, but their internal @@ -63,8 +67,8 @@ Adopt the shared scheduler option. - Central policy implements enabled/reduced-motion behavior and duration scaling. - Android activity lifecycle implements a platform-neutral lifecycle contract consumed by the scheduler. -- Native frame callbacks and advanced animation composition remain future enhancements behind the - tick-source seam. +- Native frame callbacks and advanced animation composition remain behind the tick-source seam; + Android Choreographer and composable definitions are the current implementations. ## Consequences @@ -75,8 +79,9 @@ and timer lifetimes. The timer is a pacing request rather than a guarantee of a particular FPS. It can be replaced by a stable render-loop signal later. The scheduler owns active callbacks strongly until they terminate, -so custom owners must cancel when their lifecycle ends. Android physical-device pacing and native -reduced-motion discovery remain manual/future work. +so custom owners must cancel when their lifecycle ends. Android physical-device pacing remains +manual work. Native animation-scale discovery and live foreground observation are implemented +through the platform settings provider. ## Rejected alternatives diff --git a/docs/architecture/layout-aware-visual-state-metrics.md b/docs/architecture/layout-aware-visual-state-metrics.md index 004771b..8578055 100644 --- a/docs/architecture/layout-aware-visual-state-metrics.md +++ b/docs/architecture/layout-aware-visual-state-metrics.md @@ -18,7 +18,7 @@ target styles. State styles inherit unset values through their `ControlStyle.Par The transition runtime creates one temporary presentation style; it never writes interpolated values back to a target style. -Issue #26 supports these metrics: +The implemented 1.10.0 scope supports these metrics: - `ControlStyle.Padding`, interpolated independently on all four sides; - aggregate and per-side `BorderStyle.Width` values. @@ -84,6 +84,6 @@ The frame path performs no reflection or full style reconstruction. Snapshots ar interpolation is component-wise, and one existing temporary `ControlStyle` is reused throughout the transition. Layout runs only when an integer layout metric actually changes. -Designer transition editing remains outside this issue. `ControlStyle.Padding` is an ordinary -code-first style property suitable for future serialization, while delegate-valued transitions -remain hidden from current Designer serialization as before. +The Designer stores padding and border-width style values plus transition duration and known easing +identifiers. It does not live-preview the transition and never serializes arbitrary easing +delegates; those remain code-first. diff --git a/docs/architecture/paint-and-gradients.md b/docs/architecture/paint-and-gradients.md index 106c356..980027b 100644 --- a/docs/architecture/paint-and-gradients.md +++ b/docs/architecture/paint-and-gradients.md @@ -3,11 +3,12 @@ ## Status and scope This document records the state found after the 1.8.0 release and the target architecture for the -paint/brush hardening stage. The stage deliberately stops before ThemeManager, shapes, charts, a -new animation scheduler, or a theme JSON loader. Its output is a reusable visual-value contract for -those later features. +paint/brush hardening stage. That stage is implemented. ThemeManager, strict theme JSON, the shared +animation scheduler, and the Shape/Geometry foundation now consume the resulting visual-value +contract; charts remain future work. Sections describing the old baseline are retained as design +history rather than current limitation claims. -## 1. Current color, brush, and gradient system +## 1. Pre-stage color, brush, and gradient system ModernFormsNext already has a public `ModernFormsNext.Drawing.Brush` hierarchy. It contains `SolidColorBrush`, `GradientBrush`, `LinearGradientBrush`, `RadialGradientBrush`, @@ -35,7 +36,7 @@ matching C# object initializers. - Designer structured values and `CSharpLiteralWriter` are the existing serialization/code generation contract. -## 3. Problems in the current architecture +## 3. Problems identified in the pre-stage architecture 1. Brushes and stops are mutable but publish no change notification. Mutating a shared brush does not invalidate controls that use it. @@ -101,24 +102,23 @@ Resource dictionaries continue to notify only when the resource entry changes. I changes flow through the brush's own notification contract; no global resource broadcast is added. Mutations have the same UI-thread affinity as current resource updates and control setters. -## 8. Future ThemeManager impact +## 8. Delivered ThemeManager impact -ThemeManager can publish shared brushes under stable dynamic-resource keys. Runtime changes can -update a brush in place for targeted invalidation, while atomic theme replacement can replace the -resource value. Opacity, spread mode, stable stop ordering, and neutral values form a future JSON -schema without embedding Skia names. This stage documents that schema direction but does not add a -partial theme serializer. +ThemeManager publishes cloned brushes under stable dynamic-resource keys. Runtime changes can update +a brush in place for targeted invalidation, while atomic theme replacement replaces the resource +value. Opacity, spread mode, stable stop ordering, and neutral values are represented by the strict, +renderer-neutral [theme JSON schema](../theme-json-schema.md). Advanced color interpolation is intentionally not exposed until ThemeManager can define and validate color spaces consistently. The initial renderer preserves Skia's current sRGB-compatible color behavior. -## 9. Future Shape impact +## 9. Delivered Shape impact -Shapes will be able to reuse `Brush` for fills and, later, stroke paint without depending on a -control. Relative gradient coordinates are resolved against the geometry's paint bounds by the -same adapter. The model does not reference `Control`, Windows, Android, or the Designer. Stroke -caps, joins, dashes, and geometry are outside this stage. +Shapes reuse `Brush` for fills and strokes. Relative gradient coordinates are resolved against the +geometry's paint bounds by the same adapter. Geometry stays platform-neutral; the shared Skia +renderer supports stroke caps, joins, dashes, transforms, and retained paths without a second paint +hierarchy. ## 10. Target architecture @@ -175,7 +175,7 @@ creation itself dominates and cannot be eliminated safely for bounds-dependent g bounded cache policy. Text brushes require a temporary alpha layer as before. Animated brush properties rebuild shaders -and should be driven by the future UI-thread animation scheduler, not worker-thread callbacks. +and are driven by the shared UI-thread `AnimationScheduler`, not worker-thread callbacks. ## 14. Native memory and shader cache risks @@ -207,5 +207,5 @@ This stage is complete when: resource without changing the default template application; - shared, Windows, Android, Designer, VSIX, samples, tests, and local packages pass release validation; and -- the roadmap marks only paint/gradient hardening complete and recommends UI animation scheduler - hardening next. +- the roadmap and current documentation distinguish the completed foundation from remaining mapping, + color-space, batching, and device-validation work. diff --git a/docs/architecture/ui-animation-scheduler.md b/docs/architecture/ui-animation-scheduler.md index 819e36e..60f2b68 100644 --- a/docs/architecture/ui-animation-scheduler.md +++ b/docs/architecture/ui-animation-scheduler.md @@ -9,6 +9,10 @@ diagnostics. It deliberately excludes ThemeManager, Shape controls, navigation t designer-authored transition system. The animated-layout foundation now consumes this scheduler as described in [Animated layout architecture](animated-layout.md); it does not add another ticker. +Implementation update (2026-08-18): ThemeManager, Shape controls, composable definitions, +Designer-authored safe transition metadata, Android Choreographer pacing, and Android live +animation-scale observation now consume this seam. Navigation transitions remain future work. + ## Pre-change state Before this stage, ModernFormsNext had a small animation surface under @@ -189,7 +193,7 @@ The scheduler does not invalidate globally. Existing property setters retain res Cancellation performs no property write, so it creates no extra repaint. Layout and render invalidation remain separate concerns. -## Paint/Brush, resources, and future themes +## Paint/Brush, resources, and themes The owner of an explicit in-place brush animation is the brush itself. Its synchronous `Changed` event continues through the weak, reference-counted subscriptions introduced with dynamic @@ -205,12 +209,13 @@ data. Theme transitions construct compatible local animation plans after resourc publish the current presentation brush during a rapid replacement, and restore the exact target reference at completion. -## Future Shape and navigation work +## Shape and future navigation work -Shape properties can use the same typed interpolators and owner keys. Navigation surfaces can use -multiple keys for opacity and transform without owning timers. Neither feature is implemented in -this stage. Animated layout uses a focused presentation-geometry helper: layout computes the target -once, while scheduler frames request composition invalidation without rerunning layout. +Shape controls use the shared paint/geometry/rendering architecture and can consume the same typed +interpolators and owner keys. Navigation surfaces can later use multiple keys for opacity and +transform without owning timers. Animated layout uses a focused presentation-geometry helper: +layout computes the target once, while scheduler frames request composition invalidation without +rerunning layout. ## Reduced motion diff --git a/docs/audits/1.10.0-documentation-and-limitations-audit.md b/docs/audits/1.10.0-documentation-and-limitations-audit.md new file mode 100644 index 0000000..b922f51 --- /dev/null +++ b/docs/audits/1.10.0-documentation-and-limitations-audit.md @@ -0,0 +1,316 @@ +# ModernFormsNext 1.10.0 documentation and limitations audit + +Audit date: 2026-08-18 + +Baseline: `v1.10.0` / `3d3c05ed17de18267a65050d6b1384da928c3e9d` + +Scope: documentation and metadata only; no functional implementation, issue creation, roadmap +milestone mutation, version change, publication, or device claim. + +## Method + +The audit compared repository documentation with the implementation, focused automated tests, and +current GitHub issue state. It distinguished implemented behavior, deterministic test coverage, +recorded manual evidence, and unperformed emulator/physical-device/profiler checks. Closed issues +were not treated as an active backlog merely because an older document still referenced them. + +The scan covered limitation/future/preview/experimental/fallback/manual-validation phrases and code +markers (`TODO`, `FIXME`, `HACK`, `WORKAROUND`). GitHub issues were searched before proposing any +new backlog item. No issue was created. + +## Documentation inventory + +All 64 tracked Markdown files were inspected: + +- repository: `AGENTS.md`, `README.md`, `CHANGELOG.md`, `RELEASING.md`, `license.md`, and + `third-party-licenses.md`; +- release-site shell: `docs-site/index.md` and `docs-site/api-index.md`; +- package/backend/extension guides: `ModernFormsNext.Templates/README.md`, + `ModernFormsNext.VisualStudioExtension/README.md`, and + `ModernFormsNext.WindowKit.Backend.Android/README.md`; +- release/current docs: `docs/1.10.0-release-notes.md`, `docs/1.9.0-release-notes.md`, + `docs/1.9.0-theme-system.md`, `docs/getting-started.md`, `docs/installation.md`, + `docs/samples.md`, and `docs/releasing/versioned-documentation-artifacts.md`; +- platform docs: `docs/platforms/android.md`, `docs/android-backend.md`, + `docs/android-development.md`, `docs/android-adb.md`, `docs/android-permissions.md`, + `docs/cross-platform-sample.md`, `docs/platform-specific-code.md`, and + `docs/platform-specific-features.md`; +- Designer/docs model: `docs/designer-architecture.md`, `docs/designer-animation-effects.md`, + `docs/user-controls.md`, `docs/shapes-and-vector-geometry.md`, + `docs/migrations/1.8.0-to-1.9.0.md`, and `docs/migrations/1.9.0-to-1.10.0.md`; +- animation/theme/paint: `docs/animations.md`, `docs/composable-animations.md`, + `docs/dynamic-resources.md`, `docs/themes.md`, `docs/theme-json-schema.md`, + `docs/paint-and-gradients.md`, and `docs/styling.md`; +- architecture: `docs/architecture.md`, `docs/architecture/android-animation-runtime.md`, + `docs/architecture/animated-layout.md`, `docs/architecture/brush-interpolation.md`, + `docs/architecture/layout-aware-visual-state-metrics.md`, + `docs/architecture/paint-and-gradients.md`, `docs/architecture/ui-animation-scheduler.md`, and all + nine files under `docs/architecture/decisions/`; +- controls/content: `docs/data-binding.md`, `docs/markdown.md`, `docs/markdown-editor.md`, + `docs/richtextbox.md`, `docs/tooltips.md`; +- roadmap: `docs/roadmap/ModernFormsNext-Framework-Roadmap.md`; +- samples: `samples/ModernFormsNext.Android.SmokeTest/README.md`, + `samples/ModernFormsNext.CrossPlatform.Sample/README.md`, and + `samples/ModernFormsNext.CrossPlatform.Sample/Assets/README.md`. + +The audit also inspected `docs-site/toc.yml`, the three tracked workflow/configuration YAML files, +23 tracked PowerShell scripts/modules, project metadata, the release workflow, and subsystem code +and tests needed to verify claims. + +Ignored local `docs/docfx.json`, `docs/index.md`, `docs/toc.yml`, `docs/api/`, and `docs/_site/` are +not release inputs and have no tracked Git history. They were preserved untouched. The canonical +release site is built from `docs-site/`, tracked repository content, Release assemblies/XML, and the +shared release-documentation scripts. + +## Active limitation classification + +The central index records 39 active limitations: + +| Type | Count | +| --- | ---: | +| Bug | 0 | +| Missing feature | 14 | +| Known design limitation | 5 | +| Platform limitation | 6 | +| Validation gap | 4 | +| Performance limitation | 2 | +| Tooling limitation | 3 | +| Compatibility limitation | 5 | +| Intentional out-of-scope behavior | 0 | +| **Total active** | **39** | + +No active limitation met the audit's Critical threshold. High-impact gaps are concentrated in the +Designer transaction/editing model and Android application, platform-service, accessibility, IME, +lifecycle, and release-quality coverage. See the [central index](../known-limitations.md). + +## Experimental and public API status + +The shared `ModernFormsNext` APIs are not blanket-marked experimental merely because some newer +subsystems are evolving. Windows remains the supported primary runtime. The Android backend and its +shared-control host are explicitly experimental and not production-supported; that platform status +does not make the same shared controls experimental on Windows. The VSIX/Designer is a shipped +code-first tool with documented editing and isolation boundaries, not a license to infer missing +runtime behavior. Existing compatibility members marked `Obsolete` remain separate API migration +concerns and were not reclassified as product limitations. + +## Already tracked limitations + +- Designer editing: [#33](https://github.com/ProGraMajster/ModernFormsNext/issues/33) through + [#42](https://github.com/ProGraMajster/ModernFormsNext/issues/42), with the current partial + capabilities stated explicitly instead of describing each area as wholly absent. +- Hot reload and framework compatibility: [#43](https://github.com/ProGraMajster/ModernFormsNext/issues/43) + and [#44](https://github.com/ProGraMajster/ModernFormsNext/issues/44). +- System theme integration and GPU rendering: [#45](https://github.com/ProGraMajster/ModernFormsNext/issues/45) + and [#46](https://github.com/ProGraMajster/ModernFormsNext/issues/46). +- Virtualization, commands, data transfer, diagnostics, accessibility, native hosting, developer + tools, IME, lifecycle, and test hosting: [#55](https://github.com/ProGraMajster/ModernFormsNext/issues/55) + through [#64](https://github.com/ProGraMajster/ModernFormsNext/issues/64). +- Navigation/localization and dependent future systems remain covered by [#12](https://github.com/ProGraMajster/ModernFormsNext/issues/12) + through [#16](https://github.com/ProGraMajster/ModernFormsNext/issues/16) and + [#20](https://github.com/ProGraMajster/ModernFormsNext/issues/20)–[#21](https://github.com/ProGraMajster/ModernFormsNext/issues/21). + +## Issues created from missing coverage + +The audit originally recorded these as proposals because no open issue covered each complete +problem. The post-audit tracking synchronization created the linked issues and assigned complete +ModernFormsNext Roadmap metadata. + +### P1: Establish an Android device, performance, and reliability matrix — [#69](https://github.com/ProGraMajster/ModernFormsNext/issues/69) + +- **Problem:** issue #29 delivered the Choreographer/lifecycle/multi-touch runtime, but the recorded + evidence does not cover a physical device, 90/120 Hz, repeated rotation/recreation, long + background intervals, GPU behavior, broad IME/accessibility combinations, or profiler leak runs. +- **Expected behavior:** define repeatable emulator and physical-device scenarios, retain device/API/ + refresh-rate evidence, set performance and idle/leak acceptance criteria, and record results + separately from automated builds. +- **Rationale:** this closes a release-quality evidence gap without confusing it with a functional + scheduler implementation. +- **Area:** Android / quality; **priority:** High; **suggested target:** 1.11.0. +- **Dependencies:** existing cross-platform sample and diagnostics; coordinate with #58, #59, #62, + and #63 where their implementations become available. + +### P2: Complete safe custom-control discovery and metadata — [#68](https://github.com/ProGraMajster/ModernFormsNext/issues/68) + +- **Problem:** UserControl root design and data-only nested preview are implemented, but toolbox + discovery is source-only, type discovery refreshes on reopen, referenced binary controls remain + code-first, and project UserControl custom properties/events do not have a complete safe source + metadata contract. +- **Expected behavior:** define explicit descriptors for project and referenced controls, safe + property/event serialization, diagnostics, incremental refresh, and fallback behavior without + loading arbitrary application code into the Designer. +- **Rationale:** issue #32 delivered the safe core workflow; this proposal tracks the remaining + ecosystem surface without weakening the safety boundary in #40. +- **Area:** Designer / UserControl; **priority:** High; **suggested target:** 1.11.0 or 1.12.0. +- **Dependencies:** #33 for transactional edits, #37 for event workflow, #39 for inheritance, and + #40 for process/isolation policy. + +### P3: Extend vector geometry and Path Designer tooling — [#70](https://github.com/ProGraMajster/ModernFormsNext/issues/70) + +- **Problem:** the 1.10.0 geometry model intentionally omits arc segments, groups/boolean operations, + SVG import/core path text, general Stretch, generic Control clipping, and a graphical Bezier + editor. +- **Expected behavior:** approve an additive platform-neutral geometry contract, extend the single + Skia conversion/cache path, preserve hit-test/render parity, and add deterministic + serialization/generation/reverse-parser and Designer tests. +- **Rationale:** issue #11 is correctly closed for the initial vector foundation; the omitted + operations are a coherent follow-up rather than evidence that #11 is incomplete. +- **Area:** Shape/Geometry / Designer; **priority:** Medium; **suggested target:** 1.12.0. +- **Dependencies:** existing Shape/Geometry and Brush systems; consider later chart/diagram needs in + #16 without coupling the APIs prematurely. + +### P4: Stabilize the Visual Studio Designer host contract — [#71](https://github.com/ProGraMajster/ModernFormsNext/issues/71) + +- **Problem:** the VSIX still uses reflection to obtain a runtime HWND and does not integrate with + built-in View Designer/Shift+F7 routing or automate dependent-file metadata for legacy projects. +- **Expected behavior:** expose a supported embeddable host/window contract, remove reflection, + preserve the thin-host architecture, and add VSIX validation for routing and project-item + relationships. +- **Rationale:** this is a tooling boundary independent of missing Designer editing features. +- **Area:** Visual Studio integration / WindowKit; **priority:** Medium; **suggested target:** 1.11.0. +- **Dependencies:** no dependency on new Designer algorithms; coordinate with #40 if isolation moves + out of process. + +### P5: Complete the Android application and windowing host — [#72](https://github.com/ProGraMajster/ModernFormsNext/issues/72) + +- **Problem:** Android can attach one shared control tree to `AndroidSkiaHostView`, but it has no + general `Application.Run(Form)`, `IWindowingPlatform`/`IWindowImpl`, popup/owned-window model, or + multiple framework windows. +- **Expected behavior:** define a platform-neutral application/window host mapping that reuses the + existing control tree, dispatcher, lifecycle, frame source, and surface adapter without creating + an Android-only UI framework. +- **Rationale:** this is the primary architectural boundary between the experimental vertical slice + and a general Android application backend. +- **Area:** Android / WindowKit; **priority:** High; **suggested target:** Future (not automatically + 1.11.0). +- **Dependencies:** #63 lifecycle/activation, #59 accessibility, #60 native hosting for dependent + services, and #69 validation. + +## Post-audit GitHub tracking synchronization + +The synchronization checked open issues and relevant closed 1.10.0 issues before creating new +work. All 39 active limitations now link to at least one active issue. The mapping reuses 23 unique +open issues, extends seven existing issue bodies with audit-specific acceptance criteria, and adds +22 issues. No active limitation is left as a no-issue exception. + +In addition to the five original proposals above, the synchronization created: + +- animation follow-ups [#73](https://github.com/ProGraMajster/ModernFormsNext/issues/73) through + [#76](https://github.com/ProGraMajster/ModernFormsNext/issues/76); +- Android system appearance and shared theme/rendering work + [#77](https://github.com/ProGraMajster/ModernFormsNext/issues/77)–[#78](https://github.com/ProGraMajster/ModernFormsNext/issues/78); +- Android service completeness and Linux/macOS backend work + [#79](https://github.com/ProGraMajster/ModernFormsNext/issues/79)–[#80](https://github.com/ProGraMajster/ModernFormsNext/issues/80); +- safe reverse synchronization, release smoke automation, validation isolation, dynamic-resource + compatibility, BindingNavigator, RichTextBox, Markdown editing, ToolTip behavior, and RTL layout + [#81](https://github.com/ProGraMajster/ModernFormsNext/issues/81) through + [#89](https://github.com/ProGraMajster/ModernFormsNext/issues/89). + +The synchronization also added all 53 open issues to the ModernFormsNext Roadmap and verified that +each has non-empty Status, Target version, Area, Priority, and Effort fields. Permanent safety +boundaries remain explicit inside tracked issues: arbitrary application-code execution during +Designer metadata discovery/reverse synchronization and WinForms designer-serialization hooks are +not planned framework behavior. + +## Documentation-only problems corrected + +- Removed current-state claims that animated layout, padding/border visual-state interpolation, + Shape/Geometry, source-described custom effects, different-count gradient interpolation, and + transition editors were still future work. +- Corrected Android animation policy documentation: the backend reads and observes + `ANIMATOR_DURATION_SCALE` with a lifecycle/subscription-aware `ContentObserver`; it does not read + `TRANSITION_ANIMATION_SCALE` as a second policy source. +- Distinguished Android animation policy from the still-missing Android system light/dark + ThemeManager provider. +- Reconciled the roadmap's 2026-08-01 snapshot with the implemented 1.10.0 Shape, animated-layout, + visual-state, Brush, UserControl, and Android animation work. +- Replaced undifferentiated Designer TODO language with current capability statements and issue + links. +- Added the central limitations entry to README and the versioned DocFX TOC. + +## Historical or obsolete limitations + +The following statements are obsolete for 1.10.0 and were removed or explicitly marked historical: + +- no animated-layout subsystem (#25); +- layout-aware state metrics always switch discretely (#26); +- different non-empty gradient-stop counts cannot interpolate (#27); +- Designer effects are limited to built-in ripple/press descriptions (#28); +- Android has only foreground refresh and no live animator-scale observer (#29); +- Shape/Geometry is future work (#11); +- Designer container Padding differs from runtime (#31); +- Form-only Designer roots / no UserControl design (#32); +- no Designer transition editor or deterministic transition serialization; +- UserControl `.mfdesign` preview changes require reopening (document content reloads on the next + preview request; only source type discovery currently requires reopen). + +The 1.9.0 changelog and release notes keep their historical limitations because they describe that +release, not current master. + +## TODO, FIXME, HACK, and WORKAROUND audit + +The tracked non-Markdown code/configuration scan matched 34 lines: 32 `TODO` occurrences, 2 `HACK` +occurrences, no `FIXME` or `WORKAROUND` occurrence, and one `TEMP` occurrence. The `TEMP` match is +the normal Visual Studio installer-log use of `$env:TEMP`, not technical debt; `TEMPORARY` has no +tracked non-Markdown match. No comment was deleted merely for cleanup. + +The markers fall into these groups: + +- **Potential user-visible follow-up requiring a focused reproduction before issue creation:** + border scaling (`Control.cs`), non-client Form sizing (`Form.cs`), Flow/Table RTL and flow + auto-scroll position, ListBox shift selection and selected-index maintenance, TextBox horizontal + scrolling and whole-word search, TreeView keyboard checkbox toggle, TableLayout custom-cell paint, + and popup scaling override. +- **Performance/polish notes:** avoid redundant FormTitleBar invalidation, cache NavigationPane + measurement work, and move Ribbon work out of paint. These are not treated as confirmed bugs. +- **Architecture/consolidation notes:** unify `ScrollControl` with `ScrollableControl`, settle + placeholder Control/Layout/WindowBase decisions, and review generated-layout leftovers. +- **Upstream/interop compatibility notes:** the MicroCom fast-up-to-date timestamp workaround, + runtime storage-provider TODO, pixel-format color-type note, and inherited Windows/Avalonia + implementation comments. These need upstream-context review before conversion into issues. +- **Intentional generated source:** `DesignerFileService` emits `// TODO: Add event handling logic.` + inside a newly generated user handler. That is user-facing scaffold content, not framework debt. + +This audit does not create speculative issues from ambiguous comments. The concrete active +limitations are documented; marker-only candidates should be reproduced and split into narrow +issues if confirmed. + +## Potential release-quality concerns + +- Android remains experimental and lacks the evidence matrix tracked by + [#69](https://github.com/ProGraMajster/ModernFormsNext/issues/69); no new device result is claimed. +- Designer safety uses data-only preview rather than arbitrary user-code execution; fidelity claims + must stay within that contract. +- The versioned documentation pipeline is exact-tag/SHA-bound and validated, but browser rendering, + interactive Visual Studio checks, Marketplace publication, and device checks remain manual; the + automatable follow-up and explicit handoffs are tracked by + [#82](https://github.com/ProGraMajster/ModernFormsNext/issues/82). +- Repository-wide version-consistency tests can be contaminated by nested worktrees under + `artifacts/`; clean exact-SHA worktree validation remains the reliable release check and the + isolation work is tracked by [#83](https://github.com/ProGraMajster/ModernFormsNext/issues/83). + +## Validation record + +- `dotnet restore .\ModernFormsNext.slnx --disable-parallel /p:UseSharedCompilation=false`: + succeeded. +- full Debug solution build, sequential with shared compilation disabled and Windows targeting + enabled: succeeded with 0 warnings and 0 errors, including Android targets and Debug VSIX + validation. +- full Release solution build with the same safe sequencing: succeeded with 0 warnings and 0 + errors, including Android targets and Release VSIX validation. +- automated tests: all 1,112 tests were covered. The first in-tree run passed 1,111 and reproduced + the known nested-`artifacts` contamination in + `EveryPackableProjectUsesTheCentralPackageVersion`; the other 1,111 passed together, and that one + repository-enumeration test passed separately in a clean detached worktree at the unchanged code + baseline. No product test failed. +- pinned DocFX 2.78.5 metadata/build with warnings-as-errors: succeeded with 0 warnings and 0 + errors; DocFX applied 890 models and indexed 881 HTML files. The generated site contains + `content/docs/known-limitations.html` and the central page is present in the tracked TOC. +- release-documentation tests: 32/32 assertions passed. +- all four local versioned documentation archives passed the official metadata, path-safety, + content, offline-asset, and internal-link validator. +- final staged `git diff --check`: clean. + +No interactive Visual Studio/ControlGallery/browser smoke or Android emulator/physical-device test +was performed because the audit diff changes documentation only. At the time of the original audit +run, no release, package publication, issue, PR, or remote branch was created; the later GitHub +tracking synchronization is recorded above. diff --git a/docs/composable-animations.md b/docs/composable-animations.md index c2a9a0f..bf55ba1 100644 --- a/docs/composable-animations.md +++ b/docs/composable-animations.md @@ -1,7 +1,8 @@ -# Composable animations and interaction effects in ModernFormsNext 1.9.0 +# Composable animations and interaction effects -This document records the composable animation and interaction-effect scope included in -ModernFormsNext 1.9.0. It does not change the release status or authorize publication. +This document describes the composable animation and interaction-effect scope introduced in +ModernFormsNext 1.9.0 and extended in 1.10.0. It does not change release status or authorize +publication. ## Highlights @@ -20,7 +21,8 @@ ModernFormsNext 1.9.0. It does not change the release status or authorize public - Ripple overflow is explicit and deterministic: remove oldest, remove newest, ignore the new wave, or replace all active waves. The existing eviction property remains source-compatible. - Windows observes the native client-area animation preference without polling. Experimental - Android reads the global animator and transition scales on startup/foreground entry. + Android reads the global animator-duration scale and observes it while the host is active and + animation policy has subscribers. - The Designer Property Grid has detached, scheduler-free editors for ordered interaction effects, layout transitions, and visual-state transitions with stable `.mfdesign` and generated-code round trips. Explicitly attributed project effects are discovered from source without loading @@ -48,12 +50,13 @@ auto-reverse, custom animation, and custom interpolation. Windows remains the primary runtime target. Android touch integration is experimental and requires device/emulator validation for frame pacing, background/foreground transitions, multi-touch -rendering, platform setting changes, and orientation changes. Android refreshes platform animation -scales on foreground entry rather than maintaining a live settings observer. Visual-state layout -metrics switch immediately rather than interpolate and incompatible Brush structures switch +rendering, platform setting changes, and orientation changes. Android maintains a lifecycle- and +subscription-aware `ContentObserver` for the animator-duration scale. Visual-state padding and +border widths interpolate; other layout-aware metrics and incompatible Brush structures switch discretely. Designer documents serialize only built-in easing identifiers; custom delegate easing and general `AnimationDefinition` activation remain code-first. The Designer still has no global -undo/redo stack and does not execute or preview project effect code. +undo/redo stack and does not execute or preview project effect code. See the +[central known-limitations index](known-limitations.md) for the full current matrix. See [UI animations](animations.md) and the [composable-animation ADR](architecture/decisions/ADR-Composable-Animations-And-Interaction-Effects.md), diff --git a/docs/designer-animation-effects.md b/docs/designer-animation-effects.md index b66529a..29f083b 100644 --- a/docs/designer-animation-effects.md +++ b/docs/designer-animation-effects.md @@ -108,7 +108,8 @@ included in the VSIX; no application assembly is added to the extension process. drag, resize, and custom-code isolation. - Designer-wide undo/redo does not exist yet. Editors use atomic OK/Cancel semantics so a future transaction service can wrap one committed definition change. -- Android runtime animation integration and device validation remain part of issue #29. +- Android runtime animation integration is implemented. Broad emulator and physical-device frame, + lifecycle, setting-change, and rendering validation remains outstanding. ## Manual Visual Studio smoke test @@ -121,4 +122,5 @@ effect can be checked with the explicit attributes shown above; its throwing con run while the designer or editor is open. See [Designer architecture](designer-architecture.md), [Animations](animations.md), and -[Composable animations](composable-animations.md). +[Composable animations](composable-animations.md). The +[central known-limitations index](known-limitations.md) tracks the remaining boundaries. diff --git a/docs/designer-architecture.md b/docs/designer-architecture.md index a9c06c4..ba7837d 100644 --- a/docs/designer-architecture.md +++ b/docs/designer-architecture.md @@ -63,7 +63,7 @@ document outline, layout engine, hit testing, file service, or code-generation s ### ModernFormsNext.VisualStudioExtension -`ModernFormsNext.VisualStudioExtension` is the future Visual Studio integration layer. The +`ModernFormsNext.VisualStudioExtension` is the current Visual Studio integration layer. The user-facing entry point is the primary form/control code file, such as `MainForm.cs`, not the metadata file. The extension detects designable ModernFormsNext C# files, exposes a safe `View ModernFormsNext Designer` command, opens the companion `.mfdesign` document through a @@ -73,8 +73,9 @@ The VSIX must not globally replace the C# editor for every `.cs` file. Only file recognized as ModernFormsNext form/control files, have explicit ModernFormsNext project design metadata, or have a valid companion `.mfdesign` file should expose the designer command. -The VSIX also contributes **ModernFormsNext Form** and **ModernFormsNext UserControl** C# item templates. Each item template creates -the user-authored `.cs` file, the generated `.Designer.cs` file, and the `.mfdesign` companion +The VSIX also contributes **ModernFormsNext Form** and **ModernFormsNext UserControl** C# item +templates. Each item template creates the user-authored `.cs` file, the generated `.Designer.cs` +file, and the `.mfdesign` companion document in one operation. It avoids `SubType=Form` for the same reason as the project template: that value belongs to the classic Windows Forms designer. @@ -277,7 +278,33 @@ user-facing project item. A host should use reverse sync only when a generated ` file appears newer or manually edited, and it should report parser diagnostics before overwriting the `.mfdesign` document. -## Visual Studio TODO +## Current Designer limitations + +- There is no Designer-wide undo/redo transaction history ([#33](https://github.com/ProGraMajster/ModernFormsNext/issues/33)), + multi-selection/group editing ([#35](https://github.com/ProGraMajster/ModernFormsNext/issues/35)), + or complete smart-guide/equal-spacing/baseline workflow ([#36](https://github.com/ProGraMajster/ModernFormsNext/issues/36)). +- Copy, paste, and duplicate exist for an in-session single-control workflow. Cut, a system + clipboard contract, complete cross-document behavior, and transaction integration remain in + [#34](https://github.com/ProGraMajster/ModernFormsNext/issues/34). +- The Events view persists bindings and can generate a handler method. Default-event double-click, + compatible-method selection, robust navigation, and rename diagnostics remain in + [#37](https://github.com/ProGraMajster/ModernFormsNext/issues/37). +- Project resources and inherited-control design remain incomplete + ([#38](https://github.com/ProGraMajster/ModernFormsNext/issues/38), + [#39](https://github.com/ProGraMajster/ModernFormsNext/issues/39)). +- Arbitrary project code is not executed for preview. Source-described UserControls use the safe + data-only model above; broader isolation is tracked by + [#40](https://github.com/ProGraMajster/ModernFormsNext/issues/40). +- Auto-save exists, but crash recovery and external-change conflict handling remain in + [#41](https://github.com/ProGraMajster/ModernFormsNext/issues/41). Focused parity tests exist for + delivered subsystems, but a comprehensive runtime/Designer parity suite remains in + [#42](https://github.com/ProGraMajster/ModernFormsNext/issues/42). +- Reverse parsing is deliberately conservative: unsupported arbitrary expressions produce + diagnostics and are never evaluated or merged automatically. + +See [Known limitations](known-limitations.md) for the central classification and priorities. + +## Current Visual Studio integration boundaries The Visual Studio extension hosts the shared shell through a small HWND adapter. The adapter creates a lightweight ModernFormsNext form, places `ModernFormsDesignerShell` inside it, and @@ -285,7 +312,7 @@ parents that HWND into the Visual Studio editor pane. This keeps the designer UI `ModernFormsNext.Designer` instead of copying property grid, surface, toolbox, or outline code into the VSIX. -The Visual Studio extension still needs: +The remaining integration boundaries are: - hardening of the HWND adapter into a supported public hosting API in the framework or a dedicated embeddable WindowKit surface, so the VSIX no longer needs reflection to obtain the diff --git a/docs/known-limitations.md b/docs/known-limitations.md new file mode 100644 index 0000000..c3b4a8b --- /dev/null +++ b/docs/known-limitations.md @@ -0,0 +1,91 @@ +# Known limitations + +This page is the central index of current ModernFormsNext 1.10.0 limitations. It is intentionally +an index: follow the **Details** links for behavior, workarounds, and validation evidence. The +baseline is tag `v1.10.0` / commit `3d3c05ed17de18267a65050d6b1384da928c3e9d`, re-audited on +2026-08-18 against the code, automated tests, and GitHub issue state. + +Windows is the primary supported runtime. Android is an experimental shared-control vertical +slice. A successful build or deterministic test does not imply emulator, physical-device, GPU, +accessibility, IME-vendor, or leak-profile validation. + +## Classification + +- **Type** distinguishes bugs, missing features, design/platform/validation/performance/tooling/ + compatibility limitations, intentional scope, and obsolete history. +- **Severity** describes product impact: Critical, High, Medium, or Low. It is not a promised + delivery order. +- **Tracked** links an open issue. Some rows link more than one issue when independent subsystems + own different parts of the limitation. **Intentional** identifies a permanent safety or + compatibility sub-boundary; any improvable part of the same row remains linked to active work. + +The post-audit GitHub synchronization verified that every active row below links to at least one +open issue with complete ModernFormsNext Roadmap metadata. + +No active Critical limitation or confirmed current bug was found in the audited 1.10.0 areas. +Closed issues [#2](https://github.com/ProGraMajster/ModernFormsNext/issues/2), +[#11](https://github.com/ProGraMajster/ModernFormsNext/issues/11), +[#25](https://github.com/ProGraMajster/ModernFormsNext/issues/25)–[#29](https://github.com/ProGraMajster/ModernFormsNext/issues/29), +[#31](https://github.com/ProGraMajster/ModernFormsNext/issues/31), and +[#32](https://github.com/ProGraMajster/ModernFormsNext/issues/32) are treated as completed work, +not active limitations. + +## Current limitations index + +| ID | Area | Limitation | Type | Severity | Status / issue | Details | +| --- | --- | --- | --- | --- | --- | --- | +| DES-01 | Designer | No designer-wide undo/redo transaction history. | Missing feature | High | [Tracked #33](https://github.com/ProGraMajster/ModernFormsNext/issues/33) | [Designer architecture](designer-architecture.md#current-designer-limitations) | +| DES-02 | Designer | Clipboard editing is an in-session, single-control copy/paste/duplicate path; cut, a system clipboard contract, complete cross-document behavior, and transaction integration are absent. | Missing feature | High | [Tracked #34](https://github.com/ProGraMajster/ModernFormsNext/issues/34) | [Installation](installation.md#designer-keyboard-shortcuts) | +| DES-03 | Designer | No multi-selection, marquee selection, or group editing. | Missing feature | High | [Tracked #35](https://github.com/ProGraMajster/ModernFormsNext/issues/35) | [Designer architecture](designer-architecture.md#current-designer-limitations) | +| DES-04 | Designer | Existing grid/snapping math is not a complete smart-guide, equal-spacing, baseline, or configurable-grid workflow. | Missing feature | Medium | [Tracked #36](https://github.com/ProGraMajster/ModernFormsNext/issues/36) | [Designer architecture](designer-architecture.md#current-designer-limitations) | +| DES-05 | Designer | The Events view can persist bindings and generate a method, but default-event double-click, compatible-method selection, robust code navigation, and rename diagnostics are incomplete. | Missing feature | Medium | [Tracked #37](https://github.com/ProGraMajster/ModernFormsNext/issues/37) | [Designer architecture](designer-architecture.md#current-designer-limitations) | +| DES-06 | Designer | No project resource browser or stable asset-management workflow. | Missing feature | Medium | [Tracked #38](https://github.com/ProGraMajster/ModernFormsNext/issues/38) | [Designer architecture](designer-architecture.md#current-designer-limitations) | +| DES-07 | Designer | Visual editing of inherited custom Forms and UserControls is not implemented. | Missing feature | High | [Tracked #39](https://github.com/ProGraMajster/ModernFormsNext/issues/39) | [UserControls](user-controls.md#current-design-time-boundaries) | +| DES-08 | Designer | Arbitrary application code is not executed for preview. Project UserControls use data-only projections and unsupported executable controls use safe placeholders. | Known design limitation | High | Intentional safety boundary; broader isolation [tracked #40](https://github.com/ProGraMajster/ModernFormsNext/issues/40) | [Safe preview](designer-architecture.md#safe-embedded-usercontrol-preview) | +| DES-09 | Designer | Auto-save exists, but crash recovery and external-change conflict handling do not. | Missing feature | High | [Tracked #41](https://github.com/ProGraMajster/ModernFormsNext/issues/41) | [Designer architecture](designer-architecture.md#current-designer-limitations) | +| DES-10 | Designer/layout | Padding, order, DPI, Shape, animation, and UserControl paths have focused tests, but there is no comprehensive Designer/runtime parity suite. | Validation gap | High | [Tracked #42](https://github.com/ProGraMajster/ModernFormsNext/issues/42) | [Designer architecture](designer-architecture.md#current-designer-limitations) | +| DES-11 | Visual Studio integration | The VSIX HWND adapter still uses reflection for the runtime handle and lacks built-in View Designer/Shift+F7 and dependent-file automation. | Tooling limitation | Medium | [Tracked #71](https://github.com/ProGraMajster/ModernFormsNext/issues/71) | [Visual Studio integration](designer-architecture.md#current-visual-studio-integration-boundaries) | +| DES-12 | Custom controls | Toolbox discovery is source-only and refreshed by reopening the Designer; binary-only controls and source-discovered custom properties/events are not a complete metadata surface. | Tooling limitation | High | [Tracked #68](https://github.com/ProGraMajster/ModernFormsNext/issues/68) | [UserControls](user-controls.md#current-design-time-boundaries) | +| GEO-01 | Shape/Geometry | No arc segment, geometry group/boolean operations, SVG import/core path string, general Stretch contract, generic Control geometry clip, or graphical Bezier editor. | Missing feature | Medium | [Tracked #70](https://github.com/ProGraMajster/ModernFormsNext/issues/70) | [Shapes](shapes-and-vector-geometry.md#current-limitations) | +| GEO-02 | Shape/Geometry | Android shares the renderer and builds successfully, but physical-device visual, touch-hit, GPU, and cache profiling have not been recorded. | Validation gap | Medium | [Tracked #69](https://github.com/ProGraMajster/ModernFormsNext/issues/69) | [Shapes](shapes-and-vector-geometry.md#current-limitations) | +| ANI-01 | LayoutTransition | Transitions are per-control, zero-area source/target rectangles snap, and normal ancestor clipping remains authoritative. | Known design limitation | Medium | Follow-up policy and extension work [tracked #73](https://github.com/ProGraMajster/ModernFormsNext/issues/73) | [Animated layout](architecture/animated-layout.md#current-limitations) | +| ANI-02 | VisualStateTransition | Layout-aware interpolation covers padding and border widths; other layout metrics remain discrete. | Known design limitation | Medium | Focused scope completed in [#26](https://github.com/ProGraMajster/ModernFormsNext/issues/26); additional metrics [tracked #74](https://github.com/ProGraMajster/ModernFormsNext/issues/74) | [Visual-state metrics](architecture/layout-aware-visual-state-metrics.md) | +| ANI-03 | InteractionEffects | Custom delegate easing and general `AnimationDefinition` activation remain code-first; the Designer does not run a live effect preview. | Known design limitation | Medium | Safe subset completed in [#28](https://github.com/ProGraMajster/ModernFormsNext/issues/28); follow-up [tracked #75](https://github.com/ProGraMajster/ModernFormsNext/issues/75) | [Designer effects](designer-animation-effects.md#current-limitations) | +| ANI-04 | Brush interpolation | Cross-kind gradient geometry, GlassBrush, NoBrush/null, empty-to-populated gradients, and custom/derived brushes switch discretely; color interpolation is sRGB. | Known design limitation | Medium | Supported matrix completed in [#27](https://github.com/ProGraMajster/ModernFormsNext/issues/27); follow-up [tracked #76](https://github.com/ProGraMajster/ModernFormsNext/issues/76) | [Brush matrix](architecture/brush-interpolation.md#deliberate-limitations) | +| THM-01 | ThemeManager | No automatic ThemeManager reapply for OS theme changes and no theme-file hot reload; Android has no system light/dark theme provider. | Missing feature | Medium | Windows/system [#45](https://github.com/ProGraMajster/ModernFormsNext/issues/45), file reload [#43](https://github.com/ProGraMajster/ModernFormsNext/issues/43), and Android provider [#77](https://github.com/ProGraMajster/ModernFormsNext/issues/77) | [Themes](themes.md#known-limitations) | +| THM-02 | ThemeManager | No shared shadow rendering contract; line height and letter spacing are not honored globally. | Missing feature | Low | [Tracked #78](https://github.com/ProGraMajster/ModernFormsNext/issues/78) | [Themes](themes.md#known-limitations) | +| AND-01 | Android application host | No general `Application.Run(Form)`, `IWindowingPlatform`, `IWindowImpl`, or multiple framework windows. | Platform limitation | High | [Tracked #72](https://github.com/ProGraMajster/ModernFormsNext/issues/72) | [Android status](platforms/android.md#important-limitations) | +| AND-02 | Android services | Native dialogs, clipboard, file/folder pickers, drag/drop, WebView/media/native views, notifications, sharing, and several other WindowKit services are incomplete. | Platform limitation | High | Umbrella [#79](https://github.com/ProGraMajster/ModernFormsNext/issues/79); related [#20](https://github.com/ProGraMajster/ModernFormsNext/issues/20), [#57](https://github.com/ProGraMajster/ModernFormsNext/issues/57), and [#60](https://github.com/ProGraMajster/ModernFormsNext/issues/60) | [Android status](platforms/android.md#important-limitations) | +| AND-03 | Android accessibility | Shared accessibility objects do not yet provide complete Android semantics, UI automation, or screen-reader integration. | Platform limitation | High | [Tracked #59](https://github.com/ProGraMajster/ModernFormsNext/issues/59) | [Android status](platforms/android.md#important-limitations) | +| AND-04 | Android input/IME | The current TextBox path supports composition and Unicode editing, but control, keyboard, language, vendor-IME, focus-transfer, and candidate/caret coverage is incomplete. | Platform limitation | High | [Tracked #62](https://github.com/ProGraMajster/ModernFormsNext/issues/62) | [Android status](platforms/android.md#important-limitations) | +| AND-05 | Android lifecycle | The sample handles activity recreation, but there is no complete shared application activation, state-restoration, safe-area/inset, or host-independent lifecycle policy. | Platform limitation | High | [Tracked #63](https://github.com/ProGraMajster/ModernFormsNext/issues/63) | [Android status](platforms/android.md#important-limitations) | +| AND-06 | Android release quality | No recorded physical-device, 90/120 Hz, GPU, long-run, broad IME/accessibility, or profiler leak matrix; AAB/store and general trim-safety support are not declared. | Validation gap | High | [Tracked #69](https://github.com/ProGraMajster/ModernFormsNext/issues/69) | [Android runtime validation](architecture/android-animation-runtime.md#manual-validation-checklist) | +| PLT-01 | Cross-platform backends | Windows is the only supported full runtime backend; Android is experimental and there are no supported Linux or macOS application backends. | Platform limitation | High | Android host [#72](https://github.com/ProGraMajster/ModernFormsNext/issues/72); Linux/macOS [#80](https://github.com/ProGraMajster/ModernFormsNext/issues/80) | [README status](../README.md#current-status) | +| REN-01 | Rendering/Skia | No explicit OpenGL/Vulkan/Metal/ANGLE backend selection or declared GPU-acceleration contract. | Performance limitation | Medium | [Tracked #46](https://github.com/ProGraMajster/ModernFormsNext/issues/46) | [Roadmap risks](roadmap/ModernFormsNext-Framework-Roadmap.md#known-cross-cutting-risks) | +| REN-02 | Rendering/Skia | Bounds-dependent shaders are created per rendering scope and the framework has no unified render/layout allocation budget or profiler overlay. | Performance limitation | Low | Diagnostics work [tracked #58](https://github.com/ProGraMajster/ModernFormsNext/issues/58) | [Paint and gradients](paint-and-gradients.md#current-limitations) | +| SER-01 | `.mfdesign` / code generation | `.mfdesign` is the source of truth. Reverse parsing accepts the generator's conservative subset and reports unsupported arbitrary expressions rather than evaluating or merging them. | Compatibility limitation | Medium | Safe fidelity improvements [tracked #81](https://github.com/ProGraMajster/ModernFormsNext/issues/81); arbitrary code execution remains permanently out of scope | [Designer reverse sync](designer-architecture.md#current-designer-limitations) | +| TPL-01 | Templates/compatibility | The packaged starter template is Windows-only and the published libraries target .NET 10; Android needs an explicit activity/surface host. | Compatibility limitation | Medium | Older .NET [#44](https://github.com/ProGraMajster/ModernFormsNext/issues/44); Android host [#72](https://github.com/ProGraMajster/ModernFormsNext/issues/72) | [Installation](installation.md#android) | +| REL-01 | Documentation/release | Browser rendering, interactive VS Designer, Marketplace publication, and Android device observation remain manual gates outside deterministic DocFX/package tests. | Validation gap | Low | Automation and explicit handoffs [tracked #82](https://github.com/ProGraMajster/ModernFormsNext/issues/82) | [Versioned documentation](releasing/versioned-documentation-artifacts.md#current-validation-boundaries) | +| REL-02 | Repository validation | Nested worktrees under `artifacts/` can contaminate project-enumeration tests; exact-SHA validation needs a clean external worktree and sequential build flags. | Tooling limitation | Low | [Tracked #83](https://github.com/ProGraMajster/ModernFormsNext/issues/83) | [Versioned documentation](releasing/versioned-documentation-artifacts.md#current-validation-boundaries) | +| RES-01 | Dynamic resources | Reflection-based property references need a trimming/AOT metadata strategy; merged dictionaries and factories are not implemented. | Compatibility limitation | Medium | [Tracked #84](https://github.com/ProGraMajster/ModernFormsNext/issues/84) | [Dynamic resources](dynamic-resources.md#current-limits) | +| BND-01 | Data binding | No ModernFormsNext-native `BindingNavigator`; WinForms designer serialization hooks are intentionally not ported. | Missing feature | Medium | Native control [tracked #85](https://github.com/ProGraMajster/ModernFormsNext/issues/85); WinForms serialization hooks remain permanently out of scope | [Data binding](data-binding.md#current-limitations) | +| TXT-01 | RichTextBox | The portable RTF/editor subset omits OLE, protected ranges, URL activation, bullets/paragraph indentation rendering, custom tab stops, and native IME language-option behavior. | Compatibility limitation | Medium | Compatibility surface [tracked #86](https://github.com/ProGraMajster/ModernFormsNext/issues/86); shared IME [#62](https://github.com/ProGraMajster/ModernFormsNext/issues/62) | [RichTextBox](richtextbox.md#compatibility-notes) | +| TXT-02 | Markdown/document editing | No keyboard focus/activation for individual links, native touch selection UI, stable runtime drag/drop image insertion, very-large-document virtualization, or full WYSIWYG editing. | Missing feature | Medium | Umbrella [#87](https://github.com/ProGraMajster/ModernFormsNext/issues/87); related [#55](https://github.com/ProGraMajster/ModernFormsNext/issues/55), [#57](https://github.com/ProGraMajster/ModernFormsNext/issues/57), and [#62](https://github.com/ProGraMajster/ModernFormsNext/issues/62) | [Markdown](markdown.md#compatibility-matrix), [MarkdownEditor](markdown-editor.md#current-limitations) | +| TIP-01 | ToolTip | `UseAnimation`, `UseFading`, and full inactive-window `ShowAlways` behavior are compatibility storage only. | Compatibility limitation | Low | Runtime behavior or permanent-no-op decision [tracked #88](https://github.com/ProGraMajster/ModernFormsNext/issues/88) | [ToolTips](tooltips.md#compatibility-notes) | +| LAY-01 | Layout/RTL | Flow and table layout do not have complete right-to-left behavior; related TODOs remain in the layout implementation. | Missing feature | Medium | Layout parity [tracked #89](https://github.com/ProGraMajster/ModernFormsNext/issues/89); related localization [#14](https://github.com/ProGraMajster/ModernFormsNext/issues/14) | [Roadmap](roadmap/ModernFormsNext-Framework-Roadmap.md#known-cross-cutting-risks) | + +## Current status by subsystem + +- **Completed and supported on the primary Windows path:** Shape controls and the documented + geometry subset; shared scheduler; LayoutTransition; padding/border visual-state metrics; + compatible Brush interpolation including different non-empty gradient-stop counts; ThemeManager; + Form/UserControl design roots; `.mfdesign` serialization and generated C# for supported values; + versioned tag/SHA-bound documentation archives. +- **Completed but intentionally bounded:** safe source-metadata effects, data-only UserControl + preview, conservative reverse parsing, per-control layout transitions, and discrete Brush + fallback for incompatible values. +- **Experimental:** Android shared-control hosting, animation frame pacing, lifecycle adapter, + permissions, pointer routing, and TextBox IME integration. + +See the [1.10.0 documentation and limitations audit](audits/1.10.0-documentation-and-limitations-audit.md) +for obsolete statements removed, issue coverage, proposed backlog items, and the TODO/FIXME review. diff --git a/docs/paint-and-gradients.md b/docs/paint-and-gradients.md index 649f4a0..1160bbb 100644 --- a/docs/paint-and-gradients.md +++ b/docs/paint-and-gradients.md @@ -195,11 +195,10 @@ change. Common source operations remain available, including indexing, enumerati initializers, `Add`, `AddRange`, `Remove`, and `Clear`. Code that explicitly requires `List` must accept `IList` or `GradientStopCollection` instead. -## Planned JSON representation +## Theme JSON representation -There is no runtime brush JSON converter in this stage. Implementing half of ThemeManager's loading -and validation pipeline would create a second, premature contract. The planned schema direction is -renderer-neutral, camel-cased, and discriminated by `type`: +`ThemeJsonSerializer` reads and writes the strict ThemeManager schema. Brush values are renderer- +neutral, camel-cased, and discriminated by `type`: ```json { @@ -216,23 +215,27 @@ renderer-neutral, camel-cased, and discriminated by `type`: } ``` -The intended discriminators are `solid`, `linearGradient`, `radialGradient`, `sweepGradient`, and -`none`. Eight-digit colors use `#AARRGGBB`; six-digit colors are opaque. A radial value adds +The supported discriminators include `solid`, `linearGradient`, `radialGradient`, `sweepGradient`, +`glass`, and `none`. Eight-digit colors use `#AARRGGBB`; six-digit colors are opaque. A radial value adds `center`, `origin`, and `radius`; a sweep value adds `center`, `startAngle`, and `endAngle`. The -future ThemeManager work must version this schema, validate unknown/missing fields, produce path- -specific errors, and test round trips before it becomes a supported file format. +loader validates unknown or missing fields, enforces bounded collections and inheritance, reports +path-specific errors, and never activates CLR types through reflection. See the complete +[theme JSON schema](theme-json-schema.md) for the current allow-list and limits. ## Current limitations - Relative mapping is the only supported coordinate mode; absolute mapping is deferred. - Radial gradients are circular and use one radius, not independent X/Y radii. - Existing public Skia-compatible members remain for source compatibility; use the neutral members - in new application, theme, and future shape code. -- Advanced color-space interpolation and brush animation helpers are not implemented. + in new application, theme, and shape code. +- Advanced color-space interpolation is not implemented. Planner-based state/theme transitions + support compatible built-in brushes, while the identity-preserving `Brush.AnimateTo` helper has + the narrower exact-type/equal-stop-count contract. - Shader objects are intentionally short-lived and disposed per rendering scope; there is no global bounds-dependent native shader cache. - Android uses the same model and shader factory, but Android support as a whole remains experimental and still requires physical-device GPU validation. See the **Paint & Gradients** page in `samples/ControlGallery` for manual resize, spread, transform, -runtime mutation, and dynamic-resource checks. +runtime mutation, and dynamic-resource checks. Remaining boundaries are indexed in +[Known limitations](known-limitations.md). diff --git a/docs/platform-specific-code.md b/docs/platform-specific-code.md index 532f99d..df6c222 100644 --- a/docs/platform-specific-code.md +++ b/docs/platform-specific-code.md @@ -20,10 +20,13 @@ an Application Context or lifecycle. Full desktop WindowKit services continue to use the established `AvaloniaGlobals` registry. The lightweight backend layer now also exposes `PlatformServiceRegistry`, allowing Android foundation -services to be used without loading desktop rendering/windowing dependencies. The first Android -iteration registers: +services to be used without loading desktop rendering/windowing dependencies. The current Android +foundation registers: - `IPlatformDispatcher`; +- `IPlatformApplicationLifecycle`; +- `IPlatformAnimationSettings`; +- `IPlatformAnimationFrameSource`; - `IPermissionService`. It does not register `IWindowingPlatform`, `IClipboard`, or empty placeholders. Consumers therefore @@ -49,3 +52,6 @@ Clipboard, OpenUri, sharing, file pickers, notifications, WebView, media, camera drag-and-drop should each remain Android backend services. Only capability-shaped DTOs and contracts belong in shared code. Android `Intent`, `Activity`, `Context`, `Uri`, and permission strings remain implementation details of the Android assembly. + +The implemented and missing platform boundaries are summarized in +[Known limitations](known-limitations.md). diff --git a/docs/platforms/android.md b/docs/platforms/android.md index 7d458aa..af5452d 100644 --- a/docs/platforms/android.md +++ b/docs/platforms/android.md @@ -42,6 +42,9 @@ framework controls. Android-specific types remain in `ModernFormsNext.WindowKit. - Activity foreground/background transitions, pause/resume, configuration changes, and activity replacement are tracked. The cross-platform sample keeps its process-owned control tree and state when the host activity is recreated. +- Animation frames use one demand-driven Choreographer callback. The platform animation provider + reads `Settings.Global.ANIMATOR_DURATION_SCALE` and observes it only while the lifecycle is + foreground and animation policy has subscribers. - The shared ThemeManager model, strict JSON stream loader, dynamic theme resources, built-in Light/Dark themes, and scheduler-based transitions compile for Android. Background/no-host time is excluded by the existing lifecycle integration. @@ -57,10 +60,11 @@ framework controls. Android-specific types remain in `ModernFormsNext.WindowKit. - Android does not implement the general `Application.Run(Form)` startup path, `IWindowingPlatform`, or `IWindowImpl`. Applications must currently provide an Android activity and attach a control root explicitly. -- Android does not yet register a system light/dark or reduced-motion ThemeManager provider. - `ThemeVariant.System` therefore uses the explicit Light/Dark apply fallback. This limitation does - not imply runtime parity: startup, switching, storage streams, and visual transitions still need - emulator/device validation for a release. +- Android does not yet register a system light/dark ThemeManager provider. `ThemeVariant.System` + therefore uses the explicit Light/Dark apply fallback. Reduced motion is separate: the Android + animation-settings provider reads and observes the global animator-duration scale. Neither + implementation implies runtime parity; startup, switching, storage streams, setting changes, and + visual transitions still need broad emulator/device validation for a release. - Only one framework control surface is exercised. Multiple framework windows, popups, owned windows, and desktop-style window management are not available. - Clipboard, native dialogs, file/folder pickers, drag and drop, notification delivery, camera and @@ -85,6 +89,9 @@ framework controls. Android-specific types remain in `ModernFormsNext.WindowKit. production performance targets, long-running stability tests, and broad device/IME/accessibility coverage are not yet part of the release gate. +The [central known-limitations index](../known-limitations.md) maps these boundaries to existing +issues and audit proposals. + ## Requirements - The .NET SDK selected by [`global.json`](../../global.json) (`10.0.201`, with .NET 10 feature-band diff --git a/docs/releasing/versioned-documentation-artifacts.md b/docs/releasing/versioned-documentation-artifacts.md index 4ad3ec7..0d489a1 100644 --- a/docs/releasing/versioned-documentation-artifacts.md +++ b/docs/releasing/versioned-documentation-artifacts.md @@ -145,6 +145,24 @@ docs/migrations/1.9.0-to-1.10.0.md All tracked migration guides are included automatically. A release without a migration guide does not fail; do not create a synthetic guide when there are no known migration steps. +## Current validation boundaries + +The canonical DocFX inputs are `docs-site/`, tracked repository documentation, and API metadata from +matching Release assemblies/XML. Ignored local `docs/docfx.json`, `docs/index.md`, `docs/toc.yml`, +`docs/api/`, and `docs/_site/` remnants are not release inputs and must not be treated as a second +documentation source. + +The scripts deterministically validate metadata, archives, public links represented by repository +content, and internal offline links. Browser rendering, interactive Visual Studio Designer/VSIX +behavior, Marketplace publication, and Android emulator or physical-device behavior remain manual +gates and must be reported separately. + +Repository-wide project/version enumeration can see nested Git worktrees placed below `artifacts/`. +For an exact-SHA release check, use a clean external worktree and run builds/tests sequentially with +`-m:1 /p:UseSharedCompilation=false`; do not weaken consistency tests to accommodate a contaminated +checkout. The [central known-limitations index](../known-limitations.md) records this tooling +boundary. + ## Security and exclusions Bundle inputs are allowlisted and selected from Git-tracked paths. Validation rejects `.git`, diff --git a/docs/roadmap/ModernFormsNext-Framework-Roadmap.md b/docs/roadmap/ModernFormsNext-Framework-Roadmap.md index 52cd30b..87c9e62 100644 --- a/docs/roadmap/ModernFormsNext-Framework-Roadmap.md +++ b/docs/roadmap/ModernFormsNext-Framework-Roadmap.md @@ -1,6 +1,6 @@ # ModernFormsNext framework roadmap -- Baseline audited: 2026-08-01 +- Baseline audited: 2026-08-18 against ModernFormsNext 1.10.0 - Paint/gradient foundation implemented: 2026-07-19 - ThemeManager, composable animations, and platform animation polish implemented for 1.9.0 - SDK baseline: .NET 10 (`10.0.201`) @@ -26,7 +26,7 @@ The architecture should therefore be extended, not replaced. The implementation 4. ThemeManager (implemented foundation), then localization; 5. page lifecycle, navigation, routing, tabs, flyout, and shell; 6. virtualized data controls and SearchBar; -7. shapes and path geometry; +7. shapes and path geometry (implemented 1.10.0 foundation); 8. modular document providers and viewers; 9. charts, then diagrams. @@ -46,38 +46,44 @@ already exist. | Properties | CLR properties plus compact internal `PropertyStore` | Dynamic resources and future generated descriptors invoke existing setters. No dependency-property clone. | | Layout | `LayoutEngine`, `DefaultLayout`, `FlowLayoutPanel`, `TableLayoutPanel`, `Dock`, `Anchor`, margin/padding/min/max/AutoSize | Page hosts, collection presenters, shell panes, and shapes must use these transactions and constraints. | | Styles | `ControlStyle`, parent-style fallback, normal/hover state, compatibility `BackColor`/`ForeColor` | Extend state/style representation incrementally; preserve renderer-facing style objects. | -| Paints | Observable `Drawing.Brush`; solid, glass, no-fill, linear/radial/sweep gradients; typed stops; opacity/transform/spread; shared Skia adapter | Reuse for ThemeManager and future shapes/charts. Version and implement the documented JSON direction only with ThemeManager validation. | +| Paints | Observable `Drawing.Brush`; solid, glass, no-fill, linear/radial/sweep gradients; typed stops; opacity/transform/spread; shared Skia adapter; strict ThemeManager JSON | Reuse for ThemeManager, shapes, and future charts. Keep JSON validation in the one ThemeManager schema. | | Rendering | Per-control `SKBitmap` back buffers, renderer classes, `PaintEventArgs`, Skia canvas helpers | Shapes/charts/documents render through Skia and existing clipping/invalidation. Avoid native control substitution. | | Invalidation | Property setters call `Invalidate`, layout setters use layout transactions; windows invalidate platform surfaces | Dynamic values call normal setters and do not globally repaint. Add dirty-region precision later. | -| Animation | Shared monotonic `AnimationScheduler`, composable definitions/runs, handles, owner/key replacement, typed interpolators, Brush transitions, native reduced-motion policy, diagnostics, and compatibility helpers | Reuse for theme/shape/navigation transitions; keep layout invalidation explicit and design animated layout as a separate future subsystem. | +| Animation | Shared monotonic `AnimationScheduler`, composable definitions/runs, handles, owner/key replacement, typed interpolators, Brush transitions, native reduced-motion policy, animated bounds, layout-aware state metrics, diagnostics, and compatibility helpers | Reuse for theme/shape/navigation transitions; preserve the single scheduler and existing layout-transition contract. | | Input | Framework mouse/keyboard/text/IME pipeline, capture, hit testing, touch scrolling in `SkiaControlSurface` | Collection, SearchBar, pages, charts, and shapes share the same input path. | | Data binding | `IBindableComponent`, `Binding`, `BindingContext`, `BindingSource`, list managers and converters | Reuse for items sources and selected values; add collection-change/virtualization contracts instead of a parallel binding engine. | | Serialization | `System.Text.Json` in designer and binding conversion; stable design document serializer | Reuse conventions and converters, but keep theme/localization runtime schemas separate from designer files. | | Documents | `Documents.Document`, block/inline/table/image/list/code model, Markdown parser, layout/text map/selection/cache, `DocumentViewer` | Evolve and extract compatibly. Do not recreate the requested model under duplicate public names. | | Windows | Full `IWindowingPlatform`, Win32 input/window/services and Skia framebuffer path | Primary runtime for page hosting, printing, clipboard, system theme, pointer/keyboard validation. | -| Android | Lifecycle/permissions/main-thread dispatcher, `AndroidSkiaHostView`, `SkiaControlSurface`, native IME and multi-touch | Shared controls can be validated now; window/shell/back/accessibility/service parity remains a separate prerequisite. | +| Android | Lifecycle/permissions/main-thread dispatcher, Choreographer/settings integration, `AndroidSkiaHostView`, `SkiaControlSurface`, native IME and multi-touch | Shared controls can be validated now; window/shell/back/accessibility/service parity and broad device evidence remain separate prerequisites. | | Packaging | Packable core and WindowKit projects, conditional Windows backend, templates, tests and samples | Add optional feature packages without reversing dependency direction. | ### Architectural gaps - No page lifecycle, page host, navigation stack, route registry, deep-link contract, or back-request abstraction. -- Existing `Theme` is a static heterogeneous bag centered on colors; it has no serializable schema, - validation, inheritance, scoped overrides, state styles, system-theme adapter, or atomic update. -- `ControlStyle` has only a small normal/hover model. It lacks pressed/selected/disabled/focused state - resolution, brushes for every surface, typography records, shadow, radius, and transitions. -- Brush mutation, opacity, transforms, stable stop ordering, spread modes, and targeted invalidation - are implemented. A batch update scope, advanced interpolation, and a versioned JSON loader remain. +- `ThemeManager` now provides strict JSON, validation, inheritance, atomic apply, dynamic-resource + defaults, state styles, and transitions. Automatic OS-theme reapply, file hot reload, a shared + shadow rendering contract, and an Android system-theme provider remain gaps. +- `ControlStyle` resolves Normal/Hover/Pressed/Focused/Disabled states with brush, typography, + border, corner, transform, and transition data. Layout-aware interpolation is deliberately + limited to padding and border widths; selected-state and broader metric contracts remain future. +- Brush mutation, opacity, transforms, stable stop ordering, spread modes, planner interpolation, + strict Theme JSON, and targeted invalidation are implemented. A batch update scope, absolute + mapping, and selectable color-space interpolation remain. - The shared scheduler marshals callbacks to the UI dispatcher, uses elapsed monotonic time, stops while idle, pauses over Android background lifecycle, and integrates Windows/experimental Android - reduced-motion preferences. A live Android settings observer, physical-device frame-pacing - validation, and a general animated-layout subsystem remain future work. + reduced-motion preferences. Android now has a lifecycle/subscription-aware settings observer and + Choreographer source; physical-device frame-pacing/profile validation remains future work. - No localization catalog/provider, plural rules, missing-key diagnostics, dynamic culture change, or verified end-to-end RTL layout behavior. - Lists and grids are retained collections; there is no shared item-container generator, virtualization/recycling, incremental loading, or observable items-source abstraction suitable for `CollectionView` and charts. -- No retained vector geometry/path parser/hit-testing model. +- The retained Shape/Geometry model, path figures, line/quadratic/cubic segments, transforms, Skia + rendering, hit testing, Designer round trips, and ControlGallery coverage are implemented. + Arcs, geometry groups/boolean operations, SVG import, a general Stretch contract, and graphical + Bezier editing remain future work. - No general document provider registry, MIME sniffing contract, paged render source, password request, or platform print adapter. Existing document code is in the main package. - Android does not yet host `Form`, multiple windows, general popups/dialogs, platform accessibility, @@ -95,8 +101,9 @@ already exist. semantics merely for code reuse. - `Theme` and `BuiltInTheme` are public. ThemeManager must retain a compatibility facade and cannot silently redefine existing values or event order. -- `Path` collides conceptually with `System.IO.Path`; keep it in a clear namespace such as - `ModernFormsNext.Shapes` and provide unambiguous documentation. +- `ModernFormsNext.Path` collides conceptually with `System.IO.Path`; qualify either type where both + are used. Moving the shipped public type to a proposed `ModernFormsNext.Shapes` namespace would + be a breaking change and is not roadmap cleanup. - `Application` is static and `Application.Run(Form)` is Windows-oriented. AppShell must not make `Application` state instance-based as an accidental breaking change. @@ -116,8 +123,8 @@ Items source + container recycling -> CollectionView -> CarouselView / SearchBar suggestions / chart legends -> RefreshView composes any scroll host -Geometry + Paint -> Shapes - -> chart render primitives -> diagrams +Geometry + Paint -> Shapes (implemented foundation) + -> future chart render primitives -> diagrams Document provider + viewport contracts -> PDF provider/viewer -> general DocumentViewer @@ -216,13 +223,13 @@ manual while the backend is experimental. Done/tests: solid/linear/radial/focal/sweep/no-fill rendering, opacity, transform, tile modes, bounds, strict offsets, stable duplicate offsets, mutation, resource precedence/fallback, weak subscriptions, Designer round-trip, and scoped shader disposal are covered. ControlGallery provides -manual visual checks. A versioned JSON converter, batch notifications, absolute mapping, and advanced -color interpolation are explicitly deferred. +manual visual checks. ThemeManager provides the strict versioned JSON schema. Batch notifications, +absolute mapping, and advanced color interpolation are explicitly deferred. #### UI animation scheduler — implemented foundation -Purpose: provide one platform-neutral, monotonic UI scheduler for control, value, Brush, future -theme, shape, and navigation transitions without a timer per animation. +Purpose: provide one platform-neutral, monotonic UI scheduler for control, value, Brush, theme, +shape, and future navigation transitions without a timer per animation. Implemented API: `AnimationScheduler`, `AnimationHandle`, `AnimationState`, `AnimationOptions`, owner/key replacement, `AnimationPolicy`, `AnimationSchedulerDiagnostics`, built-in easing, typed @@ -238,8 +245,9 @@ Done/tests: deterministic manual clock/tick tests cover progress, delay, dropped replacement, cancellation, faults, policy modes, dispatcher affinity, high animation counts, interpolation, Brush/dynamic-resource invalidation, composition, keyframes, repeat, auto-reverse, visual-state transitions, interaction effects, and owner lifetime without `Thread.Sleep`. -ControlGallery provides opt-in manual checks and cancels all work on unload. A general animated- -layout layer and physical-device Android frame-pacing validation are explicitly deferred. +ControlGallery provides opt-in manual checks and cancels all work on unload. Animated bounds and +selected visual-state layout metrics are implemented in 1.10.0; physical-device Android frame- +pacing validation remains deferred. #### 3. ThemeManager — implemented foundation @@ -484,27 +492,23 @@ Done/tests: cultures/12–24h/seconds, bounds and wrapping policy, nullable stat format parsing, DST explicitly irrelevant to `TimeOnly`, accessibility and shared regression tests for DateTimePicker. -### Stage 4 — shapes and vector geometry +### Stage 4 — shapes and vector geometry (implemented 1.10.0 foundation) -#### 17. Shape and geometry system — difficulty: Very high +#### 17. Shape and geometry system — delivered foundation; advanced scope remains -Purpose: `Shape`, `Ellipse`, `Line`, `Path`, `Polygon`, and `Polyline` with fill/stroke, opacity, -caps/joins/dashes, geometry scaling, hit testing, and animatable properties. +Implemented: `Shape`, `Ellipse`, `Circle`, `Line`, `Path`, `Polygon`, and `Polyline`; fill/stroke, +opacity, caps/joins/dashes, transforms, fill rules, layout, invalidation, hit testing, Skia resource +caching, and Designer round trips. `ModernFormsNext.Drawing` contains line, rectangle, ellipse, +path/figure, line-segment, quadratic-Bezier, and cubic-Bezier geometry. The Designer provides +structured point/path editors and culture-invariant compact parsing. ControlGallery and focused +tests cover runtime/Designer behavior without introducing another renderer or layout engine. -Proposed API: `ModernFormsNext.Shapes.Shape : Control`; `Fill`, `Stroke`, `StrokeThickness`, -`StrokeLineCap`, `StrokeLineJoin`, `StrokeDashArray`, `Stretch`; geometry types `PathGeometry`, -`PathFigure`, `LineSegment`, `BezierSegment`, `QuadraticBezierSegment`, `ArcSegment`; a culture- -invariant SVG/XAML-like path parser with documented supported grammar. - -Dependencies: hardened paints, UI-thread animation/interpolator service, layout/invalidation. - -Risks/platform: arc conversion, numerical stability, bounds including stroke, dash scaling, path -parser security/complexity, mutable point collections, hit-test performance and name collision. -All geometry stays shared Skia code. - -Done/tests: parser valid/invalid corpus, line/Bezier/quadratic/arc geometry, stretch modes, fill rules, -caps/joins/dashes/transparency/gradients, bounds and hit tests, mutation invalidation, animation -cancellation, no per-frame path leaks, golden rendering on Windows and Android density checks. +Remaining advanced scope: arc segments, geometry groups/boolean operations, SVG import or a core +SVG-style path grammar, a general `Stretch` contract, generic Control geometry clips, and a +graphical Bezier editor. These are proposals, not 1.10.0 capabilities. Android compiles the shared +renderer, but physical-device visual/touch/GPU/cache profiling is still a validation gap. See +[Shapes and vector geometry](../shapes-and-vector-geometry.md) and +[Known limitations](../known-limitations.md). ### Stage 5 — modular documents @@ -624,7 +628,8 @@ dependency-based bands: - Navigation preview: Page/ContentPage/NavigationPage/routing; Windows host plus Android surface host. - Shell preview: TabbedPage/FlyoutPage/AppShell after lifecycle/back tests are stable. - Data controls preview: virtualization foundation, CollectionView, then carousel/refresh/search/time. -- Vector preview: shapes/path parser and animation integration. +- Vector foundation: shapes, retained geometry, Skia rendering, hit testing, Designer round trips, + and compact path parsing are implemented; advanced geometry/authoring remains future. - Documents preview: provider contracts and compatibility plan, then optional PDF, viewer unification, editor slices. - Visualization preview: core charts first; advanced charts and diagrams in later increments. @@ -639,8 +644,8 @@ dependency-based bands: and explicit reset APIs before broad parallel execution. - Reflection-based CLR property references need a trimming/source-generation strategy before AOT is advertised. -- Android physical-device pacing and live settings observation remain open even though shared - animation callbacks use the platform UI dispatcher and foreground refreshes motion preferences. +- Android physical-device pacing and profiling remain open even though shared animation callbacks + use Choreographer and the lifecycle/subscription-aware provider observes motion preferences. - Virtualization, document rendering, and charts compete for cache/memory budgets. Introduce shared diagnostics and bounded caches rather than independent unbounded stores. @@ -648,5 +653,6 @@ dependency-based bands: **Localization on the completed resource/theme foundation.** Build JSON-first localization providers, culture fallback, formatting/plurals, live resource updates, safe diagnostics, and RTL -metadata without duplicating the property or resource systems. Shape remains a separate later -stage; theme shadows should wait for a shared rendering contract. +metadata without duplicating the property or resource systems. Shape foundation is already shipped; +advanced geometry and theme shadows should wait for explicit contracts. In parallel, prioritize the +Designer transaction/parity backlog and Android device evidence before broadening platform claims. diff --git a/docs/shapes-and-vector-geometry.md b/docs/shapes-and-vector-geometry.md index 9c45f5c..f20c9e4 100644 --- a/docs/shapes-and-vector-geometry.md +++ b/docs/shapes-and-vector-geometry.md @@ -144,3 +144,16 @@ and generated C# use invariant decimal syntax independently of the current UI cu Open **Shapes** in ControlGallery for solid and gradient fills, gradient and solid strokes, caps, joins, a reusable Bezier path, a vector transform, and stroke-safe control-bound smoke tests. + +## Current limitations + +- The geometry model has line, rectangle, ellipse, line segment, quadratic Bezier, and cubic Bezier + primitives. It does not yet include arc segments, geometry groups/boolean operations, SVG import + or a core SVG-style path string, a general `Stretch` contract, or generic Control geometry clips. +- The Designer provides structured and compact text editors, not a graphical Bezier canvas. +- Windows and Android share the Skia renderer, but the Android Shape path has no recorded physical- + device visual, touch-hit, GPU, or cache-profile matrix. An Android build is not that evidence. + +See [Known limitations](known-limitations.md) and the +[1.10.0 audit proposals](audits/1.10.0-documentation-and-limitations-audit.md#p3-extend-vector-geometry-and-path-designer-tooling) +for issue-ready scope without claiming those features are implemented. diff --git a/docs/themes.md b/docs/themes.md index d21ac4b..28a7b41 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -203,9 +203,11 @@ Only the shared `AnimationScheduler` is used. Compatible changed values are: - compatible linear, radial, and sweep gradients, including geometry, opacity, transform, stop colors, and stop offsets. -An incompatible Brush type or gradient stop count switches immediately. Glass and no-fill brushes -also switch immediately. Spacing, padding, sizing, corners, borders, typography, and other layout -values switch at commit to avoid a layout pass on every frame. +An incompatible Brush type switches immediately. Compatible gradients may have different non-empty +stop counts; the shared planner normalizes them for the transition. Cross-kind gradient geometry, +empty-to-populated gradients, Glass, and no-fill brushes switch immediately. Spacing, padding, +sizing, corners, borders, typography, and other layout values switch at commit to avoid a layout +pass on every frame. Platform reduced-motion can suppress transition creation. The scheduler's `AnimationsEnabled`, `ReducedMotion`, and duration policy is authoritative, including for active work. Background/no-host @@ -306,3 +308,5 @@ kept for rendering, window-lifecycle, emulator/device, and interactive Designer - line height and letter spacing are not globally honored; - Android has no system-theme provider and remains experimental; - physical-device Android and interactive Designer checks cannot be replaced by headless tests. + +See the [central known-limitations index](known-limitations.md) for issue mapping and priorities. diff --git a/docs/user-controls.md b/docs/user-controls.md index dab18c7..531773c 100644 --- a/docs/user-controls.md +++ b/docs/user-controls.md @@ -115,11 +115,18 @@ self-reference check so manually edited invalid documents cannot generate design renderer. Runtime-only custom property behavior, referenced-binary-only controls, and user code side effects are intentionally absent. The safe placeholder remains the fallback when a source document cannot be identified unambiguously. -- The designer has copy/paste and duplicate operations for child controls, but no general - transaction-based undo/redo stack or multi-select support yet. +- The designer has in-session, single-control copy/paste and duplicate operations for child + controls. Cut, a system clipboard contract, complete cross-document behavior, transaction-based + undo/redo, and multi-select support are not implemented. - The Visual Studio designer and interactive preview are currently Windows-first. `UserControl` itself remains in the shared, platform-neutral framework project. +Source `.mfdesign` changes are re-read on the next render through the preview cache key. Changes to +the set or identity of source-discovered types require reopening the Designer; binary-only discovery +and a complete custom property/event metadata surface are not implemented. See +[Known limitations](known-limitations.md) and the +[1.10.0 audit proposal](audits/1.10.0-documentation-and-limitations-audit.md#p2-complete-safe-custom-control-discovery-and-metadata). + ## Manual Visual Studio smoke test 1. Add a **ModernFormsNext UserControl** named `MyUserControl1` and place, in order, a `Label`,