address review audit: persist canonical wallpaper, dedupe types, tighten edge cases

R1 — Persisted wallpaper is now always the canonical /wallpapers/wallpaperN.jpg
form, never the resolved file:// URL. Swatch clicks pass WALLPAPER_PATHS[i]
(the relative path) to onWallpaperChange; the resolved URL stays in
wallpaperPreviewUrls for rendering only. This prevents machine-specific paths
from being written into project JSON and avoids break-on-upgrade /
break-on-share regressions. Legacy projects carrying resolved file:// URLs are
rewritten by a new normalizer in normalizeProjectEditor:
file://…(/assets)?/wallpapers/wallpaperN.jpg → /wallpapers/wallpaperN.jpg.

R2 — resolveImageWallpaperUrl now catches anything getAssetPath throws
(UnsafeAssetPathError, AssetBaseUnavailableError) and rewraps as
BackgroundLoadError with the original as cause. Callers (videoExporter retry
loop, gifExporter catch, VideoEditor toast) only need one instanceof check and
users always see the translated errors.exportBackgroundLoadFailed toast.

R3 — src/vite-env.d.ts no longer duplicates Window.electronAPI. The interface
had drifted — renderer declaration was missing readBinaryFile, getPlatform,
revealInFolder, getShortcuts, saveShortcuts, hudOverlay*, countdown overlay
methods that electron-env.d.ts already declares. Removed the duplicate and
kept the triple-slash reference so the authoritative declaration is the one
in electron/electron-env.d.ts.

N1 — GRADIENT_RE accepts optional "repeating-" prefix so
repeating-linear/radial/conic-gradient values classify as gradients instead
of falling through to color.

N2 — displayBasename returns "(unknown)" sentinel for URLs without a
meaningful basename (file:///, bare /) instead of leaking the original string.

N3 — electron-builder.json5 extraResources block gets an inline comment
pointing at preload.ts:assetBaseDir so the bidirectional coupling is
discoverable from either file.

Tests: 54 unit tests pass (up from 35). New coverage for repeating
gradients, displayBasename sentinels, BackgroundLoadError cause wrapping,
legacy file:// wallpaper normalization (5 cases).

src/components/video-editor/SettingsPanel.tsx

@@ -321,7 +321,10 @@ export function SettingsPanel({
 	onWebcamSizePresetCommit,
 }: SettingsPanelProps) {
 	const t = useScopedT("settings");
-	const wallpaperPaths = useMemo(() => WALLPAPER_PATHS.map(resolveImageWallpaperUrl), []);
+	// Resolved URLs are for DOM rendering only (backgroundImage). The canonical
+	// `/wallpapers/wallpaperN.jpg` form in WALLPAPER_PATHS is what gets persisted
+	// on click — never the machine-specific file:// URL.
+	const wallpaperPreviewUrls = useMemo(() => WALLPAPER_PATHS.map(resolveImageWallpaperUrl), []);
 	const [customImages, setCustomImages] = useState<string[]>([]);
 	const fileInputRef = useRef<HTMLInputElement>(null);
 	const colorPalette = [
@@ -506,7 +509,7 @@ export function SettingsPanel({
 		setCustomImages((prev) => prev.filter((img) => img !== imageUrl));
 		// If the removed image was selected, clear selection
 		if (selected === imageUrl) {
-			onWallpaperChange(wallpaperPaths[0] || WALLPAPER_PATHS[0]);
+			onWallpaperChange(WALLPAPER_PATHS[0]);
 		}
 	};
 
@@ -1126,23 +1129,12 @@ export function SettingsPanel({
 												);
 											})}
 
-											{wallpaperPaths.map((path) => {
-												const isSelected = (() => {
-													if (!selected) return false;
-													if (selected === path) return true;
-													try {
-														const clean = (s: string) =>
-															s.replace(/^file:\/\//, "").replace(/^\//, "");
-														if (clean(selected).endsWith(clean(path))) return true;
-														if (clean(path).endsWith(clean(selected))) return true;
-													} catch {
-														// Best-effort comparison; fallback to strict match.
-													}
-													return false;
-												})();
+											{WALLPAPER_PATHS.map((canonicalPath, i) => {
+												const previewUrl = wallpaperPreviewUrls[i] ?? canonicalPath;
+												const isSelected = selected === canonicalPath;
 												return (
 													<div
-														key={path}
+														key={canonicalPath}
 														className={cn(
 															"aspect-square w-9 h-9 rounded-md border-2 overflow-hidden cursor-pointer transition-all duration-200 shadow-sm",
 															isSelected
@@ -1150,11 +1142,11 @@ export function SettingsPanel({
 																: "border-white/10 hover:border-[#34B27B]/40 opacity-80 hover:opacity-100 bg-white/5",
 														)}
 														style={{
-															backgroundImage: `url(${path})`,
+															backgroundImage: `url(${previewUrl})`,
 															backgroundSize: "cover",
 															backgroundPosition: "center",
 														}}
-														onClick={() => onWallpaperChange(path)}
+														onClick={() => onWallpaperChange(canonicalPath)}
 														role="button"
 													/>
 												);

src/components/video-editor/projectPersistence.test.ts

@@ -197,3 +197,43 @@ it("detects unsaved changes from differing snapshots", () => {
 	expect(hasProjectUnsavedChanges("same", "same")).toBe(false);
 	expect(hasProjectUnsavedChanges("current", "baseline")).toBe(true);
 });
+
+describe("wallpaper legacy normalization", () => {
+	it("rewrites resolved file:// resources paths from pre-fix projects", () => {
+		const normalized = normalizeProjectEditor({
+			wallpaper: "file:///opt/Openscreen/resources/assets/wallpapers/wallpaper5.jpg",
+		});
+		expect(normalized.wallpaper).toBe("/wallpapers/wallpaper5.jpg");
+	});
+
+	it("rewrites resolved file:// paths under the new resources/wallpapers layout", () => {
+		const normalized = normalizeProjectEditor({
+			wallpaper: "file:///opt/Openscreen/resources/wallpapers/wallpaper3.jpg",
+		});
+		expect(normalized.wallpaper).toBe("/wallpapers/wallpaper3.jpg");
+	});
+
+	it("rewrites unpackaged dev paths (public/wallpapers/…)", () => {
+		const normalized = normalizeProjectEditor({
+			wallpaper: "file:///home/user/project/public/wallpapers/wallpaper1.jpg",
+		});
+		expect(normalized.wallpaper).toBe("/wallpapers/wallpaper1.jpg");
+	});
+
+	it("leaves canonical relative paths untouched", () => {
+		const normalized = normalizeProjectEditor({ wallpaper: "/wallpapers/wallpaper2.jpg" });
+		expect(normalized.wallpaper).toBe("/wallpapers/wallpaper2.jpg");
+	});
+
+	it("leaves data URIs untouched", () => {
+		const dataUri = "data:image/png;base64,AAA";
+		expect(normalizeProjectEditor({ wallpaper: dataUri }).wallpaper).toBe(dataUri);
+	});
+
+	it("leaves colors and gradients untouched", () => {
+		expect(normalizeProjectEditor({ wallpaper: "#1a1a2e" }).wallpaper).toBe("#1a1a2e");
+		expect(
+			normalizeProjectEditor({ wallpaper: "linear-gradient(90deg, red, blue)" }).wallpaper,
+		).toBe("linear-gradient(90deg, red, blue)");
+	});
+});

src/components/video-editor/projectPersistence.ts

@@ -40,6 +40,17 @@ import {
 
 const VALID_BLUR_SHAPES = new Set(["rectangle", "oval", "freehand"] as const);
 
+// Pre-fix projects could persist resolved file:// URLs (machine-specific) instead
+// of the canonical `/wallpapers/wallpaperN.jpg` form. Rewrite those on load so
+// they resolve against the current install's resources directory.
+const LEGACY_FILE_WALLPAPER_RE = /^file:\/\/.*?\/(?:assets\/)?wallpapers\/(wallpaper\d+\.jpg)$/i;
+
+function normalizeWallpaperValue(value: string): string {
+	const match = LEGACY_FILE_WALLPAPER_RE.exec(value);
+	if (!match) return value;
+	return `/wallpapers/${match[1]}`;
+}
+
 export { WALLPAPER_PATHS };
 
 export const PROJECT_VERSION = 2;
@@ -422,7 +433,10 @@ export function normalizeProjectEditor(editor: Partial<ProjectEditorState>): Pro
 	const cropHeight = clamp(rawCropHeight, 0.01, 1 - cropY);
 
 	return {
-		wallpaper: typeof editor.wallpaper === "string" ? editor.wallpaper : DEFAULT_WALLPAPER,
+		wallpaper:
+			typeof editor.wallpaper === "string"
+				? normalizeWallpaperValue(editor.wallpaper)
+				: DEFAULT_WALLPAPER,
 		shadowIntensity: typeof editor.shadowIntensity === "number" ? editor.shadowIntensity : 0,
 		showBlur: typeof editor.showBlur === "boolean" ? editor.showBlur : false,
 		motionBlurAmount: isFiniteNumber(editor.motionBlurAmount)