Move reusable file persistence mechanics into engine persistence - PR_26140_048-move-file-persistence-to-engine

Author: DavidQ

docs/dev/reports/PR_26140_048-move-file-persistence-to-engine_report.md

@@ -0,0 +1,55 @@
+# PR_26140_048-move-file-persistence-to-engine
+
+## Summary
+- Added `src/engine/persistence/FilePersistenceService.js` as the shared engine owner for browser text file persistence mechanics: file text reads, file-handle text reads/writes, and text download creation.
+- Updated V2/workspace file flows to import directly from `src/engine/persistence/index.js`: Workspace Manager V2, Preview Generator V2, Asset Manager V2, Object Vector Studio V2, Palette Manager V2, Text to Speech V2, shared project workspace import/export, and shared game manifest file loading.
+- Moved obvious reusable text file mechanics from active non-V2 tool files while keeping picker UI, repo path decisions, preview generation decisions, image/object URL preview logic, and manifest workflow behavior local to those tools.
+- Did not touch sample JSON.
+
+## Files Changed
+- `src/engine/persistence/FilePersistenceService.js`
+- `src/engine/persistence/index.js`
+- `src/tools/common/GameManifestLoader.js`
+- `tools/shared/projectSystem.js`
+- `tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js`
+- `tools/preview-generator-v2/PreviewGeneratorV2App.js`
+- `tools/asset-manager-v2/js/AssetManagerV2App.js`
+- `tools/object-vector-studio-v2/js/ToolStarterApp.js`
+- `tools/palette-manager-v2/controls/PaletteImportExportControl.js`
+- `tools/text2speech-V2/js/TextToSpeechToolApp.js`
+- `tools/Asset Pipeline/main.js`
+- `tools/Parallax Scene Studio/main.js`
+- `tools/SVG Asset Studio/main.js`
+- `tools/Sprite Editor/modules/spriteEditorApp.js`
+- `tools/Tilemap Studio/main.js`
+- `tools/Vector Map Editor/editor/VectorMapRuntimeExporter.js`
+- `tools/Vector Map Editor/editor/VectorMapSerializer.js`
+
+## Behavior Notes
+- `readFileText()` preserves modern `file.text()` behavior and preserves FileReader fallback behavior for callers that still need it.
+- `downloadTextFile()` preserves existing JSON/SVG download behavior and supports the prior append-to-body pattern used by Asset Manager V2 and Text to Speech V2.
+- `readFileHandleText()` and `writeFileHandleText()` keep Workspace Manager V2 and Preview Generator V2 in charge of repo path validation, read-back verification, and user-facing workflow messages.
+- Remaining direct FileReader/object URL usage is image decode, image preview, fake repo-handle emulation, or engine runtime blob download behavior, not reusable text file persistence.
+
+## Validation
+- PASS: `git diff --check`
+- PASS: `node --check` for all changed JavaScript files.
+- PASS: targeted import validation for import-safe changed modules.
+- PASS: targeted FilePersistenceService behavior validation for text reads, FileReader fallback, file-handle read/write, and text download creation.
+- PASS: `npm run test:workspace-v2` - 58 passed.
+- INFO: `npm run build` is unavailable in this repo (npm reports missing script); `npm run` was used to confirm available scripts.
+- SKIPPED: full samples smoke test, per request.
+- PASS: repo-structured ZIP created at `tmp/PR_26140_048-move-file-persistence-to-engine_delta.zip` and `zipfile.testzip()` returned ok.
+
+## Coverage
+- Playwright impacted: Yes. Workspace/tool file flows and browser file persistence mechanics changed.
+- V8 coverage artifacts were generated by `npm run test:workspace-v2`:
+  - `docs/dev/reports/playwright_v8_coverage_report.txt`
+  - `docs/dev/reports/coverage_changed_js_guardrail.txt`
+- Confirmed covered changed runtime files include `src/engine/persistence/FilePersistenceService.js` (78%), `src/engine/persistence/index.js` (100%), `tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js` (93%), `tools/preview-generator-v2/PreviewGeneratorV2App.js` (88%), `tools/asset-manager-v2/js/AssetManagerV2App.js` (63%), `tools/object-vector-studio-v2/js/ToolStarterApp.js` (94%), and `tools/text2speech-V2/js/TextToSpeechToolApp.js` (91%).
+- Valid WARN details were added for changed files with spaces in their paths that the existing guardrail parser did not list.
+
+## Manual Validation
+- Open Workspace Manager V2, select repo, select a game, and verify the game dropdown/tool tiles still populate.
+- Launch Asset Manager V2, Object Vector Studio V2, Palette Manager V2, Text to Speech V2, and Preview Generator V2 from Workspace Manager and verify import/export or save/read-back actions behave as before.
+- Optional spot check legacy text file flows: Asset Pipeline JSON load, Parallax/Tilemap project/asset registry load/save, SVG load/save, Sprite project/registry load, and Vector Map editor/runtime JSON export.

src/engine/persistence/FilePersistenceService.js

@@ -0,0 +1,110 @@
+/*
+Toolbox Aid
+David Quesenberry
+05/20/2026
+FilePersistenceService.js
+*/
+function resolveWindowRef(windowRef = null) {
+  return windowRef || globalThis.window || globalThis;
+}
+
+function resolveDocumentRef(documentRef = null, windowRef = null) {
+  return documentRef || resolveWindowRef(windowRef).document || globalThis.document || null;
+}
+
+function resolveFileReader(file, windowRef = null) {
+  return file?.ownerDocument?.defaultView?.FileReader
+    || resolveWindowRef(windowRef).FileReader
+    || globalThis.FileReader
+    || null;
+}
+
+export async function readFileText(file, { errorMessage = "Unable to read selected file.", windowRef = null } = {}) {
+  if (!file) {
+    throw new Error(errorMessage);
+  }
+  if (typeof file.text === "function") {
+    return String(await file.text());
+  }
+
+  const FileReaderCtor = resolveFileReader(file, windowRef);
+  if (typeof FileReaderCtor !== "function") {
+    throw new Error(errorMessage);
+  }
+
+  return new Promise((resolve, reject) => {
+    const reader = new FileReaderCtor();
+    reader.onerror = () => reject(new Error(errorMessage));
+    reader.onload = () => resolve(String(reader.result ?? ""));
+    reader.readAsText(file);
+  });
+}
+
+export async function readFileHandleText(fileHandle, {
+  handleErrorMessage = "file handle cannot be read",
+  textErrorMessage = "file text read-back is unavailable"
+} = {}) {
+  if (!fileHandle || typeof fileHandle.getFile !== "function") {
+    throw new Error(handleErrorMessage);
+  }
+
+  const file = await fileHandle.getFile();
+  if (!file || typeof file.text !== "function") {
+    throw new Error(textErrorMessage);
+  }
+
+  return {
+    file,
+    text: String(await file.text())
+  };
+}
+
+export async function writeFileHandleText(fileHandle, content, {
+  handleErrorMessage = "file handle cannot be written"
+} = {}) {
+  if (!fileHandle || typeof fileHandle.createWritable !== "function") {
+    throw new Error(handleErrorMessage);
+  }
+
+  const writable = await fileHandle.createWritable();
+  await writable.write(String(content));
+  await writable.close();
+  return true;
+}
+
+export function downloadTextFile(content, fileName, {
+  appendToBody = false,
+  documentRef = null,
+  mimeType = "application/json",
+  windowRef = null
+} = {}) {
+  const browserWindow = resolveWindowRef(windowRef);
+  const documentObject = resolveDocumentRef(documentRef, browserWindow);
+  const BlobCtor = browserWindow.Blob || globalThis.Blob;
+  const urlApi = browserWindow.URL || browserWindow.webkitURL || globalThis.URL;
+  if (
+    !documentObject
+    || typeof documentObject.createElement !== "function"
+    || typeof BlobCtor !== "function"
+    || typeof urlApi?.createObjectURL !== "function"
+    || typeof urlApi?.revokeObjectURL !== "function"
+  ) {
+    return false;
+  }
+
+  const blob = new BlobCtor([String(content)], { type: mimeType });
+  const url = urlApi.createObjectURL(blob);
+  const link = documentObject.createElement("a");
+  link.href = url;
+  link.download = fileName;
+  link.rel = "noopener";
+  if (appendToBody && documentObject.body) {
+    documentObject.body.append(link);
+  }
+  link.click();
+  if (appendToBody && typeof link.remove === "function") {
+    link.remove();
+  }
+  urlApi.revokeObjectURL(url);
+  return true;
+}

src/engine/persistence/index.js

@@ -10,5 +10,6 @@ export { default as LocalStorageService } from './LocalStorageService.js';
 export { default as SessionStorageService } from './SessionStorageService.js';
 export { default as CookieStorageService } from './CookieStorageService.js';
 export { default as SaveSlotManager } from './SaveSlotManager.js';
+export { downloadTextFile, readFileHandleText, readFileText, writeFileHandleText } from './FilePersistenceService.js';
 export { compressText, decompressText, compressJson, decompressJson } from './CompressionService.js';
 export { serializeWorldState, deserializeWorldState } from './WorldSerializer.js';

src/tools/common/GameManifestLoader.js

@@ -1,5 +1,5 @@
 import { asPositiveInteger } from "../../shared/number/index.js";
-import { SessionStorageService } from "../../engine/persistence/index.js";
+import { readFileText, SessionStorageService } from "../../engine/persistence/index.js";
 import { isRecord } from "../../shared/types/typeGuards.js";
 
 export { isRecord };
@@ -93,7 +93,7 @@ export class GameManifestLoader {
       return { ok: false, skipped: true };
     }
     try {
-      return parseJson(await file.text(), file.name || "selected manifest file");
+      return parseJson(await readFileText(file), file.name || "selected manifest file");
     } catch (error) {
       return { ok: false, message: `Manifest file could not be read: ${error.message}` };
     }

tools/Asset Pipeline/main.js

@@ -1,4 +1,5 @@
 import { runAssetPipelineTooling } from "../shared/pipeline/assetPipelineTooling.js";
+import { readFileText } from "../../src/engine/persistence/index.js";
 import { safeParseJson, toPrettyJson } from "../shared/debugInspectorData.js";
 import { registerToolBootContract } from "../shared/toolBootContract.js";
 import {
@@ -591,7 +592,7 @@ async function loadPipelineFromJsonFile(file) {
     return;
   }
   try {
-    const text = await file.text();
+    const text = await readFileText(file);
     const parsed = parseJsonObjectString(text);
     if (!parsed) {
       throw new Error("Selected file must contain a valid JSON object.");

tools/Parallax Scene Studio/main.js

@@ -15,6 +15,7 @@ import {
   sanitizeAssetRegistry,
   upsertRegistryEntry
 } from "../shared/projectAssetRegistry.js";
+import { downloadTextFile, readFileText } from "../../src/engine/persistence/index.js";
 import { registerAssetPipelineCandidate } from "../shared/assetPipelineFoundation.js";
 import {
   getBlockingAssetValidationMessage,
@@ -361,19 +362,6 @@ function createTilemapParallaxPatch(parallaxDocument) {
   };
 }
 
-function createDownload(fileName, content) {
-  const blob = new Blob([content], { type: "application/json" });
-  const href = URL.createObjectURL(blob);
-  const anchor = document.createElement("a");
-  anchor.href = href;
-  anchor.download = fileName;
-  anchor.style.display = "none";
-  document.body.appendChild(anchor);
-  anchor.click();
-  document.body.removeChild(anchor);
-  URL.revokeObjectURL(href);
-}
-
 function summarizeGraphFindings(findings) {
   return Array.isArray(findings) && findings.length > 0
     ? ` Graph findings: ${findings.length}.`
@@ -1210,7 +1198,7 @@ class ParallaxEditorApp {
     };
     const payload = JSON.stringify(output, null, 2);
     const fileName = `${this.documentModel.map.name || "map"}.parallax.json`;
-    createDownload(fileName, payload);
+    downloadTextFile(payload, fileName);
     this.updateStatus(`Saved ${fileName} (${output.assetRefs.parallaxSourceIds.length} parallax asset refs, ID-based layer references).${summarizeGraphFindings(findings)} Validation: ${summarizeAssetValidation(validation)}.`);
   }
 
@@ -1223,7 +1211,7 @@ class ParallaxEditorApp {
     }
     const { findings } = buildAssetDependencyGraph(this.assetRegistry);
     const payload = createRegistryDownloadPayload(this.assetRegistry);
-    createDownload("project.assets.json", payload);
+    downloadTextFile(payload, "project.assets.json");
     this.updateStatus(`Saved project.assets.json (${this.assetRegistry.parallaxSources.length} parallax sources).${summarizeGraphFindings(findings)} Validation: ${summarizeAssetValidation(validation)}.`);
   }
 
@@ -1236,7 +1224,7 @@ class ParallaxEditorApp {
     const patch = createTilemapParallaxPatch(createRegistryManagedParallaxSaveDocument(this.documentModel));
     const payload = JSON.stringify(patch, null, 2);
     const fileName = `${this.documentModel.map.name || "map"}.tilemap-parallax.patch.json`;
-    createDownload(fileName, payload);
+    downloadTextFile(payload, fileName);
     this.updateStatus(`Exported ${fileName}. Validation: ${summarizeAssetValidation(validation)}.`);
   }
 
@@ -1272,22 +1260,21 @@ class ParallaxEditorApp {
       return;
     }
     const fileBase = `${this.assetRegistry.projectId || this.documentModel.map.name || "parallax-project"}.package`;
-    createDownload(`${fileBase}.json`, `${JSON.stringify(packageResult.manifest, null, 2)}\n`);
-    createDownload(`${fileBase}.report.txt`, `${packageResult.reportText}\n`);
+    downloadTextFile(`${JSON.stringify(packageResult.manifest, null, 2)}\n`, `${fileBase}.json`);
+    downloadTextFile(`${packageResult.reportText}\n`, `${fileBase}.report.txt`);
     this.updateStatus(`${summarizeProjectPackaging(packageResult)} Manifest and report exported.`);
   }
 
-  handleLoadProject(event) {
+  async handleLoadProject(event) {
     this.exitSimulationMode();
     const file = event.target.files?.[0];
     if (!file) {
       return;
     }
 
-    const reader = new FileReader();
-    reader.onload = () => {
-      try {
-        const raw = JSON.parse(String(reader.result));
+    try {
+      const text = await readFileText(file);
+      const raw = JSON.parse(text);
         const guard = assertStandaloneToolDocument(raw, {
           expectedLabel: "Parallax project",
           acceptedSchemas: ["toolbox.parallax/1", "toolbox.tilemap/1"],
@@ -1324,25 +1311,21 @@ class ParallaxEditorApp {
         } else {
           this.updateStatus(`Loaded ${file.name} (validation: ${summarizeAssetValidation(validation)}).`);
         }
-      } catch (error) {
-        this.updateStatus(`Load failed: ${error instanceof Error ? error.message : "invalid JSON"}`);
-      }
+    } catch (error) {
+      this.updateStatus(`Load failed: ${error instanceof Error ? error.message : "invalid JSON"}`);
+    }
       this.refs.loadProjectInput.value = "";
-    };
-
-    reader.readAsText(file);
   }
 
-  handleLoadAssetRegistry(event) {
+  async handleLoadAssetRegistry(event) {
     const file = event.target.files?.[0];
     if (!file) {
       return;
     }
 
-    const reader = new FileReader();
-    reader.onload = () => {
-      try {
-        const parsed = JSON.parse(String(reader.result));
+    try {
+      const text = await readFileText(file);
+      const parsed = JSON.parse(text);
         this.assetRegistry = mergeAssetRegistries(this.assetRegistry, parsed);
         const resolution = this.resolveAssetRefsFromRegistry();
         this.invalidateImageCache();
@@ -1355,13 +1338,10 @@ class ParallaxEditorApp {
         } else {
           this.updateStatus(`Loaded ${file.name} (${this.assetRegistry.parallaxSources.length} parallax sources, validation: ${summarizeAssetValidation(validation)}).`);
         }
-      } catch (error) {
-        this.updateStatus(`Asset registry load failed: ${error instanceof Error ? error.message : "invalid JSON"}`);
-      }
+    } catch (error) {
+      this.updateStatus(`Asset registry load failed: ${error instanceof Error ? error.message : "invalid JSON"}`);
+    }
       this.refs.loadAssetRegistryInput.value = "";
-    };
-
-    reader.readAsText(file);
   }
 
   applyMapMetaFromInputs() {

tools/SVG Asset Studio/main.js

@@ -4,6 +4,7 @@ David Quesenberry
 03/30/2026
 main.js
 */
+import { downloadTextFile, readFileText } from "../../src/engine/persistence/index.js";
 import { registerToolBootContract } from "../shared/toolBootContract.js";
 import {
   getToolLoadQuerySnapshot,
@@ -2313,19 +2314,6 @@ function serializeCurrentSvg() {
   return `<?xml version="1.0" encoding="UTF-8"?>\n${serialized}\n`;
 }
 
-function downloadTextFile(fileName, content, mimeType) {
-  const blob = new Blob([content], { type: mimeType });
-  const href = URL.createObjectURL(blob);
-  const anchor = document.createElement("a");
-  anchor.href = href;
-  anchor.download = fileName;
-  anchor.style.display = "none";
-  document.body.appendChild(anchor);
-  anchor.click();
-  document.body.removeChild(anchor);
-  URL.revokeObjectURL(href);
-}
-
 function parseDimension(value, fallback) {
   if (typeof value !== "string") {
     return fallback;
@@ -3180,7 +3168,7 @@ function bindEvents() {
     if (!file) {
       return;
     }
-    const text = await file.text();
+    const text = await readFileText(file);
     loadSvgFromText(text, file.name);
     refs.loadSvgInput.value = "";
   });
@@ -3189,7 +3177,7 @@ function bindEvents() {
     finalizePendingPolyline(true);
     const content = serializeCurrentSvg();
     const fileName = `${state.documentName || "background-art"}.svg`;
-    downloadTextFile(fileName, content, "image/svg+xml");
+    downloadTextFile(content, fileName, { mimeType: "image/svg+xml" });
     setStatus(`Saved ${fileName}.`);
   });