@aura3d/editor-runtime 1.0.6 → 1.3.0

package/src/CameraPathEditor.ts

@@ -0,0 +1,223 @@
+import { CommandHistory } from "./CommandHistory";
+import { CurveEditor } from "./CurveEditor";
+import { KeyframeEditor, readTimelineKeyframes, type TimelineKeyframe } from "./KeyframeEditor";
+import type { TimelineClip } from "./TimelineModel";
+
+export type EditorCameraVector3 = readonly [number, number, number];
+
+export interface EditorCameraPathKeyframe {
+  readonly id: string;
+  readonly time: number;
+  readonly position: EditorCameraVector3;
+  readonly target: EditorCameraVector3;
+  readonly fov: number;
+  readonly focusDistance?: number;
+  readonly shake?: number;
+  readonly interpolation?: TimelineKeyframe["interpolation"];
+}
+
+export interface EditorCameraPathSample {
+  readonly time: number;
+  readonly position: EditorCameraVector3;
+  readonly target: EditorCameraVector3;
+  readonly fov: number;
+  readonly focusDistance?: number;
+  readonly shake: number;
+}
+
+export interface EditorCameraPathEvidence {
+  readonly clipId: string;
+  readonly cameraKeyframeCount: number;
+  readonly editablePropertyCount: number;
+  readonly sampledPointCount: number;
+  readonly evidence: {
+    readonly shotCameraMoveEditing: boolean;
+    readonly cameraPositionCurves: boolean;
+    readonly cameraTargetCurves: boolean;
+    readonly fovCurve: boolean;
+    readonly deterministicSampling: true;
+  };
+}
+
+const CAMERA_PROPERTY_PATHS = [
+  "camera.position.x",
+  "camera.position.y",
+  "camera.position.z",
+  "camera.target.x",
+  "camera.target.y",
+  "camera.target.z",
+  "camera.fov",
+  "camera.focusDistance",
+  "camera.shake"
+] as const;
+
+type CameraPropertyPath = typeof CAMERA_PROPERTY_PATHS[number];
+
+export class CameraPathEditor {
+  private readonly keyframes: KeyframeEditor;
+  private readonly curves: CurveEditor;
+
+  constructor(history = new CommandHistory()) {
+    this.keyframes = new KeyframeEditor(history);
+    this.curves = new CurveEditor(history);
+  }
+
+  get commandHistory(): CommandHistory {
+    return this.keyframes.commandHistory;
+  }
+
+  async setCameraKeyframe(clip: TimelineClip, keyframe: EditorCameraPathKeyframe): Promise<EditorCameraPathKeyframe> {
+    const normalized = normalizeCameraKeyframe(keyframe);
+    const interpolation = normalized.interpolation ?? "linear";
+    for (const [propertyPath, value] of cameraKeyframeEntries(normalized)) {
+      await this.keyframes.addKeyframe(clip, {
+        id: cameraKeyframePropertyId(normalized.id, propertyPath),
+        propertyPath,
+        time: normalized.time,
+        value,
+        interpolation
+      });
+    }
+    clip.properties.cameraPathEdited = "true";
+    clip.properties.cameraPathKeyframeIds = JSON.stringify(readCameraPathKeyframes(clip).map((frame) => frame.id));
+    return normalized;
+  }
+
+  readCameraPathKeyframes(clip: TimelineClip): readonly EditorCameraPathKeyframe[] {
+    return readCameraPathKeyframes(clip);
+  }
+
+  sample(clip: TimelineClip, time: number): EditorCameraPathSample {
+    assertFinite(time, "Camera path sample time");
+    const fallback = this.readCameraPathKeyframes(clip)[0];
+    if (!fallback) throw new Error(`Camera path clip "${clip.id}" has no editable camera keyframes.`);
+    return {
+      time,
+      position: [
+        numericCurveValue(this.curves.sample(clip, "camera.position.x", time).value, fallback.position[0]),
+        numericCurveValue(this.curves.sample(clip, "camera.position.y", time).value, fallback.position[1]),
+        numericCurveValue(this.curves.sample(clip, "camera.position.z", time).value, fallback.position[2])
+      ],
+      target: [
+        numericCurveValue(this.curves.sample(clip, "camera.target.x", time).value, fallback.target[0]),
+        numericCurveValue(this.curves.sample(clip, "camera.target.y", time).value, fallback.target[1]),
+        numericCurveValue(this.curves.sample(clip, "camera.target.z", time).value, fallback.target[2])
+      ],
+      fov: numericCurveValue(this.curves.sample(clip, "camera.fov", time).value, fallback.fov),
+      focusDistance: optionalNumericCurveValue(this.curves.sample(clip, "camera.focusDistance", time).value, fallback.focusDistance),
+      shake: numericCurveValue(this.curves.sample(clip, "camera.shake", time).value, fallback.shake ?? 0)
+    };
+  }
+
+  evidence(clip: TimelineClip): EditorCameraPathEvidence {
+    const keyframes = this.readCameraPathKeyframes(clip);
+    const encodedKeyframes = readTimelineKeyframes(clip);
+    const fovEvidence = this.curves.evidence(clip, "camera.fov");
+    return {
+      clipId: clip.id,
+      cameraKeyframeCount: keyframes.length,
+      editablePropertyCount: CAMERA_PROPERTY_PATHS.filter((path) => encodedKeyframes.some((keyframe) => keyframe.propertyPath === path)).length,
+      sampledPointCount: fovEvidence.sampledPointCount,
+      evidence: {
+        shotCameraMoveEditing: clip.properties.cameraPathEdited === "true" && keyframes.length >= 2,
+        cameraPositionCurves: ["camera.position.x", "camera.position.y", "camera.position.z"].every((path) => encodedKeyframes.some((keyframe) => keyframe.propertyPath === path)),
+        cameraTargetCurves: ["camera.target.x", "camera.target.y", "camera.target.z"].every((path) => encodedKeyframes.some((keyframe) => keyframe.propertyPath === path)),
+        fovCurve: fovEvidence.keyframeCount >= 2,
+        deterministicSampling: true
+      }
+    };
+  }
+}
+
+export function createCameraPathEditor(history?: CommandHistory): CameraPathEditor {
+  return new CameraPathEditor(history);
+}
+
+export function readCameraPathKeyframes(clip: TimelineClip): readonly EditorCameraPathKeyframe[] {
+  const groups = new Map<string, Partial<Record<CameraPropertyPath, number>> & { time?: number }>();
+  for (const keyframe of readTimelineKeyframes(clip)) {
+    const parsed = parseCameraKeyframePropertyId(keyframe.id);
+    if (!parsed) continue;
+    if (typeof keyframe.value !== "number") continue;
+    const group = groups.get(parsed.frameId) ?? {};
+    group[parsed.propertyPath] = keyframe.value;
+    group.time = keyframe.time;
+    groups.set(parsed.frameId, group);
+  }
+  return [...groups.entries()].flatMap(([id, values]) => {
+    const position = tupleFrom(values["camera.position.x"], values["camera.position.y"], values["camera.position.z"]);
+    const target = tupleFrom(values["camera.target.x"], values["camera.target.y"], values["camera.target.z"]);
+    if (!position || !target || values["camera.fov"] === undefined || values.time === undefined) return [];
+    return [{
+      id,
+      time: values.time,
+      position,
+      target,
+      fov: values["camera.fov"],
+      focusDistance: values["camera.focusDistance"],
+      shake: values["camera.shake"]
+    }];
+  }).sort((a, b) => a.time - b.time || a.id.localeCompare(b.id));
+}
+
+function cameraKeyframeEntries(keyframe: EditorCameraPathKeyframe): readonly (readonly [CameraPropertyPath, number])[] {
+  return [
+    ["camera.position.x", keyframe.position[0]],
+    ["camera.position.y", keyframe.position[1]],
+    ["camera.position.z", keyframe.position[2]],
+    ["camera.target.x", keyframe.target[0]],
+    ["camera.target.y", keyframe.target[1]],
+    ["camera.target.z", keyframe.target[2]],
+    ["camera.fov", keyframe.fov],
+    ["camera.focusDistance", keyframe.focusDistance ?? 0],
+    ["camera.shake", keyframe.shake ?? 0]
+  ];
+}
+
+function normalizeCameraKeyframe(keyframe: EditorCameraPathKeyframe): EditorCameraPathKeyframe {
+  const id = keyframe.id.trim();
+  if (!id) throw new Error("Camera path keyframe id is required.");
+  assertFinite(keyframe.time, "Camera path keyframe time");
+  if (keyframe.time < 0) throw new RangeError("Camera path keyframe time must be non-negative.");
+  assertVector3(keyframe.position, "Camera path keyframe position");
+  assertVector3(keyframe.target, "Camera path keyframe target");
+  assertFinite(keyframe.fov, "Camera path keyframe fov");
+  if (keyframe.fov <= 0) throw new RangeError("Camera path keyframe fov must be positive.");
+  if (keyframe.focusDistance !== undefined) assertFinite(keyframe.focusDistance, "Camera path keyframe focusDistance");
+  if (keyframe.shake !== undefined) assertFinite(keyframe.shake, "Camera path keyframe shake");
+  return { ...keyframe, id };
+}
+
+function cameraKeyframePropertyId(frameId: string, propertyPath: string): string {
+  return `${frameId}#${propertyPath}`;
+}
+
+function parseCameraKeyframePropertyId(id: string): { readonly frameId: string; readonly propertyPath: CameraPropertyPath } | undefined {
+  const separator = id.lastIndexOf("#");
+  if (separator <= 0) return undefined;
+  const propertyPath = id.slice(separator + 1);
+  if (!CAMERA_PROPERTY_PATHS.includes(propertyPath as CameraPropertyPath)) return undefined;
+  return { frameId: id.slice(0, separator), propertyPath: propertyPath as CameraPropertyPath };
+}
+
+function tupleFrom(x: number | undefined, y: number | undefined, z: number | undefined): EditorCameraVector3 | undefined {
+  return x === undefined || y === undefined || z === undefined ? undefined : [x, y, z];
+}
+
+function numericCurveValue(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function optionalNumericCurveValue(value: unknown, fallback: number | undefined): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  return fallback;
+}
+
+function assertVector3(value: EditorCameraVector3, label: string): void {
+  if (value.length !== 3) throw new Error(`${label} must contain three numeric components.`);
+  for (const component of value) assertFinite(component, label);
+}
+
+function assertFinite(value: number, label: string): void {
+  if (!Number.isFinite(value)) throw new RangeError(`${label} must be finite.`);
+}

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));
+}

package/src/EpisodeReviewPanel.ts

@@ -0,0 +1,236 @@
+export type EpisodeReviewStatus = "draft" | "needs-review" | "approved" | "rejected";
+
+export interface EpisodeReviewRejectedFrame {
+  readonly id: string;
+  readonly time: number;
+  readonly reason: string;
+}
+
+export interface EpisodeReviewNote {
+  readonly id: string;
+  readonly author: string;
+  readonly text: string;
+  readonly time?: number;
+}
+
+export interface EpisodeReviewWaveformLane {
+  readonly id: string;
+  readonly label: string;
+  readonly startTime: number;
+  readonly duration: number;
+  readonly peakCount: number;
+  readonly pathPointCount: number;
+}
+
+export interface EpisodeReviewManualVisemeEdit {
+  readonly id: string;
+  readonly characterId: string;
+  readonly visemeId: string;
+  readonly startTime: number;
+  readonly endTime: number;
+  readonly reason?: string;
+}
+
+export interface EpisodeReviewPanelState {
+  readonly packageId: string;
+  readonly packageHash?: string;
+  readonly status: EpisodeReviewStatus;
+  readonly reviewer?: string;
+  readonly approvedAt?: string;
+  readonly notes: readonly EpisodeReviewNote[];
+  readonly rejectedFrames: readonly EpisodeReviewRejectedFrame[];
+  readonly waveformLanes?: readonly EpisodeReviewWaveformLane[];
+  readonly manualVisemeEdits?: readonly EpisodeReviewManualVisemeEdit[];
+}
+
+export interface EpisodeReviewPanelSnapshot extends EpisodeReviewPanelState {
+  readonly kind: "episode-review-panel";
+  readonly approvalRecorded: boolean;
+  readonly rejectedFrameCount: number;
+  readonly noteCount: number;
+  readonly waveformLaneCount: number;
+  readonly manualVisemeEditCount: number;
+  readonly reviewUiEvidence: {
+    readonly waveformReview: boolean;
+    readonly manualVisemeEdits: boolean;
+    readonly visualFrameReview: boolean;
+    readonly reviewerNotes: boolean;
+  };
+}
+
+export class EpisodeReviewPanel {
+  private state: EpisodeReviewPanelState;
+
+  constructor(state: EpisodeReviewPanelState) {
+    this.state = sanitizeReviewState(state);
+  }
+
+  addNote(note: EpisodeReviewNote): EpisodeReviewPanelSnapshot {
+    this.state = sanitizeReviewState({
+      ...this.state,
+      notes: [...this.state.notes, sanitizeReviewNote(note)]
+    });
+    return this.snapshot();
+  }
+
+  rejectFrame(frame: EpisodeReviewRejectedFrame): EpisodeReviewPanelSnapshot {
+    this.state = sanitizeReviewState({
+      ...this.state,
+      status: "rejected",
+      rejectedFrames: [...this.state.rejectedFrames, sanitizeRejectedFrame(frame)]
+    });
+    return this.snapshot();
+  }
+
+  setWaveformLanes(waveformLanes: readonly EpisodeReviewWaveformLane[]): EpisodeReviewPanelSnapshot {
+    this.state = sanitizeReviewState({
+      ...this.state,
+      waveformLanes: waveformLanes.map(sanitizeWaveformLane)
+    });
+    return this.snapshot();
+  }
+
+  applyManualVisemeEdit(edit: EpisodeReviewManualVisemeEdit): EpisodeReviewPanelSnapshot {
+    const sanitized = sanitizeManualVisemeEdit(edit);
+    this.state = sanitizeReviewState({
+      ...this.state,
+      manualVisemeEdits: [
+        ...((this.state.manualVisemeEdits ?? []).filter((candidate) => candidate.id !== sanitized.id)),
+        sanitized
+      ]
+    });
+    return this.snapshot();
+  }
+
+  approve(reviewer: string, approvedAt = new Date(0).toISOString()): EpisodeReviewPanelSnapshot {
+    const name = nonEmpty(reviewer, "Episode review reviewer");
+    if (this.state.rejectedFrames.length > 0) {
+      throw new Error("Episode review cannot be approved while rejected frames are present.");
+    }
+    this.state = sanitizeReviewState({
+      ...this.state,
+      status: "approved",
+      reviewer: name,
+      approvedAt
+    });
+    return this.snapshot();
+  }
+
+  markNeedsReview(): EpisodeReviewPanelSnapshot {
+    this.state = sanitizeReviewState({
+      ...this.state,
+      status: "needs-review",
+      reviewer: undefined,
+      approvedAt: undefined
+    });
+    return this.snapshot();
+  }
+
+  serialize(): EpisodeReviewPanelState {
+    return sanitizeReviewState(this.state);
+  }
+
+  snapshot(): EpisodeReviewPanelSnapshot {
+    const waveformLanes = this.state.waveformLanes ?? [];
+    const manualVisemeEdits = this.state.manualVisemeEdits ?? [];
+    return {
+      kind: "episode-review-panel",
+      ...this.serialize(),
+      approvalRecorded: this.state.status === "approved" && Boolean(this.state.reviewer),
+      rejectedFrameCount: this.state.rejectedFrames.length,
+      noteCount: this.state.notes.length,
+      waveformLaneCount: waveformLanes.length,
+      manualVisemeEditCount: manualVisemeEdits.length,
+      reviewUiEvidence: {
+        waveformReview: waveformLanes.length > 0,
+        manualVisemeEdits: manualVisemeEdits.length > 0,
+        visualFrameReview: this.state.rejectedFrames.length > 0,
+        reviewerNotes: this.state.notes.length > 0
+      }
+    };
+  }
+}
+
+export function createEpisodeReviewPanel(state: EpisodeReviewPanelState): EpisodeReviewPanel {
+  return new EpisodeReviewPanel(state);
+}
+
+function sanitizeReviewState(state: EpisodeReviewPanelState): EpisodeReviewPanelState {
+  return {
+    packageId: nonEmpty(state.packageId, "Episode review packageId"),
+    packageHash: state.packageHash,
+    status: state.status,
+    reviewer: state.reviewer,
+    approvedAt: state.approvedAt,
+    notes: state.notes.map(sanitizeReviewNote),
+    rejectedFrames: state.rejectedFrames.map(sanitizeRejectedFrame),
+    waveformLanes: (state.waveformLanes ?? []).map(sanitizeWaveformLane),
+    manualVisemeEdits: (state.manualVisemeEdits ?? []).map(sanitizeManualVisemeEdit)
+  };
+}
+
+function sanitizeReviewNote(note: EpisodeReviewNote): EpisodeReviewNote {
+  return {
+    id: nonEmpty(note.id, "Episode review note id"),
+    author: nonEmpty(note.author, "Episode review note author"),
+    text: nonEmpty(note.text, "Episode review note text"),
+    time: note.time
+  };
+}
+
+function sanitizeRejectedFrame(frame: EpisodeReviewRejectedFrame): EpisodeReviewRejectedFrame {
+  if (!Number.isFinite(frame.time) || frame.time < 0) {
+    throw new Error("Episode review rejected frame time must be a non-negative finite number.");
+  }
+  return {
+    id: nonEmpty(frame.id, "Episode review rejected frame id"),
+    time: frame.time,
+    reason: nonEmpty(frame.reason, "Episode review rejected frame reason")
+  };
+}
+
+function sanitizeWaveformLane(lane: EpisodeReviewWaveformLane): EpisodeReviewWaveformLane {
+  if (!Number.isFinite(lane.startTime) || lane.startTime < 0) {
+    throw new Error("Episode review waveform lane startTime must be a non-negative finite number.");
+  }
+  if (!Number.isFinite(lane.duration) || lane.duration < 0) {
+    throw new Error("Episode review waveform lane duration must be a non-negative finite number.");
+  }
+  if (!Number.isInteger(lane.peakCount) || lane.peakCount < 0) {
+    throw new Error("Episode review waveform lane peakCount must be a non-negative integer.");
+  }
+  if (!Number.isInteger(lane.pathPointCount) || lane.pathPointCount < 0) {
+    throw new Error("Episode review waveform lane pathPointCount must be a non-negative integer.");
+  }
+  return {
+    id: nonEmpty(lane.id, "Episode review waveform lane id"),
+    label: nonEmpty(lane.label, "Episode review waveform lane label"),
+    startTime: lane.startTime,
+    duration: lane.duration,
+    peakCount: lane.peakCount,
+    pathPointCount: lane.pathPointCount
+  };
+}
+
+function sanitizeManualVisemeEdit(edit: EpisodeReviewManualVisemeEdit): EpisodeReviewManualVisemeEdit {
+  if (!Number.isFinite(edit.startTime) || edit.startTime < 0) {
+    throw new Error("Episode review manual viseme startTime must be a non-negative finite number.");
+  }
+  if (!Number.isFinite(edit.endTime) || edit.endTime <= edit.startTime) {
+    throw new Error("Episode review manual viseme endTime must be greater than startTime.");
+  }
+  return {
+    id: nonEmpty(edit.id, "Episode review manual viseme id"),
+    characterId: nonEmpty(edit.characterId, "Episode review manual viseme characterId"),
+    visemeId: nonEmpty(edit.visemeId, "Episode review manual viseme visemeId"),
+    startTime: edit.startTime,
+    endTime: edit.endTime,
+    reason: edit.reason
+  };
+}
+
+function nonEmpty(value: string, label: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) throw new Error(`${label} must be a non-empty string.`);
+  return trimmed;
+}