beauticode-dsh 1.0.7 → 1.0.13

package/vendor/core/background-store.js

@@ -4,11 +4,11 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import crypto from "node:crypto";
 import { COMMIT_MARKER_NAME, COMMIT_MARKER_STALE_MS, DEFAULT_VIDEO_BASENAME, MANIFEST_NAME, SAVED_META_NAME, SCHEMA_ID, } from "./constants.js";
 import { assertSafeBasename, MediaValidationError, validateImageFile, validateVideoFile, } from "./media-validation.js";
-import { copyFileAtomic, emptyDir, ensureDataLayout, isPathInsideRoot, linkOrCopyFileAtomic, resolveDataPaths, rmrf, } from "./paths.js";
+import { copyFileAtomic, emptyDir, ensureDataLayout, isPathInsideRoot, resolveDataPaths, rmrf, } from "./paths.js";
 import { normalizeBackgroundEffects } from "./types.js";
+import { isLocalBackgroundSource, managedPrimaryFile, resolveBackgroundImagePath, resolveBackgroundVideoPath, } from "./media-source.js";
 import { BUNDLED_GALLERY_THEME_ID, } from "./bundled-gallery.js";
 import { acquireFileLock } from "./file-lock.js";
-import { normalizeSavedThemeSource, } from "./skin-pack.js";
 /** 1×1 transparent PNG — poster when video apply has no prior image. */
 const SYNTHETIC_POSTER_PNG = Buffer.from("89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c63000100000500010d0a2db40000000049454e44ae426082", "hex");
 const COMMIT_JOURNAL_NAME = ".beauticode-commit.json";
@@ -41,9 +41,33 @@ function isManifest(value) {
     const b = v.background;
     if (b.type !== "image" && b.type !== "video")
         return false;
-    if (typeof b.image !== "string")
+    if (b.image != null && typeof b.image !== "string")
         return false;
-    if (b.type === "video" && typeof b.video !== "string")
+    if (b.video != null && typeof b.video !== "string")
+        return false;
+    if (b.source != null) {
+        if (!b.source || typeof b.source !== "object")
+            return false;
+        const source = b.source;
+        if (source.kind === "local") {
+            if (typeof source.path !== "string" || !path.isAbsolute(source.path))
+                return false;
+        }
+        else if (source.kind === "managed") {
+            if (typeof source.file !== "string")
+                return false;
+        }
+        else {
+            return false;
+        }
+    }
+    // Legacy v1 manifests have no source field. New local image manifests do
+    // not need an active copy; video manifests still retain a managed poster.
+    if (!b.source && b.type === "image" && typeof b.image !== "string")
+        return false;
+    if (!b.source && b.type === "video" && typeof b.video !== "string")
+        return false;
+    if (b.type === "video" && typeof b.image !== "string")
         return false;
     if (b.effects != null && !normalizeBackgroundEffects(b.effects))
         return false;
@@ -56,26 +80,27 @@ export class BackgroundStore {
     maxSavedBytes;
     bundledThemes;
     #runtimeSessionName = `session-${process.pid}-${crypto.randomUUID()}`;
-    #runtimeMediaCache = new Map();
+    #runtimeVideoCache = new Map();
     #writeChain = Promise.resolve();
     #writeContext = new AsyncLocalStorage();
     constructor(opts = {}) {
         this.paths = resolveDataPaths(opts.root);
         this.commitMarkerStaleMs = opts.commitMarkerStaleMs ?? COMMIT_MARKER_STALE_MS;
         this.maxSavedThemes = opts.maxSavedThemes ?? 20;
-        this.maxSavedBytes = opts.maxSavedBytes ?? 8 * 1024 * 1024 * 1024;
+        this.maxSavedBytes = opts.maxSavedBytes ?? 2 * 1024 * 1024 * 1024;
         this.bundledThemes = normalizeBundledThemes(opts.bundledThemes);
     }
     async init() {
         await ensureDataLayout(this.paths);
         const markerFresh = await this.#isCommitMarkerFresh();
-        if (!markerFresh || this.#writeContext.getStore()) {
-            await this.#recoverInterruptedCommit();
-            await fs.mkdir(this.paths.activeDir, { recursive: true });
-        }
-        else {
+        // A fresh marker always belongs to a live transaction. Readers and
+        // re-entrant writer calls must leave its journal/staging tree untouched;
+        // recovery is only safe after the marker becomes stale or disappears.
+        if (markerFresh) {
             return;
         }
+        await this.#recoverInterruptedCommit();
+        await fs.mkdir(this.paths.activeDir, { recursive: true });
         const manifestPath = path.join(this.paths.activeDir, MANIFEST_NAME);
         try {
             await fs.access(manifestPath);
@@ -202,10 +227,15 @@ export class BackgroundStore {
             throw new MediaValidationError("Active background manifest failed schema checks.");
         }
         if (parsed.background) {
-            assertSafeBasename(parsed.background.image, "background.image");
+            if (parsed.background.image) {
+                assertSafeBasename(parsed.background.image, "background.image");
+            }
             if (parsed.background.video) {
                 assertSafeBasename(parsed.background.video, "background.video");
             }
+            if (parsed.background.source?.kind === "managed") {
+                assertSafeBasename(parsed.background.source.file, "background.source.file");
+            }
         }
         return parsed;
     }
@@ -213,14 +243,14 @@ export class BackgroundStore {
         const m = await this.readActiveManifest();
         if (!m.background)
             return null;
-        return path.join(this.paths.activeDir, m.background.image);
+        return resolveBackgroundImagePath(this.paths.activeDir, m.background);
     }
     async activeVideoPath() {
         const m = await this.readActiveManifest();
-        if (!m.background || m.background.type !== "video" || !m.background.video) {
+        if (!m.background || m.background.type !== "video") {
             return null;
         }
-        return path.join(this.paths.activeDir, m.background.video);
+        return resolveBackgroundVideoPath(this.paths.activeDir, m.background);
     }
     /**
      * Serialize mutations. Prevents concurrent stage/commit interleaving
@@ -243,99 +273,68 @@ export class BackgroundStore {
         return run;
     }
     /**
-     * Copy the active still to a renderer-only path outside `active`.
-     *
-     * Serving `active/poster.png` keeps that directory open on Windows, so the
-     * next atomic active-directory rotation fails with EPERM. The detached copy
-     * matches the video runtime path.
-     */
-    async prepareRuntimeImage(manifest) {
-        if (!manifest.background?.image)
-            return null;
-        return this.#prepareRuntimeMedia({
-            generation: manifest.generation,
-            kind: "image",
-            sourceName: manifest.background.image,
-            ext: path.extname(manifest.background.image) || ".png",
-            validate: (filePath) => validateImageFile(filePath),
-        });
-    }
-    /**
-     * Copy the active video to a renderer-only path outside `active`.
-     *
-     * Chromium keeps a Windows file handle for videos attached through
-     * DOM.setFileInputFiles. Pointing it at `active/background.mp4` prevents the
-     * next atomic active-directory rotation with EPERM. The detached copy keeps
-     * renderer lifetime independent from the disk transaction.
+     * Resolve the renderer video path. Managed videos get a detached runtime
+     * copy because Chromium can keep an active-directory handle open. Local
+     * references already live outside active, so returning the source path avoids
+     * both the active copy and the runtime copy.
      */
     async prepareRuntimeVideo(manifest) {
-        if (manifest.background?.type !== "video" ||
-            !manifest.background.video) {
-            return null;
-        }
-        return this.#prepareRuntimeMedia({
-            generation: manifest.generation,
-            kind: "video",
-            sourceName: manifest.background.video,
-            ext: ".mp4",
-            validate: (filePath) => validateVideoFile(filePath),
-        });
-    }
-    async #prepareRuntimeMedia(opts) {
         return this.#withWriteLock(async () => {
+            if (manifest.background?.type !== "video") {
+                return null;
+            }
             await this.init();
-            const cacheKey = `${opts.kind}:${opts.generation}`;
-            const cached = this.#runtimeMediaCache.get(cacheKey);
+            const source = resolveBackgroundVideoPath(this.paths.activeDir, manifest.background);
+            if (!source)
+                return null;
+            if (isLocalBackgroundSource(manifest.background)) {
+                await validateVideoFile(source, { mode: "fast" });
+                return source;
+            }
+            const cached = this.#runtimeVideoCache.get(manifest.generation);
             if (cached) {
                 try {
-                    await opts.validate(cached);
+                    await validateVideoFile(cached);
                     return cached;
                 }
                 catch {
-                    this.#runtimeMediaCache.delete(cacheKey);
+                    this.#runtimeVideoCache.delete(manifest.generation);
                 }
             }
-            const source = path.join(this.paths.activeDir, opts.sourceName);
-            const validated = await opts.validate(source);
-            const sessionDir = await this.#ensureRuntimeSessionDir();
-            const safeExt = opts.ext.toLowerCase().startsWith(".")
-                ? opts.ext.toLowerCase()
-                : `.${opts.ext}`;
-            const destination = path.join(sessionDir, `${opts.kind}-${opts.generation}-${validated.identity.slice(0, 16)}${safeExt}`);
+            const validated = await validateVideoFile(source);
+            const sessionDir = path.join(this.paths.runtimeMediaDir, this.#runtimeSessionName);
+            if (!isPathInsideRoot(this.paths.runtimeMediaDir, sessionDir)) {
+                throw new MediaValidationError("Runtime media path escaped runtime-media root.");
+            }
+            const runtimeRootStat = await fs.lstat(this.paths.runtimeMediaDir);
+            if (!runtimeRootStat.isDirectory() ||
+                runtimeRootStat.isSymbolicLink()) {
+                throw new MediaValidationError("Runtime media root must be a real directory.");
+            }
+            await fs.mkdir(sessionDir, { recursive: true });
+            const sessionStat = await fs.lstat(sessionDir);
+            if (!sessionStat.isDirectory() || sessionStat.isSymbolicLink()) {
+                throw new MediaValidationError("Runtime media session must be a real directory.");
+            }
+            const [realRuntimeRoot, realSessionDir] = await Promise.all([
+                fs.realpath(this.paths.runtimeMediaDir),
+                fs.realpath(sessionDir),
+            ]);
+            if (!isPathInsideRoot(realRuntimeRoot, realSessionDir)) {
+                throw new MediaValidationError("Runtime media session escaped runtime-media root.");
+            }
+            const destination = path.join(sessionDir, `video-${manifest.generation}-${validated.identity.slice(0, 16)}.mp4`);
             await copyFileAtomic(validated.filePath, destination);
-            const copied = await opts.validate(destination);
+            const copied = await validateVideoFile(destination);
             if (copied.identity !== validated.identity) {
                 await fs.rm(destination, { force: true }).catch(() => { });
-                throw new MediaValidationError(`Runtime ${opts.kind} copy failed its identity check.`);
+                throw new MediaValidationError("Runtime video copy failed its identity check.");
             }
-            this.#runtimeMediaCache.set(cacheKey, destination);
-            await this.#pruneRuntimeMediaUnlocked([...this.#runtimeMediaCache.values()]);
+            this.#runtimeVideoCache.set(manifest.generation, destination);
+            await this.#pruneRuntimeMediaUnlocked(destination);
             return destination;
         });
     }
-    async #ensureRuntimeSessionDir() {
-        const sessionDir = path.join(this.paths.runtimeMediaDir, this.#runtimeSessionName);
-        if (!isPathInsideRoot(this.paths.runtimeMediaDir, sessionDir)) {
-            throw new MediaValidationError("Runtime media path escaped runtime-media root.");
-        }
-        const runtimeRootStat = await fs.lstat(this.paths.runtimeMediaDir);
-        if (!runtimeRootStat.isDirectory() || runtimeRootStat.isSymbolicLink()) {
-            throw new MediaValidationError("Runtime media root must be a real directory.");
-        }
-        await fs.mkdir(sessionDir, { recursive: true });
-        const sessionStat = await fs.lstat(sessionDir);
-        if (!sessionStat.isDirectory() || sessionStat.isSymbolicLink()) {
-            throw new MediaValidationError("Runtime media session must be a real directory.");
-        }
-        const [realRuntimeRoot, realSessionDir] = await Promise.all([
-            fs.realpath(this.paths.runtimeMediaDir),
-            fs.realpath(sessionDir),
-        ]);
-        if (!isPathInsideRoot(realRuntimeRoot, realSessionDir)) {
-            throw new MediaValidationError("Runtime media session escaped runtime-media root.");
-        }
-        return sessionDir;
-    }
     /**
      * Best-effort cleanup. Locked stale files are retained and retried on the
      * next apply/start instead of turning successful theme switching into an
@@ -344,15 +343,14 @@ export class BackgroundStore {
     async pruneRuntimeMedia(keepPath = null) {
         await this.#withWriteLock(async () => {
             await this.init();
-            const keep = (Array.isArray(keepPath) ? keepPath : [keepPath]).filter((value) => typeof value === "string" && value.length > 0);
-            await this.#pruneRuntimeMediaUnlocked(keep);
+            await this.#pruneRuntimeMediaUnlocked(keepPath);
         });
     }
-    async #pruneRuntimeMediaUnlocked(keepPaths) {
+    async #pruneRuntimeMediaUnlocked(keepPath) {
         const runtimeRoot = path.resolve(this.paths.runtimeMediaDir);
-        const keep = new Set(keepPaths
-            .filter((value) => isPathInsideRoot(runtimeRoot, value))
-            .map((value) => path.resolve(value)));
+        const keep = keepPath && isPathInsideRoot(runtimeRoot, keepPath)
+            ? path.resolve(keepPath)
+            : null;
         let sessions;
         try {
             sessions = await fs.readdir(runtimeRoot);
@@ -366,8 +364,7 @@ export class BackgroundStore {
             const sessionDir = path.join(runtimeRoot, name);
             if (!isPathInsideRoot(runtimeRoot, sessionDir))
                 continue;
-            const keepInSession = [...keep].some((file) => isPathInsideRoot(sessionDir, file));
-            if (!keepInSession) {
+            if (!keep || !isPathInsideRoot(sessionDir, keep)) {
                 await rmrf(sessionDir).catch(() => { });
                 continue;
             }
@@ -380,15 +377,15 @@ export class BackgroundStore {
             }
             for (const file of files) {
                 const candidate = path.resolve(sessionDir, file);
-                if (keep.has(candidate) || !isPathInsideRoot(sessionDir, candidate)) {
+                if (candidate === keep || !isPathInsideRoot(sessionDir, candidate)) {
                     continue;
                 }
                 await fs.rm(candidate, { recursive: true, force: true }).catch(() => { });
             }
         }
-        for (const [key, cached] of this.#runtimeMediaCache) {
-            if (!keep.has(path.resolve(cached))) {
-                this.#runtimeMediaCache.delete(key);
+        for (const [generation, cached] of this.#runtimeVideoCache) {
+            if (path.resolve(cached) !== keep) {
+                this.#runtimeVideoCache.delete(generation);
             }
         }
     }
@@ -411,14 +408,7 @@ export class BackgroundStore {
             await emptyDir(dir);
             await this.#writeJsonAtomic(path.join(dir, MANIFEST_NAME), manifest);
             if (manifest.background) {
-                const imgSrc = path.join(this.paths.activeDir, manifest.background.image);
-                const imgDst = path.join(dir, manifest.background.image);
-                await linkOrCopyFileAtomic(imgSrc, imgDst);
-                if (manifest.background.video) {
-                    const vSrc = path.join(this.paths.activeDir, manifest.background.video);
-                    const vDst = path.join(dir, manifest.background.video);
-                    await linkOrCopyFileAtomic(vSrc, vDst);
-                }
+                await this.#copyManagedBackgroundFiles(this.paths.activeDir, dir, manifest.background);
             }
             return { id, dir, manifest };
         });
@@ -460,20 +450,45 @@ export class BackgroundStore {
             try {
                 let background = null;
                 if (input.type === "image") {
-                    const image = await validateImageFile(input.imagePath);
-                    // Keep extension from source when it's an allowed one.
-                    const basename = `poster${image.extension === ".jpeg" ? ".jpg" : image.extension}`;
-                    assertSafeBasename(basename, "image");
-                    await copyFileAtomic(image.filePath, path.join(stagingDir, basename));
-                    background = { type: "image", image: basename };
-                    const effects = normalizeBackgroundEffects(input.effects);
-                    if (effects)
-                        background.effects = effects;
+                    const mode = input.source ?? "managed";
+                    if (mode !== "local" && mode !== "managed") {
+                        throw new MediaValidationError(`Unsupported image import mode: ${mode}`);
+                    }
+                    const image = await validateImageFile(input.imagePath, {
+                        mode: mode === "local" ? "fast" : "full",
+                    });
+                    if (mode === "local") {
+                        background = {
+                            type: "image",
+                            source: { kind: "local", path: image.filePath },
+                        };
+                        const effects = normalizeBackgroundEffects(input.effects);
+                        if (effects)
+                            background.effects = effects;
+                    }
+                    else {
+                        // Keep extension from source when it's an allowed one.
+                        const basename = `poster${image.extension === ".jpeg" ? ".jpg" : image.extension}`;
+                        assertSafeBasename(basename, "image");
+                        await copyFileAtomic(image.filePath, path.join(stagingDir, basename));
+                        background = { type: "image", image: basename };
+                        const effects = normalizeBackgroundEffects(input.effects);
+                        if (effects)
+                            background.effects = effects;
+                    }
                 }
                 else if (input.type === "video") {
-                    const video = await validateVideoFile(input.videoPath);
-                    assertSafeBasename(DEFAULT_VIDEO_BASENAME, "video");
-                    await copyFileAtomic(video.filePath, path.join(stagingDir, DEFAULT_VIDEO_BASENAME));
+                    const mode = input.source ?? "managed";
+                    if (mode !== "local" && mode !== "managed") {
+                        throw new MediaValidationError(`Unsupported video import mode: ${mode}`);
+                    }
+                    const video = await validateVideoFile(input.videoPath, {
+                        mode: mode === "local" ? "fast" : "full",
+                    });
+                    if (mode === "managed") {
+                        assertSafeBasename(DEFAULT_VIDEO_BASENAME, "video");
+                        await copyFileAtomic(video.filePath, path.join(stagingDir, DEFAULT_VIDEO_BASENAME));
+                    }
                     // Poster: explicit path → reuse active image → synthetic 1x1 PNG.
                     let imageBasename;
                     if (input.imagePath) {
@@ -482,8 +497,11 @@ export class BackgroundStore {
                         assertSafeBasename(imageBasename, "image");
                         await copyFileAtomic(image.filePath, path.join(stagingDir, imageBasename));
                     }
-                    else if (previous.background?.image) {
-                        const prevImage = path.join(this.paths.activeDir, previous.background.image);
+                    else if (previous.background) {
+                        const prevImage = resolveBackgroundImagePath(this.paths.activeDir, previous.background);
+                        if (!prevImage) {
+                            throw new MediaValidationError("Previous background has no poster image.");
+                        }
                         const image = await validateImageFile(prevImage);
                         imageBasename = `poster${image.extension === ".jpeg" ? ".jpg" : image.extension}`;
                         assertSafeBasename(imageBasename, "image");
@@ -497,7 +515,9 @@ export class BackgroundStore {
                     background = {
                         type: "video",
                         image: imageBasename,
-                        video: DEFAULT_VIDEO_BASENAME,
+                        ...(mode === "local"
+                            ? { source: { kind: "local", path: video.filePath } }
+                            : { video: DEFAULT_VIDEO_BASENAME }),
                     };
                 }
                 else {
@@ -540,10 +560,7 @@ export class BackgroundStore {
             try {
                 await this.#writeJsonAtomic(path.join(stagingDir, MANIFEST_NAME), restored);
                 if (restored.background) {
-                    await copyFileAtomic(path.join(snapshot.dir, restored.background.image), path.join(stagingDir, restored.background.image));
-                    if (restored.background.video) {
-                        await copyFileAtomic(path.join(snapshot.dir, restored.background.video), path.join(stagingDir, restored.background.video));
-                    }
+                    await this.#copyManagedBackgroundFiles(snapshot.dir, stagingDir, restored.background);
                 }
                 await this.#validateTree(stagingDir, restored);
                 await this.#promoteStagingToActive(stagingDir);
@@ -557,11 +574,29 @@ export class BackgroundStore {
     async #validateTree(dir, manifest) {
         if (!manifest.background)
             return;
-        const imagePath = path.join(dir, manifest.background.image);
-        await validateImageFile(imagePath);
-        if (manifest.background.video) {
-            const videoPath = path.join(dir, manifest.background.video);
-            await validateVideoFile(videoPath);
+        const imagePath = resolveBackgroundImagePath(dir, manifest.background);
+        if (!imagePath) {
+            throw new MediaValidationError("Background has no image source.");
+        }
+        await validateImageFile(imagePath, {
+            mode: manifest.background.type === "image" && isLocalBackgroundSource(manifest.background)
+                ? "fast"
+                : "full",
+        });
+        const videoPath = resolveBackgroundVideoPath(dir, manifest.background);
+        if (videoPath) {
+            await validateVideoFile(videoPath, {
+                mode: isLocalBackgroundSource(manifest.background) ? "fast" : "full",
+            });
+        }
+    }
+    async #copyManagedBackgroundFiles(sourceDir, destinationDir, background) {
+        if (background.image) {
+            await copyFileAtomic(path.join(sourceDir, background.image), path.join(destinationDir, background.image));
+        }
+        const primaryFile = managedPrimaryFile(background);
+        if (primaryFile && primaryFile !== background.image) {
+            await copyFileAtomic(path.join(sourceDir, primaryFile), path.join(destinationDir, primaryFile));
         }
     }
     async #promoteStagingToActive(stagingDir) {
@@ -614,7 +649,7 @@ export class BackgroundStore {
             if (!trimmed || trimmed.length > 80) {
                 throw new MediaValidationError("Theme name must be 1–80 characters.");
             }
-            if (/[<>:"/\|?*]/.test(trimmed) || Array.from(trimmed).some((ch) => ch.charCodeAt(0) < 32)) {
+            if (/[<>:"/\\|?*]/.test(trimmed) || Array.from(trimmed).some((ch) => ch.charCodeAt(0) < 32)) {
                 throw new MediaValidationError("Theme name contains illegal characters.");
             }
             const manifest = await this.readActiveManifest();
@@ -625,9 +660,19 @@ export class BackgroundStore {
             if (usage.count >= this.maxSavedThemes) {
                 throw new MediaValidationError(`Saved theme limit reached (${this.maxSavedThemes}). Delete one before saving.`);
             }
-            let incomingBytes = (await fs.stat(path.join(this.paths.activeDir, manifest.background.image))).size;
-            if (manifest.background.video) {
-                incomingBytes += (await fs.stat(path.join(this.paths.activeDir, manifest.background.video))).size;
+            const imagePath = resolveBackgroundImagePath(this.paths.activeDir, manifest.background);
+            const primaryPath = manifest.background.type === "video"
+                ? resolveBackgroundVideoPath(this.paths.activeDir, manifest.background)
+                : imagePath;
+            if (!imagePath || !primaryPath) {
+                throw new MediaValidationError("Active background has no resolvable media source.");
+            }
+            let incomingBytes = 0;
+            if (manifest.background.type === "video") {
+                incomingBytes += (await fs.stat(imagePath)).size;
+            }
+            if (!isLocalBackgroundSource(manifest.background)) {
+                incomingBytes += (await fs.stat(primaryPath)).size;
             }
             if (usage.bytes + incomingBytes > this.maxSavedBytes) {
                 throw new MediaValidationError(`Saved theme storage limit exceeded (${this.maxSavedBytes} bytes). Delete a theme before saving.`);
@@ -639,11 +684,7 @@ export class BackgroundStore {
             }
             const stagingDir = await this.#createStagingDir();
             try {
-                const imageSrc = path.join(this.paths.activeDir, manifest.background.image);
-                await copyFileAtomic(imageSrc, path.join(stagingDir, manifest.background.image));
-                if (manifest.background.video) {
-                    await copyFileAtomic(path.join(this.paths.activeDir, manifest.background.video), path.join(stagingDir, manifest.background.video));
-                }
+                await this.#copyManagedBackgroundFiles(this.paths.activeDir, stagingDir, manifest.background);
                 // Persist media only — generation is assigned on restore.
                 const savedManifest = {
                     schema: SCHEMA_ID,
@@ -675,6 +716,7 @@ export class BackgroundStore {
                     type: manifest.background.type,
                     path: dir,
                     savedAt: meta.savedAt,
+                    sourceMode: isLocalBackgroundSource(manifest.background) ? "local" : "managed",
                 };
                 if (typeof meta.videoPositionSec === "number") {
                     info.videoPositionSec = meta.videoPositionSec;
@@ -686,138 +728,6 @@ export class BackgroundStore {
             }
         });
     }
-    /**
-     * Copy validated local media into saved/ without changing the active
-     * background. Used by the skin-center installer.
-     */
-    async importSavedThemeFromMedia(input) {
-        return this.#withWriteLock(async () => {
-            await this.init();
-            const trimmed = String(input?.name ?? "").trim();
-            if (!trimmed || trimmed.length > 80) {
-                throw new MediaValidationError("Theme name must be 1–80 characters.");
-            }
-            if (/[<>:"/\\|?*]/.test(trimmed) ||
-                Array.from(trimmed).some((ch) => ch.charCodeAt(0) < 32)) {
-                throw new MediaValidationError("Theme name contains illegal characters.");
-            }
-            const source = normalizeSavedThemeSource(input.source);
-            if (source) {
-                const existing = await this.findSavedThemeBySource(source);
-                if (existing)
-                    return existing;
-            }
-            const imagePath = String(input.imagePath ?? "").trim();
-            const videoPath = String(input.videoPath ?? "").trim();
-            if (!imagePath && !videoPath) {
-                throw new MediaValidationError("Import requires an image or video file.");
-            }
-            const video = videoPath ? await validateVideoFile(videoPath) : null;
-            let image = null;
-            if (imagePath) {
-                image = await validateImageFile(imagePath);
-            }
-            else if (video) {
-                try {
-                    const previous = await this.readActiveManifest();
-                    if (previous.background?.image) {
-                        image = await validateImageFile(path.join(this.paths.activeDir, previous.background.image));
-                    }
-                }
-                catch {
-                    image = null;
-                }
-            }
-            const usage = await this.#savedThemeUsage();
-            if (usage.count >= this.maxSavedThemes) {
-                throw new MediaValidationError(`Saved theme limit reached (${this.maxSavedThemes}). Delete one before saving.`);
-            }
-            const incomingBytes = (image?.size ?? SYNTHETIC_POSTER_PNG.length) + (video?.size ?? 0);
-            if (usage.bytes + incomingBytes > this.maxSavedBytes) {
-                throw new MediaValidationError(`Saved theme storage limit exceeded (${this.maxSavedBytes} bytes). Delete a theme before saving.`);
-            }
-            const id = slugThemeId(trimmed);
-            const dir = path.join(this.paths.savedDir, id);
-            if (!isPathInsideRoot(this.paths.savedDir, dir)) {
-                throw new MediaValidationError("Saved theme path escaped saved root.");
-            }
-            const stagingDir = await this.#createStagingDir();
-            try {
-                let imageBasename;
-                if (image) {
-                    imageBasename = `poster${image.extension === ".jpeg" ? ".jpg" : image.extension}`;
-                    assertSafeBasename(imageBasename, "image");
-                    await copyFileAtomic(image.filePath, path.join(stagingDir, imageBasename));
-                }
-                else {
-                    imageBasename = "poster.png";
-                    assertSafeBasename(imageBasename, "image");
-                    await fs.writeFile(path.join(stagingDir, imageBasename), SYNTHETIC_POSTER_PNG);
-                }
-                const background = video
-                    ? {
-                        type: "video",
-                        image: imageBasename,
-                        video: DEFAULT_VIDEO_BASENAME,
-                    }
-                    : { type: "image", image: imageBasename };
-                if (!video) {
-                    const effects = normalizeBackgroundEffects(input.effects);
-                    if (effects)
-                        background.effects = effects;
-                }
-                if (video) {
-                    assertSafeBasename(DEFAULT_VIDEO_BASENAME, "video");
-                    await copyFileAtomic(video.filePath, path.join(stagingDir, DEFAULT_VIDEO_BASENAME));
-                }
-                const savedManifest = {
-                    schema: SCHEMA_ID,
-                    generation: 0,
-                    background,
-                    updatedAt: nowIso(),
-                };
-                await this.#writeJsonAtomic(path.join(stagingDir, MANIFEST_NAME), savedManifest);
-                const meta = {
-                    id,
-                    name: trimmed,
-                    type: background.type,
-                    savedAt: nowIso(),
-                };
-                if (source)
-                    meta.source = source;
-                if (video) {
-                    const pos = normalizeVideoPositionSec(input.videoPositionSec);
-                    if (pos != null) {
-                        meta.videoPositionSec = pos;
-                        meta.videoPositionUpdatedAt = nowIso();
-                    }
-                }
-                await this.#writeJsonAtomic(path.join(stagingDir, SAVED_META_NAME), meta);
-                await this.#validateTree(stagingDir, savedManifest);
-                await fs.rename(stagingDir, dir);
-                return {
-                    id,
-                    name: trimmed,
-                    type: background.type,
-                    path: dir,
-                    savedAt: meta.savedAt,
-                    ...(source ? { source } : {}),
-                };
-            }
-            finally {
-                await rmrf(stagingDir);
-            }
-        });
-    }
-    async findSavedThemeBySource(source) {
-        const wanted = normalizeSavedThemeSource(source);
-        if (!wanted)
-            return null;
-        const listed = await this.listSavedThemes();
-        return (listed.find((theme) => theme.source?.kind === wanted.kind &&
-            theme.source.skinId === wanted.skinId &&
-            theme.source.centerUrl === wanted.centerUrl) ?? null);
-    }
     async listSavedThemes() {
         await this.init();
         let entries = [];
@@ -847,17 +757,16 @@ export class BackgroundStore {
                 // Directory basename is the authoritative id (filesystem truth).
                 // Older builds stored non-ASCII meta.id that useSavedTheme rejected.
                 const pos = normalizeVideoPositionSec(meta.videoPositionSec);
-                const source = normalizeSavedThemeSource(meta.source);
                 out.push({
                     id: entry,
                     name: meta.name,
                     type: m.background.type,
                     path: dir,
                     savedAt: typeof meta.savedAt === "string" ? meta.savedAt : "",
+                    sourceMode: isLocalBackgroundSource(m.background) ? "local" : "managed",
                     ...(pos != null && m.background.type === "video"
                         ? { videoPositionSec: pos }
                         : {}),
-                    ...(source ? { source } : {}),
                 });
             }
             catch {
@@ -1007,11 +916,18 @@ export class BackgroundStore {
             throw new MediaValidationError("Saved theme manifest is invalid.");
         }
         await this.#validateTree(dir, parsed);
-        const imagePath = path.join(dir, parsed.background.image);
+        const imagePath = resolveBackgroundImagePath(dir, parsed.background);
+        if (!imagePath) {
+            throw new MediaValidationError("Saved theme has no image source.");
+        }
+        const sourceMode = isLocalBackgroundSource(parsed.background)
+            ? "local"
+            : "managed";
         if (parsed.background.type === "image") {
             const input = {
                 type: "image",
                 imagePath,
+                source: sourceMode,
             };
             const effects = normalizeBackgroundEffects(parsed.background.effects);
             if (effects)
@@ -1022,7 +938,8 @@ export class BackgroundStore {
                 themeId: id,
             };
         }
-        if (!parsed.background.video) {
+        const videoPath = resolveBackgroundVideoPath(dir, parsed.background);
+        if (!videoPath) {
             throw new MediaValidationError("Saved video theme has no video file.");
         }
         let videoPositionSec = null;
@@ -1037,7 +954,8 @@ export class BackgroundStore {
         const input = {
             type: "video",
             imagePath,
-            videoPath: path.join(dir, parsed.background.video),
+            videoPath,
+            source: sourceMode,
         };
         if (videoPositionSec != null && videoPositionSec > 0) {
             input.startAt = videoPositionSec;
@@ -1099,10 +1017,7 @@ export class BackgroundStore {
             const stagingDir = await this.#createStagingDir();
             try {
                 await this.#writeJsonAtomic(path.join(stagingDir, MANIFEST_NAME), restored);
-                await copyFileAtomic(path.join(dir, restored.background.image), path.join(stagingDir, restored.background.image));
-                if (restored.background.video) {
-                    await copyFileAtomic(path.join(dir, restored.background.video), path.join(stagingDir, restored.background.video));
-                }
+                await this.#copyManagedBackgroundFiles(dir, stagingDir, restored.background);
                 await this.#validateTree(stagingDir, restored);
                 await this.#promoteStagingToActive(stagingDir);
                 const manifest = await this.readActiveManifest();
@@ -1191,6 +1106,7 @@ export class BackgroundStore {
                     type: "image",
                     path: spec.imagePath,
                     savedAt: "",
+                    sourceMode: "managed",
                     bundled: true,
                 });
             }
@@ -1214,9 +1130,17 @@ export class BackgroundStore {
                 const manifest = JSON.parse(raw);
                 if (!isManifest(manifest) || !manifest.background)
                     continue;
-                bytes += (await fs.stat(path.join(theme.path, manifest.background.image))).size;
-                if (manifest.background.video) {
-                    bytes += (await fs.stat(path.join(theme.path, manifest.background.video))).size;
+                const imagePath = resolveBackgroundImagePath(theme.path, manifest.background);
+                const primaryPath = manifest.background.type === "video"
+                    ? resolveBackgroundVideoPath(theme.path, manifest.background)
+                    : imagePath;
+                if (!imagePath || !primaryPath)
+                    continue;
+                if (manifest.background.type === "video") {
+                    bytes += (await fs.stat(imagePath)).size;
+                }
+                if (!isLocalBackgroundSource(manifest.background)) {
+                    bytes += (await fs.stat(primaryPath)).size;
                 }
             }
             catch {
@@ -1226,70 +1150,6 @@ export class BackgroundStore {
         return { count, bytes };
     }
 }
-/**
- * Display name for an imported file. Id stays a random ASCII folder; this is
- * only the label shown in 已保存主题.
- */
-export function themeNameFromFilePath(filePath, fallback = "主题") {
-    const base = path.basename(String(filePath ?? "").replaceAll("\\", "/"));
-    const ext = path.extname(base);
-    let name = (ext ? base.slice(0, -ext.length) : base).trim();
-    name = name
-        .replace(/[<>:"/\\|?*]/g, " ")
-        .replace(/[\u0000-\u001f]/g, "")
-        .replace(/\s+/g, " ")
-        .trim();
-    if (!name)
-        name = fallback;
-    if (name.length > 80)
-        name = name.slice(0, 80).trim();
-    if (!name)
-        name = fallback;
-    return name;
-}
-export function importedThemeInputFromApply(input, name) {
-    if (input.type === "image") {
-        const next = {
-            name: String(name ?? "").trim() || themeNameFromFilePath(input.imagePath, "图片"),
-            imagePath: input.imagePath,
-        };
-        if (input.effects)
-            next.effects = input.effects;
-        return next;
-    }
-    const next = {
-        name: String(name ?? "").trim() || themeNameFromFilePath(input.videoPath, "视频"),
-        videoPath: input.videoPath,
-    };
-    if (input.imagePath)
-        next.imagePath = input.imagePath;
-    const pos = normalizeVideoPositionSec(input.startAt);
-    if (pos != null)
-        next.videoPositionSec = pos;
-    return next;
-}
-export async function persistAndApplyImportedMedia(session, input, opts = {}) {
-    if (input.type !== "image" && input.type !== "video") {
-        return {
-            ok: false,
-            error: "Imported media must be an image or video.",
-            rolledBack: false,
-        };
-    }
-    let theme;
-    try {
-        theme = await session.importSavedTheme(importedThemeInputFromApply(input, opts.name));
-    }
-    catch (error) {
-        return {
-            ok: false,
-            error: error instanceof Error ? error.message : String(error),
-            rolledBack: false,
-        };
-    }
-    const result = await session.useSavedTheme(theme.id);
-    return { ...result, theme };
-}
 /** Normalize a playback position for theme meta. Invalid → null (caller treats as 0). */
 export function normalizeVideoPositionSec(value) {
     const n = typeof value === "number" ? value : Number(value);