Chore: Enhance spreadsheet state management with debouncing and schema validation (#177)

Author: vprashrex

app/components/assessment/SpreadsheetModalInner.tsx

@@ -11,8 +11,12 @@ import {
   loadSpreadsheetState,
   persistSpreadsheetState,
 } from "@/app/lib/assessment/results";
+import { SPREADSHEET_STATE_DEBOUNCE_MS } from "@/app/lib/assessment/constants";
 import type { UniverAPI } from "@/app/lib/types/assessment";
 
+// Univer command types: 0=COMMAND, 1=OPERATION, 2=MUTATION. Only mutations change state.
+const UNIVER_MUTATION_TYPE = 2;
+
 interface SpreadsheetModalInnerProps {
   runId: number;
   title: string;
@@ -50,20 +54,42 @@ export default function SpreadsheetModalInner({
     api.createUniverSheet(saved ?? buildSpreadsheetWorkbookData(headers, rows));
 
     let debounceTimer: ReturnType<typeof setTimeout> | null = null;
-    const cmdDisposable = api.onCommandExecuted(() => {
+    let lastSerialized: string | null = null;
+
+    const flushNow = () => {
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      try {
+        const snapshot = api.getActiveWorkbook()?.save();
+        if (!snapshot) return;
+        const serialized = JSON.stringify(snapshot);
+        if (serialized === lastSerialized) return; // dedup unchanged saves
+        lastSerialized = serialized;
+        persistSpreadsheetState(runId, snapshot);
+      } catch {
+        // serialization failed or storage unavailable — keep in-memory state
+      }
+    };
+
+    const cmdDisposable = api.onCommandExecuted((info) => {
+      // Skip non-mutating commands (selection, scroll, focus, etc.)
+      if (info.type !== UNIVER_MUTATION_TYPE) return;
       if (debounceTimer) clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(() => {
-        try {
-          const snapshot = api.getActiveWorkbook()?.save();
-          if (snapshot) persistSpreadsheetState(runId, snapshot);
-        } catch {
-          // silently skip — storage quota exceeded or unavailable
-        }
-      }, 1500);
+      debounceTimer = setTimeout(flushNow, SPREADSHEET_STATE_DEBOUNCE_MS);
     });
 
+    const handleVisibility = () => {
+      if (document.visibilityState === "hidden") flushNow();
+    };
+    window.addEventListener("beforeunload", flushNow);
+    document.addEventListener("visibilitychange", handleVisibility);
+
     return () => {
-      if (debounceTimer) clearTimeout(debounceTimer);
+      window.removeEventListener("beforeunload", flushNow);
+      document.removeEventListener("visibilitychange", handleVisibility);
+      flushNow(); // flush pending edits on unmount
       cmdDisposable.dispose();
       api.dispose?.();
       univerRef.current = null;

app/lib/assessment/constants.ts

@@ -15,6 +15,8 @@ export const ASSESSMENT_CONFIG_VERSION_PAGE_SIZE = 8;
 
 export const RESULTS_POLL_INTERVAL_MS = 60_000;
 export const SPREADSHEET_STATE_STORAGE_PREFIX = "kaapi_sheet_state_";
+export const SPREADSHEET_STATE_SCHEMA_VERSION = 1;
+export const SPREADSHEET_STATE_DEBOUNCE_MS = 800;
 export const SPREADSHEET_PREVIEW_ROW_LIMIT = 5000;
 
 export const MAX_DATASET_FILE_BYTES = 5 * 1024 * 1024;

app/lib/assessment/results.ts

@@ -3,12 +3,14 @@ import type {
   AssessmentRun,
   ResultTone,
   ResultsCounts,
+  SpreadsheetStateEnvelope,
   StatusFilter,
 } from "@/app/lib/types/assessment";
 import {
   ACTIVE_ASSESSMENT_STATUSES,
   COMPLETED_ASSESSMENT_STATUSES,
   FAILED_ASSESSMENT_STATUSES,
+  SPREADSHEET_STATE_SCHEMA_VERSION,
   SPREADSHEET_STATE_STORAGE_PREFIX,
 } from "@/app/lib/assessment/constants";
 
@@ -77,14 +79,66 @@ export function spreadsheetStorageKey(runId: number): string {
 export function loadSpreadsheetState(runId: number): object | null {
   try {
     const raw = localStorage.getItem(spreadsheetStorageKey(runId));
-    return raw ? (JSON.parse(raw) as object) : null;
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<SpreadsheetStateEnvelope>;
+    if (parsed?.v !== SPREADSHEET_STATE_SCHEMA_VERSION || !parsed.data) {
+      localStorage.removeItem(spreadsheetStorageKey(runId));
+      return null;
+    }
+    return parsed.data;
   } catch {
     return null;
   }
 }
 
+// Evict oldest spreadsheet-state entries until below `keep` count.
+function evictOldestSpreadsheetStates(keep: number): void {
+  const entries: Array<{ key: string; ts: number }> = [];
+  for (let i = 0; i < localStorage.length; i++) {
+    const key = localStorage.key(i);
+    if (!key?.startsWith(SPREADSHEET_STATE_STORAGE_PREFIX)) continue;
+    try {
+      const raw = localStorage.getItem(key);
+      if (!raw) continue;
+      const parsed = JSON.parse(raw) as Partial<SpreadsheetStateEnvelope>;
+      entries.push({ key, ts: parsed?.ts ?? 0 });
+    } catch {
+      // malformed — treat as oldest so it gets dropped first
+      entries.push({ key, ts: 0 });
+    }
+  }
+  entries.sort((a, b) => a.ts - b.ts);
+  const toDrop = Math.max(0, entries.length - keep);
+  for (let i = 0; i < toDrop; i++) {
+    localStorage.removeItem(entries[i].key);
+  }
+}
+
 export function persistSpreadsheetState(runId: number, data: object): void {
-  localStorage.setItem(spreadsheetStorageKey(runId), JSON.stringify(data));
+  const envelope: SpreadsheetStateEnvelope = {
+    v: SPREADSHEET_STATE_SCHEMA_VERSION,
+    ts: Date.now(),
+    data,
+  };
+  const key = spreadsheetStorageKey(runId);
+  const payload = JSON.stringify(envelope);
+  try {
+    localStorage.setItem(key, payload);
+  } catch (err) {
+    // Quota exceeded — drop oldest sheets (keep current) and retry once
+    const isQuota =
+      err instanceof DOMException &&
+      (err.name === "QuotaExceededError" ||
+        err.name === "NS_ERROR_DOM_QUOTA_REACHED");
+    if (!isQuota) return;
+    try {
+      localStorage.removeItem(key);
+      evictOldestSpreadsheetStates(5);
+      localStorage.setItem(key, payload);
+    } catch {
+      // still failing — give up silently; in-memory state remains intact
+    }
+  }
 }
 
 type SpreadsheetCellEntry = { v: string | number; t: number; s?: object };

app/lib/types/assessment.ts

@@ -272,13 +272,27 @@ export interface ResultsCounts {
   failed: number;
 }
 
+export type UniverCommandInfo = {
+  id: string;
+  type?: number;
+  params?: unknown;
+};
+
 export type UniverAPI = {
   dispose?: () => void;
-  onCommandExecuted: (cb: () => void) => { dispose: () => void };
+  onCommandExecuted: (cb: (info: UniverCommandInfo) => void) => {
+    dispose: () => void;
+  };
   getActiveWorkbook: () => { save: () => object } | null;
   createUniverSheet: (d: object) => void;
 };
 
+export type SpreadsheetStateEnvelope = {
+  v: number;
+  ts: number;
+  data: object;
+};
+
 export interface AssessmentResultsPreview {
   runId: number;
   title: string;