@aura3d/editor-runtime 1.0.6 → 1.3.0

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/KeyframeEditor.ts

@@ -0,0 +1,214 @@
+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(".", "-")}`;
+}

package/src/MultiUserReviewWorkflow.ts

@@ -0,0 +1,229 @@
+export type ReviewParticipantRole = "owner" | "reviewer" | "animator" | "audio" | "viewer";
+export type ReviewDecisionStatus = "pending" | "approved" | "changes-requested";
+export type ReviewWorkflowStatus = "draft" | "needs-review" | "changes-requested" | "approved";
+
+export interface ReviewParticipant {
+  readonly id: string;
+  readonly name: string;
+  readonly role: ReviewParticipantRole;
+  readonly active?: boolean | undefined;
+}
+
+export interface ReviewThread {
+  readonly id: string;
+  readonly authorId: string;
+  readonly text: string;
+  readonly time?: number | undefined;
+  readonly frame?: number | undefined;
+  readonly assignedTo?: string | undefined;
+  readonly resolved: boolean;
+}
+
+export interface ReviewDecision {
+  readonly reviewerId: string;
+  readonly status: ReviewDecisionStatus;
+  readonly at: string;
+  readonly note?: string | undefined;
+}
+
+export interface MultiUserReviewWorkflowState {
+  readonly packageId: string;
+  readonly status?: ReviewWorkflowStatus | undefined;
+  readonly requiredReviewerCount?: number | undefined;
+  readonly participants: readonly ReviewParticipant[];
+  readonly threads: readonly ReviewThread[];
+  readonly decisions: readonly ReviewDecision[];
+}
+
+export interface MultiUserReviewWorkflowSnapshot {
+  readonly kind: "multi-user-review-workflow";
+  readonly packageId: string;
+  readonly status: ReviewWorkflowStatus;
+  readonly participantCount: number;
+  readonly activeParticipantCount: number;
+  readonly reviewerCount: number;
+  readonly requiredReviewerCount: number;
+  readonly approvedReviewerCount: number;
+  readonly changeRequestCount: number;
+  readonly threadCount: number;
+  readonly unresolvedThreadCount: number;
+  readonly assignedThreadCount: number;
+  readonly canPublish: boolean;
+  readonly participants: readonly ReviewParticipant[];
+  readonly threads: readonly ReviewThread[];
+  readonly decisions: readonly ReviewDecision[];
+  readonly evidence: {
+    readonly multiUserReview: boolean;
+    readonly assignmentWorkflow: boolean;
+    readonly reviewerQuorum: boolean;
+    readonly publishBlockedByOpenThreads: boolean;
+  };
+}
+
+export class MultiUserReviewWorkflow {
+  private packageId: string;
+  private status: ReviewWorkflowStatus;
+  private requiredReviewerCount: number;
+  private participants = new Map<string, ReviewParticipant>();
+  private threads = new Map<string, ReviewThread>();
+  private decisions = new Map<string, ReviewDecision>();
+
+  constructor(state: MultiUserReviewWorkflowState) {
+    this.packageId = nonEmpty(state.packageId, "Review package id");
+    this.status = state.status ?? "needs-review";
+    this.requiredReviewerCount = Math.max(1, Math.floor(state.requiredReviewerCount ?? 1));
+    for (const participant of state.participants) this.addParticipant(participant);
+    for (const thread of state.threads) this.addThread(thread);
+    for (const decision of state.decisions) this.recordDecision(decision);
+  }
+
+  addParticipant(participant: ReviewParticipant): MultiUserReviewWorkflowSnapshot {
+    const clean = sanitizeParticipant(participant);
+    this.participants.set(clean.id, clean);
+    return this.snapshot();
+  }
+
+  addThread(thread: ReviewThread): MultiUserReviewWorkflowSnapshot {
+    const clean = sanitizeThread(thread);
+    this.requireParticipant(clean.authorId);
+    if (clean.assignedTo) this.requireParticipant(clean.assignedTo);
+    this.threads.set(clean.id, clean);
+    if (!clean.resolved && this.status === "approved") this.status = "changes-requested";
+    return this.snapshot();
+  }
+
+  assignThread(threadId: string, participantId: string): MultiUserReviewWorkflowSnapshot {
+    this.requireParticipant(participantId);
+    const thread = this.requireThread(threadId);
+    this.threads.set(threadId, { ...thread, assignedTo: participantId });
+    return this.snapshot();
+  }
+
+  resolveThread(threadId: string): MultiUserReviewWorkflowSnapshot {
+    const thread = this.requireThread(threadId);
+    this.threads.set(threadId, { ...thread, resolved: true });
+    return this.snapshot();
+  }
+
+  recordDecision(decision: ReviewDecision): MultiUserReviewWorkflowSnapshot {
+    const clean = sanitizeDecision(decision);
+    const participant = this.requireParticipant(clean.reviewerId);
+    if (participant.role !== "reviewer" && participant.role !== "owner") {
+      throw new Error(`Review participant "${clean.reviewerId}" is not allowed to approve or request changes.`);
+    }
+    this.decisions.set(clean.reviewerId, clean);
+    if (clean.status === "changes-requested") this.status = "changes-requested";
+    else if (this.snapshot().canPublish) this.status = "approved";
+    return this.snapshot();
+  }
+
+  markNeedsReview(): MultiUserReviewWorkflowSnapshot {
+    this.status = "needs-review";
+    return this.snapshot();
+  }
+
+  serialize(): MultiUserReviewWorkflowState {
+    return {
+      packageId: this.packageId,
+      status: this.status,
+      requiredReviewerCount: this.requiredReviewerCount,
+      participants: [...this.participants.values()],
+      threads: [...this.threads.values()],
+      decisions: [...this.decisions.values()]
+    };
+  }
+
+  snapshot(): MultiUserReviewWorkflowSnapshot {
+    const participants = [...this.participants.values()];
+    const threads = [...this.threads.values()];
+    const decisions = [...this.decisions.values()];
+    const reviewerCount = participants.filter((participant) => participant.role === "owner" || participant.role === "reviewer").length;
+    const approvedReviewerCount = decisions.filter((decision) => decision.status === "approved").length;
+    const changeRequestCount = decisions.filter((decision) => decision.status === "changes-requested").length;
+    const unresolvedThreadCount = threads.filter((thread) => !thread.resolved).length;
+    const canPublish = approvedReviewerCount >= this.requiredReviewerCount && changeRequestCount === 0 && unresolvedThreadCount === 0;
+    const status: ReviewWorkflowStatus = canPublish ? "approved" : changeRequestCount > 0 ? "changes-requested" : this.status === "draft" ? "draft" : "needs-review";
+    return {
+      kind: "multi-user-review-workflow",
+      packageId: this.packageId,
+      status,
+      participantCount: participants.length,
+      activeParticipantCount: participants.filter((participant) => participant.active !== false).length,
+      reviewerCount,
+      requiredReviewerCount: this.requiredReviewerCount,
+      approvedReviewerCount,
+      changeRequestCount,
+      threadCount: threads.length,
+      unresolvedThreadCount,
+      assignedThreadCount: threads.filter((thread) => Boolean(thread.assignedTo)).length,
+      canPublish,
+      participants,
+      threads,
+      decisions,
+      evidence: {
+        multiUserReview: participants.length > 1,
+        assignmentWorkflow: threads.some((thread) => Boolean(thread.assignedTo)),
+        reviewerQuorum: approvedReviewerCount >= this.requiredReviewerCount,
+        publishBlockedByOpenThreads: unresolvedThreadCount > 0
+      }
+    };
+  }
+
+  private requireParticipant(id: string): ReviewParticipant {
+    const participant = this.participants.get(id);
+    if (!participant) throw new Error(`Unknown review participant: ${id}`);
+    return participant;
+  }
+
+  private requireThread(id: string): ReviewThread {
+    const thread = this.threads.get(id);
+    if (!thread) throw new Error(`Unknown review thread: ${id}`);
+    return thread;
+  }
+}
+
+export function createMultiUserReviewWorkflow(state: MultiUserReviewWorkflowState): MultiUserReviewWorkflow {
+  return new MultiUserReviewWorkflow(state);
+}
+
+function sanitizeParticipant(participant: ReviewParticipant): ReviewParticipant {
+  return {
+    id: nonEmpty(participant.id, "Review participant id"),
+    name: nonEmpty(participant.name, "Review participant name"),
+    role: participant.role,
+    active: participant.active
+  };
+}
+
+function sanitizeThread(thread: ReviewThread): ReviewThread {
+  if (thread.time !== undefined && (!Number.isFinite(thread.time) || thread.time < 0)) {
+    throw new Error("Review thread time must be a non-negative finite number.");
+  }
+  if (thread.frame !== undefined && (!Number.isInteger(thread.frame) || thread.frame < 0)) {
+    throw new Error("Review thread frame must be a non-negative integer.");
+  }
+  return {
+    id: nonEmpty(thread.id, "Review thread id"),
+    authorId: nonEmpty(thread.authorId, "Review thread author"),
+    text: nonEmpty(thread.text, "Review thread text"),
+    time: thread.time,
+    frame: thread.frame,
+    assignedTo: thread.assignedTo,
+    resolved: thread.resolved
+  };
+}
+
+function sanitizeDecision(decision: ReviewDecision): ReviewDecision {
+  return {
+    reviewerId: nonEmpty(decision.reviewerId, "Review decision reviewer"),
+    status: decision.status,
+    at: nonEmpty(decision.at, "Review decision timestamp"),
+    note: decision.note
+  };
+}
+
+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;
+}