@aura3d/editor-runtime 1.1.0 → 1.3.0

package/src/AssetDropZone.ts

@@ -2,12 +2,12 @@ import type { Command } from "./Command";
 import { CommandHistory } from "./CommandHistory";
 import type { EditorProjectAssetDocument } from "./ProjectSerializer";
 
-export type CartoonAssetCategory = "character" | "set" | "prop" | "camera" | "light" | "audio" | "material" | "unknown";
+export type AnimationAssetCategory = "character" | "set" | "prop" | "camera" | "light" | "audio" | "material" | "unknown";
 
-export interface CartoonEditorAssetReference extends EditorProjectAssetDocument {
+export interface AnimationEditorAssetReference extends EditorProjectAssetDocument {
   readonly kind?: "aura-asset-ref" | "editor-asset-ref";
-  readonly category?: CartoonAssetCategory;
-  readonly profile?: "cartoon-character" | "cartoon-set" | "cartoon-prop" | "cartoon-audio" | string;
+  readonly category?: AnimationAssetCategory;
+  readonly profile?: "animation-character" | "animation-set" | "animation-prop" | "animation-audio" | string;
   readonly style?: string;
   readonly rigType?: "humanoid" | "creature" | "prop" | "none";
   readonly lipSyncReady?: boolean;
@@ -21,14 +21,14 @@ export interface AssetDropPlacement {
 }
 
 export interface AssetDropResult<TNode> {
-  readonly asset: CartoonEditorAssetReference;
+  readonly asset: AnimationEditorAssetReference;
   readonly node: TNode;
   readonly placement: AssetDropPlacement;
 }
 
 export interface AssetDropZoneOptions<TNode> {
   readonly history?: CommandHistory;
-  readonly createNode: (asset: CartoonEditorAssetReference, placement: AssetDropPlacement) => TNode;
+  readonly createNode: (asset: AnimationEditorAssetReference, placement: AssetDropPlacement) => TNode;
   readonly addNode: (node: TNode, placement: AssetDropPlacement) => void;
   readonly removeNode: (node: TNode) => void;
   readonly onDrop?: (result: AssetDropResult<TNode>) => void;
@@ -41,7 +41,7 @@ export class AssetDropZone<TNode = unknown> {
     this.history = options.history ?? new CommandHistory();
   }
 
-  async dropAsset(asset: CartoonEditorAssetReference, placement: AssetDropPlacement = {}): Promise<AssetDropResult<TNode>> {
+  async dropAsset(asset: AnimationEditorAssetReference, placement: AssetDropPlacement = {}): Promise<AssetDropResult<TNode>> {
     validateAssetReference(asset);
     validatePlacement(placement);
     const node = this.options.createNode(asset, placement);
@@ -82,7 +82,7 @@ class DropAssetCommand<TNode> implements Command {
 
   constructor(
     private readonly options: Pick<AssetDropZoneOptions<TNode>, "addNode" | "removeNode">,
-    private readonly asset: CartoonEditorAssetReference,
+    private readonly asset: AnimationEditorAssetReference,
     private readonly node: TNode,
     private readonly placement: AssetDropPlacement
   ) {
@@ -98,21 +98,21 @@ class DropAssetCommand<TNode> implements Command {
   }
 }
 
-export function serializeAssetForDrag(asset: CartoonEditorAssetReference): string {
+export function serializeAssetForDrag(asset: AnimationEditorAssetReference): string {
   validateAssetReference(asset);
   return JSON.stringify(asset);
 }
 
-export function readAssetFromDataTransfer(dataTransfer: DataTransfer | null): CartoonEditorAssetReference | undefined {
+export function readAssetFromDataTransfer(dataTransfer: DataTransfer | null): AnimationEditorAssetReference | undefined {
   if (!dataTransfer) return undefined;
   const encoded = dataTransfer.getData("application/x-aura3d-asset") || dataTransfer.getData("text/plain");
   if (!encoded.trim()) return undefined;
-  const parsed = JSON.parse(encoded) as CartoonEditorAssetReference;
+  const parsed = JSON.parse(encoded) as AnimationEditorAssetReference;
   validateAssetReference(parsed);
   return parsed;
 }
 
-function validateAssetReference(asset: CartoonEditorAssetReference): void {
+function validateAssetReference(asset: AnimationEditorAssetReference): void {
   if (!asset.id?.trim()) throw new Error("Dropped Aura3D asset id is required.");
   if (!asset.name?.trim()) throw new Error(`Dropped Aura3D asset name is required: ${asset.id}`);
   if ((asset.uri && /^https?:\/\//i.test(asset.uri) || asset.source && /^https?:\/\//i.test(asset.source)) && asset.kind !== "aura-asset-ref") {
@@ -121,12 +121,12 @@ function validateAssetReference(asset: CartoonEditorAssetReference): void {
   if (asset.source !== undefined && !asset.source.trim()) throw new Error(`Dropped Aura3D asset source cannot be empty: ${asset.id}`);
   if (asset.license !== undefined && !asset.license.trim()) throw new Error(`Dropped Aura3D asset license cannot be empty: ${asset.id}`);
   if (asset.category === "character") {
-    if (asset.rigType === "none") throw new Error(`Cartoon character asset "${asset.id}" must be rigged.`);
-    if ((asset.clips?.length ?? 0) === 0) throw new Error(`Cartoon character asset "${asset.id}" requires animation clip metadata.`);
-    if (!asset.lipSyncReady) throw new Error(`Cartoon character asset "${asset.id}" requires lip-sync readiness metadata.`);
+    if (asset.rigType === "none") throw new Error(`Animation character asset "${asset.id}" must be rigged.`);
+    if ((asset.clips?.length ?? 0) === 0) throw new Error(`Animation character asset "${asset.id}" requires animation clip metadata.`);
+    if (!asset.lipSyncReady) throw new Error(`Animation character asset "${asset.id}" requires lip-sync readiness metadata.`);
   }
   if ((asset.category === "set" || asset.category === "audio") && !asset.license) {
-    throw new Error(`Cartoon ${asset.category} asset "${asset.id}" requires license metadata.`);
+    throw new Error(`Animation ${asset.category} asset "${asset.id}" requires license metadata.`);
   }
 }
 

package/src/EventTrackEditor.ts

@@ -0,0 +1,169 @@
+// Editor authoring controller for animation event tracks (T2.2). Lets a timeline UI add / move /
+// delete typed markers on named lanes (hitbox active-frames, footsteps, VFX, generic markers) and
+// serialize to the canonical `animation-event-tracks/v1` shape that `@aura3d/animation`'s
+// `deserializeAnimationEventTracks` / `sampleClipEvents` consume — so authored tracks drive gameplay
+// (hitbox windows) and playback (footstep/VFX triggers) deterministically.
+//
+// Type-only imports from `@aura3d/animation` keep this controller free of any runtime coupling to
+// that package (the types are erased at build time); the serialized output is verified to round-trip
+// through the animation package's deserializer in tests.
+
+import type {
+  AnimationClipEvent,
+  AnimationClipEventType,
+  AnimationEventTrack,
+  SerializedAnimationEventTracks
+} from "@aura3d/animation";
+
+export interface EventMarkerView {
+  readonly id: string;
+  readonly time: number;
+  readonly duration?: number;
+  readonly type: AnimationClipEventType;
+  readonly selected: boolean;
+}
+
+export interface EventTrackLane {
+  readonly name: string;
+  readonly type: AnimationClipEventType;
+  readonly markers: readonly EventMarkerView[];
+}
+
+export interface EventTrackEditorOptions {
+  readonly clipId: string;
+  readonly duration: number;
+}
+
+export interface AddEventMarkerOptions {
+  readonly id?: string;
+  readonly type?: AnimationClipEventType;
+  /** Window length (seconds). >0 makes the marker an active-frame window (e.g. hitbox on/off). */
+  readonly duration?: number;
+  readonly payload?: unknown;
+  readonly tags?: readonly string[];
+}
+
+interface LaneState {
+  type: AnimationClipEventType;
+  markers: AnimationClipEvent[];
+}
+
+/**
+ * Timeline event-track authoring controller. Deterministic: marker ids come from a monotonic
+ * counter (no `Date.now`/`Math.random`), so undo/redo and serialization are reproducible.
+ */
+export class EventTrackEditor {
+  readonly clipId: string;
+  duration: number;
+  private readonly order: string[] = [];
+  private readonly lanesMap = new Map<string, LaneState>();
+  private selectedId: string | undefined;
+  private idCounter = 0;
+
+  constructor(options: EventTrackEditorOptions) {
+    if (!Number.isFinite(options.duration) || options.duration < 0) {
+      throw new Error("EventTrackEditor duration must be a finite, non-negative number.");
+    }
+    this.clipId = options.clipId;
+    this.duration = options.duration;
+  }
+
+  addTrack(name: string, type: AnimationClipEventType = "marker"): this {
+    if (!this.lanesMap.has(name)) {
+      this.lanesMap.set(name, { type, markers: [] });
+      this.order.push(name);
+    }
+    return this;
+  }
+
+  removeTrack(name: string): this {
+    if (this.lanesMap.delete(name)) this.order.splice(this.order.indexOf(name), 1);
+    return this;
+  }
+
+  /** Add a marker to a lane (auto-creates the lane). Returns the new marker id. */
+  addMarker(trackName: string, time: number, options: AddEventMarkerOptions = {}): string {
+    if (!Number.isFinite(time) || time < 0) {
+      throw new Error("Event marker time must be a finite, non-negative number.");
+    }
+    this.addTrack(trackName, options.type);
+    const lane = this.lanesMap.get(trackName)!;
+    const id = options.id ?? `${trackName}#${this.idCounter++}`;
+    lane.markers.push({
+      id,
+      name: trackName,
+      type: options.type ?? lane.type,
+      time,
+      ...(options.duration !== undefined ? { duration: options.duration } : {}),
+      ...(options.payload !== undefined ? { payload: options.payload } : {}),
+      ...(options.tags !== undefined ? { tags: options.tags } : {})
+    });
+    lane.markers.sort((a, b) => a.time - b.time);
+    return id;
+  }
+
+  /** Move an existing marker to a new time. */
+  moveMarker(trackName: string, markerId: string, time: number): this {
+    if (!Number.isFinite(time) || time < 0) {
+      throw new Error("Event marker time must be a finite, non-negative number.");
+    }
+    const lane = this.lanesMap.get(trackName);
+    const index = lane?.markers.findIndex((m) => m.id === markerId) ?? -1;
+    if (!lane || index < 0) throw new Error(`Marker ${markerId} not found on track ${trackName}.`);
+    lane.markers[index] = { ...lane.markers[index]!, time };
+    lane.markers.sort((a, b) => a.time - b.time);
+    return this;
+  }
+
+  /** Delete a marker. */
+  removeMarker(trackName: string, markerId: string): this {
+    const lane = this.lanesMap.get(trackName);
+    if (!lane) return this;
+    const index = lane.markers.findIndex((m) => m.id === markerId);
+    if (index >= 0) lane.markers.splice(index, 1);
+    if (this.selectedId === markerId) this.selectedId = undefined;
+    return this;
+  }
+
+  select(markerId: string | undefined): this {
+    this.selectedId = markerId;
+    return this;
+  }
+
+  markerCount(): number {
+    let count = 0;
+    for (const lane of this.lanesMap.values()) count += lane.markers.length;
+    return count;
+  }
+
+  /** View-model for the timeline UI: lanes with marker positions + selection state. */
+  lanes(): readonly EventTrackLane[] {
+    return this.order.map((name) => {
+      const lane = this.lanesMap.get(name)!;
+      return {
+        name,
+        type: lane.type,
+        markers: lane.markers.map((m) => ({
+          id: m.id!,
+          time: m.time,
+          ...(m.duration !== undefined ? { duration: m.duration } : {}),
+          type: m.type ?? lane.type,
+          selected: m.id === this.selectedId
+        }))
+      };
+    });
+  }
+
+  /** Serialize to the canonical `animation-event-tracks/v1` shape. */
+  serialize(): SerializedAnimationEventTracks {
+    const tracks: AnimationEventTrack[] = this.order.map((name) => {
+      const lane = this.lanesMap.get(name)!;
+      return { name, type: lane.type, markers: lane.markers.map((m) => ({ ...m })) };
+    });
+    return { schema: "animation-event-tracks/v1", clipId: this.clipId, duration: this.duration, tracks };
+  }
+}
+
+export function createEventTrackEditor(options: EventTrackEditorOptions): EventTrackEditor {
+  return new EventTrackEditor(options);
+}

package/src/SceneOutliner.ts

@@ -1,6 +1,6 @@
 import { HierarchyModel, type HierarchyNodeDescriptor } from "./HierarchyModel";
 import type { SelectionId } from "./Selection";
-import type { CartoonSceneNode } from "./CartoonSceneEditor";
+import type { AnimationSceneNode } from "./AnimationSceneEditor";
 
 export interface SceneOutlinerItem extends HierarchyNodeDescriptor {
   readonly icon: string;
@@ -16,7 +16,7 @@ export class SceneOutliner {
   private readonly hierarchy = new HierarchyModel();
   private disposers: (() => void)[] = [];
 
-  describe(root: CartoonSceneNode, selectedIds: ReadonlySet<SelectionId> = new Set()): readonly SceneOutlinerItem[] {
+  describe(root: AnimationSceneNode, selectedIds: ReadonlySet<SelectionId> = new Set()): readonly SceneOutlinerItem[] {
     return this.hierarchy.flatten(root, selectedIds).map((item) => {
       const node = findNode(root, String(item.id));
       const kind = node?.kind ?? "unknown";
@@ -28,7 +28,7 @@ export class SceneOutliner {
     });
   }
 
-  render(root: CartoonSceneNode, container: HTMLElement, options: SceneOutlinerOptions = {}): readonly SceneOutlinerItem[] {
+  render(root: AnimationSceneNode, container: HTMLElement, options: SceneOutlinerOptions = {}): readonly SceneOutlinerItem[] {
     this.dispose();
     const items = this.describe(root, options.selectedIds);
     container.replaceChildren();
@@ -68,7 +68,7 @@ function iconForKind(kind: string): string {
   }
 }
 
-function findNode(root: CartoonSceneNode, id: string): CartoonSceneNode | undefined {
+function findNode(root: AnimationSceneNode, id: string): AnimationSceneNode | undefined {
   if (root.id === id) return root;
   for (const child of root.children) {
     const found = findNode(child, id);

package/src/index.ts

@@ -1,17 +1,19 @@
 export type { Command, CommandContext } from "./Command";
 export { CommandHistory, CommandTransactionError } from "./CommandHistory";
 export { AssetDropZone, readAssetFromDataTransfer, serializeAssetForDrag } from "./AssetDropZone";
-export type { AssetDropPlacement, AssetDropResult, AssetDropZoneOptions, CartoonAssetCategory, CartoonEditorAssetReference } from "./AssetDropZone";
+export type { AssetDropPlacement, AssetDropResult, AssetDropZoneOptions, AnimationAssetCategory, AnimationEditorAssetReference } from "./AssetDropZone";
 export { CameraPathEditor, createCameraPathEditor, readCameraPathKeyframes } from "./CameraPathEditor";
 export type { EditorCameraPathEvidence, EditorCameraPathKeyframe, EditorCameraPathSample, EditorCameraVector3 } from "./CameraPathEditor";
-export { CartoonSceneEditor, createCartoonSceneNode } from "./CartoonSceneEditor";
-export type { CartoonSceneEditorOptions, CartoonSceneEditorSnapshot, CartoonSceneEpisodeSnapshot, CartoonSceneEpisodeState, CartoonSceneNode, CartoonSceneTransform } from "./CartoonSceneEditor";
+export { AnimationSceneEditor, createAnimationSceneNode } from "./AnimationSceneEditor";
+export type { AnimationSceneEditorOptions, AnimationSceneEditorSnapshot, AnimationSceneEpisodeSnapshot, AnimationSceneEpisodeState, AnimationSceneNode, AnimationSceneTransform } from "./AnimationSceneEditor";
 export { CurveEditor } from "./CurveEditor";
 export type { TimelineCurveEvidence, TimelineCurvePoint, TimelineCurveSample } from "./CurveEditor";
 export { DiagnosticsOverlayModel } from "./DiagnosticsOverlayModel";
 export type { EditorDiagnosticsInput, EditorDiagnosticsResource, EditorDiagnosticsSnapshot } from "./DiagnosticsOverlayModel";
 export { EditorRuntime } from "./EditorRuntime";
 export type { EditorMode, EditorRuntimeSnapshot } from "./EditorRuntime";
+export { EventTrackEditor, createEventTrackEditor } from "./EventTrackEditor";
+export type { AddEventMarkerOptions, EventMarkerView, EventTrackEditorOptions, EventTrackLane } from "./EventTrackEditor";
 export { EpisodeReviewPanel, createEpisodeReviewPanel } from "./EpisodeReviewPanel";
 export type { EpisodeReviewManualVisemeEdit, EpisodeReviewNote, EpisodeReviewPanelSnapshot, EpisodeReviewPanelState, EpisodeReviewRejectedFrame, EpisodeReviewStatus, EpisodeReviewWaveformLane } from "./EpisodeReviewPanel";
 export { EditorStateModel, createMemoryEditorStateStorage } from "./EditorStateModel";

package/tests/editor-runtime.test.ts

@@ -4,7 +4,7 @@ import { Ray, Vector3 } from "@aura3d/math";
 import { Scene } from "@aura3d/scene";
 import {
   CommandHistory,
-  CartoonSceneEditor,
+  AnimationSceneEditor,
   CameraPathEditor,
   CurveEditor,
   CreateNodeCommand,
@@ -692,8 +692,8 @@ test("KeyframeEditor and CurveEditor author deterministic bezier keyframes on ti
   assert.equal(curve.evidence(clip, "transform.position.x").evidence.deterministicSampling, true);
 });
 
-test("CartoonSceneEditor, AssetDropZone, SceneOutliner, and PropertyPanel compose and edit cartoon scene nodes", async () => {
-  const editor = new CartoonSceneEditor();
+test("AnimationSceneEditor, AssetDropZone, SceneOutliner, and PropertyPanel compose and edit animation scene nodes", async () => {
+  const editor = new AnimationSceneEditor();
   const reviewPanel = new EpisodeReviewPanel({
     packageId: "moon-garden-001",
     packageHash: "sha256-review",
@@ -757,7 +757,7 @@ test("CartoonSceneEditor, AssetDropZone, SceneOutliner, and PropertyPanel compos
   assert.equal(node.transform.position.x, 1);
 
   const serialized = editor.serializeScene();
-  const restored = new CartoonSceneEditor();
+  const restored = new AnimationSceneEditor();
   restored.loadScene(serialized);
   assert.equal(restored.snapshot().nodeCount, 2);
 
@@ -772,7 +772,7 @@ test("CartoonSceneEditor, AssetDropZone, SceneOutliner, and PropertyPanel compos
   }), /typed Aura3D asset reference/);
 });
 
-test("Timeline track type helpers create cartoon timeline lanes compatible with route playback", () => {
+test("Timeline track type helpers create animation timeline lanes compatible with route playback", () => {
   const dialogue = createTimelineTrackConfig("dialogue", "Dialogue");
   const captions = createTimelineTrackConfig("caption", "Captions");
   const shots = createTimelineTrackConfig("shot", "Shots");