@haiyue/extensions 0.1.0

package/dist/tween/Tween2DComponent.d.ts

@@ -0,0 +1,70 @@
+import { Component } from '@haiyue/engine';
+import { Easing, type EasingFunction } from '@haiyue/engine/tween';
+export type Tween2DEasingName = keyof typeof Easing;
+export interface Tween2DProperties {
+    x?: number;
+    y?: number;
+    rotation?: number;
+    scaleX?: number;
+    scaleY?: number;
+}
+export interface Tween2DComponentOptions {
+    from?: Tween2DProperties;
+    to?: Tween2DProperties;
+    duration?: number;
+    delay?: number;
+    easing?: Tween2DEasingName | EasingFunction | string;
+    removeOnComplete?: boolean;
+}
+export declare class Tween2DComponent extends Component {
+    static UniqueCheckType: number;
+    static UniqueSymbol: symbol;
+    static editor: {
+        fields: {
+            from: {
+                type: string;
+                label: string;
+                rows: number;
+            };
+            to: {
+                type: string;
+                label: string;
+                rows: number;
+            };
+            duration: {
+                type: string;
+                label: string;
+                min: number;
+                step: number;
+            };
+            delay: {
+                type: string;
+                label: string;
+                min: number;
+                step: number;
+            };
+            easing: {
+                type: string;
+                label: string;
+            };
+            removeOnComplete: {
+                type: string;
+                label: string;
+            };
+        };
+    };
+    from: Tween2DProperties | null;
+    to: Tween2DProperties;
+    duration: number;
+    delay: number;
+    easing: Tween2DEasingName | EasingFunction | string;
+    removeOnComplete: boolean;
+    elapsed: number;
+    started: boolean;
+    completed: boolean;
+    private _resolvedFrom;
+    constructor(options?: Tween2DComponentOptions);
+    resolveFrom(current: Tween2DProperties): Tween2DProperties;
+    getEasingFunction(): EasingFunction;
+    clone(): Tween2DComponent;
+}

package/dist/tween/Tween2DSystem.d.ts

@@ -0,0 +1,12 @@
+import { System, type World } from '@haiyue/engine';
+export interface Tween2DSystemOptions {
+    priority?: number;
+}
+export declare class Tween2DSystem extends System {
+    private readonly completedEntities;
+    private readonly transformScratch;
+    constructor(options?: Tween2DSystemOptions);
+    update(world: World, _time: number, delta: number): this;
+    private updateEntity;
+    private apply;
+}

package/dist/tween.d.ts

@@ -0,0 +1,4 @@
+export { Tween2DComponent } from './tween/Tween2DComponent';
+export type { Tween2DComponentOptions, Tween2DEasingName, Tween2DProperties } from './tween/Tween2DComponent';
+export { Tween2DSystem } from './tween/Tween2DSystem';
+export type { Tween2DSystemOptions } from './tween/Tween2DSystem';

package/dist/tween.js

@@ -0,0 +1,138 @@
+import { Component, System, Transform2D } from '@haiyue/engine';
+import { UniqueCheckType } from '@haiyue/engine/ecs';
+import { Easing } from '@haiyue/engine/tween';
+
+class Tween2DComponent extends Component {
+    static UniqueCheckType = UniqueCheckType.SYMBOL | UniqueCheckType.REPLACE;
+    static UniqueSymbol = Symbol.for('Tween2DComponent');
+    static editor = {
+        fields: {
+            from: { type: 'json', label: 'From JSON', rows: 4 },
+            to: { type: 'json', label: 'To JSON', rows: 4 },
+            duration: { type: 'number', label: 'Duration ms', min: 0, step: 16 },
+            delay: { type: 'number', label: 'Delay ms', min: 0, step: 16 },
+            easing: { type: 'text', label: 'Easing' },
+            removeOnComplete: { type: 'boolean', label: 'Remove On Complete' },
+        },
+    };
+    from;
+    to;
+    duration;
+    delay;
+    easing;
+    removeOnComplete;
+    elapsed = 0;
+    started = false;
+    completed = false;
+    _resolvedFrom = {};
+    constructor(options = {}) {
+        super('Tween2DComponent');
+        this.from = options.from ? { ...options.from } : null;
+        this.to = { ...(options.to ?? {}) };
+        this.duration = Math.max(0, options.duration ?? 160);
+        this.delay = Math.max(0, options.delay ?? 0);
+        this.easing = options.easing ?? 'cubicOut';
+        this.removeOnComplete = options.removeOnComplete ?? true;
+    }
+    resolveFrom(current) {
+        if (this.started)
+            return this._resolvedFrom;
+        this._resolvedFrom = {};
+        for (const key of Object.keys(this.to)) {
+            this._resolvedFrom[key] = this.from?.[key] ?? current[key] ?? 0;
+        }
+        return this._resolvedFrom;
+    }
+    getEasingFunction() {
+        if (typeof this.easing === 'function')
+            return this.easing;
+        return Easing[this.easing] ?? Easing.linear;
+    }
+    clone() {
+        return new Tween2DComponent({
+            ...(this.from ? { from: { ...this.from } } : {}),
+            to: { ...this.to },
+            duration: this.duration,
+            delay: this.delay,
+            easing: this.easing,
+            removeOnComplete: this.removeOnComplete,
+        });
+    }
+}
+
+function lerp(from, to, t) {
+    return from + (to - from) * t;
+}
+function readTransform(transform, out) {
+    out.x = transform.x;
+    out.y = transform.y;
+    out.rotation = transform.rotation;
+    out.scaleX = transform.scaleX;
+    out.scaleY = transform.scaleY;
+    return out;
+}
+class Tween2DSystem extends System {
+    completedEntities = [];
+    transformScratch = { x: 0, y: 0, rotation: 0, scaleX: 1, scaleY: 1 };
+    constructor(options = {}) {
+        super({ all: [Tween2DComponent, Transform2D] });
+        this.name = 'Tween2DSystem';
+        if (options.priority !== undefined)
+            this.priority = options.priority;
+    }
+    update(world, _time, delta) {
+        if (this.disabled)
+            return this;
+        this.completedEntities.length = 0;
+        const entities = this.entitySet.get(world);
+        if (entities) {
+            for (const entity of entities)
+                this.updateEntity(entity, delta);
+        }
+        for (const entity of this.completedEntities) {
+            const tween = entity.getComponent(Tween2DComponent);
+            if (tween?.completed && tween.removeOnComplete)
+                entity.removeComponent(tween);
+        }
+        return this;
+    }
+    updateEntity(entity, delta) {
+        const tween = entity.getComponent(Tween2DComponent);
+        const transform = entity.getComponent(Transform2D);
+        if (!tween || !transform || tween.completed)
+            return;
+        tween.elapsed += delta;
+        if (tween.elapsed < tween.delay)
+            return;
+        const from = tween.resolveFrom(readTransform(transform, this.transformScratch));
+        if (!tween.started) {
+            tween.started = true;
+            this.apply(transform, from, 0);
+        }
+        const duration = Math.max(1, tween.duration);
+        const raw = Math.min((tween.elapsed - tween.delay) / duration, 1);
+        const progress = tween.getEasingFunction()(raw);
+        this.apply(transform, from, progress, tween.to);
+        if (raw >= 1) {
+            tween.completed = true;
+            this.apply(transform, from, 1, tween.to);
+            if (tween.removeOnComplete)
+                this.completedEntities.push(entity);
+        }
+    }
+    apply(transform, from, progress, to = from) {
+        if (to.x !== undefined)
+            transform.x = lerp(from.x ?? transform.x, to.x, progress);
+        if (to.y !== undefined)
+            transform.y = lerp(from.y ?? transform.y, to.y, progress);
+        if (to.rotation !== undefined)
+            transform.rotation = lerp(from.rotation ?? transform.rotation, to.rotation, progress);
+        if (to.scaleX !== undefined)
+            transform.scaleX = lerp(from.scaleX ?? transform.scaleX, to.scaleX, progress);
+        if (to.scaleY !== undefined)
+            transform.scaleY = lerp(from.scaleY ?? transform.scaleY, to.scaleY, progress);
+    }
+}
+
+export { Tween2DComponent, Tween2DSystem };
+//# sourceMappingURL=tween.js.map

package/dist/utils/RenderSystem2DBase.d.ts

@@ -0,0 +1,42 @@
+import { type EntityHierarchyDisabledCache, type FrameData, type IEngine, type RenderCommandContext } from '@haiyue/engine/extension-authoring';
+import { Camera2D } from '@haiyue/engine/components';
+import { Entity, System, type SystemQuery } from '@haiyue/engine/ecs';
+import { type Object2DGpu } from './render2dGpu';
+export interface RenderSystem2DBaseOptions {
+    loadOp?: 'clear' | 'load';
+    priority?: number;
+}
+export declare abstract class RenderSystem2DBase extends System {
+    protected readonly engine: IEngine;
+    protected cameraEntity: Entity;
+    protected readonly disabledHierarchyCache: EntityHierarchyDisabledCache;
+    protected readonly liveEntityIds: Set<number>;
+    loadOp: 'clear' | 'load';
+    readonly recoveryLabel: string;
+    readonly recoverySource: {
+        kind: 'component-render-system';
+        system: string;
+    };
+    private readonly unregisterRecovery;
+    protected constructor(rule: SystemQuery, engine: IEngine, cameraEntity: Entity, options?: RenderSystem2DBaseOptions, name?: string);
+    setCameraEntity(cameraEntity: Entity): this;
+    protected getCamera2D(context?: RenderCommandContext): Camera2D | null;
+    protected getFrameData(context: RenderCommandContext): FrameData;
+    protected computeCameraViewProjection(camera: Camera2D, context?: RenderCommandContext): Float32Array;
+    protected writeCameraBuffer(queue: GPUQueue, buffer: GPUBuffer, context?: RenderCommandContext): boolean;
+    protected getWorldMatrix2D(entity: Entity, context: RenderCommandContext): Float32Array;
+    private getCameraEntity;
+    protected isEntityRenderable(entity: Entity): boolean;
+    protected beginLiveEntityTracking(): Set<number>;
+    protected markEntityLive(entity: Entity | number): void;
+    protected createObjectGpu(layout: GPUBindGroupLayout): Object2DGpu;
+    protected destroyObjectGpu(objectGpu: Object2DGpu): void;
+    protected getOrCreateEntityGpu<T>(cache: Map<number, T>, entity: Entity, create: () => T): T;
+    protected releaseEntityGpuEntriesNotIn<T>(cache: Map<number, T>, destroy: (gpu: T) => void, liveEntities?: ReadonlySet<number>): void;
+    protected destroyEntityGpuEntries<T>(cache: Map<number, T>, destroy: (gpu: T) => void): void;
+    suspendForDeviceLoss(): void;
+    recoverGpuResource(_device: GPUDevice, signal: AbortSignal): void;
+    destroy(): this;
+    protected abstract releaseGpuResourcesForRecovery(): void;
+    protected restoreGpuResourcesAfterRecovery(): void;
+}

package/dist/utils/arrayAccess.d.ts

@@ -0,0 +1,4 @@
+/** Reads an element whose presence is an internal runtime invariant. */
+export declare function requiredItemAt<T>(values: ArrayLike<T>, index: number, label: string): T;
+/** Reads a number whose presence is an internal runtime invariant. */
+export declare function requiredNumberAt(values: ArrayLike<number>, index: number, label: string): number;

package/dist/utils/camera2d.d.ts

@@ -0,0 +1,12 @@
+import { Camera2D, Entity } from '@haiyue/engine';
+import { type IEngine } from '@haiyue/engine/core';
+export interface Camera2DScratch {
+    viewMatrix: Float32Array;
+    viewProjMatrix: Float32Array;
+}
+export declare function createCamera2DScratch(): Camera2DScratch;
+export declare function compute2DViewProjection(engine: IEngine, cameraEntity: Entity, camera: Camera2D, scratch?: Camera2DScratch): Float32Array;
+export declare function write2DCameraBuffer(queue: GPUQueue, buffer: GPUBuffer, viewProj: Float32Array): void;
+export declare const IDENTITY_2D_WORLD_MATRIX: Float32Array;
+export type WorldMatrix2DFrameCache = Map<Entity, Float32Array>;
+export declare function get2DEntityWorldMatrix(entity: Entity, cache?: WorldMatrix2DFrameCache): Float32Array;

package/dist/utils/render2dGpu.d.ts

@@ -0,0 +1,32 @@
+import { type ExtensionGPUResourceTracker } from '@haiyue/engine/extension-authoring';
+export interface Camera2DGpu {
+    layout: GPUBindGroupLayout;
+    buffer: GPUBuffer;
+    tracker?: ExtensionGPUResourceTracker;
+    bindGroup: GPUBindGroup;
+}
+export interface Object2DGpu {
+    buffer: GPUBuffer;
+    bindGroup: GPUBindGroup;
+    snapshot: Float32Array;
+    tracker?: ExtensionGPUResourceTracker;
+}
+export interface Texture2DGpu {
+    layout: GPUBindGroupLayout;
+    sampler: GPUSampler;
+    fallbackTexture: GPUTexture;
+    fallbackBindGroup: GPUBindGroup;
+    tracker?: ExtensionGPUResourceTracker;
+}
+export declare function createCamera2DLayout(device: GPUDevice): GPUBindGroupLayout;
+export declare function createCamera2DGpu(device: GPUDevice, tracker?: ExtensionGPUResourceTracker, layout?: GPUBindGroupLayout): Camera2DGpu;
+export declare function createObject2DLayout(device: GPUDevice): GPUBindGroupLayout;
+export declare function createObject2DGpu(device: GPUDevice, layout: GPUBindGroupLayout, tracker?: ExtensionGPUResourceTracker): Object2DGpu;
+export declare function createTexture2DGpu(device: GPUDevice, fallbackAlpha?: number, tracker?: ExtensionGPUResourceTracker): Texture2DGpu;
+export declare function writeFloatBuffer(queue: GPUQueue, buffer: GPUBuffer, data: Float32Array): void;
+export declare function matrixEquals(a: Float32Array, b: Float32Array): boolean;
+export declare function createMatrixSnapshot(): Float32Array;
+export declare function writeObjectMatrixIfChanged(queue: GPUQueue, gpu: Object2DGpu, matrix: Float32Array): boolean;
+export declare function destroyCamera2DGpu(gpu: Camera2DGpu): void;
+export declare function destroyObject2DGpu(gpu: Object2DGpu): void;
+export declare function destroyTexture2DGpu(gpu: Texture2DGpu): void;

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "@haiyue/extensions",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Stable optional HaiYue runtimes for 2D/3D animation, glTF, Spine, tilemaps, text, tweening, and grids.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HaiyueStudio/Engine.git",
+    "directory": "extensions"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "test/fixtures/gltf/animation-characterization.gltf",
+    "src/**/*"
+  ],
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./gltf": {
+      "source": "./src/gltf.ts",
+      "types": "./dist/gltf.d.ts",
+      "import": "./dist/gltf.js"
+    },
+    "./experimental/gltf-worker": {
+      "source": "./src/experimental-gltf-worker.ts",
+      "types": "./dist/experimental-gltf-worker.d.ts",
+      "import": "./dist/experimental-gltf-worker.js"
+    },
+    "./experimental/spine-worker": {
+      "source": "./src/experimental-spine-worker.ts",
+      "types": "./dist/experimental-spine-worker.d.ts",
+      "import": "./dist/experimental-spine-worker.js"
+    },
+    "./spine": {
+      "source": "./src/spine.ts",
+      "types": "./dist/spine.d.ts",
+      "import": "./dist/spine.js"
+    },
+    "./tilemap": {
+      "source": "./src/tilemap.ts",
+      "types": "./dist/tilemap.d.ts",
+      "import": "./dist/tilemap.js"
+    },
+    "./canvas-text": {
+      "source": "./src/canvas-text.ts",
+      "types": "./dist/canvas-text.d.ts",
+      "import": "./dist/canvas-text.js"
+    },
+    "./tween": {
+      "source": "./src/tween.ts",
+      "types": "./dist/tween.d.ts",
+      "import": "./dist/tween.js"
+    },
+    "./grid": {
+      "source": "./src/grid.ts",
+      "types": "./dist/grid.d.ts",
+      "import": "./dist/grid.js"
+    },
+    "./animation": {
+      "source": "./src/animation.ts",
+      "types": "./dist/animation.d.ts",
+      "import": "./dist/animation.js"
+    },
+    "./hya-state-machine": {
+      "source": "./src/hya-state-machine.ts",
+      "types": "./dist/hya-state-machine.d.ts",
+      "import": "./dist/hya-state-machine.js"
+    },
+    "./animation3d": {
+      "source": "./src/animation3d.ts",
+      "types": "./dist/animation3d.d.ts",
+      "import": "./dist/animation3d.js"
+    },
+    "./gltf-animation3d": {
+      "source": "./src/gltf-animation3d.ts",
+      "types": "./dist/gltf-animation3d.d.ts",
+      "import": "./dist/gltf-animation3d.js"
+    }
+  },
+  "scripts": {
+    "build": "node ../scripts/build-rollup-once.mjs && node ../scripts/build-rollup-once.mjs rollup.worker.config.js",
+    "build:animation-runtime-tests": "node -e \"require('node:fs').rmSync('dist-test', { recursive: true, force: true })\" && tsc -p tsconfig.animation-runtime-tests.json",
+    "test": "npm run build && npm run build:animation-runtime-tests && node --test --test-concurrency=1 \"test/**/*.test.mjs\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.animation3d-type-tests.json && tsc -p tsconfig.animation-runtime-tests.json --noEmit"
+  },
+  "dependencies": {
+    "draco3dgltf": "^1.5.7",
+    "earcut": "^3.0.2",
+    "wgpu-matrix": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@haiyue/animation-spec": ">=0.1.0 <0.2.0",
+    "@haiyue/engine": ">=0.1.0 <0.2.0"
+  },
+  "devDependencies": {
+    "@haiyue/animation-spec": "0.1.0",
+    "@haiyue/engine": "0.1.0",
+    "@rollup/plugin-node-resolve": "^15.0.0",
+    "@rollup/plugin-typescript": "^11.0.0",
+    "@webgpu/types": "^0.1.40",
+    "rollup": "^4.0.0",
+    "tslib": "^2.6.0",
+    "typescript": "^5.2.0"
+  }
+}

package/src/animation/Animation2DComponent.ts

@@ -0,0 +1,135 @@
+import type { AnimationSource, ParsedAnimation } from '@haiyue/animation-spec';
+import { parseAnimation } from '@haiyue/animation-spec';
+import { Component, type Entity, type World } from '@haiyue/engine';
+import { ComponentLifecycleFlags, UniqueCheckType } from '@haiyue/engine/ecs';
+import type { Animation2DRuntime } from './Animation2DRuntime';
+import type { Animation2DExtensionRegistry } from './Animation2DExtensionRegistry';
+
+export interface Animation2DComponentOptions {
+  autoplay?: boolean;
+  loop?: boolean;
+  speed?: number;
+  startTime?: number;
+  runtimeExtensions?: Animation2DExtensionRegistry;
+}
+
+export interface Animation2DRuntimeStats {
+  readonly nodeCount: number;
+  readonly visualCount: number;
+  readonly unsupportedComponentCount: number;
+  readonly pendingResourceCount: number;
+  readonly failedResourceCount: number;
+  readonly textCount: number;
+  readonly particleCount: number;
+  readonly audioCount: number;
+}
+
+export class Animation2DComponent extends Component {
+  static override UniqueCheckType = UniqueCheckType.SYMBOL | UniqueCheckType.REPLACE;
+  static override UniqueSymbol = Symbol.for('Animation2DComponent');
+  static override Lifecycle = ComponentLifecycleFlags.EntityRemoveComponent | ComponentLifecycleFlags.EntityRemoveFromWorld;
+
+  readonly animation: ParsedAnimation;
+  playing: boolean;
+  loop: boolean;
+  speed: number;
+  currentTime: number;
+  completed = false;
+  readonly runtimeExtensions: Animation2DExtensionRegistry | undefined;
+  _runtime: Animation2DRuntime | null = null;
+  _needsApply = true;
+  _forceParticleSeek = false;
+
+  constructor(source: AnimationSource | ParsedAnimation, options: Animation2DComponentOptions = {}) {
+    super('Animation2DComponent');
+    this.animation = isParsed(source) ? source : parseAnimation(source);
+    this.playing = options.autoplay ?? true;
+    this.loop = options.loop ?? this.animation.endBehavior === 'loop';
+    this.speed = finiteSpeed(options.speed ?? 1);
+    this.currentTime = clampTime(options.startTime ?? 0, this.animation.duration);
+    this.runtimeExtensions = options.runtimeExtensions;
+  }
+
+  get runtimeStats(): Animation2DRuntimeStats {
+    return this._runtime?.stats ?? {
+      nodeCount: 0,
+      visualCount: 0,
+      unsupportedComponentCount: 0,
+      pendingResourceCount: 0,
+      failedResourceCount: 0,
+      textCount: 0,
+      particleCount: 0,
+      audioCount: 0,
+    };
+  }
+
+  play(): this {
+    if (this.completed) {
+      this.currentTime = 0;
+      this._needsApply = true;
+      this._forceParticleSeek = true;
+    }
+    this.playing = true;
+    this.completed = false;
+    this._runtime?.setPlaying(true);
+    return this;
+  }
+
+  pause(): this {
+    this.playing = false;
+    this._runtime?.setPlaying(false);
+    return this;
+  }
+
+  seek(seconds: number): this {
+    this.currentTime = clampTime(seconds, this.animation.duration);
+    this.completed = false;
+    this._needsApply = true;
+    this._forceParticleSeek = true;
+    return this;
+  }
+
+  setSpeed(speed: number): this {
+    this.speed = finiteSpeed(speed);
+    return this;
+  }
+
+  onEntityRemoveComponent(_entity: Entity, component: Component): void {
+    if (component === this) this._disposeRuntime();
+  }
+
+  onEntityRemoveFromWorld(_entity: Entity, _world: World): void {
+    this._disposeRuntime();
+  }
+
+  override clone(): Animation2DComponent {
+    const clone = new Animation2DComponent(this.animation, {
+      autoplay: this.playing,
+      loop: this.loop,
+      speed: this.speed,
+      startTime: this.currentTime,
+      ...(this.runtimeExtensions ? { runtimeExtensions: this.runtimeExtensions } : {}),
+    });
+    clone.disabled = this.disabled;
+    return clone;
+  }
+
+  _disposeRuntime(): void {
+    this._runtime?.destroy();
+    this._runtime = null;
+  }
+}
+
+function isParsed(source: AnimationSource | ParsedAnimation): source is ParsedAnimation {
+  return typeof source === 'object' && source !== null && 'source' in source;
+}
+
+function finiteSpeed(value: number): number {
+  if (!Number.isFinite(value) || value < 0) throw new RangeError('Animation2DComponent speed must be finite and non-negative.');
+  return value;
+}
+
+function clampTime(value: number, duration: number): number {
+  if (!Number.isFinite(value)) throw new RangeError('Animation2DComponent time must be finite.');
+  return Math.max(0, Math.min(duration, value));
+}

package/src/animation/Animation2DExtensionRegistry.ts

@@ -0,0 +1,52 @@
+import type {
+  AnimationComponent,
+  AnimationNode,
+  ParsedAnimation,
+} from '@haiyue/animation-spec';
+import type { Entity } from '@haiyue/engine';
+
+export interface Animation2DExtensionContext {
+  readonly animation: ParsedAnimation;
+  readonly node: Readonly<AnimationNode>;
+  readonly component: Readonly<AnimationComponent>;
+  /** Anchor-adjusted parent for entities created by the extension. */
+  readonly parent: Entity;
+}
+
+export interface Animation2DExtensionInstance {
+  /** Deterministic composition-time update; implementations must tolerate seeks and loop wrap. */
+  apply?(timeSeconds: number, opacity: number): void;
+  setOpacity?(opacity: number): void;
+  destroy?(): void;
+}
+
+export interface Animation2DExtensionHandler {
+  /** Component type or namespaced extension id implemented by this handler. */
+  readonly id: string;
+  create(context: Animation2DExtensionContext): Animation2DExtensionInstance | void;
+}
+
+/** Instance-owned registry; unregister tokens only remove the handler that created them. */
+export class Animation2DExtensionRegistry {
+  private readonly _handlers = new Map<string, Animation2DExtensionHandler>();
+
+  register(handler: Animation2DExtensionHandler): () => void {
+    if (!handler.id.trim()) throw new TypeError('Animation runtime extension id must not be empty.');
+    if (this._handlers.has(handler.id)) throw new Error(`Animation runtime extension "${handler.id}" is already registered.`);
+    this._handlers.set(handler.id, handler);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      if (this._handlers.get(handler.id) === handler) this._handlers.delete(handler.id);
+    };
+  }
+
+  get(id: string): Animation2DExtensionHandler | undefined {
+    return this._handlers.get(id);
+  }
+
+  has(id: string): boolean {
+    return this._handlers.has(id);
+  }
+}