@turbowarp/sb3fix 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turbowarp/sb3fix",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Fix corrupted Scratch projects",
   "main": "src/sb3fix.js",
   "scripts": {
@@ -24,7 +24,7 @@
     "@turbowarp/jszip": "^3.12.0"
   },
   "devDependencies": {
-    "copy-webpack-plugin": "^13.0.0",
+    "copy-webpack-plugin": "^14.0.0",
     "webpack": "^5.98.0",
     "webpack-cli": "^6.0.1"
   }

package/src/sb3fix.js

@@ -24,17 +24,31 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 const isObject = (obj) => !!obj && typeof obj === 'object';
 
+/**
+ * Object.hasOwn() but it works in more browsers.
+ * @param {unknown} obj 
+ * @param {string} property 
+ * @returns {boolean} true if Object.hasOwn(obj, property)
+ */
+const hasOwn = (obj, property) => Object.prototype.hasOwnProperty.call(obj, property);
+
 /**
  * @typedef PlatformInfo
- * @property {boolean} [allowsNonScalarVariables]
+ * @property {boolean} [allowsNonScalarVariables] If true, variables don't need to be a single string/number/boolean.
+ * @property {boolean} [nativelyUnderstandsSpork] If true, the platform's editor can natively understand spork-isms in project.json and thus compatibility fixes can be skipped.
  */
 
 /**
  * @type {Record<Platform, PlatformInfo>}
  */
 const platforms = {
-  scratch: {},
+  scratch: {
+    // Although the Scratch website uses spork, the desktop app still doesn't so for now, we'll keep applying the spork fixes there too.
+    nativelyUnderstandsSpork: false,
+    allowsNonScalarVariables: false
+  },
   turbowarp: {
+    nativelyUnderstandsSpork: false,
     allowsNonScalarVariables: true
   }
 };
@@ -44,8 +58,8 @@ const platforms = {
  * @returns {PlatformInfo}
  */
 const getPlatform = (options) => {
-  if (options && Object.prototype.hasOwnProperty.call(options, 'platform')) {
-    if (Object.prototype.hasOwnProperty.call(platforms, options.platform)) {
+  if (options && hasOwn(options, 'platform')) {
+    if (hasOwn(platforms, options.platform)) {
       return platforms[options.platform];
     }
     throw new Error(`Unknown platform: ${options.platform}`);
@@ -171,6 +185,7 @@ const fixJSON = (data, options = {}) => {
 
   /**
    * @param {unknown[]} native
+   * @returns {boolean} true to keep, false to delete
    */
   const fixCompressedNativeInPlace = (native) => {
     if (!Array.isArray(native)) {
@@ -201,7 +216,7 @@ const fixJSON = (data, options = {}) => {
           log('number native had invalid value');
           native[1] = String(value);
         }
-        break;
+        return true;
       }
 
       // Color: [9, hex color]
@@ -214,7 +229,7 @@ const fixJSON = (data, options = {}) => {
           log('color native had invalid value');
           native[1] = '#000000';
         }
-        break;
+        return true;
       }
 
       // Text: [10, string|number]
@@ -227,7 +242,25 @@ const fixJSON = (data, options = {}) => {
           log('text native had invalid value');
           native[1] = String(value);
         }
-        break;
+        return true;
+      }
+
+      // Broadcast: [11, name, id]
+      case 11: {
+        if (native.length !== 3) {
+          throw new Error(`Broadcast native is of unexpected length: ${native.length}`);
+        }
+        const name = native[1];
+        if (typeof name !== 'string') {
+          log(`broadcast native name was not a string`);
+          native[1] = String(native[1]);
+        }
+        const id = native[2];
+        if (typeof id !== 'string') {
+          log(`deleting compressed broadcast reference with non-string ID`);
+          return false;
+        }
+        return true;
       }
 
       // Variable: [12, variable name, variable id, x?, y?]
@@ -243,18 +276,27 @@ const fixJSON = (data, options = {}) => {
           log(`variable or list native name was not a string`);
           native[1] = String(native[1]);
         }
-        break;
+        const id = native[2];
+        if (typeof id !== 'string') {
+          log(`deleting compressed variable or list reference with non-string ID`);
+          return false;
+        }
+        return true;
       }
+
+      default:
+        throw new Error(`Unknown native type: ${type}`);
     }
   };
 
   /**
    * @param {string} id
    * @param {unknown} block
+   * @returns {boolean} true to keep, false to delete
    */
   const fixBlockInPlace = (id, block) => {
     if (Array.isArray(block)) {
-      fixCompressedNativeInPlace(block);
+      return fixCompressedNativeInPlace(block);
     } else if (isObject(block)) {
       const inputs = block.inputs;
       if (!isObject(inputs)) {
@@ -266,7 +308,10 @@ const fixJSON = (data, options = {}) => {
         }
         for (let i = 1; i < input.length; i++) {
           if (Array.isArray(input[i])) {
-            fixCompressedNativeInPlace(input[i]);
+            if (!fixCompressedNativeInPlace(input[i])) {
+              // Logging happens in fixCompressedNativeInPlace
+              input[i] = null;
+            }
           }
         }
       }
@@ -280,11 +325,68 @@ const fixJSON = (data, options = {}) => {
           throw new Error(`block ${id} field ${fieldName} is not an array`);
         }
       }
+
+      return true;
     } else {
       throw new Error(`block ${id} is not an object`);
     }
   };
 
+  /**
+   * Fix backwards-incompatible changes that Scratch made in the spork migration.
+   * @param {object} blocks
+   */
+  const fixSporkBackwardsIncompatibilityInPlace = (blocks) => {
+    for (const [blockId, block] of Object.entries(blocks)) {
+      if (!isObject(block)) {
+        continue;
+      }
+
+      switch (block.opcode) {
+        // Custom block definition prototype blocks used to be marked as shadow: true, but spork marks as shadow: false.
+        // Our scratch-blocks relies on it being shadow: true to prevent moving, so we'll force it to be that way.
+        case 'procedures_prototype':
+          if (block.shadow !== true) {
+            log(`(spork) forcing shadow on procedures_prototype block ${blockId}`);
+            block.shadow = true;
+          }
+          break;
+
+        // For completeness with the above, set the argument reporter generators to be shadow: true as well.
+        case 'argument_reporter_string_number':
+        case 'argument_reporter_boolean': {
+          const parent = blocks[block.parent];
+          if (isObject(parent) && parent.opcode === 'procedures_prototype' && block.shadow !== true) {
+            log(`(spork) forcing shadow on ${block.opcode} block ${blockId}`);
+            block.shadow = true;
+          }
+          break;
+        }
+
+        // control_stop used to define a mutation for whether it has a connection below, which is what old
+        // scratch-blocks relies on to determine if there is another conneciton below or not. Spork does not define
+        // this mutation and relies only on the STOP_OPTION field. We will generate the mutation if it's missing so
+        // that a "stop other scripts in sprite" block doesn't cause the workspace to fail to load.
+        case 'control_stop': {
+          if (!block.mutation) {
+            const field = block.fields && block.fields.STOP_OPTION;
+            const stopOption = Array.isArray(field) ? field[0] : null;
+            const hasNext = stopOption === 'other scripts in sprite' || stopOption === 'other scripts in stage';
+            if (hasNext) {
+              log(`(spork) generating mutation on control_stop block ${blockId}`);
+              block.mutation = {
+                tagName: 'mutation',
+                hasnext: hasNext ? 'true' : 'false',
+                children: []
+              };
+            }
+          }
+          break;
+        }
+      }
+    }
+  };
+
   /**
    * @param {string} id
    * @param {unknown} comment
@@ -393,7 +495,14 @@ const fixJSON = (data, options = {}) => {
       throw new Error('blocks is not an object');
     }
     for (const [blockId, block] of Object.entries(blocks)) {
-      fixBlockInPlace(blockId, block);
+      if (!fixBlockInPlace(blockId, block)) {
+        // Logging happens in fixBlockInPlace
+        delete blocks[blockId];
+      }
+    }
+
+    if (!platform.nativelyUnderstandsSpork) {
+      fixSporkBackwardsIncompatibilityInPlace(blocks);
     }
 
     // Comments are not required
@@ -475,7 +584,7 @@ const fixJSON = (data, options = {}) => {
       'off',
       'on-flipped'
     ];
-    if (Object.prototype.hasOwnProperty.call(stage, 'videoState') && !VIDEO_STATES.includes(stage.videoState)) {
+    if (hasOwn(stage, 'videoState') && !VIDEO_STATES.includes(stage.videoState)) {
       log(`stage had invalid videoState: ${stage.videoState}`);
       stage.videoState = 'off';
     }
@@ -631,21 +740,25 @@ const fixZip = async (data, options = {}) => {
     }
   });
 
-  /** @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}`);
+  for (const [relativePath, file] of Object.entries(zip.files)) {
+    if (file.dir) {
+      continue;
+    }
+
+    if (/(?:project|sprite)\.json/.test(relativePath) || /[0-9a-f]{32}\./.test(relativePath)) {
+      try {
+        // If the file is corrupt, this will throw.
+        await file.async('uint8array');
+      } catch (error) {
+        log(`zip had unreadable file ${relativePath}: ${error}`);
+        zip.remove(relativePath);
+      }
+    } else {
+      log(`zip had extraneous file ${relativePath}`);
       zip.remove(relativePath);
     }
   }