@haiyue/extensions 0.1.0 → 0.2.0

package/dist/animation.js

@@ -1,12 +1,13 @@
-import { parseAnimation, ANIMATION_MIME_TYPE } from '@haiyue/animation-spec';
+import { parseAnimation, AnimationFormatError, ANIMATION_MIME_TYPE } from '@haiyue/animation-spec';
 import { Component, System } from '@haiyue/engine';
 import { UniqueCheckType, ComponentLifecycleFlags } from '@haiyue/engine/ecs';
-import { A as Animation2DRuntime, a as AnimationVisual2D } from './chunks/Animation2DStateMachine-9IonguNa.js';
-export { c as createAnimation2DStateMachineController, t as tessellateAnimationPath } from './chunks/Animation2DStateMachine-9IonguNa.js';
+import { A as Animation2DRuntime } from './chunks/Animation2DStateMachine-BHcA6Cu3.js';
+export { c as createAnimation2DStateMachineController, t as tessellateAnimationPath } from './chunks/Animation2DStateMachine-BHcA6Cu3.js';
 import { requireEngineDevice, getExtensionGPUResourceTracker, beginRenderCommandPass, cloneRenderPassDescriptor, alignUp4, estimateTextureBytes, getExtensionSharedRendererResource } from '@haiyue/engine/extension-authoring';
-import { R as RenderSystem2DBase, d as destroyCamera2DGpu, c as createCamera2DGpu, i as createCamera2DLayout } from './chunks/RenderSystem2DBase-DDT61dAu.js';
-import { A as Animation2dWgsl } from './chunks/2d-ui-animation-2d.generated-D4aHzFU2.js';
-export { A as AnimationStateMachineController, a as AnimationStateMachineValidationError, c as compileAnimationStateMachine, v as validateAnimationStateMachineDefinition } from './chunks/AnimationStateMachineController-BIcAh-sT.js';
+import { R as RenderSystem2DBase, d as destroyCamera2DGpu, c as createCamera2DGpu, i as createCamera2DLayout } from './chunks/RenderSystem2DBase-CF2s00vg.js';
+import { A as Animation2dWgsl } from './chunks/2d-ui-animation-2d.generated-FpziAeGJ.js';
+import { A as AnimationVisual2D, c as createAnimation2DPipeline, a as animation2DCullingPipelineKey, b as animation2DCullingPrimitive } from './chunks/AnimationVisual2D-8y3qp0_U.js';
+export { A as AnimationStateMachineController, b as AnimationStateMachineValidationError, a as compileAnimationStateMachine, d as validateAnimationStateMachineDefinition } from './chunks/AnimationStateMachineController-4sKaqh9E.js';
 import '@haiyue/engine/geometry';
 import '@haiyue/engine/components';
 import 'wgpu-matrix';
@@ -18,10 +19,13 @@ class Animation2DComponent extends Component {
     animation;
     playing;
     loop;
+    loopStartTime;
+    loopEndTime;
     speed;
     currentTime;
     completed = false;
     runtimeExtensions;
+    _nodeOverrides = new Map();
     _runtime = null;
     _needsApply = true;
     _forceParticleSeek = false;
@@ -30,6 +34,8 @@ class Animation2DComponent extends Component {
         this.animation = isParsed(source) ? source : parseAnimation(source);
         this.playing = options.autoplay ?? true;
         this.loop = options.loop ?? this.animation.endBehavior === 'loop';
+        this.loopStartTime = normalizeLoopStartTime(options.loopStartTime ?? 0, this.animation.duration);
+        this.loopEndTime = normalizeLoopEndTime(options.loopEndTime ?? this.animation.duration, this.loopStartTime, this.animation.duration);
         this.speed = finiteSpeed(options.speed ?? 1);
         this.currentTime = clampTime(options.startTime ?? 0, this.animation.duration);
         this.runtimeExtensions = options.runtimeExtensions;
@@ -73,6 +79,39 @@ class Animation2DComponent extends Component {
         this.speed = finiteSpeed(speed);
         return this;
     }
+    setNodeOverride(nodeId, override) {
+        if (!this.animation.nodes.some(node => node.id === nodeId))
+            throw new ReferenceError(`Animation node "${nodeId}" does not exist.`);
+        const position = override.position;
+        if (position && (position.length !== 2 || position.some(value => !Number.isFinite(value)))) {
+            throw new RangeError('Animation2D node override position must contain two finite values.');
+        }
+        if (override.opacity !== undefined && (!Number.isFinite(override.opacity) || override.opacity < 0 || override.opacity > 1)) {
+            throw new RangeError('Animation2D node override opacity must be within 0..1.');
+        }
+        if (override.enabled !== undefined && typeof override.enabled !== 'boolean') {
+            throw new TypeError('Animation2D node override enabled must be boolean.');
+        }
+        this._nodeOverrides.set(nodeId, Object.freeze({
+            ...(position ? { position: Object.freeze([position[0], position[1]]) } : {}),
+            ...(override.opacity === undefined ? {} : { opacity: override.opacity }),
+            ...(override.enabled === undefined ? {} : { enabled: override.enabled }),
+        }));
+        this._needsApply = true;
+        return this;
+    }
+    clearNodeOverride(nodeId) {
+        if (this._nodeOverrides.delete(nodeId))
+            this._needsApply = true;
+        return this;
+    }
+    clearNodeOverrides() {
+        if (this._nodeOverrides.size > 0) {
+            this._nodeOverrides.clear();
+            this._needsApply = true;
+        }
+        return this;
+    }
     onEntityRemoveComponent(_entity, component) {
         if (component === this)
             this._disposeRuntime();
@@ -84,11 +123,15 @@ class Animation2DComponent extends Component {
         const clone = new Animation2DComponent(this.animation, {
             autoplay: this.playing,
             loop: this.loop,
+            loopStartTime: this.loopStartTime,
+            loopEndTime: this.loopEndTime,
             speed: this.speed,
             startTime: this.currentTime,
             ...(this.runtimeExtensions ? { runtimeExtensions: this.runtimeExtensions } : {}),
         });
         clone.disabled = this.disabled;
+        for (const [nodeId, override] of this._nodeOverrides)
+            clone.setNodeOverride(nodeId, override);
         return clone;
     }
     _disposeRuntime() {
@@ -109,6 +152,254 @@ function clampTime(value, duration) {
         throw new RangeError('Animation2DComponent time must be finite.');
     return Math.max(0, Math.min(duration, value));
 }
+function normalizeLoopStartTime(value, duration) {
+    if (!Number.isFinite(value) || value < 0 || value >= duration) {
+        throw new RangeError('Animation2DComponent loopStartTime must be finite, non-negative, and less than duration.');
+    }
+    return value;
+}
+function normalizeLoopEndTime(value, loopStartTime, duration) {
+    if (!Number.isFinite(value) || value <= loopStartTime || value > duration) {
+        throw new RangeError('Animation2DComponent loopEndTime must be finite, greater than loopStartTime, and no greater than duration.');
+    }
+    return value;
+}
+
+class InteractionRuntimeError extends Error {
+    code;
+    path;
+    name = 'InteractionRuntimeError';
+    constructor(code, path, message) {
+        super(`${message} (${path})`);
+        this.code = code;
+        this.path = path;
+    }
+}
+
+class InteractionRuntime {
+    document;
+    options;
+    targets;
+    listeners;
+    queue = [];
+    pointers = new Map();
+    captures = new Map();
+    focused;
+    sequence = 0;
+    transactionSequence = 0;
+    draining = false;
+    currentDepth = 0;
+    disposed = false;
+    maxEventQueue;
+    maxEventRecursion;
+    maxPointers;
+    maxStringBytes;
+    constructor(document, options = {}) {
+        this.document = document;
+        this.options = options;
+        this.targets = new Map(document.targets.map(target => [target.id, target]));
+        this.listeners = new Map();
+        for (const listener of document.listeners) {
+            const values = this.listeners.get(listener.target) ?? [];
+            values.push(listener);
+            this.listeners.set(listener.target, values);
+        }
+        this.maxEventQueue = options.maxEventQueue ?? document.limits?.maxEventQueue ?? 1_000_000;
+        this.maxEventRecursion = options.maxEventRecursion ?? document.limits?.maxEventRecursion ?? 64;
+        this.maxPointers = options.maxPointers ?? document.limits?.maxPointers ?? 1_024;
+        this.maxStringBytes = options.maxStringBytes ?? 4 * 1024 * 1024;
+    }
+    dispatchPointer(input) {
+        this.assertLive();
+        if (!Number.isSafeInteger(input.pointerId) || input.pointerId < 0 || input.point.some(value => !Number.isFinite(value)))
+            throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_LIMIT', '$.pointer', 'invalid pointer input');
+        let state = this.pointers.get(input.pointerId);
+        if (!state) {
+            if (this.pointers.size >= this.maxPointers)
+                throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_LIMIT', '$.pointers', 'pointer budget exceeded');
+            state = { point: input.point, hover: undefined, down: undefined, downPoint: undefined, dragging: false };
+            this.pointers.set(input.pointerId, state);
+        }
+        const hit = this.captures.get(input.pointerId) ?? this.hitTest(input.point), previousHover = state.hover;
+        state.point = input.point;
+        if (input.kind === 'move' && previousHover !== hit) {
+            if (previousHover)
+                this.enqueue({ kind: 'pointer-exit', target: previousHover, depth: 0, pointerId: input.pointerId, point: input.point });
+            if (hit)
+                this.enqueue({ kind: 'pointer-enter', target: hit, depth: 0, pointerId: input.pointerId, point: input.point });
+            state.hover = hit;
+        }
+        if (input.kind === 'down') {
+            state.down = hit;
+            state.downPoint = input.point;
+            state.dragging = false;
+            if (hit) {
+                this.enqueue({ kind: 'pointer-down', target: hit, depth: 0, pointerId: input.pointerId, point: input.point, button: input.button ?? 0 });
+                this.focusFromPointer(hit);
+            }
+        }
+        else if (input.kind === 'move') {
+            if (hit)
+                this.enqueue({ kind: 'pointer-move', target: hit, depth: 0, pointerId: input.pointerId, point: input.point });
+            if (state.down && state.downPoint) {
+                const distance = Math.hypot(input.point[0] - state.downPoint[0], input.point[1] - state.downPoint[1]);
+                if (!state.dragging && distance >= this.document.dragThreshold) {
+                    state.dragging = true;
+                    this.enqueue({ kind: 'drag-start', target: state.down, depth: 0, pointerId: input.pointerId, point: input.point });
+                }
+                if (state.dragging)
+                    this.enqueue({ kind: 'drag', target: state.down, depth: 0, pointerId: input.pointerId, point: input.point });
+            }
+        }
+        else {
+            if (hit)
+                this.enqueue({ kind: 'pointer-up', target: hit, depth: 0, pointerId: input.pointerId, point: input.point, button: input.button ?? 0 });
+            if (state.down) {
+                if (state.dragging)
+                    this.enqueue({ kind: 'drag-end', target: state.down, depth: 0, pointerId: input.pointerId, point: input.point });
+                else if (hit === state.down)
+                    this.enqueue({ kind: 'click', target: state.down, depth: 0, pointerId: input.pointerId, point: input.point, button: input.button ?? 0 });
+            }
+            state.down = undefined;
+            state.downPoint = undefined;
+            state.dragging = false;
+            this.captures.delete(input.pointerId);
+        }
+        this.drain();
+    }
+    dispatchKeyboard(input) { this.assertLive(); if (!this.focused)
+        return; this.enqueue({ kind: 'keyboard', target: this.focused, depth: 0, key: input.key, keyPhase: input.phase, modifiers: input.modifiers ?? [] }); this.drain(); }
+    dispatchText(text) { this.assertLive(); this.stringInput(text, '$.text'); if (!this.focused)
+        return; this.enqueue({ kind: 'text-input', target: this.focused, depth: 0, text }); this.drain(); }
+    dispatchDataChange(binding, value, target = this.focused) { this.assertLive(); this.stringInput(binding, '$.binding'); if (!target)
+        throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_PORT', binding, 'data change requires a target'); this.enqueue({ kind: 'data-change', target, depth: 0, binding, value }); this.drain(); }
+    dispatchGamepad(input) { this.assertLive(); if (!this.focused)
+        return; this.enqueue({ kind: 'gamepad', target: this.focused, depth: 0, gamepad: input }); this.drain(); }
+    dispatchSemanticAction(target, action) { this.assertLive(); this.target(target); this.enqueue({ kind: 'semantic-action', target, depth: 0, semanticAction: action }); this.drain(); }
+    enqueueReportedEvent(name, payload = null, target = this.focused) { this.assertLive(); this.stringInput(name, '$.event.name'); if (!target)
+        throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_PORT', name, 'reported event requires a target'); this.enqueue({ kind: 'reported-event', target, depth: this.draining ? this.currentDepth + 1 : 0, name, payload }); if (!this.draining)
+        this.drain(); }
+    enqueueComponentEvent(target, name, payload = null) { this.assertLive(); this.stringInput(name, '$.componentEvent.name'); this.enqueue({ kind: 'component-event', target, depth: this.draining ? this.currentDepth + 1 : 0, name, payload }); if (!this.draining)
+        this.drain(); }
+    focus(target) { this.assertLive(); if (target !== undefined) {
+        const item = this.target(target);
+        if (!item.focusable || item.enabled === false)
+            throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_PORT', target, 'target is not focusable');
+    } if (this.focused === target)
+        return; const previous = this.focused; this.focused = target; if (previous)
+        this.enqueue({ kind: 'blur', target: previous, depth: this.draining ? this.currentDepth + 1 : 0 }); if (target)
+        this.enqueue({ kind: 'focus', target, depth: this.draining ? this.currentDepth + 1 : 0 }); if (!this.draining)
+        this.drain(); }
+    focusNext(reverse = false) { const ordered = [...this.targets.values()].filter(target => target.focusable && target.enabled !== false).sort((a, b) => (a.tabIndex ?? 0) - (b.tabIndex ?? 0) || a.order - b.order || a.id.localeCompare(b.id)); if (ordered.length === 0) {
+        this.focus(undefined);
+        return undefined;
+    } const current = ordered.findIndex(target => target.id === this.focused), delta = reverse ? -1 : 1, index = (current + delta + ordered.length) % ordered.length; this.focus(ordered[index].id); return this.focused; }
+    hitTest(point) { this.assertLive(); return [...this.targets.values()].filter(target => target.enabled !== false && this.options.geometryPort?.visible?.(target.id) !== false).sort((a, b) => b.order - a.order || b.id.localeCompare(a.id)).find(target => this.containsTarget(target, point, true))?.id; }
+    dispose() { if (this.disposed)
+        return; this.disposed = true; this.queue.length = 0; this.pointers.clear(); this.captures.clear(); this.focused = undefined; this.options.actionPort?.dispose?.(); }
+    get trace() { return Object.freeze({ sequence: this.sequence, focused: this.focused ?? null, captures: Object.freeze([...this.captures].map(([pointer, target]) => Object.freeze({ pointer, target }))), pointers: this.pointers.size, queued: this.queue.length, disposed: this.disposed }); }
+    enqueue(event) { if (event.depth > this.maxEventRecursion)
+        throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_LIMIT', '$.events', 'event recursion budget exceeded'); if (this.queue.length >= this.maxEventQueue)
+        throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_LIMIT', '$.events', 'event queue budget exceeded'); this.target(event.target); this.queue.push(event); }
+    drain() { if (this.draining)
+        return; this.draining = true; try {
+        while (this.queue.length) {
+            const event = this.queue.shift();
+            this.currentDepth = event.depth;
+            this.route(event);
+        }
+    }
+    finally {
+        this.currentDepth = 0;
+        this.draining = false;
+    } }
+    route(event) { const path = this.path(event.target), transactionId = ++this.transactionSequence, snapshot = this.snapshot(); const actionPort = this.options.actionPort; actionPort?.begin(transactionId); try {
+        for (const current of path.slice(0, -1))
+            this.invokeListeners(current, 'capture', event, transactionId);
+        this.invokeListeners(event.target, 'target', event, transactionId);
+        for (const current of path.slice(0, -1).reverse())
+            this.invokeListeners(current, 'bubble', event, transactionId);
+        actionPort?.commit(transactionId);
+    }
+    catch (error) {
+        this.restore(snapshot);
+        actionPort?.rollback(transactionId);
+        throw error;
+    } }
+    invokeListeners(currentTarget, phase, event, transactionId) { const listeners = this.listeners.get(currentTarget) ?? []; for (const listener of listeners) {
+        if (listener.event !== event.kind || !listener.phases.includes(phase) || !this.matches(listener, event))
+            continue;
+        const routed = Object.freeze({ sequence: ++this.sequence, kind: event.kind, phase, target: event.target, currentTarget, ...(event.pointerId === undefined ? {} : { pointerId: event.pointerId }), ...(event.point === undefined ? {} : { point: event.point, localPoint: this.toLocal(currentTarget, event.point) }), ...(event.button === undefined ? {} : { button: event.button }), ...(event.key === undefined ? {} : { key: event.key }), ...(event.keyPhase === undefined ? {} : { keyPhase: event.keyPhase }), ...(event.modifiers === undefined ? {} : { modifiers: event.modifiers }), ...(event.text === undefined ? {} : { text: event.text }), ...(event.binding === undefined ? {} : { binding: event.binding }), ...(event.value === undefined ? {} : { value: event.value }), ...(event.gamepad === undefined ? {} : { gamepad: event.gamepad }), ...(event.semanticAction === undefined ? {} : { semanticAction: event.semanticAction }), ...(event.name === undefined ? {} : { name: event.name }), ...(event.payload === undefined ? {} : { payload: event.payload }) });
+        for (const action of listener.actions)
+            this.invokeAction(action, routed);
+    } }
+    invokeAction(action, event) { if (action.kind === 'pointer-capture') {
+        if (event.pointerId === undefined)
+            throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_PORT', event.currentTarget, 'pointer capture requires a pointer event');
+        this.captures.set(event.pointerId, event.currentTarget);
+    }
+    else if (action.kind === 'pointer-release') {
+        if (event.pointerId !== undefined)
+            this.captures.delete(event.pointerId);
+    }
+    else if (action.kind === 'focus')
+        this.focus(action.target ?? event.currentTarget); const port = this.options.actionPort; if (!port && !['pointer-capture', 'pointer-release', 'focus'].includes(action.kind))
+        throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_PORT', event.currentTarget, `action port is required for ${action.kind}`); port?.invoke(action, event); }
+    matches(listener, event) { if (listener.pointerButton !== undefined && listener.pointerButton !== event.button)
+        return false; if (listener.key !== undefined && listener.key !== event.key)
+        return false; if (listener.keyPhase !== undefined && listener.keyPhase !== event.keyPhase)
+        return false; if (listener.modifiers && !listener.modifiers.every(modifier => event.modifiers?.includes(modifier)))
+        return false; if (listener.gamepad && (!event.gamepad || (listener.gamepad.index !== undefined && listener.gamepad.index !== event.gamepad.index) || listener.gamepad.control !== event.gamepad.control || listener.gamepad.phase !== event.gamepad.phase))
+        return false; if (listener.semanticAction !== undefined && listener.semanticAction !== event.semanticAction)
+        return false; return true; }
+    containsTarget(target, point, clips) { const local = this.toLocal(target.id, point); if (clips && target.clips?.some(id => !this.containsTarget(this.target(id), point, false)))
+        return false; const area = target.hitArea, kind = area.kind; if (kind === 'rect') {
+        const [x, y, width, height] = area.rect;
+        return local[0] >= x && local[1] >= y && local[0] <= x + width && local[1] <= y + height;
+    } if (kind === 'ellipse') {
+        const center = area.center, radius = area.radius;
+        if (radius[0] === 0 || radius[1] === 0)
+            return false;
+        return ((local[0] - center[0]) / radius[0]) ** 2 + ((local[1] - center[1]) / radius[1]) ** 2 <= 1;
+    } if (kind === 'polygon')
+        return pointInPolygon(local, area.points); if (kind === 'geometry') {
+        const port = this.options.geometryPort?.containsGeometry;
+        if (!port)
+            throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_PORT', target.id, 'geometry hit area requires a geometry port');
+        return port(area.port, target.id, local);
+    } return false; }
+    toLocal(id, point) { const chain = this.path(id); let matrix = [1, 0, 0, 1, 0, 0]; for (const targetId of chain) {
+        const target = this.target(targetId), authored = target.transform, dynamic = this.options.geometryPort?.matrix?.(targetId);
+        if (authored)
+            matrix = multiply(matrix, authored);
+        if (dynamic)
+            matrix = multiply(matrix, dynamic);
+    } return transform(inverse(matrix), point); }
+    path(id) { const result = []; let current = this.target(id); while (current) {
+        result.unshift(current.id);
+        current = current.parent ? this.target(current.parent) : undefined;
+    } return result; }
+    focusFromPointer(id) { let target = this.target(id); while (target && !target.focusable)
+        target = target.parent ? this.target(target.parent) : undefined; if (target?.focusable)
+        this.focus(target.id); }
+    target(id) { const target = this.targets.get(id); if (!target)
+        throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_PORT', id, 'unknown interaction target'); return target; }
+    snapshot() { return { pointers: new Map([...this.pointers].map(([id, state]) => [id, { ...state }])), captures: new Map(this.captures), focus: this.focused, queue: [...this.queue] }; }
+    restore(snapshot) { this.pointers = snapshot.pointers; this.captures = snapshot.captures; this.focused = snapshot.focus; this.queue.splice(0, this.queue.length, ...snapshot.queue); }
+    stringInput(value, path) { if (typeof value !== 'string' || new TextEncoder().encode(value).length > this.maxStringBytes)
+        throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_LIMIT', path, 'string input exceeds budget'); }
+    assertLive() { if (this.disposed)
+        throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_PORT', '$', 'interaction runtime is disposed'); }
+}
+function multiply(a, b) { return [a[0] * b[0] + a[2] * b[1], a[1] * b[0] + a[3] * b[1], a[0] * b[2] + a[2] * b[3], a[1] * b[2] + a[3] * b[3], a[0] * b[4] + a[2] * b[5] + a[4], a[1] * b[4] + a[3] * b[5] + a[5]]; }
+function inverse(value) { const determinant = value[0] * value[3] - value[1] * value[2]; if (Math.abs(determinant) < 1e-12)
+    throw new InteractionRuntimeError('E_INTERACTION_RUNTIME_PORT', '$.transform', 'interaction transform is singular'); return [value[3] / determinant, -value[1] / determinant, -value[2] / determinant, value[0] / determinant, (value[2] * value[5] - value[3] * value[4]) / determinant, (value[1] * value[4] - value[0] * value[5]) / determinant]; }
+function transform(matrix, point) { return [matrix[0] * point[0] + matrix[2] * point[1] + matrix[4], matrix[1] * point[0] + matrix[3] * point[1] + matrix[5]]; }
+function pointInPolygon(point, points) { let inside = false; for (let index = 0, previous = points.length - 1; index < points.length; previous = index++) {
+    const a = points[index], b = points[previous], crosses = a[1] > point[1] !== b[1] > point[1] && point[0] < (b[0] - a[0]) * (point[1] - a[1]) / (b[1] - a[1]) + a[0];
+    if (crosses)
+        inside = !inside;
+} return inside; }
 
 class Animation2DSystem extends System {
     _assetManager;
@@ -149,12 +440,15 @@ class Animation2DSystem extends System {
         }
         if (component.completed && component.animation.endBehavior === 'destroy' && !component.playing)
             return;
-        component._runtime ??= new Animation2DRuntime(entity, component.animation, component.runtimeExtensions, this._assetManager);
+        component._runtime ??= new Animation2DRuntime(entity, component.animation, component.runtimeExtensions, this._assetManager, component._nodeOverrides);
         if (component.playing && delta > 0 && component.speed > 0) {
             component.currentTime += delta * 0.001 * component.speed;
-            if (component.currentTime >= component.animation.duration) {
+            const playbackEnd = component.loop ? component.loopEndTime : component.animation.duration;
+            if (component.currentTime >= playbackEnd) {
                 if (component.loop) {
-                    component.currentTime %= component.animation.duration;
+                    const loopDuration = component.loopEndTime - component.loopStartTime;
+                    component.currentTime = component.loopStartTime
+                        + ((component.currentTime - component.loopEndTime) % loopDuration);
                     component._forceParticleSeek = true;
                 }
                 else {
@@ -178,9 +472,93 @@ class Animation2DSystem extends System {
     }
 }
 
+/** 256 MiB of rgba8 mask targets before allocator/tracker overhead. */
+const ANIMATION_2D_MAX_MASK_PIXELS = 64 * 1024 * 1024;
+function animationMaskTargetKey(viewKey, sourceKey) {
+    return `${viewKey.length}:${viewKey}${sourceKey.length}:${sourceKey}`;
+}
+function animationMaskCompositeKey(viewKey, sourceKeys) {
+    return `${viewKey.length}:${viewKey}${sourceKeys.map(key => `${key.length}:${key}`).join('')}`;
+}
+/** Classifies every mask allocation limit before any GPU target is created. */
+function assertAnimationMaskBudget(input) {
+    const basePath = `$runtime.views[${JSON.stringify(input.viewKey)}]`;
+    if (!Number.isSafeInteger(input.groupCount) || input.groupCount < 0) {
+        throw new AnimationFormatError('E_ANIMATION_INVALID_FORMAT', 'Mask group count must be a non-negative safe integer.', `${basePath}.maskGroups`);
+    }
+    if (input.groupCount > input.maxGroupCount) {
+        throw new AnimationFormatError('E_ANIMATION_LIMIT_EXCEEDED', `Mask group count ${input.groupCount} exceeds limit ${input.maxGroupCount}.`, `${basePath}.maskGroups`);
+    }
+    if (!Number.isSafeInteger(input.width) || input.width <= 0 || !Number.isSafeInteger(input.height) || input.height <= 0) {
+        throw new AnimationFormatError('E_ANIMATION_INVALID_FORMAT', 'Mask target dimensions must be positive safe integers.', `${basePath}.maskTexture`);
+    }
+    if (input.width > input.maxTextureDimension2D || input.height > input.maxTextureDimension2D) {
+        throw new AnimationFormatError('E_ANIMATION_LIMIT_EXCEEDED', `Mask target ${input.width}x${input.height} exceeds device maxTextureDimension2D ${input.maxTextureDimension2D}.`, `${basePath}.maskTexture`);
+    }
+    const pixels = input.width * input.height * input.groupCount;
+    const maxPixels = input.maxPixels ?? ANIMATION_2D_MAX_MASK_PIXELS;
+    if (!Number.isSafeInteger(pixels) || pixels > maxPixels) {
+        throw new AnimationFormatError('E_ANIMATION_LIMIT_EXCEEDED', `Mask target pixels ${pixels} exceed aggregate limit ${maxPixels}.`, `${basePath}.maskPixels`);
+    }
+}
+
+/** Official Cubism 5.2-and-earlier blend factors for premultiplied source colors. */
+function animationBlendState(mode) {
+    if (mode === 'additive')
+        return {
+            color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+            alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+        };
+    if (mode === 'multiplicative')
+        return {
+            color: { srcFactor: 'dst', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+        };
+    if (mode === 'screen')
+        return {
+            color: { srcFactor: 'one', dstFactor: 'one-minus-src', operation: 'add' },
+            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+        };
+    return {
+        color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+    };
+}
+function animationBlendFragmentEntryPoint(mode, textureAlphaMode = 'straight') {
+    return textureAlphaMode === 'premultiplied' ? 'fs_main_premultiplied_texture' : 'fs_main';
+}
+
 const SHADER = Animation2dWgsl;
+const TEXT_MIPMAP_SHADER = /* wgsl */ `
+struct VertexOutput {
+  @builtin(position) position: vec4f,
+  @location(0) uv: vec2f,
+}
+
+@group(0) @binding(0) var sourceTexture: texture_2d<f32>;
+@group(0) @binding(1) var sourceSampler: sampler;
+
+@vertex
+fn vertexMain(@builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
+  let positions = array(vec2f(-1.0, -1.0), vec2f(3.0, -1.0), vec2f(-1.0, 3.0));
+  let uvs = array(vec2f(0.0, 1.0), vec2f(2.0, 1.0), vec2f(0.0, -1.0));
+  var output: VertexOutput;
+  output.position = vec4f(positions[vertexIndex], 0.0, 1.0);
+  output.uv = uvs[vertexIndex];
+  return output;
+}
+
+@fragment
+fn fragmentMain(input: VertexOutput) -> @location(0) vec4f {
+  return textureSample(sourceTexture, sourceSampler, input.uv);
+}
+`;
 const MAX_COMPOSITE_LAYERS = 8;
-const COMPOSITE_PARAMS_OFFSET = 28;
+const MULTIPLY_COLOR_OFFSET = 20;
+const SCREEN_COLOR_OFFSET = 24;
+const PARAMS_OFFSET = 28;
+const UV_RECT_OFFSET = 32;
+const COMPOSITE_PARAMS_OFFSET = 36;
 const COMPOSITE_EXPANSION_OFFSET = COMPOSITE_PARAMS_OFFSET + MAX_COMPOSITE_LAYERS * 4;
 const GRADIENT_PARAMS_OFFSET = COMPOSITE_EXPANSION_OFFSET + MAX_COMPOSITE_LAYERS;
 const GRADIENT_GEOMETRY_OFFSET = GRADIENT_PARAMS_OFFSET + 4;
@@ -193,7 +571,7 @@ const MAX_EFFECTS = 8;
 const OBJECT_FLOATS = EFFECT_DATA_OFFSET + MAX_EFFECTS * EFFECT_FLOATS;
 const OBJECT_BYTES = OBJECT_FLOATS * 4;
 function getAnimation2DSharedGpu(device, tracker) {
-    return getExtensionSharedRendererResource(device, 'Animation2D.sharedGpu:v1', () => createAnimation2DSharedGpu(device, tracker));
+    return getExtensionSharedRendererResource(device, 'Animation2D.sharedGpu:v2', () => createAnimation2DSharedGpu(device, tracker));
 }
 function createAnimation2DSharedGpu(device, tracker) {
     const cameraLayout = createCamera2DLayout(device);
@@ -216,7 +594,21 @@ function createAnimation2DSharedGpu(device, tracker) {
             })),
             { binding: MAX_COMPOSITE_LAYERS, visibility: GPUShaderStage.FRAGMENT, sampler: { type: 'filtering' } },
         ] });
-    const sampler = device.createSampler({ magFilter: 'linear', minFilter: 'linear' });
+    const sampler = device.createSampler({ magFilter: 'linear', minFilter: 'linear', mipmapFilter: 'linear' });
+    const mipmapSampler = device.createSampler({
+        magFilter: 'linear',
+        minFilter: 'linear',
+        addressModeU: 'clamp-to-edge',
+        addressModeV: 'clamp-to-edge',
+    });
+    const mipmapShader = device.createShaderModule({ label: 'Animation2D.textMipmapShader', code: TEXT_MIPMAP_SHADER });
+    const mipmapPipeline = device.createRenderPipeline({
+        label: 'Animation2D.textMipmapPipeline',
+        layout: 'auto',
+        vertex: { module: mipmapShader, entryPoint: 'vertexMain' },
+        fragment: { module: mipmapShader, entryPoint: 'fragmentMain', targets: [{ format: 'rgba8unorm' }] },
+        primitive: { topology: 'triangle-list' },
+    });
     const shader = device.createShaderModule({ label: 'Animation2D.shader', code: SHADER });
     const pipelineLayout = device.createPipelineLayout({
         bindGroupLayouts: [cameraLayout, objectLayout, textureLayout, compositeLayout],
@@ -260,6 +652,8 @@ function createAnimation2DSharedGpu(device, tracker) {
         textureLayout,
         compositeLayout,
         sampler,
+        mipmapSampler,
+        mipmapPipeline,
         shader,
         pipelineLayout,
         pipelines: new Map(),
@@ -285,6 +679,8 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
     textureLayout;
     compositeLayout;
     sampler;
+    mipmapSampler;
+    mipmapPipeline;
     whiteTexture;
     whiteBindGroup;
     emptyCompositeBindGroup;
@@ -295,6 +691,8 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
     pipelines;
     entityGpu = new Map();
     geometryGpu = new Map();
+    explicitUvIds = new WeakMap();
+    nextExplicitUvId = 1;
     textureBindGroups = new WeakMap();
     maskTargets = new Map();
     effectTargets = new Map();
@@ -371,6 +769,27 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
             }
             group.push(item);
         }
+        // Variant-expanded documents can retain many mutually exclusive mask
+        // sources. A completely transparent group contributes the transparent
+        // identity mask, so sharing the renderer's immutable transparent texture
+        // is exact and avoids allocating one full-viewport target per inactive
+        // state. Keep the group keys so alpha-inverted consumers still resolve the
+        // correct transparent input instead of being classified as unresolved.
+        const knownSourceKeys = new Set(this.sourceItems.keys());
+        let activeSourceGroupCount = 0;
+        for (const sources of this.sourceItems.values()) {
+            if (sources.some(source => !isFullyTransparent(source.visual)))
+                activeSourceGroupCount++;
+        }
+        const viewKey = context.view?.key ?? 'default';
+        assertAnimationMaskBudget({
+            groupCount: activeSourceGroupCount,
+            maxGroupCount: this.maxMaskTargets,
+            width: context.view?.target.width ?? this.engine.width,
+            height: context.view?.target.height ?? this.engine.height,
+            maxTextureDimension2D: context.device.limits.maxTextureDimension2D,
+            viewKey,
+        });
         const maskTargets = this.activeMaskTargets;
         maskTargets.clear();
         let maskPixels = 0;
@@ -382,19 +801,19 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
         let effectPixels = 0;
         for (const sourceKey of orderSourceGroups(this.sourceItems)) {
             const sources = this.sourceItems.get(sourceKey);
-            if (maskCount >= this.maxMaskTargets)
-                break;
-            const targetKey = `${context.view?.key ?? 'default'}:${sourceKey}`;
+            if (sources.every(source => isFullyTransparent(source.visual)))
+                continue;
+            const targetKey = animationMaskTargetKey(viewKey, sourceKey);
             const target = this.getMaskTarget(targetKey, context, frame);
             maskPixels += target.width * target.height;
             maskCount++;
             let initialized = false;
             for (const source of sources) {
-                const resolved = this.resolveCompositeBindGroup(source.visual, maskTargets, context.view?.key ?? 'default');
-                if (!resolved) {
-                    droppedCompositeCount++;
+                if (isFullyTransparent(source.visual))
                     continue;
-                }
+                const resolved = this.resolveCompositeBindGroup(source.visual, maskTargets, knownSourceKeys, viewKey);
+                if (!resolved)
+                    throw unresolvedCompositeError(source.visual, viewKey);
                 compositeLayerCount += source.visual.compositeLayers.length;
                 const effectTarget = source.visual.effects.length > 0 && !context.passEncoder
                     ? this.renderEffectStack(source, context, resolved, frame)
@@ -412,7 +831,7 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
                     this.drawEffectResult(pass, source.entity, effectTarget.texture);
                 }
                 else {
-                    pass.setPipeline(this.getPipeline('rgba8unorm', 1, false, false));
+                    pass.setPipeline(this.getPipeline('rgba8unorm', 1, false, false, 'normal', source.visual.textureAlphaMode, source.visual.culling));
                     this.draw(pass, source.entity, source.visual, context, resolved, true);
                 }
                 pass.end();
@@ -434,7 +853,7 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
             applyViewport(passEncoder, context);
             passEncoder.setBindGroup(0, this.cameraGpu.bindGroup);
             for (const entry of pending) {
-                passEncoder.setPipeline(this.getPipeline(outputFormat, context.view?.sampleCount ?? this.engine.msaaSamples, true, context.view?.reverseZ ?? this.engine.reverseZ));
+                passEncoder.setPipeline(this.getPipeline(outputFormat, context.view?.sampleCount ?? this.engine.msaaSamples, true, context.view?.reverseZ ?? this.engine.reverseZ, entry.item.visual.blendMode, entry.item.visual.textureAlphaMode, entry.item.visual.culling));
                 this.draw(passEncoder, entry.item.entity, entry.item.visual, context, entry.composite, false);
                 visualCount++;
             }
@@ -449,13 +868,11 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
         };
         for (const item of this.items) {
             const { visual } = item;
-            if (visual.sourceOnly)
-                continue;
-            const resolved = this.resolveCompositeBindGroup(visual, maskTargets, context.view?.key ?? 'default');
-            if (!resolved) {
-                droppedCompositeCount++;
+            if (visual.sourceOnly || isFullyTransparent(visual))
                 continue;
-            }
+            const resolved = this.resolveCompositeBindGroup(visual, maskTargets, knownSourceKeys, viewKey);
+            if (!resolved)
+                throw unresolvedCompositeError(visual, viewKey);
             compositeLayerCount += visual.compositeLayers.length;
             if (visual.effects.length > 0 && !context.passEncoder) {
                 const effectTarget = this.renderEffectStack(item, context, resolved, frame);
@@ -517,6 +934,8 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
         this.textureLayout = shared.textureLayout;
         this.compositeLayout = shared.compositeLayout;
         this.sampler = shared.sampler;
+        this.mipmapSampler = shared.mipmapSampler;
+        this.mipmapPipeline = shared.mipmapPipeline;
         this.whiteTexture = shared.whiteTexture;
         this.whiteBindGroup = shared.whiteBindGroup;
         this.emptyCompositeBindGroup = shared.emptyCompositeBindGroup;
@@ -548,13 +967,13 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
             throw new Error('Animation2D ordered effects require an isolated render-pass descriptor.');
         return { passEncoder: context.encoder.beginRenderPass(cloneRenderPassDescriptor(context.descriptor, 'load')), ownsPass: true };
     }
-    getPipeline(format, sampleCount, withDepth, reverseZ) {
+    getPipeline(format, sampleCount, withDepth, reverseZ, blendMode = 'normal', textureAlphaMode = 'straight', culling = false) {
         const depthFormat = withDepth ? this.engine.getDepthFormat(reverseZ) : 'none';
-        const key = `visual:${format}:${sampleCount}:${depthFormat}:${reverseZ ? 1 : 0}`;
+        const key = `visual:${format}:${sampleCount}:${depthFormat}:${reverseZ ? 1 : 0}:${blendMode}:${textureAlphaMode}:${animation2DCullingPipelineKey(culling)}`;
         const cached = this.pipelines.get(key);
         if (cached)
             return cached;
-        const pipeline = requireEngineDevice(this.engine).createRenderPipeline({
+        const pipeline = createAnimation2DPipeline(key, () => requireEngineDevice(this.engine).createRenderPipeline({
             label: `Animation2D.pipeline:${key}`,
             layout: this.pipelineLayout,
             vertex: { module: this.shader, entryPoint: 'vs_main', buffers: [{
@@ -564,18 +983,19 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
                             { shaderLocation: 1, offset: 8, format: 'float32x2' },
                         ],
                     }] },
-            fragment: { module: this.shader, entryPoint: 'fs_main', targets: [{ format, blend: {
-                            color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-                            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-                        } }] },
-            primitive: { topology: 'triangle-list', cullMode: 'none' },
+            fragment: {
+                module: this.shader,
+                entryPoint: animationBlendFragmentEntryPoint(blendMode, textureAlphaMode),
+                targets: [{ format, blend: animationBlendState(blendMode) }],
+            },
+            primitive: animation2DCullingPrimitive(culling),
             ...(withDepth ? { depthStencil: {
                     format: depthFormat,
                     depthWriteEnabled: false,
                     depthCompare: 'always',
                 } } : {}),
             multisample: { count: sampleCount },
-        });
+        }));
         this.pipelines.set(key, pipeline);
         return pipeline;
     }
@@ -622,11 +1042,13 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
         const object = this.getEntityGpu(entity);
         object.data.set(this.getWorldMatrix2D(entity, context), 0);
         object.data.set(visual.color, 16);
-        object.data[20] = visual.compositeLayers.length;
-        object.data[21] = outputMask ? 1 : 0;
-        object.data[22] = Math.min(MAX_EFFECTS, visual.effects.length);
-        object.data[23] = 0;
-        object.data.set(visual.uvRect, 24);
+        object.data.set(visual.multiplyColor, MULTIPLY_COLOR_OFFSET);
+        object.data.set(visual.screenColor, SCREEN_COLOR_OFFSET);
+        object.data[PARAMS_OFFSET] = visual.compositeLayers.length;
+        object.data[PARAMS_OFFSET + 1] = outputMask ? 1 : 0;
+        object.data[PARAMS_OFFSET + 2] = Math.min(MAX_EFFECTS, visual.effects.length);
+        object.data[PARAMS_OFFSET + 3] = 0;
+        object.data.set(visual.uvRect, UV_RECT_OFFSET);
         object.data.fill(0, COMPOSITE_PARAMS_OFFSET);
         for (let index = 0; index < visual.compositeLayers.length; index++) {
             const layer = visual.compositeLayers[index];
@@ -686,7 +1108,7 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
                 }],
         });
         applyViewport(sourcePass, context);
-        sourcePass.setPipeline(this.getPipeline('rgba8unorm', 1, false, false));
+        sourcePass.setPipeline(this.getPipeline('rgba8unorm', 1, false, false, 'normal', item.visual.textureAlphaMode, item.visual.culling));
         sourcePass.setBindGroup(0, this.cameraGpu.bindGroup);
         this.draw(sourcePass, item.entity, item.visual, context, compositeBindGroup, false);
         sourcePass.end();
@@ -732,6 +1154,7 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
                 externalVersion: -1,
                 externalWidth: 0,
                 externalHeight: 0,
+                externalMipLevelCount: 1,
                 externalBindGroup: null,
             };
         });
@@ -762,22 +1185,26 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
                         retire();
                     }
                 }
+                object.externalMipLevelCount = calculateMipLevelCount(size.width, size.height);
                 object.externalTexture = requireEngineDevice(this.engine).createTexture({
                     label: `Animation2D.text:${entity.id}`,
                     size: [size.width, size.height],
+                    mipLevelCount: object.externalMipLevelCount,
                     format: 'rgba8unorm',
                     // WebGPU copyExternalImageToTexture requires RENDER_ATTACHMENT in addition
                     // to COPY_DST for browser-backed image sources.
                     usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
                 });
-                getExtensionGPUResourceTracker(this.engine)?.trackTexture(object.externalTexture, 'Animation2D.textTexture', size.width * size.height * 4);
+                getExtensionGPUResourceTracker(this.engine)?.trackTexture(object.externalTexture, 'Animation2D.textTexture', estimateRgba8MipChainBytes(size.width, size.height, object.externalMipLevelCount));
                 object.externalBindGroup = this.createTextureBindGroup(object.externalTexture);
                 object.externalWidth = size.width;
                 object.externalHeight = size.height;
                 object.externalVersion = -1;
             }
             if (object.externalSource !== source || object.externalVersion !== material.textureVersion) {
-                requireEngineDevice(this.engine).queue.copyExternalImageToTexture({ source }, { texture: object.externalTexture }, [size.width, size.height]);
+                const device = requireEngineDevice(this.engine);
+                device.queue.copyExternalImageToTexture({ source }, { texture: object.externalTexture, premultipliedAlpha: true }, [size.width, size.height]);
+                this.generateTextMipChain(device, object.externalTexture, object.externalMipLevelCount, entity.id);
                 object.externalSource = source;
                 object.externalVersion = material.textureVersion;
             }
@@ -785,14 +1212,44 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
         }
         return visual.requiresTexture ? this.transparentBindGroup : this.whiteBindGroup;
     }
+    generateTextMipChain(device, texture, mipLevelCount, entityId) {
+        if (mipLevelCount <= 1)
+            return;
+        const encoder = device.createCommandEncoder({ label: `Animation2D.textMipmaps:${entityId}` });
+        for (let level = 1; level < mipLevelCount; level++) {
+            const bindGroup = device.createBindGroup({
+                label: `Animation2D.textMipmapBindGroup:${entityId}:${level}`,
+                layout: this.mipmapPipeline.getBindGroupLayout(0),
+                entries: [
+                    { binding: 0, resource: texture.createView({ baseMipLevel: level - 1, mipLevelCount: 1 }) },
+                    { binding: 1, resource: this.mipmapSampler },
+                ],
+            });
+            const pass = encoder.beginRenderPass({
+                label: `Animation2D.textMipmapPass:${entityId}:${level}`,
+                colorAttachments: [{
+                        view: texture.createView({ baseMipLevel: level, mipLevelCount: 1 }),
+                        loadOp: 'clear',
+                        storeOp: 'store',
+                        clearValue: { r: 0, g: 0, b: 0, a: 0 },
+                    }],
+            });
+            pass.setPipeline(this.mipmapPipeline);
+            pass.setBindGroup(0, bindGroup);
+            pass.draw(3);
+            pass.end();
+        }
+        device.queue.submit([encoder.finish()]);
+    }
     getGeometryGpu(visual) {
         const geometry = visual.geometry;
-        let gpu = this.geometryGpu.get(geometry.id);
+        const key = this.geometryKey(visual);
+        let gpu = this.geometryGpu.get(key);
         if (gpu && gpu.version === geometry.version)
             return gpu;
         if (gpu)
             this.destroyGeometryGpu(gpu);
-        const vertices = buildVertices(geometry.positions);
+        const vertices = buildVertices(geometry.positions, visual.uvs);
         const device = requireEngineDevice(this.engine);
         const vertexBuffer = device.createBuffer({ size: vertices.byteLength, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
         device.queue.writeBuffer(vertexBuffer, 0, vertices);
@@ -814,9 +1271,19 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
             indexFormat: geometry.indices instanceof Uint32Array ? 'uint32' : 'uint16',
             version: geometry.version,
         };
-        this.geometryGpu.set(geometry.id, gpu);
+        this.geometryGpu.set(key, gpu);
         return gpu;
     }
+    geometryKey(visual) {
+        if (!visual.uvs)
+            return `${visual.geometry.id}:derived`;
+        let uvId = this.explicitUvIds.get(visual.uvs);
+        if (uvId === undefined) {
+            uvId = this.nextExplicitUvId++;
+            this.explicitUvIds.set(visual.uvs, uvId);
+        }
+        return `${visual.geometry.id}:uv:${uvId}`;
+    }
     getTextureBindGroup(texture) {
         let bindGroup = this.textureBindGroups.get(texture);
         if (!bindGroup) {
@@ -831,20 +1298,28 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
                 { binding: 1, resource: this.sampler },
             ] });
     }
-    resolveCompositeBindGroup(visual, targets, viewKey) {
+    resolveCompositeBindGroup(visual, targets, knownSourceKeys, viewKey) {
         if (visual.compositeLayers.length === 0)
             return this.emptyCompositeBindGroup;
         const resolved = [];
+        const resolvedKeys = [];
         for (const key of visual.compositeKeys) {
             const target = targets.get(key);
-            if (!target)
-                return null;
-            resolved.push(target);
+            if (target) {
+                resolved.push(target.texture);
+                resolvedKeys.push(key);
+            }
+            else {
+                if (!knownSourceKeys.has(key))
+                    return null;
+                resolved.push(this.transparentTexture);
+                resolvedKeys.push(`transparent:${key}`);
+            }
         }
-        const key = `${viewKey}:${visual.compositeKeys.join('|')}`;
+        const key = animationMaskCompositeKey(viewKey, resolvedKeys);
         let bindGroup = this.compositeBindGroups.get(key);
         if (!bindGroup) {
-            bindGroup = this.createCompositeBindGroup(resolved.map(target => target.texture));
+            bindGroup = this.createCompositeBindGroup(resolved);
             this.compositeBindGroups.set(key, bindGroup);
         }
         return bindGroup;
@@ -946,7 +1421,7 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
     sweepGeometryGpu() {
         this.liveGeometryIds.clear();
         for (const item of this.items)
-            this.liveGeometryIds.add(item.visual.geometry.id);
+            this.liveGeometryIds.add(this.geometryKey(item.visual));
         for (const [id, gpu] of this.geometryGpu)
             if (!this.liveGeometryIds.has(id)) {
                 this.destroyGeometryGpu(gpu);
@@ -980,6 +1455,9 @@ class Animation2DRenderSystem extends RenderSystem2DBase {
         }
     }
 }
+function isFullyTransparent(visual) {
+    return visual.color[3] <= 0 && visual.effects.length === 0;
+}
 function writeBufferAligned(queue, buffer, source) {
     if (source.byteLength % 4 === 0) {
         queue.writeBuffer(buffer, 0, source);
@@ -1003,6 +1481,16 @@ function externalImageSize(source) {
         height: Math.max(1, isImage ? source.naturalHeight || source.height : source.height),
     };
 }
+function calculateMipLevelCount(width, height) {
+    return Math.floor(Math.log2(Math.max(1, width, height))) + 1;
+}
+function estimateRgba8MipChainBytes(width, height, mipLevelCount) {
+    let bytes = 0;
+    for (let level = 0; level < mipLevelCount; level++) {
+        bytes += Math.max(1, width >> level) * Math.max(1, height >> level) * 4;
+    }
+    return bytes;
+}
 function compareItems(a, b) {
     return a.visual.instanceId - b.visual.instanceId || a.visual.order - b.visual.order || a.entity.id - b.entity.id;
 }
@@ -1035,10 +1523,14 @@ function compositeOperationCode(operation) {
 }
 function effectKindCode(kind) {
     return kind === 'tint' ? 1 : kind === 'fill' ? 2 : kind === 'opacity' ? 3
-        : kind === 'color-matrix' ? 4 : kind === 'blur' ? 5 : 6;
+        : kind === 'color-matrix' ? 4 : kind === 'blur' ? 5 : kind === 'drop-shadow' ? 6
+            : kind === 'inner-feather' ? 7 : 8;
 }
 function visualNodeKey(visual) { return visual.nodeKey; }
-function buildVertices(positions) {
+function unresolvedCompositeError(visual, viewKey) {
+    return new AnimationFormatError('E_ANIMATION_INVALID_FORMAT', `Composite target for visual "${visual.nodeId}" could not be resolved in view "${viewKey}".`, `$runtime.visuals[${JSON.stringify(visual.nodeId)}].composite`);
+}
+function buildVertices(positions, explicitUvs) {
     let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
     for (let i = 0; i < positions.length; i += 2) {
         const x = positions[i], y = positions[i + 1];
@@ -1053,8 +1545,8 @@ function buildVertices(positions) {
         const x = positions[source], y = positions[source + 1];
         out[target++] = x;
         out[target++] = y;
-        out[target++] = (x - minX) / width;
-        out[target++] = 1 - (y - minY) / height;
+        out[target++] = explicitUvs?.[source] ?? (x - minX) / width;
+        out[target++] = explicitUvs?.[source + 1] ?? 1 - (y - minY) / height;
     }
     return out;
 }
@@ -1167,5 +1659,5 @@ class Animation2DExtensionRegistry {
     }
 }
 
-export { Animation2DComponent, Animation2DExtensionRegistry, Animation2DRenderSystem, Animation2DSystem, HAIYUE_ANIMATION_ASSET_TYPE, createAnimationAssetLoader };
+export { Animation2DComponent, Animation2DExtensionRegistry, Animation2DRenderSystem, Animation2DSystem, HAIYUE_ANIMATION_ASSET_TYPE, InteractionRuntime, createAnimationAssetLoader };
 //# sourceMappingURL=animation.js.map