drawnui

name	drawnui
description	Working with DrawnUI UI, controls, layouts (SkiaStack, SkiaRow, SkiaLayer, SkiaWrap, SkiaGrid), rendering, caching, gestures, overlays, SkiaLayout, SkiaShape, SkiaButton, Canvas, virtualization, or XAML/C# composition in DrawnUi-based apps.
triggers	["drawnui"]
version	1.10.0
tags	["drawnui","blazor","webassembly","dotnet"]

DrawnUI

Maintenance Rule

• Update this skill whenever a new verified DrawnUI rule, pattern, pitfall, correction, or better workflow is discovered and it is missing here.
• If the user corrects a DrawnUI assumption, behavior, or recommended approach, correct this skill too after verifying the new rule well enough to avoid storing a bad pattern.
• Prefer keeping reusable cross-project DrawnUI guidance here; put repo-only facts in repo memory when they are too specific to generalize.

Use for DrawnUI-specific implementation details, not generic MAUI assumptions.

Primary docs source: docs inside the DrawnUi repo. Locate a local checkout if present; otherwise use the published docs at https://drawnui.net (same content, rendered) or the repo https://github.com/DrawnUi/DrawnUi.Net. For SOURCE CODE without a local checkout, read it from GitHub (browse or raw fetch) — NuGet packages ship compiled assemblies with SourceLink PDBs and XML API docs (lib/<tfm>/*.xml in the package cache is useful for offline API signatures), not .cs files.

Start here before guessing patterns:

• docs/index.md
• docs/articles/getting-started.md
• docs/articles/layouts.md
• docs/articles/gestures.md
• docs/articles/interactive-button.md
• docs/articles/sample-apps.md
• docs/articles/web/index.md (pure WebAssembly target)
• docs/api/index.md

For Blazor-specific work load the drawnui-blazor skill. For pure-WebAssembly (DrawnUi.Web, no Blazor) see the section below.

Core Rules

• PROHIBITED: writing any DrawnUI UI composition without a caching plan. Before emitting code, decide for EVERY subtree whether it is cached or uncached and WHY, from its invalidation source: static chrome (toolbars, panels, side bars) → UseCache = Image at the top of the subtree; scroll content → Image on the content (blitted at offset — never cache the scroll's parent, that thrashes per scroll frame); document/artboard layers with independently-changing children → ImageComposite (re-records changed children only); constantly-repainting overlays (adorners, marquee, custom per-frame paint) → NO cache; stable overlays sitting over live surfaces that repaint every frame → cache them so they blit. Shipping a whole app shell with zero UseCache (only leaf visuals cached) is the failure mode this rule exists to prevent — it makes a drawn app feel laggy and reads as "drawn UI is slow" when it is not.
• ALWAYS add XML documentation comments to every class and public/protected API member you create in DrawnUI library code (classes, properties, fields, methods, ctors). Human-readable, states purpose + when to use; no undocumented public surface.
• Prefer DrawnUI docs first, then existing repo/sample patterns, before inventing new structure.
• Keep Canvas at RenderingMode="Accelerated" when hosting DrawnUI camera or GPU-rendered content.
• Do not nest UseCache="GPU" inside already GPU-cached or GPU-rendered content unless runtime evidence proves it safe.
• Prefer top-level GPU cache only. Do not assume inner controls should default to no cache; decide from redraw source, visual stability, and subtree cost.
• Preserve stable layout sizing. Avoid Auto sizing around performance-sensitive DrawnUI surfaces unless existing code already depends on it.
• For camera overlays, place controls inside DrawnUI tree when interaction/visual sync matters.
• For simple app chrome over DrawnUI, MAUI overlay is acceptable only if user did not ask for DrawnUI-native controls.

C# Code-Behind Composition and Event Wiring

See drawnui-fluent skill for all C# code-behind patterns: inline control construction, .Assign(out _field), .OnTapped(), .OnTextChanged(), .ObserveProperty(), .ObserveProperties(), .Adapt(), .WhenPaint(), .ObserveSelf(), gradients, colors, shadows, and per-control code patterns.

Layouts — prefer semantic aliases

Prefer alias controls over raw SkiaLayout Type="..." — same class, preset Type + sane defaults. Aliases default HorizontalOptions=Fill; base SkiaLayout does NOT fill and defaults to Type=Absolute, so raw SkiaLayout Type=Column aligns differently than SkiaStack.

Alias	Equals	Use
SkiaStack	SkiaLayout Type=Column + Fill	vertical stack (MAUI VerticalStackLayout)
SkiaRow	SkiaLayout Type=Row	horizontal stack
SkiaLayer	SkiaLayout Type=Absolute + Fill	overlay/superposition; single-cell-grid substitute
SkiaWrap	SkiaLayout Type=Wrap + Fill	responsive wrap
SkiaGrid	SkiaLayout Type=Grid + Fill	MAUI Grid alternative
SkiaFrame	SkiaShape Type=Rectangle	NOT a layout — shape alias

• Grid: ColumnDefinitions/RowDefinitions (*, 2*, Auto, absolute), attached SkiaLayout.Column/Row/ColumnSpan/RowSpan (0-based), ColumnSpacing/RowSpacing. SkiaDecoratedGrid = grid drawing separator lines (HorizontalLine/VerticalLine gradients).
• Split = explicit column count for Column/Wrap/Grid with ItemsSource; UseDynamicColumns lets a short last row expand; grid Invert flips fill order to columns-first.
• Perf: for a known-size icon + label pair prefer an Absolute layer + left Margin on the label over a 2-column grid.
• Shader effect + image that overflows its box = misplaced output (root-caused & fixed in DrawnUi 2026-08-20, two stacked bugs). Triggers only when a SkiaShaderEffect sits on a SkiaImage whose drawn content is bigger than its DrawingRect — classically AspectCover driven by HEIGHT (square/landscape source in a taller-than-wide box; portrait sources are width-driven and never show it). (1) SkiaImage.CachedImage returned ScaledSource.Image, rasterized at DISPLAY size, and effects map that texture 1:1 onto the box → content shifted right by half the horizontal overdraw. (2) SkiaShaderEffect.CreateSnapshot snapshotted ctx.Destination (CANVAS coords) out of ctx.Surface, which is a CACHE surface while baking into a cached parent → shifted by the control's canvas offset. Diagnosing this class: put a marker stripe at the source centre and measure it in the rendered pixels across box aspect ratios AND with/without the effect — theory alone kept "proving" the aspect math correct, because the math WAS correct.
• Custom deco painting: pick the stage by what must sit under/over it (device-verified 2026-08-20, nameplate crescent): WhenPaint runs BEFORE the shape paints its own background — anything drawn there gets tinted/covered by a translucent bg; WhenPainted/PostAnimators draw above everything, but under a CACHED parent the callback's ctx.Destination can span the whole canvas, not the control (rendered a full-height stripe). The reliable pattern for "after background, before content, correctly sized": a tiny SkiaControl subclass overriding Paint(DrawingContext), mounted as the parent's first child with Fill×Fill — children paint after the shape bg, each with its own correct , and the shape's rounded clip still applies. Example: red crescent = .

Positioning children inside containers — 4 ways, prefer in order

WPF-style system: there is no free X/Y — the layout computes position and stamps the arranged DrawingRect. Pick the FIRST way that fits:

1. Layout-owned (default): Column/Row/Grid/Wrap parents position children — set nothing. Tune with container Spacing/Padding and per-child alignment + size requests.
2. Margin + alignment — the WPF-style workhorse, works in ANY container incl. Absolute: Margin = new(50,0,0,0) places after a logical 50pt column; VerticalOptions = End + Margin = new(0,0,0,100) = exactly 100pt above the container bottom. Arranged by layout → DrawingRect/HitBoxAuto stay truthful (hit-testing, adorners, position math all correct). Often replaces a whole SkiaGrid.
3. Left/Top — cached controls only (UseCache != None): offsets the cached output directly, no matrix transform, faster than Translation, background-thread friendly. Mind cache defaults — many controls are cached out of the box (labels, shapes, svg, lottie…), see the defaults table in § Caching Guidance.
4. TranslationX/Y — LAST resort: matrix transform with save/restore around every draw, the most expensive option. Only when nothing else fits (live gesture drag, transform animations). Trap: a translated CONTAINER shifts rendering but NOT its descendants' HitBoxAuto/DrawingRect — hit-testing/adorner math under a moved container goes stale unless you compensate with the ancestors' own-transform offsets.

Control Patterns

• SkiaLayout: base of ALL layout types (and of SkiaShape); author with the aliases above.
• SkiaShape: Type Rectangle/Circle/Ellipse/Path/Polygon/Line/Arc; IS a SkiaLayout — holds multiple Children and CLIPS them to its outline (LayoutChildren sets their arrangement); ClipBackgroundColor=true = hollow shape (stroke/shadow only). Custom circular UI, shutter buttons, frames, chips, clipped containers.
• SkiaButton: standard text/button interactions. Custom visuals contract: child tagged Tag="BtnText" / Tag="BtnShape" auto-binds text/style. Platform look set in code via UsingControlStyle — SkiaButton has NO bindable ControlStyle (unlike SkiaSwitch/SkiaCheckbox/SkiaSlider, which DO: Cupertino/Material/Windows/Platform).
• Style builders must never clobber user-set properties (fixed 2026-08-28, lib ≥ 1.10.5.18): Create*StyleContent() on styled controls (SkiaSlider, SkiaProgress; Cupertino/Material/Windows/default) runs LAZILY at first measure via CreateDefaultContent — i.e. AFTER the user's object initializer/XAML. They used to assign HorizontalOptions = Fill, MinimumWidthRequest, UseCache unconditionally → a SkiaSlider { HorizontalOptions = Center, WidthRequest = 150 } rendered flush left (ArtOfFoto light table). Now SkiaControl.SetStyleDefault(BindableProperty, value) applies style defaults only when !IsSet(property). Rule for any new styled control: ctor assignments are fine (user code runs after), but anything inside a lazy content builder goes through SetStyleDefault. Pass values with the property's exact CLR type (64d for a double property — a boxed int throws in SetValue). Tell: user-set alignment/cache silently "ignored" on a styled control only; plain layouts honor it. Test: src/Tests/UnitTests/StyleDefaultsTests.cs.
• SkiaSvg: use for icon-based controls. TintColor vs FillColor/StrokeColor; SvgString sets SVG from inline text.
• : default — CROPS; set explicitly when the whole image must show. Never combine Operations/GPU cache with GPU-surface shader effects on it.

Wider control catalog (details: docs/articles/controls/*.md)

SkiaHotspot (invisible tap area) · ContentLayout (single-Content host) · SkiaSwitch / SkiaCheckbox / SkiaRadioButton (GroupName) / SkiaToggle (base for custom toggles) · SkiaSlider (value = End; EnableRange → Start..End; Step) · SkiaProgress (Progress 0–1, IsIndeterminate) · SkiaSpinner (fortune wheel: Segments, Spin(), SpinCompleted) · SkiaWheelPicker (iOS wheel; SelectedIndex bindable) · SkiaCarousel (SelectedIndex, SidesOffset peek, ScrollProgress, InTransition) · SkiaDrawer (edge panel: Direction, HeaderSize, IsOpen, CommandOpen/Close/Toggle) · SkiaShell (drawn navigation: GoToAsync routes, modals, popups, toasts; tagged ShellLayout/RootLayout/NavigationLayout) · SkiaViewSwitcher (PushAsync/PopAsync, TransitionType) · SkiaTabsSelector · SkiaScrollLooped (IsBanner, CycleSpace) · RefreshIndicator (pull-to-refresh, any content incl. Lottie) · SkiaScrollBar (Dock=Start for inverted lists) · SkiaGif · SkiaMediaImage (auto image/gif) · SkiaSprite (sheet: Columns/Rows/FramesPerSecond, FrameSequence, named sequences) · SkiaSpriteSet (stateful actor, HitBoxAuto trimmed hit rect) · SkiaImageManager (PreloadImages(), ReuseBitmaps, ) · · · (embed native MAUI view — MAUI head only; Windows = snapshot; , see its section below) · (see skill).

• On Blazor, local SkiaSvg.Source assets are not instant by default on first render. For public-facing or above-the-fold local SVGs, register them at startup with DrawnExtensions.RegisterSvg(...) and warm them through UseDrawnUiAsync(...) so the first page paint can hit the shared SVG text cache instead of async fetching.
• SkiaLabel: use for lightweight overlay text.
• SkiaImage.PreviewBase64: instant inline preview (e.g. tiny blurred jpeg from backend) shown while Source downloads. Contract: RAW base64 only — SetFromBase64 feeds it straight to Convert.FromBase64String, a data:image/...;base64, data-URI prefix throws FormatException. Must be set BEFORE Source in code-behind. Clear both on recycled cells to avoid stale previews.

SkiaShell overlays and safe insets

Nothing in the lib's overlay/popup/modal path subtracts system insets — ShellLayout spans the FULL edge-to-edge window, so anything pinned to an edge lands under the Android navigation bar / iOS home indicator. Inset source of truth: Super.Screen.BottomInset / TopInset (Internals/Helpers/Screen.cs, populated per platform, Super.InsetsChanged fires on change); SkiaShell.BottomInsets/TopInsets mirror it but only after OnLayoutInvalidated has run at least once — prefer Super.Screen.* in code that can run earlier (e.g. ShowToast builds its control inside Task.Run). App-side XAML binds AddMarginBottom="{Binding BottomInsets}".

Toast (SkiaShell.ShowToast) was fixed 2026-07-20 (device-verified) by padding the toast root — Padding = new Thickness(0, 0, 0, Super.Screen.BottomInset) — NOT a margin: padding keeps the background full-bleed to the screen edge (correct edge-to-edge look) and keeps the slide-in/out animation, which translates by sender.Height, correct. Same treatment is needed for any custom bottom-pinned overlay (VerticalOptions=End inside ShellLayout).

Known unrelated bug nearby, still unfixed: SkiaShell.OnLayoutInvalidated sets TopInsets = Super.Screen.BottomInset (with a //WTF is this??? comment) — should be TopInset.

SkiaMauiElement / SkiaMauiEntry / SkiaMauiEditor — NO CACHED ANCESTORS

Hosted native MAUI views (SkiaMauiElement and its SkiaMauiEntry/SkiaMauiEditor subclasses) are real platform views laid over the canvas. Their on-screen rect + visibility come from the per-frame RENDERED NODE TREE: DrawnView (DrawnView.cs, "notify registered tree final nodes") walks skiaControl.FindRenderedNode(subscriber) and sets VisualTransform.IsVisible = node != null → SkiaMauiElement.ApplyTransform → LayoutNativeView.

SkiaControl.Render() sets VisualLayer = null every frame and rebuilds it. A control drawing from CACHE does NOT re-render its children → its fresh node has EMPTY Children → the hosted element's node is unreachable from the root → IsVisible=false → Android view forced ViewStates.Invisible (size 0x0) → absent from the native view hierarchy, cannot take focus, keyboard never opens. Silent: no exception, the drawn placeholder/frame still paints, so it looks like "focus is broken".

Rules until the lib stops depending on the node tree:

• EVERY ancestor of a SkiaMauiElement must be uncached. Two default-on traps: SkiaShape sets UseCache=Operations in its ctor (a plain frame around an entry kills it → UseCache="None"), and SkiaScroll.AutoCache sets Operations on itself (→ AutoCache="False").
• Diagnosing on Android, in order: adb shell uiautomator dump → is there an EditText node at all? (missing = native view Invisible, NOT a focus bug); adb shell dumpsys input_method | grep -E "mInputShown|mServedView=" (mServedView=DecorView = nothing focused); only then look at focus code.
• Verified 2026-07-20 on device (demo ScreenVarious): entry unblocked by scroll AutoCache=False, editor still dead until its SkiaShape wrapper got UseCache="None". AnimateSnapshot was NOT involved (snapshot=False throughout).

Two lib bugs fixed the same day (both in src/Maui/DrawnUi/Controls/EditText/):

• SkiaMauiEntry created its native Entry in OnLayoutReady(), which never fires → Content stayed null → no native control ever existed. Now created in OnMeasuring, mirroring SkiaMauiEditor which always did it there. Create hosted native content in OnMeasuring, never in OnLayoutReady.
• Both classes still declared public new bool OnFocusChanged(bool) after ISkiaGestureListener renamed it to SetFrameworkFocus(bool). It compiled (base SkiaControl.SetFrameworkFocus is public virtual with a matching signature) but the interface slot silently bound to the base returning CanBeFocused (default false) → canvas always rejected focus. Fixed to override SetFrameworkFocus + CanBeFocused = true + claim focus on TouchActionResult.Down (these controls consume every gesture, so the native view may never see the touch). When renaming an interface method, grep for the OLD name across the repo — new-shadowed leftovers are dead code with NO build error.

SkiaEditor emoji/unicode + caret over shaped runs

• SkiaEditor.UseUnicode (default true) renders emoji/CJK via SkiaRichLabel with MarkdownEnabled=false (rich font-run fallback, NO markdown formatting). UseMarkdown = rich + markdown. Both false = plain single-font SkiaLabel (fastest, no emoji — plain label picks ONE font per label from the FIRST glyph, can't mix text+emoji).
• Backspace/delete on stub heads (Blazor/Net, no native control) must be grapheme-aware: SkiaEditor.CodeUnitsBeforeCaret/AfterCaret (via StringInfo text elements). Naive count=1 code-unit delete splits a surrogate-pair emoji → orphaned surrogate corrupts the string/markdown parser. MAUI unaffected (native EditText is grapheme-aware).
• Caret-over-shaped-text (2026-07 root fix): the caret maps CursorPosition→X by reading the line-span's POSITIONED glyph array LineSpan.Glyphs (LineGlyph[]). SkiaLabel.MeasureLineGlyphs used to return Glyphs=null for SHAPED runs (emoji/complex scripts) — text still rendered (shaper draws at paint time) but the caret had no positions → cursor stuck at 0 after typing/pasting emoji. Fix: when NeedsGlyphPositions (editors set it — normal labels DON'T, so their hot path is a single added bool check then the same width-only early-return, NO slowdown), MeasureLineGlyphs builds positioned LineGlyph[] from the SKShaper.Result via BuildGlyphsFromShaping.
• SKShaper.Result.Clusters are UTF-8 BYTE offsets, NOT UTF-16 char offsets (SkiaSharp feeds HarfBuzz UTF-8). The caret works in UTF-16 code units, so BuildGlyphsFromShaping must convert cluster byte offsets → char indices (Utf8ByteOffsetToCharIndex, Rune.Utf8SequenceLength). Not doing this made an all-emoji string report glyph0 spanning both emojis (clusters=0,4 → [s0+4] instead of [s0+2],[s2+2]) → line had 5 slots for 4 code units → caret landed at HALF the typed emojis. ASCII-prefix + trailing-emoji masks it (byte==char for ASCII, last glyph clamps to text.Length). Device-verified on Android via FastRepro + adb (adb shell input tap, logcat DOTNET tag, gated SkiaLabel.DebugCaret logging removed after).
• SkiaEditor.GetLineGlyphs flattens ALL font-run spans into ONE-ENTRY-PER-CODE-UNIT with line-absolute X (span glyph Position is span-relative; render adds cumulative span offsetX). is a code-unit offset, so a multi-unit glyph (surrogate emoji) must occupy as many caret slots as code units. Single-span ASCII takes a zero-alloc fast path.

SkiaShape stroke contracts the content clip (descender trap)

A stroked SkiaShape clips its CHILDREN to a stroke-inset path (CalculateClipSizeForStroke → shape inset + GetSmallUnderStroke + Ceiling/Floor). Small in px, but for TEXT it cuts glyph descenders (g/j/p) that overflow the font's metric line box — the visible cut is as big as the font's overshoot, so it looks large and is font/DPR-specific (only reproduces on the head whose font overshoots). Borderless shapes clip to the full rect (return destination) so the overflow shows; bordered ones cut it → symptom presents as "only stroked styles cut, and by a lot". Fix for a text-bearing shape: protected override SKRect CalculateClipSizeForStroke(SKRect d, float s) => d; (clip to full rect; border still draws via the shape path, Padding keeps text off the frame). Done on SkiaEditor 2026-07 for its Cupertino/Windows (bordered) styles. Base method is now virtual.

SkiaEditor (totally drawn text input)

• SkiaEditor : SkiaShape (namespace DrawnUi.Draw), source src/Shared/EditText/SkiaEditor.cs + per-platform partials (src/Maui/DrawnUi/Platforms/*/SkiaEditor.*.cs, Blazor, Net). Default UseCache = Operations set in constructor.
• Key properties: Text, PlaceholderText, PlaceholderColor, PlaceholderHorizontalAlignment, FontSize, FontFamily, TextColor, CursorColor, SelectionColor, MaxLines (1 = single-line), AutoHeight, IsPassword, ReturnType (MAUI enum, e.g. ReturnType.Send), KeyboardType, plus inherited SkiaShape visuals (CornerRadius, BackgroundColor, Padding).
• Chat-style growing input: MaxLines = 3, AutoHeight = true — starts 1 line tall, grows with actual rendered line count (word-wrap counted via Label.LinesCount, not just \n), caps at MaxLines then scrolls, shrinks back on delete. Ignored when HeightRequest set. Height self-heals next frame after label remeasure (UpdateViewportHeight runs each Paint with 0.5pt change guard). Verified headless (DrawnUi.Net HeadlessCanvasHost, 2026-06).
• Enter-to-send: multiline + ReturnType = ReturnType.Send → Enter submits (TextSubmitted/CommandOnSubmit, focus kept), Shift+Enter inserts line break, Alt+Enter soft break (Blazor/Net/OpenTk). Gate: ShouldSubmitOnEnter (shared). Default ReturnType.Done keeps Enter=newline — gate is strictly Send. ReturnType available on ALL targets incl. Blazor (shim enum src/Blazor/DrawnUi/Compat/ReturnType.Blazor.cs). Per-platform: Windows PreviewKeyDown intercept; Blazor/Net StubPressEnter(splitLine, shift); Android Control_EditorAction + multiline-Send uses SetRawInputType trick (Send IME key with multiline editing, NOT SetSingleLine(true)); Apple (hardware Shift+Enter NOT distinguishable there — Send always submits on "\n"). Full chat combo verified headless 2026-06: .

Gestures & Interaction

Two layers must BOTH be on, or handlers never fire: (1) canvas host input mode, (2) control-level handlers.

• Host: MAUI Canvas.Gestures = Enabled (normal interactive default), SoftLock (canvas inside a native ScrollView, cooperates), Lock (capture whole input stream — games/fullscreen). Blazor WASM: GesturesMode param, opt-in. Blazor Server: no param, control handlers still work. DrawnUi.Net headless: inject gestures yourself.
• Code-behind fluent event patterns (.OnTapped(), .OnLongPressing(), .WithGestures(...)): see drawnui-fluent skill.
• XAML tap handlers use Tapped="HandlerName" — when porting to code, replace with .OnTapped().
• Raw handling: ConsumeGestures — handler (object sender, SkiaGesturesInfo e); check e.Args.Type (TouchActionResult: Tapped/Panning/Up/Down/LongPressing/Cancelled), set e.Consumed = true to stop propagation. Keep the handler SYNCHRONOUS; offload async/animation via Task.Run inside.
• Gesture data: e.Args.Event.Distance.Delta (divide by control.RenderingScale for pts), .Distance.Total (swipe), .Location, .StartingLocation, NumberOfTouches.
• MVVM XAML attached props (any control): draw:AddGestures.CommandTapped, .CommandTappedParameter, .AnimationTapped="Scale|Ripple|Fade".
• Propagation: LockChildrenGestures (LockTouch: Disabled(default, pass all)/Enabled(consume all)/PassNone/PassTap/PassTapAndLongPress); BlockGesturesBelow=true stops touch reaching lower z-layers; InputTransparent makes the control ITSELF ignore input (not the things below it).
• Custom controls: override ProcessGestures(args, apply) — return this = consumed, null = pass; never consume Up unless required. Expand hitbox via CreateHitRect() override (inflate × RenderingScale). Layout gesture events: ChildTapped, .

Startup & Init

• MAUI: builder.UseDrawnUi(new DrawnUiStartupSettings { ... }). Settings: DesktopWindow (WindowParameters Width/Height/IsFixedSize — phone-like desktop window), UseDesktopKeyboard (KeyboardManager on Windows/MacCatalyst), MobileIsFullscreen (drop safe insets/status bar), Logger (ILogger consumed by Super.Log), Startup (Action<IServiceProvider> post-init hook).
• Blazor: await Super.UseDrawnUi(builder).WithBaseUrl(builder.HostEnvironment.BaseAddress).WithOptions(settings).ConfigureFonts(...).PreloadAssets(...).BuildAndRunAsync().
• .NET/OpenTK: Super.UseDrawnUi().ConfigureFonts(...).Build() ONCE before creating any canvas/window (BuildAsync() for async font loading).
• Fonts: fonts.AddFont("fonts/OpenSans-Regular.ttf", "FontText", FontWeight.Regular); emoji via NotoColorEmoji-Regular.ttf. Preload: assets.AddImage("bot.png", "images/bot.png").
• MAUI drawn assets live in Resources/Raw/** (NOT Resources/Images); filenames LOWERCASE — uppercase silently fails to load on iOS.
• Canvas.RenderingMode replaced the legacy HardwareAcceleration property. Current line = .NET 9 + SkiaSharp v3 (v1.3+); package renamed AppoMobi.Maui.DrawnUi → DrawnUi.Maui.
• Packages by host: DrawnUi.Maui / DrawnUi.Blazor.Wasm / DrawnUi.Blazor.Server / DrawnUi.Web (pure WASM — PackageId verified in csproj; docs pages saying "DrawnUi.Wasm" are stale) / DrawnUi.OpenTk(+.Game) / DrawnUi.Net (headless render, server-side image/PDF, offscreen layout validation).
• Debug/profiling toggles: Super.EnableRenderingStats, canvasView.FPS/FrameTime, control.DebugShowBounds, Super.ShowInvalidatedAreas, Super.MaxFps = 30 (iOS battery/heat cap).
• Super.DisplayException(this, e) renders an exception on the canvas — wrap InitializeComponent()/build code in it during development.

Invalidation & Custom Controls

• Update() = redraw + invalidate own cache; Repaint() = redraw WITHOUT destroying cache (position/transform changes); InvalidateMeasure() = size/layout recalc; if a parent refuses to refresh, Parent?.Invalidate().
• NEVER dispose SKBitmap/SKPicture/render objects mid-frame — control.DisposeObject(x) batches disposal safely at frame end.
• Custom drawing: override Paint(DrawingContext ctx) — ctx.Context.Canvas, ctx.Destination, ctx.Scale. Custom layout: override MeasureAbsolute/ArrangeChildren.
• Measure is NOT virtual — override OnMeasuring in custom controls.
• Custom composed control pattern: extend a layout, override CreateDefaultContent() with if (Views.Count == 0) AddSubView(CreateView()); guard; aggregate multi-property reactions into one MapProperties() called from propertyChanged callbacks.
• UI-not-updating checklist: VM implements INPC? property actually raises change (bindable property or OnPropertyChanged())? name matches nameof()? custom OnPropertyChanged override kept [CallerMemberName]?
• Fade-in image on load: subclass SkiaImage, override OnSuccess, set Opacity=0.01 then FadeToAsync(1).
• layout.ApplyItemsSource() forces ItemsSource rebuild. ViewsAdapter renames: GetViewForIndex→GetExistingViewAtIndex, GetViewAtIndex→GetOrCreateViewForIndex.

SkiaSharp v3/v4 API (DrawnUI pins 4.148+; v2-era snippets won't compile)

• SKPaint no longer carries filter quality: SKPaint.FilterQuality REMOVED. Pass SKSamplingOptions per draw call: canvas.DrawImage(img, rect, sampling, paint). DrawnUI helpers (DrawnUi.Draw): FilterQuality enum (None/Low/Medium/High/Ultra) + SkiaSamplingOptions.GetSamplingOptions(q) and presets NearestNoMip (1:1 blits), LinearNoMip, LinearLinear (smooth up/down-scale), MitchellCubic (best upscale), CatmullRomCubic (sharper, may ring). CachedObject.Draw overloads take in SKSamplingOptions.
• SKPaint no longer carries text state: Typeface, TextSize, TextAlign, MeasureText, GetTextPath etc. moved to SKFont. Draw text as canvas.DrawText(text, x, y, font, paint) — font geometry from SKFont, color/shader/stroke from SKPaint. Text AA via SKFontEdging on the font (SubpixelAntialias/Antialias — DrawnUI switches on Super.FontSubPixelRendering), not paint flags.
• SKSL scalar uniforms must be float, not float[1] (see drawnui-fluent shader section).

Caching Guidance

A control with an IPostRendererEffect NEVER blits from its cache

SkiaShaderEffect, SkiaBackdrop and anything else implementing IPostRendererEffect bypass the cached blit entirely. In SkiaControl.Shared.cs the draw path is literally if (EffectPostRenderers.Count == 0) { cache.Draw(...) } followed by foreach (var postRenderer in EffectPostRenderers) postRenderer.Render(context); — so when the list is non-empty the cache is NOT drawn and the effect re-executes every frame: build uniforms, Compiled.ToShader(...), DrawRect, then Canvas.Flush(). A Canvas.Flush() per effect per frame is a GPU pipeline stall, so the cost scales with the NUMBER of shader-carrying controls on screen and is nearly independent of how simple the SKSL is.

Consequences, all verified from source:

• Never remove an image cache from a control that carries a shader effect. GetPrimaryTextureImage (mode Always, the default) returns Parent?.CachedImage when present, and otherwise falls back to CreateSnapshot = Canvas.Flush() + Surface.Snapshot() EVERY frame. The cache on such a control is not a redundant "nested cache" — it is the effect's input texture. Removing it makes the control dramatically more expensive, not cheaper.
• N live shader-carrying controls on one screen is an N-stall-per-frame design. A filter-picker strip of live shader thumbnails over a camera preview measured 60fps → 36fps (+11ms/frame) for ~8 visible thumbs on a high-end Windows GPU. Hiding the strip restored 60fps.
• If the shaded content changes far slower than the frame rate, do not use a live effect at all. Bake the shaded result into an SKImage once per content change and show it in a plain cached SkiaImage with no VisualEffects. Thumbnails refreshed every few seconds must never re-run their shader 60 times a second.
• UseBackground = PostRendererEffectUseBackgroud.Once freezes the input snapshot (removing the per-frame Surface.Snapshot) but the Render still runs per frame — it is a mitigation, not a fix.
• Diagnosing: FPS drops proportional to how many shader-carrying controls are VISIBLE, and does not improve when you switch to a simpler shader. That signature means per-frame effect dispatch, not shader cost.

Group before you cache (layer grouping)

Caching is a decision about SUBTREES, not about individual controls. Scattered siblings sitting over a surface that repaints every frame (camera preview, GL scene, video, animated canvas) are traversed and drawn ONE BY ONE on every frame even when each of them is individually cached — the parent still walks them, applies transforms and blits N times. Wrap such a set of controls in ONE container (SkiaLayer for overlay/absolute, SkiaStack/SkiaRow/SkiaGrid where the arrangement demands it) and cache THAT container: the live surface then pays a single blit per frame.

Applies to: camera/GL overlays (shutter row, top bar, badges, HUD), static app chrome over any animated content, side panels, toolbars.

Pick the cache type by the GROUP's size and its own change rate:

• small / medium group, redraws relatively often on state change → GPU (GPU-resident bitmap, blit with no re-upload)
• large / near-fullscreen group → Operations (recorded draw commands, avoids holding a huge bitmap; also the safe choice when memory matters more than blit cost)
• large group, visually static, memory budget fine → Image
• group whose children change INDEPENDENTLY of each other (document/artboard/HUD with separate live readouts) → ImageComposite (re-records only the dirty child)
• any child inside the group that repaints EVERY frame does not belong in the group — pull it out as a sibling with no cache, so it never dirties the whole layer

Constraints when grouping: keep the GPU cache at the TOP grouped container, never nested inside another GPU-cached/GPU-rendered subtree; never put Operations above a GPU-cached child (GRContext change can crash); once the group is cached, descendants usually stay uncached by omission unless they have their own separate reuse case.

• Omitted UseCache means the CONTROL'S OWN default, which is NOT always None — see the defaults table below. Layouts, SkiaImage and SkiaButton do default to None, so for those treat caching as opt-in, added only where reuse value is clear.

Default	Controls
Operations	SkiaLabel, SkiaShape, SkiaSvg, SkiaEditor, SkiaScrollBar, SkiaSpriteSet (needs Left+Top), SkiaWheelPickerCell
OperationsFull	SkiaHoverMask
ImageDoubleBuffered	SkiaLottie, SkiaGif, SkiaSlider, SkiaProgress*
Image	SkiaWheelShape, SkiaRadioButton*
None	SkiaSprite, SkiaCachedStack (owns its own plane cache), layouts, SkiaImage, SkiaButton (its intended OperationsFull is disabled behind a todo)

* set in CreateDefaultStyleContent(), so it applies to the default look only — a custom-templated SkiaProgress/SkiaRadioButton gets no cache. All others are set in the constructor.

Conditional: AutoCache on SkiaScroll/SkiaDrawer sets THEIR OWN UseCache = Operations once Content exists — deliberate exception to "never cache a scroll".

• No cache, UseCache="None": use when subtree is cached and you don't need to cache more. Or if the control is will be updating with new content with frequency close to canvas fps. - GPU-backed cache should preferably live at top cached container, not nested deeper in subtree. Nested GPU cache is possible only when you explicitly know that case is safe and beneficial.
• UseCache="GPU": use when layer is worth being stored as a GPU-backed bitmap. Best for small overlays with high frequency of redrawing, prefer small top overlays.
• UseCache="Image": use when layer is worth being stored as a CPU-bitmap and redrawn from it later instead of recalculations/logical paintings.
• UseCache="Operations" will be stored as drawing commands. Must never be used over any child below having GPU tye of cache - might crash if GRContext changes. Useful for small vector-based controls or large animated containers to avoid storing large bitmaps.
• Decide caching from both subtree cost and parent redraw frequency. Over live surfaces that repaint every frame, even small overlay controls can benefit from top-level cache if their own visuals are mostly stable between state changes.
• Simple capture buttons over live camera preview can justify top-level cache because camera invalidation would otherwise force subtree traversal and redraw every frame.
• Frequently mutating does not automatically mean no cache. First ask what causes redraws: parent surface every frame, or subtree visuals themselves every frame. Cache helps in first case if subtree is stable; cache often loses in second case.
• If parent cache already captures the whole reusable subtree, descendants commonly stay non-cached by omission unless they have their own separate reuse case.
• If visual bug or native crash appears, inspect cache placement first.

Cache machinery (only when debugging the cache system itself)

• UseCache is what you set, UsingCacheType is what runs (Draw/Base/SkiaControl.Cache.cs:555-604), resolved in order: (1) !AllowCaching || !Super.CacheEnabled → None; (2) if CanUseCacheDoubleBuffering && Super.Multithreaded: None→OperationsFull, ImageDoubleBuffered/GPU→Image, ImageComposite/ImageCompositeGPU→Operations; (3) ImageDoubleBuffered && !CanUseCacheDoubleBuffering→Image; (4) GPU/ImageCompositeGPU without Super.GpuCacheEnabled→Image/ImageComposite; (5) None + double-buffering + Multithreaded + parent is SkiaControl → Operations; (6) else UseCache. Nothing overrides UsingCacheType — customize via CanUseCacheDoubleBuffering/AllowCaching. Code branches on IsCacheComposite/IsCacheImage/IsCacheGPU, not enum equality: a new cache type must be added to all three plus both CreateRenderingObject paths. SkiaCacheType.Auto is declared but never implemented (zero references).
• Globals (Super.cs): CacheEnabled (true, master off-switch), GpuCacheEnabled (true), Multithreaded (false, experimental — set OffscreenRenderingAtCanvasLevel true alongside it).
• Offscreen bakes are NOT Task.Run: OffscreenRenderingService runs Clamp(ProcessorCount/2, 2, 4) dedicated AboveNormal threads, because on the shared threadpool latency-critical bakes queue behind app startup work and the pool grows only ~1 thread/500 ms. On WASM they drain INLINE instead (see drawnui-blazor skill).
• CacheValidityType { Valid, Missing, SizeMismatch, GraphicContextMismatch } — GraphicContextMismatch = GRContext handle changed (app background→foreground kills every GPU-backed cache).
• on the OLD when its surface is transferred to a new one (ImageComposite / double-buffer swap) so its Dispose skips the now-shared surface. Getting it wrong = "black/empty render right after a cache swap".

ImageDoubleBuffered semantics + blank-blink mechanism (fixed 2026-07)

• ImageDoubleBuffered NEVER paints sync: missing/unusable cache → DrawPlaceholder() (default no-op = EMPTY) + async bake on the per-control offscreen queue (LimitedQueue(1), latest wins). Sync-create-when-missing is Image cache behavior only.
• Fallback design: invalidation sends front RenderObject → RenderObjectPrevious, which draws while rebake lands. BUT DestroyRenderingObject() also sets RenderObjectPreviousNeedsUpdate = true (poison) → next draw KILLS previous before the draw decision → nothing drawable → blank frames until bake. Poison is correct ONLY for recycled rebinds (stale pixels = wrong content).
• Historic blink triggers (both fixed in lib): (1) InvalidateMeasureInternal hard-destroyed on ANY remeasure REQUEST — even same resulting size (e.g. SkiaImage bitmap arrival) — now for ImageDoubleBuffered keeps front + NeedUpdateFrontCache=true; (2) SkiaDynamicDrawnCell.AttachContext destroyed on every rebind — now gated by protected virtual bool DestroyCacheOnContextChange => true (override to false in non-recycled cells like chat: stale pixels 1-2 frames beat blank).
• Actual size change: size-mismatch branch in UseRenderingObject refuses stale-size cache (no stretch); lib now sync re-records at the new size (TrySyncRebuildStaleSize, guarded by _offscreenBakeBusy so it never paints concurrently with a bake). Fires only on resize of an already-cached control — cold cells stay async (zero-spike scroll preserved).
• Debug tell: content shows OK, then EMPTY, then OK again = destroy-then-async-rebake window, not "cache not ready".

Shared cache per control TYPE (CacheSharing)

• CacheSharing = CacheSharingType.Shared (SkiaControl.Cache.cs): all instances of the SAME control type on the same Canvas share ONE CachedObject instead of each allocating their own. Eligible cache types: Operations, Image, GPU (per IsSharedCacheEligible; the XML doc says Image/GPU only — code includes Operations too).
• Pattern: create a dedicated subclass with FIXED identical visuals baked into the constructor, e.g. class IncomingBubbleSign : SkiaShape (polygon points, color, size, UseCache=Image, CacheSharing=Shared). Thousands of recycled-list cells each hold their own instance, but physically one cache surface is rendered once and blitted everywhere. Example: chat bubble deco-triangle tails as IncomingBubbleSign/OutcomingBubbleSign subclasses shared by all cells.
• Constraint: instances MUST be visually identical (same size/colors/content) — the cache is keyed by type, any per-instance visual difference would show the wrong pixels.
• Disposal: individual control disposal does NOT release the shared cache; free via SuperView.Cache.Free<T>() or let the Canvas dispose it.
• Composes with IsGhost (occupies layout, not drawn) — e.g. ghost tails keep bubble alignment in follow-up messages of a same-sender group while only group-first messages draw the shared tail.

Shader Effects (SkiaShaderEffect / SkiaBackdrop)

• Use ShaderCode (inline SKSL string) instead of ShaderSource (file path) on the DRAWNUI_NET / OpenTK target — LoadFromResources throws there. ShaderCode bypasses file loading entirely and compiles the string directly.
• SkiaBackdrop + VisualEffects + a SkiaShaderEffect subclass (e.g. GlassBackdropEffect) works on the OpenTK target. The backdrop snapshots ctx.Context.Surface which is the same GPU framebuffer used by raw GL — so GL-drawn content (cube, 3D scene) IS captured and passed to the shader as iImage1.
• For liquid glass over a GL scene: place SkiaBackdrop as the first child inside the SkiaShape panel. Do NOT put GPU cache (UseCache = GPU) on the outer shape — that caches the backdrop snapshot and prevents live updates each frame.
• Match GlassBackdropEffect.CornerRadius to the parent SkiaShape.CornerRadius (in points, not pixels — the effect multiplies by RenderingScale internally).
• SkiaBackdrop.Blur = 0 when using a custom shader effect — the shader handles its own blur.

Shader slide transitions (SkiaShaderCarousel / ShaderTransitionEffect)

• SkiaShaderCarousel (DrawnUi.Controls): SkiaCarousel subclass where slides never translate — an attached ShaderTransitionEffect (a ShaderDoubleTexturesEffect adding progress + ratio uniforms) blends the from/to cells' cached images. Give it a gl-transitions style transition(vec2 uv) via TransitionShader (Resources/Raw path), TransitionShaderCode (raw SkSL string — required on OpenTK/DRAWNUI_NET and in the fiddle), or a custom TransitionTemplate. Cell templates MUST use UseCache = Image (the effect samples cell RenderObject caches); ctor forces RecyclingTemplate.Disabled.
• InterruptedTransitionMs (default 50): a swipe during a running transition wraps the current transition up in ~that time, then plays the next. Gesture targeting is deterministic: max ONE slide per gesture, direction from velocity (threshold 100) or displacement, target computed from the gesture-origin snap — never from nearest-to-finger.
• Custom effect subclass: override protected virtual ShaderTransitionEffect CreateTransitionEffect() — called once from ctor; effect is attached lazily on first Render.
• AspectFit letterboxed slides (photo viewer case): the shader spans the whole cell, so e.g. the cube transition's reflection projects at SCREEN bottom instead of under the photo. Fix = a band-clipped effect subclass: (1) override Render, intersect ctx.Destination with the union of from/to inner SkiaImage.DisplayRect, call base.Render(ctx.WithDestination(clipped)); (2) override SyncEngineState and set GetEngine().Offset to the clipped destination origin (base sets it to TEXTURE bounds origin, so uv would not be [0,1] over the band); (3) cell textures stay full-size, so remap sampling in a custom template: getFromColor/getToColor sample (uBandOffset + float2(uv.x, 1.0-uv.y) * uBandScale) * uTexResolution with those uniforms added in CreateUniforms (band rect vs stored textureBounds ratios). NB iResolution AND iImageResolution are both destination-sized (engine.CreateUniforms(destW, destH, destW, destH)) — after clipping they are band-sized, so the full texture pixel size needs its own uniform.
• Single-texture variant of the same hack: — only intersect destination with , no remap needed, because with the snapshot is taken FROM the clipped destination, so texture == band content exactly.

Visual Structure

• For custom shutter/camera buttons, prefer composed SkiaShape outer ring + inner shape/disc.
• Use ZIndex for overlays above camera/content.
• Keep bottom controls in dedicated overlay container when alignment inside mixed layered content becomes unstable.

Runtime Checks

• If UI exists but looks wrong, verify: parent layout, HorizontalOptions, VerticalOptions, Margin, ZIndex, clipping, cache placement.
• If control not visible, verify it is inside DrawnUI content tree, not hidden behind another layer, and parent fills available space.
• If touch does not fire, verify gesture/tap handler is on interactive outer control and no blocking overlay sits above it.

On-device (Android) runtime validation

• Frame smoothness ground truth: real gestures via adb shell input swipe + adb shell dumpsys gfxinfo <pkg> reset / dump — the accelerated DrawnUi canvas goes through Choreographer. CAVEAT: gfxinfo only measures frames that were SUBMITTED — a blocked render loop produces no frame at all, so multi-100ms stalls are INVISIBLE in its percentiles (observed: p99=15ms while a WasDrawn-gap probe showed 300ms+ holds). Always pair gfxinfo with an offset/frame-gap probe on DrawnView.WasDrawn. Do NOT judge smoothness from SkiaScroll.Scrolled events (sparse, not per-frame) or from repaint counts at rest.
• Offscreen double-buffer bakes run on DEDICATED worker threads (OffscreenRenderingService in SkiaControl.Cache.cs), NOT Task.Run: on the shared threadpool, startup bakes queued behind app tasks and the ~1-thread/500ms injection rate made cold cells materialize one by one over seconds.
• DrawPlaceholder (cold ImageDoubleBuffered cell awaiting first bake) is an EMPTY virtual — override it for skeleton UX. Two verified traps: it can run BEFORE the cell is bound (BindingContext null — provide a neutral fallback), and it paints in a pass WITHOUT the control's own Rotation transform (a 180°-rotated chat cell needed mirrored alignment: outgoing=Left in placeholder space to appear right on screen).
• Per-frame managed hook: DrawnView.WasDrawn fires for every drawn frame (subscribe via MainScroll.Superview). Note: frames also fire while offset is stationary (loads/measure repaints) — filter by offset delta if measuring scroll cadence.
• net10-android Console.WriteLine lands in logcat tag DOTNET (not mono-stdout).
• Build config per bug class: STRUCTURAL/correctness bugs -> Debug builds (minutes-faster deploy cycle, no AOT); Release only when validating performance/feel or GC/timing-sensitive behavior. Never burn Release AOT cycles on a structural repro.
• Bound every device wait: am start can fail silently — verify pidof within ~15s, and give every logcat-marker poll a deadline instead of an unbounded until-loop.
• Explicit concurrent copying GC lines in logcat ≈ managed (Mono bridge) full GCs — one per second during scroll means allocation pressure in the draw path; correlate with GC.GetTotalAllocatedBytes per frame.
• Switchable in-app auto-test driver pattern: shared partial (e.g. ChatPage.AutoTest.cs) with a single public static bool AutoTestEnabled = false flag + partial void MaybeStartAutoTest() called at init; driver logs and the app stays fully normal when the flag is off.

Ordered ScrollToIndex semantics (MeasureVisible)

• An OrderedScrollToIndex is HELD until ARRIVAL, not until issue: while pending it gates LoadMore for the whole animated flight, re-aims if content resizes mid-travel, re-issues on stall (≤2) then accepts, and is cancelled by user touch (Down). Under MeasureVisible it also waits until LastMeasuredIndex >= target and kicks KickBackgroundMeasurement() when measurement is idle — never resolve a jump against estimated extents.
• Background measurement invariants: only the current pass may clear _isBackgroundMeasuring (generation/cts identity check — a stale task's finally must not clobber it), and the measure loop must not break on its OWN staged BackgroundMeasurement changes (only on real structure mutations), else it starves to one batch per draw.

Visual Effects (VisualEffects, shadows, glow)

• Every SkiaControl has a VisualEffects collection (IList<SkiaEffect>). Effects: IImageEffect (SKImageFilter), IColorEffect (SKColorFilter), IRenderEffect/BaseChainedEffect (wrap paint), IPostRendererEffect (after paint, shaders/backdrop), IStateEffect, ISkiaGestureProcessor.
• Built-in shadows: DropShadowEffect (Blur=sigma, X/Y offset in points, Color), OuterGlowEffect (symmetric, no offset), ChainDropShadowsEffect (collection of SkiaShadow for multi-shadow).
• Shadows/glow paint OUTSIDE DrawingRect. When a control is cached, the cache surface + clip are bounds-sized → shadow would be clipped. DrawnUI auto-expands cache/clip/dirty-region so this works. Do NOT require ExpandDirtyRegion for built-in shadow/glow — attach effect and it shows, cached or not.
• Mechanism: SkiaEffect.GetEffectMargin(float scale) returns per-side overflow in PIXELS (default Thickness.Zero). Control aggregates per-side max into EffectsMarginPixels (cached; recomputed on effect add/remove/replace or param/scale change via InvalidateEffectsMargin, which also invalidates cache). Three sites consume it through GetRenderingExpandPixels(): GetCacheArea (surface), DrawWithClipAndTransforms clip, and DrawingRect→DirtyRegion.
• Shadow margin = 3 * Blur per side (+offset for DropShadow). 3σ matches Skia's own blur filter bounds (ceil(3*sigma)); beyond that alpha <0.3%. SkiaSharp does not bind computeFastBounds, so this is computed in managed code — same result for Gaussian blur.
• Blur is treated as PIXELS (don't scale it); offsets (X/Y) are points (scale them). Mirror in custom effects.
• Legacy SkiaShape.Shadows (SkiaShadow list) and MAUI Shadow (PlatformShadow) are ALSO wired into this expansion (2026-07): base ComputeEffectsMargin merges PlatformShadow; SkiaShape.ComputeEffectsMargin override merges Shadows (skipped when PlatformShadow present — mirrors paint precedence). Legacy SkiaShadow sigma = (scaled, unlike effects' pixel Blur) → margin per side . No wrappers or reserved padding for shadowed cached shapes; layout size stays shadow-free by design (CSS/Android convention). A/B harness proof: cached 40pt circle, Blur 8 / Y 12 → 0 shadow px below rect without the merge, 324 with.

OpenTK / Mixed GL+DrawnUI

Trigger: CanvasHost, DrawnUiWindow, RenderScene(), overlay on 3D scene, mixing GL and Skia, cube/mesh invisible while background shows, GL state corruption symptoms.

Problem: Skia does NOT restore GL state after compositing on a shared framebuffer/context. Left dirty: GL_VIEWPORT (Skia's internal coords → your geometry maps off-screen), GL_STENCIL_TEST enabled (all fragments fail stencil → nothing draws), glDepthMask(false) (GL.Clear(DepthBufferBit) no-ops → stale depth corrupts tests), partial color mask. Symptom: clear color visible, 3D geometry invisible; first frame fine, breaks from second frame on.

Fix — two-way contract, BOTH sides required:

// BEFORE your GL draw, every frame — restore what Skia left dirty:
GL.Viewport(0, 0, clientWidth, clientHeight);
GL.Disable(EnableCap.StencilTest);
GL.DepthMask(true);
GL.ColorMask(true, true, true, true);
GL.ClearColor(r, g, b, 1f);
GL.Clear(ClearBufferMask.ColorBufferBit | ClearBufferMask.DepthBufferBit | ClearBufferMask.StencilBufferBit);
GL.Enable(EnableCap.DepthTest);
// ... your draw calls ...
GL.Finish();

// AFTER your GL draw, before Skia renders — tell Skia its cached VAO/program/state is stale:
grContext.ResetContext();   // CanvasHost: _host.ResetGrContext()

• CanvasHost (overlay over your own GameWindow): restore block → draw scene → GL.Finish() → _host.ResetGrContext() → _host.Render() → SwapBuffers(). Canvas must use RenderingMode = RenderingModeType.AcceleratedRetained + BackgroundColor = Colors.Transparent so Skia doesn't clear the framebuffer before compositing.
• DrawnUiWindow base: RenderDrawnUi() already contains the restore block + ResetContext() — just override RenderScene() (enable depth test, draw, end with GL.Finish()).
• Same class of issue applies to any 2D-over-GL compositor (SkiaSharp raw, Flutter embedding, ImGui, NanoVG).

OpenTK raw assets (Images / Lottie / fonts) — output-dir relative

OpenTK has NO MAUI asset pipeline. A source string like "Images/banana.gif" / SkiaLottie.Source="Lottie/x.json" resolves relative to the OUTPUT dir (next to the exe). The asset MUST be copied there via Content + CopyToOutputDirectory:

<Content Include="Images\**"><CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory></Content>

Gotcha (the #1 "asset won't load" cause): a bare <Content Include="Images\x.gif" /> in a WinExe/console SDK project is NOT copied by default — build succeeds, file shows in IDE, but runtime can't find it and it silently fails to render. Always add CopyToOutputDirectory="PreserveNewest"; verify with ls bin/Debug/<tfm>/Images. Per-head asset roots differ: OpenTK = output dir, MAUI = Resources/Raw/**, Web = wwwroot/** — keep the asset in every head you ship. OpenTkPong.csproj is the reference pattern. Docs: docs/articles/opentk/resources.md. NEVER assume an asset loads on a head without verifying it lands in that head's asset root.

DrawnUi.Web (pure WebAssembly, no Blazor)

Package DrawnUi.Web — DrawnUI in the browser as a standalone pure-WASM app. NOT Blazor: only [JSImport]/[JSExport] interop, no IJSRuntime/ElementReference/Razor. Built on the DRAWNUI_NET base (SharedNet + Net shims, same base as OpenTK), NOT the Blazor DrawnUi.Blazor.Core partials. Source: src/Web/DrawnUi.Web/. Docs: docs/articles/web/index.md + getting-started.md.

• Entry: Super.UseDrawnUi().ConfigureFonts(...).ConfigureStyles(...).RunAsync("canvas-id", () => new Canvas { ... }). RunAsync(elementId, factory) (BrowserHost.RunAsync) wires rendering, input, requestAnimationFrame loop, resize, fonts, gestures.
• Canvas.RenderingMode: Accelerated = WebGL (GPU, auto-falls back to raster), Default = raster (putImageData). RenderingMode must be final BEFORE AttachCanvasView (host handles this) — changing it after attach disposes the view and kills the loop.
• Host shape: static index.html with one <canvas id="drawnui-canvas"> (set touch-action:none) + main.js loader importing ./_content/DrawnUi.Web/drawnui-web.js; csproj uses Microsoft.NET.Sdk.BlazorWebAssembly SDK + WasmBuildNative=true + SkiaSharp.NativeAssets.WebAssembly + HarfBuzzSharp.NativeAssets.WebAssembly; DefineConstants include DRAWNUI_NET;WEB;BROWSER.