feat(record-tour): save and load tour setup as a JSON file (#898)

* feat(record-tour): save and load tour setup as a JSON file

The Record Map Tour panel could only export the recorded video; the
underlying keyframes, durations, and frame rate were lost when the panel
closed, so a tour could not be paused, refined, or reused.

Add a Save setup / Load setup pair near the top of the panel. Save writes
the keyframes and FPS to a JSON file; Load reads one back, repopulating the
keyframe list and frame rate (fresh ids are minted so reloaded rows never
collide). The serializer and parser share the FPS/segment bounds with the
controls, so a hand-edited or stale file is clamped to the supported range,
and a malformed file surfaces a translated error instead of crashing.

Closes #897

* Address Claude review feedback

- parseTourConfig now rejects a config written by a newer, incompatible
  format version (was stamped on save but never read back); a missing or
  older version is still accepted.
- Clamp zoom/pitch/bearing into MapLibre's supported ranges on load to match
  the documented validation contract (only durationMs/fps were clamped).
- Rename the config file default to "map-tour-setup" so it is genuinely
  distinct from the video name, and fix the misleading comment.
- Grammar: "Saved setup as {{name}}".
- Add tests for camera clamping and newer-version rejection.

* Address Claude review feedback (round 2)

- Wrap bearing onto (-180, 180] instead of clamping, so a hand-edited 270
  maps to -90 (west) rather than 180 (south).
- Reject a keyframe whose latitude is outside ±90 (a real out-of-range
  coordinate), matching the validation the comment claims.
- Cap parsed keyframes at 500 so a crafted/huge file can't make the parser
  allocate a giant array and loop createId() over it.
- handleLoadConfig: only clear the result banner once a file is actually
  chosen, so cancelling the picker no longer wipes a prior "Saved setup…".
- Confirm before loading when the panel already has keyframes, so a misclick
  on "Load setup" can't silently discard in-progress work (new confirmLoad
  string).
- Tests for bearing wrap, latitude rejection, and the keyframe cap.

* Address CodeRabbit review feedback

- Guard the raw config text length (1 MB) before JSON.parse, so a pathological
  file is rejected without being fully allocated first (completes the
  MAX_KEYFRAMES DoS hardening, which only ran post-parse).

* Address Claude review feedback (round 3)

- handleSaveConfig now clears the result banner only after the file is
  actually written, matching handleLoadConfig, so cancelling the save dialog
  no longer wipes a prior "Saved setup…" message.
- handleLoadConfig short-circuits only on a cancelled picker (null result);
  an empty file now flows through to parseTourConfig so it surfaces a real
  error instead of silently doing nothing.

* Address Claude review feedback (round 4)

- Clamp each keyframe's durationMs on serialize too, mirroring parseKeyframe,
  so save/load is symmetric and a programmatic caller can't persist an
  out-of-range duration.
- Tighten the version gate to also reject a present-but-non-numeric version
  (e.g. "2"); a missing version is still accepted as legacy v1. Add tests for
  the string-version rejection and the missing-version acceptance.

* Address Claude review feedback (round 5)

- Fix openLocalDataFileWithFallback hanging forever when the browser file
  picker is dismissed without a selection: the input only had an onchange
  handler (which never fires on cancel), so handleLoadConfig's await never
  settled. Add a "cancel" listener that resolves null, matching the existing
  pickImageFilesWithFallback pattern.
- Assert the missing-fps fallback to DEFAULT_FPS in the parse test.

* Address Claude review feedback (round 6)

- Tighten the version gate: a present version must be an integer in
  [1, TOUR_CONFIG_VERSION], so an unrecognized 0 or negative value is now
  rejected too (only a missing version still defaults to v1). Add a test for
  the version-below-1 case.

Author: giswqs

apps/geolibre-desktop/src/components/layout/RecordTourDialog.tsx

@@ -5,6 +5,8 @@ import {
   ArrowUp,
   Camera,
   Circle,
+  Download,
+  FolderOpen,
   GripHorizontal,
   MapPin,
   Plus,
@@ -15,11 +17,23 @@ import {
 } from "lucide-react";
 import { useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
-import { saveBinaryFileWithFallback } from "../../lib/tauri-io";
 import {
+  openLocalDataFileWithFallback,
+  saveBinaryFileWithFallback,
+  saveTextFileWithFallback,
+} from "../../lib/tauri-io";
+import {
+  DEFAULT_FPS,
+  DEFAULT_SEGMENT_SECONDS,
   estimateTourDurationMs,
   isTourRecordingSupported,
+  MAX_FPS,
+  MAX_SEGMENT_SECONDS,
+  MIN_FPS,
+  MIN_SEGMENT_SECONDS,
+  parseTourConfig,
   recordTour,
+  serializeTourConfig,
   type TourKeyframe,
   TourRecordingUnsupportedError,
 } from "../../lib/tour-recorder";
@@ -35,12 +49,10 @@ interface RecordTourDialogProps {
 type Status = "idle" | "recording" | "ready" | "saving";
 
 const DEFAULT_FILE_NAME = "map-tour";
-const DEFAULT_FPS = 30;
-const MIN_FPS = 10;
-const MAX_FPS = 60;
-const DEFAULT_SEGMENT_SECONDS = 4;
-const MIN_SEGMENT_SECONDS = 0.5;
-const MAX_SEGMENT_SECONDS = 30;
+// Default leaf name for the saved tour *configuration* (the editable JSON),
+// distinct from the recorded video's name so the two exports are easy to tell
+// apart in a downloads folder.
+const DEFAULT_CONFIG_FILE_NAME = "map-tour-setup";
 
 function createId(): string {
   if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
@@ -92,6 +104,9 @@ export function RecordTourDialog({
   const [error, setError] = useState<string | null>(null);
   const [savedName, setSavedName] = useState<string | null>(null);
   const [saveCancelled, setSaveCancelled] = useState(false);
+  // Outcome banner for the configuration save/load actions (kept separate from
+  // the video save banner so the two messages never clobber each other).
+  const [configMessage, setConfigMessage] = useState<string | null>(null);
   // The finished recording, held until the user names it and clicks Save.
   const [pendingBlob, setPendingBlob] = useState<Blob | null>(null);
   const [fileName, setFileName] = useState(DEFAULT_FILE_NAME);
@@ -126,6 +141,7 @@ export function RecordTourDialog({
   const clearResultMessages = () => {
     setSavedName(null);
     setSaveCancelled(false);
+    setConfigMessage(null);
     setError(null);
   };
 
@@ -357,6 +373,69 @@ export function RecordTourDialog({
     setStatus("idle");
   };
 
+  // Export the editable tour setup (keyframes, durations, FPS) as a JSON file so
+  // it can be reloaded and refined later, independent of the recorded video.
+  const handleSaveConfig = async () => {
+    if (keyframes.length === 0) return;
+    try {
+      const content = serializeTourConfig(keyframes, fps);
+      const fileType = t("recordTour.configFileType");
+      const name = await saveTextFileWithFallback(content, {
+        defaultName: `${DEFAULT_CONFIG_FILE_NAME}.json`,
+        filters: [{ name: fileType, extensions: ["json"] }],
+        browserTypes: [
+          { description: fileType, accept: { "application/json": [".json"] } },
+        ],
+        mimeType: "application/json",
+      });
+      // Cancelling the dialog returns null and is a no-op, so only clear a prior
+      // result banner once the file is actually written.
+      if (name) {
+        clearResultMessages();
+        setConfigMessage(t("recordTour.configSaved", { name }));
+      }
+    } catch (err) {
+      console.warn("Tour configuration save failed", err);
+      clearResultMessages();
+      setError(t("recordTour.configSaveError"));
+    }
+  };
+
+  // Load a previously saved tour setup, replacing the current keyframe list and
+  // frame rate. Fresh ids are minted so reloaded rows never collide. A bad file
+  // throws a parse error, surfaced as a translated message rather than a crash.
+  const handleLoadConfig = async () => {
+    // Loading replaces the whole tour, so confirm first when there is existing
+    // work a misclick would otherwise wipe.
+    if (keyframes.length > 0 && !window.confirm(t("recordTour.confirmLoad"))) {
+      return;
+    }
+    try {
+      const fileType = t("recordTour.configFileType");
+      const result = await openLocalDataFileWithFallback({
+        filters: [{ name: fileType, extensions: ["json"] }],
+        accept: ".json,application/json",
+        readText: true,
+      });
+      // Only a null result means the picker was cancelled (a no-op). An empty
+      // file still flows through so parseTourConfig surfaces a real error rather
+      // than silently doing nothing after the user explicitly chose a file.
+      if (result == null) return;
+      clearResultMessages();
+      const config = parseTourConfig(result.text ?? "");
+      setKeyframes(config.keyframes.map((kf) => ({ ...kf, id: createId() })));
+      setFps(config.fps);
+      setFpsText(String(config.fps));
+      setConfigMessage(
+        t("recordTour.configLoaded", { count: config.keyframes.length }),
+      );
+    } catch (err) {
+      console.warn("Tour configuration load failed", err);
+      clearResultMessages();
+      setError(t("recordTour.configLoadError"));
+    }
+  };
+
   const totalSeconds = estimateTourDurationMs(keyframes) / 1000;
   const canRecord =
     keyframes.length >= 2 && RECORDING_SUPPORTED && status === "idle";
@@ -411,6 +490,33 @@ export function RecordTourDialog({
           </p>
         )}
 
+        {/* Save / load the editable tour setup so work can be paused, resumed,
+            and reused across sessions (independent of the recorded video). */}
+        <div className="flex items-center gap-2">
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            className="flex-1"
+            disabled={editingFrozen}
+            onClick={handleLoadConfig}
+          >
+            <FolderOpen className="mr-1.5 h-3.5 w-3.5" />
+            {t("recordTour.loadConfig")}
+          </Button>
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            className="flex-1"
+            disabled={editingFrozen || keyframes.length === 0}
+            onClick={handleSaveConfig}
+          >
+            <Download className="mr-1.5 h-3.5 w-3.5" />
+            {t("recordTour.saveConfig")}
+          </Button>
+        </div>
+
         <div className="flex items-center justify-between gap-2">
           <Button
             type="button"
@@ -510,6 +616,11 @@ export function RecordTourDialog({
             {t("recordTour.saveCancelled")}
           </p>
         )}
+        {configMessage && (
+          <p className="text-sm text-emerald-600 dark:text-emerald-400">
+            {configMessage}
+          </p>
+        )}
         {error && <p className="text-sm text-destructive">{error}</p>}
 
         {busy ? (

apps/geolibre-desktop/src/i18n/locales/en.json

@@ -479,6 +479,15 @@
     "hint": "Pan and zoom the map, then capture each view. The map stays interactive while this panel is open.",
     "unsupported": "This browser cannot record the map canvas. Try a recent version of Chrome, Edge, or Firefox.",
     "addView": "Add current view",
+    "loadConfig": "Load setup",
+    "saveConfig": "Save setup",
+    "confirmLoad": "Replace the current keyframes with the loaded setup?",
+    "configFileType": "Tour Configuration",
+    "configSaved": "Saved setup as {{name}}",
+    "configLoaded_one": "Loaded setup with {{count}} keyframe.",
+    "configLoaded_other": "Loaded setup with {{count}} keyframes.",
+    "configSaveError": "Could not save the tour setup. Please try again.",
+    "configLoadError": "Could not load the tour setup. The file may be invalid.",
     "keyframeCount_one": "{{count}} keyframe",
     "keyframeCount_other": "{{count}} keyframes",
     "empty": "Pan and zoom the map to a starting view, then add it as the first keyframe. Add at least two keyframes to record a tour.",

apps/geolibre-desktop/src/lib/tauri-io.ts

@@ -1118,6 +1118,9 @@ export async function openLocalDataFileWithFallback(
         reject(error);
       }
     };
+    // Resolve (rather than hang) when the dialog is dismissed without a pick;
+    // `change` never fires on cancel, so without this the Promise never settles.
+    input.addEventListener("cancel", () => resolve(null));
     input.click();
   });
 }