JS extension: initialize runtime.extensionRuntimeOptions and guard unsandbox flag to prevent TypeError

[coderabbitai]

Summary
When loading the JavaScript/SPjavascriptV2 extension from PR TurboWarp#159, VM logs:
TypeError: can't access property "javascriptUnsandboxed", this.runtime.extensionRuntimeOptions is undefined

This happens as soon as the extension tries to read runtime.extensionRuntimeOptions.javascriptUnsandboxed.

Backlinks

• PR: Extensions scratch-gui#159
• Discussion/logs: finish js extension for sake scratch-gui#326
• Requested by: @supervoidcoder

Steps to reproduce

1. Use scratch-gui (PR More CONDITIONAL and LOOP stuff TurboWarp/scratch-vm#159) with the JS extension enabled.
2. Open the extension library and add the JavaScript/SPjavascriptV2 extension.
3. Observe VM console warnings/errors referencing javascriptUnsandboxed and undefined extensionRuntimeOptions.

Actual behavior

• Accessing this.runtime.extensionRuntimeOptions.javascriptUnsandboxed throws because extensionRuntimeOptions is undefined.

Root cause

• In our VM fork, extensionRuntimeOptions is never initialized before extensions load.
• Some extension code assumes it exists and directly reads javascriptUnsandboxed.

Fix (Option A: initialize in Runtime constructor)
File: src/engine/runtime.js (constructor)

 class Runtime {
   constructor() {
+    // Ensure extensions can safely read runtime options bag.
+    this.extensionRuntimeOptions = this.extensionRuntimeOptions || {};
     // ... existing constructor code ...
   }
 }

Fix (Option B: initialize in VirtualMachine after Runtime creation, before loading extensions)
File: src/virtual-machine.js (constructor/init path)

- this.runtime = new Runtime();
+ this.runtime = new Runtime();
+ // Guard: ensure the options bag exists before any extension reads it.
+ this.runtime.extensionRuntimeOptions = this.runtime.extensionRuntimeOptions || {};

Fix (defensive read in the JS extension; belongs in the extension repo, but documenting here)

- const unsandboxed = this.runtime.extensionRuntimeOptions.javascriptUnsandboxed;
+ const unsandboxed = this.runtime.extensionRuntimeOptions?.javascriptUnsandboxed === true;

Acceptance criteria

• No VM warnings/errors about extensionRuntimeOptions being undefined when the JS extension loads.
• Reading javascriptUnsandboxed never throws, regardless of default config.
• Existing extensions keep working.

Notes

• This brings behavior in line with PenguinMod/TurboWarp forks that initialize Runtime.extensionRuntimeOptions to an object.

[traycerai]

Plan

Observations

The issue is clear: runtime.extensionRuntimeOptions is never initialized, causing a TypeError when the JavaScript extension (sp_javascriptV2) attempts to read runtime.extensionRuntimeOptions.javascriptUnsandboxed at line 458. The Runtime constructor initializes many properties (runtimeOptions, compilerOptions, etc.) but omits extensionRuntimeOptions. Only one extension currently uses this property, making the fix low-risk.

Approach

Initialize extensionRuntimeOptions as an empty object in the Runtime constructor, following the same pattern as other runtime properties. This ensures the property exists before any extension loads, preventing TypeError exceptions. This approach aligns with TurboWarp/PenguinMod implementations and provides a safe foundation for future extensions that may need runtime configuration options.

Reasoning

I explored the repository structure, examined both src/engine/runtime.js and src/virtual-machine.js to understand the initialization flow, searched for all usages of extensionRuntimeOptions across the codebase, and confirmed that only the JavaScript extension currently accesses this property. I verified that no existing code initializes this property anywhere.

Proposed File Changes

📄 src/engine/runtime.js ^(MODIFY) 🔗

In the Runtime constructor (around line 459-468 where runtimeOptions and compilerOptions are initialized), add initialization for extensionRuntimeOptions as an empty object. This should be placed after the existing runtime configuration properties to maintain logical grouping.

Add a property initialization:

• Initialize this.extensionRuntimeOptions to an empty object {}
• Add a JSDoc comment explaining this is a bag for extension-specific runtime options that extensions can read (e.g., javascriptUnsandboxed for packager mode)
• Position it near the runtimeOptions and compilerOptions properties for consistency

This ensures extensions can safely access runtime.extensionRuntimeOptions without encountering undefined errors, and provides a clear extension point for future runtime configuration needs.

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end.

### Observations

The issue is clear: `runtime.extensionRuntimeOptions` is never initialized, causing a TypeError when the JavaScript extension (`sp_javascriptV2`) attempts to read `runtime.extensionRuntimeOptions.javascriptUnsandboxed` at line 458. The Runtime constructor initializes many properties (runtimeOptions, compilerOptions, etc.) but omits `extensionRuntimeOptions`. Only one extension currently uses this property, making the fix low-risk.


### Approach

Initialize `extensionRuntimeOptions` as an empty object in the Runtime constructor, following the same pattern as other runtime properties. This ensures the property exists before any extension loads, preventing TypeError exceptions. This approach aligns with TurboWarp/PenguinMod implementations and provides a safe foundation for future extensions that may need runtime configuration options.


### Reasoning

I explored the repository structure, examined both `src/engine/runtime.js` and `src/virtual-machine.js` to understand the initialization flow, searched for all usages of `extensionRuntimeOptions` across the codebase, and confirmed that only the JavaScript extension currently accesses this property. I verified that no existing code initializes this property anywhere.


## Proposed File Changes

### src/engine/runtime.js(MODIFY)

In the Runtime constructor (around line 459-468 where `runtimeOptions` and `compilerOptions` are initialized), add initialization for `extensionRuntimeOptions` as an empty object. This should be placed after the existing runtime configuration properties to maintain logical grouping.

Add a property initialization:
- Initialize `this.extensionRuntimeOptions` to an empty object `{}`
- Add a JSDoc comment explaining this is a bag for extension-specific runtime options that extensions can read (e.g., `javascriptUnsandboxed` for packager mode)
- Position it near the `runtimeOptions` and `compilerOptions` properties for consistency

This ensures extensions can safely access `runtime.extensionRuntimeOptions` without encountering undefined errors, and provides a clear extension point for future runtime configuration needs.

---

Developer Humor

🏗️ Constructor's Confession

I built a Runtime house so grand,
With runtimeOptions close at hand,
But extensionRuntimeOptions? Forgot!
Now extensions crash on the spot.
One empty object, that's all it takes,
To fix these TypeError heartbreaks! 🔧

---

Execution Information

Branch: develop
Commit: 065a453

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[supervoidcoder]

/q dev

[amazon-q-developer]

Progress Updates

• I'll start by exploring the repository structure to understand the codebase and locate the relevant files mentioned in the request (src/engine/runtime.js and src/virtual-machine.js).
• I can see the repository structure. Now I'll examine the key files mentioned in the request: src/engine/runtime.js and src/virtual-machine.js to understand the current implementation and identify where to make the changes.
• The runtime.js file is quite large. I need to look at the constructor more closely to see if extensionRuntimeOptions is already initialized. Let me search for "extensionRuntimeOptions" in the file to understand the current state.
• The search didn't find any existing references to extensionRuntimeOptions in runtime.js, which confirms the issue. Now let me check the virtual-machine.js file to understand how the Runtime is instantiated and where we should add the initialization.
• I can see that the Runtime is instantiated on line 70 in the VirtualMachine constructor. Now let me search for any existing references to extensionRuntimeOptions in the virtual-machine.js file to understand the current state.
• No existing references to extensionRuntimeOptions in virtual-machine.js either. Now let me search across the entire project to see if there are any references to this property to understand how it's supposed to be used.
• Perfect! I found the issue. The JavaScript extension at src/extensions/sp_javascriptV2/index.js is trying to access this.runtime.extensionRuntimeOptions.javascriptUnsandboxed on line 458, but the property is never initialized. Let me examine this file to understand the context better.
• Now I understand the issue completely. The JavaScript extension is trying to access this.runtime.extensionRuntimeOptions.javascriptUnsandboxed but the extensionRuntimeOptions property is never initialized in the Runtime constructor. Let me create a plan to fix this issue.
• Analyzing the issue and determining the best fix approach
• I'll implement the fix by initializing the extensionRuntimeOptions property in the Runtime constructor. This is the cleanest approach as it ensures the property is always available when extensions try to access it.
• I can see the beginning of the Runtime constructor. Let me add the extensionRuntimeOptions initialization right after the super() call to ensure it's available early in the constructor process.
• Let me try a more specific match:
• Let me check the exact formatting by viewing more lines:
• It looks like the change has already been made! Let me verify this by checking if the extensionRuntimeOptions initialization is actually there. Let me search for it in the runtime.js file to confirm.
• Great! The fix has been successfully applied. The extensionRuntimeOptions property is now initialized in the Runtime constructor on line 214. Now let me test that this resolves the issue by checking if the JavaScript extension can safely access the property. Let me also verify that the fix follows the acceptance criteria.
• Perfect! Now the JavaScript extension should be able to safely access this.runtime.extensionRuntimeOptions.javascriptUnsandboxed without getting a TypeError. Let me create a simple test to verify that the fix works as expected by creating a minimal test script.
• Verify that the extensionRuntimeOptions fix is working correctly and meets all acceptance criteria
• Now I'll execute the test script I created to verify that the fix is working correctly and meets the acceptance criteria.
• Let me check if there are any existing tests I should run to ensure I haven't broken anything:
• I can see there are test scripts available. Let me run the existing unit tests to make sure my changes don't break anything, and then run my custom test to verify the fix works.
• Perfect! I can see there are runtime tests. Let me check the engine_runtime.js test file:
• Great! Now let me add a test to verify that extensionRuntimeOptions is properly initialized. Let me add it to the existing spec test:
• Let me add a test for extensionRuntimeOptions right after the existing spec test:
• Perfect! Now let me also create a test to verify that the JavaScript extension can safely access the property. Let me check if there are any existing extension tests:
• Let me create a simple test to verify the JavaScript extension integration:
• Now let me run the tests to verify everything is working:
• Let me run the specific runtime tests to verify my changes work:
• Let me also verify that the fix doesn't break any existing functionality by checking if there are any other references to extensionRuntimeOptions in the codebase:
• I have successfully implemented and tested the fix for the JavaScript extension TypeError. The solution initializes the extensionRuntimeOptions property in the Runtime constructor, which prevents the TypeError when extensions try to access runtime options. I've also added comprehensive tests to ensure the fix works correctly and doesn't break existing functionality.

---

✅ I finished the proposed code changes, and the pull request is ready for review: #16.

Comment on the pull request to provide feedback and request a new iteration.

To provide feedback on how Amazon Q Developer performed with code generation, create an issue in the Amazon Q Developer public repository.