drawnui-react 0.1.0-preview.1

package/dist/core/SkiaEffect.js

@@ -0,0 +1,571 @@
+import { SkiaValueAnimator } from "./Animators";
+import { Easing } from "./Easing";
+import { SkiaImageManager } from "./SkiaImageManager";
+import { Super } from "./Super";
+import { Thickness } from "./Types";
+/**
+ * Mirrors DrawnUi SkiaEffect: something attached to a control through `VisualEffects`. `Update()` re-renders the
+ * parent (C# invalidates the parent's cache and redraws), `GetEffectMargin` reports what it paints outside the box.
+ */
+export class SkiaEffect {
+    /** Set by Attach/Dettach. */
+    Parent;
+    Tag;
+    Attach(parent) { this.Parent = parent; }
+    Dettach() { this.Parent = undefined; }
+    /** Cached resources must be dropped here, not on the next draw (C# contract). */
+    OnDisposing() { }
+    Dispose() { this.OnDisposing(); this.Parent = undefined; }
+    /** Effect parameters changed: the parent's cache is re-recorded and the composition redrawn (C# Parent.Update). */
+    Update() {
+        const p = this.Parent;
+        if (!p)
+            return;
+        p.InvalidateEffectsMargin();
+        p.InvalidateCache();
+        p.RepaintComposition();
+    }
+    /** Extra space in PIXELS painted beyond the parent's DrawingRect. */
+    GetEffectMargin(_scale) { return Thickness.Zero; }
+    get NeedApply() { return this.Parent !== undefined; }
+}
+export function IsPostRendererEffect(e) {
+    return typeof e.Render === "function" && "UseBackground" in e;
+}
+/** Runtime effects compiled once per source text (C# SkSl cache per resource name). */
+const compiledCache = new Map();
+/** Shader files fetched once per url. */
+const sourceCache = new Map();
+/**
+ * Mirrors DrawnUi SkiaShaderEffect: an SkSL fragment shader (`ShaderSource` url or inline `ShaderCode`, optionally
+ * wrapped by a `ShaderTemplate` at `//script-goes-here`) drawn over the parent control with the Shadertoy-style
+ * uniforms `iResolution`, `iImageResolution`, `iTime`, `iOffset`, `iMouse` and the parent's own output as the
+ * `iImage1` texture (`UseBackground` Always / Once / Never, `AutoCreateInputTexture`). Extra uniforms through
+ * `SetUniform`, extra textures by overriding `CreateTexturesUniforms`. Uniforms not declared by the shader are
+ * skipped, declared texture children that are not supplied sample transparent.
+ */
+export class SkiaShaderEffect extends SkiaEffect {
+    /** Url of the .sksl file (fetched once, compiled once per text). */
+    get ShaderSource() { return this.shaderSource; }
+    set ShaderSource(v) { if (this.shaderSource !== v) {
+        this.shaderSource = v;
+        this.ApplyShaderSource();
+    } }
+    /** Inline SkSL, used when ShaderSource is not set. */
+    get ShaderCode() { return this.shaderCode; }
+    set ShaderCode(v) { if (this.shaderCode !== v) {
+        this.shaderCode = v;
+        this.ApplyShaderSource();
+    } }
+    /** Url of a template .sksl whose `//script-goes-here` is replaced by the shader. */
+    get ShaderTemplate() { return this.shaderTemplate; }
+    set ShaderTemplate(v) { if (this.shaderTemplate !== v) {
+        this.shaderTemplate = v;
+        this.ApplyShaderSource();
+    } }
+    /** Snapshot the surface being drawn (true) or the on-screen one. */
+    UseContext = true;
+    /** Create the `iImage1` texture from the parent's output; false for output-only shaders. */
+    AutoCreateInputTexture = true;
+    UseBackground = "Always";
+    AquiredBackground = false;
+    BlendMode = "SrcOver";
+    FilterMode = "Linear";
+    MipmapMode = "None";
+    /** Tile mode of the input textures. */
+    TileMode = "Clamp";
+    /** Set every Render from the frame time (seconds); can be driven manually. */
+    TimeSeconds = 0;
+    /** Shadertoy iMouse.xy, pixels relative to the control. */
+    MouseCurrent = { X: 0, Y: 0 };
+    /** Shadertoy iMouse.zw: where a drag started, zero = not dragging. */
+    MouseInitial = { X: 0, Y: 0 };
+    /** Custom uniforms by name (float arrays sized like the SkSL type), merged on top of the standard ones. */
+    Uniforms = new Map();
+    /** Compilation errors land here; without a handler they are logged. */
+    OnCompilationError;
+    /** Code as loaded/assembled for the last compile. */
+    LoadedCode = "";
+    shaderSource = "";
+    shaderCode = "";
+    shaderTemplate = "";
+    compiled;
+    compiledKey = "";
+    uniformSlots = new Map();
+    uniformFloats = 0;
+    childNames = [];
+    hasNewShader = true;
+    compileFailed = false;
+    loading;
+    loadedSource;
+    loadedTemplate;
+    textureShader;
+    frozen;
+    frozenOwned = false;
+    paint;
+    get IsCompiled() { return this.compiled !== undefined; }
+    /** C# NeedApply && IsCompiled; the compile itself is attempted here (sync once the source is loaded) so a fresh effect gets its first chance before the render decides between the plain blit and the shader. */
+    get NeedApply() { return super.NeedApply && this.EnsureCompiled(); }
+    /** Loads (async, once) and compiles (sync) when needed; true when a compiled effect exists. */
+    EnsureCompiled() {
+        if (!this.EnsureLoaded())
+            return false;
+        if ((this.hasNewShader && !this.compileFailed) || (!this.compiled && !this.compileFailed)) {
+            this.hasNewShader = false;
+            this.CompileShader();
+        }
+        return this.compiled !== undefined;
+    }
+    // ---- uniforms API (C# SetUniform overloads) ----
+    SetUniform(name, ...values) {
+        if (name && values.length > 0) {
+            this.Uniforms.set(name, values);
+            this.Update();
+        }
+        return this;
+    }
+    ReleaseFrozenSnapshot() {
+        if (this.frozenOwned && this.frozen)
+            this.DisposeImage(this.frozen.Image);
+        this.frozen = undefined;
+        this.frozenOwned = false;
+    }
+    DisposeImage(image) {
+        const sv = this.Parent?.Superview;
+        if (sv)
+            sv.DisposeObject({ Dispose: () => image.delete() });
+        else
+            image.delete();
+    }
+    ApplyShaderSource() {
+        this.hasNewShader = true;
+        this.compileFailed = false;
+        this.Update();
+    }
+    // ---- textures ----
+    /** Snapshot of what the parent painted (C# CreateSnapshot): the surface the pixels are on, mapped through its origin. */
+    CreateSnapshot(ctx, destination) {
+        const surface = this.UseContext ? ctx.Context.Surface : this.Parent?.Superview?.Surface;
+        if (!surface)
+            return undefined;
+        surface.flush();
+        const origin = this.UseContext ? ctx.Context.Origin : undefined;
+        const ox = origin?.X ?? 0, oy = origin?.Y ?? 0;
+        // whole-surface snapshot: a bounded snapshot of a GPU surface is not origin-safe in CanvasKit; the texture shader
+        // gets a local translation so its texel (0,0) is the destination's top-left
+        const image = surface.makeImageSnapshot();
+        if (!image)
+            return undefined;
+        return { Image: image, Bounds: destination, Origin: { X: ox, Y: oy } };
+    }
+    /** C# GetPrimaryTexture: the parent's cache, a frozen snapshot (Once) or nothing (Never). */
+    GetPrimaryTexture(_ctx, _destination) {
+        switch (this.UseBackground) {
+            case "Never": return undefined;
+            case "Once":
+                if (!this.AquiredBackground || !this.frozen) {
+                    this.ReleaseFrozenSnapshot();
+                    let snapshot = this.Parent?.CachedImage;
+                    let owned = false;
+                    if (!snapshot && this.AutoCreateInputTexture) {
+                        snapshot = this.CreateSnapshot(_ctx, _destination);
+                        owned = true;
+                    }
+                    if (snapshot) {
+                        this.frozen = snapshot;
+                        this.frozenOwned = owned;
+                        this.AquiredBackground = true;
+                    }
+                }
+                return this.frozen;
+            default:
+                return this.Parent?.CachedImage;
+        }
+    }
+    /** Image → shader with the effect's sampling, translated so texel (0,0) = bounds top-left; cached per image. */
+    CreateTextureShader(texture) {
+        const CK = Super.CK;
+        // texel (0,0) must land on the texture's top-left: a snapshot of a whole surface is shifted by where that top-left is
+        const dx = texture.Origin ? texture.Bounds.Left - texture.Origin.X : 0, dy = texture.Origin ? texture.Bounds.Top - texture.Origin.Y : 0;
+        const key = `${this.FilterMode}|${this.MipmapMode}|${this.TileMode}|${dx},${dy}`;
+        const c = this.textureShader;
+        if (c && c.image === texture.Image && c.key === key)
+            return c.shader;
+        c?.shader.delete();
+        const tile = CK.TileMode[this.TileMode] ?? CK.TileMode.Clamp;
+        const fm = this.FilterMode === "Nearest" ? CK.FilterMode.Nearest : CK.FilterMode.Linear;
+        const mm = this.MipmapMode === "Linear" ? CK.MipmapMode.Linear : this.MipmapMode === "Nearest" ? CK.MipmapMode.Nearest : CK.MipmapMode.None;
+        const local = dx !== 0 || dy !== 0 ? CK.Matrix.translated(-dx, -dy) : undefined;
+        const shader = texture.Image.makeShaderOptions(tile, tile, fm, mm, local);
+        this.textureShader = { image: texture.Image, key, shader };
+        return shader;
+    }
+    /** Texture children by name (C# CreateTexturesUniforms). Override to add `iImage2` etc. */
+    CreateTexturesUniforms(_ctx, _destination, primaryTexture) {
+        return { iImage1: primaryTexture };
+    }
+    /** Standard uniforms + `Uniforms` (C# CreateUniforms). Override, call super and add your own with `Set`. */
+    CreateUniforms(destination, textureBounds, values) {
+        this.Set(values, "iResolution", destination.Width, destination.Height);
+        this.Set(values, "iImageResolution", destination.Width, destination.Height);
+        this.Set(values, "iTime", this.TimeSeconds);
+        // iOffset is where the texture starts on screen: shaders sample (fragCoord - iOffset)
+        this.Set(values, "iOffset", textureBounds?.Left ?? destination.Left, textureBounds?.Top ?? destination.Top);
+        this.Set(values, "iMouse", this.MouseCurrent.X, this.MouseCurrent.Y, this.MouseInitial.X, this.MouseInitial.Y);
+        for (const [k, v] of this.Uniforms)
+            this.Set(values, k, ...v);
+    }
+    /** Writes a uniform by name into the flat float array; undeclared names are skipped like C#. */
+    Set(values, name, ...v) {
+        const u = this.uniformSlots.get(name);
+        if (!u)
+            return;
+        const n = Math.min(u.count, v.length);
+        for (let i = 0; i < n; i++)
+            values[u.slot + i] = v[i];
+    }
+    // ---- compilation ----
+    static async FetchText(url) {
+        let p = sourceCache.get(url);
+        if (!p) {
+            p = fetch(url).then((r) => { if (!r.ok)
+                throw new Error(`${r.status} ${url}`); return r.text(); });
+            sourceCache.set(url, p);
+        }
+        return p;
+    }
+    /** Fetches ShaderSource / ShaderTemplate when needed; true when the code is ready to compile. */
+    EnsureLoaded() {
+        const needSource = this.shaderSource && this.loadedSource?.url !== this.shaderSource;
+        const needTemplate = this.shaderTemplate && this.loadedTemplate?.url !== this.shaderTemplate;
+        if (!needSource && !needTemplate)
+            return true;
+        if (this.loading)
+            return false;
+        const src = this.shaderSource, tpl = this.shaderTemplate;
+        this.loading = (async () => {
+            try {
+                if (needSource)
+                    this.loadedSource = { url: src, code: await SkiaShaderEffect.FetchText(src) };
+                if (needTemplate)
+                    this.loadedTemplate = { url: tpl, code: await SkiaShaderEffect.FetchText(tpl) };
+                this.hasNewShader = true;
+                this.compileFailed = false;
+            }
+            catch (e) {
+                this.compileFailed = true;
+                this.SendError(String(e));
+            }
+            finally {
+                this.loading = undefined;
+                this.Update();
+            }
+        })();
+        return false;
+    }
+    SendError(error) {
+        if (this.OnCompilationError)
+            this.OnCompilationError(this, error);
+        else
+            console.error(`[SkiaShaderEffect] ${error}`);
+    }
+    /** The template wrapping the code; subclasses supply a default (ShaderTransitionEffect). */
+    GetTemplate() { return this.loadedTemplate?.code ?? ""; }
+    CompileShader() {
+        let code = this.shaderSource ? this.loadedSource?.code ?? "" : this.shaderCode;
+        code = code.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+        this.LoadedCode = code;
+        const template = this.GetTemplate();
+        if (template)
+            code = template.replace("//script-goes-here", code);
+        if (this.compiledKey === code && this.compiled)
+            return;
+        this.compiled = undefined;
+        this.compiledKey = code;
+        this.textureShader?.shader.delete();
+        this.textureShader = undefined;
+        if (!code.trim())
+            return;
+        let effect = compiledCache.get(code);
+        if (!effect) {
+            let error = "";
+            effect = Super.CK.RuntimeEffect.Make(code, (e) => { error = e; }) ?? undefined;
+            if (!effect) {
+                this.compileFailed = true;
+                this.SendError(error || "shader compilation failed");
+                return;
+            }
+            compiledCache.set(code, effect);
+        }
+        this.compiled = effect;
+        // uniform layout: flat floats in declaration order; a uniform spans up to the next slot (arrays included)
+        const count = effect.getUniformCount();
+        const slots = [];
+        for (let i = 0; i < count; i++)
+            slots.push({ name: effect.getUniformName(i), slot: effect.getUniform(i).slot });
+        this.uniformFloats = effect.getUniformFloatCount();
+        this.uniformSlots = new Map();
+        slots.forEach((s, i) => this.uniformSlots.set(s.name, { slot: s.slot, count: (i + 1 < slots.length ? slots[i + 1].slot : this.uniformFloats) - s.slot }));
+        this.childNames = [...code.matchAll(/uniform\s+shader\s+(\w+)\s*;/g)].map((m) => m[1]);
+    }
+    /** Builds this frame's shader (C# CreateShader). */
+    CreateShader(ctx, source) {
+        if (!this.EnsureCompiled())
+            return undefined;
+        const effect = this.compiled;
+        if (!effect)
+            return undefined;
+        const destination = ctx.Destination;
+        let owned;
+        if (this.UseBackground !== "Never") {
+            if (!source && this.AutoCreateInputTexture) {
+                source = this.CreateSnapshot(ctx, destination);
+                owned = source?.Image;
+            }
+            if (!source)
+                return undefined;
+        }
+        const primary = source ? this.CreateTextureShader(source) : undefined;
+        const textures = this.CreateTexturesUniforms(ctx, destination, primary);
+        const values = new Float32Array(this.uniformFloats);
+        this.CreateUniforms(destination, source?.Bounds, values);
+        const CK = Super.CK;
+        const temp = [];
+        const children = this.childNames.map((n) => {
+            const s = textures[n];
+            if (s)
+                return s;
+            const empty = CK.Shader.MakeColor(CK.TRANSPARENT, CK.ColorSpace.SRGB);
+            temp.push(empty);
+            return empty;
+        });
+        const shader = effect.makeShaderWithChildren(values, children);
+        if (owned)
+            this.DisposeImage(owned);
+        return { shader, children: temp };
+    }
+    /** IPostRendererEffect: draws the shader over ctx.Destination (C# Render). */
+    Render(ctx) {
+        this.TimeSeconds = performance.now() / 1000;
+        const texture = this.GetPrimaryTexture(ctx, ctx.Destination);
+        const built = this.CreateShader(ctx, texture);
+        if (!built)
+            return;
+        const CK = Super.CK;
+        const paint = this.paint ?? (this.paint = new CK.Paint());
+        paint.setBlendMode(CK.BlendMode[this.BlendMode] ?? CK.BlendMode.SrcOver);
+        paint.setShader(built.shader);
+        const d = ctx.Destination;
+        ctx.Context.Canvas.drawRect(CK.LTRBRect(d.Left, d.Top, d.Right, d.Bottom), paint);
+        paint.setShader(null);
+        built.shader.delete();
+        for (const t of built.children)
+            t.delete();
+    }
+    OnDisposing() {
+        this.textureShader?.shader.delete();
+        this.textureShader = undefined;
+        this.ReleaseFrozenSnapshot();
+        this.paint?.delete();
+        this.paint = undefined;
+        this.compiled = undefined; // compiled effects stay in the shared cache
+        super.OnDisposing();
+    }
+}
+/**
+ * Mirrors DrawnUi ShaderDoubleTexturesEffect: two input textures. `iImage1` comes from `ControlFrom`'s cache or a
+ * `PrimarySource` image, `iImage2` from `ControlTo`'s cache or a `SecondarySource` image (both resized to the parent
+ * box like C#), else from the parent as usual.
+ */
+export class ShaderDoubleTexturesEffect extends SkiaShaderEffect {
+    get ControlFrom() { return this.controlFrom; }
+    set ControlFrom(v) { this.controlFrom = v; }
+    get ControlTo() { return this.controlTo; }
+    set ControlTo(v) { if (this.controlTo !== v) {
+        this.controlTo = v;
+        this.secondary?.delete();
+        this.secondary = undefined;
+    } }
+    get PrimarySource() { return this.primarySource; }
+    set PrimarySource(v) { if (this.primarySource !== v) {
+        this.primarySource = v;
+        this.primaryImage = undefined;
+        this.LoadTexture(v, (i) => { this.primaryImage = i; this.Update(); });
+    } }
+    get SecondarySource() { return this.secondarySource; }
+    set SecondarySource(v) { if (this.secondarySource !== v) {
+        this.secondarySource = v;
+        this.secondaryImage = undefined;
+        this.LoadTexture(v, (i) => { this.secondaryImage = i; this.secondary?.delete(); this.secondary = undefined; this.Update(); });
+    } }
+    controlFrom;
+    controlTo;
+    primarySource = "";
+    secondarySource = "";
+    primaryImage;
+    secondaryImage;
+    resizedPrimary;
+    resizedSecondary;
+    secondary;
+    LoadTexture(url, done) {
+        if (!url)
+            return;
+        SkiaImageManager.Instance.LoadImageAsync(url).then((i) => { if (url === this.primarySource || url === this.secondarySource)
+            done(i); }).catch((e) => this.SendError(String(e)));
+    }
+    /** C# Resize*LoadedBitmap: the file texture spans the parent box. */
+    Resized(ctx, source, slot) {
+        const d = this.Parent?.DrawingRect;
+        if (!d || d.Width <= 0 || d.Height <= 0)
+            return undefined;
+        const w = Math.round(d.Width), h = Math.round(d.Height);
+        const cur = slot === "p" ? this.resizedPrimary : this.resizedSecondary;
+        if (cur && cur.source === source && cur.w === w && cur.h === h)
+            return cur.image;
+        const main = ctx.Context.Surface;
+        if (!main)
+            return undefined;
+        const surface = main.makeSurface({ ...main.imageInfo(), width: w, height: h });
+        if (!surface)
+            return undefined;
+        const CK = Super.CK;
+        const canvas = surface.getCanvas();
+        canvas.clear(CK.TRANSPARENT);
+        canvas.drawImageRectOptions(source, CK.XYWHRect(0, 0, source.width(), source.height()), CK.XYWHRect(0, 0, w, h), CK.FilterMode.Linear, CK.MipmapMode.Linear, null);
+        const image = surface.makeImageSnapshot();
+        surface.delete();
+        cur?.image.delete();
+        const entry = { source, w, h, image };
+        if (slot === "p")
+            this.resizedPrimary = entry;
+        else
+            this.resizedSecondary = entry;
+        if (slot === "s") {
+            this.secondary?.delete();
+            this.secondary = undefined;
+        }
+        return image;
+    }
+    GetPrimaryTexture(ctx, destination) {
+        if (this.controlFrom)
+            return this.controlFrom.CachedImage;
+        if (this.primarySource) {
+            const img = this.primaryImage ? this.Resized(ctx, this.primaryImage, "p") : undefined;
+            return img ? { Image: img, Bounds: destination } : undefined;
+        }
+        return super.GetPrimaryTexture(ctx, destination);
+    }
+    /** C# GetSecondaryTexture: ControlTo's cache image or the resized SecondarySource, as a clamped shader. */
+    GetSecondaryTexture(ctx) {
+        const CK = Super.CK;
+        let image;
+        if (this.controlTo)
+            image = this.controlTo.CachedImage?.Image;
+        else if (this.secondaryImage)
+            image = this.Resized(ctx, this.secondaryImage, "s");
+        if (!image)
+            return undefined;
+        if (this.secondary && this.secondaryImageRef === image)
+            return this.secondary;
+        this.secondary?.delete();
+        this.secondary = image.makeShaderOptions(CK.TileMode.Clamp, CK.TileMode.Clamp, CK.FilterMode.Linear, CK.MipmapMode.None);
+        this.secondaryImageRef = image;
+        return this.secondary;
+    }
+    secondaryImageRef;
+    CreateTexturesUniforms(ctx, destination, primaryTexture) {
+        return { ...super.CreateTexturesUniforms(ctx, destination, primaryTexture), iImage2: this.GetSecondaryTexture(ctx) };
+    }
+    OnDisposing() {
+        this.secondary?.delete();
+        this.secondary = undefined;
+        this.resizedPrimary?.image.delete();
+        this.resizedPrimary = undefined;
+        this.resizedSecondary?.image.delete();
+        this.resizedSecondary = undefined;
+        this.controlFrom = undefined;
+        this.controlTo = undefined;
+        super.OnDisposing();
+    }
+}
+/**
+ * Mirrors DrawnUi ShaderTransitionEffect: `iImage1` = from, `iImage2` = to, plus `progress` (0..1) and `ratio`
+ * (width / height) uniforms; without a ShaderTemplate the gl-transitions adapter `DefaultTemplate` wraps a
+ * `transition(vec2 uv)` function using `getFromColor` / `getToColor`.
+ */
+export class ShaderTransitionEffect extends ShaderDoubleTexturesEffect {
+    static DefaultTemplate = `
+uniform float ratio; // width / height
+uniform float progress; // 0.0 - 1.0
+uniform shader iImage1; // Texture
+uniform shader iImage2; // Texture for backside
+uniform float2 iOffset; // Top-left corner of DrawingRect
+uniform float2 iResolution; // Viewport resolution (pixels)
+uniform float2 iImageResolution; // iImage1 resolution (pixels)
+uniform float  iTime; // Shader playback time (s)
+uniform float4 iMouse; // Mouse drag pos=.xy Click pos=.zw (pixels)
+
+//In GLSL, the texture coordinate origin is at the bottom-left corner,
+//whereas in SKSL the origin is at the top-left corner.
+
+vec4 getFromColor(vec2 uv) {
+    vec2 adjustedUV = float2(uv.x, 1.0 - uv.y) * iImageResolution;
+    return iImage1.eval(adjustedUV);
+}
+
+vec4 getToColor(vec2 uv) {
+    vec2 adjustedUV = float2(uv.x, 1.0 - uv.y) * iImageResolution;
+    return iImage2.eval(adjustedUV);
+}
+
+//script-goes-here
+`;
+    /** 0 = fully ControlFrom, 1 = fully ControlTo; call Update() after changing. */
+    Progress = 0;
+    GetTemplate() { return super.GetTemplate() || ShaderTransitionEffect.DefaultTemplate; }
+    CreateUniforms(destination, textureBounds, values) {
+        super.CreateUniforms(destination, textureBounds, values);
+        this.Set(values, "progress", this.Progress);
+        this.Set(values, "ratio", destination.Height > 0 ? destination.Width / destination.Height : 1);
+    }
+}
+/**
+ * Mirrors DrawnUi AnimatedShaderEffect: a `progress` 0→1 uniform driven by an animator over `DurationMs`
+ * (2500) plus `iCenter` (normalized). `Play()` restarts, `Completed` fires when it finishes, `Stop()` is silent.
+ */
+export class AnimatedShaderEffect extends SkiaShaderEffect {
+    Center = { X: 0.5, Y: 0.5 };
+    DurationMs = 2500;
+    Progress = 0;
+    Completed;
+    Animator;
+    Play() {
+        this.Animator?.Stop();
+        const parent = this.Parent;
+        if (!parent)
+            return;
+        if (!this.Animator) {
+            const a = new SkiaValueAnimator(parent);
+            a.OnUpdated = (v) => { this.Progress = v; this.Update(); };
+            a.Finished = () => this.Completed?.(this);
+            this.Animator = a;
+        }
+        this.Progress = 0;
+        this.AquiredBackground = false; // Once mode re-captures on the next render
+        const a = this.Animator;
+        a.mMinValue = 0;
+        a.mMaxValue = 1;
+        a.Speed = this.DurationMs;
+        a.Easing = Easing.Linear;
+        a.Repeat = 0;
+        a.Start();
+        this.Update();
+    }
+    Stop() { this.Animator?.Stop(); }
+    CreateUniforms(destination, textureBounds, values) {
+        super.CreateUniforms(destination, textureBounds, values);
+        this.Set(values, "progress", this.Progress);
+        this.Set(values, "iCenter", this.Center.X, this.Center.Y);
+    }
+    OnDisposing() { this.Animator?.Stop(); this.Animator = undefined; super.OnDisposing(); }
+}

package/dist/core/SkiaImageManager.d.ts

@@ -0,0 +1,43 @@
+import type { Image } from "canvaskit-wasm";
+/** C# LoadPriority: order of the managed load queue. */
+export type LoadPriority = "Low" | "Normal" | "High";
+/**
+ * Mirrors DrawnUi SkiaImageManager: loads + decodes image sources once and shares the decoded CanvasKit Image
+ * between all SkiaImage instances using the same source (`ReuseBitmaps`). `LoadImageManagedAsync` goes through the
+ * priority queue (High > Normal > Low, at most `MaxParallelLoads` fetches in flight, C# semaphore of 5; the same
+ * source requested twice is fetched once), `LoadImageAsync` loads directly. `PreloadImages` warms the cache,
+ * `CancelAll` drops what is still queued. Sources are URLs (absolute, or relative to the page like "images/photo.jpg").
+ */
+export declare class SkiaImageManager {
+    static readonly Instance: SkiaImageManager;
+    /** Keep decoded images for reuse across controls (DrawnUi ReuseBitmaps). */
+    static ReuseBitmaps: boolean;
+    /** Fetches in flight at once through the managed queue (C# CreateSemaphoreForLocalFiles: 5). */
+    static MaxParallelLoads: number;
+    /** C# CanReload: raised when a queued load failed so the caller may retry later. */
+    CanReload?: (source: string, error: Error) => void;
+    private readonly cache;
+    private readonly pending;
+    private readonly queue;
+    private readonly waiting;
+    private running;
+    /** Queue diagnostics. */
+    get QueuedCount(): number;
+    get RunningCount(): number;
+    /** Cached decoded image, if loaded already (C# GetFromCache). */
+    GetFromCache(source: string): Image | undefined;
+    /** Direct load without the queue (C# LoadImageAsync); cached and de-duplicated. Rejects on network/decode failure. */
+    LoadImageAsync(source: string, signal?: AbortSignal): Promise<Image>;
+    private Fetch;
+    /** Queued load (C# LoadImageManagedAsync): cached images resolve at once, the rest wait their turn by priority. */
+    LoadImageManagedAsync(source: string, signal?: AbortSignal, priority?: LoadPriority): Promise<Image>;
+    private Pump;
+    /** C# PreloadImage: warms the cache for one source; failures are ignored. */
+    PreloadImage(source: string, priority?: LoadPriority): Promise<void>;
+    /** Warms the cache so first paint of these images is instant (DrawnUi PreloadImages). Failures are ignored. */
+    PreloadImages(sources: string[], priority?: LoadPriority): Promise<void>;
+    /** Drops everything still waiting in the queue (C# CancelAll); loads already in flight finish. */
+    CancelAll(): void;
+    /** Drops a cached image (or everything) — decoded images hold GPU/WASM memory. */
+    Clear(source?: string): void;
+}