Persist local action trail in browser storage

Author: xiangtinghe616-blip

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2026-05-30 — Local Action Persistence v1
+
+### Changed
+
+- Persisted frontend-only staged action trail records in browser localStorage.
+- Restored local staged action history after page refresh.
+- Restored staged break state from persisted action trail records.
+- Added a clear control for the current break's staged action history.
+- Preserved action preview, candidate decision guardrails, hide-staged queue behavior, and evidence review workflow.
+
+### Design Notes
+
+- This milestone makes the alpha workbench feel more like a persistent review tool.
+- Staged actions remain browser-local and are not written to a backend.
+- This prepares the project for a future real action-log API or file-backed persistence layer.
+
 ## 2026-05-30 — Action Log Payload Contract v1
 
 ### Added

frontend/components/BreakResolutionWorkbench.tsx

@@ -1,7 +1,11 @@
 "use client";
 
 import { Button } from "@salt-ds/core";
-import { type LocalActionRecord } from "@/lib/actionLog";
+import {
+  ACTION_TRAIL_STORAGE_KEY,
+  isLocalActionRecordArray,
+  type LocalActionRecord,
+} from "@/lib/actionLog";
 import { useEffect, useMemo, useState } from "react";
 import {
   candidatesByExceptionId as fallbackCandidatesByExceptionId,
@@ -874,15 +878,32 @@ function buildActionPreview({
 }
 
 
-function LocalActionTrail({ records }: { records: LocalActionRecord[] }) {
+function LocalActionTrail({
+  records,
+  onClear,
+}: {
+  records: LocalActionRecord[];
+  onClear: () => void;
+}) {
   return (
     <div className="mt-4 rounded-2xl border border-slate-200 bg-white p-3">
       <div className="flex items-center justify-between gap-3">
         <div className="text-xs font-bold uppercase tracking-[0.16em] text-slate-500">
           Staged action history
         </div>
-        <div className="rounded-full bg-slate-100 px-2.5 py-1 text-xs font-bold text-slate-600">
-          {records.length} staged
+        <div className="flex items-center gap-2">
+          <div className="rounded-full bg-slate-100 px-2.5 py-1 text-xs font-bold text-slate-600">
+            {records.length} staged
+          </div>
+          {records.length > 0 ? (
+            <button
+              type="button"
+              onClick={onClear}
+              className="rounded-full border border-slate-200 bg-white px-2.5 py-1 text-xs font-bold text-slate-600 hover:bg-slate-50"
+            >
+              Clear
+            </button>
+          ) : null}
         </div>
       </div>
 
@@ -935,6 +956,7 @@ export default function BreakResolutionWorkbench() {
   const [hideStaged, setHideStaged] = useState(false);
   const [stagedExceptionIds, setStagedExceptionIds] = useState<string[]>([]);
   const [actionTrail, setActionTrail] = useState<LocalActionRecord[]>([]);
+  const [hasLoadedActionTrail, setHasLoadedActionTrail] = useState(false);
   const [queueFilter, setQueueFilter] = useState<QueueFilter>("All");
   const [dataSource, setDataSource] = useState("static fallback");
   const [isLoadingData, setIsLoadingData] = useState(true);
@@ -977,6 +999,41 @@ export default function BreakResolutionWorkbench() {
     void loadWorkbenchData();
   }, []);
 
+  useEffect(() => {
+    try {
+      const storedActionTrail = window.localStorage.getItem(ACTION_TRAIL_STORAGE_KEY);
+
+      if (!storedActionTrail) {
+        return;
+      }
+
+      const parsedActionTrail = JSON.parse(storedActionTrail) as unknown;
+
+      if (isLocalActionRecordArray(parsedActionTrail)) {
+        setActionTrail(parsedActionTrail);
+        setStagedExceptionIds(
+          Array.from(new Set(parsedActionTrail.map((record) => record.exceptionId))),
+        );
+      }
+    } catch {
+      setActionTrail([]);
+      setStagedExceptionIds([]);
+    } finally {
+      setHasLoadedActionTrail(true);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!hasLoadedActionTrail) {
+      return;
+    }
+
+    window.localStorage.setItem(
+      ACTION_TRAIL_STORAGE_KEY,
+      JSON.stringify(actionTrail),
+    );
+  }, [actionTrail, hasLoadedActionTrail]);
+
   const filteredPriorityQueue = useMemo(
     () =>
       filterPriorityQueue(
@@ -1596,7 +1653,17 @@ export default function BreakResolutionWorkbench() {
             </div>
 
 
-            <LocalActionTrail records={currentBreakActionTrail} />
+            <LocalActionTrail
+              records={currentBreakActionTrail}
+              onClear={() => {
+                setActionTrail((current) =>
+                  current.filter((record) => record.exceptionId !== selectedBreak.exceptionId),
+                );
+                setStagedExceptionIds((current) =>
+                  current.filter((exceptionId) => exceptionId !== selectedBreak.exceptionId),
+                );
+              }}
+            />
           </aside>
         </section>
 

frontend/lib/actionLog.ts

@@ -1,3 +1,5 @@
+export const ACTION_TRAIL_STORAGE_KEY = "cash-reconciliation-workbench.action-trail.v1";
+
 export type DecisionType = "Action recommendation" | "Candidate decision";
 
 export type CandidateSource = "Rule-based" | "Splink" | "Split-payment";
@@ -63,3 +65,29 @@ export function toActionLogPayloadV1(
       : undefined,
   };
 }
+
+export function isLocalActionRecordArray(
+  value: unknown,
+): value is LocalActionRecord[] {
+  return (
+    Array.isArray(value) &&
+    value.every((item) => {
+      if (!item || typeof item !== "object") {
+        return false;
+      }
+
+      const record = item as Partial<LocalActionRecord>;
+
+      return (
+        typeof record.id === "string" &&
+        typeof record.exceptionId === "string" &&
+        typeof record.actionType === "string" &&
+        typeof record.proposedStatus === "string" &&
+        typeof record.dispositionCode === "string" &&
+        typeof record.actor === "string" &&
+        typeof record.timestamp === "string"
+      );
+    })
+  );
+}
+