canvasengine 2.0.0-beta.5 → 2.0.0-beta.51

package/src/components/DOMSprite.ts

@@ -0,0 +1,1040 @@
+import { isSignal, Signal } from "@signe/reactive";
+import { Subscription } from "rxjs";
+import { createComponent, Element, registerComponent } from "../engine/reactive";
+import { ComponentFunction } from "../engine/signal";
+import { arrayEquals, fps2ms, isBrowser, isFunction, preciseNow } from "../engine/utils";
+import { DisplayObjectProps } from "./types/DisplayObject";
+import { CanvasDOMElement, DOMElementProps } from "./DOMElement";
+import { OnHook } from "./DisplayObject";
+import { Tick } from "../directives/Scheduler";
+import {
+  AnimationFrames,
+  FrameOptions,
+  SpritesheetOptions,
+  TextureOptions,
+} from "./types/Spritesheet";
+
+export interface DOMSpriteFrame {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface DOMSpriteProps extends DOMElementProps {
+  image?: string;
+  rectangle?: DOMSpriteFrame | { value?: DOMSpriteFrame };
+  frames?: DOMSpriteFrame[];
+  frameIndex?: number;
+  fps?: number;
+  playing?: boolean;
+  loop?: boolean;
+  sheet?: {
+    definition?:
+    | DOMSpriteSheetDefinition
+    | { value?: DOMSpriteSheetDefinition }
+    | Signal<DOMSpriteSheetDefinition | undefined>
+    | Promise<DOMSpriteSheetDefinition>;
+    playing?: string;
+    params?: any;
+    onFinish?: () => void;
+  };
+  element?: "div" | "img";
+  class?: any;
+  style?: any;
+  attrs?: Record<string, any> & {
+    class?:
+    | string
+    | string[]
+    | Record<string, boolean>
+    | { items?: string[] }
+    | { value?: string | string[] | Record<string, boolean> };
+    style?:
+    | string
+    | Record<string, string | number>
+    | { value?: string | Record<string, string | number> };
+  };
+  onBeforeDestroy?: OnHook;
+  context?: {
+    tick?: Signal<Tick | null>;
+  };
+}
+
+const EVENTS = [
+  "click",
+  "mouseover",
+  "mouseout",
+  "mouseenter",
+  "mouseleave",
+  "mousemove",
+  "mouseup",
+  "mousedown",
+  "touchstart",
+  "touchend",
+  "touchmove",
+  "touchcancel",
+  "wheel",
+  "scroll",
+  "resize",
+  "focus",
+  "blur",
+  "change",
+  "input",
+  "submit",
+  "reset",
+  "keydown",
+  "keyup",
+  "keypress",
+  "contextmenu",
+  "drag",
+  "dragend",
+  "dragenter",
+  "dragleave",
+  "dragover",
+  "drop",
+  "dragstart",
+  "select",
+  "selectstart",
+  "selectend",
+  "selectall",
+  "selectnone",
+];
+
+type DOMSpriteTextureOptionsMerging = TextureOptions & {
+  spriteWidth: number;
+  spriteHeight: number;
+  image?: string;
+};
+
+type DOMSpriteFrameOptions = FrameOptions & DOMSpriteFrame;
+
+type DOMSpriteAnimationData = {
+  frames: DOMSpriteFrameOptions[];
+  animations: AnimationFrames;
+  params: any[];
+  data: DOMSpriteTextureOptionsMerging;
+  name: string;
+};
+
+type DOMSpriteSheetDefinition = SpritesheetOptions & {
+  image?: string;
+};
+
+export class CanvasDOMSprite extends CanvasDOMElement {
+  private frameIndex = 0;
+  private frames: DOMSpriteFrame[] = [];
+  private rectangle?: DOMSpriteFrame;
+  private image?: string;
+  private fps = 120;
+  private loop = true;
+  private playing = true;
+  private hasExternalFrameIndex = false;
+  private elapsed = 0;
+  private tickSignal?: Signal<Tick | null>;
+  private tickSubscription?: Subscription;
+  private sheetSubscriptions: Subscription[] = [];
+  private sheetDefinition?: DOMSpriteSheetDefinition;
+  private sheetAnimations: Map<string, DOMSpriteAnimationData> = new Map();
+  private sheetCurrentAnimation?: DOMSpriteAnimationData;
+  private sheetCurrentName?: string;
+  private sheetParams: any = {};
+  private sheetTime = 0;
+  private sheetFrameIndex = 0;
+  private sheetFinished = false;
+  private sheetLoadToken = 0;
+  private sheetOnFinish?: () => void;
+  private rafId?: number;
+  private lastRafTimestamp?: number;
+  private lastTickTimestamp?: number;
+  private renderElementType: "div" | "img" = "div";
+  private wrapperElementType: "div" | "img" = "div";
+  private isAnimating = false;
+  private playingSubscription?: Subscription;
+  private playingSignal?: Signal<boolean>;
+  private explicitWidth?: string;
+  private explicitHeight?: string;
+  private frameWidth = 0;
+  private frameHeight = 0;
+  private fitMode?: string;
+  private renderElement?: HTMLElement;
+  private isContained = false;
+
+  onInit(props: DOMElementProps) {
+    const spriteProps = props as DOMSpriteProps;
+    const hasSheet = spriteProps.sheet !== undefined;
+    const defaultElement: "div" | "img" = !hasSheet && spriteProps.image ? "img" : "div";
+    this.renderElementType = spriteProps.element ?? defaultElement;
+    const resolvedFit = this.resolveValue(spriteProps.objectFit);
+    this.fitMode = resolvedFit ?? undefined;
+    this.wrapperElementType =
+      this.fitMode === "contain" && this.renderElementType === "img"
+        ? "div"
+        : this.renderElementType;
+    const nextProps = this.mergeEventAttrs({ ...spriteProps, element: this.wrapperElementType });
+    this.tickSignal = nextProps.context?.tick;
+    this.applyProps(nextProps);
+    super.onInit(nextProps as any);
+    this.syncRenderElement();
+    this.applyDisplayProps(nextProps);
+    this.render();
+    this.updateAnimationLoop();
+  }
+
+  onMount(context: Element<CanvasDOMElement>) {
+    this.tickSignal = context.props.context?.tick;
+    super.onMount(context);
+    this.bindPlayingSignal(context);
+    this.bindSheetParams(context);
+    this.updateAnimationLoop();
+  }
+
+  onUpdate(props: DOMElementProps) {
+    const nextProps = this.mergeEventAttrs(props as DOMSpriteProps);
+    super.onUpdate(nextProps as any);
+    this.applyProps(nextProps);
+    this.syncRenderElement();
+    this.applyDisplayProps(nextProps);
+    this.render();
+    this.updateAnimationLoop();
+  }
+
+  async onDestroy(
+    parent: Element<CanvasDOMElement>,
+    afterDestroy: () => void
+  ): Promise<void> {
+    if (this.playingSubscription) {
+      this.playingSubscription.unsubscribe();
+      this.playingSubscription = undefined;
+    }
+    if (this.sheetSubscriptions.length > 0) {
+      this.sheetSubscriptions.forEach((sub) => sub.unsubscribe());
+      this.sheetSubscriptions = [];
+    }
+    this.stopAnimationLoop();
+    await super.onDestroy(parent, afterDestroy);
+  }
+
+  private resolveRectangle(
+    rectangle?: DOMSpriteFrame | { value?: DOMSpriteFrame } | Signal<DOMSpriteFrame | undefined>
+  ): DOMSpriteFrame | undefined {
+    if (!rectangle) return undefined;
+    const signalResolved = isSignal(rectangle as any)
+      ? (rectangle as Signal<DOMSpriteFrame | undefined>)()
+      : rectangle;
+    if (!signalResolved) return undefined;
+    const resolved = (signalResolved as any).value ?? signalResolved;
+    if (!resolved) return undefined;
+    return resolved as DOMSpriteFrame;
+  }
+
+  private resolveSheetDefinition(
+    definition?:
+      | DOMSpriteSheetDefinition
+      | { value?: DOMSpriteSheetDefinition }
+      | Signal<DOMSpriteSheetDefinition | undefined>
+      | Promise<DOMSpriteSheetDefinition>
+  ): DOMSpriteSheetDefinition | Promise<DOMSpriteSheetDefinition | undefined> | undefined {
+    if (!definition) return undefined;
+    const signalResolved = isSignal(definition as any)
+      ? (definition as Signal<DOMSpriteSheetDefinition | undefined>)()
+      : definition;
+    if (!signalResolved) return undefined;
+    return (signalResolved as any).value ?? signalResolved;
+  }
+
+  private async detectImageDimensions(
+    imagePath: string
+  ): Promise<{ width: number; height: number }> {
+    if (!isBrowser() || !imagePath) {
+      return { width: 0, height: 0 };
+    }
+    return new Promise((resolve, reject) => {
+      const img = new Image();
+      img.onload = () => resolve({ width: img.naturalWidth, height: img.naturalHeight });
+      img.onerror = () => reject(new Error(`Failed to load image: ${imagePath}`));
+      img.src = imagePath;
+    });
+  }
+
+  private async createSheetAnimations(definition: DOMSpriteSheetDefinition) {
+    this.sheetAnimations.clear();
+    const { textures } = definition;
+    if (!textures) return;
+
+    const parentProps: (keyof TextureOptions)[] = [
+      "width",
+      "height",
+      "framesHeight",
+      "framesWidth",
+      "rectWidth",
+      "rectHeight",
+      "offset",
+    ];
+
+    for (const animationName in textures) {
+      const baseOptions = parentProps.reduce(
+        (prev, val) => ({ ...prev, [val]: (definition as any)[val] }),
+        {}
+      );
+      const optionsTextures: DOMSpriteTextureOptionsMerging = {
+        ...baseOptions,
+        ...textures[animationName],
+        spriteWidth: 0,
+        spriteHeight: 0,
+      };
+      optionsTextures.image =
+        (textures[animationName] as any).image ?? definition.image;
+
+      const {
+        rectWidth,
+        rectHeight,
+        framesWidth = 1,
+        framesHeight = 1,
+        image,
+      } = optionsTextures;
+
+      let width = optionsTextures.width || 0;
+      let height = optionsTextures.height || 0;
+
+      if (image && ((!width || width <= 0) || (!height || height <= 0))) {
+        const dimensions = await this.detectImageDimensions(image);
+        if (!width || width <= 0) {
+          width = dimensions.width;
+        }
+        if (!height || height <= 0) {
+          height = dimensions.height;
+        }
+      }
+
+      if (!width || !height || !framesWidth || !framesHeight) {
+        continue;
+      }
+
+      optionsTextures.width = width;
+      optionsTextures.height = height;
+      optionsTextures.spriteWidth = rectWidth ? rectWidth : width / framesWidth;
+      optionsTextures.spriteHeight = rectHeight ? rectHeight : height / framesHeight;
+
+      this.sheetAnimations.set(animationName, {
+        frames: [],
+        name: animationName,
+        animations: textures[animationName].animations,
+        params: [],
+        data: optionsTextures,
+      });
+    }
+  }
+
+  private async setSheetDefinition(
+    definition?: DOMSpriteSheetDefinition | Promise<DOMSpriteSheetDefinition>
+  ) {
+    const token = ++this.sheetLoadToken;
+    if (!definition) {
+      this.sheetDefinition = undefined;
+      this.sheetAnimations.clear();
+      this.sheetCurrentAnimation = undefined;
+      this.sheetCurrentName = undefined;
+      return;
+    }
+
+    const resolved = await definition;
+    if (token !== this.sheetLoadToken) return;
+    if (!resolved) {
+      this.sheetDefinition = undefined;
+      this.sheetAnimations.clear();
+      this.sheetCurrentAnimation = undefined;
+      this.sheetCurrentName = undefined;
+      return;
+    }
+    this.sheetDefinition = resolved;
+    if (resolved.image) {
+      this.image = resolved.image;
+    }
+
+    await this.createSheetAnimations(resolved);
+
+    const textureKeys = resolved.textures ? Object.keys(resolved.textures) : [];
+    const fallbackName =
+      this.sheetCurrentName ||
+      (textureKeys.includes("stand") ? "stand" : textureKeys[0]) ||
+      undefined;
+    if (fallbackName) {
+      this.playSheet(fallbackName, [this.sheetParams]);
+    }
+    this.render();
+    this.updateAnimationLoop();
+  }
+
+  private playSheet(name: string, params: any[] = []) {
+    const animParams = this.sheetCurrentAnimation?.params;
+    if (this.sheetCurrentAnimation && this.sheetCurrentAnimation.name === name) {
+      if (arrayEquals(params, animParams || [])) return;
+    }
+
+    const animation = this.sheetAnimations.get(name);
+    if (!animation) {
+      throw new Error(
+        `Impossible to play the ${name} animation because it doesn't exist on the spritesheet`
+      );
+    }
+
+    const cloneParams = structuredClone(params);
+    let animations: any = animation.animations;
+    animations = isFunction(animations) ? (animations as Function)(...cloneParams) : animations;
+
+    animation.frames = [];
+    animation.params = cloneParams;
+    this.sheetCurrentAnimation = animation;
+    this.sheetCurrentName = name;
+    this.sheetTime = 0;
+    this.sheetFrameIndex = 0;
+    this.sheetFinished = false;
+
+    const data = animation.data;
+    const spriteWidth = data.spriteWidth;
+    const spriteHeight = data.spriteHeight;
+    const offsetX = data.offset?.x ?? 0;
+    const offsetY = data.offset?.y ?? 0;
+
+    for (const container of animations as FrameOptions[][]) {
+      for (const frame of container) {
+        const frameX = frame.frameX ?? 0;
+        const frameY = frame.frameY ?? 0;
+        animation.frames.push({
+          ...frame,
+          x: frameX * spriteWidth + offsetX,
+          y: frameY * spriteHeight + offsetY,
+          width: spriteWidth,
+          height: spriteHeight,
+        });
+      }
+    }
+
+    this.render();
+    this.updateAnimationLoop();
+  }
+
+  private getCurrentSheetFrame(): DOMSpriteFrame | null {
+    if (!this.sheetCurrentAnimation || this.sheetCurrentAnimation.frames.length === 0) {
+      return null;
+    }
+    return this.sheetCurrentAnimation.frames[this.sheetFrameIndex] ?? null;
+  }
+
+  private advanceSheet(tick: Tick) {
+    if (!this.playing || !this.sheetCurrentAnimation) return;
+
+    const frames = this.sheetCurrentAnimation.frames;
+    if (frames.length <= 1) return;
+
+    const baseFps = this.fps > 0 ? this.fps : 60;
+    let deltaRatio = 0;
+    if (tick.deltaTime) {
+      deltaRatio = tick.deltaTime / fps2ms(baseFps);
+    } else if (typeof tick.deltaRatio === "number") {
+      deltaRatio = tick.deltaRatio * (baseFps / 60);
+    }
+
+    const nextFrame = frames[this.sheetFrameIndex + 1];
+    if (!nextFrame) {
+      if (this.loop) {
+        this.sheetTime = 0;
+        this.sheetFrameIndex = 0;
+        this.applyFrame(frames[0]);
+        return;
+      } else if (!this.sheetFinished) {
+        this.sheetFinished = true;
+        if (this.sheetOnFinish) this.sheetOnFinish();
+      }
+      this.applyFrame(frames[frames.length - 1]);
+      return;
+    }
+
+    this.sheetTime += deltaRatio || 0;
+    if (this.sheetTime >= nextFrame.time) {
+      this.sheetFrameIndex += 1;
+    }
+    this.applyFrame(frames[this.sheetFrameIndex]);
+  }
+
+  private mergeEventAttrs(props: DOMSpriteProps): DOMSpriteProps {
+    let merged = props.attrs ? { ...props.attrs } : undefined;
+    for (const event of EVENTS) {
+      const handler = (props as any)[event];
+      if (handler && !merged?.[event]) {
+        if (!merged) merged = {};
+        merged[event] = handler;
+      }
+    }
+    if (props.class !== undefined) {
+      if (!merged) merged = {};
+      if (merged.class) {
+        merged.class = [props.class, merged.class];
+      } else {
+        merged.class = props.class;
+      }
+    }
+    if (props.style !== undefined) {
+      if (!merged) merged = {};
+      if (
+        typeof merged.style === "object"
+        && merged.style !== null
+        && typeof props.style === "object"
+        && props.style !== null
+      ) {
+        merged.style = { ...merged.style, ...props.style };
+      } else if (merged.style === undefined) {
+        merged.style = props.style;
+      } else if (typeof merged.style === "string" && typeof props.style === "string") {
+        merged.style = `${merged.style}; ${props.style}`;
+      } else {
+        merged.style = props.style;
+      }
+    }
+    if (!merged) return props;
+    return { ...props, attrs: merged };
+  }
+
+  private applyProps(props: DOMSpriteProps) {
+    if (props.image !== undefined) {
+      this.image = isSignal(props.image as any) ? (props.image as any)() : props.image;
+    }
+    if (props.rectangle !== undefined) {
+      this.rectangle = this.resolveRectangle(props.rectangle);
+    }
+    if (props.frames !== undefined) {
+      const resolvedFrames = isSignal(props.frames as any)
+        ? (props.frames as any)()
+        : props.frames;
+      this.frames = resolvedFrames ?? [];
+    }
+    if (props.sheet !== undefined) {
+      const resolvedSheet = isSignal(props.sheet as any)
+        ? (props.sheet as any)()
+        : props.sheet;
+      if (resolvedSheet?.definition !== undefined) {
+        const resolvedDefinition = this.resolveSheetDefinition(resolvedSheet.definition);
+        if (resolvedDefinition instanceof Promise) {
+          void this.setSheetDefinition(resolvedDefinition);
+        } else if (resolvedDefinition && resolvedDefinition !== this.sheetDefinition) {
+          void this.setSheetDefinition(resolvedDefinition);
+        }
+      }
+      if (resolvedSheet?.params !== undefined) {
+        this.sheetParams = { ...this.sheetParams, ...resolvedSheet.params };
+      }
+      if (resolvedSheet?.playing !== undefined) {
+        this.sheetCurrentName = resolvedSheet.playing;
+      }
+      if (resolvedSheet?.onFinish !== undefined) {
+        this.sheetOnFinish = resolvedSheet.onFinish;
+      }
+      if (this.sheetAnimations.size > 0 && this.sheetCurrentName) {
+        this.playSheet(this.sheetCurrentName, [this.sheetParams]);
+      }
+    }
+    if (props.frameIndex !== undefined) {
+      const isFrameIndexSignal = isSignal(props.frameIndex as any);
+      const resolvedIndex = isFrameIndexSignal
+        ? (props.frameIndex as any)()
+        : props.frameIndex;
+      if (resolvedIndex !== undefined) {
+        this.frameIndex = resolvedIndex;
+      }
+      this.hasExternalFrameIndex = isFrameIndexSignal;
+    }
+    if (props.fps !== undefined) {
+      const resolvedFps = isSignal(props.fps as any) ? (props.fps as any)() : props.fps;
+      if (resolvedFps !== undefined) {
+        this.fps = resolvedFps;
+      }
+    }
+    if (props.playing !== undefined) {
+      const resolvedPlaying = isSignal(props.playing as any)
+        ? (props.playing as any)()
+        : props.playing;
+      this.playing = resolvedPlaying === true;
+      if (!this.playing) {
+        this.elapsed = 0;
+      }
+    }
+    if (props.loop !== undefined) {
+      const resolvedLoop = isSignal(props.loop as any) ? (props.loop as any)() : props.loop;
+      if (resolvedLoop !== undefined) {
+        this.loop = resolvedLoop;
+      }
+    }
+    if (props.objectFit !== undefined) {
+      const resolvedFit = this.resolveValue(props.objectFit);
+      this.fitMode = resolvedFit ?? undefined;
+    }
+  }
+
+  private resolveValue<T>(value: T | Signal<T> | { value?: T } | undefined): T | undefined {
+    if (value === undefined) return undefined;
+    const resolved = isSignal(value as any) ? (value as any)() : value;
+    if (resolved && typeof resolved === "object" && "value" in (resolved as any)) {
+      return (resolved as any).value as T;
+    }
+    return resolved as T;
+  }
+
+  private resolvePoint(
+    value: DOMSpriteProps["scale"] | DOMSpriteProps["anchor"] | DOMSpriteProps["skew"] | DOMSpriteProps["pivot"]
+  ): { x: number; y: number } | undefined {
+    const resolved = this.resolveValue<any>(value as any);
+    if (resolved === undefined || resolved === null) return undefined;
+    if (typeof resolved === "number") {
+      return { x: resolved, y: resolved };
+    }
+    if (Array.isArray(resolved)) {
+      const [x, y] = resolved;
+      return { x: x ?? 0, y: y ?? x ?? 0 };
+    }
+    if (typeof resolved === "object") {
+      return { x: resolved.x ?? 0, y: resolved.y ?? 0 };
+    }
+    return undefined;
+  }
+
+  private resolveSize(value: DOMSpriteProps["width"] | DOMSpriteProps["height"]): string | undefined {
+    const resolved = this.resolveValue<any>(value as any);
+    if (resolved === undefined || resolved === null) return undefined;
+    if (typeof resolved === "number") return `${resolved}px`;
+    if (typeof resolved === "string") return resolved;
+    return undefined;
+  }
+
+  private resolvePixelSize(value?: string): number | undefined {
+    if (!value) return undefined;
+    if (value.endsWith("px")) {
+      const parsed = parseFloat(value);
+      return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    if (/^\d+(\.\d+)?$/.test(value)) {
+      const parsed = parseFloat(value);
+      return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    return undefined;
+  }
+
+  private toCssColor(tint: number): string {
+    const clamped = Math.max(0, Math.min(0xffffff, tint));
+    return `#${clamped.toString(16).padStart(6, "0")}`;
+  }
+
+  private applyDisplayProps(props: DOMSpriteProps) {
+    if (!this.element) return;
+
+    if (props.width !== undefined) {
+      this.explicitWidth = this.resolveSize(props.width);
+    } else {
+      this.explicitWidth = undefined;
+    }
+    if (props.height !== undefined) {
+      this.explicitHeight = this.resolveSize(props.height);
+    } else {
+      this.explicitHeight = undefined;
+    }
+    if (this.explicitWidth !== undefined) {
+      this.element.style.width = this.explicitWidth;
+    }
+    if (this.explicitHeight !== undefined) {
+      this.element.style.height = this.explicitHeight;
+    }
+
+    if (props.alpha !== undefined) {
+      const alpha = this.resolveValue(props.alpha);
+      if (alpha !== undefined) {
+        this.element.style.opacity = String(alpha);
+      }
+    }
+
+    if (props.visible !== undefined) {
+      const visible = this.resolveValue(props.visible);
+      this.element.style.display = visible === false ? "none" : "";
+    }
+
+    if (props.zIndex !== undefined) {
+      const zIndex = this.resolveValue(props.zIndex);
+      if (zIndex !== undefined) {
+        this.element.style.zIndex = String(zIndex);
+      }
+    }
+
+    if (props.cursor !== undefined) {
+      const cursor = this.resolveValue(props.cursor);
+      if (cursor !== undefined) {
+        this.element.style.cursor = String(cursor);
+      }
+    }
+
+    if (props.tint !== undefined) {
+      const tint = this.resolveValue(props.tint);
+      if (typeof tint === "number") {
+        this.element.style.filter = `drop-shadow(0 0 0 ${this.toCssColor(tint)})`;
+      }
+    }
+
+    const hasTransformProps = [
+      props.x,
+      props.y,
+      props.scale,
+      props.rotation,
+      props.angle,
+      props.skew,
+      props.roundPixels,
+    ].some((value) => value !== undefined);
+
+    if (hasTransformProps) {
+      let x = this.resolveValue(props.x) ?? 0;
+      let y = this.resolveValue(props.y) ?? 0;
+      const roundPixels = this.resolveValue(props.roundPixels);
+      if (roundPixels) {
+        x = Math.round(x);
+        y = Math.round(y);
+      }
+
+      const scale = this.resolvePoint(props.scale) ?? { x: 1, y: 1 };
+      const skew = this.resolvePoint(props.skew);
+
+      const angle = this.resolveValue(props.angle);
+      const rotation = this.resolveValue(props.rotation);
+      const rotationDeg = angle !== undefined
+        ? angle
+        : rotation !== undefined
+          ? (rotation * 180) / Math.PI
+          : 0;
+
+      const transformParts = [
+        `translate3d(${x}px, ${y}px, 0)`,
+      ];
+
+      if (rotationDeg !== 0) {
+        transformParts.push(`rotate(${rotationDeg}deg)`);
+      }
+
+      if (skew) {
+        const skewX = (skew.x * 180) / Math.PI;
+        const skewY = (skew.y * 180) / Math.PI;
+        if (skewX !== 0 || skewY !== 0) {
+          transformParts.push(`skew(${skewX}deg, ${skewY}deg)`);
+        }
+      }
+
+      if (scale.x !== 1 || scale.y !== 1) {
+        transformParts.push(`scale(${scale.x}, ${scale.y})`);
+      }
+
+      this.element.style.transform = transformParts.join(" ");
+
+    }
+
+    const pivot = this.resolvePoint(props.pivot);
+    const anchor = this.resolvePoint(props.anchor);
+    if (pivot) {
+      this.element.style.transformOrigin = `${pivot.x}px ${pivot.y}px`;
+    } else if (anchor) {
+      this.element.style.transformOrigin = `${anchor.x * 100}% ${anchor.y * 100}%`;
+    }
+  }
+
+  private syncRenderElement() {
+    if (!this.element) return;
+    if (this.fitMode === "contain" && !(this.element instanceof HTMLImageElement)) {
+      if (!this.isContained) {
+        const inner = document.createElement(this.renderElementType);
+        this.element.style.position = "relative";
+        this.element.style.overflow = "hidden";
+        inner.style.position = "absolute";
+        inner.style.left = "0";
+        inner.style.top = "0";
+        inner.style.transformOrigin = "0 0";
+        this.element.appendChild(inner);
+        this.renderElement = inner;
+        this.isContained = true;
+      }
+      return;
+    }
+
+    if (this.isContained) {
+      if (this.renderElement && this.renderElement !== this.element) {
+        this.renderElement.remove();
+      }
+      this.renderElement = undefined;
+      this.isContained = false;
+    }
+  }
+
+  private getRenderElement() {
+    return this.renderElement ?? this.element;
+  }
+
+  private applyContainScale() {
+    if (!this.isContained) return;
+    const target = this.getRenderElement();
+    if (!target || !this.element) return;
+    if (this.frameWidth <= 0 || this.frameHeight <= 0) return;
+
+    const containerWidth =
+      this.resolvePixelSize(this.explicitWidth) ?? this.element.clientWidth;
+    const containerHeight =
+      this.resolvePixelSize(this.explicitHeight) ?? this.element.clientHeight;
+
+    if (!containerWidth || !containerHeight) return;
+
+    const scale = Math.min(containerWidth / this.frameWidth, containerHeight / this.frameHeight);
+    if (!Number.isFinite(scale) || scale <= 0) return;
+    target.style.transform = `scale(${scale})`;
+  }
+
+  private bindPlayingSignal(context: Element<CanvasDOMElement>) {
+    const playingValue = context.propObservables?.playing as any;
+    if (!playingValue || !isSignal(playingValue)) return;
+    if (this.playingSignal === playingValue) return;
+
+    if (this.playingSubscription) {
+      this.playingSubscription.unsubscribe();
+      this.playingSubscription = undefined;
+    }
+
+    this.playingSignal = playingValue;
+    this.playing = playingValue();
+    this.playingSubscription = playingValue.observable.subscribe((value) => {
+      this.playing = value === true;
+      if (!this.playing) {
+        this.elapsed = 0;
+      }
+      this.updateAnimationLoop();
+    });
+  }
+
+  private bindSheetParams(context: Element<CanvasDOMElement>) {
+    const sheetProps = context.propObservables?.sheet as any;
+    const params = sheetProps?.params as any;
+    if (!params || typeof params !== "object") return;
+    for (const key in params) {
+      const value = params[key];
+      if (!isSignal(value)) continue;
+      this.sheetSubscriptions.push(
+        value.observable.subscribe((nextValue) => {
+          this.sheetParams = { ...this.sheetParams, [key]: nextValue };
+          if (this.sheetCurrentName) {
+            this.playSheet(this.sheetCurrentName, [this.sheetParams]);
+          }
+        })
+      );
+    }
+  }
+
+  private getFrames(): DOMSpriteFrame[] {
+    if (this.frames && this.frames.length > 0) return this.frames;
+    if (this.rectangle) return [this.rectangle];
+    return [];
+  }
+
+  private normalizeIndex(index: number, length: number) {
+    if (length <= 0) return 0;
+    if (this.loop) {
+      const mod = index % length;
+      return mod < 0 ? mod + length : mod;
+    }
+    if (index < 0) return 0;
+    if (index >= length) return length - 1;
+    return index;
+  }
+
+  private render() {
+    if (!this.element) return;
+    const target = this.getRenderElement();
+    const sheetFrame = this.getCurrentSheetFrame();
+    if (sheetFrame) {
+      this.applyFrame(sheetFrame);
+      return;
+    }
+    const frames = this.getFrames();
+    if (frames.length === 0) {
+      if (this.renderElementType === "img" && this.image && target) {
+        (target as HTMLImageElement).src = this.image;
+      } else if (this.image) {
+        target.style.backgroundImage = `url("${this.image}")`;
+      }
+      return;
+    }
+
+    const normalizedIndex = this.normalizeIndex(this.frameIndex, frames.length);
+    if (normalizedIndex !== this.frameIndex && !this.loop) {
+      this.frameIndex = normalizedIndex;
+    }
+
+    const frame = frames[normalizedIndex];
+    this.applyFrame(frame);
+  }
+
+  private applyFrame(frame: DOMSpriteFrame) {
+    if (!this.element) return;
+    const target = this.getRenderElement();
+    if (!target) return;
+    this.frameWidth = frame.width;
+    this.frameHeight = frame.height;
+    if (this.fitMode === "contain") {
+      target.style.width = `${frame.width}px`;
+      target.style.height = `${frame.height}px`;
+    } else {
+      target.style.width = this.explicitWidth ?? `${frame.width}px`;
+      target.style.height = this.explicitHeight ?? `${frame.height}px`;
+    }
+
+    const x = frame.x ?? 0;
+    const y = frame.y ?? 0;
+
+    if (this.renderElementType === "img") {
+      const img = target as HTMLImageElement;
+      if (this.image) {
+        img.src = this.image;
+      }
+      img.style.objectFit = "none";
+      img.style.objectPosition = `-${x}px -${y}px`;
+      this.applyContainScale();
+      return;
+    }
+
+    if (this.image) {
+      target.style.backgroundImage = `url("${this.image}")`;
+    }
+    target.style.backgroundRepeat = "no-repeat";
+    target.style.backgroundPosition = `-${x}px -${y}px`;
+    this.applyContainScale();
+  }
+
+  private updateAnimationLoop() {
+    const sheetFrames = this.sheetCurrentAnimation?.frames ?? [];
+    const shouldAnimate = this.sheetCurrentAnimation
+      ? this.playing && sheetFrames.length > 1
+      : this.playing &&
+      !this.hasExternalFrameIndex &&
+      this.getFrames().length > 1 &&
+      this.fps > 0;
+
+    if (shouldAnimate) {
+      this.startAnimationLoop();
+    } else {
+      this.stopAnimationLoop();
+    }
+  }
+
+  private startAnimationLoop() {
+    if (this.tickSubscription || this.rafId !== undefined) {
+      this.stopAnimationLoop();
+    }
+    this.isAnimating = true;
+    this.elapsed = 0;
+    this.lastTickTimestamp = undefined;
+
+    if (this.tickSignal?.observable) {
+      this.tickSubscription = (this.tickSignal.observable as any).subscribe((result: any) => {
+        const tick = result?.value ?? result;
+        if (!tick) return;
+        if (this.sheetCurrentAnimation) {
+          this.advanceSheet(tick);
+          return;
+        }
+        let deltaTime = tick.deltaTime || 0;
+        if (deltaTime <= 0) {
+          const now = preciseNow();
+          if (this.lastTickTimestamp === undefined) {
+            this.lastTickTimestamp = now;
+            return;
+          }
+          deltaTime = now - this.lastTickTimestamp;
+          this.lastTickTimestamp = now;
+        }
+        if (deltaTime > 0) {
+          this.advance(deltaTime);
+        }
+      });
+      return;
+    }
+
+    const step = (timestamp: number) => {
+      if (!this.playing || this.hasExternalFrameIndex) {
+        this.stopAnimationLoop();
+        return;
+      }
+      if (this.lastRafTimestamp === undefined) {
+        this.lastRafTimestamp = timestamp;
+      }
+      const delta = timestamp - this.lastRafTimestamp;
+      this.lastRafTimestamp = timestamp;
+      if (this.sheetCurrentAnimation) {
+        this.advanceSheet({
+          timestamp,
+          deltaTime: delta,
+          frame: 0,
+          deltaRatio: delta / fps2ms(this.fps),
+        });
+      } else {
+        this.advance(delta);
+      }
+
+      if (isBrowser()) {
+        this.rafId = window.requestAnimationFrame(step);
+      } else {
+        this.rafId = setTimeout(() => {
+          step(preciseNow());
+        }, fps2ms(this.fps)) as unknown as number;
+      }
+    };
+
+    if (isBrowser()) {
+      this.rafId = window.requestAnimationFrame(step);
+    } else {
+      this.rafId = setTimeout(() => {
+        step(preciseNow());
+      }, fps2ms(this.fps)) as unknown as number;
+    }
+  }
+
+  private stopAnimationLoop() {
+    this.isAnimating = false;
+    if (this.tickSubscription) {
+      this.tickSubscription.unsubscribe();
+      this.tickSubscription = undefined;
+    }
+    if (this.rafId !== undefined) {
+      if (isBrowser()) {
+        window.cancelAnimationFrame(this.rafId);
+      } else {
+        clearTimeout(this.rafId);
+      }
+      this.rafId = undefined;
+      this.lastRafTimestamp = undefined;
+    }
+    this.lastTickTimestamp = undefined;
+  }
+
+  private advance(deltaTime: number) {
+    const frames = this.getFrames();
+    if (!this.playing || frames.length <= 1 || this.fps <= 0) return;
+
+    this.elapsed += deltaTime;
+    const frameDuration = fps2ms(this.fps);
+
+    while (this.elapsed >= frameDuration) {
+      this.elapsed -= frameDuration;
+      this.frameIndex += 1;
+      if (!this.loop && this.frameIndex >= frames.length) {
+        this.frameIndex = frames.length - 1;
+        break;
+      }
+    }
+
+    this.render();
+  }
+}
+
+registerComponent("DOMSprite", CanvasDOMSprite);
+
+export const DOMSprite: ComponentFunction<DOMSpriteProps> = (props) => {
+  return createComponent("DOMSprite", props);
+};