Fixing JS Extension Integration: Runner, Toolbox, And FieldCustom

Hey guys! Ever wrestled with getting your JavaScript extensions to play nice with Scratch? You're not alone! This guide dives deep into some common snags encountered when integrating JS extensions, specifically focusing on the sandboxed runner, toolbox values, and FieldCustom keys. We'll break down the problems, explore the solutions, and provide you with the knowledge to conquer these challenges. Let's get started!

1. Sandboxed Runner: Ensuring Proper Return Values

The sandboxed runner is a crucial component that executes JavaScript code within the Scratch environment. It acts as a secure container, preventing extensions from wreaking havoc on the main application. However, a common issue arises when the runner doesn't return values in the format expected by Scratch.

The Problem: Mismatched Return Shapes

Imagine you've created a cool reporter block in your extension that's supposed to fetch some data and display it in Scratch. But, when you run the block, nothing shows up! This might be because the sandboxed runner isn't returning the result in the correct shape. Some JavaScript extension code expects the sandbox execution to resolve an object with a value property (e.g., { value, success }). If the runner returns a primitive value directly on success, then result.value ends up being undefined, leaving your reporter block empty.

The Solution: Standardizing the Return Format

To fix this, we need to ensure the sandboxed runner always returns an object with a value property, along with a success indicator. This provides a consistent format for Scratch to handle the results. Let's look at the proposed fix in src/util/sandboxed-javascript-runner.js:

- return result;
+ return { value: result, success: true };

This simple change wraps the result in an object with value and success properties when the execution is successful. Similarly, we need to handle errors gracefully:

- throw err;
+ return { value: undefined, success: false, error: String(err && err.message || err) };

Here, we catch any errors, stringify the error message, and return an object with value set to undefined, success set to false, and the error message stored in the error property. This allows Scratch to handle errors from extensions in a consistent way.

By implementing these changes, reporter blocks can reliably receive values from the sandboxed runner, making your extensions more robust and user-friendly. This standardized approach ensures that even if something goes wrong within the sandbox, Scratch can still provide helpful feedback to the user, like an error message.

2. Toolbox Values: Enforcing String-Only Input

The toolbox in Scratch is where all the blocks live, neatly organized and ready to be used. When you create an extension, you're essentially adding new blocks to this toolbox. However, building this toolbox has certain expectations, particularly when it comes to the data types used for block text and default values.

The Problem: Non-String Values Causing Chaos

Imagine your extension includes a block with a text field or a default value that isn't a string. This can cause the toolbox building process to throw an error, specifically "Unexpected input received in replaceUnsafeChars". Why? Because the toolbox sanitizer, which prepares the blocks for display, expects strings. Passing in null, undefined, or even objects will lead to a crash.

The Solution: Stringify Everything!

The key here is to ensure that all block text and default values are strings. This might seem obvious, but it's a common oversight that can trip up extension developers. There are a few ways to tackle this:

1. Developer Note: Add a clear note in your codebase and documentation stating that all block text and argument defaultValue must be strings. This serves as a reminder for yourself and any collaborators.
2. Console Warning (Nice-to-Have): For extra safety, consider logging a console.warn message during extension load if non-string defaults or text are detected. This provides immediate feedback to extension authors, helping them catch errors early.

By enforcing string-only input for toolbox values, you'll prevent those pesky "Unexpected input received in replaceUnsafeChars" errors and ensure your blocks load smoothly into the Scratch environment. This proactive approach not only saves you debugging time but also contributes to a more stable and user-friendly experience for Scratch users who install your extensions.

3. FieldCustom: Documenting the Registration Key

FieldCustom is a powerful feature in Scratch that allows you to create custom input fields within your blocks. This opens up a world of possibilities for creating unique and interactive blocks tailored to your extension's specific needs. However, getting FieldCustom to work correctly requires careful attention to registration and key matching.

The Problem: Missing or Mismatched Keys

Picture this: you've meticulously designed a custom input field, compiled everything, and loaded your extension. But, instead of seeing your beautiful custom field, you're greeted with a null or uneditable input. This likely means the registration key for your FieldCustom is either missing or doesn't match the key used in your block's argument.

The Solution: Register and Match the Key!

To make FieldCustom work its magic, you need to follow a specific procedure:

1. Register the Input: Call ScratchBlocks.FieldCustom.registerInput('yourKey', ...) at module load time. This step is crucial because it tells Scratch about your custom input field and how it should behave. Make sure this registration happens before getInfo() is called, as getInfo() is where your extension declares its blocks.

2. Match the Key: Ensure that the block argument using the custom field has the correct configuration:

   {
     type: 'custom',
     custom: 'yourKey',   // must match registry key
     defaultValue: ''     // string
   }
   

   The custom property in the block argument must match the key you used when registering the input with ScratchBlocks.FieldCustom.registerInput(). A mismatch here is a common cause of FieldCustom not rendering correctly.

3. Document the Process: Clearly document these steps for extension authors. A dedicated section in your documentation explaining the importance of registration and key matching will save developers a lot of headaches.

By diligently registering your FieldCustom inputs and ensuring the keys match, you'll unlock the full potential of custom input fields in your Scratch extensions. Clear documentation is your best friend here, guiding other developers to seamlessly integrate your custom fields into their Scratch projects.

Acceptance Criteria: Putting It All Together

To ensure our fixes are working correctly, let's define some acceptance criteria:

• Sandbox Runner: The sandboxed runner should return an object with { value, success }, allowing reporter blocks to access result.value reliably.
• Toolbox Strings: No more "Unexpected input received in replaceUnsafeChars" errors when extension blocks use only string defaults and text.
• FieldCustom: Custom FieldCustom inputs should render as editable when the extension registers a matching key.

These criteria provide a clear roadmap for testing and verifying that our solutions are effective.

Out of Scope: What We're Not Covering Here

It's important to note what this guide doesn't cover. Specifically:

• Extension Repository Updates: The extension repository itself needs to be updated with blocks in JSON format, ensuring string-only values. We'll also need to make sure FieldCustom.registerInput() runs before getInfo(). These are responsibilities that fall on the extension developers themselves.

We'll make sure to link these requirements in the extension's PR description to provide clear guidance for extension authors.

Conclusion: Empowering Extension Developers

Integrating JavaScript extensions with Scratch can be a rewarding experience, but it's not without its challenges. By understanding the intricacies of the sandboxed runner, toolbox values, and FieldCustom keys, you can overcome these hurdles and create powerful extensions that enhance the Scratch ecosystem. Remember, clear communication, robust testing, and comprehensive documentation are your allies in this journey. Happy coding, and let's build some amazing extensions together!