@aura3d/editor-runtime 1.4.0 → 1.4.1

package/src/EventTrackEditor.ts

@@ -1,169 +0,0 @@
-// 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/Gizmo.ts

@@ -1,101 +0,0 @@
-import type { Ray } from "@aura3d/math";
-import type { CommandHistory } from "./CommandHistory";
-import type { TransformTarget } from "./commands/TransformCommand";
-
-export type GizmoAxis = "x" | "y" | "z" | "uniform";
-export type GizmoPlaneAxis = "xy" | "xz" | "yz";
-export type GizmoHandle = GizmoAxis | GizmoPlaneAxis;
-export type GizmoSpaceMode = "world" | "local";
-export type GizmoPivotMode = "center" | "active" | "individual";
-
-export interface GizmoSettings {
-  readonly snapEnabled: boolean;
-  readonly positionSnap: number;
-  readonly rotationSnapDegrees: number;
-  readonly scaleSnap: number;
-  readonly spaceMode: GizmoSpaceMode;
-  readonly pivotMode: GizmoPivotMode;
-}
-
-export const DEFAULT_GIZMO_SETTINGS: GizmoSettings = {
-  snapEnabled: false,
-  positionSnap: 1,
-  rotationSnapDegrees: 15,
-  scaleSnap: 0.1,
-  spaceMode: "world",
-  pivotMode: "center"
-};
-
-export interface GizmoHit {
-  readonly axis: GizmoHandle;
-  readonly distance: number;
-}
-
-export interface GizmoDrag {
-  readonly axis: GizmoHandle;
-  readonly delta: number;
-}
-
-export abstract class Gizmo {
-  enabled = true;
-  target?: TransformTarget;
-  protected settings: GizmoSettings = DEFAULT_GIZMO_SETTINGS;
-
-  constructor(protected readonly history: CommandHistory, settings: Partial<GizmoSettings> = {}) {
-    this.configure(settings);
-  }
-
-  setTarget(target: TransformTarget | undefined): void {
-    this.target = target;
-  }
-
-  configure(settings: Partial<GizmoSettings>): void {
-    this.settings = normalizeGizmoSettings({ ...this.settings, ...settings });
-  }
-
-  snapshotSettings(): GizmoSettings {
-    return this.settings;
-  }
-
-  hitTest(_ray: Ray): GizmoHit | undefined {
-    return undefined;
-  }
-
-  abstract drag(input: GizmoDrag): Promise<void>;
-
-  dispose(): void {
-    this.enabled = false;
-    this.target = undefined;
-  }
-
-  protected snapPositionDelta(value: number): number {
-    return this.settings.snapEnabled ? snap(value, this.settings.positionSnap) : value;
-  }
-
-  protected snapRotationDelta(radians: number): number {
-    return this.settings.snapEnabled ? snap(radians, this.settings.rotationSnapDegrees * Math.PI / 180) : radians;
-  }
-
-  protected snapScaleFactor(value: number): number {
-    return this.settings.snapEnabled ? snap(value, this.settings.scaleSnap) : value;
-  }
-}
-
-export function normalizeGizmoSettings(settings: Partial<GizmoSettings> = {}): GizmoSettings {
-  return {
-    snapEnabled: settings.snapEnabled ?? DEFAULT_GIZMO_SETTINGS.snapEnabled,
-    positionSnap: positive(settings.positionSnap, DEFAULT_GIZMO_SETTINGS.positionSnap),
-    rotationSnapDegrees: positive(settings.rotationSnapDegrees, DEFAULT_GIZMO_SETTINGS.rotationSnapDegrees),
-    scaleSnap: positive(settings.scaleSnap, DEFAULT_GIZMO_SETTINGS.scaleSnap),
-    spaceMode: settings.spaceMode ?? DEFAULT_GIZMO_SETTINGS.spaceMode,
-    pivotMode: settings.pivotMode ?? DEFAULT_GIZMO_SETTINGS.pivotMode
-  };
-}
-
-function positive(value: number | undefined, fallback: number): number {
-  return Number.isFinite(value) && Number(value) > 0 ? Number(value) : fallback;
-}
-
-function snap(value: number, increment: number): number {
-  return Math.round(value / increment) * increment;
-}

package/src/HierarchyModel.ts

@@ -1,57 +0,0 @@
-import type { SelectionId } from "./Selection";
-
-export interface HierarchyLikeNode {
-  readonly id?: SelectionId;
-  readonly name?: string;
-  readonly visible?: boolean;
-  readonly children?: readonly HierarchyLikeNode[];
-}
-
-export interface HierarchyNodeDescriptor {
-  readonly id: SelectionId;
-  readonly name: string;
-  readonly visible: boolean;
-  readonly selected: boolean;
-  readonly depth: number;
-  readonly childCount: number;
-  readonly children: readonly HierarchyNodeDescriptor[];
-}
-
-export class HierarchyModel {
-  describe(root: HierarchyLikeNode, selectedIds: ReadonlySet<SelectionId> = new Set()): HierarchyNodeDescriptor {
-    return describeNode(root, selectedIds, 0, "root");
-  }
-
-  flatten(root: HierarchyLikeNode, selectedIds: ReadonlySet<SelectionId> = new Set()): readonly HierarchyNodeDescriptor[] {
-    const output: HierarchyNodeDescriptor[] = [];
-    const visit = (node: HierarchyNodeDescriptor): void => {
-      output.push(node);
-      for (const child of node.children) {
-        visit(child);
-      }
-    };
-    visit(this.describe(root, selectedIds));
-    return output;
-  }
-}
-
-function describeNode(
-  node: HierarchyLikeNode,
-  selectedIds: ReadonlySet<SelectionId>,
-  depth: number,
-  fallbackId: SelectionId
-): HierarchyNodeDescriptor {
-  const id = node.id ?? fallbackId;
-  const name = node.name ?? String(id);
-  const visible = node.visible ?? true;
-  const children = (node.children ?? []).map((child, index) => describeNode(child, selectedIds, depth + 1, `${id}:${index}`));
-  return {
-    id,
-    name,
-    visible,
-    selected: selectedIds.has(id),
-    depth,
-    childCount: children.length,
-    children
-  };
-}

package/src/InspectorModel.ts

@@ -1,71 +0,0 @@
-import { SetPropertyCommand } from "./commands/SetPropertyCommand";
-
-export type InspectorEditableValue = number | string | boolean;
-
-export interface InspectorProperty {
-  readonly path: readonly string[];
-  readonly type: "number" | "string" | "boolean" | "object";
-  readonly value: unknown;
-  readonly editable: boolean;
-}
-
-export class InspectorModel {
-  describe(target: object): readonly InspectorProperty[] {
-    return this.describeObject(target);
-  }
-
-  createSetPropertyCommand<T extends object>(
-    target: T,
-    path: readonly string[],
-    value: InspectorEditableValue
-  ): SetPropertyCommand<T> {
-    const property = this.describe(target).find((descriptor) => samePath(descriptor.path, path));
-    if (!property) {
-      throw new Error(`Inspector property path does not exist: ${path.join(".")}`);
-    }
-    if (!property.editable) {
-      throw new Error(`Inspector property is not editable: ${path.join(".")}`);
-    }
-    this.assertValueMatchesProperty(property, value);
-    return new SetPropertyCommand(target, path, value);
-  }
-
-  private describeObject(target: object, prefix: readonly string[] = []): InspectorProperty[] {
-    const properties: InspectorProperty[] = [];
-    for (const [key, value] of Object.entries(target)) {
-      const path = [...prefix, key];
-      const type = this.propertyType(value);
-      properties.push({
-        path,
-        type,
-        value,
-        editable: type !== "object"
-      });
-      if (type === "object" && typeof value === "object" && value !== null && !Array.isArray(value)) {
-        properties.push(...this.describeObject(value as object, path));
-      }
-    }
-    return properties;
-  }
-
-  private propertyType(value: unknown): InspectorProperty["type"] {
-    const valueType = typeof value;
-    if (valueType === "number" || valueType === "string" || valueType === "boolean") {
-      return valueType;
-    }
-    return "object";
-  }
-
-  private assertValueMatchesProperty(property: InspectorProperty, value: InspectorEditableValue): void {
-    if (property.type === "number" && !Number.isFinite(value)) {
-      throw new Error(`Inspector property ${property.path.join(".")} expected a finite number.`);
-    }
-    if (typeof value !== property.type) {
-      throw new Error(`Inspector property ${property.path.join(".")} expected ${property.type}, got ${typeof value}.`);
-    }
-  }
-}
-
-function samePath(left: readonly string[], right: readonly string[]): boolean {
-  return left.length === right.length && left.every((segment, index) => segment === right[index]);
-}

package/src/KeyframeEditor.ts

@@ -1,214 +0,0 @@
-import type { Command } from "./Command";
-import { CommandHistory } from "./CommandHistory";
-import type { TimelineClip } from "./TimelineModel";
-
-export type TimelineKeyframeValue = number | string | boolean;
-export type TimelineKeyframeInterpolation = "hold" | "linear" | "bezier";
-
-export interface TimelineBezierHandle {
-  readonly time: number;
-  readonly value: number;
-}
-
-export interface TimelineKeyframe {
-  readonly id: string;
-  readonly propertyPath: string;
-  readonly time: number;
-  readonly value: TimelineKeyframeValue;
-  readonly interpolation: TimelineKeyframeInterpolation;
-  readonly inHandle?: TimelineBezierHandle;
-  readonly outHandle?: TimelineBezierHandle;
-}
-
-export interface CreateTimelineKeyframeOptions {
-  readonly id?: string;
-  readonly propertyPath: string;
-  readonly time: number;
-  readonly value: TimelineKeyframeValue;
-  readonly interpolation?: TimelineKeyframeInterpolation;
-  readonly inHandle?: TimelineBezierHandle;
-  readonly outHandle?: TimelineBezierHandle;
-}
-
-export interface PasteTimelineKeyframesOptions {
-  readonly timeOffset?: number;
-  readonly idPrefix?: string;
-  readonly propertyPath?: string;
-}
-
-const KEYFRAME_PROPERTY = "auraKeyframes";
-
-export function readTimelineKeyframes(clip: TimelineClip): readonly TimelineKeyframe[] {
-  const encoded = clip.properties[KEYFRAME_PROPERTY];
-  if (typeof encoded !== "string" || encoded.trim().length === 0) return [];
-  const parsed = JSON.parse(encoded) as TimelineKeyframe[];
-  if (!Array.isArray(parsed)) {
-    throw new Error(`Timeline clip keyframes must decode to an array: ${clip.id}`);
-  }
-  return parsed.map(normalizeKeyframe).sort(compareKeyframes);
-}
-
-export function encodeTimelineKeyframes(keyframes: readonly TimelineKeyframe[]): string {
-  return JSON.stringify([...keyframes].map(normalizeKeyframe).sort(compareKeyframes));
-}
-
-export function timelineKeyframesByProperty(clip: TimelineClip, propertyPath: string): readonly TimelineKeyframe[] {
-  return readTimelineKeyframes(clip).filter((keyframe) => keyframe.propertyPath === propertyPath);
-}
-
-export class KeyframeEditor {
-  constructor(private readonly history = new CommandHistory()) {}
-
-  get commandHistory(): CommandHistory {
-    return this.history;
-  }
-
-  keyframes(clip: TimelineClip, propertyPath?: string): readonly TimelineKeyframe[] {
-    const keyframes = readTimelineKeyframes(clip);
-    return propertyPath ? keyframes.filter((keyframe) => keyframe.propertyPath === propertyPath) : keyframes;
-  }
-
-  async addKeyframe(clip: TimelineClip, options: CreateTimelineKeyframeOptions): Promise<TimelineKeyframe> {
-    const keyframe = normalizeKeyframe({
-      id: options.id ?? stableKeyframeId(options.propertyPath, options.time),
-      propertyPath: options.propertyPath,
-      time: options.time,
-      value: options.value,
-      interpolation: options.interpolation ?? "linear",
-      inHandle: options.inHandle,
-      outHandle: options.outHandle
-    });
-    const next = [...readTimelineKeyframes(clip).filter((candidate) => candidate.id !== keyframe.id), keyframe];
-    await this.applyKeyframes(clip, next, `Add keyframe ${keyframe.id}`);
-    return keyframe;
-  }
-
-  async deleteKeyframes(clip: TimelineClip, ids: readonly string[]): Promise<void> {
-    const remove = new Set(ids);
-    await this.applyKeyframes(clip, readTimelineKeyframes(clip).filter((keyframe) => !remove.has(keyframe.id)), `Delete ${ids.length} keyframes`);
-  }
-
-  async moveKeyframes(clip: TimelineClip, ids: readonly string[], deltaTime: number): Promise<readonly TimelineKeyframe[]> {
-    assertFinite(deltaTime, "Keyframe deltaTime");
-    const move = new Set(ids);
-    const next = readTimelineKeyframes(clip).map((keyframe) => move.has(keyframe.id)
-      ? normalizeKeyframe({ ...keyframe, time: Math.max(0, keyframe.time + deltaTime) })
-      : keyframe);
-    await this.applyKeyframes(clip, next, `Move ${ids.length} keyframes`);
-    return next.filter((keyframe) => move.has(keyframe.id));
-  }
-
-  async scaleKeyframes(clip: TimelineClip, ids: readonly string[], pivotTime: number, scale: number): Promise<readonly TimelineKeyframe[]> {
-    assertFinite(pivotTime, "Keyframe pivotTime");
-    assertFinite(scale, "Keyframe scale");
-    if (scale <= 0) throw new RangeError("Keyframe scale must be positive.");
-    const scaleIds = new Set(ids);
-    const next = readTimelineKeyframes(clip).map((keyframe) => scaleIds.has(keyframe.id)
-      ? normalizeKeyframe({ ...keyframe, time: Math.max(0, pivotTime + (keyframe.time - pivotTime) * scale) })
-      : keyframe);
-    await this.applyKeyframes(clip, next, `Scale ${ids.length} keyframes`);
-    return next.filter((keyframe) => scaleIds.has(keyframe.id));
-  }
-
-  copyKeyframes(clip: TimelineClip, ids: readonly string[]): readonly TimelineKeyframe[] {
-    const copy = new Set(ids);
-    return readTimelineKeyframes(clip).filter((keyframe) => copy.has(keyframe.id)).map((keyframe) => ({ ...keyframe }));
-  }
-
-  async pasteKeyframes(
-    clip: TimelineClip,
-    keyframes: readonly TimelineKeyframe[],
-    options: PasteTimelineKeyframesOptions = {}
-  ): Promise<readonly TimelineKeyframe[]> {
-    const timeOffset = options.timeOffset ?? 0;
-    assertFinite(timeOffset, "Paste keyframe timeOffset");
-    const prefix = options.idPrefix ?? "pasted";
-    const pasted = keyframes.map((keyframe, index) => normalizeKeyframe({
-      ...keyframe,
-      id: `${prefix}-${keyframe.id}-${index}`,
-      propertyPath: options.propertyPath ?? keyframe.propertyPath,
-      time: Math.max(0, keyframe.time + timeOffset)
-    }));
-    await this.applyKeyframes(clip, [...readTimelineKeyframes(clip), ...pasted], `Paste ${pasted.length} keyframes`);
-    return pasted;
-  }
-
-  async replaceKeyframes(clip: TimelineClip, keyframes: readonly TimelineKeyframe[], label = "Replace keyframes"): Promise<void> {
-    await this.applyKeyframes(clip, keyframes, label);
-  }
-
-  private async applyKeyframes(clip: TimelineClip, keyframes: readonly TimelineKeyframe[], name: string): Promise<void> {
-    await this.history.execute(new SetClipKeyframesCommand(clip, keyframes, name));
-  }
-}
-
-class SetClipKeyframesCommand implements Command {
-  readonly name: string;
-  private readonly before: readonly TimelineKeyframe[];
-  private readonly after: readonly TimelineKeyframe[];
-
-  constructor(private readonly clip: TimelineClip, keyframes: readonly TimelineKeyframe[], name: string) {
-    this.name = name;
-    this.before = readTimelineKeyframes(clip);
-    this.after = [...keyframes].map(normalizeKeyframe).sort(compareKeyframes);
-  }
-
-  execute(): void {
-    this.write(this.after);
-  }
-
-  undo(): void {
-    this.write(this.before);
-  }
-
-  private write(keyframes: readonly TimelineKeyframe[]): void {
-    if (keyframes.length === 0) {
-      delete this.clip.properties[KEYFRAME_PROPERTY];
-      return;
-    }
-    this.clip.properties[KEYFRAME_PROPERTY] = encodeTimelineKeyframes(keyframes);
-  }
-}
-
-function normalizeKeyframe(keyframe: TimelineKeyframe): TimelineKeyframe {
-  if (!keyframe.id.trim()) throw new Error("Timeline keyframe id is required.");
-  if (!keyframe.propertyPath.trim()) throw new Error("Timeline keyframe propertyPath is required.");
-  assertFinite(keyframe.time, "Timeline keyframe time");
-  if (keyframe.time < 0) throw new RangeError("Timeline keyframe time must be non-negative.");
-  validateKeyframeValue(keyframe.value);
-  validateHandle(keyframe.inHandle, "inHandle");
-  validateHandle(keyframe.outHandle, "outHandle");
-  return {
-    id: keyframe.id,
-    propertyPath: keyframe.propertyPath,
-    time: Number(keyframe.time.toFixed(4)),
-    value: keyframe.value,
-    interpolation: keyframe.interpolation,
-    inHandle: keyframe.inHandle,
-    outHandle: keyframe.outHandle
-  };
-}
-
-function validateKeyframeValue(value: TimelineKeyframeValue): void {
-  if (typeof value === "number" && !Number.isFinite(value)) {
-    throw new Error("Timeline keyframe numeric values must be finite.");
-  }
-}
-
-function validateHandle(handle: TimelineBezierHandle | undefined, label: string): void {
-  if (!handle) return;
-  assertFinite(handle.time, `Timeline keyframe ${label}.time`);
-  assertFinite(handle.value, `Timeline keyframe ${label}.value`);
-}
-
-function assertFinite(value: number, label: string): void {
-  if (!Number.isFinite(value)) throw new RangeError(`${label} must be finite.`);
-}
-
-function compareKeyframes(left: TimelineKeyframe, right: TimelineKeyframe): number {
-  return left.time - right.time || left.propertyPath.localeCompare(right.propertyPath) || left.id.localeCompare(right.id);
-}
-
-function stableKeyframeId(propertyPath: string, time: number): string {
-  return `key-${propertyPath.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "value"}-${Number(time.toFixed(4)).toString().replace(".", "-")}`;
-}