@aura3d/editor-runtime 1.0.6 → 1.1.0

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

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