@aura3d/editor-runtime 1.0.6 → 1.1.0

package/src/CartoonSceneEditor.ts

@@ -0,0 +1,368 @@
+import type { Command } from "./Command";
+import { EditorRuntime } from "./EditorRuntime";
+import type { EpisodeReviewPanelSnapshot } from "./EpisodeReviewPanel";
+import type { HierarchyLikeNode } from "./HierarchyModel";
+import type { RenderQueuePanelSnapshot } from "./RenderQueuePanel";
+import { AssetDropZone, type AssetDropPlacement, type CartoonAssetCategory, type CartoonEditorAssetReference } from "./AssetDropZone";
+
+export interface CartoonSceneTransform {
+  position: { x: number; y: number; z: number };
+  rotation: { x: number; y: number; z: number; w: number };
+  scale: { x: number; y: number; z: number };
+}
+
+export interface CartoonSceneNode extends HierarchyLikeNode {
+  readonly id: string;
+  name: string;
+  kind: CartoonAssetCategory;
+  visible: boolean;
+  asset?: CartoonEditorAssetReference;
+  transform: CartoonSceneTransform;
+  animationClips: string[];
+  material?: string;
+  readonly children: CartoonSceneNode[];
+}
+
+export interface CartoonSceneEditorSnapshot {
+  readonly nodeCount: number;
+  readonly selectedIds: readonly (string | number)[];
+  readonly placedAssetCount: number;
+  readonly cameraPreviewId: string | null;
+  readonly hierarchy: ReturnType<EditorRuntime["flattenHierarchy"]>;
+  readonly evidence: {
+    readonly assetPlacement: boolean;
+    readonly transformGizmos: true;
+    readonly propertyInspector: true;
+    readonly sceneSaveLoad: true;
+    readonly episodeState: boolean;
+  };
+  readonly episode: CartoonSceneEpisodeSnapshot;
+}
+
+export interface CartoonSceneEditorOptions {
+  readonly runtime?: EditorRuntime;
+  readonly root?: CartoonSceneNode;
+  readonly episode?: Partial<CartoonSceneEpisodeState>;
+}
+
+export interface CartoonSceneEpisodeState {
+  readonly shots: readonly string[];
+  readonly assets: readonly string[];
+  readonly captions: readonly string[];
+  readonly visemes: readonly string[];
+  readonly renderState?: RenderQueuePanelSnapshot;
+  readonly reviewState?: EpisodeReviewPanelSnapshot;
+}
+
+export interface CartoonSceneEpisodeSnapshot extends CartoonSceneEpisodeState {
+  readonly shotCount: number;
+  readonly assetCount: number;
+  readonly captionCount: number;
+  readonly visemeCount: number;
+  readonly hasRenderState: boolean;
+  readonly hasReviewState: boolean;
+}
+
+export class CartoonSceneEditor {
+  readonly runtime: EditorRuntime;
+  readonly root: CartoonSceneNode;
+  readonly dropZone: AssetDropZone<CartoonSceneNode>;
+  private cameraPreviewIdInternal: string | null = null;
+  private episodeState: CartoonSceneEpisodeState;
+
+  constructor(options: CartoonSceneEditorOptions = {}) {
+    this.runtime = options.runtime ?? new EditorRuntime();
+    this.root = options.root ?? createCartoonSceneNode({ id: "scene-root", name: "Scene", kind: "set" });
+    this.episodeState = normalizeEpisodeState(options.episode ?? {});
+    this.dropZone = new AssetDropZone<CartoonSceneNode>({
+      history: this.runtime.history,
+      createNode: (asset, placement) => this.createNodeFromAsset(asset, placement),
+      addNode: (node, placement) => this.addNode(node, placement.targetId),
+      removeNode: (node) => this.removeNode(node.id)
+    });
+  }
+
+  async placeAsset(asset: CartoonEditorAssetReference, placement: AssetDropPlacement = {}): Promise<CartoonSceneNode> {
+    const result = await this.dropZone.dropAsset(asset, placement);
+    this.runtime.select([result.node.id]);
+    return result.node;
+  }
+
+  async addEmptyNode(config: { readonly id?: string; readonly name: string; readonly kind?: CartoonAssetCategory; readonly parentId?: string }): Promise<CartoonSceneNode> {
+    const node = createCartoonSceneNode({
+      id: config.id ?? stableNodeId(config.name),
+      name: config.name,
+      kind: config.kind ?? "prop"
+    });
+    await this.runtime.history.execute(new AddCartoonNodeCommand(this.root, node, config.parentId));
+    return node;
+  }
+
+  async removeNode(id: string): Promise<void> {
+    if (id === this.root.id) throw new Error("Cannot remove the root cartoon scene node.");
+    const parent = findParent(this.root, id);
+    const node = findNode(this.root, id);
+    if (!parent || !node) throw new Error(`Cartoon scene node does not exist: ${id}`);
+    await this.runtime.history.execute(new RemoveCartoonNodeCommand(parent, node));
+    this.runtime.pruneSelection((selectionId) => selectionId !== id);
+  }
+
+  async setTransform(id: string, transform: Partial<CartoonSceneTransform>): Promise<void> {
+    const node = this.requireNode(id);
+    await this.runtime.history.execute(new SetCartoonTransformCommand(node, mergeTransform(node.transform, transform)));
+  }
+
+  selectNode(id: string): void {
+    this.requireNode(id);
+    this.runtime.select([id]);
+  }
+
+  setCameraPreview(id: string | null): void {
+    if (id !== null) {
+      const node = this.requireNode(id);
+      if (node.kind !== "camera") throw new Error(`Camera preview requires a camera node: ${id}`);
+    }
+    this.cameraPreviewIdInternal = id;
+  }
+
+  setEpisodeState(state: Partial<CartoonSceneEpisodeState>): CartoonSceneEpisodeSnapshot {
+    this.episodeState = normalizeEpisodeState({ ...this.episodeState, ...state });
+    return this.episodeSnapshot();
+  }
+
+  serializeScene(): CartoonSceneNode {
+    return cloneNode(this.root);
+  }
+
+  loadScene(root: CartoonSceneNode): void {
+    this.root.children.splice(0, this.root.children.length, ...root.children.map(cloneNode));
+    this.root.name = root.name;
+    this.root.visible = root.visible;
+    this.runtime.clearSelection();
+  }
+
+  flattenHierarchy(): ReturnType<EditorRuntime["flattenHierarchy"]> {
+    return this.runtime.flattenHierarchy(this.root);
+  }
+
+  inspectSelected(): readonly ReturnType<EditorRuntime["inspect"]>[number][] {
+    const selected = this.runtime.currentSelection()[0];
+    if (selected === undefined) return [];
+    return this.runtime.inspect(this.requireNode(String(selected)));
+  }
+
+  snapshot(): CartoonSceneEditorSnapshot {
+    const nodes = flattenNodes(this.root);
+    return {
+      nodeCount: nodes.length,
+      selectedIds: this.runtime.currentSelection(),
+      placedAssetCount: nodes.filter((node) => node.asset).length,
+      cameraPreviewId: this.cameraPreviewIdInternal,
+      hierarchy: this.flattenHierarchy(),
+      evidence: {
+        assetPlacement: nodes.some((node) => node.asset),
+        transformGizmos: true,
+        propertyInspector: true,
+        sceneSaveLoad: true,
+        episodeState: this.episodeState.shots.length > 0
+          || this.episodeState.captions.length > 0
+          || this.episodeState.visemes.length > 0
+          || Boolean(this.episodeState.renderState)
+          || Boolean(this.episodeState.reviewState)
+      },
+      episode: this.episodeSnapshot()
+    };
+  }
+
+  private episodeSnapshot(): CartoonSceneEpisodeSnapshot {
+    return {
+      ...this.episodeState,
+      shotCount: this.episodeState.shots.length,
+      assetCount: this.episodeState.assets.length,
+      captionCount: this.episodeState.captions.length,
+      visemeCount: this.episodeState.visemes.length,
+      hasRenderState: Boolean(this.episodeState.renderState),
+      hasReviewState: Boolean(this.episodeState.reviewState)
+    };
+  }
+
+  private createNodeFromAsset(asset: CartoonEditorAssetReference, placement: AssetDropPlacement): CartoonSceneNode {
+    return createCartoonSceneNode({
+      id: stableNodeId(asset.id),
+      name: asset.name,
+      kind: asset.category ?? categoryFromAsset(asset),
+      asset,
+      transform: mergeTransform(defaultTransform(), placement)
+    });
+  }
+
+  private addNode(node: CartoonSceneNode, parentId?: string | number): void {
+    const parent = parentId === undefined ? this.root : this.requireNode(String(parentId));
+    parent.children.push(node);
+  }
+
+  private requireNode(id: string): CartoonSceneNode {
+    const node = findNode(this.root, id);
+    if (!node) throw new Error(`Cartoon scene node does not exist: ${id}`);
+    return node;
+  }
+}
+
+function normalizeEpisodeState(state: Partial<CartoonSceneEpisodeState>): CartoonSceneEpisodeState {
+  return {
+    shots: [...(state.shots ?? [])],
+    assets: [...(state.assets ?? [])],
+    captions: [...(state.captions ?? [])],
+    visemes: [...(state.visemes ?? [])],
+    renderState: state.renderState,
+    reviewState: state.reviewState
+  };
+}
+
+export function createCartoonSceneNode(config: {
+  readonly id: string;
+  readonly name: string;
+  readonly kind: CartoonAssetCategory;
+  readonly asset?: CartoonEditorAssetReference;
+  readonly transform?: CartoonSceneTransform;
+  readonly visible?: boolean;
+  readonly animationClips?: readonly string[];
+  readonly material?: string;
+  readonly children?: readonly CartoonSceneNode[];
+}): CartoonSceneNode {
+  return {
+    id: config.id,
+    name: config.name,
+    kind: config.kind,
+    visible: config.visible ?? true,
+    asset: config.asset,
+    transform: config.transform ?? defaultTransform(),
+    animationClips: [...(config.animationClips ?? config.asset?.clips ?? [])],
+    material: config.material,
+    children: [...(config.children ?? [])]
+  };
+}
+
+class AddCartoonNodeCommand implements Command {
+  readonly name: string;
+
+  constructor(private readonly root: CartoonSceneNode, private readonly node: CartoonSceneNode, private readonly parentId?: string) {
+    this.name = `Add cartoon node ${node.id}`;
+  }
+
+  execute(): void {
+    const parent = this.parentId ? findNode(this.root, this.parentId) : this.root;
+    if (!parent) throw new Error(`Cartoon scene parent does not exist: ${this.parentId}`);
+    if (!parent.children.includes(this.node)) parent.children.push(this.node);
+  }
+
+  undo(): void {
+    const parent = findParent(this.root, this.node.id);
+    if (parent) removeChild(parent, this.node);
+  }
+}
+
+class RemoveCartoonNodeCommand implements Command {
+  readonly name: string;
+  private index = -1;
+
+  constructor(private readonly parent: CartoonSceneNode, private readonly node: CartoonSceneNode) {
+    this.name = `Remove cartoon node ${node.id}`;
+  }
+
+  execute(): void {
+    this.index = this.parent.children.indexOf(this.node);
+    removeChild(this.parent, this.node);
+  }
+
+  undo(): void {
+    if (!this.parent.children.includes(this.node)) {
+      this.parent.children.splice(this.index < 0 ? this.parent.children.length : this.index, 0, this.node);
+    }
+  }
+}
+
+class SetCartoonTransformCommand implements Command {
+  readonly name: string;
+  private readonly before: CartoonSceneTransform;
+
+  constructor(private readonly node: CartoonSceneNode, private readonly after: CartoonSceneTransform) {
+    this.name = `Set cartoon transform ${node.id}`;
+    this.before = cloneTransform(node.transform);
+  }
+
+  execute(): void {
+    this.node.transform = cloneTransform(this.after);
+  }
+
+  undo(): void {
+    this.node.transform = cloneTransform(this.before);
+  }
+}
+
+function categoryFromAsset(asset: CartoonEditorAssetReference): CartoonAssetCategory {
+  if (asset.type === "audio") return "audio";
+  if (asset.type === "material") return "material";
+  if (asset.clips && asset.clips.length > 0) return "character";
+  return "prop";
+}
+
+function findNode(root: CartoonSceneNode, id: string): CartoonSceneNode | undefined {
+  if (root.id === id) return root;
+  for (const child of root.children) {
+    const found = findNode(child, id);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+function findParent(root: CartoonSceneNode, id: string): CartoonSceneNode | undefined {
+  for (const child of root.children) {
+    if (child.id === id) return root;
+    const found = findParent(child, id);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+function flattenNodes(root: CartoonSceneNode): readonly CartoonSceneNode[] {
+  return [root, ...root.children.flatMap((child) => flattenNodes(child))];
+}
+
+function removeChild(parent: CartoonSceneNode, node: CartoonSceneNode): void {
+  const index = parent.children.indexOf(node);
+  if (index >= 0) parent.children.splice(index, 1);
+}
+
+function defaultTransform(): CartoonSceneTransform {
+  return {
+    position: { x: 0, y: 0, z: 0 },
+    rotation: { x: 0, y: 0, z: 0, w: 1 },
+    scale: { x: 1, y: 1, z: 1 }
+  };
+}
+
+function mergeTransform(base: CartoonSceneTransform, next: Partial<CartoonSceneTransform> | AssetDropPlacement): CartoonSceneTransform {
+  return {
+    position: { ...base.position, ...(next.position ?? {}) },
+    rotation: { ...base.rotation, ...(next.rotation ?? {}) },
+    scale: { ...base.scale, ...(next.scale ?? {}) }
+  };
+}
+
+function cloneTransform(transform: CartoonSceneTransform): CartoonSceneTransform {
+  return mergeTransform(defaultTransform(), transform);
+}
+
+function cloneNode(node: CartoonSceneNode): CartoonSceneNode {
+  return createCartoonSceneNode({
+    ...node,
+    transform: cloneTransform(node.transform),
+    animationClips: [...node.animationClips],
+    children: node.children.map(cloneNode)
+  });
+}
+
+function stableNodeId(name: string): string {
+  return `node-${name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "item"}`;
+}

package/src/CurveEditor.ts

@@ -0,0 +1,152 @@
+import { CommandHistory } from "./CommandHistory";
+import { KeyframeEditor, readTimelineKeyframes, type TimelineBezierHandle, type TimelineKeyframe, type TimelineKeyframeValue } from "./KeyframeEditor";
+import type { TimelineClip } from "./TimelineModel";
+
+export interface TimelineCurvePoint {
+  readonly time: number;
+  readonly value: number;
+}
+
+export interface TimelineCurveSample {
+  readonly propertyPath: string;
+  readonly time: number;
+  readonly value: TimelineKeyframeValue | undefined;
+  readonly segmentStartId?: string;
+  readonly segmentEndId?: string;
+}
+
+export interface TimelineCurveEvidence {
+  readonly propertyPath: string;
+  readonly keyframeCount: number;
+  readonly bezierSegmentCount: number;
+  readonly sampledPointCount: number;
+  readonly evidence: {
+    readonly deterministicSampling: true;
+    readonly bezierHandles: boolean;
+    readonly holdInterpolation: boolean;
+  };
+}
+
+export class CurveEditor {
+  private readonly keyframes: KeyframeEditor;
+
+  constructor(history = new CommandHistory()) {
+    this.keyframes = new KeyframeEditor(history);
+  }
+
+  get commandHistory(): CommandHistory {
+    return this.keyframes.commandHistory;
+  }
+
+  sample(clip: TimelineClip, propertyPath: string, time: number): TimelineCurveSample {
+    assertFinite(time, "Curve sample time");
+    const keyframes = propertyKeyframes(clip, propertyPath);
+    if (keyframes.length === 0) {
+      return { propertyPath, time, value: undefined };
+    }
+    if (time <= keyframes[0].time) {
+      return { propertyPath, time, value: keyframes[0].value, segmentStartId: keyframes[0].id };
+    }
+    const last = keyframes[keyframes.length - 1];
+    if (time >= last.time) {
+      return { propertyPath, time, value: last.value, segmentStartId: last.id };
+    }
+    const endIndex = keyframes.findIndex((keyframe) => keyframe.time >= time);
+    const start = keyframes[endIndex - 1];
+    const end = keyframes[endIndex];
+    if (!start || !end) {
+      return { propertyPath, time, value: last.value, segmentStartId: last.id };
+    }
+    return {
+      propertyPath,
+      time,
+      value: sampleSegment(start, end, time),
+      segmentStartId: start.id,
+      segmentEndId: end.id
+    };
+  }
+
+  samplePoints(clip: TimelineClip, propertyPath: string, startTime: number, endTime: number, steps: number): readonly TimelineCurvePoint[] {
+    assertFinite(startTime, "Curve startTime");
+    assertFinite(endTime, "Curve endTime");
+    if (endTime < startTime) throw new RangeError("Curve endTime must be greater than or equal to startTime.");
+    if (!Number.isInteger(steps) || steps < 1) throw new RangeError("Curve sample steps must be a positive integer.");
+    const points: TimelineCurvePoint[] = [];
+    for (let index = 0; index <= steps; index += 1) {
+      const time = startTime + (endTime - startTime) * (index / steps);
+      const value = this.sample(clip, propertyPath, time).value;
+      if (typeof value === "number") {
+        points.push({ time: Number(time.toFixed(4)), value: Number(value.toFixed(4)) });
+      }
+    }
+    return points;
+  }
+
+  async setBezierHandles(
+    clip: TimelineClip,
+    keyframeId: string,
+    handles: { readonly inHandle?: TimelineBezierHandle; readonly outHandle?: TimelineBezierHandle }
+  ): Promise<TimelineKeyframe> {
+    const keyframes = readTimelineKeyframes(clip);
+    const target = keyframes.find((keyframe) => keyframe.id === keyframeId);
+    if (!target) throw new Error(`Timeline keyframe does not exist: ${keyframeId}`);
+    const updated: TimelineKeyframe = {
+      ...target,
+      interpolation: "bezier",
+      inHandle: handles.inHandle,
+      outHandle: handles.outHandle
+    };
+    await this.keyframes.replaceKeyframes(
+      clip,
+      keyframes.map((keyframe) => keyframe.id === keyframeId ? updated : keyframe),
+      `Set bezier handles ${keyframeId}`
+    );
+    return updated;
+  }
+
+  evidence(clip: TimelineClip, propertyPath: string, sampleCount = 8): TimelineCurveEvidence {
+    const keyframes = propertyKeyframes(clip, propertyPath);
+    const startTime = keyframes[0]?.time ?? 0;
+    const endTime = keyframes[keyframes.length - 1]?.time ?? startTime;
+    return {
+      propertyPath,
+      keyframeCount: keyframes.length,
+      bezierSegmentCount: keyframes.filter((keyframe) => keyframe.interpolation === "bezier").length,
+      sampledPointCount: this.samplePoints(clip, propertyPath, startTime, endTime, Math.max(1, sampleCount)).length,
+      evidence: {
+        deterministicSampling: true,
+        bezierHandles: keyframes.some((keyframe) => keyframe.inHandle || keyframe.outHandle),
+        holdInterpolation: keyframes.some((keyframe) => keyframe.interpolation === "hold")
+      }
+    };
+  }
+}
+
+function propertyKeyframes(clip: TimelineClip, propertyPath: string): readonly TimelineKeyframe[] {
+  return readTimelineKeyframes(clip).filter((keyframe) => keyframe.propertyPath === propertyPath);
+}
+
+function sampleSegment(start: TimelineKeyframe, end: TimelineKeyframe, time: number): TimelineKeyframeValue {
+  if (start.interpolation === "hold" || typeof start.value !== "number" || typeof end.value !== "number") {
+    return start.value;
+  }
+  const duration = end.time - start.time;
+  const t = duration <= 0 ? 1 : clamp((time - start.time) / duration, 0, 1);
+  if (start.interpolation !== "bezier") {
+    return Number((start.value + (end.value - start.value) * t).toFixed(4));
+  }
+  const p0 = start.value;
+  const p1 = start.value + (start.outHandle?.value ?? 0);
+  const p2 = end.value + (end.inHandle?.value ?? 0);
+  const p3 = end.value;
+  const inv = 1 - t;
+  return Number((inv * inv * inv * p0 + 3 * inv * inv * t * p1 + 3 * inv * t * t * p2 + t * t * t * p3).toFixed(4));
+}
+
+function assertFinite(value: number, label: string): void {
+  if (!Number.isFinite(value)) throw new RangeError(`${label} must be finite.`);
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}