@haiyue/extensions 0.1.0 → 0.2.0

package/README.md

@@ -2,12 +2,19 @@
 
 Optional runtime capabilities for `@haiyue/engine`.
 
+`@haiyue/extensions/controls` adds configurable fixed/floating virtual joystick input,
+per-frame events, Entity movement/heading and optional Engine GUI presentation.
+See the [guide](../docs/engine-guide/virtual-joystick.md) and
+[runnable example](../examples/virtual-joystick/index.html). This new stable subpath
+is a local candidate for a future reviewed minor release, not a published 0.1.x addition.
+
 ## Stable entrypoints
 
 - `@haiyue/extensions/gltf` — glTF loading, runtime components, compatibility reports, materials, and the engine plugin.
 - `@haiyue/extensions/animation3d` — source-independent 3D clips, mixers, pose buffers, layers, masks, events, state machines, and the HYA adapter.
 - `@haiyue/extensions/gltf-animation3d` — adapts glTF clips to the source-independent Animation3D runtime.
 - `@haiyue/extensions/animation` — HYA Animation2D components, systems, loading, rendering, and state-machine integration.
+- `@haiyue/extensions/deformable-animation` — source-neutral HYA deformable-mesh sampling, dynamic geometry, texture and alpha-mask runtime; it has no Live2D/Cubism dependency.
 - `@haiyue/extensions/hya-state-machine` — the focused HYA 2D state-machine runtime.
 - `@haiyue/extensions/spine` — Spine component, render system, plugin, and the stable worker interface seam.
 - `@haiyue/extensions/tilemap` — Tilemap2D component, render system, and plugin.
@@ -27,4 +34,22 @@ engine.installPlugin(createGltfPlugin());
 
 The package root remains a minimal experimental authoring base. Worker transport and low-level parsing are explicitly available from `@haiyue/extensions/experimental/gltf-worker` and `@haiyue/extensions/experimental/spine-worker`; they may change without stable-API compatibility guarantees.
 
+The source-neutral indexed-sprite renderer is available from `@haiyue/extensions/experimental/indexed-sprite`. It stores index planes and palette rows separately, so changing a palette does not duplicate sprite pixels. It also accepts RGB/RGBA planes, batches atlas pages, supports nearest or palette-aware linear filtering, and owns bounded upload/recovery/disposal:
+
+```ts
+import { IndexedSpriteRenderer } from '@haiyue/extensions/experimental/indexed-sprite';
+
+const renderer = new IndexedSpriteRenderer(device, [{
+  id: 'idle-0', width: 2, height: 2, format: 'indexed8',
+  pixels: new Uint8Array([0, 1, 1, 0]),
+}], [{
+  id: 'default', colorCount: 2,
+  rgba: new Uint8Array([0, 0, 0, 0, 255, 255, 255, 255]),
+}], { targetFormat: navigator.gpu.getPreferredCanvasFormat() });
+
+renderer.uploadAll();
+renderer.render(pass, [{ spriteId: 'idle-0', paletteId: 'default', x: 320, y: 180 }], 1280, 720);
+renderer.dispose();
+```
+
 WebGPU is required by the runtime; there is no WebGL fallback.

package/dist/animation/Animation2DComponent.d.ts

@@ -5,10 +5,22 @@ import type { Animation2DExtensionRegistry } from './Animation2DExtensionRegistr
 export interface Animation2DComponentOptions {
     autoplay?: boolean;
     loop?: boolean;
+    /** Seconds from which playback repeats after the first complete pass. */
+    loopStartTime?: number;
+    /** Exclusive end of the repeated range; later timeline content remains available for an exit pass. */
+    loopEndTime?: number;
     speed?: number;
     startTime?: number;
     runtimeExtensions?: Animation2DExtensionRegistry;
 }
+export interface Animation2DNodeOverride {
+    /** Local node position in the HYA canvas coordinate system (screen-y-down). */
+    readonly position?: readonly [number, number];
+    /** Runtime opacity replacement in the inclusive 0..1 range. */
+    readonly opacity?: number;
+    /** Overrides authored/timeline visibility while present. */
+    readonly enabled?: boolean;
+}
 export interface Animation2DRuntimeStats {
     readonly nodeCount: number;
     readonly visualCount: number;
@@ -26,10 +38,13 @@ export declare class Animation2DComponent extends Component {
     readonly animation: ParsedAnimation;
     playing: boolean;
     loop: boolean;
+    readonly loopStartTime: number;
+    readonly loopEndTime: number;
     speed: number;
     currentTime: number;
     completed: boolean;
     readonly runtimeExtensions: Animation2DExtensionRegistry | undefined;
+    readonly _nodeOverrides: Map<string, Animation2DNodeOverride>;
     _runtime: Animation2DRuntime | null;
     _needsApply: boolean;
     _forceParticleSeek: boolean;
@@ -39,6 +54,9 @@ export declare class Animation2DComponent extends Component {
     pause(): this;
     seek(seconds: number): this;
     setSpeed(speed: number): this;
+    setNodeOverride(nodeId: string, override: Animation2DNodeOverride): this;
+    clearNodeOverride(nodeId: string): this;
+    clearNodeOverrides(): this;
     onEntityRemoveComponent(_entity: Entity, component: Component): void;
     onEntityRemoveFromWorld(_entity: Entity, _world: World): void;
     clone(): Animation2DComponent;

package/dist/animation/Animation2DExtensionRegistry.d.ts

@@ -1,11 +1,18 @@
 import type { AnimationComponent, AnimationNode, ParsedAnimation } from '@haiyue/animation-spec';
 import type { Entity } from '@haiyue/engine';
+import type { AssetManager } from '@haiyue/engine/assets';
 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;
+    /** Shared runtime asset manager; absent hosts must reject resource-backed handlers. */
+    readonly assetManager?: AssetManager;
+    /** Stable identity separating multiple instances of the same HYA document. */
+    readonly instanceId: number;
+    /** Aborted before the owning animation hierarchy is destroyed. */
+    readonly signal: AbortSignal;
 }
 export interface Animation2DExtensionInstance {
     /** Deterministic composition-time update; implementations must tolerate seeks and loop wrap. */

package/dist/animation/Animation2DRenderSystem.d.ts

@@ -24,6 +24,8 @@ export declare class Animation2DRenderSystem extends RenderSystem2DBase {
     private textureLayout;
     private compositeLayout;
     private sampler;
+    private mipmapSampler;
+    private mipmapPipeline;
     private whiteTexture;
     private whiteBindGroup;
     private emptyCompositeBindGroup;
@@ -34,6 +36,8 @@ export declare class Animation2DRenderSystem extends RenderSystem2DBase {
     private pipelines;
     private readonly entityGpu;
     private readonly geometryGpu;
+    private readonly explicitUvIds;
+    private nextExplicitUvId;
     private textureBindGroups;
     private readonly maskTargets;
     private readonly effectTargets;
@@ -72,7 +76,9 @@ export declare class Animation2DRenderSystem extends RenderSystem2DBase {
     private drawEffectResult;
     private getEntityGpu;
     private getVisualTextureBindGroup;
+    private generateTextMipChain;
     private getGeometryGpu;
+    private geometryKey;
     private getTextureBindGroup;
     private createTextureBindGroup;
     private resolveCompositeBindGroup;

package/dist/animation/Animation2DRuntime.d.ts

@@ -2,7 +2,7 @@ import { type AnimationComposite, type AnimationLayerEffect, type AnimationNode,
 import { Entity, Transform2D } from '@haiyue/engine';
 import { ParticleEmitter2D } from '@haiyue/engine/components';
 import type { AssetManager } from '@haiyue/engine/assets';
-import type { Animation2DRuntimeStats } from './Animation2DComponent.js';
+import type { Animation2DNodeOverride, Animation2DRuntimeStats } from './Animation2DComponent.js';
 import type { Animation2DExtensionInstance, Animation2DExtensionRegistry } from './Animation2DExtensionRegistry.js';
 import { type VectorPathMorphComponent, type VectorStrokePathComponent } from './AnimationPathTessellator.js';
 import { AnimationVisual2D } from './AnimationVisual2D.js';
@@ -22,6 +22,7 @@ export interface Animation2DRuntimeVisual {
     lastVectorTime?: number;
     readonly textRasterizer?: AnimationTextRasterizer;
     readonly sourceEffects?: readonly Readonly<AnimationLayerEffect>[];
+    readonly sourceEffectOffset?: number;
     lastEffectTime?: number;
     readonly compositeExpansionTracks?: readonly (Readonly<AnimationVectorValueTrack> | undefined)[];
     lastCompositeTime?: number;
@@ -58,6 +59,7 @@ export interface Animation2DRuntimeNode {
 export declare class Animation2DRuntime {
     private readonly _animation;
     private readonly _assetManager?;
+    private readonly _nodeOverrides;
     private readonly _root;
     protected readonly _nodes: Animation2DRuntimeNode[];
     protected readonly _nodesById: Map<string, Animation2DRuntimeNode>;
@@ -69,6 +71,7 @@ export declare class Animation2DRuntime {
     private readonly _assetHandles;
     private readonly _fontLoads;
     private readonly _fontFaces;
+    private readonly _expressionDataLoads;
     private readonly _instanceId;
     private _visualCount;
     private _unsupportedComponentCount;
@@ -82,12 +85,13 @@ export declare class Animation2DRuntime {
     protected _speed: number;
     protected _lastAppliedTime: number;
     get stats(): Animation2DRuntimeStats;
-    constructor(owner: Entity, _animation: ParsedAnimation, runtimeExtensions?: Animation2DExtensionRegistry, _assetManager?: AssetManager | undefined);
+    constructor(owner: Entity, _animation: ParsedAnimation, runtimeExtensions?: Animation2DExtensionRegistry, _assetManager?: AssetManager | undefined, _nodeOverrides?: ReadonlyMap<string, Animation2DNodeOverride>);
     apply(time: number, playing?: boolean, speed?: number, forceParticleSeek?: boolean): void;
     destroy(): void;
     setPlaying(playing: boolean): void;
     private _loadTexture;
     protected _materializeCoreVisual(node: Animation2DRuntimeNode, deferred: DeferredCoreVisual): void;
+    private _loadTextExpressionData;
     private _loadTextFonts;
     private _loadFont;
     private _applyTrack;

package/dist/animation/AnimationTextRasterizer.d.ts

@@ -11,9 +11,13 @@ export declare class AnimationTextRasterizer {
     private updating;
     private updateToken;
     private readonly animated;
+    private readonly expressionData;
+    private readonly outlineFonts;
     constructor(component: Readonly<AnimationText2DComponent>);
     setTime(time: number): void;
     invalidateFont(): void;
+    setFontData(family: string, style: 'normal' | 'italic', weight: string | number, data: ArrayBuffer): void;
+    setExpressionData(resource: string, value: unknown): void;
     destroy(): void;
     updateTexture(): Promise<void>;
     private draw;

package/dist/animation/AnimationVisual2D.d.ts

@@ -5,9 +5,21 @@ import type { AnimationTextRasterizer } from './AnimationTextRasterizer';
 export interface AnimationVisual2DOptions {
     geometry: Geometry2D;
     color: readonly [number, number, number, number];
+    /** Drawable-local multiply tint. Alpha is retained for pose parity but is not rendered. */
+    multiplyColor?: readonly [number, number, number, number];
+    /** Drawable-local alpha-aware screen tint. Alpha is retained for pose parity but is not rendered. */
+    screenColor?: readonly [number, number, number, number];
     instanceId: number;
     nodeId: string;
     order: number;
+    /** Source-neutral draw blend used by deformable meshes and other authored visuals. */
+    blendMode?: AnimationVisual2DBlendMode;
+    /** Declares whether filtered source texels are already premultiplied. */
+    textureAlphaMode?: AnimationVisual2DTextureAlphaMode;
+    /** Source-neutral back-face culling. False draws both triangle faces. */
+    culling?: boolean;
+    /** Optional explicit UV pairs for arbitrary textured triangle meshes. */
+    uvs?: Float32Array;
     sourceOnly?: boolean;
     composite?: Readonly<AnimationComposite>;
     texture?: GPUTexture | null;
@@ -19,6 +31,8 @@ export interface AnimationVisual2DOptions {
     gradient?: AnimationVisualGradient | null;
     effects?: readonly AnimationVisualEffect[];
 }
+export type AnimationVisual2DBlendMode = 'normal' | 'additive' | 'multiplicative' | 'screen';
+export type AnimationVisual2DTextureAlphaMode = 'straight' | 'premultiplied';
 export interface AnimationVisualGradient {
     kind: 'linear' | 'radial';
     start: [number, number];
@@ -27,7 +41,7 @@ export interface AnimationVisualGradient {
     stops: Float32Array;
     opacity: number;
 }
-export type AnimationVisualEffectKind = 'tint' | 'fill' | 'opacity' | 'color-matrix' | 'blur' | 'drop-shadow';
+export type AnimationVisualEffectKind = 'tint' | 'fill' | 'opacity' | 'color-matrix' | 'blur' | 'drop-shadow' | 'inner-feather' | 'vector-feather';
 export interface AnimationVisualEffect {
     readonly kind: AnimationVisualEffectKind;
     /** Mutable, kind-specific sampled values owned by the animation runtime. */
@@ -41,7 +55,11 @@ export declare class AnimationVisual2D extends Component {
     readonly instanceId: number;
     readonly nodeId: string;
     readonly nodeKey: string;
-    readonly order: number;
+    order: number;
+    readonly blendMode: AnimationVisual2DBlendMode;
+    readonly textureAlphaMode: AnimationVisual2DTextureAlphaMode;
+    readonly culling: boolean;
+    readonly uvs: Float32Array | null;
     readonly sourceOnly: boolean;
     readonly compositeLayers: readonly Readonly<AnimationCompositeLayer>[];
     readonly compositeKeys: readonly string[];
@@ -51,6 +69,8 @@ export declare class AnimationVisual2D extends Component {
     readonly compositeMode: AnimationCompositeMode | undefined;
     readonly uvRect: [number, number, number, number];
     readonly color: [number, number, number, number];
+    readonly multiplyColor: [number, number, number, number];
+    readonly screenColor: [number, number, number, number];
     texture: GPUTexture | null;
     textureHandle: AssetHandle<GPUTexture> | null;
     readonly textMaterial: AnimationTextRasterizer | null;
@@ -60,9 +80,45 @@ export declare class AnimationVisual2D extends Component {
     revision: number;
     constructor(options: AnimationVisual2DOptions);
     setTexture(texture: GPUTexture | null): void;
+    setOrder(order: number): void;
     setTextureHandle(handle: AssetHandle<GPUTexture> | null): void;
     setUvRect(value: readonly [number, number, number, number]): void;
+    /** Updates caller-owned drawable color state without replacing visual or GPU owners. */
+    setDrawableColors(multiplyColor: readonly [number, number, number, number] | Float32Array, screenColor: readonly [number, number, number, number] | Float32Array): void;
     setCompositeExpansion(index: number, value: number): void;
     resolveTexture(): GPUTexture | null;
     clone(): AnimationVisual2D;
 }
+export declare class AnimationVisual2DConfigurationError extends TypeError {
+    readonly code: 'E_ANIMATION_2D_CULLING_INVALID' | 'E_ANIMATION_2D_MULTIPLY_COLOR_INVALID' | 'E_ANIMATION_2D_SCREEN_COLOR_INVALID';
+    readonly path: string;
+    constructor(code: 'E_ANIMATION_2D_CULLING_INVALID' | 'E_ANIMATION_2D_MULTIPLY_COLOR_INVALID' | 'E_ANIMATION_2D_SCREEN_COLOR_INVALID', message: string, path: string);
+}
+export interface AnimationDrawableColorPixelInput {
+    readonly texture: readonly [number, number, number, number];
+    readonly textureAlphaMode?: AnimationVisual2DTextureAlphaMode;
+    readonly baseColor?: readonly [number, number, number, number];
+    readonly multiplyColor?: readonly [number, number, number, number];
+    readonly screenColor?: readonly [number, number, number, number];
+    readonly coverage?: number;
+    /** Mask setup intentionally ignores drawable tint RGB. */
+    readonly outputMask?: boolean;
+}
+/** CPU oracle for the premultiplied fragment emitted before framebuffer compositing. */
+export declare function composeAnimationDrawableColorPixel(input: AnimationDrawableColorPixelInput): [number, number, number, number];
+export declare class Animation2DPipelineCreationError extends Error {
+    readonly pipelineKey: string;
+    readonly cause: unknown;
+    readonly code: "E_ANIMATION_2D_PIPELINE_CREATION_FAILED";
+    readonly path: "$runtime.animation2D.pipeline";
+    constructor(pipelineKey: string, cause: unknown);
+}
+export declare function createAnimation2DPipeline<T>(pipelineKey: string, create: () => T): T;
+/**
+ * Source-neutral 2D front faces are CCW in clip space. WebGPU normalizes the
+ * viewport convention for front-face classification; callers must not add an
+ * extra framebuffer-Y inversion. Real model/world reflections still reverse it.
+ */
+export declare const ANIMATION_2D_WEBGPU_FRONT_FACE: "ccw";
+export declare function animation2DCullingPrimitive(culling: boolean): GPUPrimitiveState;
+export declare function animation2DCullingPipelineKey(culling: boolean): string;

package/dist/animation/interaction/InteractionRuntime.d.ts

@@ -0,0 +1,83 @@
+import type { InteractionActionPort, InteractionGeometryPort, RuntimeInteractionDocument, RuntimeValue } from './runtime-types.js';
+interface PointerInput {
+    readonly kind: 'move' | 'down' | 'up';
+    readonly pointerId: number;
+    readonly point: readonly [number, number];
+    readonly button?: number;
+}
+export interface InteractionRuntimeOptions {
+    readonly geometryPort?: InteractionGeometryPort;
+    readonly actionPort?: InteractionActionPort;
+    readonly maxEventQueue?: number;
+    readonly maxEventRecursion?: number;
+    readonly maxPointers?: number;
+    readonly maxStringBytes?: number;
+}
+export declare class InteractionRuntime {
+    readonly document: RuntimeInteractionDocument;
+    private readonly options;
+    private readonly targets;
+    private readonly listeners;
+    private readonly queue;
+    private pointers;
+    private captures;
+    private focused;
+    private sequence;
+    private transactionSequence;
+    private draining;
+    private currentDepth;
+    private disposed;
+    private readonly maxEventQueue;
+    private readonly maxEventRecursion;
+    private readonly maxPointers;
+    private readonly maxStringBytes;
+    constructor(document: RuntimeInteractionDocument, options?: InteractionRuntimeOptions);
+    dispatchPointer(input: PointerInput): void;
+    dispatchKeyboard(input: Readonly<{
+        key: string;
+        phase: 'down' | 'up' | 'repeat';
+        modifiers?: readonly string[];
+    }>): void;
+    dispatchText(text: string): void;
+    dispatchDataChange(binding: string, value: RuntimeValue, target?: string | undefined): void;
+    dispatchGamepad(input: Readonly<{
+        index: number;
+        control: string;
+        phase: 'down' | 'up' | 'change';
+        value: number;
+    }>): void;
+    dispatchSemanticAction(target: string, action: 'tap' | 'increase' | 'decrease' | 'focus'): void;
+    enqueueReportedEvent(name: string, payload?: RuntimeValue, target?: string | undefined): void;
+    enqueueComponentEvent(target: string, name: string, payload?: RuntimeValue): void;
+    focus(target: string | undefined): void;
+    focusNext(reverse?: boolean): string | undefined;
+    hitTest(point: readonly [number, number]): string | undefined;
+    dispose(): void;
+    get trace(): Readonly<{
+        sequence: number;
+        focused: string | null;
+        captures: readonly Readonly<{
+            pointer: number;
+            target: string;
+        }>[];
+        pointers: number;
+        queued: number;
+        disposed: boolean;
+    }>;
+    private enqueue;
+    private drain;
+    private route;
+    private invokeListeners;
+    private invokeAction;
+    private matches;
+    private containsTarget;
+    private toLocal;
+    private path;
+    private focusFromPointer;
+    private target;
+    private snapshot;
+    private restore;
+    private stringInput;
+    private assertLive;
+}
+export {};

package/dist/animation/interaction/runtime-types.d.ts

@@ -0,0 +1,257 @@
+export interface RuntimeObject {
+    readonly [key: string]: RuntimeValue;
+}
+export type RuntimeValue = number | string | boolean | null | readonly RuntimeValue[] | RuntimeObject;
+export type RuntimePath = readonly (string | number)[];
+export interface RuntimeProperty {
+    readonly id: string;
+    readonly kind: 'number' | 'integer' | 'string' | 'boolean' | 'color' | 'trigger' | 'enum' | 'model' | 'list' | 'image' | 'artboard' | 'font' | 'blob';
+    readonly enum?: string;
+    readonly model?: string;
+    readonly item?: Readonly<{
+        kind: string;
+        enum?: string;
+        model?: string;
+    }>;
+    readonly defaultValue?: RuntimeValue;
+    readonly nullable?: boolean;
+}
+export interface RuntimeModel {
+    readonly id: string;
+    readonly properties: readonly RuntimeProperty[];
+    readonly defaultInstance?: string;
+}
+export interface RuntimeInstance {
+    readonly id: string;
+    readonly model: string;
+    readonly scope: 'default' | 'global' | 'local';
+    readonly values: Readonly<Record<string, RuntimeValue>>;
+}
+export interface RuntimeConverter {
+    readonly id: string;
+    readonly version: 1;
+    readonly operations: readonly Readonly<Record<string, unknown>>[];
+}
+export interface RuntimeBinding {
+    readonly id: string;
+    readonly target: string;
+    readonly targetPath: readonly string[];
+    readonly source: Readonly<{
+        mode: 'explicit' | 'default' | 'global' | 'auto';
+        instance?: string;
+        model?: string;
+        path: RuntimePath;
+    }>;
+    readonly converter?: string;
+    readonly direction: 'read' | 'write' | 'two-way';
+}
+export interface RuntimePropertyGroup {
+    readonly id: string;
+    readonly version: 1;
+    readonly operations: readonly Readonly<Record<string, unknown>>[];
+}
+export interface RuntimeDataComponent {
+    readonly id: string;
+    readonly stateful: true;
+    readonly model: string;
+    readonly exposedProperties?: readonly string[];
+    readonly exposedInputs?: readonly string[];
+    readonly exposedEvents?: readonly string[];
+}
+export interface RuntimeDataDocument {
+    readonly enums: readonly Readonly<{
+        id: string;
+        values: readonly Readonly<{
+            key: string;
+            value: number;
+        }>[];
+    }>[];
+    readonly models: readonly RuntimeModel[];
+    readonly instances: readonly RuntimeInstance[];
+    readonly converters: readonly RuntimeConverter[];
+    readonly propertyGroups: readonly RuntimePropertyGroup[];
+    readonly bindings: readonly RuntimeBinding[];
+    readonly components: readonly RuntimeDataComponent[];
+}
+export interface DataChange {
+    readonly sequence: number;
+    readonly transactionId: number;
+    readonly instance: string;
+    readonly path: RuntimePath;
+    readonly kind: 'set' | 'trigger' | 'list-insert' | 'list-remove' | 'list-move' | 'rebind';
+    readonly previous: RuntimeValue | undefined;
+    readonly value: RuntimeValue | undefined;
+}
+export interface DataObservationBatch {
+    readonly advance: number;
+    readonly changes: readonly DataChange[];
+}
+export interface DataSubscription {
+    unsubscribe(): void;
+}
+export interface CustomConverterPort {
+    begin(transactionId: number): void;
+    invoke(request: Readonly<{
+        protocol: string;
+        port: string;
+        value: RuntimeValue;
+        arguments: Readonly<Record<string, RuntimeValue>>;
+    }>): RuntimeValue;
+    commit(transactionId: number): void;
+    rollback(transactionId: number): void;
+    dispose?(): void;
+}
+export interface DataResourceHandle {
+    readonly value: unknown;
+    release(): void;
+}
+export interface DataResourcePort {
+    acquire(kind: 'image' | 'artboard' | 'font' | 'blob', id: string, signal: AbortSignal): Promise<DataResourceHandle>;
+}
+export type RuntimeHitArea = Readonly<Record<string, unknown>>;
+export interface RuntimeInteractionTarget {
+    readonly id: string;
+    readonly parent?: string;
+    readonly component?: string;
+    readonly order: number;
+    readonly transform?: readonly [number, number, number, number, number, number];
+    readonly hitArea: RuntimeHitArea;
+    readonly clips?: readonly string[];
+    readonly enabled?: boolean;
+    readonly focusable?: boolean;
+    readonly tabIndex?: number;
+}
+export interface RuntimeInteractionAction extends Readonly<Record<string, unknown>> {
+    readonly kind: string;
+}
+export interface RuntimeInteractionListener {
+    readonly id: string;
+    readonly target: string;
+    readonly event: string;
+    readonly phases: readonly ('capture' | 'target' | 'bubble')[];
+    readonly pointerButton?: number;
+    readonly key?: string;
+    readonly keyPhase?: string;
+    readonly modifiers?: readonly string[];
+    readonly gamepad?: Readonly<{
+        index?: number;
+        control: string;
+        phase: string;
+    }>;
+    readonly semanticAction?: string;
+    readonly actions: readonly RuntimeInteractionAction[];
+}
+export interface RuntimeInteractionDocument {
+    readonly dragThreshold: number;
+    readonly targets: readonly RuntimeInteractionTarget[];
+    readonly listeners: readonly RuntimeInteractionListener[];
+    readonly limits?: Readonly<{
+        maxEventQueue?: number;
+        maxEventRecursion?: number;
+        maxPointers?: number;
+    }>;
+}
+export interface InteractionGeometryPort {
+    matrix?(target: string): readonly [number, number, number, number, number, number] | undefined;
+    visible?(target: string): boolean;
+    containsGeometry?(port: string, target: string, localPoint: readonly [number, number]): boolean;
+}
+export interface RoutedInteractionEvent {
+    readonly sequence: number;
+    readonly kind: string;
+    readonly phase: 'capture' | 'target' | 'bubble';
+    readonly target: string;
+    readonly currentTarget: string;
+    readonly pointerId?: number;
+    readonly point?: readonly [number, number];
+    readonly localPoint?: readonly [number, number];
+    readonly button?: number;
+    readonly key?: string;
+    readonly keyPhase?: string;
+    readonly modifiers?: readonly string[];
+    readonly text?: string;
+    readonly binding?: string;
+    readonly value?: RuntimeValue;
+    readonly gamepad?: Readonly<{
+        index: number;
+        control: string;
+        phase: string;
+        value: number;
+    }>;
+    readonly semanticAction?: string;
+    readonly name?: string;
+    readonly payload?: RuntimeValue;
+}
+export interface InteractionActionPort {
+    begin(transactionId: number): void;
+    invoke(action: RuntimeInteractionAction, event: RoutedInteractionEvent): void;
+    commit(transactionId: number): void;
+    rollback(transactionId: number): void;
+    dispose?(): void;
+}
+export interface RuntimeSemanticValue {
+    readonly kind: 'literal' | 'binding';
+    readonly value?: RuntimeValue;
+    readonly binding?: string;
+}
+export interface RuntimeSemanticNode {
+    readonly id: string;
+    readonly target: string;
+    readonly parent?: string;
+    readonly role: string;
+    readonly label?: RuntimeSemanticValue;
+    readonly value?: RuntimeSemanticValue;
+    readonly hint?: RuntimeSemanticValue;
+    readonly headingLevel?: number;
+    readonly traits?: readonly string[];
+    readonly state?: Readonly<Record<string, RuntimeSemanticValue>>;
+    readonly capabilities?: Readonly<Record<string, boolean>>;
+    readonly actions?: readonly string[];
+    readonly live?: string;
+    readonly readingOrder: number;
+    readonly navigationOrder: number;
+}
+export interface RuntimeSemanticsDocument {
+    readonly nodes: readonly RuntimeSemanticNode[];
+    readonly reducedMotion: Readonly<Record<string, unknown>>;
+}
+export interface SemanticSnapshotNode {
+    readonly id: string;
+    readonly target: string;
+    readonly parent?: string;
+    readonly role: string;
+    readonly label?: string;
+    readonly value?: string | number;
+    readonly hint?: string;
+    readonly headingLevel?: number;
+    readonly traits: readonly string[];
+    readonly state: Readonly<Record<string, boolean>>;
+    readonly capabilities: Readonly<Record<string, boolean>>;
+    readonly actions: readonly string[];
+    readonly live: string;
+    readonly readingOrder: number;
+    readonly navigationOrder: number;
+}
+export interface SemanticSnapshot {
+    readonly revision: number;
+    readonly nodes: readonly SemanticSnapshotNode[];
+    readonly readingOrder: readonly string[];
+    readonly navigationOrder: readonly string[];
+    readonly announcements: readonly Readonly<{
+        node: string;
+        mode: string;
+        text: string;
+    }>[];
+}
+export interface SemanticBindingPort {
+    read(binding: string): RuntimeValue;
+    subscribe?(listener: () => void): DataSubscription;
+}
+export interface SemanticHostBridge {
+    update(snapshot: SemanticSnapshot): void;
+    subscribeActions?(listener: (node: string, action: string) => void): DataSubscription;
+    dispose?(): void;
+}
+export interface SemanticActionPort {
+    invoke(target: string, action: string): void;
+}

package/dist/animation.d.ts

@@ -1,5 +1,7 @@
 export { Animation2DComponent } from './animation/Animation2DComponent';
-export type { Animation2DComponentOptions, Animation2DRuntimeStats } from './animation/Animation2DComponent';
+export type { Animation2DComponentOptions, Animation2DNodeOverride, Animation2DRuntimeStats } from './animation/Animation2DComponent';
+export { InteractionRuntime } from './animation/interaction/InteractionRuntime';
+export type { InteractionActionPort, InteractionGeometryPort, RoutedInteractionEvent, RuntimeInteractionAction, RuntimeInteractionDocument } from './animation/interaction/runtime-types';
 export { Animation2DSystem } from './animation/Animation2DSystem';
 export type { Animation2DSystemOptions } from './animation/Animation2DSystem';
 export { Animation2DRenderSystem } from './animation/Animation2DRenderSystem';