@beyondwork/docx-react-component 1.0.0

package/services/react-word-editor/components/harness-editor-session-client.tsx

@@ -0,0 +1,1214 @@
+"use client";
+
+import Link from "next/link";
+import {
+  startTransition,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+  type ReactNode,
+} from "react";
+import { useRouter } from "next/navigation";
+
+import * as Select from "@radix-ui/react-select";
+import { ChevronDown, FileText } from "lucide-react";
+
+import { WordReviewEditor } from "../../../src/ui/WordReviewEditor";
+import type {
+  AutosaveState,
+  EditorError,
+  SelectionSnapshot,
+  EditorWarning,
+  WordReviewEditorEvent,
+  WordReviewEditorRef,
+} from "../../../src/api/public-types";
+import {
+  createHarnessEditorDatastore,
+  readHarnessEditorSessionState,
+} from "../lib/harness-editor-datastore";
+import { TwUnsavedModal } from "../../../src/ui-tailwind/chrome/tw-unsaved-modal";
+import { useBeforeUnload } from "../../../src/ui-tailwind/chrome/use-before-unload";
+import {
+  buildWorkspaceHref,
+  buildWorkspaceHomeHref,
+  type WorkspacePanel,
+  type WorkspaceRouteKind,
+} from "../lib/workspace-navigation";
+import { ReducedMotionToggle } from "./reduced-motion-toggle";
+
+type WorkspaceSourceOption = {
+  sourceId: string;
+  sourceKind: "fixture" | "scenario" | "upload";
+  sourceLabel: string;
+  available: boolean;
+  name: string;
+  releaseLabel: string;
+  releaseTone: "neutral" | "success" | "warning";
+  kindLabel: string;
+  primaryBadge?: string;
+  secondaryBadge?: string;
+  note?: string;
+};
+
+type HarnessEditorSessionClientProps = {
+  routeKind: WorkspaceRouteKind;
+  currentPanel: WorkspacePanel | null;
+  sessionId: string;
+  sourceId: string;
+  documentId: string;
+  sourceKind: "fixture" | "scenario" | "upload";
+  sourceLabel: string;
+  sources: WorkspaceSourceOption[];
+  initialExportId?: string;
+  initialValidation?: ValidationState;
+  sourceValidatorPolicy?: SourceValidatorPolicy;
+  sidePanel?: ReactNode;
+};
+
+type OperatorEvent = {
+  timestamp: string;
+  detail: string;
+};
+
+type ExportState = {
+  exportId: string;
+  fileName: string;
+};
+
+type ValidationState = {
+  exportId?: string;
+  runId?: string;
+  isValid: boolean;
+  packageFindingCount: number;
+  sdkFindingCount: number;
+};
+
+type SourceValidatorPolicy = {
+  mode: string;
+  sourcePackageFindingCount: number;
+  sourceSdkFindingCount: number;
+};
+
+type HarnessOperatorState = {
+  sessionId: string;
+  documentId: string;
+  sourceLabel: string;
+  sourceLoaded: boolean;
+  sourceError: string | null;
+  busyAction: string | null;
+  isDirty: boolean;
+  autosaveState: AutosaveState["status"];
+  lastSavedAt: string | null;
+  latestExport: ExportState | null;
+  latestValidation: ValidationState | null;
+  warningCount: number;
+  errorCount: number;
+  eventLog: OperatorEvent[];
+};
+
+type HarnessOperatorBridge = {
+  getState: () => HarnessOperatorState;
+  exportCurrentSession: () => Promise<ExportState | null>;
+  validateLatestExport: () => Promise<ValidationState | null>;
+  addHarnessComment: () => string | null;
+  acceptAllTrackedChanges: () => boolean;
+};
+
+declare global {
+  interface Window {
+    __DOCX_REACT_HARNESS__?: HarnessOperatorBridge;
+  }
+}
+
+const operatorUser = {
+  userId: "harness-operator",
+  displayName: "Harness Operator",
+  email: "harness@example.internal",
+};
+
+const focusRingClass =
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--color-canvas)]";
+
+function formatTimestamp(value: string): string {
+  return new Intl.DateTimeFormat("en-US", {
+    dateStyle: "medium",
+    timeStyle: "short",
+    timeZone: "UTC",
+  }).format(new Date(value));
+}
+
+function getValidationToneClass(isValid: boolean): string {
+  return isValid ? "bg-insert-soft text-insert" : "bg-warning-soft text-comment";
+}
+
+function getSourcePosture(sourceKind: HarnessEditorSessionClientProps["sourceKind"]): string {
+  if (sourceKind === "fixture") {
+    return "release-gate fixture";
+  }
+
+  if (sourceKind === "scenario") {
+    return "representative scenario";
+  }
+
+  return "operator upload";
+}
+
+function getPanelLabel(panel: WorkspacePanel | null): string {
+  if (panel === "library") {
+    return "Library";
+  }
+
+  if (panel === "dashboard") {
+    return "QA Dashboard";
+  }
+
+  if (panel === "certification") {
+    return "Certification";
+  }
+
+  if (panel === "wave10-review") {
+    return "Wave 10 Review";
+  }
+
+  if (panel === "run") {
+    return "Run Details";
+  }
+
+  if (panel === "bundle") {
+    return "Certification Bundle";
+  }
+
+  return "Panel";
+}
+
+function getReleaseToneClass(tone: WorkspaceSourceOption["releaseTone"]): string {
+  if (tone === "success") {
+    return "bg-insert-soft text-insert";
+  }
+
+  if (tone === "warning") {
+    return "bg-accent-soft text-accent";
+  }
+
+  return "bg-subtle text-secondary";
+}
+
+function getPanelLinkClass(active: boolean): string {
+  return active
+    ? "rounded-md bg-accent-soft px-2 py-1 text-xs font-medium text-accent"
+    : "rounded-md px-2 py-1 text-xs font-medium text-secondary transition-colors hover:bg-surface-hover hover:text-primary";
+}
+
+export function HarnessEditorSessionClient({
+  routeKind,
+  currentPanel,
+  sessionId,
+  sourceId,
+  documentId,
+  sourceKind,
+  sourceLabel,
+  sources,
+  initialExportId,
+  initialValidation,
+  sourceValidatorPolicy,
+  sidePanel,
+}: HarnessEditorSessionClientProps) {
+  const router = useRouter();
+  const editorRef = useRef<WordReviewEditorRef>(null);
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+  const datastore = useMemo(
+    () => createHarnessEditorDatastore(sessionId),
+    [sessionId],
+  );
+  const [editorReady, setEditorReady] = useState(false);
+  const [sourceError, setSourceError] = useState<string | null>(null);
+  const [busyAction, setBusyAction] = useState<string | null>(null);
+  const [latestExport, setLatestExport] = useState<ExportState | null>(
+    initialExportId
+      ? {
+          exportId: initialExportId,
+          fileName: `${documentId}.docx`,
+        }
+      : null,
+  );
+  const [latestValidation, setLatestValidation] = useState<ValidationState | null>(
+    initialValidation?.runId && initialValidation.exportId === initialExportId
+      ? initialValidation
+      : null,
+  );
+  const [storyLength, setStoryLength] = useState(0);
+  const [latestSelection, setLatestSelection] = useState<SelectionSnapshot | null>(null);
+  const [warnings, setWarnings] = useState<EditorWarning[]>([]);
+  const [errors, setErrors] = useState<EditorError[]>([]);
+  const [eventLog, setEventLog] = useState<OperatorEvent[]>([]);
+  const [isDirty, setIsDirty] = useState(false);
+  const [pendingAction, setPendingAction] = useState<(() => void) | null>(null);
+  const [autosaveState, setAutosaveState] = useState<AutosaveState>({
+    status: "idle",
+  });
+
+  // Warn on browser tab close when dirty
+  useBeforeUnload(isDirty);
+  const [lastSavedAt, setLastSavedAt] = useState<string | null>(null);
+  const initialValidationRunId = initialValidation?.runId;
+  const initialValidationIsValid = initialValidation?.isValid;
+  const initialValidationPackageFindingCount =
+    initialValidation?.packageFindingCount;
+  const initialValidationSdkFindingCount = initialValidation?.sdkFindingCount;
+
+  const appendEvent = useCallback((detail: string): void => {
+    setEventLog((current) =>
+      [{ timestamp: new Date().toISOString(), detail }, ...current].slice(0, 12),
+    );
+  }, []);
+
+  useEffect(() => {
+    setEditorReady(false);
+    setSourceError(null);
+    setBusyAction(null);
+    setLatestExport(
+      initialExportId
+        ? {
+            exportId: initialExportId,
+            fileName: `${documentId}.docx`,
+          }
+        : null,
+    );
+    setLatestValidation(
+      initialValidation?.runId && initialValidation.exportId === initialExportId
+        ? initialValidation
+        : null,
+    );
+    setStoryLength(0);
+    setLatestSelection(null);
+    setWarnings([]);
+    setErrors([]);
+    setEventLog([]);
+    setIsDirty(false);
+    setAutosaveState({ status: "idle" });
+    setLastSavedAt(null);
+  }, [
+    documentId,
+    initialExportId,
+    initialValidationIsValid,
+    initialValidationPackageFindingCount,
+    initialValidationRunId,
+    initialValidationSdkFindingCount,
+    sessionId,
+  ]);
+  const validationDelta = getValidationDelta(latestValidation, sourceValidatorPolicy);
+  const certificationTargetHref = latestValidation?.runId
+    ? buildWorkspaceHref({
+        routeKind,
+        sessionId,
+        panel: "certification",
+        targetType: "validation-run",
+        targetId: latestValidation.runId,
+      })
+    : null;
+  const homeHref = buildWorkspaceHomeHref(routeKind, sessionId);
+  const currentSource = sources.find((source) => source.sourceId === sourceId);
+
+  const buildPanelHref = useCallback(
+    (panel: WorkspacePanel, extras: { runId?: string; targetType?: string; targetId?: string } = {}) =>
+      buildWorkspaceHref({
+        routeKind,
+        sessionId,
+        panel,
+        ...extras,
+      }),
+    [routeKind, sessionId],
+  );
+
+  const refreshSessionState = useCallback(async (): Promise<{
+    latestExport: ExportState | null;
+    latestValidation: ValidationState | null;
+  }> => {
+    const state = await readHarnessEditorSessionState(sessionId);
+    const nextExport = state.latestExport
+      ? {
+          exportId: state.latestExport.exportId,
+          fileName: state.latestExport.fileName,
+        }
+      : null;
+    const nextValidation =
+      nextExport &&
+      state.latestValidation &&
+      state.latestValidation.exportId === nextExport.exportId
+        ? {
+            exportId: state.latestValidation.exportId,
+            isValid: state.latestValidation.summary.isValid,
+            packageFindingCount: state.latestValidation.summary.packageFindingCount,
+            runId: state.latestValidation.runId,
+            sdkFindingCount: state.latestValidation.summary.sdkFindingCount,
+          }
+        : null;
+
+    setLatestExport(nextExport);
+    setLatestValidation(nextValidation);
+
+    return {
+      latestExport: nextExport,
+      latestValidation: nextValidation,
+    };
+  }, [sessionId]);
+
+  const exportCurrentSession = useCallback(async (): Promise<ExportState | null> => {
+    if (!editorRef.current) {
+      appendEvent("Export failed: editor runtime is not ready.");
+      return null;
+    }
+
+    setBusyAction("Exporting current session");
+
+    try {
+      await editorRef.current.exportDocx({
+        fileName: `${documentId}.docx`,
+        reason: "harness-manual-export",
+      });
+      const nextState = await refreshSessionState();
+      const nextExport = nextState.latestExport;
+      if (nextExport) {
+        appendEvent(`Stored export ${nextExport.exportId}.`);
+      } else {
+        appendEvent("Editor export completed but no durable export record was found.");
+      }
+      return nextExport;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Export failed.";
+      appendEvent(message);
+      throw error;
+    } finally {
+      setBusyAction(null);
+    }
+  }, [appendEvent, documentId, refreshSessionState]);
+
+  const validateLatestExport = useCallback(async (): Promise<ValidationState | null> => {
+    if (!latestExport) {
+      appendEvent("Export a package before requesting validation.");
+      return null;
+    }
+
+    setBusyAction("Validating latest export");
+
+    try {
+      const response = await fetch("/api/validate", {
+        body: JSON.stringify({
+          exportId: latestExport.exportId,
+          sessionId,
+        }),
+        headers: {
+          "content-type": "application/json",
+        },
+        method: "POST",
+      });
+
+      if (!response.ok) {
+        throw new Error(await response.text());
+      }
+
+      const payload = (await response.json()) as {
+        run: {
+          runId: string;
+          summary: {
+            isValid: boolean;
+            packageFindingCount: number;
+            sdkFindingCount: number;
+          };
+        };
+      };
+
+      const nextValidation = {
+        exportId: latestExport.exportId,
+        isValid: payload.run.summary.isValid,
+        packageFindingCount: payload.run.summary.packageFindingCount,
+        runId: payload.run.runId,
+        sdkFindingCount: payload.run.summary.sdkFindingCount,
+      };
+      setLatestValidation(nextValidation);
+      appendEvent(`Stored validation run ${payload.run.runId}.`);
+      if (sourceValidatorPolicy) {
+        const nextDelta = getValidationDelta(nextValidation, sourceValidatorPolicy);
+        if (nextDelta && nextDelta.totalDelta > 0) {
+          appendEvent(
+            `Validation worsened the source baseline by ${nextDelta.totalDelta} finding${nextDelta.totalDelta === 1 ? "" : "s"}.`,
+          );
+        } else if (nextDelta && nextDelta.totalDelta < 0) {
+          appendEvent(
+            `Validation improved the source baseline by ${Math.abs(nextDelta.totalDelta)} finding${Math.abs(nextDelta.totalDelta) === 1 ? "" : "s"}.`,
+          );
+        } else {
+          appendEvent("Validation matched the recorded source baseline.");
+        }
+      }
+      return nextValidation;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Validation failed.";
+      appendEvent(message);
+      throw error;
+    } finally {
+      setBusyAction(null);
+    }
+  }, [appendEvent, latestExport, sessionId, sourceValidatorPolicy]);
+
+  function resolveCommentAnchor() {
+    if (latestSelection?.activeRange.kind === "range") {
+      const { from, to, assoc } = latestSelection.activeRange;
+      if (from !== to) {
+        return latestSelection.activeRange;
+      }
+
+      if (storyLength > 0) {
+        const normalizedStart = Math.min(from, Math.max(storyLength - 1, 0));
+        const normalizedEnd = Math.min(normalizedStart + 1, storyLength);
+        return {
+          kind: "range" as const,
+          from: normalizedStart,
+          to: normalizedEnd,
+          assoc,
+        };
+      }
+    }
+
+    if (storyLength > 0) {
+      return {
+        kind: "range" as const,
+        from: 0,
+        to: Math.min(1, storyLength),
+        assoc: {
+          start: -1 as const,
+          end: 1 as const,
+        },
+      };
+    }
+
+    return null;
+  }
+
+  const addHarnessComment = useCallback((): string | null => {
+    if (!editorRef.current) {
+      appendEvent("Comment action skipped because the editor runtime is not ready.");
+      return null;
+    }
+
+    const anchor = resolveCommentAnchor();
+    if (!anchor) {
+      appendEvent("Comment action skipped because no serializable anchor is available yet.");
+      return null;
+    }
+
+    const commentId = editorRef.current.addComment({
+      authorId: operatorUser.userId,
+      body: "Harness operator comment",
+      anchor,
+    });
+
+    appendEvent(`Added comment ${commentId}.`);
+    return commentId;
+  }, [appendEvent, latestSelection, storyLength]);
+
+  const acceptAllTrackedChanges = useCallback((): boolean => {
+    if (!editorRef.current) {
+      appendEvent("Accept-all skipped because the editor runtime is not ready.");
+      return false;
+    }
+
+    editorRef.current.acceptAllChanges();
+    appendEvent("Accepted all actionable tracked changes in the current session.");
+    return true;
+  }, [appendEvent]);
+
+  const upsertWarning = useCallback((warning: EditorWarning) => {
+    setWarnings((current) => {
+      const next = current.filter((entry) => entry.warningId !== warning.warningId);
+      return [warning, ...next].slice(0, 10);
+    });
+  }, []);
+
+  const upsertError = useCallback((error: EditorError) => {
+    setErrors((current) => {
+      const next = current.filter((entry) => entry.errorId !== error.errorId);
+      return [error, ...next].slice(0, 6);
+    });
+  }, []);
+
+  const handleEvent = useCallback(
+    (event: WordReviewEditorEvent): void => {
+      switch (event.type) {
+        case "export_completed": {
+          void refreshSessionState().catch(() => undefined);
+          appendEvent(`Editor exported ${event.result.fileName}.`);
+          return;
+        }
+        case "ready": {
+          setEditorReady(true);
+          setSourceError(null);
+          setStoryLength(event.stats.storyLength);
+          setIsDirty(false);
+          appendEvent(
+            `Editor ready with ${event.stats.commentCount} comments and ${event.stats.revisionCount} revisions.`,
+          );
+          return;
+        }
+        case "dirty_changed": {
+          setIsDirty(event.isDirty);
+          if (event.isDirty && autosaveState.status === "saved") {
+            setAutosaveState({ status: "idle" });
+          }
+          return;
+        }
+        case "selection_changed": {
+          setLatestSelection(event.selection);
+          return;
+        }
+        case "autosave_state": {
+          setAutosaveState(event.state);
+          if (event.state.status === "saved") {
+            setLastSavedAt(event.state.savedAt);
+          }
+          if (event.state.status === "error") {
+            upsertError(event.state.error);
+            appendEvent(`Autosave failed: ${event.state.error.code}.`);
+          }
+          return;
+        }
+        case "snapshot_saved": {
+          setLastSavedAt(event.snapshot.savedAt || null);
+          appendEvent(
+            `${event.isAutosave ? "Autosaved" : "Saved"} snapshot checkpoint.`,
+          );
+          return;
+        }
+        case "comment_added": {
+          appendEvent(`Added comment ${event.commentId}.`);
+          return;
+        }
+        case "comment_resolved": {
+          appendEvent(`Resolved comment ${event.commentId}.`);
+          return;
+        }
+        case "change_accepted": {
+          appendEvent(`Accepted change ${event.changeId}.`);
+          return;
+        }
+        case "change_rejected": {
+          appendEvent(`Rejected change ${event.changeId}.`);
+          return;
+        }
+        case "warning_added": {
+          upsertWarning(event.warning);
+          appendEvent(`Editor warning: ${event.warning.code}`);
+          return;
+        }
+        case "warning_cleared": {
+          setWarnings((current) =>
+            current.filter((warning) => warning.warningId !== event.warningId),
+          );
+          appendEvent(`Cleared warning ${event.code}.`);
+          return;
+        }
+        case "error": {
+          upsertError(event.error);
+          appendEvent(`Editor error: ${event.error.code}`);
+          return;
+        }
+      }
+    },
+    [appendEvent, autosaveState.status, refreshSessionState, upsertError, upsertWarning],
+  );
+
+  const handleError = useCallback(
+    (error: EditorError) => {
+      upsertError(error);
+      appendEvent(`Editor error: ${error.code}`);
+      if (error.isFatal) {
+        setSourceError(error.message);
+      }
+    },
+    [appendEvent, upsertError],
+  );
+
+  const handleWarning = useCallback(
+    (warning: EditorWarning) => {
+      upsertWarning(warning);
+      appendEvent(`Editor warning: ${warning.code}`);
+    },
+    [appendEvent, upsertWarning],
+  );
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    window.__DOCX_REACT_HARNESS__ = {
+      getState: () => ({
+        sessionId,
+        documentId,
+        sourceLabel,
+        sourceLoaded: editorReady,
+        sourceError,
+        busyAction,
+        isDirty,
+        autosaveState: autosaveState.status,
+        lastSavedAt,
+        latestExport,
+        latestValidation,
+        warningCount: warnings.length,
+        errorCount: errors.length,
+        eventLog,
+      }),
+      exportCurrentSession,
+      validateLatestExport,
+      addHarnessComment,
+      acceptAllTrackedChanges,
+    };
+
+    return () => {
+      delete window.__DOCX_REACT_HARNESS__;
+    };
+  }, [
+    acceptAllTrackedChanges,
+    addHarnessComment,
+    autosaveState.status,
+    busyAction,
+    documentId,
+    editorReady,
+    errors.length,
+    eventLog,
+    exportCurrentSession,
+    isDirty,
+    lastSavedAt,
+    latestExport,
+    latestValidation,
+    sessionId,
+    sourceError,
+    sourceLabel,
+    validateLatestExport,
+    warnings.length,
+  ]);
+
+  const navigateToSession = useCallback(
+    async (nextSourceId: string, nextLabel: string) => {
+      if (busyAction) {
+        return;
+      }
+
+      if (isDirty) {
+        // Show modal — store a closure that performs the navigation after discard
+        setPendingAction(() => async () => {
+          setIsDirty(false); // Clear dirty to prevent re-prompt
+          setBusyAction(`Opening ${nextLabel}`);
+          try {
+            const response = await fetch("/api/demo-sessions", {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ sourceId: nextSourceId }),
+            });
+            if (!response.ok) return;
+            const data = await response.json();
+            startTransition(() => {
+              router.push(buildWorkspaceHref(data.session.sessionId));
+            });
+          } finally {
+            setBusyAction(null);
+          }
+        });
+        return;
+      }
+
+      setBusyAction(`Opening ${nextLabel}`);
+
+      try {
+        const response = await fetch("/api/demo-sessions", {
+          body: JSON.stringify({ sourceId: nextSourceId }),
+          headers: {
+            "content-type": "application/json",
+          },
+          method: "POST",
+        });
+
+        if (!response.ok) {
+          throw new Error(await response.text());
+        }
+
+        const payload = (await response.json()) as {
+          session: {
+            sessionId: string;
+          };
+        };
+
+        startTransition(() => {
+          router.push(
+            buildWorkspaceHomeHref(routeKind, payload.session.sessionId),
+          );
+        });
+      } catch (error) {
+        setBusyAction(null);
+        setSourceError(
+          error instanceof Error ? error.message : "Could not open the selected source.",
+        );
+      }
+    },
+    [busyAction, isDirty, routeKind, router],
+  );
+
+  const handleUpload = useCallback(
+    async (file: File | null) => {
+      if (!file || busyAction) {
+        return;
+      }
+
+      if (isDirty) {
+        setPendingAction(() => async () => {
+          setIsDirty(false);
+          setBusyAction(`Uploading ${file.name}`);
+          try {
+            const formData = new FormData();
+            formData.set("file", file);
+            const response = await fetch("/api/demo-sessions", { body: formData, method: "POST" });
+            if (!response.ok) return;
+            const data = await response.json();
+            startTransition(() => {
+              router.push(buildWorkspaceHomeHref(routeKind, data.session.sessionId));
+            });
+          } finally {
+            setBusyAction(null);
+          }
+        });
+        return;
+      }
+
+      setBusyAction(`Uploading ${file.name}`);
+
+      try {
+        const formData = new FormData();
+        formData.set("file", file);
+
+        const response = await fetch("/api/demo-sessions", {
+          body: formData,
+          method: "POST",
+        });
+
+        if (!response.ok) {
+          throw new Error(await response.text());
+        }
+
+        const payload = (await response.json()) as {
+          session: {
+            sessionId: string;
+          };
+        };
+
+        startTransition(() => {
+          router.push(
+            buildWorkspaceHomeHref(routeKind, payload.session.sessionId),
+          );
+        });
+      } catch (error) {
+        setBusyAction(null);
+        setSourceError(
+          error instanceof Error ? error.message : "Could not upload and open the document.",
+        );
+      } finally {
+        if (fileInputRef.current) {
+          fileInputRef.current.value = "";
+        }
+      }
+    },
+    [busyAction, isDirty, routeKind, router],
+  );
+
+  const utilityPanelContent =
+    currentPanel === "library" ? (
+      <LibraryPanel
+        busyAction={busyAction}
+        currentSourceId={sourceId}
+        onOpenSource={navigateToSession}
+        sources={sources}
+      />
+    ) : (
+      sidePanel
+    );
+  const workspaceStatusLabel = getWorkspaceStatusLabel({
+    autosaveState,
+    busyAction,
+    editorReady,
+    isDirty,
+    lastSavedAt,
+  });
+
+  return (
+    <section className="flex h-[100dvh] flex-col bg-canvas text-primary">
+      <div className="flex min-h-11 shrink-0 flex-wrap items-center gap-2 border-b border-border bg-surface px-3 py-2 text-xs">
+        <Link
+          className={`font-medium text-tertiary transition-colors hover:text-primary ${focusRingClass}`}
+          href={homeHref}
+        >
+          Review Workspace
+        </Link>
+
+        <Select.Root
+          onValueChange={(nextSourceId) => {
+            if (nextSourceId !== sourceId) {
+              const nextSource = sources.find((source) => source.sourceId === nextSourceId);
+              void navigateToSession(nextSourceId, nextSource?.sourceLabel || "document");
+            }
+          }}
+          value={sourceId}
+        >
+          <Select.Trigger
+            className={`inline-flex items-center gap-1 rounded-md px-2 py-1 text-xs text-secondary transition-colors hover:bg-surface-hover outline-none ${focusRingClass}`}
+          >
+            <Select.Value />
+            <Select.Icon>
+              <ChevronDown className="h-3 w-3" />
+            </Select.Icon>
+          </Select.Trigger>
+          <Select.Portal>
+            <Select.Content
+              className="z-50 overflow-hidden rounded-lg bg-canvas shadow-lg ring-1 ring-border"
+              position="popper"
+              sideOffset={4}
+            >
+              <Select.Viewport className="p-1">
+                {sources.map((source) => (
+                  <Select.Item
+                    className={`flex cursor-pointer items-center gap-2 rounded-md px-2 py-1.5 text-xs text-primary outline-none data-[disabled]:cursor-not-allowed data-[disabled]:opacity-40 data-[highlighted]:bg-surface ${focusRingClass}`}
+                    disabled={!source.available}
+                    key={source.sourceId}
+                    value={source.sourceId}
+                  >
+                    <Select.ItemText>{source.sourceLabel}</Select.ItemText>
+                    <span
+                      className={`shrink-0 rounded px-1 py-px text-[10px] font-medium ${getReleaseToneClass(
+                        source.releaseTone,
+                      )}`}
+                    >
+                      {source.sourceKind}
+                    </span>
+                  </Select.Item>
+                ))}
+              </Select.Viewport>
+            </Select.Content>
+          </Select.Portal>
+        </Select.Root>
+
+        <span
+          className={`rounded px-1 py-px text-[10px] font-medium ${getReleaseToneClass(
+            currentSource?.releaseTone || "neutral",
+          )}`}
+        >
+          {sourceKind}
+        </span>
+
+        <div className="h-3 w-px bg-border" />
+
+        <label
+          className={`flex cursor-pointer items-center gap-1.5 text-tertiary ${focusRingClass}`}
+        >
+          <FileText className="h-3 w-3" />
+          <span>Upload .docx</span>
+          <input
+            accept=".docx"
+            className="sr-only"
+            onChange={(event) => {
+              void handleUpload(event.target.files?.[0] || null);
+            }}
+            ref={fileInputRef}
+            type="file"
+          />
+        </label>
+
+        <div className="h-3 w-px bg-border" />
+
+        <Link className={getPanelLinkClass(currentPanel === "library")} href={buildPanelHref("library")}>
+          Library
+        </Link>
+        <Link className={getPanelLinkClass(currentPanel === "dashboard")} href={buildPanelHref("dashboard")}>
+          Dashboard
+        </Link>
+        <Link
+          className={getPanelLinkClass(currentPanel === "certification")}
+          href={buildPanelHref("certification")}
+        >
+          Certification
+        </Link>
+        <Link
+          className={getPanelLinkClass(currentPanel === "wave10-review")}
+          href={buildPanelHref("wave10-review")}
+        >
+          Wave 10
+        </Link>
+        {latestValidation?.runId ? (
+          <Link
+            className={getPanelLinkClass(currentPanel === "run")}
+            href={buildPanelHref("run", { runId: latestValidation.runId })}
+          >
+            Current Run
+          </Link>
+        ) : null}
+        <button
+          className={`inline-flex h-7 items-center gap-1.5 rounded-md px-2.5 text-xs font-medium text-secondary transition-colors hover:bg-surface-hover hover:text-primary disabled:cursor-not-allowed disabled:opacity-30 ${focusRingClass}`}
+          data-testid="harness-validate-button"
+          disabled={!latestExport || Boolean(busyAction)}
+          onClick={() => {
+            void validateLatestExport().catch(() => undefined);
+          }}
+          type="button"
+        >
+          Validate
+        </button>
+        {latestExport ? (
+          <a
+            className={`inline-flex h-7 items-center rounded-md bg-subtle px-2.5 text-xs font-medium text-secondary transition-colors hover:bg-surface ${focusRingClass}`}
+            href={`/api/exports/${latestExport.exportId}`}
+          >
+            Export {latestExport.exportId.slice(0, 8)}
+          </a>
+        ) : (
+          <span className="inline-flex h-7 items-center rounded-md border border-dashed border-border px-2.5 text-xs text-tertiary">
+            Export pending
+          </span>
+        )}
+        {latestValidation?.runId ? (
+          <Link
+            className={`inline-flex h-7 items-center rounded-md px-2.5 text-xs font-medium ${getValidationToneClass(
+              latestValidation.isValid,
+            )} ${focusRingClass}`}
+            href={buildPanelHref("run", { runId: latestValidation.runId })}
+          >
+            {latestValidation.isValid ? "Clean" : "Findings"} {latestValidation.runId.slice(0, 8)}
+          </Link>
+        ) : (
+          <span className="inline-flex h-7 items-center rounded-md border border-dashed border-border px-2.5 text-xs text-tertiary">
+            Validation pending
+          </span>
+        )}
+        {certificationTargetHref ? (
+          <Link
+            className={`inline-flex h-7 items-center rounded-md bg-subtle px-2.5 text-xs font-medium text-secondary transition-colors hover:bg-surface ${focusRingClass}`}
+            href={certificationTargetHref}
+          >
+            Certification target
+          </Link>
+        ) : null}
+        {validationDelta ? (
+          <span className="truncate text-tertiary/70">{validationDelta.message}</span>
+        ) : null}
+        <span className="flex-1" />
+        <span className="max-w-[18rem] truncate text-tertiary/50">
+          {getSourcePosture(sourceKind)} · {sourceLabel}
+        </span>
+        <ReducedMotionToggle />
+        <span className="font-mono text-[11px] text-tertiary/70">{sessionId}</span>
+        <span className="text-tertiary">{workspaceStatusLabel}</span>
+      </div>
+
+      <div className="flex flex-1 min-h-0">
+        <div className="flex min-w-0 flex-1 flex-col bg-surface">
+          {sourceError ? (
+            <div className="flex items-center gap-2 bg-danger-soft px-3 py-1.5 text-xs text-danger">
+              {sourceError}
+            </div>
+          ) : null}
+
+          <div className="min-h-0 flex-1">
+            <WordReviewEditor
+              ref={editorRef}
+              autosave={{
+                enabled: true,
+                debounceMs: 800,
+              }}
+              currentUser={operatorUser}
+              datastore={datastore}
+              documentId={documentId}
+              onError={handleError}
+              onEvent={handleEvent}
+              onWarning={handleWarning}
+              reviewMode="review"
+              markupDisplay="simple"
+            />
+          </div>
+        </div>
+
+        {currentPanel ? (
+          <aside className="flex w-[360px] shrink-0 flex-col border-l border-border bg-canvas">
+            <div className="flex h-10 items-center justify-between border-b border-border px-3">
+              <div>
+                <p className="text-[10px] font-medium uppercase tracking-[0.14em] text-tertiary">
+                  Utilities
+                </p>
+                <p className="text-sm font-medium text-primary">{getPanelLabel(currentPanel)}</p>
+              </div>
+              <Link
+                className={`rounded-md px-2 py-1 text-xs text-secondary transition-colors hover:bg-surface hover:text-primary ${focusRingClass}`}
+                href={homeHref}
+              >
+                Close
+              </Link>
+            </div>
+
+            <div className="min-h-0 flex-1 overflow-y-auto">
+              {utilityPanelContent}
+            </div>
+          </aside>
+        ) : null}
+      </div>
+      {/* Unsaved changes modal */}
+      <TwUnsavedModal
+        open={pendingAction !== null}
+        onCancel={() => setPendingAction(null)}
+        onDiscard={() => {
+          const action = pendingAction;
+          setPendingAction(null);
+          action?.();
+        }}
+      />
+    </section>
+  );
+}
+
+function LibraryPanel(props: {
+  sources: WorkspaceSourceOption[];
+  currentSourceId: string;
+  busyAction: string | null;
+  onOpenSource: (sourceId: string, sourceLabel: string) => Promise<void>;
+}) {
+  return (
+    <div className="space-y-3 p-3">
+      <p className="text-xs leading-5 text-tertiary">
+        Open a runtime-backed fixture, scenario, or upload without leaving the editor shell.
+      </p>
+      <div className="space-y-1">
+        {props.sources.map((source) => {
+          const active = source.sourceId === props.currentSourceId;
+
+          return (
+            <article
+              className={`rounded-lg p-2.5 transition-colors ${
+                active ? "bg-accent-soft" : "hover:bg-surface"
+              }`}
+              key={source.sourceId}
+            >
+              <div className="flex items-start justify-between gap-3">
+                <div className="min-w-0 flex-1">
+                  <div className="flex flex-wrap items-center gap-2">
+                    {source.primaryBadge ? (
+                      <span className="inline-flex items-center rounded bg-subtle px-1.5 py-0.5 text-[10px] font-medium text-primary">
+                        {source.primaryBadge}
+                      </span>
+                    ) : null}
+                    <span
+                      className={`inline-flex items-center rounded px-1.5 py-0.5 text-[10px] font-medium ${getReleaseToneClass(
+                        source.releaseTone,
+                      )}`}
+                    >
+                      {source.releaseLabel}
+                    </span>
+                    <span className="inline-flex items-center rounded bg-subtle px-1.5 py-0.5 text-[10px] font-medium text-secondary">
+                      {source.kindLabel}
+                    </span>
+                  </div>
+                  <p className="mt-2 text-sm font-medium text-primary">{source.sourceLabel}</p>
+                  <p className="mt-1 text-xs leading-5 text-secondary">
+                    {source.note || "No source note recorded."}
+                  </p>
+                  {source.secondaryBadge ? (
+                    <p className="mt-1 text-xs text-tertiary">{source.secondaryBadge}</p>
+                  ) : null}
+                </div>
+                {active ? (
+                  <span className="rounded-md bg-accent-soft px-2 py-1 text-xs font-medium text-accent">
+                    Active
+                  </span>
+                ) : (
+                  <button
+                    className={`rounded-md px-2 py-1 text-xs font-medium text-secondary transition-colors hover:bg-surface-hover hover:text-primary disabled:cursor-not-allowed disabled:opacity-40 ${focusRingClass}`}
+                    disabled={!source.available || Boolean(props.busyAction)}
+                    onClick={() => {
+                      void props.onOpenSource(source.sourceId, source.sourceLabel);
+                    }}
+                    type="button"
+                  >
+                    {source.available ? "Open" : "Missing"}
+                  </button>
+                )}
+              </div>
+            </article>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+function getWorkspaceStatusLabel(input: {
+  busyAction: string | null;
+  editorReady: boolean;
+  isDirty: boolean;
+  autosaveState: AutosaveState;
+  lastSavedAt: string | null;
+}): string {
+  if (input.busyAction) {
+    return input.busyAction;
+  }
+
+  if (input.autosaveState.status === "saving") {
+    return "Saving";
+  }
+
+  if (input.autosaveState.status === "error") {
+    return "Save error";
+  }
+
+  if (input.isDirty) {
+    return "Unsaved";
+  }
+
+  if (input.lastSavedAt) {
+    return `Saved ${formatTimestamp(input.lastSavedAt)}`;
+  }
+
+  return input.editorReady ? "Ready" : "Loading";
+}
+
+function getValidationDelta(
+  validation: ValidationState | null,
+  sourceValidatorPolicy: SourceValidatorPolicy | undefined,
+): {
+  message: string;
+  totalDelta: number;
+} | null {
+  if (!validation || !sourceValidatorPolicy) {
+    return null;
+  }
+
+  const sourceTotal =
+    sourceValidatorPolicy.sourcePackageFindingCount + sourceValidatorPolicy.sourceSdkFindingCount;
+  const validationTotal =
+    validation.packageFindingCount + validation.sdkFindingCount;
+  const totalDelta = validationTotal - sourceTotal;
+
+  if (totalDelta === 0) {
+    return {
+      message: "Validation matched the recorded source baseline.",
+      totalDelta,
+    };
+  }
+
+  if (totalDelta > 0) {
+    return {
+      message: `Validation introduced ${totalDelta} more finding${totalDelta === 1 ? "" : "s"} than the recorded source baseline.`,
+      totalDelta,
+    };
+  }
+
+  return {
+    message: `Validation removed ${Math.abs(totalDelta)} finding${Math.abs(totalDelta) === 1 ? "" : "s"} relative to the recorded source baseline.`,
+    totalDelta,
+  };
+}