@turbowarp/sb3fix 0.3.6 → 0.4.0

package/README.md

@@ -45,8 +45,14 @@ const run = async () => {
     // is not stable and may change without warning.
     logCallback: (message) => {
       console.log(message);
-    }
+    },
+
+    // Different runtimes support different features. A project that is invalid in Scratch might
+    // be valid for another runtime. This lets you control which runtime sb3fix targets.
+    // Values: 'scratch' (default), 'turbowarp'
+    platform: 'scratch'
   };
+
   // To use the above options, just supply as the second argument when you call sb3fix:
   await sb3fix.fixZip(brokenZip, options);
   sb3fix.fixJSON(brokenJSON, options);
@@ -93,7 +99,7 @@ npm run test
 
 ## License
 
-Copyright (C) 2023-2024 Thomas Weber
+Copyright (C) 2023-2025 Thomas Weber
 
 This Source Code Form is subject to the terms of the Mozilla Public
 License, v. 2.0. If a copy of the MPL was not distributed with this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turbowarp/sb3fix",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Fix corrupted Scratch projects",
   "main": "src/sb3fix.js",
   "scripts": {
@@ -21,7 +21,7 @@
   },
   "homepage": "https://github.com/TurboWarp/sb3fix#readme",
   "dependencies": {
-    "@turbowarp/jszip": "^3.11.1"
+    "@turbowarp/jszip": "^3.12.0"
   },
   "devDependencies": {
     "copy-webpack-plugin": "^13.0.0",

package/src/sb3fix.js

@@ -8,8 +8,13 @@ License, v. 2.0. If a copy of the MPL was not distributed with this
 file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
 
+/**
+ * @typedef {'scratch'|'turbowarp'} Platform
+ */
+
 /**
  * @typedef Options
+ * @property {Platform} [platform] Defaults to 'scratch'.
  * @property {(message: string) => void} [logCallback]
  */
 
@@ -19,6 +24,35 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 const isObject = (obj) => !!obj && typeof obj === 'object';
 
+/**
+ * @typedef PlatformInfo
+ * @property {boolean} [allowsNonScalarVariables]
+ */
+
+/**
+ * @type {Record<Platform, PlatformInfo>}
+ */
+const platforms = {
+  scratch: {},
+  turbowarp: {
+    allowsNonScalarVariables: true
+  }
+};
+
+/**
+ * @param {Options} options
+ * @returns {PlatformInfo}
+ */
+const getPlatform = (options) => {
+  if (options && Object.prototype.hasOwnProperty.call(options, 'platform')) {
+    if (Object.prototype.hasOwnProperty.call(platforms, options.platform)) {
+      return platforms[options.platform];
+    }
+    throw new Error(`Unknown platform: ${options.platform}`);
+  }
+  return platforms.scratch;
+};
+
 const BUILTIN_EXTENSIONS = [
   'control',
   'data',
@@ -70,6 +104,8 @@ const getKnownExtensions = (project) => {
  * @returns {object} Fixed project.json object. If the `data` argument was an object, this will point to the same object.
  */
 const fixJSON = (data, options = {}) => {
+  const platform = getPlatform(options);
+
   /**
    * @param {string} message
    */
@@ -94,10 +130,12 @@ const fixJSON = (data, options = {}) => {
       variable[0] = String(variable[0]);
     }
 
-    const value = variable[1];
-    if (typeof value !== 'number' && typeof value !== 'string' && typeof value !== 'boolean') {
-      log(`variable ${id} value was not a Scratch-compatible value`);
-      variable[1] = String(variable[1]);
+    if (!platform.allowsNonScalarVariables) {
+      const value = variable[1];
+      if (typeof value !== 'number' && typeof value !== 'string' && typeof value !== 'boolean') {
+        log(`variable ${id} value was not a Scratch-compatible value`);
+        variable[1] = String(variable[1]);
+      }
     }
   };
 
@@ -419,6 +457,30 @@ const fixJSON = (data, options = {}) => {
     }
   };
 
+  /**
+   * @param {unknown} stage
+   */
+  const fixStageInPlace = (stage) => {
+    // stage's name must match exactly
+    if (stage.name !== 'Stage') {
+      log(`stage had wrong name: ${stage.name}`);
+      stage.name = 'Stage';
+    }
+
+    // In vanilla Scratch, "turn video < ... >" with anything that isn't the dropdown allows videoState
+    // to be set to something that isn't one of the expected strings. We'll play it safe and default to
+    // off.
+    const VIDEO_STATES = [
+      'on',
+      'off',
+      'on-flipped'
+    ];
+    if (Object.prototype.hasOwnProperty.call(stage, 'videoState') && !VIDEO_STATES.includes(stage.videoState)) {
+      log(`stage had invalid videoState: ${stage.videoState}`);
+      stage.videoState = 'off';
+    }
+  };
+
   /**
    * @param {unknown} project
    */
@@ -506,12 +568,7 @@ const fixJSON = (data, options = {}) => {
 
     // Above checks ensure this invariant holds
     const stage = targets[0];
-
-    // stage's name must match exactly
-    if (stage.name !== 'Stage') {
-      log(`stage had wrong name: ${stage.name}`);
-      stage.name = 'Stage';
-    }
+    fixStageInPlace(stage);
 
     const knownExtensions = getKnownExtensions(project);
     const monitors = project.monitors;
@@ -549,13 +606,49 @@ const fixJSON = (data, options = {}) => {
 /**
  * @param {ArrayBuffer|Uint8Array|Blob} data A compressed .sb3 file.
  * @param {Options} [options]
- * @returns {Promise<ArrayBuffer>} A promise that resolves to a fixed compressed .sb3 file.
+ * @returns {Promise<Uint8Array>} A promise that resolves to a fixed compressed .sb3 file.
  */
 const fixZip = async (data, options = {}) => {
+  /**
+   * @param {string} message
+   */
+  const log = (message) => {
+    if (options.logCallback) {
+      options.logCallback(message);
+    }
+  };
+
   // JSZip is not a small library, so we'll load it somewhat lazily.
   const JSZip = require('@turbowarp/jszip');
 
-  const zip = await JSZip.loadAsync(data);
+  let zip = await JSZip.loadAsync(data, {
+    recoverCorrupted: true,
+    onCorruptCentralDirectory: (error) => {
+      log(`zip had corrupt central directory: ${error}`);
+    },
+    onUnrecoverableFileEntry: (error) => {
+      log(`zip had unrecoverable file entry: ${error}`);
+    }
+  });
+
+  /** @type {Array<[string, import("@turbowarp/jszip").JSZipObject]>} */
+  const zipFiles = [];
+  zip.forEach((relativePath, file) => {
+    zipFiles.push([relativePath, file]);
+  });
+
+  // Remove any unreadable files from the zip. This can notably happen if the compressed data in the zip was
+  // corrupted, which would make the uncompressed data size field not match. Scratch/JSZip will refuse to
+  // keep loading the project if that happens. If we remove the asset, at least there's a chance it can now
+  // be downloaded from the asset server instead.
+  for (const [relativePath, file] of zipFiles) {
+    try {
+      await file.async('uint8array');
+    } catch (error) {
+      log(`zip had unreadable file ${relativePath}: ${error}`);
+      zip.remove(relativePath);
+    }
+  }
 
   // json is not guaranteed to be stored in the root.
   const jsonFile = zip.file(/(?:project|sprite)\.json/)[0];
@@ -583,5 +676,6 @@ const fixZip = async (data, options = {}) => {
 
 module.exports = {
   fixJSON,
-  fixZip
+  fixZip,
+  platforms
 };