From cd413fd89221c2de9f4df6cfe2e8ba36af6336da Mon Sep 17 00:00:00 2001
From: Akanksha Trehun <akankshatrehun@gmail.com>
Date: Thu, 22 Oct 2026 20:55:48 +0530
Subject: [PATCH] feat: undo/redo and project recovery with versioned project
 files

- One immutable EditState (recipe minus the sound preference, plus image
  overlay settings) in a bounded history: 100 steps, no duplicates,
  slider drags and typing coalesced into one step.
- Undo/redo buttons and Cmd/Ctrl+Z, Shift+Cmd+Z, Ctrl+Y; left to the
  browser inside text fields; disabled during export.
- Project record (edits + source description, no media) saved locally
  and flushed on pagehide; missing-source recovery that resumes when the
  same file is chosen again.
- Save/open .reframe.json with strict validation and a migration table.
- "Delete saved data" removes everything the editor stored.
- Reset settings is now undoable and no longer deletes saved data.
- Fix two pre-existing test failures on main (duplicate imports in
  exportEstimate.test.ts, URL state leaking between hook tests).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                                     |   6 +-
 docs/ARCHITECTURE.md                          |   2 +
 docs/PROJECTS.md                              | 141 ++++
 src/components/HistoryControls.tsx            |  65 ++
 src/components/ProjectPanel.tsx               | 223 +++++++
 src/components/VideoEditor.tsx                | 104 ++-
 .../__tests__/ProjectControls.test.tsx        | 105 +++
 src/hooks/tests/useKeyboardShortcuts.test.tsx | 132 ++++
 src/hooks/tests/useVideoEditor.test.ts        |   3 +
 src/hooks/tests/useVideoEditorProject.test.ts | 341 ++++++++++
 src/hooks/useKeyboardShortcuts.ts             |  17 +-
 src/hooks/useVideoEditor.ts                   | 607 +++++++++++++-----
 src/lib/editHistory.ts                        | 205 ++++++
 src/lib/exportEstimate.test.ts                |   8 +-
 src/lib/historyShortcuts.ts                   |  57 ++
 src/lib/project.ts                            | 375 +++++++++++
 src/lib/tests/editHistory.test.ts             | 194 ++++++
 src/lib/tests/project.test.ts                 | 259 ++++++++
 18 files changed, 2657 insertions(+), 187 deletions(-)
 create mode 100644 docs/PROJECTS.md
 create mode 100644 src/components/HistoryControls.tsx
 create mode 100644 src/components/ProjectPanel.tsx
 create mode 100644 src/components/__tests__/ProjectControls.test.tsx
 create mode 100644 src/hooks/tests/useKeyboardShortcuts.test.tsx
 create mode 100644 src/hooks/tests/useVideoEditorProject.test.ts
 create mode 100644 src/lib/editHistory.ts
 create mode 100644 src/lib/historyShortcuts.ts
 create mode 100644 src/lib/project.ts
 create mode 100644 src/lib/tests/editHistory.test.ts
 create mode 100644 src/lib/tests/project.test.ts

diff --git a/README.md b/README.md
index 9a26ce5f0..e2f74b595 100644
--- a/README.md
+++ b/README.md
@@ -85,6 +85,8 @@ Reframe is a **browser-based video editor** — everything happens on your devic
 - **Audio Control** — Keep or mute audio independently
 - **Speed Control** — 0.25x to 4x playback speed with smooth audio adjustment
 - **Quality Settings** — CRF slider for quality vs. file size trade-offs
+- **Undo / Redo** — every edit can be undone; a slider drag counts as one step
+- **Project recovery** — edits survive a refresh, and project files (`.reframe.json`) save and reopen your edits without the video. See [docs/PROJECTS.md](docs/PROJECTS.md)
 - **Smooth UX** — Lottie animations, live export progress, instant download
 
 Everything stays on your device. No servers. No tracking. No login.
@@ -95,6 +97,8 @@ Everything stays on your device. No servers. No tracking. No login.
 | Shortcut | Action |
 |----------|--------|
 | Ctrl+Enter / Cmd+Enter | Export video |
+| Ctrl+Z / Cmd+Z | Undo the last edit |
+| Ctrl+Y or Ctrl+Shift+Z / Shift+Cmd+Z | Redo |
 | Space | Play/pause video preview |
 | M | Toggle audio mute |
 | Escape | Cancel export |
@@ -439,7 +443,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide including development
 
 ## Privacy
 
-Reframe processes all videos **100% client-side**. Your video files are never uploaded to any server. You can even use Reframe offline (after first load). The source code is fully open for inspection.
+Reframe processes all videos **100% client-side**. Your video files are never uploaded to any server. You can even use Reframe offline (after first load). Edit settings and a copy of the open video are kept in your own browser so a refresh doesn't lose work; **Delete saved data** in the editor removes them. The source code is fully open for inspection.
 ---
 
 ## Contributors
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 7dd8e2303..8a5782538 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -114,6 +114,8 @@ Reframe uses a custom React hook (`useVideoEditor`) for state management instead
 - **Type safety** — Full TypeScript support
 - **Sufficient for scope** — App state is relatively simple and doesn't require complex state management
 
+All user-visible edits (the `EditRecipe` minus the completion-sound preference, plus the image overlay's position, size and opacity) live in one `EditState`. `useVideoEditor` holds it in a bounded undo history (`src/lib/editHistory.ts`), and the preview, the export and undo/redo all read that same state. Saving, recovery and project files are described in [PROJECTS.md](PROJECTS.md).
+
 ### Component Architecture
 
 Components are organized by feature:
diff --git a/docs/PROJECTS.md b/docs/PROJECTS.md
new file mode 100644
index 000000000..9a35af1dd
--- /dev/null
+++ b/docs/PROJECTS.md
@@ -0,0 +1,141 @@
+# Undo, recovery and project files
+
+This covers how Reframe keeps edit history, what it saves in the browser, and the `.reframe.json` project format. Nothing here sends data anywhere. Everything stays in the user's browser or in files the user saves themselves.
+
+## Edit state
+
+`EditState` (`src/lib/editHistory.ts`) is the single source of truth for every edit that changes the exported video:
+
+| Included | Where it lives |
+|---|---|
+| Preset, custom size, framing, trim, rotation | `recipe` |
+| Keep audio, normalise, volume, speed | `recipe` |
+| Quality, format, brightness, contrast, saturation, sharpness, stabilisation, denoise | `recipe` |
+| Text overlays (text, position, size, colour, weight, font name) | `recipe.textOverlays` |
+| Image overlay position, size and opacity | `imageOverlay` |
+
+Not included, on purpose:
+
+- **The completion-sound preference.** It's a setting, not an edit, so undo never flips it.
+- **Files** (the source video, the image overlay file, background music). They are binary assets, not edit values, so adding or removing the image file is not an undo step.
+- **Transient UI state.** Hover, open panels, the selected text overlay, export progress, object URLs and worker state.
+- **The multi-track timeline state.** It isn't connected to the UI or the export yet (see `PHASE_1_MVP.md`).
+
+`useVideoEditor` exposes `recipe` derived from `EditState`. `handleExport` passes that same object, plus the image overlay settings, to `exportVideo`. So after an undo the preview and the export can't disagree.
+
+## Undo and redo
+
+- **Snapshots.** Each history entry is an immutable `EditState`, about 1 KB, never media. Undo and redo just move between entries.
+- **Bounded.** `HISTORY_LIMIT` is 100 entries. The oldest are dropped first.
+- **No duplicates.** A change that leaves the state equal to the current one is not recorded.
+- **Coalescing.** Repeated changes to the same continuous control within `COALESCE_WINDOW_MS` (600 ms) merge into one step:
+  - Continuous controls are sliders, trim handles, custom size, and text-overlay text, position, size and colour.
+  - The window slides, so a long drag stays one step.
+  - Dragging back to the starting value removes the step.
+  - Discrete choices (preset, format, rotation, toggles, image overlay position) always get their own step, however fast they're clicked.
+  - Adding or removing a text overlay is always its own step.
+- **When history resets.** Choosing a new video, restoring a session and deleting saved data each start a fresh history.
+- **During export.** Undo and redo are disabled while an export runs. The running export has already taken its settings.
+- **Reset settings.** "Reset settings" and the `R` shortcut are now a single undoable step. They no longer delete saved data.
+
+**Shortcuts.** macOS uses ⌘Z and ⇧⌘Z. Other platforms use Ctrl+Z, and Ctrl+Y or Ctrl+Shift+Z. They work while a slider, checkbox or button has focus. In text fields and `contenteditable` they are left to the browser, so they undo the typing. See `src/lib/historyShortcuts.ts`.
+
+## What is saved in the browser
+
+| Key | Store | Contents |
+|---|---|---|
+| `reframe:project` | localStorage | The current project document (below). Written 500 ms after the last edit while a video is open, and on `pagehide`. |
+| `reframe-session` / `files` / `currentVideo` | IndexedDB | One copy of the open source video, overwritten when a new video is chosen. Unchanged from before. |
+| `reframe:recipe`, `editorState`, `soundOnCompletion` | localStorage | Existing settings records, kept for compatibility. |
+
+The project record is stored in localStorage rather than IndexedDB because it is only a few KB and a synchronous write can be flushed reliably when the page is hidden.
+
+**Recovery on load**, in this order:
+
+1. A `?settings=` share link wins.
+2. Otherwise the saved project's edits are restored.
+3. Otherwise the older URL and recipe records are used, as before.
+
+Then the stored video copy is read from IndexedDB:
+
+- **The copy is present.** The editor opens with the video and the edits.
+- **The copy is missing, or IndexedDB fails.** This can happen after eviction, private mode, or a quota error when saving. A notice names the file, its size and length, and asks the user to choose it again.
+  - Choosing a file with the same name and byte size resumes the project, trims included.
+  - A different file keeps the other settings but resets the trim points, like any new video.
+  - "Discard saved edits" forgets the project.
+
+**Failures are reported in the "Saved on this device" panel:**
+
+- If the video copy can't be stored, the user is told they'll need to choose the file again after a refresh.
+- If the edit record can't be written, they're told to use "Save project file".
+
+**Delete saved data** asks for confirmation. It then removes the project record, the recipe and overlay records and the stored video copy, closes the video and resets the editor. Project files the user saved are not affected.
+
+## Project file format
+
+"Save project file" downloads `<video name>.reframe.json`:
+
+```json
+{
+  "format": "reframe-project",
+  "schemaVersion": 1,
+  "savedAt": "2026-10-22T12:00:00.000Z",
+  "source": { "name": "clip.mp4", "size": 24000000, "type": "video/mp4",
+              "lastModified": 1700000000000, "duration": 42.5, "width": 1920, "height": 1080 },
+  "edit": {
+    "recipe": { "preset": "square-1-1", "trimStart": 3, "trimEnd": 20, "...": "every EditRecipe field except soundOnCompletion" },
+    "imageOverlay": { "position": "top-left", "size": 250, "opacity": 60 }
+  }
+}
+```
+
+The file never contains the video, the image overlay or any other media.
+
+**Opening a project file:**
+
+- **A video is open.** The edits are applied as one undoable step. Trim points that don't fit the video are dropped. If the project was made for a different file, the user is told to check the trims.
+- **No video is open.** The edits are held and the user is asked to choose the project's video.
+
+### Validation
+
+Every document, whether imported or read back from storage, goes through `parseProject` in `src/lib/project.ts`. It rejects the whole document if anything is wrong. It never clamps values or merges them with defaults.
+
+**Size and shape:**
+
+- Input over 512 KB is rejected before parsing.
+- The document must be a JSON object with `format: "reframe-project"` and an integer `schemaVersion`.
+
+**Field checks:**
+
+- Every recipe field must be present, with the same types and ranges the editor enforces.
+- Presets must be known ids, and speed one of the speed steps.
+- Trim end must be after trim start.
+- At most 50 text overlays, each with text of at most 500 characters.
+- Overlay ids must match `[A-Za-z0-9_-]{1,64}` and must be unique. Colours must be `#rrggbb`.
+- Font names must match `[A-Za-z0-9 _-]{1,64}`, because they reach FFmpeg's `drawtext` filter.
+
+**Safe construction:**
+
+- `fontPath` is never read from a project file, because it is passed to FFmpeg as a file path. It is also never written, since a `blob:` URL is meaningless outside the tab.
+- Output objects are built field by field, so unknown keys, including `__proto__`, are dropped rather than copied.
+
+### Changing the schema
+
+1. Bump `PROJECT_SCHEMA_VERSION`.
+2. Add `MIGRATIONS[oldVersion] = (doc) => upgradedDoc`. It runs on raw JSON before validation, and migrations chain one version at a time.
+3. Update the validators for the new shape and add a test that parses a document from the old version.
+
+Documents from a newer schema than the page knows are refused with "saved by a newer version of Reframe… reload the page". A version with no migration path is refused too.
+
+A change to `EditRecipe` fields needs a project schema bump, because the validator requires every field.
+
+## Not done yet: export profiles
+
+Reusable export profiles were scoped out of this change so undo/redo and recovery could land as one coherent slice. The suggested next slice:
+
+- **Profiles.** A profile is a named subset of `EditState["recipe"]`: preset or custom size, framing, format, quality and audio options. It is stored in its own localStorage key with its own schema version, and never includes trims, overlays or media.
+- **Built-in profiles.** Landscape 1920×1080, square 1080×1080 and portrait 1080×1920, plus 1080×1350. Label them by shape and size, not by platform name, to avoid implying endorsement.
+- **Applying a profile.** Applying one is one undoable `updateEdit` step. Manual controls stay as they are.
+- **Command-builder tests.** A test runs every profile through the worker's `buildArguments`/`buildVideoFilter` and asserts the scale and pad output matches the declared dimensions.
+- **Safe-area guides.** A CSS overlay on the preview only. It is not part of `EditState`, so it can't reach the export.
+- **Batch export, if added.** Encode one profile at a time through the existing worker, never concurrently, and report each output's success or failure separately.
diff --git a/src/components/HistoryControls.tsx b/src/components/HistoryControls.tsx
new file mode 100644
index 000000000..1279e060a
--- /dev/null
+++ b/src/components/HistoryControls.tsx
@@ -0,0 +1,65 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Undo2, Redo2 } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { isMacPlatform } from "@/lib/historyShortcuts";
+
+interface Props {
+  canUndo: boolean;
+  canRedo: boolean;
+  onUndo: () => void;
+  onRedo: () => void;
+}
+
+const buttonClass =
+  "inline-flex items-center gap-1.5 min-h-[36px] px-3 rounded-lg border border-[var(--border)] bg-[var(--surface)] text-xs font-heading font-bold uppercase tracking-widest transition-colors";
+
+export default function HistoryControls({ canUndo, canRedo, onUndo, onRedo }: Props) {
+  const [isMac, setIsMac] = useState(false);
+  useEffect(() => {
+    // navigator is browser-only, so the platform can't be read during render.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setIsMac(isMacPlatform());
+  }, []);
+
+  const undoKeys = isMac ? "⌘Z" : "Ctrl+Z";
+  const redoKeys = isMac ? "⇧⌘Z" : "Ctrl+Y";
+
+  return (
+    <div role="group" aria-label="Edit history" className="flex items-center gap-2">
+      <button
+        type="button"
+        onClick={onUndo}
+        disabled={!canUndo}
+        aria-keyshortcuts={isMac ? "Meta+Z" : "Control+Z"}
+        title={`Undo (${undoKeys})`}
+        className={cn(
+          buttonClass,
+          canUndo
+            ? "text-[var(--text)] hover:bg-[var(--border)]"
+            : "text-[var(--muted)] opacity-50 cursor-not-allowed"
+        )}
+      >
+        <Undo2 size={14} aria-hidden="true" />
+        Undo
+      </button>
+      <button
+        type="button"
+        onClick={onRedo}
+        disabled={!canRedo}
+        aria-keyshortcuts={isMac ? "Shift+Meta+Z" : "Control+Y Control+Shift+Z"}
+        title={`Redo (${redoKeys})`}
+        className={cn(
+          buttonClass,
+          canRedo
+            ? "text-[var(--text)] hover:bg-[var(--border)]"
+            : "text-[var(--muted)] opacity-50 cursor-not-allowed"
+        )}
+      >
+        <Redo2 size={14} aria-hidden="true" />
+        Redo
+      </button>
+    </div>
+  );
+}
diff --git a/src/components/ProjectPanel.tsx b/src/components/ProjectPanel.tsx
new file mode 100644
index 000000000..7d0bd9f01
--- /dev/null
+++ b/src/components/ProjectPanel.tsx
@@ -0,0 +1,223 @@
+"use client";
+
+import { useRef, useState } from "react";
+import { FolderOpen, Save, Trash2, HardDrive } from "lucide-react";
+import { formatBytes } from "@/lib/ffmpeg";
+import { MAX_PROJECT_FILE_BYTES } from "@/lib/project";
+import type {
+  PendingRecovery,
+  ProjectImportResult,
+  ProjectStorageStatus,
+} from "@/hooks/useVideoEditor";
+
+function formatDuration(seconds: number): string {
+  const total = Math.max(0, Math.round(seconds));
+  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, "0")}`;
+}
+
+function formatSavedAt(savedAt: number): string {
+  return new Date(savedAt).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+}
+
+const actionClass =
+  "inline-flex items-center justify-center gap-1.5 min-h-[36px] px-3 rounded-lg border border-[var(--border)] text-xs font-heading font-bold uppercase tracking-widest text-[var(--text)] hover:bg-[var(--border)] transition-colors";
+
+interface PanelProps {
+  hasFile: boolean;
+  storageStatus: ProjectStorageStatus;
+  disabled?: boolean;
+  onBuildProjectFile: () => { fileName: string; contents: string };
+  onImportProject: (contents: string) => ProjectImportResult;
+  onDeleteSavedData: () => void;
+}
+
+/** Explains what is saved in this browser, and saves, opens or deletes it. */
+export default function ProjectPanel({
+  hasFile,
+  storageStatus,
+  disabled = false,
+  onBuildProjectFile,
+  onImportProject,
+  onDeleteSavedData,
+}: PanelProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [message, setMessage] = useState<{ tone: "ok" | "error"; text: string } | null>(null);
+  const [confirmingDelete, setConfirmingDelete] = useState(false);
+
+  const handleSave = () => {
+    const { fileName, contents } = onBuildProjectFile();
+    const url = URL.createObjectURL(new Blob([contents], { type: "application/json" }));
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = fileName;
+    link.click();
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+    setMessage({ tone: "ok", text: `Saved ${fileName}. It holds your edits, not the video.` });
+  };
+
+  const handleOpen = async (event: React.ChangeEvent<HTMLInputElement>) => {
+    const chosen = event.target.files?.[0];
+    event.target.value = "";
+    if (!chosen) return;
+    if (chosen.size > MAX_PROJECT_FILE_BYTES) {
+      setMessage({ tone: "error", text: "That file is too large to be a Reframe project." });
+      return;
+    }
+    let contents: string;
+    try {
+      contents = await chosen.text();
+    } catch {
+      setMessage({ tone: "error", text: "That file couldn't be read." });
+      return;
+    }
+    const outcome = onImportProject(contents);
+    setMessage(
+      outcome.ok
+        ? { tone: "ok", text: outcome.message }
+        : { tone: "error", text: `Couldn't open the project. ${outcome.error}` }
+    );
+  };
+
+  const sourceLine =
+    storageStatus.sourceCopy === "saved"
+      ? "A copy of the video is kept in this browser's storage so a refresh doesn't lose it."
+      : storageStatus.sourceCopy === "failed"
+        ? "This browser didn't have room to keep a copy of the video. After a refresh you'll be asked to choose it again."
+        : storageStatus.sourceCopy === "saving"
+          ? "Keeping a copy of the video in this browser's storage…"
+          : null;
+
+  return (
+    <section
+      aria-labelledby="project-panel-title"
+      className="rounded-xl border border-[var(--border)] bg-[var(--surface)] p-4 space-y-3"
+    >
+      <h2
+        id="project-panel-title"
+        className="flex items-center gap-2 text-[10px] font-heading font-bold uppercase tracking-widest text-[var(--muted)]"
+      >
+        <HardDrive size={12} aria-hidden="true" />
+        Saved on this device
+      </h2>
+
+      <div className="space-y-1.5 text-xs text-[var(--muted)] leading-relaxed">
+        <p>
+          Your edit settings are saved in this browser as you work, so you can pick up after a
+          refresh. Nothing is uploaded.
+        </p>
+        {hasFile && sourceLine && <p>{sourceLine}</p>}
+        {hasFile && storageStatus.savedAt && !storageStatus.error && (
+          <p>Edits saved at {formatSavedAt(storageStatus.savedAt)}.</p>
+        )}
+        {storageStatus.error && <p className="text-[var(--error)]">{storageStatus.error}</p>}
+      </div>
+
+      <div className="grid grid-cols-2 gap-2">
+        <button type="button" onClick={handleSave} disabled={disabled} className={actionClass}>
+          <Save size={13} aria-hidden="true" />
+          Save project file
+        </button>
+        <button
+          type="button"
+          onClick={() => inputRef.current?.click()}
+          disabled={disabled}
+          className={actionClass}
+        >
+          <FolderOpen size={13} aria-hidden="true" />
+          Open project file
+        </button>
+        <input
+          ref={inputRef}
+          type="file"
+          accept=".json,application/json"
+          className="sr-only"
+          tabIndex={-1}
+          aria-hidden="true"
+          onChange={handleOpen}
+        />
+      </div>
+
+      <div aria-live="polite" className="text-xs">
+        {message && (
+          <p className={message.tone === "error" ? "text-[var(--error)]" : "text-[var(--text)]"}>
+            {message.text}
+          </p>
+        )}
+      </div>
+
+      {confirmingDelete ? (
+        <div className="rounded-lg border border-[var(--error-border)] bg-[var(--error-bg)] p-3 space-y-2">
+          <p className="text-xs text-[var(--text)]">
+            Delete the saved edits and the stored copy of the video from this browser, and close the
+            current video? Project files you saved are not affected.
+          </p>
+          <div className="flex gap-2">
+            <button
+              type="button"
+              onClick={() => {
+                onDeleteSavedData();
+                setConfirmingDelete(false);
+                setMessage({ tone: "ok", text: "Saved data deleted. The editor has been reset." });
+              }}
+              className="min-h-[36px] px-3 rounded-lg bg-[var(--error)] text-white text-xs font-heading font-bold uppercase tracking-widest"
+            >
+              Delete
+            </button>
+            <button
+              type="button"
+              onClick={() => setConfirmingDelete(false)}
+              className="min-h-[36px] px-3 rounded-lg border border-[var(--border)] text-xs font-heading font-bold uppercase tracking-widest text-[var(--text)]"
+            >
+              Cancel
+            </button>
+          </div>
+        </div>
+      ) : (
+        <button
+          type="button"
+          onClick={() => setConfirmingDelete(true)}
+          disabled={disabled}
+          className="inline-flex items-center gap-1.5 text-xs font-heading font-bold uppercase tracking-widest text-[var(--muted)] hover:text-[var(--error)] transition-colors"
+        >
+          <Trash2 size={12} aria-hidden="true" />
+          Delete saved data
+        </button>
+      )}
+    </section>
+  );
+}
+
+interface RecoveryProps {
+  recovery: PendingRecovery;
+  onDiscard: () => void;
+}
+
+/** Shown when a saved project's video has to be chosen again. */
+export function RecoveryNotice({ recovery, onDiscard }: RecoveryProps) {
+  const { source } = recovery;
+  return (
+    <div
+      role="status"
+      className="rounded-xl border border-film-200 bg-film-50 p-4 text-sm text-film-800 space-y-2"
+    >
+      <p className="font-heading font-bold">
+        {recovery.origin === "session" ? "Pick up where you left off" : "Choose the project's video"}
+      </p>
+      <p className="text-film-700">
+        {recovery.origin === "session"
+          ? "Your edits were saved, but this browser no longer has the video. "
+          : "Project files don't include the video. "}
+        Choose <strong>{source.name}</strong> ({formatBytes(source.size)}
+        {source.duration > 0 ? `, ${formatDuration(source.duration)}` : ""}) below to continue with
+        your edits. A different video starts with fresh trim points.
+      </p>
+      <button
+        type="button"
+        onClick={onDiscard}
+        className="text-xs font-heading font-bold uppercase tracking-widest text-film-600 hover:underline"
+      >
+        Discard saved edits
+      </button>
+    </div>
+  );
+}
diff --git a/src/components/VideoEditor.tsx b/src/components/VideoEditor.tsx
index 38045cf01..f4c300089 100644
--- a/src/components/VideoEditor.tsx
+++ b/src/components/VideoEditor.tsx
@@ -18,6 +18,8 @@ import ExportSettings from "./ExportSettings";
 import ExportOverlay from "./ExportOverlay";
 import DownloadResult from "./DownloadResult";
 import ImageOverlay from "./ImageOverlay";
+import HistoryControls from "./HistoryControls";
+import ProjectPanel, { RecoveryNotice } from "./ProjectPanel";
 import { getPresetById } from "@/lib/presets";
 
 import { cn } from "@/lib/utils";
@@ -36,7 +38,6 @@ import {
 } from "lucide-react";
 import OnboardingTour from "./OnboardingTour";
 import { useKeyboardShortcuts } from "@/hooks/useKeyboardShortcuts";
-import { loadOverlayState, persistOverlayState } from "@/lib/editorPersistence";
 
 interface SectionProps {
   icon: React.ReactNode;
@@ -136,10 +137,43 @@ function Kbd({ children }: { children: React.ReactNode }) {
 }
 
 /** Collapsible panel that lists all keyboard shortcuts. */
-function KeyboardShortcutsPanel() {
+function KeyboardShortcutsPanel({ isMac }: { isMac: boolean }) {
   const [open, setOpen] = useState(false);
+  const mod = isMac ? "⌘" : "Ctrl";
 
   const shortcuts: { keys: React.ReactNode[]; label: string }[] = [
+    {
+      keys: [
+        <Kbd key="mod">{mod}</Kbd>,
+        <span key="plus" className="text-[var(--muted)] text-xs">
+          +
+        </span>,
+        <Kbd key="z">Z</Kbd>,
+      ],
+      label: "Undo",
+    },
+    {
+      keys: isMac
+        ? [
+            <Kbd key="shift">⇧</Kbd>,
+            <span key="plus1" className="text-[var(--muted)] text-xs">
+              +
+            </span>,
+            <Kbd key="mod">⌘</Kbd>,
+            <span key="plus2" className="text-[var(--muted)] text-xs">
+              +
+            </span>,
+            <Kbd key="z">Z</Kbd>,
+          ]
+        : [
+            <Kbd key="mod">Ctrl</Kbd>,
+            <span key="plus" className="text-[var(--muted)] text-xs">
+              +
+            </span>,
+            <Kbd key="y">Y</Kbd>,
+          ],
+      label: "Redo",
+    },
     {
       keys: [
         <Kbd key="ctrl">Ctrl</Kbd>,
@@ -160,7 +194,7 @@ function KeyboardShortcutsPanel() {
     },
     {
       keys: [<Kbd key="r">R</Kbd>],
-      label: "Reset all settings",
+      label: "Reset all settings (undoable)",
     },
     {
       keys: [<Kbd key="esc">Esc</Kbd>],
@@ -258,6 +292,16 @@ export default function VideoEditor() {
     cancelExport,
     reset,
     resetSettings,
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+    recovery,
+    discardRecovery,
+    storageStatus,
+    buildProjectFile,
+    importProjectFile,
+    deleteSavedData,
     videoRef,
     seekTo,
     overlayFile,
@@ -284,24 +328,12 @@ export default function VideoEditor() {
     onToggleShortcutsModal: () => {},
     currentTime,
     duration,
+    undo,
+    redo,
   });
 
   const [copied, setCopied] = useState(false);
   const [shareCopied, setShareCopied] = useState(false);
-  const initialOverlayState = useRef({
-    overlayPosition,
-    overlaySize,
-    overlayOpacity,
-  });
-  useEffect(() => {
-    if (!file) return;
-
-    persistOverlayState(localStorage, {
-      overlayPosition,
-      overlaySize,
-      overlayOpacity,
-    });
-  }, [overlayPosition, overlaySize, overlayOpacity, file]);
   const [selectedTextId, setSelectedTextId] = useState<string | null>(null);
   const [openSections, setOpenSections] = useState({
     resize: true,
@@ -311,18 +343,6 @@ export default function VideoEditor() {
     audio: false,
     export: false,
   });
-  useEffect(() => {
-    const restored = loadOverlayState(localStorage, {
-      overlayPosition: initialOverlayState.current.overlayPosition,
-      overlaySize: initialOverlayState.current.overlaySize,
-      overlayOpacity: initialOverlayState.current.overlayOpacity,
-    });
-
-    if (restored.overlayPosition) setOverlayPosition(restored.overlayPosition);
-    if (typeof restored.overlaySize === "number") setOverlaySize(restored.overlaySize);
-    if (typeof restored.overlayOpacity === "number") setOverlayOpacity(restored.overlayOpacity);
-  }, [setOverlayOpacity, setOverlayPosition, setOverlaySize]);
-
   const toggleSection = (key: keyof typeof openSections) =>
     setOpenSections((prev) => ({ ...prev, [key]: !prev[key] }));
   const downloadRef = useRef<HTMLDivElement>(null);
@@ -468,6 +488,9 @@ export default function VideoEditor() {
         </header>
         <div className="grid grid-cols-1 lg:grid-cols-[1fr_340px] gap-5">
           <div className="space-y-4 min-w-0">
+            {!file && recovery && (
+              <RecoveryNotice recovery={recovery} onDiscard={discardRecovery} />
+            )}
             {!file && <PrivacyBanner />}
             <div className="bg-[var(--surface)] rounded-xl p-3 border border-[var(--border)] animate-fade-in">
               <FileUpload
@@ -515,6 +538,16 @@ export default function VideoEditor() {
                 ⚠️ Large file - processing may take several minutes
               </p>
             )}
+            {file && (
+              <div className="flex flex-wrap items-center justify-between gap-2">
+                <HistoryControls
+                  canUndo={canUndo}
+                  canRedo={canRedo}
+                  onUndo={undo}
+                  onRedo={redo}
+                />
+              </div>
+            )}
             {file && (
               <div
                 className={cn(
@@ -759,6 +792,15 @@ export default function VideoEditor() {
                 />
               </div>
             )}
+
+            <ProjectPanel
+              hasFile={!!file}
+              storageStatus={storageStatus}
+              disabled={isProcessing}
+              onBuildProjectFile={buildProjectFile}
+              onImportProject={importProjectFile}
+              onDeleteSavedData={deleteSavedData}
+            />
           </div>
 
           <div
@@ -818,12 +860,12 @@ export default function VideoEditor() {
                   onClick={resetSettings}
                   className="text-sm font-heading font-bold uppercase tracking-widest text-[var(--muted)] hover:text-film-600 transition-all opacity-60 hover:opacity-100"
                 >
-                  Clear saved session
+                  Reset settings
                 </button>
               </div>
             </div>
 
-            <KeyboardShortcutsPanel />
+            <KeyboardShortcutsPanel isMac={isMac} />
 
             {file && (
               <p className="rounded-xl border border-[var(--border)] bg-[var(--surface)] px-3 py-2 text-xs text-[var(--muted)] leading-relaxed">
diff --git a/src/components/__tests__/ProjectControls.test.tsx b/src/components/__tests__/ProjectControls.test.tsx
new file mode 100644
index 000000000..cfa5e5ce9
--- /dev/null
+++ b/src/components/__tests__/ProjectControls.test.tsx
@@ -0,0 +1,105 @@
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import HistoryControls from "../HistoryControls";
+import ProjectPanel, { RecoveryNotice } from "../ProjectPanel";
+import { MAX_PROJECT_FILE_BYTES } from "@/lib/project";
+
+describe("HistoryControls", () => {
+  it("reflects availability in the disabled state", () => {
+    const onUndo = vi.fn();
+    const onRedo = vi.fn();
+    render(<HistoryControls canUndo canRedo={false} onUndo={onUndo} onRedo={onRedo} />);
+    const undo = screen.getByRole("button", { name: /undo/i });
+    const redo = screen.getByRole("button", { name: /redo/i });
+    expect(undo).toBeEnabled();
+    expect(redo).toBeDisabled();
+    fireEvent.click(undo);
+    fireEvent.click(redo);
+    expect(onUndo).toHaveBeenCalledTimes(1);
+    expect(onRedo).not.toHaveBeenCalled();
+  });
+});
+
+function renderPanel(overrides: Partial<React.ComponentProps<typeof ProjectPanel>> = {}) {
+  const props = {
+    hasFile: true,
+    storageStatus: { savedAt: null, sourceCopy: "saved" as const, error: null },
+    onBuildProjectFile: vi.fn(() => ({ fileName: "clip.reframe.json", contents: "{}" })),
+    onImportProject: vi.fn(() => ({ ok: true as const, message: "Project opened and applied to this video." })),
+    onDeleteSavedData: vi.fn(),
+    ...overrides,
+  };
+  const view = render(<ProjectPanel {...props} />);
+  const input = view.container.querySelector('input[type="file"]') as HTMLInputElement;
+  return { props, input };
+}
+
+describe("ProjectPanel", () => {
+  it("says what is stored and that nothing is uploaded", () => {
+    renderPanel();
+    expect(screen.getByText(/Nothing is uploaded/)).toBeInTheDocument();
+    expect(screen.getByText(/copy of the video is kept in this browser/)).toBeInTheDocument();
+  });
+
+  it("warns when the video copy could not be stored", () => {
+    renderPanel({ storageStatus: { savedAt: null, sourceCopy: "failed", error: null } });
+    expect(screen.getByText(/asked to choose it again/)).toBeInTheDocument();
+  });
+
+  it("asks for confirmation before deleting saved data", () => {
+    const { props } = renderPanel();
+    fireEvent.click(screen.getByRole("button", { name: /delete saved data/i }));
+    expect(props.onDeleteSavedData).not.toHaveBeenCalled();
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    fireEvent.click(screen.getByRole("button", { name: /delete saved data/i }));
+    fireEvent.click(screen.getByRole("button", { name: "Delete" }));
+    expect(props.onDeleteSavedData).toHaveBeenCalledTimes(1);
+    expect(screen.getByText(/Saved data deleted/)).toBeInTheDocument();
+  });
+
+  it("opens a project file and reports the outcome", async () => {
+    const { props, input } = renderPanel();
+    const file = new File(['{"format":"reframe-project"}'], "p.json", { type: "application/json" });
+    fireEvent.change(input, { target: { files: [file] } });
+    await waitFor(() => expect(props.onImportProject).toHaveBeenCalledWith('{"format":"reframe-project"}'));
+    expect(await screen.findByText("Project opened and applied to this video.")).toBeInTheDocument();
+  });
+
+  it("shows why a project was rejected", async () => {
+    const { input } = renderPanel({
+      onImportProject: vi.fn(() => ({ ok: false as const, error: "This file is not a Reframe project." })),
+    });
+    fireEvent.change(input, { target: { files: [new File(["[]"], "p.json")] } });
+    expect(await screen.findByText(/Couldn't open the project. This file is not a Reframe project./)).toBeInTheDocument();
+  });
+
+  it("refuses an oversized file without reading it", async () => {
+    const { props, input } = renderPanel();
+    const big = new File(["x"], "big.json");
+    Object.defineProperty(big, "size", { value: MAX_PROJECT_FILE_BYTES + 1 });
+    const text = vi.spyOn(big, "text");
+    fireEvent.change(input, { target: { files: [big] } });
+    expect(await screen.findByText(/too large/)).toBeInTheDocument();
+    expect(text).not.toHaveBeenCalled();
+    expect(props.onImportProject).not.toHaveBeenCalled();
+  });
+});
+
+describe("RecoveryNotice", () => {
+  it("names the file to choose and offers to discard", () => {
+    const onDiscard = vi.fn();
+    render(
+      <RecoveryNotice
+        recovery={{
+          origin: "session",
+          source: { name: "clip.mp4", size: 2048, type: "video/mp4", lastModified: 0, duration: 75, width: 1, height: 1 },
+        }}
+        onDiscard={onDiscard}
+      />
+    );
+    expect(screen.getByText("clip.mp4")).toBeInTheDocument();
+    expect(screen.getByText(/1:15/)).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: /discard saved edits/i }));
+    expect(onDiscard).toHaveBeenCalled();
+  });
+});
diff --git a/src/hooks/tests/useKeyboardShortcuts.test.tsx b/src/hooks/tests/useKeyboardShortcuts.test.tsx
new file mode 100644
index 000000000..1eaa60532
--- /dev/null
+++ b/src/hooks/tests/useKeyboardShortcuts.test.tsx
@@ -0,0 +1,132 @@
+import { renderHook, fireEvent } from "@testing-library/react";
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { useKeyboardShortcuts } from "../useKeyboardShortcuts";
+import { isTextEntryTarget, matchHistoryShortcut } from "@/lib/historyShortcuts";
+import { DEFAULT_RECIPE } from "@/lib/constants";
+
+function setPlatform(platform: "MacIntel" | "Win32") {
+  vi.spyOn(navigator, "platform", "get").mockReturnValue(platform);
+}
+
+function setup(file: File | null = new File(["x"], "a.mp4")) {
+  const undo = vi.fn();
+  const redo = vi.fn();
+  const resetSettings = vi.fn();
+  renderHook(() =>
+    useKeyboardShortcuts({
+      file,
+      recipe: DEFAULT_RECIPE,
+      resetSettings,
+      updateRecipe: vi.fn(),
+      handleExport: vi.fn(),
+      status: "idle",
+      cancelExport: vi.fn(),
+      onToggleShortcutsModal: vi.fn(),
+      currentTime: 0,
+      duration: 10,
+      undo,
+      redo,
+    })
+  );
+  return { undo, redo, resetSettings };
+}
+
+function element(html: string): HTMLElement {
+  document.body.innerHTML = html;
+  return document.body.firstElementChild as HTMLElement;
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  document.body.innerHTML = "";
+});
+
+describe("matchHistoryShortcut", () => {
+  const key = (k: string, mods: Partial<KeyboardEvent> = {}) =>
+    ({ key: k, metaKey: false, ctrlKey: false, shiftKey: false, altKey: false, ...mods }) as KeyboardEvent;
+
+  it("uses Command on macOS", () => {
+    expect(matchHistoryShortcut(key("z", { metaKey: true }), true)).toBe("undo");
+    expect(matchHistoryShortcut(key("Z", { metaKey: true, shiftKey: true }), true)).toBe("redo");
+    expect(matchHistoryShortcut(key("z", { ctrlKey: true }), true)).toBeNull();
+    expect(matchHistoryShortcut(key("y", { metaKey: true }), true)).toBeNull();
+  });
+
+  it("uses Ctrl elsewhere, with both Ctrl+Y and Ctrl+Shift+Z for redo", () => {
+    expect(matchHistoryShortcut(key("z", { ctrlKey: true }), false)).toBe("undo");
+    expect(matchHistoryShortcut(key("y", { ctrlKey: true }), false)).toBe("redo");
+    expect(matchHistoryShortcut(key("Z", { ctrlKey: true, shiftKey: true }), false)).toBe("redo");
+    expect(matchHistoryShortcut(key("z", { metaKey: true }), false)).toBeNull();
+  });
+
+  it("ignores Alt combinations and plain keys", () => {
+    expect(matchHistoryShortcut(key("z", { ctrlKey: true, altKey: true }), false)).toBeNull();
+    expect(matchHistoryShortcut(key("z"), false)).toBeNull();
+  });
+});
+
+describe("isTextEntryTarget", () => {
+  it.each([
+    ['<input type="text">', true],
+    ['<input type="number">', true],
+    ["<input>", true],
+    ["<textarea></textarea>", true],
+    ['<input type="range">', false],
+    ['<input type="checkbox">', false],
+    ["<button>b</button>", false],
+    ["<select><option>a</option></select>", false],
+  ])("%s → %s", (html, expected) => {
+    expect(isTextEntryTarget(element(html))).toBe(expected);
+  });
+
+  it("treats contenteditable as text entry", () => {
+    const el = element('<div contenteditable="true">x</div>');
+    Object.defineProperty(el, "isContentEditable", { value: true });
+    expect(isTextEntryTarget(el)).toBe(true);
+  });
+});
+
+describe("undo/redo shortcuts", () => {
+  it("undoes and redoes with Ctrl on Windows/Linux", () => {
+    setPlatform("Win32");
+    const { undo, redo } = setup();
+    fireEvent.keyDown(window, { key: "z", ctrlKey: true });
+    fireEvent.keyDown(window, { key: "y", ctrlKey: true });
+    expect(undo).toHaveBeenCalledTimes(1);
+    expect(redo).toHaveBeenCalledTimes(1);
+  });
+
+  it("undoes with Command on macOS and prevents the browser default", () => {
+    setPlatform("MacIntel");
+    const { undo } = setup();
+    const event = new KeyboardEvent("keydown", { key: "z", metaKey: true, cancelable: true, bubbles: true });
+    window.dispatchEvent(event);
+    expect(undo).toHaveBeenCalledTimes(1);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("works while a slider has focus", () => {
+    setPlatform("Win32");
+    const { undo } = setup();
+    const slider = element('<input type="range">');
+    fireEvent.keyDown(slider, { key: "z", ctrlKey: true });
+    expect(undo).toHaveBeenCalledTimes(1);
+  });
+
+  it("leaves text undo to the browser inside text fields", () => {
+    setPlatform("Win32");
+    const { undo } = setup();
+    const input = element('<input type="text">');
+    const event = new KeyboardEvent("keydown", { key: "z", ctrlKey: true, cancelable: true, bubbles: true });
+    input.dispatchEvent(event);
+    expect(undo).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("does nothing before a video is loaded", () => {
+    setPlatform("Win32");
+    const { undo } = setup(null);
+    fireEvent.keyDown(window, { key: "z", ctrlKey: true });
+    expect(undo).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/hooks/tests/useVideoEditor.test.ts b/src/hooks/tests/useVideoEditor.test.ts
index a99157ec0..27eaa4a71 100644
--- a/src/hooks/tests/useVideoEditor.test.ts
+++ b/src/hooks/tests/useVideoEditor.test.ts
@@ -39,6 +39,9 @@ describe("useVideoEditor core controller", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     localStorageMock.clear();
+    // The hook mirrors the recipe into the query string; without this, one
+    // test's ?speed=2 was read back by the next test's mount.
+    window.history.replaceState(null, "", "/");
   });
 
   it("should initialize with the default recipe", () => {
diff --git a/src/hooks/tests/useVideoEditorProject.test.ts b/src/hooks/tests/useVideoEditorProject.test.ts
new file mode 100644
index 000000000..43c9eaefb
--- /dev/null
+++ b/src/hooks/tests/useVideoEditorProject.test.ts
@@ -0,0 +1,341 @@
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { useVideoEditor } from "../useVideoEditor";
+import { exportVideo } from "@/lib/ffmpeg";
+import { loadSessionFile, clearSessionFile, saveSessionFile } from "@/lib/sessionDB";
+import {
+  PROJECT_STORAGE_KEY,
+  createProjectDocument,
+  serializeProject,
+  toEditState,
+  type SourceInfo,
+} from "@/lib/project";
+import { DEFAULT_RECIPE } from "@/lib/constants";
+import { RECIPE_STORAGE_KEY } from "@/lib/editorPersistence";
+
+vi.mock("@/lib/ffmpeg", () => ({
+  loadFFmpeg: vi.fn().mockResolvedValue(true),
+  exportVideo: vi.fn().mockResolvedValue({ blobUrl: "blob:out", size: 1, width: 1, height: 1 }),
+  terminateFFmpeg: vi.fn(),
+  formatBytes: (n: number) => `${n} B`,
+  FFmpegLoadError: class extends Error {},
+}));
+
+vi.mock("@/lib/sessionDB", () => ({
+  saveSessionFile: vi.fn().mockResolvedValue(undefined),
+  loadSessionFile: vi.fn().mockResolvedValue(null),
+  clearSessionFile: vi.fn().mockResolvedValue(undefined),
+}));
+
+const VIDEO_META = { width: 1920, height: 1080, duration: 30 };
+
+// jsdom can't decode video, so metadata loads are simulated.
+Object.defineProperty(HTMLMediaElement.prototype, "src", {
+  configurable: true,
+  get: () => "",
+  set(this: HTMLVideoElement) {
+    setTimeout(() => this.onloadedmetadata?.(new Event("loadedmetadata")), 0);
+  },
+});
+Object.defineProperty(HTMLVideoElement.prototype, "videoWidth", { configurable: true, get: () => VIDEO_META.width });
+Object.defineProperty(HTMLVideoElement.prototype, "videoHeight", { configurable: true, get: () => VIDEO_META.height });
+Object.defineProperty(HTMLMediaElement.prototype, "duration", { configurable: true, get: () => VIDEO_META.duration });
+URL.createObjectURL = vi.fn(() => "blob:test");
+URL.revokeObjectURL = vi.fn();
+
+function videoFile(name = "clip.mp4", padding = 100): File {
+  // "....ftypisom" — passes the MP4 magic-byte check.
+  const header = new Uint8Array([0, 0, 0, 0x18, 0x66, 0x74, 0x79, 0x70, 0x69, 0x73, 0x6f, 0x6d]);
+  return new File([header, new Uint8Array(padding)], name, { type: "video/mp4", lastModified: 1 });
+}
+
+function sourceOf(file: File): SourceInfo {
+  return { name: file.name, size: file.size, type: file.type, lastModified: 1, ...VIDEO_META };
+}
+
+function savedProject(file: File) {
+  const edit = toEditState({ ...DEFAULT_RECIPE, preset: "square-1-1", trimStart: 4, trimEnd: 12, rotate: 90 });
+  return createProjectDocument(
+    { ...edit, imageOverlay: { position: "top-left", size: 250, opacity: 60 } },
+    sourceOf(file),
+    new Date(5_000)
+  );
+}
+
+async function openVideo(result: { current: ReturnType<typeof useVideoEditor> }, file = videoFile()) {
+  act(() => result.current.handleFileSelect(file));
+  await waitFor(() => expect(result.current.file).toBe(file));
+  return file;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  localStorage.clear();
+  window.history.replaceState(null, "", "/");
+  vi.mocked(loadSessionFile).mockResolvedValue(null);
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("undo/redo in the editor", () => {
+  it("restores mixed edits and exports exactly what is shown", async () => {
+    const { result } = renderHook(() => useVideoEditor());
+    await openVideo(result);
+    expect(result.current.canUndo).toBe(false);
+
+    act(() => result.current.updateRecipe({ rotate: 90 }));
+    act(() => result.current.setOverlayPosition("top-left"));
+    act(() => result.current.updateRecipe({ format: "gif" }));
+    expect(result.current.recipe.keepAudio).toBe(false);
+
+    act(() => result.current.undo());
+    expect(result.current.recipe.format).toBe("mp4");
+    expect(result.current.recipe.keepAudio).toBe(true);
+    act(() => result.current.undo());
+    expect(result.current.overlayPosition).toBe("bottom-right");
+    expect(result.current.canRedo).toBe(true);
+
+    await act(() => result.current.handleExport());
+    const [, exportedRecipe, , , , overlayOptions] = vi.mocked(exportVideo).mock.calls[0]!;
+    expect(exportedRecipe).toEqual(result.current.recipe);
+    expect(exportedRecipe).toMatchObject({ rotate: 90, format: "mp4", keepAudio: true });
+    expect(overlayOptions).toMatchObject({ position: "bottom-right" });
+
+    act(() => result.current.redo());
+    act(() => result.current.redo());
+    expect(result.current.recipe.format).toBe("gif");
+    expect(result.current.canRedo).toBe(false);
+  });
+
+  it("turns one slider drag into one undo step", async () => {
+    vi.useFakeTimers({ toFake: ["Date"] });
+    const { result } = renderHook(() => useVideoEditor());
+    await openVideo(result);
+
+    for (let i = 1; i <= 50; i++) {
+      vi.setSystemTime(10_000 + i * 16);
+      act(() => result.current.updateRecipe({ brightness: i / 100 }));
+    }
+    act(() => result.current.undo());
+    expect(result.current.recipe.brightness).toBe(0);
+    expect(result.current.canUndo).toBe(false);
+  });
+
+  it("keeps the completion-sound preference out of history", async () => {
+    const { result } = renderHook(() => useVideoEditor());
+    await openVideo(result);
+    act(() => result.current.toggleSound());
+    expect(result.current.recipe.soundOnCompletion).toBe(true);
+    expect(result.current.canUndo).toBe(false);
+  });
+
+  it("makes reset-settings undoable without deleting saved data", async () => {
+    const { result } = renderHook(() => useVideoEditor());
+    await openVideo(result);
+    act(() => result.current.updateRecipe({ speed: 2, rotate: 180 }));
+    act(() => result.current.resetSettings());
+    expect(result.current.recipe.speed).toBe(1);
+    expect(clearSessionFile).not.toHaveBeenCalled();
+    act(() => result.current.undo());
+    expect(result.current.recipe).toMatchObject({ speed: 2, rotate: 180 });
+  });
+
+  it("blocks undo while an export is running", async () => {
+    let finish!: (v: unknown) => void;
+    vi.mocked(exportVideo).mockImplementationOnce(() => new Promise((r) => (finish = r)) as never);
+    const { result } = renderHook(() => useVideoEditor());
+    await openVideo(result);
+    act(() => result.current.updateRecipe({ rotate: 90 }));
+
+    let exporting!: Promise<void>;
+    act(() => {
+      exporting = result.current.handleExport();
+    });
+    await waitFor(() => expect(result.current.status).toBe("exporting"));
+    expect(result.current.canUndo).toBe(false);
+    act(() => result.current.undo());
+    expect(result.current.recipe.rotate).toBe(90);
+
+    await act(async () => {
+      finish({ blobUrl: "blob:x", size: 1, width: 1, height: 1 });
+      await exporting;
+    });
+    expect(result.current.canUndo).toBe(true);
+  });
+
+  it("starts a fresh history for a new video", async () => {
+    const { result } = renderHook(() => useVideoEditor());
+    await openVideo(result);
+    act(() => result.current.updateRecipe({ rotate: 90 }));
+    await openVideo(result, videoFile("second.mp4"));
+    expect(result.current.canUndo).toBe(false);
+    expect(result.current.recipe.rotate).toBe(90);
+  });
+});
+
+describe("project recovery", () => {
+  it("restores edits and the stored video copy after a refresh", async () => {
+    const file = videoFile();
+    localStorage.setItem(PROJECT_STORAGE_KEY, JSON.stringify(savedProject(file)));
+    vi.mocked(loadSessionFile).mockResolvedValue(file);
+
+    const { result } = renderHook(() => useVideoEditor());
+    await waitFor(() => expect(result.current.file).toBe(file));
+    expect(result.current.recipe).toMatchObject({ preset: "square-1-1", trimStart: 4, trimEnd: 12, rotate: 90 });
+    expect(result.current.overlayPosition).toBe("top-left");
+    expect(result.current.recovery).toBeNull();
+    expect(result.current.canUndo).toBe(false);
+  });
+
+  it("asks for the video when the stored copy is gone, then resumes with trims intact", async () => {
+    const file = videoFile();
+    localStorage.setItem(PROJECT_STORAGE_KEY, JSON.stringify(savedProject(file)));
+
+    const { result } = renderHook(() => useVideoEditor());
+    await waitFor(() => expect(result.current.recovery?.source.name).toBe("clip.mp4"));
+    expect(result.current.file).toBeNull();
+
+    await openVideo(result, file);
+    expect(result.current.recovery).toBeNull();
+    expect(result.current.recipe).toMatchObject({ trimStart: 4, trimEnd: 12, rotate: 90 });
+  });
+
+  it("treats reading the stored copy failing like a missing file", async () => {
+    const file = videoFile();
+    localStorage.setItem(PROJECT_STORAGE_KEY, JSON.stringify(savedProject(file)));
+    vi.mocked(loadSessionFile).mockRejectedValue(new Error("IndexedDB blocked"));
+    const { result } = renderHook(() => useVideoEditor());
+    await waitFor(() => expect(result.current.recovery).not.toBeNull());
+  });
+
+  it("starts fresh trims when a different video is chosen", async () => {
+    localStorage.setItem(PROJECT_STORAGE_KEY, JSON.stringify(savedProject(videoFile())));
+    const { result } = renderHook(() => useVideoEditor());
+    await waitFor(() => expect(result.current.recovery).not.toBeNull());
+
+    await openVideo(result, videoFile("other.mp4", 5));
+    expect(result.current.recipe).toMatchObject({ trimStart: 0, trimEnd: null, rotate: 90 });
+    expect(result.current.recovery).toBeNull();
+  });
+
+  it("can discard a saved project whose video is gone", async () => {
+    localStorage.setItem(PROJECT_STORAGE_KEY, JSON.stringify(savedProject(videoFile())));
+    const { result } = renderHook(() => useVideoEditor());
+    await waitFor(() => expect(result.current.recovery).not.toBeNull());
+    act(() => result.current.discardRecovery());
+    expect(result.current.recovery).toBeNull();
+    expect(localStorage.getItem(PROJECT_STORAGE_KEY)).toBeNull();
+    expect(result.current.recipe.rotate).toBe(0);
+  });
+
+  it("flushes the latest edit when the page is hidden mid-debounce", async () => {
+    const { result } = renderHook(() => useVideoEditor());
+    await openVideo(result);
+    act(() => result.current.updateRecipe({ rotate: 270 }));
+    act(() => {
+      window.dispatchEvent(new Event("pagehide"));
+    });
+    const stored = JSON.parse(localStorage.getItem(PROJECT_STORAGE_KEY)!);
+    expect(stored.edit.recipe.rotate).toBe(270);
+    expect(stored.source.name).toBe("clip.mp4");
+    // Never the video itself.
+    expect(JSON.stringify(stored).length).toBeLessThan(4_000);
+    expect(saveSessionFile).toHaveBeenCalledTimes(1);
+  });
+
+  it("reports when edits can't be saved in this browser", async () => {
+    const setItem = vi.spyOn(Storage.prototype, "setItem").mockImplementation((key) => {
+      if (key === PROJECT_STORAGE_KEY) throw new DOMException("full", "QuotaExceededError");
+    });
+    const { result } = renderHook(() => useVideoEditor());
+    await openVideo(result);
+    act(() => result.current.updateRecipe({ rotate: 90 }));
+    act(() => {
+      window.dispatchEvent(new Event("pagehide"));
+    });
+    expect(result.current.storageStatus.error).toContain("Save project file");
+    setItem.mockRestore();
+  });
+
+  it("reports when the video copy can't be stored", async () => {
+    vi.mocked(saveSessionFile).mockRejectedValueOnce(new DOMException("full", "QuotaExceededError"));
+    const { result } = renderHook(() => useVideoEditor());
+    await openVideo(result);
+    await waitFor(() => expect(result.current.storageStatus.sourceCopy).toBe("failed"));
+  });
+
+  it("deletes everything it saved and resets the editor", async () => {
+    const { result } = renderHook(() => useVideoEditor());
+    await openVideo(result);
+    act(() => result.current.updateRecipe({ rotate: 90 }));
+    act(() => {
+      window.dispatchEvent(new Event("pagehide"));
+    });
+    expect(localStorage.getItem(PROJECT_STORAGE_KEY)).not.toBeNull();
+
+    act(() => result.current.deleteSavedData());
+    expect(result.current.file).toBeNull();
+    expect(result.current.recipe.rotate).toBe(0);
+    expect(result.current.canUndo).toBe(false);
+    expect(localStorage.getItem(PROJECT_STORAGE_KEY)).toBeNull();
+    expect(localStorage.getItem(RECIPE_STORAGE_KEY)).toBeNull();
+    expect(clearSessionFile).toHaveBeenCalled();
+    // The settings autosave must not write the defaults straight back.
+    await new Promise((r) => setTimeout(r, 600));
+    expect(localStorage.getItem(RECIPE_STORAGE_KEY)).toBeNull();
+  });
+});
+
+describe("project files", () => {
+  it("rejects a malformed project and leaves the edits alone", async () => {
+    const { result } = renderHook(() => useVideoEditor());
+    await openVideo(result);
+    act(() => result.current.updateRecipe({ rotate: 90 }));
+    let outcome!: ReturnType<typeof result.current.importProjectFile>;
+    act(() => {
+      outcome = result.current.importProjectFile('{"format":"reframe-project","schemaVersion":1,"edit":{}}');
+    });
+    expect(outcome.ok).toBe(false);
+    expect(result.current.recipe.rotate).toBe(90);
+  });
+
+  it("applies an imported project as one undoable step", async () => {
+    const { result } = renderHook(() => useVideoEditor());
+    const file = await openVideo(result);
+    const json = serializeProject(savedProject(file));
+    let outcome!: ReturnType<typeof result.current.importProjectFile>;
+    act(() => {
+      outcome = result.current.importProjectFile(json);
+    });
+    expect(outcome).toEqual({ ok: true, message: "Project opened and applied to this video." });
+    expect(result.current.recipe).toMatchObject({ preset: "square-1-1", trimStart: 4 });
+    act(() => result.current.undo());
+    expect(result.current.recipe.trimStart).toBe(0);
+  });
+
+  it("holds an imported project until its video is chosen", async () => {
+    const { result } = renderHook(() => useVideoEditor());
+    await waitFor(() => expect(loadSessionFile).toHaveBeenCalled());
+    const file = videoFile();
+    act(() => {
+      result.current.importProjectFile(serializeProject(savedProject(file)));
+    });
+    expect(result.current.recovery).toMatchObject({ origin: "imported", source: { name: "clip.mp4" } });
+    await openVideo(result, file);
+    expect(result.current.recipe).toMatchObject({ trimStart: 4, trimEnd: 12 });
+  });
+
+  it("exports the current edits and source description without media", async () => {
+    const { result } = renderHook(() => useVideoEditor());
+    await openVideo(result);
+    act(() => result.current.updateRecipe({ rotate: 180 }));
+    const { fileName, contents } = result.current.buildProjectFile();
+    expect(fileName).toBe("clip.reframe.json");
+    const doc = JSON.parse(contents);
+    expect(doc).toMatchObject({ format: "reframe-project", schemaVersion: 1, source: { name: "clip.mp4" } });
+    expect(doc.edit.recipe.rotate).toBe(180);
+    expect(Object.keys(doc).sort()).toEqual(["edit", "format", "savedAt", "schemaVersion", "source"]);
+  });
+});
diff --git a/src/hooks/useKeyboardShortcuts.ts b/src/hooks/useKeyboardShortcuts.ts
index de87eab6c..7fbc0b3fe 100644
--- a/src/hooks/useKeyboardShortcuts.ts
+++ b/src/hooks/useKeyboardShortcuts.ts
@@ -1,6 +1,7 @@
 import { EditRecipe, ExportStatus } from "@/lib/types";
 import { PRESETS } from "@/lib/presets";
 import { useEffect, useRef } from "react";
+import { isMacPlatform, isTextEntryTarget, matchHistoryShortcut } from "@/lib/historyShortcuts";
 
 interface UseKeyboardShortcutsProps {
   file: File | null;
@@ -13,6 +14,8 @@ interface UseKeyboardShortcutsProps {
   onToggleShortcutsModal: () => void;
   currentTime: number;
   duration: number;
+  undo?: () => void;
+  redo?: () => void;
 }
 
 export function useKeyboardShortcuts({
@@ -26,6 +29,8 @@ export function useKeyboardShortcuts({
   onToggleShortcutsModal,
   currentTime,
   duration,
+  undo,
+  redo,
 }: UseKeyboardShortcutsProps) {
   const currentTimeRef = useRef(currentTime);
   useEffect(() => {
@@ -33,6 +38,16 @@ export function useKeyboardShortcuts({
   }, [currentTime]);
   useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
+      // Undo/redo works from sliders and buttons too, but never steals the
+      // browser's own text undo while the user is typing.
+      const historyAction = matchHistoryShortcut(e, isMacPlatform());
+      if (historyAction && file && !isTextEntryTarget(e.target)) {
+        e.preventDefault();
+        if (historyAction === "undo") undo?.();
+        else redo?.();
+        return;
+      }
+
       const target = e.target as HTMLElement;
       if (
         target.tagName === "INPUT" ||
@@ -91,5 +106,5 @@ export function useKeyboardShortcuts({
 
     window.addEventListener("keydown", handleKeyDown);
     return () => window.removeEventListener("keydown", handleKeyDown);
-  }, [file, recipe, resetSettings, updateRecipe, handleExport, status, cancelExport, onToggleShortcutsModal, currentTime, duration]);
+  }, [file, recipe, resetSettings, updateRecipe, handleExport, status, cancelExport, onToggleShortcutsModal, currentTime, duration, undo, redo]);
 }
diff --git a/src/hooks/useVideoEditor.ts b/src/hooks/useVideoEditor.ts
index 2833bd853..ee698aaa4 100644
--- a/src/hooks/useVideoEditor.ts
+++ b/src/hooks/useVideoEditor.ts
@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useCallback, useEffect, useRef, useMemo } from "react";
+import { useState, useCallback, useEffect, useRef, useMemo, useReducer } from "react";
 import {
   EditRecipe,
   ExportResult,
@@ -11,6 +11,23 @@ import {
   MultiTrackEditorState,
   isValidRecipe,
 } from "@/lib/types";
+import { createHistory, deepEqual, historyReducer, type EditState } from "@/lib/editHistory";
+import {
+  DEFAULT_IMAGE_OVERLAY,
+  clearProjectRecord,
+  createProjectDocument,
+  fitEditToDuration,
+  loadProjectRecord,
+  matchesSource,
+  parseProject,
+  projectFileName,
+  saveProjectRecord,
+  serializeProject,
+  sourceInfoFromFile,
+  toEditState,
+  type ProjectDocument,
+  type SourceInfo,
+} from "@/lib/project";
 import { DEFAULT_RECIPE, SPEED_STEPS } from "@/lib/constants";
 import { getPresetById } from "@/lib/presets";
 import { loadFFmpeg, exportVideo, terminateFFmpeg, FFmpegLoadError } from "@/lib/ffmpeg";
@@ -27,16 +44,68 @@ import {
 } from "@/lib/timeline";
 import {
   getStoredSoundPreference,
+  loadOverlayState,
   loadPersistedRecipe,
   migrateRecipe as migratePersistedRecipe,
+  persistOverlayState,
   persistRecipe,
   persistSoundPreference,
   RECIPE_STORAGE_KEY,
   LEGACY_SETTINGS_KEY,
+  EDITOR_STATE_KEY,
 } from "@/lib/editorPersistence";
 import { saveSessionFile, loadSessionFile, clearSessionFile } from "@/lib/sessionDB";
 
 const DEFAULT_TITLE = "Reframe — Resize, trim, and export videos in your browser";
+const PROJECT_SAVE_DELAY_MS = 500;
+
+/** A saved project whose source video has to be chosen again. */
+export interface PendingRecovery {
+  source: SourceInfo;
+  /** "imported" when it came from a project file rather than this browser. */
+  origin: "session" | "imported";
+}
+
+export interface ProjectStorageStatus {
+  /** When the edit settings were last written to this browser. */
+  savedAt: number | null;
+  /** Whether the copy of the source video in IndexedDB is usable after a refresh. */
+  sourceCopy: "none" | "saving" | "saved" | "failed";
+  error: string | null;
+}
+
+export type ProjectImportResult = { ok: true; message: string } | { ok: false; error: string };
+
+const EMPTY_STORAGE_STATUS: ProjectStorageStatus = {
+  savedAt: null,
+  sourceCopy: "none",
+  error: null,
+};
+
+function withNewSource(edit: EditState, width: number, height: number): EditState {
+  const suggested = suggestPreset(width, height);
+  return {
+    ...edit,
+    recipe: {
+      ...edit.recipe,
+      trimStart: 0,
+      trimEnd: null,
+      ...(edit.recipe.preset === DEFAULT_RECIPE.preset ? { preset: suggested } : {}),
+    },
+  };
+}
+
+function clearSavedEditorData() {
+  try {
+    clearProjectRecord(localStorage);
+    localStorage.removeItem(RECIPE_STORAGE_KEY);
+    localStorage.removeItem(LEGACY_SETTINGS_KEY);
+    localStorage.removeItem(EDITOR_STATE_KEY);
+  } catch {
+    // ignore
+  }
+  clearSessionFile().catch(console.error);
+}
 
 export function extractMetadata(
   file: File
@@ -171,6 +240,43 @@ function decodeRecipe(encoded: string): Partial<EditRecipe> | null {
   }
 }
 
+function isValidValue(key: keyof EditRecipe, val: any): boolean {
+  switch (key) {
+    case "preset":
+      return typeof val === "string";
+    case "customWidth":
+      return typeof val === "number" && !isNaN(val) && val >= 16 && val <= 7680;
+    case "customHeight":
+      return typeof val === "number" && !isNaN(val) && val >= 16 && val <= 7680;
+    case "framing":
+      return val === "fit" || val === "fill";
+    case "trimStart":
+      return typeof val === "number" && !isNaN(val) && val >= 0;
+    case "trimEnd":
+      return val === null || (typeof val === "number" && !isNaN(val) && val >= 0);
+    case "rotate":
+      return val === 0 || val === 90 || val === 180 || val === 270;
+    case "speed":
+      return (
+        typeof val === "number" &&
+        !isNaN(val) &&
+        [0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 4].includes(val)
+      );
+    case "quality":
+      return typeof val === "number" && !isNaN(val) && val >= 18 && val <= 30;
+    case "format":
+      return val === "mp4" || val === "webm" || val === "mkv" || val === "gif";
+    case "brightness":
+      return typeof val === "number" && !isNaN(val) && val >= -1 && val <= 1;
+    case "contrast":
+      return typeof val === "number" && !isNaN(val) && val >= 0 && val <= 2;
+    case "saturation":
+      return typeof val === "number" && !isNaN(val) && val >= 0 && val <= 3;
+    default:
+      return true;
+  }
+}
+
 export function useVideoEditor() {
   const [file, setFile] = useState<File | null>(null);
   const [duration, setDuration] = useState<number>(0);
@@ -179,7 +285,22 @@ export function useVideoEditor() {
     height: number;
     duration: number;
   } | null>(null);
-  const [recipe, setRecipe] = useState<EditRecipe>({ ...DEFAULT_RECIPE });
+  // Every user-visible edit lives in one history of immutable snapshots, so
+  // the preview, the export and undo/redo all read the same state.
+  const [history, dispatchHistory] = useReducer(historyReducer, undefined, () =>
+    createHistory(toEditState(DEFAULT_RECIPE))
+  );
+  const edit = history.present;
+  const [soundOnCompletion, setSoundOnCompletion] = useState(DEFAULT_RECIPE.soundOnCompletion);
+  const recipe = useMemo<EditRecipe>(
+    () => ({ ...edit.recipe, soundOnCompletion }),
+    [edit.recipe, soundOnCompletion]
+  );
+  const [recovery, setRecovery] = useState<PendingRecovery | null>(null);
+  const recoveryRef = useRef<PendingRecovery | null>(null);
+  const [storageStatus, setStorageStatus] = useState<ProjectStorageStatus>(EMPTY_STORAGE_STATUS);
+  const pendingSaveRef = useRef<ProjectDocument | null>(null);
+  const userPickedFileRef = useRef(false);
   const [status, setStatus] = useState<ExportStatus>("idle");
   const [progress, setProgress] = useState(0);
   const [result, setResult] = useState<ExportResult | null>(null);
@@ -196,9 +317,9 @@ export function useVideoEditor() {
   const [loopMusic, setLoopMusic] = useState(false);
 
   const [overlayFile, setOverlayFile] = useState<File | null>(null);
-  const [overlayPosition, setOverlayPosition] = useState<OverlayPosition>("bottom-right");
-  const [overlaySize, setOverlaySize] = useState(150);
-  const [overlayOpacity, setOverlayOpacity] = useState(100);
+  const overlayPosition = edit.imageOverlay.position;
+  const overlaySize = edit.imageOverlay.size;
+  const overlayOpacity = edit.imageOverlay.opacity;
   const [currentTime, setCurrentTime] = useState(0);
 
   // Phase 1 MVP: Multi-track timeline support
@@ -226,144 +347,169 @@ export function useVideoEditor() {
     [addTrack]
   );
 
-  const isValidValue = (key: keyof EditRecipe, val: any): boolean => {
-    switch (key) {
-      case "preset":
-        return typeof val === "string";
-      case "customWidth":
-        return typeof val === "number" && !isNaN(val) && val >= 16 && val <= 7680;
-      case "customHeight":
-        return typeof val === "number" && !isNaN(val) && val >= 16 && val <= 7680;
-      case "framing":
-        return val === "fit" || val === "fill";
-      case "trimStart":
-        return typeof val === "number" && !isNaN(val) && val >= 0;
-      case "trimEnd":
-        return val === null || (typeof val === "number" && !isNaN(val) && val >= 0);
-      case "rotate":
-        return val === 0 || val === 90 || val === 180 || val === 270;
-      case "speed":
-        return (
-          typeof val === "number" &&
-          !isNaN(val) &&
-          [0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 4].includes(val)
-        );
-      case "quality":
-        return typeof val === "number" && !isNaN(val) && val >= 18 && val <= 30;
-      case "format":
-        return val === "mp4" || val === "webm" || val === "mkv" || val === "gif";
-      case "brightness":
-        return typeof val === "number" && !isNaN(val) && val >= -1 && val <= 1;
-      case "contrast":
-        return typeof val === "number" && !isNaN(val) && val >= 0 && val <= 2;
-      case "saturation":
-        return typeof val === "number" && !isNaN(val) && val >= 0 && val <= 3;
-      default:
-        return true;
-    }
-  };
+  const updateEdit = useCallback((update: (prev: EditState) => EditState) => {
+    dispatchHistory({ type: "edit", update, now: Date.now() });
+  }, []);
+
+  const resetEdit = useCallback((update: (prev: EditState) => EditState) => {
+    dispatchHistory({ type: "reset", update });
+  }, []);
+
+  const updateRecovery = useCallback((next: PendingRecovery | null) => {
+    recoveryRef.current = next;
+    setRecovery(next);
+  }, []);
+
+  const updateRecipe = useCallback(
+    (patch: Partial<EditRecipe>) => {
+      const { soundOnCompletion: sound, ...editPatch } = patch;
+      // A preference, not an edit: kept out of undo history.
+      if (typeof sound === "boolean") setSoundOnCompletion(sound);
 
-  const updateRecipe = useCallback((patch: Partial<EditRecipe>) => {
-    setRecipe((prev) => {
       const validated: Partial<EditRecipe> = {};
-      for (const [key, val] of Object.entries(patch)) {
+      for (const [key, val] of Object.entries(editPatch)) {
         if (isValidValue(key as keyof EditRecipe, val)) {
           (validated as any)[key] = val;
         }
       }
-      const next = { ...prev, ...validated };
-      // GIF has no audio — force keepAudio off
-      if (next.format === "gif") {
-        next.keepAudio = false;
-      }
-      return next;
-    });
-  }, []);
+      if (Object.keys(validated).length === 0) return;
+
+      updateEdit((prev) => {
+        const next = { ...prev.recipe, ...validated };
+        // GIF has no audio — force keepAudio off
+        if (next.format === "gif") {
+          next.keepAudio = false;
+        }
+        return { ...prev, recipe: next };
+      });
+    },
+    [updateEdit]
+  );
+
+  const setOverlayPosition = useCallback(
+    (position: OverlayPosition) =>
+      updateEdit((prev) => ({ ...prev, imageOverlay: { ...prev.imageOverlay, position } })),
+    [updateEdit]
+  );
+  const setOverlaySize = useCallback(
+    (size: number) =>
+      updateEdit((prev) => ({ ...prev, imageOverlay: { ...prev.imageOverlay, size } })),
+    [updateEdit]
+  );
+  const setOverlayOpacity = useCallback(
+    (opacity: number) =>
+      updateEdit((prev) => ({ ...prev, imageOverlay: { ...prev.imageOverlay, opacity } })),
+    [updateEdit]
+  );
 
   useEffect(() => {
     if (typeof window === "undefined") return;
+    let cancelled = false;
 
-    // Auto-restore saved video session
-    loadSessionFile()
-      .then(async (savedFile) => {
-        if (savedFile) {
-          try {
-            const { width, height, duration: dur } = await extractMetadata(savedFile);
-            setDuration(dur);
-            setVideoMetadata({ width, height, duration: dur });
-            setFile(savedFile);
-          } catch (e) {
-            console.error("Failed to restore video session:", e);
-            clearSessionFile().catch(console.error);
-          }
-        }
-      })
-      .catch(console.error);
-
+    let saved: ProjectDocument | null = null;
+    let baseline: EditState | null = null;
     try {
+      saved = loadProjectRecord(localStorage);
+      // Genuinely needs an effect: localStorage is a browser-only API.
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setSoundOnCompletion(getStoredSoundPreference(localStorage));
+
+      const storedOverlay = loadOverlayState(localStorage, {});
+      const imageOverlay = saved?.edit.imageOverlay ?? {
+        position: storedOverlay.overlayPosition ?? DEFAULT_IMAGE_OVERLAY.position,
+        size: storedOverlay.overlaySize ?? DEFAULT_IMAGE_OVERLAY.size,
+        opacity: storedOverlay.overlayOpacity ?? DEFAULT_IMAGE_OVERLAY.opacity,
+      };
+
       const params = new URLSearchParams(window.location.search);
       const encoded = params.get("settings");
-      if (encoded) {
-        const decoded = decodeRecipe(encoded);
-        if (decoded) {
-          // Genuinely needs an effect: window.location.search is a browser-
-          // only API, unavailable during SSR/render.
-          // eslint-disable-next-line react-hooks/set-state-in-effect
-          setRecipe(migratePersistedRecipe(decoded));
-          return;
-        } else {
-          const url = new URL(window.location.href);
-          url.searchParams.delete("settings");
-          window.history.replaceState(null, "", url.toString());
-        }
+      const shared = encoded ? decodeRecipe(encoded) : null;
+      if (encoded && !shared) {
+        const url = new URL(window.location.href);
+        url.searchParams.delete("settings");
+        window.history.replaceState(null, "", url.toString());
       }
 
       const recipeKeys = Object.keys(DEFAULT_RECIPE) as Array<keyof EditRecipe>;
-      const hasRecipeParams = recipeKeys.some((key) => params.has(key));
-
-      if (hasRecipeParams) {
+      if (shared) {
+        // An explicit share link wins over anything saved here.
+        baseline = toEditState(migratePersistedRecipe(shared), imageOverlay);
+      } else if (saved) {
+        // The saved project is the most complete record of the last session;
+        // the URL only mirrors the simple recipe fields.
+        baseline = saved.edit;
+      } else if (recipeKeys.some((key) => params.has(key))) {
         const updatedPatch: Partial<EditRecipe> = {};
         recipeKeys.forEach((key) => {
           const paramVal = params.get(key);
-          if (paramVal !== null) {
-            const defaultType = typeof DEFAULT_RECIPE[key];
-            let parsedVal: any;
-
-            if (defaultType === "number") {
-              parsedVal = parseFloat(paramVal);
-            } else if (defaultType === "boolean") {
-              parsedVal = paramVal === "true";
-            } else {
-              parsedVal = paramVal === "null" ? null : paramVal;
-            }
-
-            if (isValidValue(key, parsedVal)) {
-              (updatedPatch as any)[key] = parsedVal;
-            }
+          const defaultType = typeof DEFAULT_RECIPE[key];
+          if (paramVal === null || defaultType === "object") return;
+          let parsedVal: any;
+
+          if (defaultType === "number") {
+            parsedVal = parseFloat(paramVal);
+          } else if (defaultType === "boolean") {
+            parsedVal = paramVal === "true";
+          } else {
+            parsedVal = paramVal === "null" ? null : paramVal;
           }
-        });
 
-        if (Object.keys(updatedPatch).length > 0) {
-          setRecipe((prev) => ({
-            ...prev,
-            ...updatedPatch,
-          }));
-        }
+          if (isValidValue(key, parsedVal)) {
+            (updatedPatch as any)[key] = parsedVal;
+          }
+        });
+        baseline = toEditState({ ...DEFAULT_RECIPE, ...updatedPatch }, imageOverlay);
       } else {
-        setRecipe((current) =>
-          loadPersistedRecipe(
-            localStorage,
-            migratePersistedRecipe({
-              ...current,
-              soundOnCompletion: getStoredSoundPreference(localStorage),
-            })
-          )
+        baseline = toEditState(
+          loadPersistedRecipe(localStorage, migratePersistedRecipe({ ...DEFAULT_RECIPE })),
+          imageOverlay
         );
       }
-    } catch (e) {
-      // ignore
+    } catch {
+      // Storage unavailable (private mode, blocked site data): start fresh.
+    }
+    if (baseline) {
+      const restored = baseline;
+      resetEdit(() => restored);
     }
-  }, []);
+
+    // Auto-restore the saved copy of the source video, if there is one.
+    const savedSource = saved?.source ?? null;
+    const missingSource = () => {
+      if (!cancelled && savedSource && !userPickedFileRef.current) {
+        updateRecovery({ source: savedSource, origin: "session" });
+      }
+    };
+    loadSessionFile()
+      .then(async (savedFile) => {
+        if (cancelled || userPickedFileRef.current) return;
+        if (!savedFile) return missingSource();
+        try {
+          const meta = await extractMetadata(savedFile);
+          if (cancelled || userPickedFileRef.current) return;
+          setDuration(meta.duration);
+          setVideoMetadata(meta);
+          setFile(savedFile);
+          setStorageStatus((prev) => ({ ...prev, sourceCopy: "saved" }));
+          if (savedSource && !matchesSource(savedSource, savedFile)) {
+            // The stored copy belongs to a different project than the edits.
+            resetEdit((prev) => withNewSource(prev, meta.width, meta.height));
+          }
+        } catch (e) {
+          console.error("Failed to restore video session:", e);
+          clearSessionFile().catch(console.error);
+          missingSource();
+        }
+      })
+      .catch((e) => {
+        console.error("Failed to read saved video session:", e);
+        missingSource();
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [resetEdit, updateRecovery]);
 
   useEffect(() => {
     if (typeof window === "undefined") return;
@@ -375,6 +521,8 @@ export function useVideoEditor() {
         const currentVal = recipe[key];
         const defaultVal = DEFAULT_RECIPE[key];
 
+        // Lists such as textOverlays can't round-trip through a query string.
+        if (typeof defaultVal === "object" && defaultVal !== null) return;
         if (currentVal !== defaultVal) {
           params.set(key, currentVal === null ? "null" : String(currentVal));
         }
@@ -399,13 +547,18 @@ export function useVideoEditor() {
     if (typeof window === "undefined") return;
     const timer = setTimeout(() => {
       try {
-        persistRecipe(localStorage, recipe);
+        // Defaults need no record, and writing one would undo deleteSavedData().
+        if (deepEqual(edit.recipe, toEditState(DEFAULT_RECIPE).recipe)) {
+          localStorage.removeItem(RECIPE_STORAGE_KEY);
+        } else {
+          persistRecipe(localStorage, recipe);
+        }
       } catch {
         // ignore
       }
     }, 500);
     return () => clearTimeout(timer);
-  }, [recipe]);
+  }, [recipe, edit.recipe]);
 
   const recommendedPreset = useMemo(() => {
     if (!videoMetadata) return null;
@@ -423,6 +576,7 @@ export function useVideoEditor() {
       setFileError("");
       return;
     }
+    userPickedFileRef.current = true;
 
     if (!selectedFile.type.startsWith("video/")) {
       setFileError("Please upload a video file only.");
@@ -486,24 +640,30 @@ export function useVideoEditor() {
         setDuration(dur);
         setVideoMetadata({ width, height, duration: dur });
         setFile(selectedFile);
-        saveSessionFile(selectedFile).catch(console.error);
+        setStorageStatus((prev) => ({ ...prev, sourceCopy: "saving" }));
+        saveSessionFile(selectedFile)
+          .then(() => setStorageStatus((prev) => ({ ...prev, sourceCopy: "saved" })))
+          .catch((e) => {
+            // Usually a storage quota: edits are still saved, but the video
+            // will have to be chosen again after a refresh.
+            console.error("Failed to save video session:", e);
+            setStorageStatus((prev) => ({ ...prev, sourceCopy: "failed" }));
+          });
 
         if (dimensionCheck === "warning") {
           console.warn(
             `[Reframe] High resolution video detected (${width}×${height}). Export may be slow.`
           );
         }
-        setRecipe((prev) => {
-          const suggestedPreset = suggestPreset(width, height);
-          const shouldApplySuggestion = prev.preset === DEFAULT_RECIPE.preset;
-
-          return {
-            ...prev,
-            trimStart: 0,
-            trimEnd: null,
-            ...(shouldApplySuggestion ? { preset: suggestedPreset } : {}),
-          };
-        });
+        // A new source starts a new history. Choosing the file a saved
+        // project was made from picks that project back up, trims included.
+        const pending = recoveryRef.current;
+        if (pending && matchesSource(pending.source, selectedFile)) {
+          resetEdit((prev) => fitEditToDuration(prev, dur));
+        } else {
+          resetEdit((prev) => withNewSource(prev, width, height));
+        }
+        updateRecovery(null);
       } catch (err) {
         setError(
           `Layer 4 Validation Failed: ${err instanceof Error ? err.message : "Unknown error"}`
@@ -511,7 +671,7 @@ export function useVideoEditor() {
         setStatus("error");
       }
     })();
-  }, []);
+  }, [resetEdit, updateRecovery]);
 
   const handleExport = useCallback(async () => {
     if (!file) return;
@@ -674,14 +834,14 @@ export function useVideoEditor() {
         return;
       }
 
-      setRecipe((prev) => ({ ...prev, keepAudio: !prev.keepAudio }));
+      updateEdit((prev) => ({ ...prev, recipe: { ...prev.recipe, keepAudio: !prev.recipe.keepAudio } }));
     };
 
     document.addEventListener("keydown", handleMuteShortcut);
     return () => {
       document.removeEventListener("keydown", handleMuteShortcut);
     };
-  }, [file]);
+  }, [file, updateEdit]);
 
   useEffect(() => {
     return () => {
@@ -697,16 +857,11 @@ export function useVideoEditor() {
     };
   }, []);
 
+  // Resets the edit settings as one undoable step. Saved data is left alone;
+  // deleteSavedData() is the explicit way to remove it.
   const resetSettings = useCallback(() => {
-    setRecipe(DEFAULT_RECIPE);
-    try {
-      localStorage.removeItem(RECIPE_STORAGE_KEY);
-      localStorage.removeItem(LEGACY_SETTINGS_KEY);
-      clearSessionFile().catch(console.error);
-    } catch {
-      // ignore
-    }
-  }, []);
+    updateEdit((prev) => toEditState(DEFAULT_RECIPE, prev.imageOverlay));
+  }, [updateEdit]);
 
   const cancelExport = useCallback(() => {
     exportCancelledRef.current = true;
@@ -724,24 +879,166 @@ export function useVideoEditor() {
     setFile(null);
     setVideoMetadata(null);
     setDuration(0);
-    setRecipe(DEFAULT_RECIPE);
+    resetEdit((prev) => toEditState(DEFAULT_RECIPE, prev.imageOverlay));
     setStatus("idle");
     setProgress(0);
     setResult(null);
     setError(null);
     setExportStartedAt(null);
+    pendingSaveRef.current = null;
+    updateRecovery(null);
+    setStorageStatus(EMPTY_STORAGE_STATUS);
     try {
+      clearProjectRecord(localStorage);
       localStorage.removeItem(RECIPE_STORAGE_KEY);
       localStorage.removeItem(LEGACY_SETTINGS_KEY);
       clearSessionFile().catch(console.error);
     } catch {
       // ignore
     }
-  }, [result]);
+  }, [result, resetEdit, updateRecovery]);
+
+  /** Removes everything this editor saved in the browser and starts over. */
+  const deleteSavedData = useCallback(() => {
+    if (result?.blobUrl) URL.revokeObjectURL(result.blobUrl);
+    pendingSaveRef.current = null;
+    clearSavedEditorData();
+    setFile(null);
+    setVideoMetadata(null);
+    setDuration(0);
+    setResult(null);
+    setStatus("idle");
+    setProgress(0);
+    setError(null);
+    setExportStartedAt(null);
+    setOverlayFile(null);
+    resetEdit(() => toEditState(DEFAULT_RECIPE));
+    updateRecovery(null);
+    setStorageStatus(EMPTY_STORAGE_STATUS);
+  }, [result, resetEdit, updateRecovery]);
+
+  const isBusy = status === "loading-engine" || status === "exporting";
+  const canUndo = history.past.length > 0 && !isBusy;
+  const canRedo = history.future.length > 0 && !isBusy;
+  // Undo is blocked mid-export: the running export has already captured its
+  // settings, and the result has to match what the controls showed.
+  const undoEdit = useCallback(() => {
+    if (!isBusy) dispatchHistory({ type: "undo" });
+  }, [isBusy]);
+  const redoEdit = useCallback(() => {
+    if (!isBusy) dispatchHistory({ type: "redo" });
+  }, [isBusy]);
+
+  const currentSource = useMemo(
+    () => (file && videoMetadata ? sourceInfoFromFile(file, videoMetadata) : null),
+    [file, videoMetadata]
+  );
+
+  // Persist the project (edits + source description) while a video is open.
+  const flushProjectSave = useCallback(() => {
+    const doc = pendingSaveRef.current;
+    if (!doc) return;
+    pendingSaveRef.current = null;
+    let ok = false;
+    try {
+      ok = saveProjectRecord(localStorage, doc);
+    } catch {
+      ok = false;
+    }
+    setStorageStatus((prev) =>
+      ok
+        ? { ...prev, savedAt: Date.parse(doc.savedAt), error: null }
+        : { ...prev, error: "Couldn't save your edits in this browser. Use “Save project file” to keep them." }
+    );
+  }, []);
 
   useEffect(() => {
-    persistSoundPreference(localStorage, recipe.soundOnCompletion);
-  }, [recipe.soundOnCompletion]);
+    if (!currentSource) return;
+    pendingSaveRef.current = createProjectDocument(edit, currentSource, new Date());
+    const timer = setTimeout(flushProjectSave, PROJECT_SAVE_DELAY_MS);
+    return () => clearTimeout(timer);
+  }, [edit, currentSource, flushProjectSave]);
+
+  useEffect(() => {
+    if (!currentSource) return;
+    try {
+      persistOverlayState(localStorage, {
+        overlayPosition: edit.imageOverlay.position,
+        overlaySize: edit.imageOverlay.size,
+        overlayOpacity: edit.imageOverlay.opacity,
+      });
+    } catch {
+      // ignore
+    }
+  }, [edit.imageOverlay, currentSource]);
+
+  // A refresh or closed tab inside the debounce window must not lose the edit.
+  useEffect(() => {
+    window.addEventListener("pagehide", flushProjectSave);
+    return () => {
+      window.removeEventListener("pagehide", flushProjectSave);
+      flushProjectSave();
+    };
+  }, [flushProjectSave]);
+
+  /** The current project as a JSON file. Media is never included. */
+  const buildProjectFile = useCallback(() => {
+    const source = currentSource ?? recoveryRef.current?.source ?? null;
+    const doc = createProjectDocument(edit, source, new Date());
+    return { fileName: projectFileName(source), contents: serializeProject(doc) };
+  }, [currentSource, edit]);
+
+  const importProjectFile = useCallback(
+    (contents: string): ProjectImportResult => {
+      if (isBusy) return { ok: false, error: "Wait for the export to finish before opening a project." };
+      const parsed = parseProject(contents);
+      if (!parsed.ok) return { ok: false, error: parsed.error };
+      const { project } = parsed;
+
+      if (!currentSource) {
+        // Nothing open yet: hold the edits until the matching video is chosen.
+        resetEdit(() => project.edit);
+        if (project.source) updateRecovery({ source: project.source, origin: "imported" });
+        return {
+          ok: true,
+          message: project.source
+            ? `Project opened. Choose “${project.source.name}” to continue editing it.`
+            : "Project opened. Choose a video to apply its edits to.",
+        };
+      }
+
+      // Undoable, so opening the wrong file is one Cmd/Ctrl+Z away.
+      updateEdit(() => fitEditToDuration(project.edit, currentSource.duration));
+      updateRecovery(null);
+      if (project.source && !matchesSource(project.source, currentSource)) {
+        return {
+          ok: true,
+          message: `Edits applied. This project was made for “${project.source.name}”, so check the trim points.`,
+        };
+      }
+      return { ok: true, message: "Project opened and applied to this video." };
+    },
+    [currentSource, isBusy, resetEdit, updateEdit, updateRecovery]
+  );
+
+  /** Forgets a saved project whose video can't be found, keeping nothing. */
+  const discardRecovery = useCallback(() => {
+    try {
+      clearProjectRecord(localStorage);
+    } catch {
+      // ignore
+    }
+    resetEdit(() => toEditState(DEFAULT_RECIPE));
+    updateRecovery(null);
+  }, [resetEdit, updateRecovery]);
+
+  useEffect(() => {
+    try {
+      persistSoundPreference(localStorage, soundOnCompletion);
+    } catch {
+      // ignore
+    }
+  }, [soundOnCompletion]);
   const seekTo = useCallback((time: number) => {
     if (videoRef.current) {
       videoRef.current.currentTime = time;
@@ -756,8 +1053,8 @@ export function useVideoEditor() {
   });
 
   const toggleSound = useCallback(() => {
-    updateRecipe({ soundOnCompletion: !recipe.soundOnCompletion });
-  }, [recipe.soundOnCompletion, updateRecipe]);
+    setSoundOnCompletion((prev) => !prev);
+  }, []);
 
   return {
     file,
@@ -777,6 +1074,16 @@ export function useVideoEditor() {
     cancelExport,
     reset,
     resetSettings,
+    undo: undoEdit,
+    redo: redoEdit,
+    canUndo,
+    canRedo,
+    recovery,
+    discardRecovery,
+    storageStatus,
+    buildProjectFile,
+    importProjectFile,
+    deleteSavedData,
     musicFile,
     setMusicFile,
     musicVolume,
diff --git a/src/lib/editHistory.ts b/src/lib/editHistory.ts
new file mode 100644
index 000000000..f5b802302
--- /dev/null
+++ b/src/lib/editHistory.ts
@@ -0,0 +1,205 @@
+/**
+ * Bounded undo/redo history over immutable edit snapshots.
+ *
+ * Each entry is a complete `EditState` (a small JSON-like object — never the
+ * video itself), so undo is a pointer swap rather than a reverse command. A
+ * snapshot that equals the current one is never recorded, and rapid changes to
+ * the same continuous control (a slider drag, typing into a text overlay) are
+ * merged into a single entry so one gesture is one undo step.
+ */
+import type { EditRecipe, OverlayPosition, TextOverlay } from "./types";
+
+export interface ImageOverlaySettings {
+  position: OverlayPosition;
+  size: number;
+  opacity: number;
+}
+
+/**
+ * Everything that changes the exported video and can be serialised. The
+ * completion-sound preference lives on `EditRecipe` but is a setting, not an
+ * edit, so it is excluded. So are the image/music files themselves.
+ */
+export interface EditState {
+  recipe: Omit<EditRecipe, "soundOnCompletion">;
+  imageOverlay: ImageOverlaySettings;
+}
+
+export interface EditHistory {
+  past: EditState[];
+  present: EditState;
+  future: EditState[];
+  /** Coalescing key of the entry `present` was last merged into, if any. */
+  lastKey: string | null;
+  lastAt: number;
+}
+
+export const HISTORY_LIMIT = 100;
+export const COALESCE_WINDOW_MS = 600;
+
+/**
+ * Fields driven by sliders, drags or typing. Repeated changes to one of these
+ * within the coalescing window collapse into a single undo step. Everything
+ * else (presets, format, rotate, toggles) is a discrete choice and always gets
+ * its own step, however quickly it is clicked.
+ */
+const CONTINUOUS_FIELDS = new Set([
+  "trimStart",
+  "trimEnd",
+  "customWidth",
+  "customHeight",
+  "speed",
+  "volume",
+  "quality",
+  "brightness",
+  "contrast",
+  "saturation",
+  "sharpness",
+  "textOverlays.x",
+  "textOverlays.y",
+  "textOverlays.text",
+  "textOverlays.fontSize",
+  "textOverlays.color",
+]);
+
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    const arrB = b as unknown[];
+    return a.length === arrB.length && a.every((v, i) => deepEqual(v, arrB[i]));
+  }
+  const objA = a as Record<string, unknown>;
+  const objB = b as Record<string, unknown>;
+  const keys = new Set([...Object.keys(objA), ...Object.keys(objB)]);
+  for (const key of keys) {
+    // `undefined` and a missing key are the same thing once serialised.
+    if (!deepEqual(objA[key], objB[key])) return false;
+  }
+  return true;
+}
+
+function textOverlayChanges(prev: TextOverlay[], next: TextOverlay[]): string[] | null {
+  // Adding, removing or reordering overlays is structural: never coalesced.
+  if (prev.length !== next.length || prev.some((o, i) => o.id !== next[i]?.id)) return null;
+  const changes: string[] = [];
+  next.forEach((overlay, i) => {
+    const before = prev[i] as unknown as Record<string, unknown>;
+    const after = overlay as unknown as Record<string, unknown>;
+    for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+      if (!deepEqual(before[key], after[key])) changes.push(`textOverlays.${key}#${overlay.id}`);
+    }
+  });
+  return changes;
+}
+
+/**
+ * Describes a change for coalescing. Returns `null` when the change must
+ * always be its own history entry.
+ */
+export function coalesceKey(prev: EditState, next: EditState): string | null {
+  const paths: string[] = [];
+  const prevRecipe = prev.recipe as unknown as Record<string, unknown>;
+  const nextRecipe = next.recipe as unknown as Record<string, unknown>;
+
+  for (const key of new Set([...Object.keys(prevRecipe), ...Object.keys(nextRecipe)])) {
+    if (deepEqual(prevRecipe[key], nextRecipe[key])) continue;
+    if (key === "textOverlays") {
+      const changes = textOverlayChanges(prev.recipe.textOverlays, next.recipe.textOverlays);
+      if (!changes) return null;
+      paths.push(...changes);
+    } else {
+      paths.push(key);
+    }
+  }
+  for (const key of Object.keys(next.imageOverlay) as Array<keyof ImageOverlaySettings>) {
+    if (prev.imageOverlay[key] !== next.imageOverlay[key]) paths.push(`imageOverlay.${key}`);
+  }
+
+  if (paths.length === 0) return null;
+  const continuous = paths.every((path) => CONTINUOUS_FIELDS.has(path.split("#")[0] ?? path));
+  return continuous ? paths.sort().join("|") : null;
+}
+
+export function createHistory(present: EditState): EditHistory {
+  return { past: [], present, future: [], lastKey: null, lastAt: 0 };
+}
+
+export function recordEdit(
+  history: EditHistory,
+  next: EditState,
+  now: number,
+  limit: number = HISTORY_LIMIT
+): EditHistory {
+  if (deepEqual(next, history.present)) return history;
+
+  const key = coalesceKey(history.present, next);
+  const canMerge =
+    key !== null &&
+    key === history.lastKey &&
+    now - history.lastAt <= COALESCE_WINDOW_MS &&
+    history.past.length > 0;
+
+  if (canMerge) {
+    const before = history.past[history.past.length - 1];
+    // Dragged back to where the gesture started: the step is now a no-op.
+    if (deepEqual(next, before)) {
+      return { past: history.past.slice(0, -1), present: next, future: [], lastKey: null, lastAt: 0 };
+    }
+    return { ...history, present: next, future: [], lastAt: now };
+  }
+
+  const past = [...history.past, history.present];
+  return {
+    past: past.length > limit ? past.slice(past.length - limit) : past,
+    present: next,
+    future: [],
+    lastKey: key,
+    lastAt: now,
+  };
+}
+
+export function undo(history: EditHistory): EditHistory {
+  const previous = history.past[history.past.length - 1];
+  if (!previous) return history;
+  return {
+    past: history.past.slice(0, -1),
+    present: previous,
+    future: [history.present, ...history.future],
+    lastKey: null,
+    lastAt: 0,
+  };
+}
+
+export function redo(history: EditHistory): EditHistory {
+  const following = history.future[0];
+  if (!following) return history;
+  return {
+    past: [...history.past, history.present],
+    present: following,
+    future: history.future.slice(1),
+    lastKey: null,
+    lastAt: 0,
+  };
+}
+
+export type HistoryAction =
+  | { type: "edit"; update: (prev: EditState) => EditState; now: number }
+  /** Starts a fresh history (new source video, restored or deleted project). */
+  | { type: "reset"; update: (prev: EditState) => EditState }
+  | { type: "undo" }
+  | { type: "redo" };
+
+export function historyReducer(history: EditHistory, action: HistoryAction): EditHistory {
+  switch (action.type) {
+    case "edit":
+      return recordEdit(history, action.update(history.present), action.now);
+    case "reset":
+      return createHistory(action.update(history.present));
+    case "undo":
+      return undo(history);
+    case "redo":
+      return redo(history);
+  }
+}
diff --git a/src/lib/exportEstimate.test.ts b/src/lib/exportEstimate.test.ts
index fa7180f40..12fa5af8f 100644
--- a/src/lib/exportEstimate.test.ts
+++ b/src/lib/exportEstimate.test.ts
@@ -1,7 +1,6 @@
 import { describe, test, expect } from "vitest";
 import { estimateExportSize, formatEstimatedSize } from "./exportEstimate";
 import { EditRecipe } from "./types";
-import { describe, test, expect } from "vitest";
 
 // Minimal recipe factory — only the fields estimateExportSize cares about
 function makeRecipe(overrides: Partial<EditRecipe> = {}): EditRecipe {
@@ -50,9 +49,10 @@ describe("estimateExportSize", () => {
     expect(long / short).toBeCloseTo(4, 0);
   });
 
-  test("higher resolution (4k) produces a larger estimate than 720p", () => {
-    const hd  = estimateExportSize(makeRecipe({ preset: "720p" }), 60);
-    const uhd = estimateExportSize(makeRecipe({ preset: "4k"   }), 60);
+  // "720p"/"4k" were never preset ids; use real ones (1280×720 vs 5120×1080).
+  test("higher resolution produces a larger estimate than 720p", () => {
+    const hd  = estimateExportSize(makeRecipe({ preset: "twitter-hd" }), 60);
+    const uhd = estimateExportSize(makeRecipe({ preset: "instagram-panoramic" }), 60);
     expect(uhd).toBeGreaterThan(hd);
   });
 
diff --git a/src/lib/historyShortcuts.ts b/src/lib/historyShortcuts.ts
new file mode 100644
index 000000000..d3fade737
--- /dev/null
+++ b/src/lib/historyShortcuts.ts
@@ -0,0 +1,57 @@
+/** Keyboard handling for undo/redo, kept separate so it can be unit tested. */
+
+// Inputs where the browser's own undo applies to the typed text.
+const TEXT_INPUT_TYPES = new Set([
+  "text",
+  "search",
+  "url",
+  "tel",
+  "email",
+  "password",
+  "number",
+  "date",
+  "datetime-local",
+  "month",
+  "time",
+  "week",
+]);
+
+/**
+ * True when focus is somewhere the user is typing. Undo shortcuts are left to
+ * the browser there, so Cmd/Ctrl+Z edits the text rather than the video.
+ * Sliders, checkboxes and buttons are not text entry: undo applies to the edit.
+ */
+export function isTextEntryTarget(target: EventTarget | null): boolean {
+  if (!target || typeof (target as HTMLElement).tagName !== "string") return false;
+  const el = target as HTMLElement;
+  if (el.isContentEditable) return true;
+  if (el.tagName === "TEXTAREA") return true;
+  if (el.tagName === "INPUT") {
+    return TEXT_INPUT_TYPES.has(((el as HTMLInputElement).type || "text").toLowerCase());
+  }
+  return false;
+}
+
+export function isMacPlatform(): boolean {
+  if (typeof navigator === "undefined") return false;
+  const platform =
+    (navigator as Navigator & { userAgentData?: { platform?: string } }).userAgentData?.platform ??
+    navigator.platform ??
+    "";
+  return /mac|iphone|ipad|ipod/i.test(platform);
+}
+
+type ShortcutEvent = Pick<KeyboardEvent, "key" | "metaKey" | "ctrlKey" | "shiftKey" | "altKey">;
+
+/**
+ * macOS: ⌘Z undo, ⇧⌘Z redo. Elsewhere: Ctrl+Z undo, Ctrl+Y or Ctrl+Shift+Z redo.
+ */
+export function matchHistoryShortcut(e: ShortcutEvent, isMac: boolean): "undo" | "redo" | null {
+  if (e.altKey) return null;
+  const primary = isMac ? e.metaKey && !e.ctrlKey : e.ctrlKey && !e.metaKey;
+  if (!primary) return null;
+  const key = e.key.toLowerCase();
+  if (key === "z") return e.shiftKey ? "redo" : "undo";
+  if (key === "y" && !isMac && !e.shiftKey) return "redo";
+  return null;
+}
diff --git a/src/lib/project.ts b/src/lib/project.ts
new file mode 100644
index 000000000..d3e7d7c1a
--- /dev/null
+++ b/src/lib/project.ts
@@ -0,0 +1,375 @@
+/**
+ * Reframe project documents: the serialisable edit state plus a description of
+ * the source video, used for the on-device session record and for the
+ * explicit "Save project file" / "Open project file" JSON.
+ *
+ * A project never contains media. The source is identified by name, size and
+ * duration so it can be matched when the user picks the file again.
+ *
+ * Schema changes: bump PROJECT_SCHEMA_VERSION and add an entry to MIGRATIONS
+ * that upgrades a document from the previous version. Every document, stored
+ * or imported, is migrated to the current version and then validated in full.
+ */
+import { DEFAULT_RECIPE, SPEED_STEPS } from "./constants";
+import { PRESETS } from "./presets";
+import { RECIPE_VERSION, type OverlayPosition, type TextOverlay } from "./types";
+import type { EditState, ImageOverlaySettings } from "./editHistory";
+
+export const PROJECT_FORMAT = "reframe-project";
+export const PROJECT_SCHEMA_VERSION = 1;
+export const PROJECT_STORAGE_KEY = "reframe:project";
+/** Projects are a few KB; anything this large is not one of ours. */
+export const MAX_PROJECT_FILE_BYTES = 512 * 1024;
+export const MAX_TEXT_OVERLAYS = 50;
+export const MAX_OVERLAY_TEXT_LENGTH = 500;
+
+export const DEFAULT_IMAGE_OVERLAY: ImageOverlaySettings = {
+  position: "bottom-right",
+  size: 150,
+  opacity: 100,
+};
+
+export interface SourceInfo {
+  name: string;
+  size: number;
+  type: string;
+  lastModified: number;
+  duration: number;
+  width: number;
+  height: number;
+}
+
+export interface ProjectDocument {
+  format: typeof PROJECT_FORMAT;
+  schemaVersion: number;
+  savedAt: string;
+  source: SourceInfo | null;
+  edit: EditState;
+}
+
+export type ParseResult =
+  | { ok: true; project: ProjectDocument; migratedFrom: number | null }
+  | { ok: false; error: string };
+
+type RawDocument = Record<string, unknown>;
+export type Migration = (doc: RawDocument) => RawDocument;
+
+/** Keyed by the version a migration upgrades *from*. */
+export const MIGRATIONS: Record<number, Migration> = {};
+
+class ProjectError extends Error {}
+
+function fail(message: string): never {
+  throw new ProjectError(message);
+}
+
+function isRecord(value: unknown): value is RawDocument {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function num(obj: RawDocument, key: string, min: number, max: number, label = key): number {
+  const value = obj[key];
+  if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) {
+    fail(`“${label}” must be a number from ${min} to ${max}.`);
+  }
+  return value;
+}
+
+function bool(obj: RawDocument, key: string): boolean {
+  if (typeof obj[key] !== "boolean") fail(`“${key}” must be true or false.`);
+  return obj[key] as boolean;
+}
+
+function oneOf<T>(obj: RawDocument, key: string, allowed: readonly T[]): T {
+  if (!allowed.includes(obj[key] as T)) fail(`“${key}” has an unsupported value.`);
+  return obj[key] as T;
+}
+
+const OVERLAY_POSITIONS: readonly OverlayPosition[] = [
+  "top-left",
+  "top-right",
+  "bottom-left",
+  "bottom-right",
+];
+const SAFE_ID = /^[A-Za-z0-9_-]{1,64}$/;
+// Font names reach the FFmpeg drawtext filter, so only plain names are allowed.
+const SAFE_FONT_NAME = /^[A-Za-z0-9 _-]{1,64}$/;
+const HEX_COLOR = /^#[0-9A-Fa-f]{6}$/;
+
+function parseTextOverlay(raw: unknown, index: number): TextOverlay {
+  const label = `text overlay ${index + 1}`;
+  if (!isRecord(raw)) fail(`The ${label} is not valid.`);
+  if (typeof raw.id !== "string" || !SAFE_ID.test(raw.id)) fail(`The ${label} has an invalid id.`);
+  if (typeof raw.text !== "string" || raw.text.length > MAX_OVERLAY_TEXT_LENGTH) {
+    fail(`The ${label} text must be at most ${MAX_OVERLAY_TEXT_LENGTH} characters.`);
+  }
+  if (typeof raw.color !== "string" || !HEX_COLOR.test(raw.color)) {
+    fail(`The ${label} colour must be a hex value like #ffffff.`);
+  }
+  if (raw.fontFamily !== undefined && (typeof raw.fontFamily !== "string" || !SAFE_FONT_NAME.test(raw.fontFamily))) {
+    fail(`The ${label} font name is not allowed.`);
+  }
+  // `fontPath` is deliberately never read: it is passed to FFmpeg as a file
+  // path, so a project file must not be able to supply one.
+  return {
+    id: raw.id,
+    text: raw.text,
+    x: num(raw, "x", 0, 100, `${label} x`),
+    y: num(raw, "y", 0, 100, `${label} y`),
+    fontSize: num(raw, "fontSize", 12, 120, `${label} font size`),
+    color: raw.color,
+    fontWeight: oneOf(raw, "fontWeight", ["normal", "bold", "900"] as const),
+    ...(typeof raw.fontFamily === "string" ? { fontFamily: raw.fontFamily } : {}),
+  };
+}
+
+function parseRecipe(raw: unknown): EditState["recipe"] {
+  if (!isRecord(raw)) fail("The project has no edit settings.");
+  if (raw.version !== RECIPE_VERSION) fail("The project's edit settings use an unsupported version.");
+  if (typeof raw.preset !== "string" || !PRESETS.some((p) => p.id === raw.preset)) {
+    fail("“preset” is not a known output size.");
+  }
+  const trimStart = num(raw, "trimStart", 0, Number.MAX_SAFE_INTEGER);
+  let trimEnd: number | null = null;
+  if (raw.trimEnd !== null) {
+    trimEnd = num(raw, "trimEnd", 0, Number.MAX_SAFE_INTEGER);
+    if (trimEnd <= trimStart) fail("The trim end must be after the trim start.");
+  }
+  if (!Array.isArray(raw.textOverlays)) fail("“textOverlays” must be a list.");
+  if (raw.textOverlays.length > MAX_TEXT_OVERLAYS) {
+    fail(`A project can have at most ${MAX_TEXT_OVERLAYS} text overlays.`);
+  }
+  const textOverlays = raw.textOverlays.map(parseTextOverlay);
+  if (new Set(textOverlays.map((o) => o.id)).size !== textOverlays.length) {
+    fail("Two text overlays share the same id.");
+  }
+
+  return {
+    preset: raw.preset,
+    customWidth: Math.round(num(raw, "customWidth", 16, 7680)),
+    customHeight: Math.round(num(raw, "customHeight", 16, 7680)),
+    framing: oneOf(raw, "framing", ["fit", "fill"] as const),
+    trimStart,
+    trimEnd,
+    rotate: oneOf(raw, "rotate", [0, 90, 180, 270] as const),
+    keepAudio: bool(raw, "keepAudio"),
+    normalizeAudio: bool(raw, "normalizeAudio"),
+    speed: oneOf(raw, "speed", SPEED_STEPS),
+    volume: num(raw, "volume", 0, 200),
+    quality: num(raw, "quality", 18, 30),
+    format: oneOf(raw, "format", ["mp4", "webm", "mkv", "gif"] as const),
+    stabilization: bool(raw, "stabilization"),
+    denoise: bool(raw, "denoise"),
+    brightness: num(raw, "brightness", -1, 1),
+    contrast: num(raw, "contrast", 0, 2),
+    saturation: num(raw, "saturation", 0, 3),
+    sharpness: num(raw, "sharpness", 0, 3),
+    textOverlays,
+    version: RECIPE_VERSION,
+  };
+}
+
+function parseImageOverlay(raw: unknown): ImageOverlaySettings {
+  if (!isRecord(raw)) fail("The project has no image overlay settings.");
+  return {
+    position: oneOf(raw, "position", OVERLAY_POSITIONS),
+    size: Math.round(num(raw, "size", 10, 2000, "image overlay size")),
+    opacity: num(raw, "opacity", 0, 100, "image overlay opacity"),
+  };
+}
+
+function parseSource(raw: unknown): SourceInfo | null {
+  if (raw === null) return null;
+  if (!isRecord(raw)) fail("The source video description is not valid.");
+  if (typeof raw.name !== "string" || raw.name.length === 0 || raw.name.length > 255) {
+    fail("The source video name is not valid.");
+  }
+  if (typeof raw.type !== "string" || raw.type.length > 100) fail("The source video type is not valid.");
+  return {
+    name: raw.name,
+    type: raw.type,
+    size: num(raw, "size", 0, Number.MAX_SAFE_INTEGER, "source size"),
+    lastModified: num(raw, "lastModified", 0, Number.MAX_SAFE_INTEGER, "source date"),
+    duration: num(raw, "duration", 0, Number.MAX_SAFE_INTEGER, "source duration"),
+    width: num(raw, "width", 0, 100_000, "source width"),
+    height: num(raw, "height", 0, 100_000, "source height"),
+  };
+}
+
+/** Upgrades a raw document to `target`, one version at a time. */
+export function migrateProjectDocument(
+  doc: RawDocument,
+  migrations: Record<number, Migration> = MIGRATIONS,
+  target: number = PROJECT_SCHEMA_VERSION
+): RawDocument {
+  let version = doc.schemaVersion;
+  if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+    fail("The project file has no valid schema version.");
+  }
+  if (version > target) {
+    fail(
+      `This project was saved by a newer version of Reframe (schema ${version}). Reload the page to update, then try again.`
+    );
+  }
+  let current = doc;
+  while (version < target) {
+    const migrate = migrations[version];
+    if (!migrate) fail(`Projects from schema ${version} can no longer be opened.`);
+    current = migrate(current);
+    version += 1;
+    current = { ...current, schemaVersion: version };
+  }
+  return current;
+}
+
+export function parseProject(
+  input: unknown,
+  migrations: Record<number, Migration> = MIGRATIONS,
+  target: number = PROJECT_SCHEMA_VERSION
+): ParseResult {
+  try {
+    let raw = input;
+    if (typeof raw === "string") {
+      if (raw.length > MAX_PROJECT_FILE_BYTES) fail("The file is too large to be a Reframe project.");
+      try {
+        raw = JSON.parse(raw);
+      } catch {
+        fail("The file is not valid JSON.");
+      }
+    }
+    if (!isRecord(raw) || raw.format !== PROJECT_FORMAT) fail("This file is not a Reframe project.");
+
+    const fromVersion = raw.schemaVersion;
+    const doc = migrateProjectDocument(raw, migrations, target);
+    if (!isRecord(doc.edit)) fail("The project has no edit settings.");
+    const savedAt =
+      typeof doc.savedAt === "string" && !Number.isNaN(Date.parse(doc.savedAt))
+        ? doc.savedAt
+        : new Date(0).toISOString();
+
+    return {
+      ok: true,
+      migratedFrom: fromVersion === target ? null : (fromVersion as number),
+      project: {
+        format: PROJECT_FORMAT,
+        schemaVersion: target,
+        savedAt,
+        source: parseSource(doc.source ?? null),
+        edit: {
+          recipe: parseRecipe(doc.edit.recipe),
+          imageOverlay: parseImageOverlay(doc.edit.imageOverlay),
+        },
+      },
+    };
+  } catch (err) {
+    if (err instanceof ProjectError) return { ok: false, error: err.message };
+    return { ok: false, error: "The project file could not be read." };
+  }
+}
+
+export function createProjectDocument(
+  edit: EditState,
+  source: SourceInfo | null,
+  savedAt: Date
+): ProjectDocument {
+  return {
+    format: PROJECT_FORMAT,
+    schemaVersion: PROJECT_SCHEMA_VERSION,
+    savedAt: savedAt.toISOString(),
+    source,
+    edit: {
+      // Drop anything that only makes sense in this tab (e.g. a blob: font path).
+      recipe: {
+        ...edit.recipe,
+        textOverlays: edit.recipe.textOverlays.map(({ fontPath: _fontPath, ...rest }) => rest),
+      },
+      imageOverlay: { ...edit.imageOverlay },
+    },
+  };
+}
+
+export function serializeProject(doc: ProjectDocument): string {
+  return JSON.stringify(doc, null, 2);
+}
+
+export function sourceInfoFromFile(
+  file: File,
+  meta: { width: number; height: number; duration: number }
+): SourceInfo {
+  return {
+    name: file.name,
+    size: file.size,
+    type: file.type,
+    lastModified: file.lastModified,
+    duration: meta.duration,
+    width: meta.width,
+    height: meta.height,
+  };
+}
+
+/**
+ * Same name and byte size. `lastModified` is ignored because copying a file
+ * between folders or devices often changes it.
+ */
+export function matchesSource(source: SourceInfo, file: Pick<File, "name" | "size">): boolean {
+  return source.name === file.name && source.size === file.size;
+}
+
+/** Keeps trim points inside a video of `duration` seconds. */
+export function fitEditToDuration(edit: EditState, duration: number): EditState {
+  if (!(duration > 0)) return edit;
+  let { trimStart, trimEnd } = edit.recipe;
+  if (trimEnd !== null && trimEnd > duration) trimEnd = null;
+  if (trimStart >= (trimEnd ?? duration)) trimStart = 0;
+  if (trimStart === edit.recipe.trimStart && trimEnd === edit.recipe.trimEnd) return edit;
+  return { ...edit, recipe: { ...edit.recipe, trimStart, trimEnd } };
+}
+
+export function projectFileName(source: SourceInfo | null): string {
+  const base = source?.name.replace(/\.[^.]+$/, "") ?? "untitled";
+  const safe = base.replace(/[^A-Za-z0-9 _-]+/g, "").trim().slice(0, 60) || "untitled";
+  return `${safe}.reframe.json`;
+}
+
+export function toEditState(
+  recipe: Partial<EditState["recipe"]> & { soundOnCompletion?: boolean },
+  imageOverlay: ImageOverlaySettings = DEFAULT_IMAGE_OVERLAY
+): EditState {
+  const { soundOnCompletion: _sound, ...rest } = { ...DEFAULT_RECIPE, ...recipe };
+  return { recipe: rest, imageOverlay };
+}
+
+// ── On-device session record ────────────────────────────────────────────────
+// localStorage rather than IndexedDB: the record is a few KB, and a
+// synchronous write can be flushed reliably from `pagehide`.
+
+export function saveProjectRecord(storage: Pick<Storage, "setItem">, doc: ProjectDocument): boolean {
+  try {
+    storage.setItem(PROJECT_STORAGE_KEY, JSON.stringify(doc));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function loadProjectRecord(storage: Pick<Storage, "getItem" | "removeItem">): ProjectDocument | null {
+  let raw: string | null;
+  try {
+    raw = storage.getItem(PROJECT_STORAGE_KEY);
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+  const parsed = parseProject(raw);
+  if (parsed.ok) return parsed.project;
+  try {
+    storage.removeItem(PROJECT_STORAGE_KEY);
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+export function clearProjectRecord(storage: Pick<Storage, "removeItem">): void {
+  storage.removeItem(PROJECT_STORAGE_KEY);
+}
diff --git a/src/lib/tests/editHistory.test.ts b/src/lib/tests/editHistory.test.ts
new file mode 100644
index 000000000..6a132039e
--- /dev/null
+++ b/src/lib/tests/editHistory.test.ts
@@ -0,0 +1,194 @@
+import { describe, it, expect } from "vitest";
+import {
+  COALESCE_WINDOW_MS,
+  HISTORY_LIMIT,
+  coalesceKey,
+  createHistory,
+  deepEqual,
+  historyReducer,
+  recordEdit,
+  redo,
+  undo,
+  type EditHistory,
+  type EditState,
+} from "@/lib/editHistory";
+import { toEditState } from "@/lib/project";
+import { DEFAULT_RECIPE } from "@/lib/constants";
+import { createDefaultTextOverlay } from "@/lib/text-overlay";
+
+const base = toEditState(DEFAULT_RECIPE);
+
+function withRecipe(edit: EditState, patch: Partial<EditState["recipe"]>): EditState {
+  return { ...edit, recipe: { ...edit.recipe, ...patch } };
+}
+
+/** Applies a series of patches, each `gap` ms after the previous one. */
+function play(
+  history: EditHistory,
+  patches: Array<Partial<EditState["recipe"]>>,
+  gap: number,
+  start = 1_000
+): EditHistory {
+  return patches.reduce(
+    (h, patch, i) => recordEdit(h, withRecipe(h.present, patch), start + i * gap),
+    history
+  );
+}
+
+describe("edit history", () => {
+  it("records mixed edits and undoes them in reverse order", () => {
+    let h = createHistory(base);
+    h = play(h, [{ rotate: 90 }, { preset: "square-1-1" }, { trimStart: 2 }, { format: "webm" }], 2_000);
+    expect(h.past).toHaveLength(4);
+
+    h = undo(h);
+    expect(h.present.recipe.format).toBe("mp4");
+    expect(h.present.recipe.trimStart).toBe(2);
+    h = undo(h);
+    expect(h.present.recipe.trimStart).toBe(0);
+    h = undo(h);
+    expect(h.present.recipe.preset).toBe(DEFAULT_RECIPE.preset);
+    h = undo(h);
+    expect(h.present).toEqual(base);
+  });
+
+  it("survives repeated undo/redo cycles without drifting", () => {
+    let h = play(createHistory(base), [{ rotate: 90 }, { brightness: 0.5 }, { speed: 2 }], 2_000);
+    const end = h.present;
+    for (let i = 0; i < 5; i++) {
+      h = undo(undo(undo(h)));
+      expect(h.present).toEqual(base);
+      h = redo(redo(redo(h)));
+      expect(h.present).toEqual(end);
+    }
+    expect(h.past).toHaveLength(3);
+    expect(h.future).toHaveLength(0);
+  });
+
+  it("does nothing at either end of the history", () => {
+    const h = createHistory(base);
+    expect(undo(h)).toBe(h);
+    expect(redo(h)).toBe(h);
+
+    const one = play(h, [{ rotate: 180 }], 2_000);
+    expect(redo(one)).toBe(one);
+    const back = undo(one);
+    expect(undo(back)).toBe(back);
+  });
+
+  it("drops the redo stack when a new edit is made after undo", () => {
+    let h = play(createHistory(base), [{ rotate: 90 }, { rotate: 180 }], 2_000);
+    h = undo(h);
+    h = recordEdit(h, withRecipe(h.present, { framing: "fill" }), 10_000);
+    expect(h.future).toHaveLength(0);
+    expect(redo(h)).toBe(h);
+  });
+
+  it("never records a change that leaves the state as it was", () => {
+    const h = createHistory(base);
+    expect(recordEdit(h, withRecipe(base, {}), 1_000)).toBe(h);
+    expect(recordEdit(h, toEditState({ ...DEFAULT_RECIPE }), 1_000)).toBe(h);
+  });
+
+  it("collapses a continuous slider drag into one undo step", () => {
+    const drag = Array.from({ length: 200 }, (_, i) => ({ brightness: Math.round(i / 2) / 100 }));
+    const h = play(createHistory(base), drag, 16);
+    expect(h.past).toHaveLength(1);
+    expect(h.present.recipe.brightness).toBe(drag[drag.length - 1]!.brightness);
+    expect(undo(h).present.recipe.brightness).toBe(0);
+  });
+
+  it("starts a new step after the slider rests past the coalescing window", () => {
+    let h = play(createHistory(base), [{ volume: 90 }, { volume: 80 }], 16);
+    h = play(h, [{ volume: 70 }, { volume: 60 }], 16, 1_000 + COALESCE_WINDOW_MS + 500);
+    expect(h.past).toHaveLength(2);
+    expect(undo(h).present.recipe.volume).toBe(80);
+  });
+
+  it("starts a new step when a different control is moved", () => {
+    const h = play(createHistory(base), [{ brightness: 0.2 }, { contrast: 1.5 }, { brightness: 0.3 }], 16);
+    expect(h.past).toHaveLength(3);
+  });
+
+  it("removes the step entirely when a drag ends where it started", () => {
+    const h = play(createHistory(base), [{ saturation: 1.5 }, { saturation: 2 }, { saturation: 1 }], 16);
+    expect(h.past).toHaveLength(0);
+    expect(h.present).toEqual(base);
+  });
+
+  it("keeps rapid clicks on discrete controls as separate steps", () => {
+    const h = play(createHistory(base), [{ rotate: 90 }, { rotate: 180 }, { rotate: 270 }], 50);
+    expect(h.past).toHaveLength(3);
+  });
+
+  it("merges typing and dragging on one text overlay, but not adding overlays", () => {
+    const overlay = createDefaultTextOverlay();
+    let h = recordEdit(createHistory(base), withRecipe(base, { textOverlays: [overlay] }), 1_000);
+    const second = createDefaultTextOverlay();
+    h = recordEdit(h, withRecipe(h.present, { textOverlays: [overlay, second] }), 1_010);
+    expect(h.past).toHaveLength(2);
+
+    for (const [i, text] of ["H", "He", "Hel", "Hell", "Hello"].entries()) {
+      h = recordEdit(
+        h,
+        withRecipe(h.present, { textOverlays: [{ ...overlay, text }, second] }),
+        2_000 + i * 100
+      );
+    }
+    expect(h.past).toHaveLength(3);
+
+    const moved = h.present.recipe.textOverlays;
+    for (let i = 1; i <= 30; i++) {
+      h = recordEdit(
+        h,
+        withRecipe(h.present, { textOverlays: [moved[0]!, { ...second, x: 50 - i }] }),
+        5_000 + i * 16
+      );
+    }
+    expect(h.past).toHaveLength(4);
+    expect(undo(h).present.recipe.textOverlays[1]!.x).toBe(second.x);
+  });
+
+  it("is bounded and keeps the most recent steps", () => {
+    const edits = Array.from({ length: HISTORY_LIMIT + 25 }, (_, i) => ({
+      rotate: ([0, 90, 180, 270] as const)[(i + 1) % 4],
+      customWidth: 100 + i,
+    }));
+    let h = play(createHistory(base), edits, 2_000);
+    expect(h.past).toHaveLength(HISTORY_LIMIT);
+
+    let steps = 0;
+    while (h.past.length) {
+      h = undo(h);
+      steps++;
+    }
+    expect(steps).toBe(HISTORY_LIMIT);
+    // The oldest reachable state is the one just before the last 100 edits.
+    expect(h.present.recipe.customWidth).toBe(100 + 24);
+  });
+
+  it("includes image overlay settings in the snapshot", () => {
+    const moved: EditState = { ...base, imageOverlay: { ...base.imageOverlay, position: "top-left" } };
+    const h = recordEdit(createHistory(base), moved, 1_000);
+    expect(undo(h).present.imageOverlay.position).toBe("bottom-right");
+    expect(coalesceKey(base, moved)).toBeNull();
+  });
+
+  it("reducer reset starts a clean history from the derived state", () => {
+    let h = play(createHistory(base), [{ rotate: 90 }, { rotate: 180 }], 2_000);
+    h = historyReducer(h, { type: "reset", update: (prev) => withRecipe(prev, { trimStart: 0 }) });
+    expect(h.past).toHaveLength(0);
+    expect(h.future).toHaveLength(0);
+    expect(h.present.recipe.rotate).toBe(180);
+  });
+});
+
+describe("deepEqual", () => {
+  it("compares nested plain data and treats missing and undefined keys alike", () => {
+    expect(deepEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] })).toBe(true);
+    expect(deepEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 3 }] })).toBe(false);
+    expect(deepEqual({ a: 1, b: undefined }, { a: 1 })).toBe(true);
+    expect(deepEqual([1], { 0: 1 })).toBe(false);
+    expect(deepEqual(null, {})).toBe(false);
+  });
+});
diff --git a/src/lib/tests/project.test.ts b/src/lib/tests/project.test.ts
new file mode 100644
index 000000000..276f979c6
--- /dev/null
+++ b/src/lib/tests/project.test.ts
@@ -0,0 +1,259 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  MAX_PROJECT_FILE_BYTES,
+  MAX_TEXT_OVERLAYS,
+  PROJECT_FORMAT,
+  PROJECT_SCHEMA_VERSION,
+  PROJECT_STORAGE_KEY,
+  createProjectDocument,
+  fitEditToDuration,
+  loadProjectRecord,
+  matchesSource,
+  migrateProjectDocument,
+  parseProject,
+  projectFileName,
+  saveProjectRecord,
+  serializeProject,
+  toEditState,
+  type SourceInfo,
+} from "@/lib/project";
+import { DEFAULT_RECIPE } from "@/lib/constants";
+import { createDefaultTextOverlay } from "@/lib/text-overlay";
+import type { EditState } from "@/lib/editHistory";
+
+const source: SourceInfo = {
+  name: "holiday clip.mp4",
+  size: 24_000_000,
+  type: "video/mp4",
+  lastModified: 1_700_000_000_000,
+  duration: 42.5,
+  width: 1920,
+  height: 1080,
+};
+
+function sampleEdit(): EditState {
+  const overlay = { ...createDefaultTextOverlay(), text: "Day one", x: 30 };
+  return {
+    recipe: {
+      ...toEditState(DEFAULT_RECIPE).recipe,
+      preset: "square-1-1",
+      trimStart: 3,
+      trimEnd: 20,
+      rotate: 90,
+      brightness: 0.2,
+      format: "webm",
+      textOverlays: [overlay],
+    },
+    imageOverlay: { position: "top-left", size: 250, opacity: 60 },
+  };
+}
+
+function sampleJson(mutate?: (doc: any) => void): string {
+  const doc = JSON.parse(serializeProject(createProjectDocument(sampleEdit(), source, new Date(0))));
+  mutate?.(doc);
+  return JSON.stringify(doc);
+}
+
+function memoryStorage(initial: Record<string, string> = {}) {
+  const store = { ...initial };
+  return {
+    store,
+    getItem: vi.fn((k: string) => store[k] ?? null),
+    setItem: vi.fn((k: string, v: string) => {
+      store[k] = v;
+    }),
+    removeItem: vi.fn((k: string) => {
+      delete store[k];
+    }),
+  };
+}
+
+describe("project documents", () => {
+  it("round-trips the edit state and source without any media", () => {
+    const json = sampleJson();
+    expect(json.length).toBeLessThan(4_000);
+    const parsed = parseProject(json);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    expect(parsed.project.edit).toEqual(JSON.parse(json).edit);
+    expect(parsed.project.source).toEqual(source);
+    expect(parsed.project.schemaVersion).toBe(PROJECT_SCHEMA_VERSION);
+    expect(parsed.migratedFrom).toBeNull();
+    expect(JSON.parse(json)).not.toHaveProperty("edit.recipe.soundOnCompletion");
+  });
+
+  it("never writes or reads a font file path", () => {
+    const edit = sampleEdit();
+    edit.recipe.textOverlays[0]!.fontPath = "blob:http://localhost/abc";
+    const doc = createProjectDocument(edit, source, new Date(0));
+    expect(doc.edit.recipe.textOverlays[0]).not.toHaveProperty("fontPath");
+
+    const parsed = parseProject(
+      sampleJson((d) => {
+        d.edit.recipe.textOverlays[0].fontPath = "/etc/passwd':enable=1";
+      })
+    );
+    expect(parsed.ok && parsed.project.edit.recipe.textOverlays[0]).not.toHaveProperty("fontPath");
+  });
+
+  it.each([
+    ["not JSON", "{nope", "not valid JSON"],
+    ["a JSON array", "[]", "not a Reframe project"],
+    ["another app's JSON", JSON.stringify({ format: "other", schemaVersion: 1 }), "not a Reframe project"],
+    ["no schema version", sampleJson((d) => delete d.schemaVersion), "no valid schema version"],
+    ["a fractional version", sampleJson((d) => (d.schemaVersion = 1.5)), "no valid schema version"],
+    ["no edit settings", sampleJson((d) => delete d.edit), "no edit settings"],
+    ["an unknown preset", sampleJson((d) => (d.edit.recipe.preset = "x")), "preset"],
+    ["brightness out of range", sampleJson((d) => (d.edit.recipe.brightness = 7)), "brightness"],
+    ["a string number", sampleJson((d) => (d.edit.recipe.quality = "23")), "quality"],
+    ["a null number", sampleJson((d) => (d.edit.recipe.contrast = null)), "contrast"],
+    ["an unsupported speed", sampleJson((d) => (d.edit.recipe.speed = 3)), "speed"],
+    ["an unknown format", sampleJson((d) => (d.edit.recipe.format = "exe")), "format"],
+    ["trim end before start", sampleJson((d) => (d.edit.recipe.trimEnd = 1)), "trim end"],
+    ["a missing field", sampleJson((d) => delete d.edit.recipe.keepAudio), "keepAudio"],
+    ["an old recipe version", sampleJson((d) => (d.edit.recipe.version = 0)), "unsupported version"],
+    ["an unsafe font name", sampleJson((d) => (d.edit.recipe.textOverlays[0].fontFamily = "x':fontfile=/x")), "font name"],
+    ["a bad colour", sampleJson((d) => (d.edit.recipe.textOverlays[0].color = "red")), "colour"],
+    ["an unsafe overlay id", sampleJson((d) => (d.edit.recipe.textOverlays[0].id = "<img>")), "invalid id"],
+    ["overlay text too long", sampleJson((d) => (d.edit.recipe.textOverlays[0].text = "x".repeat(501))), "at most 500"],
+    ["duplicate overlay ids", sampleJson((d) => d.edit.recipe.textOverlays.push(d.edit.recipe.textOverlays[0])), "same id"],
+    ["a bad overlay position", sampleJson((d) => (d.edit.imageOverlay.position = "middle")), "position"],
+    ["a bad source", sampleJson((d) => (d.source = { name: "" })), "source video name"],
+  ])("rejects %s", (_label, input, message) => {
+    const parsed = parseProject(input);
+    expect(parsed.ok).toBe(false);
+    if (!parsed.ok) expect(parsed.error).toContain(message);
+  });
+
+  it("rejects too many text overlays", () => {
+    const parsed = parseProject(
+      sampleJson((d) => {
+        const one = d.edit.recipe.textOverlays[0];
+        d.edit.recipe.textOverlays = Array.from({ length: MAX_TEXT_OVERLAYS + 1 }, (_, i) => ({ ...one, id: `t${i}` }));
+      })
+    );
+    expect(parsed.ok).toBe(false);
+  });
+
+  it("rejects oversized input before parsing it", () => {
+    const parse = vi.spyOn(JSON, "parse");
+    const parsed = parseProject(" ".repeat(MAX_PROJECT_FILE_BYTES + 1));
+    expect(parsed.ok).toBe(false);
+    expect(parse).not.toHaveBeenCalled();
+    parse.mockRestore();
+  });
+
+  it("ignores unknown keys, including __proto__, instead of copying them", () => {
+    const json = sampleJson().replace(
+      '"recipe": {',
+      '"recipe": { "__proto__": { "polluted": true }, "constructor": 1, "extra": "x",'
+    );
+    const parsed = parseProject(json);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    expect(parsed.project.edit.recipe).not.toHaveProperty("extra");
+    expect(Object.getPrototypeOf(parsed.project.edit.recipe)).toBe(Object.prototype);
+    expect(({} as any).polluted).toBeUndefined();
+  });
+
+  it("accepts a project with no source and an unreadable savedAt", () => {
+    const parsed = parseProject(sampleJson((d) => ((d.source = null), (d.savedAt = "soon"))));
+    expect(parsed.ok).toBe(true);
+    if (parsed.ok) {
+      expect(parsed.project.source).toBeNull();
+      expect(parsed.project.savedAt).toBe(new Date(0).toISOString());
+    }
+  });
+});
+
+describe("schema migration", () => {
+  it("upgrades step by step through the migration table", () => {
+    // Simulates a future v3 that renamed imageOverlay → logo in v2 and back.
+    const migrations = {
+      1: vi.fn((doc: any) => ({ ...doc, edit: { ...doc.edit, logo: doc.edit.imageOverlay } })),
+      2: vi.fn((doc: any) => {
+        const { logo, ...edit } = doc.edit;
+        return { ...doc, edit: { ...edit, imageOverlay: logo } };
+      }),
+    };
+    const parsed = parseProject(sampleJson(), migrations, 3);
+    expect(migrations[1]).toHaveBeenCalledTimes(1);
+    expect(migrations[2]).toHaveBeenCalledTimes(1);
+    expect(parsed.ok).toBe(true);
+    if (parsed.ok) {
+      expect(parsed.migratedFrom).toBe(1);
+      expect(parsed.project.schemaVersion).toBe(3);
+      expect(parsed.project.edit.imageOverlay.position).toBe("top-left");
+    }
+  });
+
+  it("refuses projects from a newer version with a clear message", () => {
+    const parsed = parseProject(sampleJson((d) => (d.schemaVersion = PROJECT_SCHEMA_VERSION + 1)));
+    expect(parsed.ok).toBe(false);
+    if (!parsed.ok) expect(parsed.error).toContain("newer version of Reframe");
+  });
+
+  it("refuses a version with no migration path", () => {
+    expect(() => migrateProjectDocument({ format: PROJECT_FORMAT, schemaVersion: 1 }, {}, 2)).toThrow(
+      "can no longer be opened"
+    );
+  });
+
+  it("validates the migrated result, not just the input", () => {
+    const parsed = parseProject(sampleJson(), { 1: (doc) => ({ ...doc, edit: null }) }, 2);
+    expect(parsed.ok).toBe(false);
+  });
+});
+
+describe("session record storage", () => {
+  it("saves and loads the current project", () => {
+    const storage = memoryStorage();
+    const doc = createProjectDocument(sampleEdit(), source, new Date(1_000));
+    expect(saveProjectRecord(storage, doc)).toBe(true);
+    expect(loadProjectRecord(storage)).toEqual(JSON.parse(JSON.stringify(doc)));
+  });
+
+  it("reports a failed write instead of throwing (quota, private mode)", () => {
+    const storage = memoryStorage();
+    storage.setItem.mockImplementation(() => {
+      throw new DOMException("full", "QuotaExceededError");
+    });
+    expect(saveProjectRecord(storage, createProjectDocument(sampleEdit(), source, new Date()))).toBe(false);
+  });
+
+  it("returns nothing when storage can't be read", () => {
+    const storage = memoryStorage();
+    storage.getItem.mockImplementation(() => {
+      throw new DOMException("denied", "SecurityError");
+    });
+    expect(loadProjectRecord(storage)).toBeNull();
+  });
+
+  it("discards a corrupted or half-written record", () => {
+    const storage = memoryStorage({ [PROJECT_STORAGE_KEY]: '{"format":"reframe-project","sche' });
+    expect(loadProjectRecord(storage)).toBeNull();
+    expect(storage.store[PROJECT_STORAGE_KEY]).toBeUndefined();
+  });
+});
+
+describe("source matching and fitting", () => {
+  it("matches the same file by name and size, ignoring lastModified", () => {
+    expect(matchesSource(source, { name: source.name, size: source.size })).toBe(true);
+    expect(matchesSource(source, { name: source.name, size: source.size + 1 })).toBe(false);
+    expect(matchesSource(source, { name: "other.mp4", size: source.size })).toBe(false);
+  });
+
+  it("drops trim points that don't fit a shorter video", () => {
+    const edit = sampleEdit();
+    expect(fitEditToDuration(edit, 60)).toBe(edit);
+    expect(fitEditToDuration(edit, 10).recipe).toMatchObject({ trimStart: 3, trimEnd: null });
+    expect(fitEditToDuration(edit, 2).recipe).toMatchObject({ trimStart: 0, trimEnd: null });
+    expect(fitEditToDuration(edit, 0)).toBe(edit);
+  });
+
+  it("builds a safe file name", () => {
+    expect(projectFileName(source)).toBe("holiday clip.reframe.json");
+    expect(projectFileName({ ...source, name: "../../<x>.mov" })).toBe("x.reframe.json");
+    expect(projectFileName(null)).toBe("untitled.reframe.json");
+  });
+});